> ## Documentation Index
> Fetch the complete documentation index at: https://zuno-fb55ec99.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> An AXL-native multi-agent debate for onchain LP decisions.

Zuno is an AXL-native agent mesh for onchain operations. The first
workflow is Uniswap v4 liquidity management, but the product is the
mesh: peers, transport, and *adversarial* reasoning before reviewed
execution. It is built around a Turnkey-backed Zuno wallet - the user's
main wallet stays separate, and the agent wallet is the execution wallet.

It runs in your terminal. Two flows live behind the same debate:

* **Create** a brand-new position - point Zuno at a token + amount, the
  Scout surveys live pools on the chain, the Strategist proposes 2-5
  pool/range candidates, the Critic stress-tests them, the Arbiter
  resolves on deadlock. See [CLI / create](/cli/create).
* **Rebalance** an existing position - the same four agents debate
  whether and how to move its range. See [CLI / plan](/cli/plan).

Both flows share Scout, Strategist, Critic, Arbiter and converge on a
structured plan with a verdict, confidence score, and full transcript.

A separate background worker, the **monitor**, polls your positions
every minute and pings you on Telegram when one drifts out of range or
near a boundary - so you know to ask Zuno for a recommendation. See
[CLI / monitor](/cli/monitor). The monitor is not a debate participant;
it's a standalone watcher that produces alerts.

```
$ zuno
◇ recommend what I should do with this position

  ◇ scout       regime: ranging · vol 110bps · gas 14gwei · in range
  ◇ strategist  3 candidates · lean tighter, vol is sleeping
  ◇ critic      reject A: 18h buffer is fine now, vol mean-reverts
  ◇ strategist  A′: ±2.6% · 28h buffer · $3.60/d expected
  ◇ critic      accept A′ - converged
  ────────────────────────────────────────────────────────

  position    WETH / USDC 0.05%
  range       2,190.79 to 2,421.19   out of range
  current     2,438.19

  ────────────────────────────────────────────────────────

  recommended 2,273.36 to 2,614.97   shift
  rejected    2,361.41 to 2,519.99   tighten at 2× vol
  reason      28h base buffer · survives 2× vol · gas/yield 0.71x
  decided by  critic · debate converged

  confidence  0.82  approve_with_caution
```

## Why four agents

LP management is a real tension between fee density (tight ranges, high
yield) and survival (wide ranges, low exit risk). A single scoring
function picks one side. A debate models the tension explicitly - and
makes the reasoning auditable.

| agent          | does                                                                 |
| -------------- | -------------------------------------------------------------------- |
| **Scout**      | reads the position + pool, classifies the regime in plain English    |
| **Strategist** | proposes 2-5 candidate ranges, revises after critique                |
| **Critic**     | stress-tests every candidate, vetoes weak ones with concrete reasons |
| **Arbiter**    | only joins on deadlock - picks final candidate from full transcript  |

Each agent runs as its own AXL peer with its own ed25519 peer id. They
talk over [Gensyn AXL](https://blog.gensyn.ai/introducing-axl/) - the
peer-to-peer Agent eXchange Layer. The CLI is just another peer.

A debate normally converges in 1-2 rounds. When it doesn't, the
Arbiter reads the full history and breaks the tie with explicit
reasoning the user can read.

## What's deterministic, what isn't

The agents use the LLM to *reason*. The LLM never owns arithmetic.

* Tick math, range checks, allocation, and stress simulation are pure
  functions in TypeScript.
* Volatility comes from a real CoinGecko series; gas comes from
  `eth_gasPrice` on the position's chain; yield is estimated from
  `liquidity × feeTier × in_range_share`.
* The Strategist picks `(widthMultiplier, centerOffset)` proportions -
  it can't fabricate raw tick numbers.
* The Critic scores against deterministic floors keyed to the user's
  risk profile (`conservative | balanced | aggressive`).
* The Arbiter writes the final paragraph, but the chosen candidate
  index is bounded by the actual proposal.

If `OPENAI_API_KEY` is unset, every agent has a deterministic fallback.
The mesh shape and message kinds are identical.

## Working surfaces

* Create + rebalance via the four-agent debate over AXL.
* Real on-chain v4 pool discovery (StateView probe of every
  `(token0, token1, feeTier)` candidate from the curated registry).
* Live `agent_thought` transcript rendered in the CLI and persisted in
  `risk.reasons` so `explain recommendation` can replay it.
* In-process orchestrator fallback when the AXL mesh is offline.
* Deterministic fallback when no LLM key is available.
* Background **monitor** worker with optional Telegram delivery, dedup,
  and a local `~/.zuno/alerts.json` store.
* Email-OTP sign-in, per-user Turnkey sub-org with isolated wallet.
* `apply` requires explicit approval and signs through the Turnkey
  boundary only after policy checks pass.