docs: launch Mintlify docs site with CI and branding refinements

.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

.gitignore

@@ -1,8 +1,9 @@
 /bin/
 /dist/
 /defi
+.mintlify/
 *.test
 *.out
 .coverprofile
 .DS_Store
-TODO.md
+TODO.md

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`.

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.

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

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.

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.

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.

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`).

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).