diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
new file mode 100644
index 0000000..f17e803
--- /dev/null
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,37 @@
+name: docs
+
+on:
+  push:
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+jobs:
+  mintlify-checks:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      MINT_CLI_VERSION: '4.2.378'
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Validate docs build
+        working-directory: docs
+        run: npx --yes mint@${MINT_CLI_VERSION} validate
+
+      - name: Check broken links
+        working-directory: docs
+        run: npx --yes mint@${MINT_CLI_VERSION} broken-links
+
+      - name: Check accessibility
+        working-directory: docs
+        run: npx --yes mint@${MINT_CLI_VERSION} a11y
diff --git a/.gitignore b/.gitignore
index e606d38..df033da 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,8 +1,9 @@
 /bin/
 /dist/
 /defi
+.mintlify/
 *.test
 *.out
 .coverprofile
 .DS_Store
-TODO.md
\ No newline at end of file
+TODO.md
diff --git a/AGENTS.md b/AGENTS.md
index 50d4e13..12fcb9d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -54,6 +54,9 @@ internal/
 scripts/install.sh                # macOS/Linux installer from GitHub Releases
 .goreleaser.yml                   # cross-platform release artifact config
 assets/                            # static assets (logo, images)
+docs/                             # Mintlify docs site
+  docs.json                       # Mintlify docs site config
+  *.mdx + concepts/ guides/ ...   # Mintlify docs content pages
 README.md                         # user-facing usage + caveats
 ```
 
@@ -85,6 +88,7 @@ README.md                         # user-facing usage + caveats
 - Amounts used for swaps/bridges are base units; keep both base and decimal forms consistent.
 - Release artifacts are built on `v*` tags via `.github/workflows/release.yml` and `.goreleaser.yml`.
 - `scripts/install.sh` installs the latest tagged release artifact into a writable user-space `PATH` directory by default (fallback `~/.local/bin`) and never uses sudo unless explicitly requested.
+- Docs site local checks (from `docs/`): `npx --yes mint@4.2.378 validate`, `npx --yes mint@4.2.378 broken-links`, and `npx --yes mint@4.2.378 a11y`.
 
 ## Change patterns
 
@@ -100,6 +104,10 @@ README.md                         # user-facing usage + caveats
 - Behavior changes:
   1. keep cache keys deterministic
   2. add runner-level tests for routing/fallback/strict mode
+- Docs sync for user-facing changes:
+  1. if adding a feature/command or changing behavior, update Mintlify docs + README + CHANGELOG
+  2. if changing output schema/fields/exit codes, update contract/reference docs before merge
+  3. if adding providers/chains/assets/aliases/key requirements, update provider/auth and examples docs
 
 ## Quality bar
 
@@ -122,6 +130,6 @@ README.md                         # user-facing usage + caveats
 
 ## Maintenance note
 
-- Keep `README.md`, `AGENTS.md`, and `CHANGELOG.md` aligned when commands, routing, caveats, or release-relevant behavior change.
+- Keep `README.md`, `AGENTS.md`, `CHANGELOG.md`, and Mintlify docs (`docs/docs.json` + `docs/**/*.mdx`) aligned when commands, routing, caveats, or release-relevant behavior change.
 
 Do not commit transient binaries like `./defi`.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8303eaa..b013cfa 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -47,6 +47,10 @@ Format:
 
 ### Docs
 - Updated README and AGENTS guidance for Solana usage, Kamino/Jupiter providers, and API key semantics.
+- Added a dedicated Mintlify documentation site (`docs/docs.json` + structured MDX pages) with setup, guides, automation patterns, and command reference.
+- Moved Mintlify docs into a dedicated `docs/` directory and simplified navigation to latest-only docs for lower maintenance.
+- Added a docs CI workflow that runs `mint validate` and `mint broken-links` on docs-related changes.
+- Refined docs IA by removing overlapping cookbook content, clarifying provider-driven API key requirements, and updating header branding with a lobster wordmark logo.
 
 ### Security
 - None yet.
diff --git a/README.md b/README.md
index 739192e..bed524b 100644
--- a/README.md
+++ b/README.md
@@ -19,6 +19,26 @@ Built for AI agents and scripts. Stable JSON output, canonical identifiers (CAIP
 - **Chains & protocols** — browse top chains by TVL, inspect chain TVL by asset, discover protocols, resolve asset identifiers.
 - **Automation-friendly** — JSON-first output, field selection (`--select`), strict mode, and a machine-readable schema export.
 
+## Documentation Site (Mintlify)
+
+This repo includes a dedicated Mintlify docs site under [`docs/`](docs) (`docs/docs.json` + `.mdx` pages).
+
+Preview locally:
+
+```bash
+cd docs
+npx --yes mint@4.2.378 dev --no-open
+```
+
+Validate before publishing:
+
+```bash
+cd docs
+npx --yes mint@4.2.378 validate
+npx --yes mint@4.2.378 broken-links
+npx --yes mint@4.2.378 a11y
+```
+
 ## Install
 
 ### 1) Quick install (macOS/Linux)
@@ -263,6 +283,7 @@ internal/
   httpx/                          # shared HTTP client
 
 .github/workflows/ci.yml          # CI (test/vet/build)
+docs/                             # Mintlify docs site (docs.json + MDX pages)
 AGENTS.md                         # contributor guide for agents
 ```
 ### Testing
diff --git a/docs/agents/overview.mdx b/docs/agents/overview.mdx
new file mode 100644
index 0000000..7e3754b
--- /dev/null
+++ b/docs/agents/overview.mdx
@@ -0,0 +1,42 @@
+---
+title: Agent Overview
+description: Build robust agent workflows on top of deterministic CLI contracts.
+---
+
+## Why agents like defi-cli
+
+- Stable envelope schema (`version`, `success`, `error`, `meta`)
+- Stable exit code mapping
+- Canonical chain and asset IDs
+- Provider-scoped retrieval IDs on lend/yield rows (`provider_native_id`, `provider_native_id_kind`)
+- Deterministic `--select` projections
+- Machine-readable command schema (`defi schema`)
+
+## Recommended request pattern
+
+1. Resolve all chain/asset inputs (`assets resolve` where useful).
+2. Execute command with `--json --results-only` for success payloads.
+3. Handle non-zero exit codes using `error.code` and `error.type`.
+4. Persist canonical IDs and base-unit amounts.
+
+## Suggested defaults
+
+```bash
+--timeout 12s --retries 2 --max-stale 5m
+```
+
+For strict workflows:
+
+```bash
+--strict --no-stale
+```
+
+## Command allowlist mode
+
+Use `--enable-commands` to constrain executable commands in agent sandboxes.
+
+```bash
+defi --enable-commands "providers list,yield opportunities" providers list --results-only
+```
+
+If a command is blocked, exit code `16` (`command_blocked`) is returned.
diff --git a/docs/agents/reliability-patterns.mdx b/docs/agents/reliability-patterns.mdx
new file mode 100644
index 0000000..9927d9a
--- /dev/null
+++ b/docs/agents/reliability-patterns.mdx
@@ -0,0 +1,36 @@
+---
+title: Reliability Patterns
+description: Error handling, retries, stale policy, and strict-mode strategies for production agents.
+---
+
+## Error-first flow
+
+When command exit code is non-zero:
+
+1. Parse error envelope from stderr.
+2. Branch on `error.code`.
+3. Decide retry/fallback/abort.
+
+## Core retry and fallback guidance
+
+- Retry on `11` (`rate_limited`) and `12` (`provider_unavailable`) with backoff.
+- Do not retry on `2` (`usage_error`) until input is corrected.
+- Retry on `10` (`auth_error`) only after key provisioning.
+- Treat `14` (`stale_data`) as SLO breach.
+
+## Cache/staleness strategy
+
+- Default cache mode is usually best for interactive and agent loops.
+- Use `--no-stale` for strict freshness.
+- Use `--max-stale` to control tolerated stale window on temporary provider failures.
+
+## Strict-mode strategy
+
+- Use `--strict` when partial provider aggregation is unacceptable.
+- In strict mode, partial results fail with code `15`.
+
+## Suggested wrapper behavior
+
+- Always capture stdout and stderr separately.
+- Treat stdout as success payload only when exit code is `0`.
+- Persist `meta.request_id` for trace correlation.
diff --git a/docs/agents/schema-driven.mdx b/docs/agents/schema-driven.mdx
new file mode 100644
index 0000000..2b2ad15
--- /dev/null
+++ b/docs/agents/schema-driven.mdx
@@ -0,0 +1,40 @@
+---
+title: Schema-Driven Integration
+description: Use the machine-readable command schema to generate dynamic tooling.
+---
+
+## Fetch schema
+
+```bash
+defi schema --results-only
+```
+
+Scope to a specific command path:
+
+```bash
+defi schema "yield opportunities" --results-only
+defi schema "bridge quote" --results-only
+```
+
+## Schema model
+
+Each node contains:
+
+- `path`
+- `use`
+- `short`
+- `flags[]` (`name`, `type`, `usage`, `default`, optional `shorthand`)
+- `subcommands[]`
+
+## Practical uses
+
+- Generate UI forms from flag metadata.
+- Validate requested flags before execution.
+- Produce autocomplete for command builders.
+- Build policy-aware execution layers with `--enable-commands`.
+
+## Notes
+
+- Hidden commands are not included.
+- Flag defaults are serialized as strings in schema output.
+- Runtime constraints (for example, mutually exclusive amount flags) still require command execution validation.
diff --git a/docs/concepts/config-and-cache.mdx b/docs/concepts/config-and-cache.mdx
new file mode 100644
index 0000000..37d5581
--- /dev/null
+++ b/docs/concepts/config-and-cache.mdx
@@ -0,0 +1,61 @@
+---
+title: Config and Cache
+description: Configure precedence, retries/timeouts, and stale fallback semantics.
+---
+
+## Config precedence
+
+`flags > env > config file > defaults`
+
+Default config path:
+
+```text
+${XDG_CONFIG_HOME:-~/.config}/defi/config.yaml
+```
+
+Minimal config example:
+
+```yaml
+output: json
+strict: false
+timeout: 10s
+retries: 2
+cache:
+  enabled: true
+  max_stale: 5m
+```
+
+## Useful env vars
+
+| Variable | Purpose |
+| --- | --- |
+| `DEFI_OUTPUT` | `json` or `plain` |
+| `DEFI_TIMEOUT` | Provider timeout |
+| `DEFI_RETRIES` | Retries per request |
+| `DEFI_MAX_STALE` | Stale fallback window |
+| `DEFI_NO_STALE` | Disable stale fallback |
+| `DEFI_NO_CACHE` | Disable cache |
+| `DEFI_CACHE_PATH` | Cache DB path |
+| `DEFI_CACHE_LOCK_PATH` | Cache lock path |
+
+## Cache behavior
+
+- Fresh cache hits (`age <= ttl`) return immediately.
+- After TTL expires, CLI refetches providers.
+- Stale data is served only when providers fail temporarily (`unavailable` or `rate_limited`) and within `max_stale`.
+- Cache writes use SQLite WAL + busy timeout + lock/backoff retries to reduce lock contention in parallel runs.
+- If cache init fails (path/permissions), commands continue with cache disabled.
+- Metadata commands (`version`, `schema`, `providers list`) bypass cache initialization.
+
+## Command TTLs
+
+| Command | TTL |
+| --- | --- |
+| `chains top`, `chains assets`, `protocols top`, `protocols categories` | `5m` |
+| `lend markets`, `yield opportunities`, `bridge list`, `bridge details` | `60s` |
+| `lend rates` | `30s` |
+| `bridge quote`, `swap quote` | `15s` |
+
+## Strict mode
+
+If any selected provider fails and partial results occur, `--strict` returns exit code `15` (`partial_results`).
diff --git a/docs/concepts/ids-and-amounts.mdx b/docs/concepts/ids-and-amounts.mdx
new file mode 100644
index 0000000..a9ab04e
--- /dev/null
+++ b/docs/concepts/ids-and-amounts.mdx
@@ -0,0 +1,54 @@
+---
+title: IDs and Amounts
+description: Use canonical chain/asset IDs and normalized amount fields.
+---
+
+## Chain IDs
+
+`--chain`, `--from`, and `--to` accept:
+
+- CAIP-2: `eip155:1`
+- Numeric EVM chain ID: `1`
+- Alias: `ethereum`, `base`, `hyperevm`, `megaeth`, `gnosis`, `taiko`, etc.
+- Solana mainnet alias/CAIP-2: `solana` or `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`
+
+`defi-cli` normalizes these to canonical CAIP-2 IDs in output.
+
+## Asset IDs
+
+Asset inputs accept:
+
+- Symbol: `USDC`
+- Token address: `0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48`
+- CAIP-19: `eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48`
+- Solana CAIP-19: `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/token:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`
+
+Output always returns canonical CAIP-19 in fields like `asset_id`, `from_asset_id`, `to_asset_id`.
+
+## Amount semantics
+
+For swap and bridge quotes:
+
+- `--amount` is base units (recommended for automation)
+- `--amount-decimal` is human decimal form
+- passing both returns a usage error
+
+Output includes both normalized forms:
+
+```json
+"input_amount": {
+  "amount_base_units": "1000000",
+  "amount_decimal": "1",
+  "decimals": 6
+}
+```
+
+## Important caveats
+
+- Symbol parsing depends on the local bootstrap token registry.
+- On chains without symbol coverage, pass address or CAIP-19 directly.
+- Solana support is mainnet-only (`solana` / `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`).
+- Solana devnet/testnet aliases and custom Solana CAIP-2 references are rejected.
+- MegaETH bootstrap symbol support currently includes `MEGA`, `WETH`, and `USDT` (`USDT` resolves to the chain `USDT0` contract).
+
+See [Chain Aliases](/reference/chain-aliases).
diff --git a/docs/concepts/output-contract.mdx b/docs/concepts/output-contract.mdx
new file mode 100644
index 0000000..7c96e22
--- /dev/null
+++ b/docs/concepts/output-contract.mdx
@@ -0,0 +1,68 @@
+---
+title: Output Contract
+description: Understand the stable response envelope and rendering semantics.
+---
+
+`defi-cli` always emits a stable envelope in JSON mode unless `--results-only` is used on successful commands.
+
+## Success envelope
+
+```json
+{
+  "version": "v1",
+  "success": true,
+  "data": [...],
+  "error": null,
+  "warnings": [],
+  "meta": {
+    "request_id": "...",
+    "timestamp": "2026-02-24T03:00:10Z",
+    "command": "lend markets",
+    "providers": [{"name": "aave", "status": "ok", "latency_ms": 372}],
+    "cache": {"status": "miss", "age_ms": 0, "stale": false},
+    "partial": false
+  }
+}
+```
+
+## Error envelope behavior
+
+Errors always return the full envelope, even if you pass `--results-only` or `--select`.
+
+```json
+{
+  "version": "v1",
+  "success": false,
+  "data": [],
+  "error": {
+    "code": 10,
+    "type": "auth_error",
+    "message": "missing required API key for 1inch (DEFI_1INCH_API_KEY)"
+  },
+  "meta": {
+    "command": "swap quote",
+    "cache": {"status": "bypass", "age_ms": 0, "stale": false},
+    "partial": false
+  }
+}
+```
+
+## Rendering flags
+
+| Flag | Behavior |
+| --- | --- |
+| `--json` | JSON output (default) |
+| `--plain` | key=value lines |
+| `--results-only` | output only `data` on success |
+| `--select a,b,c` | project selected fields from `data` |
+
+## Stability guarantees
+
+- `error.code` maps to stable process exit codes
+- `meta.command` uses normalized command paths
+- provider status values are stable (`ok`, `auth_error`, `rate_limited`, `unavailable`, `error`)
+- APY values are percentage points (`2.3` means `2.3%`)
+- lending/yield rows include retrieval-first IDs: `provider`, `provider_native_id`, `provider_native_id_kind`
+- bridge quotes expose `fee_breakdown` when provider fee components are available
+
+See [Envelope Schema](/reference/envelope-schema) and [Exit Codes](/reference/exit-codes).
diff --git a/docs/concepts/providers-and-auth.mdx b/docs/concepts/providers-and-auth.mdx
new file mode 100644
index 0000000..1c0e350
--- /dev/null
+++ b/docs/concepts/providers-and-auth.mdx
@@ -0,0 +1,53 @@
+---
+title: Providers and Auth
+description: Provider coverage, key requirements, and routing behavior.
+---
+
+## Provider matrix
+
+| Provider | Capabilities | Key required |
+| --- | --- | --- |
+| `defillama` | chains/protocols + bridge analytics (`bridge list`, `bridge details`) | Route-specific |
+| `aave` | lend, yield | No |
+| `morpho` | lend, yield | No |
+| `kamino` | lend, yield (Solana mainnet) | No |
+| `across` | bridge quote | No |
+| `lifi` | bridge quote | No |
+| `bungee` | bridge quote, swap quote | No (default mode) |
+| `1inch` | swap quote | Yes |
+| `uniswap` | swap quote | Yes |
+| `jupiter` | swap quote (Solana) | Optional |
+| `fibrous` | swap quote | No |
+
+API keys in `defi-cli` are provider constraints, not CLI monetization/auth. If a provider endpoint requires credentials, the corresponding command requires that provider key.
+
+## Key requirements by route
+
+- `swap quote --provider 1inch` -> `DEFI_1INCH_API_KEY`
+- `swap quote --provider uniswap` -> `DEFI_UNISWAP_API_KEY`
+- `swap quote --provider jupiter` -> `DEFI_JUPITER_API_KEY` (optional for higher limits)
+- `chains assets`, `bridge list`, `bridge details` -> `DEFI_DEFILLAMA_API_KEY`
+
+Optional Bungee dedicated backend mode requires:
+
+- `DEFI_BUNGEE_API_KEY`
+- `DEFI_BUNGEE_AFFILIATE`
+
+If either is missing, bungee quotes use public backend.
+
+## Routing and fallback
+
+- Lending routes by `--protocol` (`aave`, `morpho`, `kamino`) using direct adapters only.
+- `yield opportunities` aggregates direct providers and accepts `--providers aave,morpho,kamino`.
+- `swap quote` defaults by chain family: `1inch` for EVM chains, `jupiter` for Solana.
+- Provider/chain-family mismatches fail fast with `unsupported` errors (for example `--provider jupiter` on EVM chains).
+
+## Data caveats
+
+- Morpho can surface very high APY in tiny markets. Use `--min-tvl-usd`.
+- Kamino currently supports Solana mainnet only.
+- Solana devnet/testnet and custom Solana CAIP-2 references are unsupported.
+- Bungee quote support is chain + token dependent.
+- Fibrous currently supports `base`, `hyperevm`, and `citrea` (`monad` temporarily disabled).
+- Bungee quote requests use deterministic placeholder sender/receiver addresses for quote-only resolution (`0x000...001`).
+- Across may omit native USD fee fields for some routes; when missing, `estimated_fee_usd` can fall back to a stable-asset approximation while token-unit fees remain in `fee_breakdown`.
diff --git a/docs/docs.json b/docs/docs.json
new file mode 100644
index 0000000..0f94d57
--- /dev/null
+++ b/docs/docs.json
@@ -0,0 +1,118 @@
+{
+  "$schema": "https://mintlify.com/docs.json",
+  "theme": "mint",
+  "name": "defi-cli",
+  "description": "Agent-first DeFi retrieval CLI documentation",
+  "colors": {
+    "primary": "#0F766E",
+    "light": "#14B8A6",
+    "dark": "#0F766E"
+  },
+  "favicon": "/images/docs-lobster.png",
+  "logo": {
+    "light": "/images/docs-logo-lobster-light.png",
+    "dark": "/images/docs-logo-lobster-dark.png"
+  },
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "Learn",
+        "groups": [
+          {
+            "group": "Getting Started",
+            "pages": [
+              "index",
+              "installation",
+              "quickstart"
+            ]
+          },
+          {
+            "group": "Core Concepts",
+            "pages": [
+              "concepts/output-contract",
+              "concepts/ids-and-amounts",
+              "concepts/config-and-cache",
+              "concepts/providers-and-auth"
+            ]
+          },
+          {
+            "group": "Workflow Guides",
+            "pages": [
+              "guides/market-discovery",
+              "guides/lending",
+              "guides/yield",
+              "guides/bridge",
+              "guides/swap"
+            ]
+          }
+        ]
+      },
+      {
+        "tab": "Agents",
+        "groups": [
+          {
+            "group": "Automation",
+            "pages": [
+              "agents/overview",
+              "agents/schema-driven",
+              "agents/reliability-patterns"
+            ]
+          }
+        ]
+      },
+      {
+        "tab": "Reference",
+        "groups": [
+          {
+            "group": "CLI Commands",
+            "pages": [
+              "reference/commands-overview",
+              "reference/market-commands",
+              "reference/lending-and-yield-commands",
+              "reference/bridge-and-swap-commands",
+              "reference/meta-commands"
+            ]
+          },
+          {
+            "group": "Contracts",
+            "pages": [
+              "reference/envelope-schema",
+              "reference/exit-codes",
+              "reference/chain-aliases"
+            ]
+          }
+        ]
+      }
+    ]
+  },
+  "navbar": {
+    "links": [
+      {
+        "label": "GitHub",
+        "href": "https://github.com/ggonzalez94/defi-cli"
+      }
+    ],
+    "primary": {
+      "type": "button",
+      "label": "Install",
+      "href": "https://github.com/ggonzalez94/defi-cli#install"
+    }
+  },
+  "contextual": {
+    "options": [
+      "copy",
+      "view",
+      "chatgpt",
+      "claude",
+      "perplexity",
+      "mcp",
+      "cursor",
+      "vscode"
+    ]
+  },
+  "footer": {
+    "socials": {
+      "github": "https://github.com/ggonzalez94/defi-cli"
+    }
+  }
+}
diff --git a/docs/guides/bridge.mdx b/docs/guides/bridge.mdx
new file mode 100644
index 0000000..200f8c6
--- /dev/null
+++ b/docs/guides/bridge.mdx
@@ -0,0 +1,43 @@
+---
+title: Bridge
+description: Get bridge quotes and bridge analytics with provider-specific behavior.
+---
+
+## Quote routes
+
+Default provider is `across`:
+
+```bash
+defi bridge quote --from 1 --to 8453 --asset USDC --amount 1000000 --results-only
+```
+
+Use a specific provider:
+
+```bash
+defi bridge quote --provider lifi --from 1 --to 8453 --asset USDC --amount 1000000 --results-only
+defi bridge quote --provider bungee --from hyperevm --to 8453 --asset USDC --amount 5000000 --results-only
+```
+
+Amount inputs:
+
+```bash
+defi bridge quote --from 1 --to 8453 --asset USDC --amount-decimal 1.5 --results-only
+```
+
+## Bridge analytics
+
+These commands require `DEFI_DEFILLAMA_API_KEY`:
+
+```bash
+defi bridge list --limit 20 --results-only
+defi bridge details --bridge layerzero --results-only
+```
+
+## Notes
+
+- `--to-asset` is optional; default is source symbol on destination chain.
+- Bungee quote mode is keyless by default.
+- Optional bungee dedicated backend mode requires both `DEFI_BUNGEE_API_KEY` and `DEFI_BUNGEE_AFFILIATE`.
+- Bungee quote requests use deterministic placeholder sender/receiver addresses for quote-only flows.
+- Quotes include `fee_breakdown` with `lp_fee`, `relayer_fee`, `gas_fee`, totals, and a consistency check against amount deltas.
+- Across can omit native USD fee fields on some routes; in those cases `estimated_fee_usd` may use a stable-asset approximation.
diff --git a/docs/guides/lending.mdx b/docs/guides/lending.mdx
new file mode 100644
index 0000000..fa68829
--- /dev/null
+++ b/docs/guides/lending.mdx
@@ -0,0 +1,42 @@
+---
+title: Lending
+description: Query lending markets and rates across direct protocol adapters.
+---
+
+## Markets
+
+```bash
+defi lend markets --protocol aave --chain 1 --asset USDC --limit 10 --results-only
+defi lend markets --protocol kamino --chain solana --asset USDC --limit 10 --results-only
+```
+
+## Rates
+
+```bash
+defi lend rates --protocol morpho --chain 1 --asset USDC --limit 10 --results-only
+defi lend rates --protocol kamino --chain solana --asset USDC --limit 10 --results-only
+```
+
+## Protocol routing
+
+- `--protocol aave` -> Aave adapter
+- `--protocol morpho` -> Morpho adapter
+- `--protocol kamino` -> Kamino adapter (Solana mainnet only)
+
+## Suggested filters and reliability defaults
+
+```bash
+defi lend rates --protocol morpho --chain 1 --asset USDC --limit 20 --timeout 12s --retries 2 --max-stale 5m --results-only
+```
+
+## Output fields
+
+`lend markets` returns:
+
+- `protocol`, `chain_id`, `asset_id`
+- `provider`, `provider_native_id`, `provider_native_id_kind`
+- `supply_apy`, `borrow_apy`
+- `tvl_usd`, `liquidity_usd`
+- `source_url`, `fetched_at`
+
+`lend rates` adds `utilization`.
diff --git a/docs/guides/market-discovery.mdx b/docs/guides/market-discovery.mdx
new file mode 100644
index 0000000..9170124
--- /dev/null
+++ b/docs/guides/market-discovery.mdx
@@ -0,0 +1,43 @@
+---
+title: Market Discovery
+description: Discover chains, protocols, and assets before running strategy-specific commands.
+---
+
+Use market-discovery commands to scope chains/protocols and normalize assets first.
+
+## Top chains by TVL
+
+```bash
+defi chains top --limit 10 --results-only --select rank,chain,chain_id,tvl_usd
+```
+
+## Asset TVL on a chain
+
+```bash
+export DEFI_DEFILLAMA_API_KEY=...
+defi chains assets --chain 1 --asset USDC --limit 20 --results-only
+```
+
+Notes:
+
+- `chains assets` requires `DEFI_DEFILLAMA_API_KEY`.
+- If filtering by token address/CAIP-19, the token must have a known symbol on that chain.
+
+## Top protocols and categories
+
+```bash
+defi protocols top --limit 20 --results-only
+defi protocols top --category lending --limit 20 --results-only
+defi protocols categories --results-only
+```
+
+Category ranking is deterministic: `tvl_usd`, then protocol count, then name.
+
+## Resolve assets to canonical IDs
+
+```bash
+defi assets resolve --chain base --asset USDC --results-only
+defi assets resolve --chain eip155:1 --asset eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 --results-only
+```
+
+Use this as a normalization step before storing request plans for agents.
diff --git a/docs/guides/swap.mdx b/docs/guides/swap.mdx
new file mode 100644
index 0000000..710f209
--- /dev/null
+++ b/docs/guides/swap.mdx
@@ -0,0 +1,50 @@
+---
+title: Swap
+description: Get swap quotes across 1inch, Uniswap, Jupiter, Fibrous, and Bungee.
+---
+
+## 1inch (key required)
+
+```bash
+export DEFI_1INCH_API_KEY=...
+defi swap quote --provider 1inch --chain 1 --from-asset USDC --to-asset DAI --amount 1000000 --results-only
+```
+
+## Uniswap (key required)
+
+```bash
+export DEFI_UNISWAP_API_KEY=...
+defi swap quote --provider uniswap --chain 1 --from-asset USDC --to-asset DAI --amount 1000000 --results-only
+```
+
+## Jupiter (Solana, key optional)
+
+```bash
+defi swap quote --chain solana --from-asset USDC --to-asset SOL --amount 1000000 --results-only
+```
+
+Optional higher-limit setup:
+
+```bash
+export DEFI_JUPITER_API_KEY=...
+defi swap quote --provider jupiter --chain solana --from-asset USDC --to-asset SOL --amount 1000000 --results-only
+```
+
+## Fibrous (keyless)
+
+```bash
+defi swap quote --provider fibrous --chain hyperevm --from-asset USDC --to-asset WHYPE --amount 1000000 --results-only
+```
+
+## Bungee auto (keyless default)
+
+```bash
+defi swap quote --provider bungee --chain hyperevm --from-asset USDC --to-asset WHYPE --amount 5000000 --results-only
+```
+
+## Notes
+
+- `swap quote` defaults by chain family: `1inch` for EVM chains, `jupiter` for Solana.
+- `--amount` and `--amount-decimal` are mutually exclusive.
+- Output always includes normalized `input_amount` and `estimated_out` with base and decimal forms.
+- Fibrous currently supports `base`, `hyperevm`, and `citrea`.
diff --git a/docs/guides/yield.mdx b/docs/guides/yield.mdx
new file mode 100644
index 0000000..3d56533
--- /dev/null
+++ b/docs/guides/yield.mdx
@@ -0,0 +1,48 @@
+---
+title: Yield
+description: Rank and filter yield opportunities with provider-aware behavior.
+---
+
+## Basic ranking
+
+```bash
+defi yield opportunities --chain 1 --asset USDC --limit 20 --results-only
+```
+
+## Select providers explicitly
+
+```bash
+defi yield opportunities --chain 1 --asset USDC --providers aave,morpho --limit 20 --results-only
+defi yield opportunities --chain solana --asset USDC --providers kamino --limit 20 --results-only
+```
+
+`--providers` expects provider names from `defi providers list`.
+
+## Control risk and quality
+
+```bash
+defi yield opportunities \
+  --chain 1 \
+  --asset USDC \
+  --providers aave,morpho \
+  --min-tvl-usd 1000000 \
+  --min-apy 1 \
+  --max-risk medium \
+  --sort score \
+  --limit 20 \
+  --results-only
+```
+
+## Incomplete opportunities
+
+```bash
+defi yield opportunities --chain 1 --asset USDC --include-incomplete --results-only
+```
+
+When enabled, warnings may indicate missing APY/TVL and combined-provider counts.
+
+## Important caveats
+
+- APY values are percentage points (`2.3` = `2.3%`).
+- Morpho may produce extreme APY for very small markets; use `--min-tvl-usd`.
+- Kamino yield routes currently support Solana mainnet only.
diff --git a/docs/images/docs-lobster.png b/docs/images/docs-lobster.png
new file mode 100644
index 0000000..346b6ff
Binary files /dev/null and b/docs/images/docs-lobster.png differ
diff --git a/docs/images/docs-logo-lobster-dark.png b/docs/images/docs-logo-lobster-dark.png
new file mode 100644
index 0000000..9e57f3b
Binary files /dev/null and b/docs/images/docs-logo-lobster-dark.png differ
diff --git a/docs/images/docs-logo-lobster-light.png b/docs/images/docs-logo-lobster-light.png
new file mode 100644
index 0000000..c584966
Binary files /dev/null and b/docs/images/docs-logo-lobster-light.png differ
diff --git a/docs/index.mdx b/docs/index.mdx
new file mode 100644
index 0000000..06fde25
--- /dev/null
+++ b/docs/index.mdx
@@ -0,0 +1,77 @@
+---
+title: defi-cli Docs
+description: Query DeFi lending, yield, bridge, and swap data from a single agent-first CLI.
+---
+
+`defi-cli` is an agent-first DeFi retrieval CLI with a stable automation contract:
+
+- Stable JSON envelope + deterministic field naming
+- Stable exit codes
+- Canonical chain and asset IDs (CAIP-2 / CAIP-19)
+- Canonical amount handling (base units + decimal normalization)
+
+## Start here
+
+- New user: [Installation](/installation) -> [Quickstart](/quickstart)
+- Building automation: [Output Contract](/concepts/output-contract) -> [Agent Overview](/agents/overview)
+- Need exact command flags: [Command Reference](/reference/commands-overview)
+- Need provider/key rules: [Providers and Auth](/concepts/providers-and-auth)
+
+## Example
+
+```bash
+defi providers list --results-only
+```
+
+```json
+[
+  {
+    "name": "defillama",
+    "type": "market+bridge-data",
+    "requires_key": false,
+    "capabilities": ["chains.top", "chains.assets", "protocols.top", "protocols.categories", "bridge.list", "bridge.details"],
+    "key_env_var": "DEFI_DEFILLAMA_API_KEY"
+  },
+  {
+    "name": "kamino",
+    "type": "lending+yield",
+    "requires_key": false,
+    "capabilities": ["lend.markets", "lend.rates", "yield.opportunities"]
+  },
+  {
+    "name": "jupiter",
+    "type": "swap",
+    "requires_key": false,
+    "capabilities": ["swap.quote"],
+    "key_env_var": "DEFI_JUPITER_API_KEY"
+  }
+]
+```
+
+## Key-gated routes
+
+Most commands are keyless. Key requirements are driven by upstream providers, not by CLI licensing/auth.
+
+| Route | Env var |
+| --- | --- |
+| `swap quote --provider 1inch` | `DEFI_1INCH_API_KEY` |
+| `swap quote --provider uniswap` | `DEFI_UNISWAP_API_KEY` |
+| `swap quote --provider jupiter` | `DEFI_JUPITER_API_KEY` (optional for higher limits) |
+| `chains assets` | `DEFI_DEFILLAMA_API_KEY` |
+| `bridge list` | `DEFI_DEFILLAMA_API_KEY` |
+| `bridge details` | `DEFI_DEFILLAMA_API_KEY` |
+
+Bungee quotes are keyless by default. Dedicated backend mode requires both `DEFI_BUNGEE_API_KEY` and `DEFI_BUNGEE_AFFILIATE`.
+
+## Lending and yield routing
+
+`lend markets`, `lend rates`, and `yield opportunities` use direct protocol adapters:
+
+- `aave`
+- `morpho`
+- `kamino` (Solana mainnet)
+
+## Next
+
+- [Quickstart](/quickstart)
+- [Providers and Auth](/concepts/providers-and-auth)
diff --git a/docs/installation.mdx b/docs/installation.mdx
new file mode 100644
index 0000000..1062720
--- /dev/null
+++ b/docs/installation.mdx
@@ -0,0 +1,60 @@
+---
+title: Installation
+description: Install defi-cli from release artifacts, Go, or source.
+---
+
+## Quick install (macOS/Linux)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/ggonzalez94/defi-cli/main/scripts/install.sh | sh
+```
+
+Install a specific version:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/ggonzalez94/defi-cli/main/scripts/install.sh | sh -s -- v0.2.0
+```
+
+## Go install
+
+```bash
+go install github.com/ggonzalez94/defi-cli/cmd/defi@latest
+```
+
+## Build from source
+
+```bash
+git clone https://github.com/ggonzalez94/defi-cli.git
+cd defi-cli
+go build -o defi ./cmd/defi
+```
+
+## Verify install
+
+```bash
+defi version --long
+defi --help
+```
+
+## Optional shell completion
+
+```bash
+defi completion zsh > ~/.zsh/completions/_defi
+defi completion bash > ~/.local/share/bash-completion/completions/defi
+defi completion fish > ~/.config/fish/completions/defi.fish
+```
+
+## API key setup
+
+Use environment variables (recommended):
+
+```bash
+export DEFI_1INCH_API_KEY=...
+export DEFI_UNISWAP_API_KEY=...
+export DEFI_JUPITER_API_KEY=...
+export DEFI_DEFILLAMA_API_KEY=...
+export DEFI_BUNGEE_API_KEY=...
+export DEFI_BUNGEE_AFFILIATE=...
+```
+
+Most routes do not require keys. `DEFI_JUPITER_API_KEY` is optional and mainly useful for higher Jupiter API limits. See [Providers and Auth](/concepts/providers-and-auth) for route-level requirements.
diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx
new file mode 100644
index 0000000..75adf12
--- /dev/null
+++ b/docs/quickstart.mdx
@@ -0,0 +1,69 @@
+---
+title: Quickstart
+description: Run the most common defi-cli workflows in a few minutes.
+---
+
+## 1. List providers
+
+```bash
+defi providers list --results-only
+```
+
+## 2. Discover market context
+
+```bash
+defi chains top --limit 10 --results-only --select rank,chain,chain_id,tvl_usd
+defi protocols top --category lending --limit 10 --results-only
+```
+
+## 3. Resolve an asset to canonical ID
+
+```bash
+defi assets resolve --chain base --asset USDC --results-only
+defi assets resolve --chain solana --asset USDC --results-only
+```
+
+## 4. Query lending markets and rates
+
+```bash
+defi lend markets --protocol aave --chain 1 --asset USDC --limit 5 --results-only
+defi lend rates --protocol morpho --chain 1 --asset USDC --limit 5 --results-only
+defi lend markets --protocol kamino --chain solana --asset USDC --limit 5 --results-only
+```
+
+## 5. Rank yield opportunities
+
+```bash
+defi yield opportunities --chain 1 --asset USDC --providers aave,morpho --limit 10 --results-only
+defi yield opportunities --chain solana --asset USDC --providers kamino --limit 10 --results-only
+defi yield opportunities --chain 1 --asset USDC --providers aave,morpho --min-tvl-usd 1000000 --limit 10 --results-only
+```
+
+`--providers` expects provider names from `providers list` (`aave,morpho,kamino`), not protocol categories.
+
+## 6. Get bridge and swap quotes
+
+```bash
+defi bridge quote --from 1 --to 8453 --asset USDC --amount 1000000 --results-only
+defi bridge quote --provider bungee --from hyperevm --to 8453 --asset USDC --amount 1000000 --results-only
+
+defi swap quote --provider fibrous --chain hyperevm --from-asset USDC --to-asset WHYPE --amount 1000000 --results-only
+defi swap quote --chain solana --from-asset USDC --to-asset SOL --amount 1000000 --results-only
+```
+
+On Solana, `swap quote` defaults to the Jupiter adapter.
+
+## 7. Use schema for machine integration
+
+```bash
+defi schema --results-only
+defi schema "yield opportunities" --results-only
+```
+
+## 8. Add reliability defaults
+
+```bash
+defi yield opportunities --chain 1 --asset USDC --timeout 12s --retries 2 --max-stale 5m --results-only
+```
+
+Next: [Output Contract](/concepts/output-contract)
diff --git a/docs/reference/bridge-and-swap-commands.mdx b/docs/reference/bridge-and-swap-commands.mdx
new file mode 100644
index 0000000..af6431b
--- /dev/null
+++ b/docs/reference/bridge-and-swap-commands.mdx
@@ -0,0 +1,75 @@
+---
+title: Bridge and Swap Commands
+description: Full reference for quote and bridge-analytics command families.
+---
+
+## `bridge quote`
+
+```bash
+defi bridge quote --from 1 --to 8453 --asset USDC --amount 1000000 --results-only
+```
+
+Flags:
+
+- `--provider string` (`across|lifi|bungee`, default `across`)
+- `--from string` required
+- `--to string` required
+- `--asset string` required
+- `--to-asset string` optional
+- `--amount string` or `--amount-decimal string`
+
+Output note: bridge quotes include `fee_breakdown` with component fees (`lp_fee`, `relayer_fee`, `gas_fee`) and aggregate totals when available.
+
+## `bridge list`
+
+```bash
+defi bridge list --limit 20 --include-chains --results-only
+```
+
+Flags:
+
+- `--limit int` (default `20`)
+- `--include-chains` bool (default `true`)
+
+Auth: requires `DEFI_DEFILLAMA_API_KEY`.
+
+Reason: this route uses DefiLlama bridge analytics endpoints that are provider-gated.
+
+## `bridge details`
+
+```bash
+defi bridge details --bridge layerzero --include-chain-breakdown --results-only
+```
+
+Flags:
+
+- `--bridge string` required
+- `--include-chain-breakdown` bool (default `true`)
+
+Auth: requires `DEFI_DEFILLAMA_API_KEY`.
+
+Reason: this route uses DefiLlama bridge analytics endpoints that are provider-gated.
+
+## `swap quote`
+
+```bash
+defi swap quote --provider fibrous --chain hyperevm --from-asset USDC --to-asset WHYPE --amount 1000000 --results-only
+defi swap quote --chain solana --from-asset USDC --to-asset SOL --amount 1000000 --results-only
+```
+
+Flags:
+
+- `--provider string` (`1inch|uniswap|jupiter|fibrous|bungee`, default: `1inch` on EVM, `jupiter` on Solana)
+- `--chain string` required
+- `--from-asset string` required
+- `--to-asset string` required
+- `--amount string` or `--amount-decimal string`
+
+Auth requirements:
+
+- `1inch` -> `DEFI_1INCH_API_KEY`
+- `uniswap` -> `DEFI_UNISWAP_API_KEY`
+- `jupiter` -> `DEFI_JUPITER_API_KEY` (optional for higher limits)
+- `fibrous`, `bungee` -> keyless by default
+
+These requirements are driven by provider APIs. `defi-cli` passes through provider auth requirements per route/provider pair.
diff --git a/docs/reference/chain-aliases.mdx b/docs/reference/chain-aliases.mdx
new file mode 100644
index 0000000..619b2ba
--- /dev/null
+++ b/docs/reference/chain-aliases.mdx
@@ -0,0 +1,39 @@
+---
+title: Chain Aliases
+description: Supported chain alias normalization for chain-related flags.
+---
+
+`--chain`, `--from`, and `--to` normalize aliases, numeric IDs, and CAIP-2 values.
+
+## Common aliases
+
+| Canonical chain ID | Example aliases |
+| --- | --- |
+| `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` | `solana`, `solana-mainnet`, `mainnet-beta` |
+| `eip155:1` | `ethereum`, `mainnet`, `1` |
+| `eip155:10` | `optimism`, `op mainnet`, `10` |
+| `eip155:56` | `bsc`, `56` |
+| `eip155:100` | `gnosis`, `xdai`, `100` |
+| `eip155:137` | `polygon`, `137` |
+| `eip155:8453` | `base`, `8453` |
+| `eip155:42161` | `arbitrum`, `42161` |
+| `eip155:43114` | `avalanche`, `43114` |
+| `eip155:5000` | `mantle`, `5000` |
+| `eip155:4326` | `megaeth`, `mega eth`, `mega-eth`, `4326` |
+| `eip155:57073` | `ink`, `57073` |
+| `eip155:534352` | `scroll`, `534352` |
+| `eip155:80094` | `berachain`, `80094` |
+| `eip155:81457` | `blast`, `81457` |
+| `eip155:252` | `fraxtal`, `252` |
+| `eip155:480` | `worldchain`, `world chain`, `world-chain`, `480` |
+| `eip155:42220` | `celo`, `42220` |
+| `eip155:167000` | `taiko`, `taiko alethia`, `taiko-alethia`, `167000` |
+| `eip155:324` | `zksync`, `zksync era`, `zksync-era`, `324` |
+| `eip155:999` | `hyperevm`, `hyper evm`, `hyper-evm`, `999` |
+| `eip155:143` | `monad`, `143` |
+| `eip155:4114` | `citrea`, `4114` |
+| `eip155:146` | `sonic`, `146` |
+
+If a numeric EVM chain ID is unknown, `defi-cli` still normalizes it to `eip155:<id>`.
+
+Solana support is mainnet-only. `solana-devnet`, `solana-testnet`, and custom Solana CAIP-2 references are intentionally rejected.
diff --git a/docs/reference/commands-overview.mdx b/docs/reference/commands-overview.mdx
new file mode 100644
index 0000000..c9ed29a
--- /dev/null
+++ b/docs/reference/commands-overview.mdx
@@ -0,0 +1,49 @@
+---
+title: Commands Overview
+description: Top-level command map and shared global flags.
+---
+
+## Top-level commands
+
+- `assets`
+- `bridge`
+- `chains`
+- `lend`
+- `protocols`
+- `providers`
+- `schema`
+- `swap`
+- `version`
+- `yield`
+- `completion`
+
+## Global flags
+
+| Flag | Type | Description |
+| --- | --- | --- |
+| `--json` | bool | Output JSON (default) |
+| `--plain` | bool | Output plain text |
+| `--results-only` | bool | Output only data payload on success |
+| `--select` | string | Select fields from payload |
+| `--strict` | bool | Fail on partial results |
+| `--timeout` | duration string | Provider request timeout |
+| `--retries` | int | Retries per provider request |
+| `--max-stale` | duration string | Max stale fallback window |
+| `--no-stale` | bool | Disable stale fallback |
+| `--no-cache` | bool | Disable cache reads/writes |
+| `--enable-commands` | CSV string | Command allowlist policy |
+| `--config` | string | Config file path |
+
+## Usage pattern
+
+```bash
+defi <command> <subcommand> [flags] [global flags]
+```
+
+Examples:
+
+```bash
+defi lend markets --protocol aave --chain 1 --asset USDC --results-only
+defi bridge quote --from 1 --to 8453 --asset USDC --amount 1000000 --timeout 12s --retries 2 --results-only
+defi swap quote --chain solana --from-asset USDC --to-asset SOL --amount 1000000 --results-only
+```
diff --git a/docs/reference/envelope-schema.mdx b/docs/reference/envelope-schema.mdx
new file mode 100644
index 0000000..b0da608
--- /dev/null
+++ b/docs/reference/envelope-schema.mdx
@@ -0,0 +1,49 @@
+---
+title: Envelope Schema
+description: Field-level contract for success and error responses.
+---
+
+## Envelope fields
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `version` | string | Envelope version (`v1`) |
+| `success` | bool | `true` on success, `false` on error |
+| `data` | any | Command payload (array/object depending on command) |
+| `error` | object or `null` | Present on failures |
+| `warnings` | string[] | Optional warnings |
+| `meta` | object | Execution metadata |
+
+## `meta`
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `request_id` | string | Unique per invocation |
+| `timestamp` | RFC3339 timestamp | UTC |
+| `command` | string | Normalized command path |
+| `providers` | array | Provider statuses and latencies |
+| `cache` | object | Cache status metadata |
+| `partial` | bool | Indicates partial aggregation |
+
+## `cache`
+
+| Field | Type | Values |
+| --- | --- | --- |
+| `status` | string | `bypass`, `miss`, `hit`, `write` |
+| `age_ms` | int | Age of cached response in milliseconds |
+| `stale` | bool | Whether served cache entry is stale |
+
+## Key payload models
+
+- Market commands: `ChainTVL`, `ChainAssetTVL`, `ProtocolTVL`, `ProtocolCategory`, `AssetResolution`
+- Lending: `LendMarket`, `LendRate`
+- Yield: `YieldOpportunity`
+- Bridge: `BridgeQuote`, `BridgeSummary`, `BridgeDetails`
+- Swap: `SwapQuote`
+
+## Payload notes
+
+- `LendMarket`, `LendRate`, and `YieldOpportunity` include `provider`, `provider_native_id`, and `provider_native_id_kind` for provider-scoped identity.
+- `BridgeQuote` may include `fee_breakdown` with `lp_fee`, `relayer_fee`, `gas_fee`, and aggregate totals.
+
+For practical examples, see [Quickstart](/quickstart).
diff --git a/docs/reference/exit-codes.mdx b/docs/reference/exit-codes.mdx
new file mode 100644
index 0000000..dbc16d5
--- /dev/null
+++ b/docs/reference/exit-codes.mdx
@@ -0,0 +1,25 @@
+---
+title: Exit Codes
+description: Stable exit code contract for scripts and agents.
+---
+
+## Stable mapping
+
+| Exit code | Type | Meaning |
+| --- | --- | --- |
+| `0` | success | Command succeeded |
+| `1` | internal_error | Internal execution error |
+| `2` | usage_error | Invalid command or flags |
+| `10` | auth_error | Missing/invalid provider key |
+| `11` | rate_limited | Provider throttling |
+| `12` | provider_unavailable | Provider unavailable |
+| `13` | unsupported | Unsupported input/provider pair |
+| `14` | stale_data | Stale data beyond configured budget |
+| `15` | partial_results | Partial results with `--strict` |
+| `16` | command_blocked | Blocked by `--enable-commands` policy |
+
+## Error handling recommendation
+
+- Parse stderr envelope on non-zero exits.
+- Branch logic on `error.code`.
+- Use retries only for transient types (`11`, `12`).
diff --git a/docs/reference/lending-and-yield-commands.mdx b/docs/reference/lending-and-yield-commands.mdx
new file mode 100644
index 0000000..b23e82f
--- /dev/null
+++ b/docs/reference/lending-and-yield-commands.mdx
@@ -0,0 +1,61 @@
+---
+title: Lending and Yield Commands
+description: Full reference for lend and yield command flags and examples.
+---
+
+## `lend markets`
+
+```bash
+defi lend markets --protocol aave --chain 1 --asset USDC --limit 20 --results-only
+defi lend markets --protocol kamino --chain solana --asset USDC --limit 20 --results-only
+```
+
+Flags:
+
+- `--protocol string` (`aave`, `morpho`, `kamino`) required
+- `--chain string` required
+- `--asset string` required
+- `--limit int` (default `20`)
+
+## `lend rates`
+
+```bash
+defi lend rates --protocol morpho --chain 1 --asset USDC --limit 20 --results-only
+defi lend rates --protocol kamino --chain solana --asset USDC --limit 20 --results-only
+```
+
+Flags are the same as `lend markets`.
+
+## `yield opportunities`
+
+```bash
+defi yield opportunities \
+  --chain 1 \
+  --asset USDC \
+  --providers aave,morpho \
+  --min-tvl-usd 1000000 \
+  --max-risk medium \
+  --sort score \
+  --limit 20 \
+  --results-only
+```
+
+Flags:
+
+- `--chain string` required
+- `--asset string` required
+- `--limit int` (default `20`)
+- `--min-tvl-usd float` (default `0`)
+- `--min-apy float` (default `0`)
+- `--max-risk string` (`low|medium|high|unknown`, default `high`)
+- `--providers string` (`aave,morpho,kamino`)
+- `--sort string` (`score|apy_total|tvl_usd|liquidity_usd`, default `score`)
+- `--include-incomplete` bool (default `false`)
+
+## Provider-selection note
+
+`--providers` accepts provider names, not protocol categories.
+
+## Routing note
+
+`lend` and `yield` routes are direct-provider only (`aave`, `morpho`, `kamino`).
diff --git a/docs/reference/market-commands.mdx b/docs/reference/market-commands.mdx
new file mode 100644
index 0000000..55e4df8
--- /dev/null
+++ b/docs/reference/market-commands.mdx
@@ -0,0 +1,76 @@
+---
+title: Market Commands
+description: Reference for providers, chains, protocols, and assets commands.
+---
+
+## `providers list`
+
+List supported providers and capability auth metadata.
+
+```bash
+defi providers list --results-only
+```
+
+## `chains top`
+
+Top chains by TVL.
+
+```bash
+defi chains top --limit 20 --results-only
+```
+
+Flags:
+
+- `--limit int` (default `20`)
+
+## `chains assets`
+
+Asset-level TVL for a chain.
+
+```bash
+defi chains assets --chain 1 --asset USDC --limit 20 --results-only
+```
+
+Flags:
+
+- `--chain string` (required)
+- `--asset string` (optional filter)
+- `--limit int` (default `20`)
+
+Auth: requires `DEFI_DEFILLAMA_API_KEY`.
+
+Reason: `chains assets` is backed by a DefiLlama endpoint that is provider-gated.
+
+## `protocols top`
+
+Top protocols by TVL.
+
+```bash
+defi protocols top --category lending --limit 20 --results-only
+```
+
+Flags:
+
+- `--category string` (optional)
+- `--limit int` (default `20`)
+
+## `protocols categories`
+
+List categories with protocol counts and TVL.
+
+```bash
+defi protocols categories --results-only
+```
+
+## `assets resolve`
+
+Resolve symbol/address/CAIP-19 to canonical asset metadata.
+
+```bash
+defi assets resolve --chain base --asset USDC --results-only
+```
+
+Flags:
+
+- `--chain string` (required)
+- `--asset string` or `--symbol string` (at least one required)
diff --git a/docs/reference/meta-commands.mdx b/docs/reference/meta-commands.mdx
new file mode 100644
index 0000000..fbab59b
--- /dev/null
+++ b/docs/reference/meta-commands.mdx
@@ -0,0 +1,37 @@
+---
+title: Meta Commands
+description: Schema, version, and completion command reference.
+---
+
+## `schema [command path]`
+
+Print machine-readable command schema.
+
+```bash
+defi schema --results-only
+defi schema "swap quote" --results-only
+```
+
+## `version`
+
+Print CLI version.
+
+```bash
+defi version
+defi version --long
+```
+
+## `completion`
+
+Generate shell completion scripts.
+
+```bash
+defi completion zsh
+defi completion bash
+defi completion fish
+defi completion powershell
+```
+
+## Cache bypass behavior
+
+`version`, `schema`, and `providers list` bypass cache initialization.