@pentoshi/clai 4.11.18 → 4.11.20

package/README.md

@@ -2,27 +2,27 @@
 
 > A fast, terminal-native AI agent that runs real tools — built to run on **free API tiers**, stay alive across rate limits with **multi-key + multi-provider switching**, and do serious work: **building, debugging, and scope-based pentesting / bug bounty**.
 
-`clai` is an agentic CLI. It doesn't just describe what to do — it edits files, runs shell commands, scans hosts, fetches HTTP evidence, keeps a durable task plan, and verifies its own work before claiming success. It runs in your terminal with three full surfaces — an OpenTUI full-screen console (default on macOS/Linux), a classic Ink UI (default on Windows), and a noninteractive stream renderer for prompts and pipes. The original line-by-line REPL is gone: every interactive surface is a full-screen app sharing the same features, commands, and session state.
+`clai` is an agentic CLI. It doesn't just describe what to do — it edits files, runs shell commands, scans hosts, fetches HTTP evidence, keeps a durable task plan, and verifies its own work before claiming success. It runs in your terminal with three full surfaces — an OpenTUI full-screen console (default on macOS/Linux), a classic Ink UI (default on Windows), and a noninteractive stream renderer for prompts and pipes. Every interactive surface is a full-screen app sharing the same features, commands, and session state.
 
 Two things make it practical for everyday use:
 
-- **It's cheap-to-free to run.** A fresh install runs **keyless out of the box** on the built-in Free provider — no signup, no API key. Point it at Google Gemini, NVIDIA NIM, OpenRouter, Bynara, Hetzner, or a local Ollama — all have free access — and clai stacks them. Add several keys per provider; when one hits a rate limit, it rotates to the next automatically. Want frontier models instead? Serve **Kimi K3 on your own Modal endpoint** on Modal's **$30/month of free credit**, or start on **Lightning AI's 40M free tokens**.
+- **It's cheap-to-free to run.** A fresh install runs **keyless out of the box** on the built-in Free provider — no signup, no API key. Point it at DeepSeek, Kimi, GLM, MiniMax, Gemini, NVIDIA NIM, OpenRouter, OpenAI, Anthropic, or run completely offline with local Ollama. Add multiple keys per provider; when one hits a rate limit, it rotates to the next automatically.
 - **It's honest.** Findings need real tool output. Builds get typechecked/run before "done." Compaction and history keep long sessions coherent instead of hallucinating progress.
 
 ---
 
 ## Highlights
 
-- **Free-tier first.** 19 providers wired in, 6 cloud free tiers + local Ollama. The default provider is the **keyless Free** gateway (`free-2/kilo-auto/free`) so a fresh install runs at no cost with zero setup — no API key required.
-- **Multi-key smart switching.** Up to 10 keys per provider with a *sticky* active key and circular rotation on rate-limit / auth / quota / transient / 5xx / empty-response errors. Disable any key or endpoint row to skip it without deleting it. Optional cross-provider fallback and a free-only filter.
-- **Bring your own endpoint.** Deploy Kimi K3 (or Qwen / DeepSeek / GLM / GPT-OSS / your own fine-tune) to a [Modal](#modal--run-kimi-k3-on-your-own-endpoint-on-30month-of-free-credit) endpoint and drive it from clai on **$30/month of free compute credit**. Modal, Lightning AI and TokenRouter each keep a list of up to 10 base URLs with a sticky active one, so several deployments live side by side and you switch with one command — same editor, same ★ active row as keys.
+- **Free-tier first.** Built-in **keyless Free** gateway (`free-2/kilo-auto/free`) so a fresh install runs at no cost with zero setup — no API key required.
+- **Multi-key smart switching.** Up to 10 keys per provider with a *sticky* active key and circular rotation on rate-limit, quota, transient, or 5xx errors. Disable any key to skip it without deleting it. Optional cross-provider fallback and a free-only filter.
+- **Broad provider support.** Native support for DeepSeek, Kimi (Moonshot), GLM (Zhipu AI), MiniMax, OpenAI, Anthropic, Google Gemini, Ollama, NVIDIA NIM, OpenRouter, Qwen, and custom OpenAI-compatible endpoints.
 - **Scope-based pentesting.** Opt-in engagement scope with authorized/excluded targets, allowed phases, rate and concurrency ceilings, redirect and DNS-rebinding escape detection, and out-of-scope flagging — designed for authorized pentests and bug-bounty programs.
 - **Real building & debugging.** Scaffolds apps, edits code surgically, installs packages, runs builds/tests, starts dev servers as background jobs, and probes them before reporting success.
 - **Durable plans.** `plan.create` / `task.update` drive a live checklist that survives context compaction and reloads with `/history` — the agent works task-by-task and won't fake completion.
-- **Durable agent sessions.** Interactive sessions run behind an authenticated local PTY broker, so an agent keeps working after `/minimise`, an SSH disconnect, or switching to another history session; `clai --resume <id>` reattaches to the same live UI and output stream.
-- **Persistent interactive terminals.** Conversation-owned PTY or pipe sessions keep REPLs such as Python, Metasploit, Meterpreter, database consoles, and debuggers open across model turns. The agent can send follow-up input, read incremental output, resize, interrupt, and close them without losing state.
+- **Durable agent sessions.** Interactive sessions run behind a local broker, so an agent keeps working after `/minimise`, an SSH disconnect, or switching to another history session; `clai --resume <id>` reattaches to the same live UI and output stream.
+- **Persistent interactive terminals.** Conversation-owned PTY or pipe sessions keep REPLs such as Python, Metasploit, Meterpreter, database consoles, and debuggers open across model turns.
 - **Native + text tool calling.** Uses provider-native function calling where available, with a text-fence fallback (`toolCalling: auto|native|text`).
-- **MCP, explicitly controlled.** Discovers local stdio and remote HTTP/SSE servers from project and compatible inherited configs. MCP tools are off by default; `/mcp` inspects and adds servers, and picking one drops an editable `@mcp:<server>` token into your prompt — stack as many as you need, delete one with backspace, or switch the whole session on with `/mcp all`.
+- **MCP, explicitly controlled.** Discovers local stdio and remote HTTP/SSE servers from project configs. MCP tools are off by default; `/mcp` inspects and adds servers, and picking one drops an editable `@mcp:<server>` token into your prompt.
 - **Safety gate you control.** Every action is classified safe / confirm / block; deletes always confirm with a preview; destructive patterns are blocked.
 
 ---
@@ -58,112 +58,29 @@ cd clai && npm install && npm run build && npm start
 
 Node.js ≥ 22. Type `clai` in any terminal to start.
 
-### Platform notes
-
-| Environment | Default surface | Explicit alternative |
-|---|---|---|
-| Interactive macOS/Linux terminal at least 60×14 | OpenTUI full-screen console | `clai --classic` for the Ink UI |
-| Interactive Windows terminal | Classic Ink UI | `--ui classic` / `--classic` |
-| stdin or stdout is not a TTY | Noninteractive stream renderer | use a prompt or pipe stdin |
-
-**Windows:** the platform-selection code chooses the classic Ink UI before any Bun/OpenTUI
-startup probe. This repository's macOS validation does not claim Windows Terminal,
-PowerShell, cmd.exe/conhost, VS Code terminal, ConPTY, or Windows-binary runtime evidence;
-those target-host checks remain release gates. Use `clai --classic` explicitly when you want
-the same selection on any platform.
-
-**Linux — terminal recommendations for full mouse & hover support:**
-
-The full-screen TUI uses mouse tracking and hover events via OpenTUI's Zig FFI renderer. Not all Linux terminal emulators report these correctly. If you see missing hover highlights, broken scroll, or no mouse response:
-
-| Terminal | Mouse/Hover | Notes |
-|----------|-------------|-------|
-| **Kitty** | ✅ Full | Recommended — fastest GPU-rendered terminal, full mouse protocol support |
-| **Alacritty** | ✅ Full | GPU-accelerated, excellent mouse support |
-| **WezTerm** | ✅ Full | Cross-platform, great defaults |
-| **iTerm2** (macOS) | ✅ Full | Native macOS, full mouse + hover |
-| **macOS Terminal** | ✅ Full | Works out of the box |
-| **GNOME Terminal** | ⚠️ Partial | Mouse clicks work; hover/SGR mouse mode may be limited |
-| **Konsole** | ⚠️ Partial | Some hover events may not report |
-| **xterm** | ⚠️ Partial | Needs `xterm -xrm 'XTerm*allowMouseOps: true'` |
-| **Linux TTY** (bare `/dev/tty`) | ❌ None | No mouse support; use `clai --classic` |
-| **tmux / screen** | ⚠️ Varies | Add `set -g mouse on` to `~/.tmux.conf`; passthrough depends on the outer terminal |
-
-> **Tip:** For the best experience on Linux, use **Kitty**, **Alacritty**, or **WezTerm**. These support SGR extended mouse reporting, which is what OpenTUI requires for hover, click, and scroll events. If your terminal doesn't support hover, clai still works — you just won't see hover highlights on buttons and links.
->
-> For tmux users: `set -g mouse on` enables mouse passthrough, but hover quality depends on the outer terminal emulator.
+> **Tip for Linux users:** For the best mouse and hover support in the full-screen TUI, modern GPU-rendered terminals like **Kitty**, **Alacritty**, or **WezTerm** are recommended. On macOS, **iTerm2** and the default Terminal work out of the box.
 
 ---
 
-## Fast downloads (Cloudflare R2 mirror)
-
-Release binaries are mirrored to a **Cloudflare R2** bucket served through Cloudflare's global CDN — significantly faster than GitHub's release hosting in most regions, and free for this project's traffic (R2 has **zero egress fees**).
-
-Mirror layout at `https://downloads.clai.aniketpandey.website`:
-
-| Path | Contents |
-|---|---|
-| `/vX.Y.Z/` | Binaries + `.sha256` sidecars for release vX.Y.Z (latest release only — see retention) |
-| `/latest/` | Same files, refreshed on every release |
-| `/install/` | `install.sh` / `install.ps1` used by the one-liners above |
-| `/version.json` | Latest released version (update-check fallback) |
-
-**Retention.** R2's free tier covers 10 GB and a single release is roughly 650 MB across six
-platforms, so the mirror keeps only the newest release: after the new binaries are uploaded
-*and* re-verified byte-for-byte through the public URL, superseded `vX.Y.Z/` prefixes are
-purged. `/latest/`, `/install/` and `/version.json` are always retained. Set the repo variable
-`R2_KEEP_RELEASES` to keep more than one version (default `1`). Pruning never runs unless the
-new release verified successfully, and a failed purge only warns — it can never fail a release.
-GitHub Releases keeps every version permanently, so older downloads still work through the
-automatic fallback; only the CDN acceleration is lost for them.
-
-**Security model:** installers and `clai update` try the R2 mirror first for speed and fall back to GitHub Releases automatically. The SHA256 checksum is fetched from GitHub Releases (falling back to the mirror) and verified locally before anything is installed — the trust anchor stays with GitHub, so a bad mirror can only slow you down, never feed you tampered bytes. `CLAI_SKIP_CHECKSUM=1` still bypasses verification, at your own risk. If the mirror is unreachable but raw.githubusercontent.com works, grab the installer from `https://raw.githubusercontent.com/pentoshi007/clai/main/install/` instead — it makes the same mirror-first/fallback choices when it runs.
-
-User knobs:
-
-```sh
-CLAI_DOWNLOAD_BASE=https://your-mirror.example
-CLAI_NO_MIRROR=1
-```
-
-### Maintainer setup (one-time, ~10 minutes)
-
-1. **Create the bucket.** Cloudflare dashboard → R2 → Create bucket, e.g. `clai-releases`. Any location hint works.
-2. **Make it publicly readable.** Bucket → Settings → Public access:
-   - **Option A — `r2.dev` (zero DNS config):** enable the managed "r2.dev URL" → you get `https://pub-<hash>.r2.dev`.
-   - **Option B — custom domain (the default everywhere in this repo):** add `downloads.clai.aniketpandey.website` as a custom domain (requires the zone's DNS on Cloudflare). Free SSL, and eligible for the edge cache once the cache rule in step 7 is in place.
-   If you end up on a different hostname, update `DEFAULT_MIRROR_BASE` in `src/commands/update-install.ts`, the default base in `install/install.sh` and `install/install.ps1`, and the URLs in `manifests/` — or export `CLAI_DOWNLOAD_BASE` until a release ships the change.
-3. **Create an API token.** R2 → Manage R2 API Tokens → Create API token: permission **Object Read & Write**, scoped to the `clai-releases` bucket only. Keep the **Access Key ID**, **Secret Access Key**, and the **Account ID** shown on the token page.
-4. **Add repo secrets** (GitHub repo → Settings → Secrets and variables → Actions → Secrets): `R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `R2_BUCKET_NAME`.
-5. **Add repo variable** (Variables tab): `R2_PUBLIC_URL` = your public base URL, e.g. `https://downloads.clai.aniketpandey.website`, no trailing slash.
-6. **Done.** On every `v*.*.*` tag, the `publish-r2` job in `.github/workflows/release.yml` uploads binaries + checksums to `/vX.Y.Z/` and `/latest/`, refreshes `/install/` and `/version.json`, re-downloads every asset through the public URL to re-verify its SHA256 against the sidecars, then purges superseded `vX.Y.Z/` prefixes. Missing secrets → the job skips without failing the release; missing `R2_PUBLIC_URL` → the public-URL verification is skipped and, because nothing was verified, pruning is skipped too. The `/version.json` write is advisory: if the token cannot write bucket-root objects the job warns and mirrors the manifest to `/latest/version.json` instead, since update checks already fall back to GitHub Releases.
-
-7. **Turn on edge caching (one cache rule).** Release binaries have no file extension, and Cloudflare's default cache only covers known static extensions — so without a rule every download is served from R2 origin and `cf-cache-status` stays `DYNAMIC`. Add a Cache Rule (dashboard → Caching → Cache Rules) matching `Hostname eq downloads.clai.aniketpandey.website` with **Cache eligibility: Eligible for cache** and **Use origin cache-control: on**. The upload job already stamps the right `Cache-Control` on every object — `public, max-age=31536000, immutable` for `/vX.Y.Z/` (content-addressed by version, so it can never go stale), `max-age=300` for `/latest/` and `/install/`, and `max-age=60` for `/version.json`. Verify with `curl -sI <url> | grep cf-cache-status`: the second request for the same asset should report `HIT`.
-
-**Cost:** the R2 free tier covers 10 GB-months of storage, 1M Class A and 10M Class B operations per month, and egress is always free, so this stays $0 at clai's scale. With the cache rule in place repeat downloads are served from the edge and never reach R2, which also keeps Class B operations near zero.
-
----
-
-
 ## Quick start
 
-Out of the box, clai runs **keyless** on the built-in Free provider — no signup, no API key:
+Out of the box, `clai` runs **keyless** on the built-in Free provider — no signup, no API key:
 
 ```sh
 clai          # launch the full-screen agent console (already on the free provider)
 ```
 
-Prefer a different provider? Get a free key, add it, and go:
+Prefer a different provider? Set your key and start:
 
 ```sh
-# Add a free key (NVIDIA shown; Gemini/OpenRouter/Bynara/Hetzner work the same)
-clai set nvidia nvapi-your_key_here
-clai use nvidia
+# Add an API key (DeepSeek shown; Gemini, OpenAI, Anthropic, Kimi, etc. work the same)
+clai set deepseek sk-your_key_here
+clai use deepseek
 
 # Launch the full-screen agent console
 clai
 
-# Or one-shot from the shell
+# Or one-shot directly from the shell
 clai "explain what this repo does and find the entrypoint"
 clai --mode agent "add a /health endpoint to the Express app and run the tests"
 ```
@@ -175,237 +92,56 @@ clai set ollama --url http://localhost:11434
 clai use ollama
 ```
 
-Want a frontier open model on your own hardware budget? Deploy **Kimi K3** to a Modal endpoint and run it on Modal's **$30/month of free compute credit** — see [Modal](#modal--run-kimi-k3-on-your-own-endpoint-on-30month-of-free-credit).
-
 ---
 
-## Run it on free tiers (and keep it running)
-
-This is the core of clai's design: assemble capacity from free tiers, then survive rate limits automatically.
-
-### Supported providers
-
-| Provider | Default model | Tier | Env var |
-|----------|---------------|------|---------|
-| Free (keyless) | `free-2/kilo-auto/free` | Free · keyless | — (no key needed) |
-| NVIDIA NIM | `openai/gpt-oss-20b` | Free | `NVIDIA_API_KEY` |
-| Google Gemini | `gemini-3.5-flash` | Free | `GEMINI_API_KEY` |
-| OpenRouter | `meta-llama/llama-3.3-70b-instruct:free` | Free | `OPENROUTER_API_KEY` |
-| Bynara | `mimo-v2.5-free` | Free | `BYNARA_API_KEY` |
-| Ollama | `llama3.1:8b` | Local / free | `OLLAMA_HOST` |
-| OpenAI | `gpt-5.4-mini` | Paid | `OPENAI_API_KEY` |
-| Anthropic | `claude-3-5-haiku-latest` | Paid | `ANTHROPIC_API_KEY` |
-| AgentRouter | `claude-opus-4-6` | Paid | `AGENTROUTER_API_KEY` |
-| AWS Mantle | `anthropic.claude-haiku-4-5` | Paid | `ANTHROPIC_API_KEY` |
-| Qwen Cloud | `qwen3.7-plus` | Paid (DashScope) | `DASHSCOPE_API_KEY` |
-| Modal | `moonshotai/Kimi-K3` | Usage-based ($30/mo credit) | `MODAL_PROXY_TOKEN_ID` + `MODAL_PROXY_TOKEN_SECRET` |
-| Lightning AI | `openai/gpt-5` | Per token (40M free to start) | `LIGHTNING_API_KEY` |
-| TokenRouter | `moonshotai/kimi-k3` | Per token (prepaid) | `TOKENROUTER_API_KEY` |
-| Meta (Muse Spark) | `muse-spark-1.2` | Paid (per token) | `MODEL_API_KEY` |
-| Fireworks | `accounts/fireworks/models/kimi-k2p6` | Paid (per token) | `FIREWORKS_API_KEY` |
-| Hetzner | `Qwen/Qwen3.6-35B-A3B-FP8` | Free (experiment — no billing yet) | `HETZNER_API_KEY` |
-| OrcaRouter | `openai/gpt-4o-mini` | Paid (per token, zero markup) | `ORCAROUTER_API_KEY` |
-| Merge Gateway | `openai/gpt-5.2` | Paid (per token, free tier budget) | `MERGE_GATEWAY_API_KEY` |
-
-Several "paid" providers also expose limited free allowances — the tier label reflects what the default keys usually buy you. Flip `freeOnly` off to include paid providers in fallback.
-
-#### Free — keyless, zero setup
-
-clai's default provider needs **no account, no API key, and no config**. It bundles **two keyless gateways** under one provider, namespaced by source so overlapping model names never collide: `free-1/…` ids come from the primary gateway and `free-2/…` ids from the [Kilo gateway](https://api.kilo.ai/api/gateway). Both serve rotating catalogs of free OpenAI-compatible models — `free-2/kilo-auto/free` (default), `free-1/mimo-v2.5-free`, `free-1/hy3-free`, `free-1/x-preview-f-free`, `free-2/stepfun/step-3.7-flash:free`, `free-2/nvidia/nemotron-3-ultra-550b-a55b:free` — with SSE streaming, native tool calling, `/effort` reasoning levels, and `reasoning_content` thinking folded into the normal `/think` block.
-
-```sh
-clai                          # already on free — nothing to set up
-/model                        # live catalogs from both gateways, free-1/… + free-2/… (cached 1h)
-```
-
-- **Keyless by design.** Requests go out with no `Authorization` header; `/model` lists only the keyless models from each gateway, so premium ids stay hidden until you add a key.
-- **Two sources, one provider.** Pick `free-1/…` or `free-2/…` in `/model`; a bare id with no prefix routes to `free-1`. If one gateway is rate limited, switching to the other is one `/model` pick away.
-- **Optional key upgrades you.** `clai set free <key>` (or `FREE_API_KEY`) unlocks premium models on your account. Premium ids without a key fail fast with a clear 402-style message instead of a confusing upstream error.
-- **Best-effort tier.** The free sets rotate upstream and are capacity-constrained / rate limited — if a request fails, retry once. For dependable daily use, add a key for any other provider (`clai set <provider> <key>`, then `clai use <provider>`).
-
-#### Modal — run Kimi K3 on your own endpoint, on $30/month of free credit
+## Providers & Key Management
 
-[Modal Endpoints](https://modal.com/docs/guide/endpoints) deploy an open-weight model on your own serverless URL that speaks the OpenAI Chat Completions API. That's the cheapest route to a **frontier open model like Kimi K3** from clai: the Starter plan is $0/month and includes **$30 of compute credit every month** once a payment method is on file, endpoints scale to zero so idle time costs nothing, and billing is per-second compute rather than per token.
+### Supported Providers
 
-Kimi K3, start to finish:
+| Provider | Default Model | Tier | Environment Variable |
+|----------|---------------|------|----------------------|
+| **Free (keyless)** | `free-2/kilo-auto/free` | Free · Keyless | — (no key needed) |
+| **DeepSeek** | `deepseek-chat` | Paid / Usage | `DEEPSEEK_API_KEY` |
+| **Kimi (Moonshot)** | `moonshot-v1-auto` | Paid / Usage | `KIMI_API_KEY` / `MOONSHOT_API_KEY` |
+| **GLM (Zhipu AI)** | `glm-4-flash` | Free tier / Paid | `GLM_API_KEY` / `ZHIPU_API_KEY` |
+| **MiniMax** | `MiniMax-Text-01` | Paid / Usage | `MINIMAX_API_KEY` |
+| **Google Gemini** | `gemini-2.5-flash` | Free tier / Paid | `GEMINI_API_KEY` |
+| **NVIDIA NIM** | `openai/gpt-oss-20b` | Free tier | `NVIDIA_API_KEY` |
+| **OpenRouter** | `meta-llama/llama-3.3-70b-instruct:free` | Free / Paid | `OPENROUTER_API_KEY` |
+| **Ollama** | `llama3.1:8b` | Local / Free | `OLLAMA_HOST` |
+| **OpenAI** | `gpt-5.4-mini` | Paid | `OPENAI_API_KEY` |
+| **Anthropic** | `claude-3-5-haiku-latest` | Paid | `ANTHROPIC_API_KEY` |
+| **Qwen Cloud** | `qwen3.7-plus` | Paid (DashScope) | `DASHSCOPE_API_KEY` |
+| **Bynara** | `mimo-v2.5-free` | Free | `BYNARA_API_KEY` |
+| **Hetzner** | `Qwen/Qwen3.6-35B-A3B-FP8` | Free (experiment) | `HETZNER_API_KEY` |
 
-```sh
-pip install modal && modal setup                                 # once
-modal endpoint create --model moonshotai/Kimi-K3 --name kimi-k3  # prints an id + dashboard link
-modal endpoint list                                              # copy the endpoint URL from here
-modal workspace proxy-tokens create                              # wk-… id + ws-… secret (shown once)
-
-clai set modal --url <endpoint-url>     # e.g. https://ws--ep-kimi-k3-server.us-west.modal.direct
-clai set modal wk-yourTokenId:ws-yourTokenSecret
-clai use modal                          # model defaults to moonshotai/Kimi-K3
-```
+Model lists for all providers are fetched dynamically from their respective APIs. You can switch models anytime using `/model` or `clai model <name>`.
 
-The catalog also covers Qwen, DeepSeek, GLM, Gemma, GPT-OSS, Nemotron and your own fine-tunes — swap `--model` and deploy another endpoint. Two things differ from every other provider: the base URL belongs to your workspace, and auth is a [proxy token](https://modal.com/docs/guide/webhook-proxy-auth) *pair* sent as `Modal-Key` / `Modal-Secret` instead of a bearer key. Endpoints are authenticated by default, and proxy tokens (`wk-`/`ws-`) are not interchangeable with Modal API tokens (`ak-`/`as-`).
-
-Endpoints and token pairs are both multi-entry lists with a sticky active choice, up to 10 each:
+### Manage Keys
 
 ```sh
-clai set modal --url <a> --url <b>     # store two deployments; the last becomes active
-clai set modal --url <a>               # re-passing a known URL just activates it
-clai unset modal --url                 # clear the URLs, keep the token pairs
-clai keys                              # every URL listed, ★ marks the active one
-```
-
-Token pairs rotate on failure like any other provider's keys (the pair is stored as one `id:secret` string). Endpoints fail over alongside them: on a rate limit, workspace/auth mismatch, quota error, or 5xx, clai tries the next stored endpoint with the next key, and the ★ active endpoint sticks to the one that worked, so the next run starts on the healthy URL. `MODAL_BASE_URL` overrides the stored list entirely.
-
-From inside the console, `/provider modal` walks the same setup in two prompts — endpoint URL first (shown in full, since it isn't a secret), then the token pair — and leaves the active provider untouched if you cancel.
-
-Sticky sessions are on by default — clai sends a stable `Modal-Session-ID` for each conversation, with separate IDs for each subagent and auxiliary request stream. `MODAL_SESSION_ID` optionally seeds those IDs; it does not collapse active agents onto one shared ID. Standalone requests without a conversation use the configured ID directly, or a generated process-local ID. Sticky routing helps preserve warm caches, but does not guarantee a cache hit. The first request after idle still pays container start-up, so clai allows up to 3 minutes for the first token.
-
-`/info modal` prints the whole thing as a walkthrough: numbered setup steps, which credentials go where, the plan limits (Starter also caps you at 3 seats, 100 containers and 10 GPUs of concurrency), and a troubleshooting table.
-
-#### Lightning AI (one key, many vendors)
-
-[Lightning AI Model APIs](https://lightning.ai/docs/platform/inference/model-apis) are an OpenAI-compatible gateway in front of OpenAI, Anthropic, Google and Lightning-hosted open models — one key, billed per token, with **up to 40 million free tokens to start**. Model ids are vendor-namespaced.
-
-```sh
-clai set lightning <your-api-key>      # key: lightning.ai → Model APIs → show API key
-clai use lightning
-/model openai/gpt-5                    # or anthropic/claude-opus-4-8, google/gemini-3.5-flash,
-                                       #    lightning-ai/gpt-oss-120b (cheapest open weights)
-```
-
-`/model` reads the gateway's live catalog (41 ids at last check) and dedupes it. Keys are multi-key with rotation like everywhere else. The base URL defaults to the shared gateway but is overridable the same way as Modal's — point it at a private Lightning Inference deployment with `clai set lightning --url <url>`, or `LIGHTNING_BASE_URL`. Costs vary by orders of magnitude across the catalog, so check `/info lightning` before long agent runs.
-
-#### TokenRouter (frontier open models, one key)
-
-[TokenRouter](https://docs.tokenrouter.me) is an OpenAI-compatible gateway to Kimi, DeepSeek, Qwen, GLM, GPT-OSS and MiniMax — long-context open models aimed at agentic coding, billed per token from a prepaid balance.
-
-```sh
-clai set tokenrouter sk-your-key        # key: your account → API Keys
-clai use tokenrouter                    # model defaults to moonshotai/kimi-k3
-/model deepseek/deepseek-v4-pro         # 1M context · or moonshotai/kimi-k2.7-code, z-ai/glm-5.1, MiniMax-M3
-```
-
-Model ids are vendor-namespaced (`moonshotai/kimi-k2.6`, `deepseek/deepseek-v4-pro`, `qwen/qwen3.7-plus`); the old short ids (`kimi-k2p6`, `glm-5p1`, …) are still accepted and silently redirected to the current namespaced id. `/model` reads the live `/models` list, which is filtered to the channels your key can reach. clai carries the real per-model context windows — 1M for DeepSeek V4, 512K for MiniMax M3, 256K for Kimi/Qwen, 200K for GLM — so the context meter and auto-compaction are accurate instead of guessing 128K. Reasoning arrives as `reasoning_content` and is folded into the normal thinking block, so `/think` and `/effort` work. Base URL defaults to `https://api.tokenrouter.com/v1` and is overridable with `clai set tokenrouter --url <url>` or `TOKENROUTER_BASE_URL` if your account uses a different host.
-
-#### Fireworks and Hetzner (open-model inference)
-
-[Fireworks](https://fireworks.ai) is a per-token inference gateway for open models — Kimi, DeepSeek, GLM, Qwen, GPT-OSS, Llama — with SSE streaming and native tool calling.
-
-```sh
-clai set fireworks fw_your_key          # key: fireworks.ai → API keys
-clai use fireworks                      # model defaults to accounts/fireworks/models/kimi-k2p6
-```
-
-[Hetzner Inference](https://docs.hetzner.com/general/company-and-policy/experiments/inference/) is Hetzner's OpenAI-compatible experiment API serving open-weight models (Qwen3.6-35B with vision, 262K context) from EU servers. It is free while experimental — there is no billing yet — with fair-use per-key rate limits and no SLA or production guarantee.
-
-```sh
-clai set hetzner your-token             # token: experiments.hetzner.com → Create API Token
-clai use hetzner                        # model defaults to Qwen/Qwen3.6-35B-A3B-FP8
-```
-
-Both fetch the live model catalog for `/model` (cached 1h) and rotate keys like every other provider.
-
-#### OrcaRouter (one key, eleven upstreams, zero markup)
-
-[OrcaRouter](https://docs.orcarouter.ai) is an OpenAI-compatible gateway that routes OpenAI, Anthropic, Google Gemini, DeepSeek, xAI Grok, Qwen, Kimi, MiniMax, Z.ai GLM and more behind one key — billed at each provider's published price with no token markup. Model ids are vendor-prefixed (`openai/gpt-4o-mini`, `anthropic/claude-sonnet-4.6`, `google/gemini-2.5-flash`, `deepseek/deepseek-reasoner`, …), and `orcarouter/auto` picks the cheapest model that fits the request.
-
-```sh
-clai set orcarouter sk-your-key        # key: orcarouter.ai/console (starts with sk-)
-clai use orcarouter                    # model defaults to openai/gpt-4o-mini
-/model anthropic/claude-sonnet-4.6     # or any id from the live /models catalog
-```
-
-Streaming, native tool calling, structured outputs (`response_format`), vision via `image_url` and prompt caching all work. Reasoning uses one unified `reasoning_effort` knob (low/medium/high, plus minimal/max on some models) that the gateway translates to each upstream's native shape — `/think` and `/effort` map onto it, and thinking arrives as `reasoning_content` in the usual thinking block. `/model` reads the live catalog (cached 1h), filtered to Chat-Completions-reachable models so image/video/tts ids stay out of the picker. Keys are multi-key with rotation like everywhere else; env var is `ORCAROUTER_API_KEY`.
-
-#### Merge Gateway (one key, many vendors, OpenAI-compatible)
-
-[Merge Gateway](https://gateway.merge.dev) fronts OpenAI, Anthropic, Google and other
-upstreams behind a single key. It exposes two surfaces: its own Responses-style API at
-`/v1` and a drop-in OpenAI-compatible surface at `/v1/openai`. clai drives the
-OpenAI-compatible surface, so streaming, native tool calling, prompt caching, reasoning
-effort, multi-key rotation and cross-provider fallback all behave exactly as they do for
-every other OpenAI-compatible provider.
-
-```sh
-clai set merge-gateway mg_your-key      # key: https://gateway.merge.dev (starts with mg_)
-clai use merge-gateway                  # model defaults to openai/gpt-5.2
-/model anthropic/claude-sonnet-4-6      # or any id from the live /models catalog
-```
-
-Model ids are vendor-prefixed (`openai/gpt-5.2`, `anthropic/claude-sonnet-4-6`,
-`google/gemini-3.5-flash`, `deepseek/deepseek-reasoner`). `/model` reads the live catalog
-(cached 1h) filtered to ids reachable over Chat Completions, so embedding, image and audio
-entries stay out of the picker; if the catalog cannot be fetched, a documented offline
-subset is shown. Reasoning uses one `reasoning_effort` knob (low/medium/high) that the
-gateway translates per upstream, and thinking arrives as `reasoning_content` in the usual
-`/think` block. Requests carry both `Authorization: Bearer` and `X-API-Key`, matching the
-two shapes the gateway accepts. The free tier has a budget: once exhausted the gateway
-answers `402`, which clai treats as a quota error and rotates to the next key or provider.
-Aliases: `merge-gateway`, `mergegateway`, `merge`, `mg`. Env var `MERGE_GATEWAY_API_KEY`.
-`/info merge-gateway` prints the full walkthrough.
-
-#### Experiential Labs (one key, every vendor, OpenAI-compatible)
-
-[Experiential Labs](https://platform.experientiallabs.ai) fronts hosted providers,
-your own provider keys (BYOK) and platform-funded credits behind a single key. Every
-model is a slug that resolves through a provider waterfall with automatic failover, and
-the gateway is a drop-in OpenAI-compatible endpoint — streaming, native tool calling,
-prompt caching and reasoning effort all behave exactly as they do for every other
-OpenAI-compatible provider.
-
-```sh
-clai set explabs xpl_your-key         # key: https://platform.experientiallabs.ai/settings/api-keys (starts with xpl_)
-clai use explabs                      # model defaults to claude-fable-5.1
-/model gpt-5.6-sol                    # or any slug from the live catalog
-```
-
-`/model` lists the slugs your key can call (from `/v1/models`), enriched with catalog
-facts from the public `/api/models` (context window, vision, per-model reasoning
-efforts) and cached for an hour; image/embedding/batch slugs stay out of the picker and
-a documented offline subset is shown when the gateway is unreachable. Reasoning uses one
-`reasoning_effort` knob (low/medium/high/xhigh/max) that passes through when the route
-supports it and snaps to the nearest supported level otherwise, so `/think` and `/effort`
-work across every vendor. Keys are multi-key with rotation like everywhere else; env var
-is `EXPLABS_API_KEY`. Aliases: `explabs`, `experiential`, `experientiallabs`,
-`experiential-labs`, `exp`. `/info explabs` prints the full walkthrough.
-
-### Manage keys
-
-```sh
-clai set nvidia nvapi-first_key        # store a key (appends if one exists)
-clai set nvidia nvapi-second_key       # add another key for the same provider
+clai set deepseek sk-first_key         # store a key
+clai set deepseek sk-second_key        # add another key for multi-key rotation
 clai set gemini --from-env GEMINI_API_KEY
-echo "nvapi-..." | clai set nvidia --stdin
+echo "sk-..." | clai set deepseek --stdin
 clai set ollama --url http://localhost:11434
-clai set modal --url https://ws--ep-kimi-k3-server.us-west.modal.direct   # endpoint (repeatable)
-clai set modal wk-tokenId:ws-tokenSecret   # …then the proxy token pair
-clai set lightning <key>               # Lightning AI Model APIs
-clai set tokenrouter sk-your-key       # TokenRouter
-clai set fireworks fw_your_key         # Fireworks
-clai set hetzner your-token            # Hetzner Inference (experiments.hetzner.com)
-clai set orcarouter sk-your-key        # OrcaRouter (orcarouter.ai/console)
-clai set merge-gateway mg_your-key     # Merge Gateway (gateway.merge.dev)
-clai set explabs xpl_your-key          # Experiential Labs (platform.experientiallabs.ai)
-clai set free <key>                    # optional: unlock premium models (free is keyless by default)
-clai unset modal --url                 # drop stored endpoint URLs, keep the keys
-clai keys                              # providers + masked keys (★ active) + endpoint URLs
-clai use nvidia                        # set active provider
-clai provider                          # interactive provider/model picker
-clai unset nvidia                      # remove ALL keys for a provider
+clai keys                              # list providers with masked keys (★ active)
+clai use deepseek                      # set active provider
+clai provider                          # interactive provider/model selector
+clai unset deepseek                    # remove keys for a provider
 ```
 
-In the console, **`/set`** opens a multi-row editor: add rows with `+`, remove rows, star a row to make it the active one, or disable a row to skip it in rotation without deleting it (`d` in the classic UI, `Ctrl+D` or the ○ marker in OpenTUI) — then **Save**, or **Reset all**. Providers with their own base URL (Modal, Lightning AI, TokenRouter) get a second **endpoints** row in the `/set` picker that edits their URL list the same way — URLs are shown in full rather than masked, since they aren't secrets. `/set <provider> https://…` adds and activates one URL directly. **`/keys`** lists keys masked plus the active endpoint, marking disabled rows `(disabled)`; **`/unset`** clears a provider. Disabled entries are never tried until re-enabled, and disabling every key for a provider fails fast with a clear error instead of burning requests.
-
-### Smart switching (how it stays up)
+In the interactive console:
+- **`/set`** opens the multi-row key editor. Add keys (`+`), set the active key (★), or disable a key (`○`) without deleting it.
+- **`/keys`** displays configured keys (masked) and active status.
+- **`/provider`** and **`/model`** open interactive pickers for switching providers and models on the fly.
 
-- **Multi-key rotation** — up to **10 keys per provider**. The last key that worked is *sticky*; on failure clai rotates circularly to the next key. Endpoint providers (Modal, Lightning AI, TokenRouter) fail over their stored endpoints alongside the keys, and the ★ active endpoint follows the one that worked.
-- **Disable without deleting** — toggle any key or endpoint row disabled in the `/set` editor and rotation skips it until you re-enable it.
-- **What triggers a switch** — HTTP 429 (rate limit), 401/403 (auth), 402 / quota / billing text, transient network errors, 500–504, and empty completions. Auth and quota errors switch **immediately** (no backoff wait); rate limits back off briefly first.
-- **Cross-provider fallback** *(opt-in)* — `/fallback on` lets clai try other configured providers after the active one is exhausted (only when running a provider's default model).
-- **Free-only mode** *(opt-in)* — `/freeonly on` excludes paid-cloud providers from the fallback chain, so you never accidentally spend.
-- **Quiet status** — a single non-stacking status line shows what happened, e.g. `switching nvidia key [2/4] …ab12 (rate limited)`. Keys are always masked to the last 4 chars.
+### Smart Switching & Resilience
 
-```sh
-/freeonly on      # stay on free tiers only
-/fallback on      # allow other providers when the current one is exhausted
-```
+- **Multi-key rotation** — Store up to **10 keys per provider**. The last key that worked is *sticky*. On encountering a rate limit (HTTP 429), quota limit, auth error, or 5xx server error, `clai` automatically rotates to the next available key.
+- **Disable without deleting** — Toggle any key disabled in the `/set` editor; rotation skips it until you re-enable it.
+- **Cross-provider fallback** *(opt-in)* — `/fallback on` lets `clai` fall back to other configured providers when the active provider is exhausted.
+- **Free-only mode** *(opt-in)* — `/freeonly on` restricts fallback strictly to free tiers so you never accidentally spend.
 
 ---
 
@@ -415,11 +151,11 @@ In the console, **`/set`** opens a multi-row editor: add rows with `+`, remove r
 
 The same agent that runs recon also ships code. It explores before it writes, matches your existing stack from lockfiles, edits surgically, and proves the result:
 
-- Scaffolds and extends apps; replaces starter boilerplate with real features (a scaffold alone is treated as incomplete).
+- Scaffolds and extends apps; replaces starter boilerplate with real features.
 - Surgical file tools: `fs.edit`, `fs.replaceLines`, `fs.append`, plus multi-file writes.
 - Runs the checks that apply — typecheck, build, unit/integration tests — and fixes failures before claiming success.
 - Starts dev servers as background jobs, tails until ready, probes `localhost`, and reports the URL / port / job id with the server left running.
-- Debugging loop: reproduce → read the actual error → fix root cause → re-verify (never "diagnosed but not fixed").
+- Debugging loop: reproduce → read the actual error → fix root cause → re-verify.
 
 ```sh
 clai --mode agent "convert this Vite React app to Next.js App Router, keep all features, run the build"
@@ -428,7 +164,7 @@ clai --mode agent "this test is flaky — find the race and fix it"
 
 ### Scope-based pentesting & bug bounty
 
-clai is built to run real, authorized security work — not to narrate it. It follows a recon-first methodology and keeps you inside the boundaries you set.
+`clai` is built to run real, authorized security work — not to narrate it. It follows a recon-first methodology and keeps you inside the boundaries you set.
 
 ```
 recon / discovery  →  fingerprint stack  →  plan.create (kind=pentest)
@@ -445,7 +181,7 @@ recon / discovery  →  fingerprint stack  →  plan.create (kind=pentest)
 4. `/implement` and execute task-by-task; expand the plan as new attack surface appears without wiping completed work.
 5. **Report** with structure — title, severity, evidence, reproduction, impact, remediation — and honest residual/untested notes.
 
-**Scope enforcement is real, not cosmetic.** When scope is active, clai checks each target against your authorized/excluded lists, enforces token-bucket rate limits and a concurrency ceiling, detects **redirects that leave scope** and **DNS-rebinding escapes**, and flags out-of-scope hosts instead of touching them. Loopback GET/HEAD stays allowed for local dev verification. Scope is opt-in: with no scope defined, scoping is simply off.
+**Scope enforcement is real, not cosmetic.** When scope is active, `clai` checks each target against your authorized/excluded lists, enforces token-bucket rate limits and a concurrency ceiling, detects **redirects that leave scope** and **DNS-rebinding escapes**, and flags out-of-scope hosts instead of touching them.
 
 ```sh
 clai authorize-pentest AGREE
@@ -458,7 +194,7 @@ Dedicated recon tools: `pentest.recon` (bundled whois/dns/nmap), `pentest.webDis
 
 ### General security & sysadmin workflows
 
-Log triage, config hardening, packaging, network questions, OCR of a screenshot or PDF report, quick OSINT — all handled by the same agent under the same safety gate.
+Log triage, config hardening, packaging, network analysis, OCR of a screenshot or PDF report, quick OSINT — all handled by the same agent under the same safety gate.
 
 ---
 
@@ -472,27 +208,27 @@ Three modes, switchable anytime with a slash command, `Shift+Tab`, or `clai --mo
 | **agent** | Executes: edits, installs, scans, verifies, works the plan. |
 | **plan** | Research and design a durable plan; approve with `/implement` before execution. |
 
-**Reasoning / thinking** is controlled with `/effort` (alias `/reasoning`), accepting `on`, `off`, `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`. clai only sends reasoning options to models that support them — and if a model rejects them at runtime, it marks that model, retries once without them, and tells you (`… rejected reasoning options — retrying without them`) so a session never hangs on an unsupported knob.
+**Reasoning / thinking** is controlled with `/effort` (alias `/reasoning`), accepting `on`, `off`, `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`. `clai` sends reasoning options only to models that support them.
 
 ---
 
 ## Safety gate
 
-You own authorization; clai still gates risk on every action:
+You own authorization; `clai` gates risk on every action:
 
 | Level | Behavior |
 |-------|----------|
 | **safe** | Auto-runs read-only work: `fs.read/list/search`, `sysinfo`, `dns.lookup`, `whois.lookup`, `http.fetch` GET, `web.search`/`web.fetch`, recon scanners. |
-| **confirm** | Asks first for mutations: file writes/edits, installs, moves, aggressive/mutating shell. |
-| **block** | Refuses destructive patterns (`rm -rf /`, fork bombs, classic exfil signatures) and SSRF-prone fetches. |
+| **confirm** | Asks first for mutations: file writes/edits, installs, moves, mutating shell commands. |
+| **block** | Refuses destructive patterns (`rm -rf /`, fork bombs, exfiltration signatures) and SSRF-prone fetches. |
 
-`fs.delete` always confirms (with an optional `v` preview) even under allow-all. `tool.batch` inherits the highest risk level of its children. Use `/permissions` to choose the default confirmation level and `/allow` / `/disallow` for a per-session tool allow-list.
+`fs.delete` always confirms (with an optional diff preview) even under allow-all. Use `/permissions` to choose the confirmation level and `/allow` / `/disallow` for a per-session tool allow-list.
 
 ---
 
 ## Terminal UI
 
-The old line REPL has been removed — there are only full surfaces now. An OpenTUI full-screen console is selected for a sufficiently large interactive POSIX terminal. The classic Ink UI is selected on Windows, on smaller terminals, or with `--classic`; non-TTY prompts use the noninteractive stream renderer. In the classic UI, mouse reporting is on by default so wheel swipes scroll the live tail and panels instead of being misread as prompt-history keys; native text selection stays one modifier away (Shift/Option/Fn), and `CLAI_CLASSIC_MOUSE=0` turns mouse reporting off. The interactive surfaces provide streaming chat, nested tool cards (including `tool.batch` sub-calls), file diffs, a live plan pane, pickers, history, and secure masked key prompts. MCP tools stay off by default; picking a server with `/mcp` inserts an aqua `@mcp:<server>` token into the prompt you are typing — several tokens can coexist, backspace deletes one like any other text, and `all` / `off` add no token. MCP counts never appear in status bars.
+The interactive console provides streaming chat, nested tool cards, file diffs, a live plan pane, pickers, session history, and masked key prompts.
 
 | Action | Key |
 |--------|-----|
@@ -503,62 +239,24 @@ The old line REPL has been removed — there are only full surfaces now. An Open
 | Plan pane / plan detail | `Ctrl+H` / `Ctrl+P` |
 | Background jobs | `Ctrl+J` |
 | Expand thinking / tool output | `Ctrl+T` / `Ctrl+O` |
-| Copy the focused thinking block | `c` |
+| Copy focused thinking block | `c` |
 | Search transcript | `Ctrl+R` |
 | Copy selection | `Ctrl+Shift+C` |
 | Commands / file mentions | `/` · `@` |
 | MCP servers / project config | `/mcp` |
 | Command help / shortcut reference | `Ctrl+G` / `/shortcuts` |
 
-Completed thinking collapses to one clickable `✦ Thought for 3.2s` line; clicking it (or `Ctrl+T`) opens the reasoning in a card that scrolls internally when the reasoning is long. Clicking a card focuses it — the border turns violet and the wheel scrolls that card instead of the chat, even at its first and last row — while an unfocused card dims, shows `click to focus`, and leaves the wheel to the transcript. Moving the pointer out or clicking elsewhere releases it, and `c` copies the focused block's full reasoning and then releases it.
-
-Tool cards show the command/input clearly, with a live elapsed timer next to the command name while they run (the final duration stays visible afterwards), and keep long scan tails in an expandable OUTPUT pager (search, copy, export). File writes show a diff preview. When the agent finishes each prompt — naturally or aborted — a `✻ Worked for 1m16s` row is appended under the response, and it is restored when the session is resumed from `/history`. The status line names what the agent is actually doing right now — `responding` while streaming, `compacting` during auto or manual context compaction — instead of holding the last tool name. Prompts typed while the agent is busy are queued and run automatically in order once the turn settles; the queue pauses only when the previous turn was cancelled, errored, or stopped by the loop guard. Compaction cards preserve session memory without dropping the plan, and `/history` restores full sessions — prompts, tool results, and the matching plan — even after an abort or autosave.
-
-Automatic session titles describe the conversation's combined tasks, rather than replacing earlier work with the latest topic. Related follow-ups are grouped into shared themes, aiming for at most 12 words and 96 characters. Naming uses balanced request excerpts and the saved conversation transcript, including prompts inside compacted sections, so earlier tasks remain available after compaction and resume. Titles are first generated after two user prompts and reconsidered every three prompts; manually naming a session disables further automatic updates until it is reset or restored.
-
-On exit, both interactive surfaces leave the alternate screen and print a sign-off card on the normal terminal: the wordmark beside a labelled block — session title, folder, elapsed time and message count, reasoning/cache token notes, and the command that reopens the session — followed by the same per-provider/model token table `/usage` shows. Resuming is `clai --resume <id>` (a unique id prefix is enough, and `-c/--continue` picks the newest session for the current directory). Sessions that were never persisted (`--no-history`, private mode, or nothing sent) say so instead of offering a resume command. The card is borderless and reflows down to very narrow terminals: the wordmark drops from six rows to four, then the block stacks beneath it, and labels give way before the resume command is ever shortened.
-
-### Context usage and prompt caching
-
-The composer context chip shows the latest provider-reported input token count, including during follow-ups and compaction. It waits for the first response instead of showing a speculative count. Local estimates are marked `~` and used when prompt usage is unavailable; internal request-size checks remain separate. A new provider measurement can legitimately be lower after compaction. Cached tokens are part of the reported prompt total, not an extra context bucket to add again.
-
-Automatic compaction targets 200,000 assembled request tokens by default, including tool schemas and replayed context. Existing saved budgets at or below the former 180,000 default are migrated to `autoCompactRequestTokens: 200000` in the configuration file. When a custom session context window is set, its compaction target is 70% of that window instead: for example, 253,000 → 177,100 and 1,000,000 → 700,000. Both targets remain subject to output, safety, and compaction headroom: without a custom window, a 200,000-token model has a 156,992-token trigger, while a sufficiently large model reaches the full 200,000 default target. Dispatch also reserves the actual requested completion budget, including expanded continuations, and attempts compaction if the request no longer fits. Unusable summaries preserve the original history; clai will not silently delete context to force an oversized request through.
-
-Same-route follow-ups retain previously sent request state, and supported cache-affinity keys stay stable for the session. Compaction reuses the previous request prefix when it fits and makes at most one generation attempt; rejected, truncated, or unusable summaries retain the original history rather than silently issuing another request. Cache hits still depend on the provider's expiry, routing, and supported caching behavior. Changing models or replacing history with a compacted summary can require a new cache prefix.
-
-Recovery instructions and responder result ledgers append changed snapshots without deleting previously sent messages; identical updates are not duplicated. This shared history behavior applies to AgentRouter and other compatible providers. Custom OpenAI-compatible providers can declare `profile.cache.kind: "affinity-key"` with an `affinityField` and optional `isolationField` supported by their API. Chat Completions and Responses requests populate those fields with stable session keys; unrelated request controls cannot be replaced by cache fields. API compatibility alone does not imply support for every provider-specific caching option.
-
-Anthropic, AWS Mantle, and Gemini keep changing request context in conversation order rather than moving it ahead of all prior messages. Anthropic-compatible requests use bounded conversation cache checkpoints in addition to the stable system checkpoint. The cache percentage is cumulative cached input divided by cumulative input tokens for requests with cache accounting, not the percentage of the session still held in a provider cache. A few uncached requests can lower that percentage, and later hits improve it gradually rather than immediately restoring its previous value.
-
-Long-session memory optimizations preserve conversation and transcript content: rendering caches have size-aware eviction, terminal reattachment uses a fixed-size ring with the existing replay limit, and history recovery scans records incrementally. Bounded output previews and diagnostic excerpts own their text instead of retaining the full backing strings of large tool outputs. These are storage and rendering optimizations, not additional model-context truncation.
-
-Compatible providers negotiate their API before sending the conversation: a short synthetic request uses the production serializers, authentication/custom headers, streaming mode, and reasoning/tool-control options, with at most 512 output tokens. Optional Responses fields are negotiated on these small requests. If Responses exposes no visible reasoning, a small Chat request checks whether Chat actually exposes it; clai prefers Chat only with positive evidence, otherwise retaining Responses. Encrypted/private reasoning and reasoning-token counts are not treated as visible text, and neither API can guarantee reasoning text on every answer.
-
-Preflight uses no conversation history, images, or original tool schemas and has separate cache affinity. Choices are shared for matching provider, endpoint, model, credentials, headers, mode, and options; concurrent callers share negotiation. Observations expire after 30 minutes for new sessions, while active sessions retain their choice to protect cache prefixes. Cancellation, authentication/rate-limit failures, timeouts, and server errors do not mark a route unsupported. A cold negotiation uses at most three small requests with a shared 30-second deadline; these are billable provider calls, not conversation generations, and do not replace the real request's usage/context reporting. Small probes validate basic protocol/control support, not every image format, tool schema, or replay artifact.
-
-Successful real Responses API requests are retained even when the provider does not expose reasoning; clai does not regenerate an answer or silently change protocols merely to obtain visible thinking. Ordinary requests do not evict earlier tool interactions just because their accumulated arguments cross a rolling size threshold. Explicit compaction and context admission checks still apply.
-
-When switching providers or models, incompatible reasoning and interrupted native tool transactions are projected into compatible history without deleting the original conversation. Tool results remain available as text where native replay is unsafe, while compatible new tool transactions stay native. Known text-only GLM-5 routes do not receive image parts or the `image.view` tool. If a route rejects image input, clai can retry once without images and tells both the user and model that the image contents are unavailable; the original attachments remain available when switching back to a vision-capable model.
+- **Thinking blocks:** Clickable `✦ Thought for 3.2s` rows open internal reasoning in a scrollable card (`Ctrl+T`). Pressing `c` copies the reasoning text.
+- **Tool cards:** Show running commands with live elapsed timers, status indicators, and expandable output pagers (`Ctrl+O`) with search and copy capabilities.
+- **File diffs:** Edits and writes render clean inline diff previews before changes take effect.
 
 ### Background sessions, minimise, and SSH reattach
 
-Normal persistent interactive launches use a per-session local PTY broker. The UI and agent run inside that broker-owned terminal, while the shell process you interact with is a disposable client. This keeps the exact same live UI, pending confirmation, queue, tools, MCP connections, and terminal subprocesses alive when the client goes away.
-
-- `/minimise` (also `/minimize`) detaches immediately and returns the shell prompt without cancelling the current turn. It prints the session id and the exact `clai --resume <id>` command.
-- An SSH or terminal disconnect has the same detach behavior. SSH into the VM again as the same OS user and run `clai --resume <id>`; `clai -c` prefers the newest live session in the current directory.
-- `/history` marks running, attached, and detached sessions. Selecting another session attaches or starts its own runtime instead of loading over a running agent, so the outgoing agent continues independently.
-- One terminal controls a session at a time. Attaching from another terminal safely transfers control and releases the old terminal; this prevents duplicate keystrokes while still allowing cross-computer SSH takeover.
-- The broker stores only bounded terminal replay (2 MiB), uses an authenticated user-only Unix socket or Windows named pipe, and keeps runtime metadata/locks user-readable only. It never opens a TCP port.
-- A detached runtime stays alive while a turn, compaction, queued prompt, or responder job is active. Once truly idle and detached, it exits after 30 minutes by default; the saved session still resumes normally without keeping idle processes forever.
-- `--no-history`, private mode, non-TTY/one-shot runs, and systems without a usable PTY retain the existing direct foreground behavior. `/minimise` reports that background detach is unavailable instead of partially detaching.
-
-Optional controls:
+Interactive sessions run behind a local broker so an agent continues working across terminal disconnects:
 
-```sh
-CLAI_SESSION_RUNTIME_IDLE_MS=1800000  # detached idle lifetime (1 minute–24 hours)
-CLAI_SESSION_RUNTIME_MAX_IDLE=2       # idle-detached LRU cap (1–256; 0 disables)
-CLAI_DISABLE_SESSION_RUNTIME=1        # force legacy direct foreground ownership
-```
+- **`/minimise`** (or `/minimize`) detaches immediately and returns you to your shell without interrupting the turn. It displays the session ID and resume command.
+- **SSH disconnects:** If an SSH session drops, reconnect and run `clai --resume <id>` (or `clai -c` to continue the latest session in the current directory).
+- **`/history`** lists all active, attached, and detached sessions.
 
 ---
 
@@ -567,72 +265,24 @@ CLAI_DISABLE_SESSION_RUNTIME=1        # force legacy direct foreground ownership
 | Command | Does |
 |---------|------|
 | `/ask` · `/agent` · `/plan` | Switch mode (plan = design-then-approve) |
-| `/implement` · `/discard` | Approve+execute or drop the current plan |
-| `/model [name\|#]` · `/provider [name]` | Pick model / switch provider |
-| `/set [provider]` · `/unset [provider]` · `/keys` · `/info [provider]` | Manage API keys, endpoint URLs, and view provider setup / pricing info |
-| `/effort [level]` · `/reasoning [level]` | Thinking / reasoning effort |
+| `/implement` · `/discard` | Approve and execute or drop the current plan |
+| `/model [name]` · `/provider [name]` | Select model / switch provider |
+| `/set [provider]` · `/unset [provider]` · `/keys` | Manage API keys and view provider configuration |
+| `/effort [level]` · `/reasoning [level]` | Configure thinking / reasoning effort |
 | `/freeonly [on\|off]` · `/fallback [on\|off]` | Free-only filter · cross-provider fallback |
 | `/search [provider]` · `/search-provider` | Choose web-search backend |
-| `/mcp [server\|all\|off\|list\|status\|tools\|locations\|refresh\|stop <server>\|start <server>\|login <server>\|add notion]` | Browse/select MCP servers, stop or restart one, sign in with OAuth, or connect official Notion MCP |
-| `/scope [show\|add\|new\|clear]` | Engagement scope |
-| `/output [last\|id\|list]` | Open full tool output (also `Ctrl+O`) |
-| `/jobs` | Background jobs (also `Ctrl+J`) |
-| `/orchestrator [on\|off\|status\|models]` · `/orchestration` | Show delegation status, configure subagent model fallbacks, or turn subagents on/off |
-| `/agents [id\|stop id\|restart id]` | Pick a subagent to inspect live output, or stop/restart its assignment |
-| `/compact` · `/context` | Compact history now · show context size |
-| `/history` · `/save <name>` · `/new` · `/clear` · `/reset` | Session lifecycle (`/clear` deletes the current session outright) |
-| `/allow <tool>` · `/disallow <tool>` · `/permissions` | Tool permissions |
+| `/mcp [...]` | Browse, configure, start, or stop MCP servers |
+| `/scope [show\|add\|new\|clear]` | Manage engagement scope |
+| `/output [last\|id\|list]` | Open full tool output pager (also `Ctrl+O`) |
+| `/jobs` | View background jobs (also `Ctrl+J`) |
+| `/compact` · `/context` | Compact history now · show context token size |
+| `/history` · `/save <name>` · `/new` · `/clear` | Session lifecycle management |
+| `/allow <tool>` · `/disallow <tool>` · `/permissions` | Tool permission management |
 | `/cwd <path>` | Change working directory |
 | `/think` · `/thinking` | Show thinking from the last response |
-| `/privacy [...]` | Private mode · clear history/logs/artifacts |
-| `/minimise` · `/minimize` | Detach this terminal while the live session continues in the background |
-| `/update` · `/help` · `/shortcuts` · `/exit` | Housekeeping |
-
-Orchestration is enabled in new and restored sessions. `/orchestrator`,
-`/orchestration`, and `/orchastrator` show the current status and open a picker
-with **On**, **Off**, and **Models…**. `/orchestrator status` prints the status
-without changing it, `/orchestrator on` / `/orchestrator off` set it directly,
-and `/orchestrator models` opens the subagent model editor. The active position
-determines the first eligible model; other enabled rows are fallbacks in rotation
-order. With no saved chain, subagents follow the parent session route. A fallback
-is used only for a retryable pre-output failure, and model-chain changes apply to
-new attempts.
-Turning orchestration off stops active children and blocks new starts and
-restarts for this session; turning it back on re-enables delegation. `/agents`
-opens the separate live inspector. `/agents` opens the same live inspector in
-Classic and OpenTUI: select a child, press `Esc` to return to the picker, then
-select another child or **Main agent**. Inspecting output never interrupts the
-main turn. The pager follows live output; `l` toggles follow. Turning
-orchestration off stops active children and prevents new starts and restarts.
-`/agents stop <id>` stops an individual child. `/agents restart <id>` reruns the
-assignment when orchestration is enabled. Saved child reports can be inspected
-after resuming their parent session; `--no-history` keeps child records in
-memory only.
-
-The last usable child summary is stored separately from activity and survives
-stop, restart, and compaction. `subagent.read` with `view=summary` recovers it with
-its original attempt and completion status; a prior summary never marks a stopped
-attempt complete. Undelivered terminal results return through the parent inbox on
-session restore, and acknowledged results are not replayed on later restores.
-
-Children have no fixed concurrency, step, or assignment-time budget. By default,
-they inherit the parent's provider/model and project root; a configured subagent
-model chain selects a primary execution route and fallbacks without changing the
-assignment identity. Children retain independent histories and stable cache
-prefixes. Their only tools are confined file reads/listings/searches and web
-search/fetch; shell, editing, MCP, arbitrary HTTP actions, and further delegation
-are unavailable. Provider context and transport safety limits still apply. Context
-compaction retains evidence and continues research without displaying internal
-partial reports as deliverables.
-
-The parent leaves delegated investigations to their children and continues only
-necessary non-overlapping work. Results arrive automatically at safe model
-boundaries or wake an idle parent. When no independent work remains,
-`subagent.wait` suspends without polling or a default deadline; omit the ID to
-receive whichever child completes, fails, or stops first. Healthy work should not
-be cancelled for slowness or because the parent repeated it. Reports are retained
-whole and paged with `subagent.read`; use the returned attempt and `nextOffset`
-to continue reading. Activity reads default to three recent events.
+| `/privacy [...]` | Private mode · clear history, logs, or artifacts |
+| `/minimise` · `/minimize` | Detach terminal while the session runs in background |
+| `/update` · `/help` · `/shortcuts` · `/exit` | Utilities and exit |
 
 ---
 
@@ -644,49 +294,34 @@ clai [prompt...]                       # interactive UI, or one-shot with a prom
   -y/--yes  --no-history
   --show-thinking  --verbose  --quiet    # one-shot stream controls
   --tui  --classic
-  --ui <tui|v2|opentui|classic|legacy|ink> # aliases; ignored with a prompt
-  --resume <sessionId>  -c/--continue    # reattach live or reopen saved session; ignored with a prompt
+  --resume <sessionId>  -c/--continue    # reattach live or reopen saved session
 
-clai set <provider> [key]              # --from-env <VAR> | --stdin | --url <url> (repeatable) | --skip-ping
-clai unset <provider>                  # remove all keys for a provider (--url = endpoint URLs instead)
-clai keys                              # list providers with masked keys + endpoint URLs
+clai set <provider> [key]              # --from-env <VAR> | --stdin | --url <url>
+clai unset <provider>                  # remove all keys for a provider
+clai keys                              # list providers with masked keys
 clai use <provider>                    # set active provider
 clai provider [provider]               # switch provider or open picker
 clai model <model>                     # set model for the active provider
 clai mode <ask|agent|plan>             # set default mode
 clai search-provider <brave|tavily|duckduckgo>
-clai config [key] [value]              # print / get / set config
+clai config [key] [value]              # view or update configuration
 clai doctor                            # check installed tools + provider config
-clai history [--show <id>]             # list sessions / print one (with resume commands)
-clai update                            # check for updates
+clai history [--show <id>]             # list saved sessions
+clai update                            # check for updates and upgrade
 clai authorize-pentest AGREE           # enable scan/attack tools (one-time ack)
-clai scope <show|new|add|clear>        # engagement scope (new: --targets --exclude --phases
-                                       #   --name --note --expires --max-rate --max-concurrency)
-clai privacy <status|on|off|retention|clear-history|clear-logs|clear-artifacts|clear-all>
+clai scope <show|new|add|clear>        # engagement scope management
+clai privacy <status|on|off|clear-all> # privacy and history clearing
 ```
 
-### One-shot output and exit status
-
-`clai "prompt"` and piped prompts use the noninteractive stream renderer. The final
-assistant answer is written to **stdout**; progress, tool cards, diffs, thinking (when
-`--show-thinking` is enabled), confirmations, and errors are written to **stderr**. `--quiet`
-suppresses progress while retaining the final answer on stdout, and `--verbose` expands tool
-output and diff hunks. `--no-history` disables persistence for that run.
-
-A completed, partially completed, blocked, or failed turn returns exit code `0`; an aborted
-turn returns `130`; an unhandled or loader error returns `1`. While one-shot work is running,
-press `Esc` or `Ctrl+C` to abort it, including commands launched through `bun run dev`.
-`--show-thinking` can also be enabled with `CLAI_SHOW_THINKING=1`.
-
 ---
 
 ## Model Context Protocol (MCP)
 
-clai can discover and call tools from local or remote MCP servers. MCP tools are **off by default** and are not sent to the model until a prompt mentions a server or the session is switched on with `/mcp all`. Run `/mcp` to discover configured servers and open the shared picker in Classic or OpenTUI. Picking a server inserts an aqua `@mcp:<server>` token into the composer text, exactly like a `skill:` mention: it is ordinary editable text, so backspace removes it, and several tokens select several servers for that prompt. `all` and `off` insert no token.
+`clai` can discover and call tools from local or remote MCP servers. MCP tools are **off by default**; they are activated when a prompt mentions `@mcp:<server>` or via `/mcp all`.
 
 ### Project configuration
 
-The native project file is `.clai/mcp.json`. It accepts JSON or JSONC and the common `servers` / `mcpServers` shapes. A minimal configuration can mix stdio and Streamable HTTP servers:
+Define MCP servers in `.clai/mcp.json` (or standard `.vscode/mcp.json` / `.cursor/mcp.json` locations):
 
 ```json
 {
@@ -708,38 +343,7 @@ The native project file is `.clai/mcp.json`. It accepts JSON or JSONC and the co
 }
 ```
 
-A `command` entry uses stdio. A `url` entry uses Streamable HTTP by default; set `"type": "sse"` for a legacy SSE endpoint. Remote HTTP/SSE entries with no `auth` block use OAuth discovery when the server requests authorization; set `"auth": {"kind": "none"}` to opt out explicitly for a public server. `${workspaceFolder}`, `${env:NAME}` / `${env.NAME}`, and compatible `${input:name}` substitutions are resolved at discovery time, and resolved secret values are redacted from diagnostics.
-
-The picker can add one server without hand-editing the file: choose **+ add MCP server** and a full multiline editor opens — visible caret, arrow-key and word/line navigation, mid-text edits, selection, and multi-line paste. `Enter` inserts a newline, `Ctrl+S` saves, `Esc` cancels. If the JSON does not validate, the editor reopens with your text intact and the parse error in the header, so a long paste is never retyped. You can also supply the fragment inline:
-
-```text
-/mcp add {"name":"docs","command":"docs-server","args":[]}
-```
-
-The add flow accepts one named object or a one-entry `servers` / `mcpServers` fragment, validates it, then atomically merges it into the current project `.clai/mcp.json` with deterministic server ordering and restrictive permissions. Existing unrelated metadata is preserved.
-
-clai also inherits compatible configuration from `CLAI_MCP_CONFIG` (an OS-delimited file list), ancestor `.clai/mcp.json` and `.mcp.json` files, repository `.github/mcp.json` and `.vscode/mcp.json`, clai user config, and supported Copilot, Claude, and VS Code user locations. Higher-precedence definitions deterministically shadow inherited servers with the same name. `/mcp locations` shows the exact project target and inherited paths for the current workspace.
-
-### Select and inspect servers
-
-```text
-/mcp                         # picker: add, off, all, or one server
-/mcp docs                    # drop @mcp:docs into the prompt (repeat for more servers)
-/mcp all                     # expose tools from every live server
-/mcp off                     # default: expose no MCP tools
-/mcp list                    # sources, transports, state, selection, and catalog
-/mcp status                  # live, failed, and invalid server details
-/mcp tools [server]          # canonical mcp.<server>.<tool> names
-/mcp locations               # project and inherited configuration paths
-/mcp refresh                 # rediscover configs and live tools
-/mcp reconnect docs          # restart one server connection
-/mcp stop docs               # shut the server down and drop its tools from every request
-/mcp start docs              # bring a stopped server back
-/mcp login docs              # run OAuth browser sign-in, store the token, reconnect
-/mcp add notion              # add https://mcp.notion.com/mcp and sign in
-```
-
-Static built-in tools always remain first; selected MCP definitions are appended in deterministic order as `mcp.<server>.<tool>`. Each schema is normalised once — documentation-only keywords dropped, descriptions bounded, keywords canonically ordered — and sent exactly once per request in the native function payload rather than repeated as prompt text, so a large server such as GitHub MCP costs a stable, cacheable prefix instead of tens of thousands of duplicated tokens per turn. Selection is never silently widened or dropped mid-refresh, and `/mcp stop <server>` closes the connection and removes its tools from every subsequent request until `/mcp start <server>`. A tool explicitly annotated read-only can run under the normal safe/parallel policy. Unmarked, mutating, or destructive MCP tools require the usual confirmation, and ask mode exposes only safe tools. Server descriptions and results are treated as untrusted data, secrets are redacted, response sizes and lifecycles are bounded, and HTTP credentials are never forwarded through redirects.
+Use `/mcp` inside the interactive console to browse servers, inspect available tools, view logs, restart connections, or add new servers interactively.
 
 ---
 
@@ -756,31 +360,15 @@ Static built-in tools always remain first; selected MCP definitions are appended
 | **Plan** | `plan.create` · `task.update` · `agent.handoff` |
 | **Context** | `sysinfo` · `image.ocr` · `pdf.read` |
 
-### tool.batch fail policy
-
-Default is **continue** — one failed lookup never kills the rest (ideal for recon). Opt into fail-fast or selective cancellation when later work depends on earlier success:
-
-```json
-{"name":"tool.batch","args":{
-  "on_fail":"cancel_pending",
-  "calls":[
-    {"name":"net.scan","args":{"target":"lab.example"}},
-    {"name":"http.fetch","args":{"url":"https://lab.example/"}}
-  ]
-}}
-```
-
-Top-level messages with several separate tool blocks never cancel siblings — use `tool.batch` when you need a fail policy.
-
 ---
 
 ## Web search / OSINT
 
-| Provider | Key | Env var |
-|----------|-----|---------|
-| DuckDuckGo | none (default) | — |
-| Brave | required | `BRAVE_SEARCH_API_KEY` |
-| Tavily | required | `TAVILY_API_KEY` |
+| Provider | Key | Environment Variable |
+|----------|-----|----------------------|
+| **DuckDuckGo** | None (default) | — |
+| **Brave** | Required | `BRAVE_SEARCH_API_KEY` |
+| **Tavily** | Required | `TAVILY_API_KEY` |
 
 ```sh
 clai set brave bsx-...
@@ -788,41 +376,37 @@ clai set tavily tvly-...
 clai search-provider tavily
 ```
 
-Search-provider keys are multi-key and rotate just like model providers.
-
 ---
 
 ## Per-project context
 
-Drop a `.clai/context.md` in a repo and its contents are injected every turn — lab topology, in-scope hosts, stack assumptions, coding conventions, or anything the agent should always know for that project. Project-scoped MCP servers belong in `.clai/mcp.json`; use `/mcp locations` to see that target plus every inherited compatible source.
+Drop a `.clai/context.md` in any project root, and its content is injected automatically on every turn — repo architecture, stack conventions, testing instructions, or scope rules.
 
 ---
 
 ## Interactive REPLs and terminals
 
-Ask clai to use an interactive terminal whenever a program needs more than one input step. It keeps the process attached to the current conversation instead of treating it like a one-line shell command:
+When a task requires multi-step interactive terminal interactions, `clai` maintains a persistent terminal session attached to the conversation:
 
 ```text
-Start a Python REPL, inspect the failing parser, make a small change, and show me the result.
+Start a Python REPL, test the regular expression against our test cases, and show me the output.
 ```
 
-The agent uses `terminal.start`, `terminal.send`, `terminal.read`, `terminal.status`, `terminal.list`, `terminal.resize`, and `terminal.close` internally. Sessions are isolated per conversation, capture output as cursor-addressed pages, redact prompted secret input before it reaches transcripts or artifacts, and reliably terminate their process trees on close. In plan mode, starting or sending terminal input waits for plan approval; read, status, list, and close operations remain available.
-
-For authorized security work, interactive effects are re-evaluated against the active engagement scope at the time they are delivered. That includes the target, port, phase, and expiry accumulated from prior REPL commands, so a split sequence cannot bypass scope controls.
+The agent runs interactive commands in persistent PTY sessions, reads incremental output, sends follow-up commands, and safely terminates processes upon completion.
 
 ---
 
 ## Configuration & privacy
 
 ```sh
-clai config                # view config
-clai mode agent            # default mode
-clai model <name>          # default model for the active provider
+clai config                # view current config
+clai mode agent            # set default mode
+clai model <name>          # set default model
 /privacy on                # private mode: don't persist this session
 /privacy clear-all         # wipe history, logs, and artifacts
 ```
 
-Config lives under your OS user config dir (e.g. `~/.config/clai/`). Keys are stored locally and shown only masked. Inside an interactive console, `/provider`, `/model`, and `/models` change only that session and are restored with it; the explicit `clai use`, `clai provider`, and `clai model` CLI commands continue to set global defaults.
+Config is stored locally in your OS user directory (e.g. `~/.config/clai/`). Keys are stored locally and never exposed in plain text.
 
 ---
 
@@ -833,31 +417,12 @@ npm install
 npm run dev          # run from source
 npm run typecheck
 npm run build
-npm test             # full Vitest suite
-npm run test:classic:pty  # provider-independent POSIX PTY smoke
-npm run compile      # native binaries (Bun)
-npm run release:verify
-npm pack --dry-run
+npm test             # full test suite
+npm run compile      # compile native binaries with Bun
 ```
 
 ---
 
-## Releasing
-
-Tag-driven CI (`.github/workflows/release.yml`): validate (typecheck + tests + release checks) → multi-platform binaries → GitHub Release → npm `@pentoshi/clai` → Homebrew tap.
-
-```sh
-# package.json "version" is the single source of truth.
-npm version 3.8.0 --no-git-tag-version
-npm run sync-version    # refreshes version.generated.ts + install manifests + lockfile
-git commit -am "v3.8.0" && git push origin main
-git tag -a v3.8.0 -m "clai v3.8.0" && git push origin v3.8.0
-```
-
-Secrets: `NPM_TOKEN`, `TAP_GITHUB_TOKEN`. Optional: `NPM_PROVENANCE=true`.
-
----
-
 ## Architecture
 
 ```
@@ -865,7 +430,7 @@ clai/
 ├─ src/
 │  ├─ index.ts          # CLI entry + subcommands
 │  ├─ agent/            # loop, plans, compaction, resume orientation, tool parsing
-│  ├─ llm/              # 19 providers, streaming, native tools, key rotation + fallback
+│  ├─ llm/              # providers, streaming, native tools, key rotation + fallback
 │  ├─ mcp/              # discovery, validation, transports, lifecycle, and tool dispatch
 │  ├─ tools/            # fs, shell, net, http, web, pentest, batch, plan
 │  ├─ safety/           # risk classifier + engagement (scope) policy