@askalf/dario 5.4.15 → 5.4.17

package/docs/integrations/openclaw-walkthrough.md

@@ -0,0 +1,248 @@
+# dario + OpenClaw — battletested setup
+
+End-to-end walkthrough for running OpenClaw through dario so it routes against your Claude Pro / Max subscription instead of paying per-token API rates. Covers install → config → first run → verification → the gotchas that bite first-time users — including the `openclaw.inbound_meta.v1` classifier filter that dario's default mode silently protects against.
+
+This is opinionated. There are several ways to wire OpenClaw to dario; this is the one we run in production and trust to not surprise us. Where we omit options it's because they're worse, not because they don't exist.
+
+## What you'll have at the end
+
+- OpenClaw running locally, talking to dario at `localhost:3456`
+- All Claude API calls routed through your Pro / Max subscription via the Claude Code wire shape
+- OpenClaw's tool schema (`exec`, `process`, `web_search`, `web_fetch`, `browser`, `message`) auto-translated to CC's canonical set on the outbound path and rebuilt back on the inbound path — **no flag required**
+- Your `openclaw.inbound_meta.v1` namespace stripped at the proxy boundary so Anthropic's billing classifier doesn't flip you to extra-usage
+- `dario doctor --usage` showing the OpenClaw traffic in your 5-hour bucket with `claim=five_hour (subscription)`
+
+Total install + config: 5–10 minutes if dario is already installed.
+
+## Prerequisites
+
+| Thing | Version | Why |
+|---|---|---|
+| **OpenClaw** | 2026.2.17+ recommended | Older versions read auth differently — see auth-profiles gotcha below |
+| **dario** | v3.31.2+ (latest preferred — `npm i -g @askalf/dario@latest`) | Auth-mismatch reject log, structural-fallback tool detection, classifier-fingerprint protection |
+| **A Claude OAuth login** | run `dario login` once | The whole point — a Pro / Max subscription on a Claude account |
+| **Bun** (recommended) | 1.1+ | dario auto-relaunches under Bun for TLS-fingerprint fidelity. Skip if you're fine with a runtime banner; install via [bun.sh](https://bun.sh) for the full subscription wire shape. |
+
+Verify dario before starting OpenClaw — saves you from chasing OpenClaw errors that are actually dario auth issues:
+
+```bash
+dario doctor          # all green = ready
+dario status          # OAuth healthy, expires in N hours
+```
+
+If `dario status` shows expired or missing OAuth, run `dario login` and retry. Don't continue past this step until both are clean.
+
+## Install OpenClaw
+
+Follow the install instructions in [OpenClaw's own README](https://github.com/openclaw/openclaw) — installation steps move with their releases and we'd rather link the canonical source than copy-paste a snapshot that goes stale.
+
+Verify after install:
+
+```bash
+openclaw --version
+```
+
+The rest of this guide assumes a working `openclaw` CLI on your `PATH`.
+
+## Configure OpenClaw → dario
+
+OpenClaw reads its Anthropic configuration from three places, in priority order (2026.2.17+):
+
+1. `~/.openclaw/agents/main/agent/auth-profiles.json` — wins if the `anthropic:default` entry exists
+2. `openclaw.json` — `apiKey` field
+3. `ANTHROPIC_API_KEY` and `ANTHROPIC_BASE_URL` env vars — fallback
+
+**This priority order is the single most common source of "why doesn't dario see my requests" tickets** ([dario#97](https://github.com/askalf/dario/issues/97)). Read the next section carefully.
+
+### Step 1 — Set the env vars
+
+Put this in your shell profile (`~/.bashrc`, `~/.zshrc`, fish `config.fish`, or PowerShell `$PROFILE`):
+
+```bash
+export ANTHROPIC_BASE_URL=http://localhost:3456
+export ANTHROPIC_API_KEY=dario
+```
+
+Two things to know:
+
+- `ANTHROPIC_BASE_URL=http://localhost:3456` — points OpenClaw at dario instead of `api.anthropic.com`. dario speaks the Anthropic protocol on this port.
+- `ANTHROPIC_API_KEY=dario` — this string is a literal placeholder. dario doesn't validate it (the real auth lives in dario's stored OAuth token). If you're running dario with `DARIO_API_KEY` set (LAN/multi-host mode), use that value here instead.
+
+### Step 2 — Clear or overwrite the auth-profiles.json entry
+
+If you've ever set up OpenClaw with a real Anthropic API key, the env vars above won't take effect — `auth-profiles.json` wins. Pick one of two fixes:
+
+**Option A: delete the Anthropic entry from auth-profiles.json (preferred — confirmed working by [@tetsuco in dario#97](https://github.com/askalf/dario/issues/97))**
+
+Open `~/.openclaw/agents/main/agent/auth-profiles.json` in any editor, remove the `"anthropic:default"` entry (or the whole file if Anthropic is the only profile in there), save. OpenClaw falls back to the env vars on next run.
+
+**Option B: overwrite the auth-profiles.json entry with `dario`**
+
+```bash
+openclaw models auth paste-token --provider anthropic
+# When prompted, paste the literal string: dario
+```
+
+This replaces whatever was in the file with `dario`. Keep a backup if you use the original key elsewhere.
+
+> **Loopback escape hatch.** If you're running dario at `--host=127.0.0.1` (the default), you don't need `DARIO_API_KEY` set at all and the auth-profiles content matters less — dario only enforces auth on non-loopback binds. So if you can stay on loopback, do; the auth-profiles dance is only needed for LAN reach setups (Tailscale, multi-host).
+
+### Step 3 — Verify the config takes effect
+
+```bash
+echo "$ANTHROPIC_BASE_URL"
+# expected: http://localhost:3456
+```
+
+If that's empty, restart your shell or `source` your profile.
+
+### Battletested model choices
+
+OpenClaw exposes its model selection through its own config. We default to:
+
+| Model | When to use | Notes |
+|---|---|---|
+| `claude-sonnet-4-6` | **Default for everything.** | Best quality/speed for agent loops. What we run 95% of the time. |
+| `claude-opus-5` | Hard reasoning tasks, refactors, novel architecture | ~3× slower per turn, ~3× more tokens. Subscription absorbs the cost; your wall-clock pays. Worth it for one-shot heavy lifts, overkill for routine. |
+| `claude-haiku-4-5` | Fast scripts, quick lookups, smoke tests | Cheap on tokens, weak on multi-step reasoning. Don't run a long autonomous OpenClaw session on Haiku. |
+
+Set the model in OpenClaw's config (the field name varies by OpenClaw version — check `openclaw config --help`). Use the canonical Anthropic model ID (no provider prefix) — OpenClaw is already on the Anthropic protocol.
+
+## First run
+
+Start dario in one terminal:
+
+```bash
+dario proxy --verbose
+```
+
+Leave it running. You'll watch real-time request logs here.
+
+In a second terminal, run an OpenClaw task:
+
+```bash
+openclaw "Add a function to utils.py that takes a list of strings and returns them sorted by length, longest first. Include a docstring and a basic test."
+```
+
+(Exact invocation may differ by OpenClaw version — check `openclaw --help`. The above is the conceptual shape; substitute the right flags for your install.)
+
+Watch the dario terminal — you should see one log line per request, looking like:
+
+```
+[dario] #1 POST /v1/messages (model: claude-sonnet-4-6) → 200 (1843 ms)
+[dario] #2 POST /v1/messages (model: claude-sonnet-4-6) → 200 (2104 ms)
+...
+```
+
+If you see `→ 200` lines and OpenClaw is making progress, you're good. dario's `client: 'unknown-non-cc'` structural fallback is silently auto-translating OpenClaw's `exec` / `process` / `web_search` / `web_fetch` / `browser` / `message` tools to CC's canonical set on the outbound path and rebuilding the OpenClaw shape on the inbound path — no flag, no config.
+
+## Verifying subscription billing (the important part)
+
+This is what separates "OpenClaw talking to dario" from "OpenClaw actually using your Claude subscription." Two checks:
+
+### Check 1: dario doctor --usage
+
+```bash
+dario doctor --usage
+```
+
+You should see your 5-hour bucket showing non-zero usage with `claim=five_hour (subscription)`:
+
+```
+[ OK ]  Usage 5h (all)          12.3% used  •  status=allowed  •  claim=five_hour (subscription)
+```
+
+If `claim=five_hour (subscription)` shows up, you're billing against subscription, not API. Done.
+
+If `claim=api` shows up, something flipped you to per-token billing. The most common cause for OpenClaw users is the next section.
+
+### Check 2: Anthropic dashboard
+
+Log into [console.anthropic.com](https://console.anthropic.com) → Usage. **Your API spend should be flat** (no new charges since you started OpenClaw). If it's climbing, something is bypassing dario.
+
+## How dario protects you from the classifier filter
+
+Anthropic's billing classifier fingerprints the string `openclaw.inbound_meta.v1` and routes any request containing it to extra-usage billing — not subscription. This was reproduced in [dario discussion #178](https://github.com/askalf/dario/discussions/178) following Theo Browne's original finding.
+
+The filter triggers on the `openclaw.inbound_meta.v1` namespace appearing in the request body — which is easy to hit accidentally. If you've ever made a commit message or branch name containing that string in any of your repos, Claude Code's environment block (which CC adds to its prompt) will surface those names back to the model in the system prompt, and the classifier flips your request.
+
+**dario's default template-replay mode protects you from this automatically.** Every outbound request gets rebuilt from dario's captured-fresh CC system prompt — your local git context (commit messages, branch names, modified-file lists) is discarded at the proxy boundary. The `openclaw.inbound_meta.v1` string never leaves your machine.
+
+You don't need to do anything to get this protection — it's the default. The protection is validated by `scripts/research/test-dario-protects-openclaw.mjs` against real Anthropic upstream traffic.
+
+> **If you want to verify it on your own machine:** create a temp git repo with `{"schema": "openclaw.inbound_meta.v1"}` as a commit message, run OpenClaw against dario from inside that repo, and check `dario doctor --usage` — you should still see `claim=five_hour`. Without dario, the same setup would 400 or flip to api-billing.
+
+## Common gotchas
+
+### `401 Unauthorized` from dario, even though `ANTHROPIC_API_KEY=dario` is set
+
+This is the auth-profiles.json priority issue ([dario#97](https://github.com/askalf/dario/issues/97)). OpenClaw is reading a stale Anthropic key from `~/.openclaw/agents/main/agent/auth-profiles.json` instead of your env var. Run `dario proxy -v` to confirm — you'll see `Authorization present but value mismatch (header: x-api-key)` in the reject log. Fix with one of the three options in Step 2 above.
+
+### `Connection refused` to localhost:3456
+
+dario isn't running, or it's bound to a different port:
+
+```bash
+curl -s http://localhost:3456/health
+# expected: {"status":"ok",...}
+```
+
+If that fails, start dario (`dario proxy --verbose`). If it's running on a custom port, match it: `ANTHROPIC_BASE_URL=http://localhost:<port>`.
+
+### `claim=api` showing up in dario doctor --usage
+
+Something is sneaking the `openclaw.inbound_meta.v1` string past dario's template replay. The most common cause is running with `dario proxy --passthrough` (thin proxy, no template injection) — passthrough mode does an OAuth swap only and does NOT scrub the system prompt, so any classifier triggers in your local env survive. Drop the `--passthrough` flag and the default template-replay mode will protect you.
+
+If you actually need passthrough mode for some other reason, you'll need to clean your local git state — rename branches with `openclaw` in their names, rewrite commit messages with that string, and remove any files in your working tree that contain the classifier-fingerprint namespace.
+
+### Long sessions failing with rate limits
+
+If you run multiple parallel OpenClaw sessions on a single Claude account, you'll hit the 5-hour rate limit fast. Two fixes:
+
+1. **Add a second account to dario's pool** (`dario accounts add work` after running `dario login` on a second account). Pool mode routes each request to whichever account has the most headroom and uses session stickiness so multi-turn chats stay on one account. See [`docs/multi-account-pool.md`](./multi-account-pool.md).
+2. **Stagger the runs** — finish one before starting the next. Cheaper, no extra subscription needed.
+
+### Tools come back empty / wrong shape
+
+Symptom: OpenClaw's tool calls round-trip with stripped fields, or your runtime complains about a required field being absent only when routed through dario.
+
+If you see this, run dario with `--preserve-tools`:
+
+```bash
+dario proxy --preserve-tools
+```
+
+This skips the CC tool remap entirely and forwards OpenClaw's tool definitions through to the model unchanged. You lose the CC wire shape (and may lose subscription billing), but you keep all custom tool fields. Reserve for cases where the auto-detection can't reconstruct your schema cleanly.
+
+## What this guide doesn't cover
+
+- **OpenClaw's own internal config flags.** OpenClaw has a rich CLI with options for sandbox, project root, agent loop tuning, etc. We don't shadow them here; check `openclaw --help`. The dario integration is at the LLM layer; agent code doesn't need to change.
+- **OpenClaw derivatives** (forks like `openclaw-billing-proxy`, `nanoclaw`, etc.). These typically work the same way — point them at `localhost:3456` and dario's structural-fallback tool detection (the 3+ tools, ≥80% not in TOOL_MAP rule) catches them automatically. If a specific fork doesn't work, open an issue with the request body shape and we'll add explicit detection.
+
+## Quick reference card
+
+```bash
+# One-time setup
+# (install OpenClaw per its README)
+npm install -g @askalf/dario
+dario login
+
+# Per-session
+export ANTHROPIC_BASE_URL=http://localhost:3456
+export ANTHROPIC_API_KEY=dario
+# (clear ~/.openclaw/agents/main/agent/auth-profiles.json first if you have a stale Anthropic key)
+dario proxy --verbose &
+openclaw "your task here"
+
+# Verify subscription billing
+dario doctor --usage   # claim=five_hour (subscription) ✓
+```
+
+## Related guides
+
+- [`openhands-walkthrough.md`](./openhands-walkthrough.md) — sister walkthrough for OpenHands
+- [`agent-compat.md`](./agent-compat.md) — short setup snippets for every other agent dario supports
+- [`multi-account-pool.md`](./multi-account-pool.md) — adding 2+ Claude accounts to extend rate limits
+- [`commands.md`](./commands.md) — full dario CLI reference
+- [`faq.md`](./faq.md) — common dario questions, including the OpenClaw auth-profiles 401 entry
+- [`research/system-prompt-classifier-study.md`](./research/system-prompt-classifier-study.md) — empirical work on what the billing classifier reads (and doesn't)

package/docs/integrations/openhands-walkthrough.md

@@ -0,0 +1,255 @@
+# dario + OpenHands — battletested setup
+
+End-to-end walkthrough for running [OpenHands](https://github.com/All-Hands-AI/OpenHands) (the open-source software-engineer agent, formerly OpenDevin) through dario so it routes against your Claude Pro / Max subscription instead of paying per-token API rates. Covers install → config → first run → verification → the gotchas that bite first-time users.
+
+This is opinionated. There are several ways to wire OpenHands to dario; this is the one we run in production and trust to not surprise us. Where we omit options it's because they're worse, not because they don't exist.
+
+## What you'll have at the end
+
+- OpenHands running locally, talking to dario at `localhost:3456`
+- All Claude API calls routed through your Pro / Max subscription via the Claude Code wire shape
+- Multi-turn agent loops running on subscription billing, not per-token
+- `dario doctor --usage` showing the OpenHands traffic in your 5-hour bucket
+- A working `--task` invocation you can drop into a script
+
+Total install + config: 10–15 minutes if Python and dario are already installed.
+
+## Prerequisites
+
+| Thing | Version | Why |
+|---|---|---|
+| **Python** | 3.12+ | OpenHands' minimum |
+| **Poetry** or **pipx** | recent | OpenHands' install flow |
+| **dario** | v3.30+ (latest preferred — `npm i -g @askalf/dario@latest`) | OpenAI-compat endpoint plus the provider-prefix routing this guide leans on |
+| **A Claude OAuth login** | run `dario login` once | The whole point — a Pro / Max subscription on a Claude account |
+| **Bun** (recommended) | 1.1+ | dario auto-relaunches under Bun for TLS-fingerprint fidelity. Skip if you're fine with a runtime banner; install via [bun.sh](https://bun.sh) for the full subscription wire shape. |
+
+Verify dario before starting OpenHands install — saves you from chasing OpenHands errors that are actually dario auth issues:
+
+```bash
+dario doctor          # all green = ready
+dario status          # OAuth healthy, expires in N hours
+```
+
+If `dario status` shows expired or missing OAuth, run `dario login` and retry. Don't continue past this step until both are clean.
+
+## Install OpenHands
+
+The official path uses `pipx` for a clean install that doesn't fight your system Python:
+
+```bash
+pipx install openhands-ai
+```
+
+If you don't have pipx: `python -m pip install --user pipx && pipx ensurepath`, then start a new shell.
+
+Verify:
+
+```bash
+openhands --version
+```
+
+If you'd rather run from a clone (faster iteration on agent code, harder to keep updated):
+
+```bash
+git clone https://github.com/All-Hands-AI/OpenHands.git
+cd OpenHands
+poetry install
+```
+
+Both paths give you the `openhands` CLI. The rest of this guide assumes the pipx path.
+
+## Configure OpenHands → dario
+
+OpenHands reads config from environment variables and an optional `config.toml`. We use environment variables for everything because they're easier to swap when testing different Claude models or pool accounts.
+
+### The minimum working config
+
+Put this in your shell profile (`~/.bashrc`, `~/.zshrc`, `~/.config/fish/config.fish`, or PowerShell `$PROFILE`):
+
+```bash
+export LLM_BASE_URL=http://localhost:3456
+export LLM_API_KEY=dario
+export LLM_MODEL=anthropic/claude-sonnet-4-6
+```
+
+Three things to know about each line:
+
+- `LLM_BASE_URL=http://localhost:3456` — points OpenHands at dario instead of `api.anthropic.com`. dario speaks both Anthropic and OpenAI protocols on this port; OpenHands picks Anthropic because of the model name in the next line.
+- `LLM_API_KEY=dario` — this string is a literal placeholder. dario doesn't validate it; the real auth lives in dario's stored OAuth token. Putting a dummy value here is intentional. If you're running dario with `DARIO_API_KEY` set (LAN/multi-host mode), use that value here instead.
+- `LLM_MODEL=anthropic/claude-sonnet-4-6` — the `anthropic/` prefix tells LiteLLM (OpenHands' inner routing layer) "use the Anthropic protocol" — that's what makes OpenHands hit dario's `/v1/messages` endpoint instead of `/v1/chat/completions`. Without the prefix, LiteLLM defaults to OpenAI shape and dario will translate it but you lose subscription-billing fidelity. **Always use the `anthropic/` prefix.**
+
+### Battletested model choices
+
+| Model | When to use | Notes |
+|---|---|---|
+| `anthropic/claude-sonnet-4-6` | **Default for everything.** | Best quality/speed for agent loops. What we run 95% of the time. |
+| `anthropic/claude-opus-5` | Hard reasoning tasks, refactors, novel architecture | ~3× slower per turn, ~3× more tokens. Subscription absorbs the cost; your wall-clock pays. Worth it for one-shot heavy lifts, overkill for routine. |
+| `anthropic/claude-haiku-4-5` | Fast scripts, quick lookups, smoke tests | Cheap on tokens, weak on multi-step reasoning. Don't run a multi-hour agent loop on Haiku. |
+
+We do **not** recommend mixing models inside a single OpenHands run via the `LLM_DRAFT_MODEL` setting — the runtime overhead of switching wire shapes mid-conversation costs more than the smaller-model savings.
+
+### Optional but useful
+
+```bash
+# Maximum tokens per response (default is conservative)
+export LLM_MAX_OUTPUT_TOKENS=8192
+
+# Cap input context to stay safely under Anthropic's per-model ceiling.
+# Sonnet 4.6 supports 200k natively; OpenHands defaults to 128k. Leave at default
+# unless you've seen 'context too long' errors during long sessions.
+# export LLM_MAX_INPUT_TOKENS=128000
+
+# Temperature — keep low for code agents.
+export LLM_TEMPERATURE=0.0
+```
+
+### Verifying the config loads
+
+```bash
+echo "$LLM_BASE_URL $LLM_MODEL"
+# expected: http://localhost:3456 anthropic/claude-sonnet-4-6
+```
+
+If those don't print, the env vars didn't load — restart your shell or `source` your profile.
+
+## First run
+
+Start dario in one terminal:
+
+```bash
+dario proxy --verbose
+```
+
+Leave it running. You'll watch real-time request logs here.
+
+In a second terminal, run an OpenHands task:
+
+```bash
+openhands --task "Add a function to utils.py that takes a list of strings and returns them sorted by length, longest first. Include a docstring and a basic test."
+```
+
+OpenHands will:
+
+1. Spin up its workspace
+2. Ask Claude (via dario) what to do
+3. Execute file edits, run tests, and iterate
+
+Watch the dario terminal — you should see one log line per request, looking like:
+
+```
+[dario] #1 POST /v1/messages (model: claude-sonnet-4-6) → 200 (1843 ms)
+[dario] #2 POST /v1/messages (model: claude-sonnet-4-6) → 200 (2104 ms)
+...
+```
+
+If you see `→ 200` lines and OpenHands is making progress, you're good.
+
+## Verifying subscription billing (the important part)
+
+This is what separates "OpenHands talking to dario" from "OpenHands actually using your Claude subscription." Two checks:
+
+### Check 1: dario doctor --usage
+
+```bash
+dario doctor --usage
+```
+
+You should see your 5-hour bucket showing non-zero usage with `claim=five_hour (subscription)`:
+
+```
+[ OK ]  Usage 5h (all)          12.3% used  •  status=allowed  •  claim=five_hour (subscription)
+```
+
+If `claim=five_hour (subscription)` shows up, you're billing against subscription, not API. Done.
+
+If `claim=api` shows up, something flipped you to per-token billing — usually the model name is wrong (missing `anthropic/` prefix) or you set `DARIO_API_KEY` and OpenHands didn't pass it correctly.
+
+### Check 2: Anthropic dashboard
+
+Log into [console.anthropic.com](https://console.anthropic.com) → Usage. **Your API spend should be flat** (no new charges since you started OpenHands). If it's climbing, something is bypassing dario.
+
+## Common gotchas
+
+### `Error: model not found: anthropic/claude-sonnet-4-6`
+
+LiteLLM's local model registry is out of date. Two options:
+
+- Upgrade OpenHands: `pipx upgrade openhands-ai`
+- OR set the model without the `anthropic/` prefix and let dario's `claude-*` regex catch it: `LLM_MODEL=claude-sonnet-4-6`. This loses some LiteLLM routing intelligence but works. You may also use dario's provider-prefix syntax: `LLM_MODEL=claude:claude-sonnet-4-6`.
+
+### `Connection refused` to localhost:3456
+
+dario isn't running, or it's bound to a different port:
+
+```bash
+curl -s http://localhost:3456/health
+# expected: {"status":"ok",...}
+```
+
+If that fails, start dario (`dario proxy --verbose`). If it's running but on a custom port, match it: `LLM_BASE_URL=http://localhost:<port>`.
+
+### OpenHands hangs at "thinking..." for >60 seconds, then times out
+
+dario's outbound timeout to Anthropic is 5 min by default; if OpenHands gives up sooner, set its retry config:
+
+```bash
+export LLM_NUM_RETRIES=3
+export LLM_RETRY_MIN_WAIT=2
+export LLM_RETRY_MAX_WAIT=60
+```
+
+This makes OpenHands more patient. Anthropic occasionally serves slow first-token latency on subscription traffic; the retry layer absorbs it cleanly.
+
+### Long sessions fail with `context_length_exceeded`
+
+OpenHands' context manager doesn't always trim aggressively enough. If a session runs hot, set:
+
+```bash
+export LLM_MAX_INPUT_TOKENS=180000   # Sonnet 4.6 native ceiling minus headroom
+```
+
+For very long autonomous runs, switch the agent to `--config-file` mode and enable OpenHands' context-condensation feature explicitly. The TOML config has more knobs than the env vars expose.
+
+### Multiple OpenHands sessions starve a single Claude account
+
+If you run two or more parallel OpenHands sessions, you'll hit the 5-hour rate limit fast. Two fixes:
+
+1. **Add a second account to dario's pool** (`dario accounts add work` after running `dario login` on a second account). Pool mode routes each request to whichever account has the most headroom and uses session stickiness so multi-turn chats stay on one account. See [`docs/multi-account-pool.md`](./multi-account-pool.md).
+2. **Stagger the runs** — finish one before starting the next. Cheaper, no extra subscription needed.
+
+### "Claim flipped to api during a session"
+
+Anthropic's billing classifier occasionally rejects subscription traffic if the request body fingerprint drifts. dario captures CC's exact wire shape weekly and pins it; if you see this happen, run `dario doctor` first — it'll show whether your CC version is current. If `template: live capture, CC vX.Y.Z (Nh old)` is more than 48 hours old, do `dario doctor --bun-bootstrap` to force a fresh capture.
+
+## What this guide doesn't cover
+
+- **OpenHands web UI** (`openhands serve`). Same env vars work; the walkthrough above is TUI/CLI-focused because that's where battletesting time has gone. The web UI works but we don't run it routinely.
+- **Custom OpenHands agents.** Subclassing `Agent` to write your own controller is supported but out of scope here. The dario integration is at the LLM layer; agent code doesn't need to change.
+- **Sandbox configuration.** OpenHands runs commands in Docker by default. dario doesn't care which sandbox you use; pick whichever your security model requires.
+
+## Quick reference card
+
+```bash
+# One-time setup
+pipx install openhands-ai
+npm install -g @askalf/dario
+dario login
+
+# Per-session
+export LLM_BASE_URL=http://localhost:3456
+export LLM_API_KEY=dario
+export LLM_MODEL=anthropic/claude-sonnet-4-6
+dario proxy --verbose &
+openhands --task "your task here"
+
+# Verify subscription billing
+dario doctor --usage   # claim=five_hour (subscription) ✓
+```
+
+## Related guides
+
+- [`agent-compat.md`](./agent-compat.md) — short setup snippets for every other agent dario supports (Cursor, Continue, Aider, Cline, Zed, GitHub Copilot, etc.)
+- [`multi-account-pool.md`](./multi-account-pool.md) — adding 2+ Claude accounts to extend rate limits
+- [`commands.md`](./commands.md) — full dario CLI reference
+- [`faq.md`](./faq.md) — common dario questions independent of which agent you're running

package/docs/mcp-server.md

@@ -0,0 +1,22 @@
+# dario as MCP server (v3.27)
+
+`dario mcp` turns dario itself into a **stdio JSON-RPC 2.0 MCP server**. Claude Desktop, Cursor, Zed, any MCP-aware editor can introspect dario's state without leaving the editor.
+
+```bash
+dario mcp        # spawns the MCP server on stdin/stdout — wire it up to your MCP client
+```
+
+**Strictly read-only.** The exposed tool set is:
+
+| Tool | What it reports |
+|---|---|
+| `doctor` | Full aggregated health report — same output as `dario doctor` |
+| `status` | OAuth authentication state (authenticated / no-credentials / expired-but-refreshable) |
+| `accounts_list` | Pool accounts + expiry times. Never touches API keys. |
+| `backends_list` | Configured OpenAI-compat backends — keys redacted completely (not even a `sk-…` prefix) |
+| `subagent_status` | CC sub-agent install and version-match state |
+| `fingerprint_info` | Runtime / TLS classification, template source + schema version |
+
+Mutations (`login`, `logout`, `accounts add/remove`, `backend add/remove`, `subagent install/remove`, `proxy` start/stop) are **not** exposed. An MCP client can observe dario; changing dario's state stays a CLI action the user types with intent. The test suite asserts the forbidden-tool set stays forbidden so a future accidental drift gets caught.
+
+Zero runtime deps — the JSON-RPC dispatcher is hand-rolled over Node's `readline`. `src/mcp/protocol.ts` + `src/mcp/tools.ts` + `src/mcp/server.ts` are each pure over their inputs (streams are injectable, data sources are injectable) so the e2e test runs in-process against a `PassThrough` pair.

package/docs/multi-account-pool.md

@@ -0,0 +1,68 @@
+# The account pool
+
+As of v5.0 the account pool is dario's one credential model. A plain `dario login` is a **pool of one** (materialized as `~/.dario/accounts/login.json` under the reserved `login` alias); adding accounts just makes it a pool of many. There's no separate single-account mode — a pool of one and a pool of many run the identical request path.
+
+```bash
+dario login                     # a pool of one
+dario accounts add work         # now a pool of two
+dario accounts add personal
+dario accounts list
+dario proxy
+```
+
+Your `dario login` credentials materialize into the pool automatically — on `dario login` itself, and again on `dario proxy` startup as a safety net. `~/.dario/credentials.json` is left in place; the back-fill is a one-way copy, never a move. If you run `dario accounts add <alias>` on top of a login-only setup, the `login` account is already in the pool, so you simply gain the new alias alongside it. Picking `login` as an explicit alias is your call — dario won't clobber it.
+
+Each request picks the account with the highest headroom:
+
+```
+headroom = 1 - max(util_5h, util_7d)
+```
+
+The response's `anthropic-ratelimit-unified-*` headers are parsed back into the pool so the next selection sees fresh utilization. An account that returns a 429 is marked `rejected` and routed around until its window resets. When every account is exhausted, requests queue for up to 60 seconds waiting for headroom to reappear. Plan tiers mix freely in the same pool — dario doesn't care about tier, only headroom.
+
+## Routing strategy
+
+Headroom spreading is the default and stays the right call when every seat is equal. `--pool-strategy=fill-first` (env `DARIO_POOL_STRATEGY`, config `pool.strategy`) flips to concentration: new conversations land on the **alphabetically-first** eligible seat until its headroom drains to the 2% floor, then spill to the next alias in line. Failover follows the same order — after a 429 the retry goes to the next alias, not the max-headroom seat.
+
+Two situations where that beats spreading:
+
+- **Primary/backup seats.** A `z-backup` account stays completely untouched — fresh 5h and 7d windows — until `a-main` is actually drained. Headroom spreading would nibble at both from the first request.
+- **Cache concentration.** Every fresh conversation lands where the prompt-cache pressure already is, so the spill seat's windows are fully fresh when the primary hits its wall.
+
+Alias order is the operator's knob: name seats `1-main` / `2-overflow` to pick the fill order. Strategy only decides where **unbound** conversations land — sticky bindings (below) behave identically in both modes, and a conversation bound to a seat stays there until that seat is rejected, expiring, or under the floor.
+
+## Session stickiness
+
+Multi-turn agent sessions pin to one account for the life of the conversation, so the Anthropic prompt cache isn't destroyed by account rotation between turns.
+
+**The problem.** Claude prompt cache is scoped to `{account × cache_control key}`. When the pool rotates a long agent conversation across accounts on headroom alone, turn 1 builds a cache entry on account A, turn 2 lands on account B and reads nothing from A's cache — paying full cache-create cost again. For a long agent session that's a **5–10× token-cost multiplier** on every turn after the first.
+
+**The fix.** Dario hashes a conversation's first user message into a 16-hex-char `stickyKey` (SHA-256 truncated, deterministic) and binds the key to whichever account `select()` would have picked on turn 1. Subsequent turns re-use that account as long as it's still healthy (not rejected, token not near expiry, headroom > 2%). On 429 failover, dario rebinds the key to the new account so the next turn doesn't re-select the exhausted one. 6h TTL, 2,000-entry cap, lazy cleanup. No client cooperation required.
+
+## Pool-exhausted fallback
+
+`--pool-fallback=<model>` (env `DARIO_POOL_FALLBACK`, config `poolFallback.model`) is a strictly opt-in escape hatch for when the whole pool is drained or cooling. With it set **and** an openai-compat backend configured (`dario backend add …`), an OpenAI-shape request (`/v1/chat/completions`) that the pool can't serve — at selection time, or after a mid-flight 429 with no peer left — is forwarded to that backend with the model swapped to `<model>`, instead of returning the 429/503.
+
+Three deliberate limits:
+
+- **OpenAI-shape only.** Anthropic-shape requests (`/v1/messages`) keep the error. dario translates Anthropic→OpenAI on the way out but has no OpenAI→Anthropic *response* translator, so a fallback there would corrupt the client's stream. Point Anthropic-native clients that want this at `/v1/chat/completions`, or leave the fallback off.
+- **Never silent.** Every substituted response carries `x-dario-pool-fallback: <model>`. A quietly swapped model is exactly the surprise this project exists to avoid — check for the header if you need to know which requests fell back.
+- **Empty pool still errors.** A pool with zero accounts is a setup mistake (`dario login` never ran); that returns the usual 503 rather than silently re-billing every request to another provider.
+
+```bash
+dario backend add openrouter --key=sk-or-... --base-url=https://openrouter.ai/api/v1
+dario proxy --pool-fallback=openrouter/anthropic/claude-3.5-sonnet
+```
+
+## In-flight 429 failover
+
+When a Claude request hits a 429 mid-flight, dario retries the *same request* against a different account before the client sees an error. The client sees one successful response; the pool sees the rejected account go cold until its window resets. Combined with session stickiness, long agent runs survive pool-level exhaustion without dropping user-facing turns.
+
+## Inspection
+
+```bash
+curl http://localhost:3456/accounts     # per-account utilization, claim, sticky bindings, status
+curl http://localhost:3456/analytics    # per-account / per-model stats, burn rate, exhaustion predictions
+```
+
+Every request carries a `billingBucket` field (`subscription` / `subscription_fallback` / `extra_usage` / `api` / `unknown`) so you can see which bucket each request billed against and a `subscriptionPercent` headline number tells you at a glance whether dario is actually routing through your subscription or silently falling to API overage.