aegiscode 5.2.32 → 6.0.0

package/README.md

@@ -1,422 +1,153 @@
-# aegiscode
+# aegiscode — the terminal host
 
-<div align="center">
+`aegiscode` in your shell — the command-line version of AEGIS Desktop. The same
+tool surface the Claude Code plugin exposes over MCP, plus a terminal instead of
+an editor — built on the same two shared pieces and no others:
 
-[![GitHub stars](https://img.shields.io/github/stars/aegisinfo/aegiscode?style=flat&logo=github&label=Stars&color=534AB7)](https://github.com/aegisinfo/aegiscode/stargazers)
-[![npm version](https://img.shields.io/npm/v/aegiscode?style=flat&logo=npm&label=npm&color=CB3837)](https://www.npmjs.com/package/aegiscode)
-[![npm downloads](https://img.shields.io/npm/dt/aegiscode?style=flat&logo=npm&label=downloads&color=CB3837)](https://www.npmjs.com/package/aegiscode)
-[![License](https://img.shields.io/badge/license-MIT-brightgreen?style=flat)](LICENSE)
-[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-0F6E56?style=flat)](https://github.com/aegisinfo/aegiscode/pulls)
+| Shared piece | What it is |
+|---|---|
+| `client/aegis.js` | The thin transport. Holds the API key, speaks HTTP/SSE. No brain logic. |
+| `mcp/tools.js` | The tool registry — names, JSON schemas, result formatting. |
+| `desktop/renderer/usage.js` | The token-usage → number mapping, shared with the GUI so the two can never disagree. |
 
-</div>
+Routing, model tiers, memory and billing all stay behind aegiscloud.org.
 
-**aegiscode remembers your project between sessions — so you never have to re-explain your stack, decisions, or context.**
+## Names: one name, `aegiscode`
 
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset="assets/demo.svg">
-  <img src="assets/demo.svg" alt="aegiscode terminal demo — animated" width="100%"/>
-</picture>
+This host and the CLI used to be two names for two packages. They are one
+product, so they are one name now:
 
-Multi-model terminal coding assistant. Works with Claude, OpenAI, DeepSeek, Groq, Gemini and Ollama. BYOK — your keys, your cost.
+| Name | Status |
+|---|---|
+| `aegiscode` | **this host**, v6.0.0. Installs a single binary, `aegiscode`. |
+| `aegis-terminal` | deprecated — the 0.1.x spelling of this package, folded into `aegiscode`. |
+| `aegiscode-cli` | 4.0.3, an earlier name of the full `aegisinfo/aegiscode` coding-assistant CLI. Untouched. |
+| `aegis-cli` | 0.4.8 (unrelated). |
+| `aegis` (bin) | claimed **twice already** — by `aegiscode-cli` (→ `bin/cli.js`) and by `aegis-desktop` (→ `bin/aegis.js`). Pre-existing; whichever installs last wins. |
 
-- **Private AI, BYOK** — run fully local with Ollama, no API key needed. A free aegiscloud.org account is still required to start the app (one-time Google login), but nothing you run locally leaves your machine.
-- **A model that grows over time** — `/router` auto-picks the cheapest model that can handle each task and learns from every session, so cost drops while quality holds.
-- **Many models, one answer** — `/council` votes and `/debate` makes them argue it out, so you get a reasoned consensus instead of one model's guess.
-- **Cloud sync — $2/month** — keep cross-session semantic memory and sync every session across machines. Activate with a single code.
-
-> ### Semantic memory — €2/month
-> The AI remembers your project, stack, and decisions across every session.  
-> Subscribe at **[aegiscloud.org](https://aegiscloud.org)**, then activate with one command:
->
-> ```
-> /memory activate <token>
-> ```
-
----
+Publishing this host as `aegiscode` moves the `latest` dist-tag for that name
+onto it. The previous line (`aegiscode@5.x`, the `aegisinfo/aegiscode` agent) is
+still installable and immutable on the registry — pin `aegiscode@5` for it.
 
 ## Install
 
-> Requires **Node.js >= 22**. Install via [nvm](https://github.com/nvm-sh/nvm): `nvm install 22`
-
-> **Important:** Use [Kitty](https://sw.kovidgoyal.net/kitty/) (recommended) or a modern terminal emulator (Ghostty, WezTerm, Alacritty, iTerm2, Windows Terminal) for the best experience. Older terminals may have rendering issues.
-
 ```bash
 npm install -g aegiscode
+# or, from a source checkout — no install needed:
+node cli/bin/aegiscode.js
 ```
 
-Or from source:
-
-```bash
-git clone https://github.com/aegisinfo/aegiscodex-
-cd aegiscodex-
-bash install.sh
-```
-
-`install.sh` builds the project and creates an `aegis-cli` wrapper in `~/.local/bin` — no sudo needed.
-
-**Prefer a native window over a raw terminal?** [ds-terminal](https://github.com/aegisinfo/ds-terminal) wraps `aegis-cli` in a GPU-accelerated Alacritty window with a split-pane layout — AI session on top, shell below.
+Requires Node 18+. Set your key once:
 
 ```bash
-curl -fsSL https://dl.aegiscloud.org/ds-terminal/install.sh | bash
-```
-
----
-
-## First run
-
-Run `aegis-cli` — the first thing it does is open your browser for a one-time login to your free aegiscloud.org account (Google sign-in). This is required even for fully local/Ollama-only use; once logged in, the session is cached and you won't see it again.
-
-After login, if no API keys are configured, an interactive setup guide launches automatically:
-
-```
-◆ aegiscode — Setup
-
-  Keys are saved to ~/.aegiscode/.env
-
-  Select provider:
-❯ Anthropic (Claude)    ANTHROPIC_API_KEY
-  OpenAI (GPT)          OPENAI_API_KEY
-  DeepSeek              DEEPSEEK_API_KEY
-  Groq                  GROQ_API_KEY
-  Google Gemini         GEMINI_API_KEY
-  Ollama (local)        (no key needed)
-```
-
-Pick a provider, paste your key, and optionally add more. Keys are saved to `~/.aegiscode/.env` and the app starts immediately.
-
-**Or configure manually** — create `~/.aegiscode/.env`:
-
-```env
-ANTHROPIC_API_KEY=YOUR_ANTHROPIC_API_KEY
-OPENAI_API_KEY=YOUR_OPENAI_API_KEY
-DEEPSEEK_API_KEY=YOUR_DEEPSEEK_API_KEY
-GROQ_API_KEY=YOUR_GROQ_API_KEY
-GEMINI_API_KEY=YOUR_GEMINI_API_KEY
+export AEGIS_API_KEY="aegis_..."
 ```
 
-Only add the keys for providers you want to use. aegiscode picks them up automatically.
-
----
-
-## Claude Code Pro/Max subscription login
-
-Already paying for Claude Code? Use your subscription instead of a pay-per-token Anthropic API key:
+## Use
 
 ```bash
-claude setup-token        # generates a Claude Code OAuth token (sk-ant-oat...)
-aegis-cli login --claude-pro  # paste it in
-```
-
-The token is saved to `~/.aegiscode/.env` as `CLAUDE_CODE_OAUTH_TOKEN` and takes priority over `ANTHROPIC_API_KEY` for any Anthropic model. Anthropic only allows OAuth subscription tokens to make API calls through the official `claude` binary, so aegiscode shells out to it instead of calling the API directly — the `claude` CLI must be installed and on `PATH`. Tool calls (file edits, shell commands) run through `claude`'s own permission system, following whichever permission mode you've set in aegiscode.
-
----
-
-## Quick start
+aegiscode                        # interactive session
+aegiscode "why is the sky blue"  # one-shot, prints the answer and the tokens
+aegiscode -p "..." --json        # machine-readable
+echo "q" | aegiscode -p -        # prompt on stdin
+aegiscode -m deepseek/deepseek-v4-flash -p "..."   # pin a model
+```
+
+In a session, plain text is a prompt. `/help` lists commands:
+
+| Command | What it does |
+|---|---|
+| `/ask <prompt>` | Pooled inference (identical to typing the prompt) |
+| `/status` | Key, plan, account, memory state |
+| `/models` | The model ids you can pin |
+| `/balance` | Token-bank balance and recent spend — tokens beside € |
+| `/recall <query>` | Search cloud memory |
+| `/remember <text>` | Save a durable note |
+| `/memory` `/import` | Review or import memory from other tools |
+| `/byok` `/byok-set` `/byok-rm` | Bring-your-own-key status and management (the key is prompted, never echoed) |
+| `/model` `/stream` `/theme` `/cost` `/clear` `/help` `/quit` | Session controls |
+| `/tool <name> [json]` | Call any registry tool directly |
+
+Every command above that talks to AEGIS names a tool from `mcp/tools.js`, and
+the test suite asserts both directions: no command points at a tool that does
+not exist, and no tool is unreachable from the prompt.
+
+## What it looks like
+
+```
+                                     ▄▄▄▄▄▄▄
+                                     ▟███████▙
+                                     ▜███▀███▛
+                                      ▜█████▛
+                                       ▜███▛
+                                        ▜▛
+
+                                     A E G I S  C O D E
+                             Cloud brain in your shell.
+
+┏━ aegiscode ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃ version  v6.0.0                                              ┃
+┃ model    nexus-brain                                         ┃
+┃ base     https://aegiscloud.org                              ┃
+┃ key      aegis_••••4f2a                                      ┃
+┃ render   streaming                                           ┃
+┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+ type /help for commands ∙ /quit to exit
+
+┃» you
+┃ summarise what changed in the token accounting
+┃⬢ aegis
+┃ Three things changed, and one of them was costing you money:
+┃
+┃ ∙ the pool merges worker usage instead of overwriting it
+┃ ∙ cache reads and writes are billed, not ignored
+┃ ∙ a zero-token call no longer refunds its reservation
+┃
+┃   merge_usage({input_tokens: 1250}, {output_tokens: 312})
+┃   => 1562 total
+┣─ ∅ nexus-brain ∙ 1,562 tok ∙ 1,250/312 ∙ €0.0007 ∙ 4.2s ∙ 4 calls
+
+ ⬢ aegis ∙ nexus-brain ∙ 1,562 tok ∙ €0.0007 ∙ stream          ctrl+c quit
+```
+
+Render it yourself, with no key and no network:
 
 ```bash
-aegis-cli                        # interactive mode
-aegis-cli "refactor this file"   # start with a message
-aegis-cli --model deepseek-chat  # use a specific model
-aegis-cli --router               # start with the auto-router on
-aegis-cli --continue             # resume last session
-aegis-cli --resume <session-id>  # resume specific session
-aegis-cli --print "what does this repo do?"            # headless — print response, exit
-aegis-cli --print --output-format json "summarize this" # headless JSON output, for scripts
+node cli/scripts/demo.mjs            # from a source checkout
+                                     # --light, --width 100, --plain also work
 ```
 
----
-
-## Configuration
-
-Config lives at `~/.aegiscode/config.json`. It is created automatically on first run.
-
-API keys are read from `~/.aegiscode/.env` — you don't need to put them in `config.json`.
+## Design notes
 
-To add a custom model inside the app:
-
-```
-/model add openrouter-mixtral "Mixtral 8x7B" mistralai/mixtral-8x7b-instruct https://openrouter.ai/api/v1 sk-or-...
-```
-
----
-
-## Built-in models
-
-| ID | Model | Provider |
-|----|-------|----------|
-| `claude-fable-5` | claude-fable-5 | Anthropic |
-| `claude-sonnet-4` | claude-sonnet-4-6 | Anthropic |
-| `claude-opus-4` | claude-opus-4-8 | Anthropic |
-| `claude-haiku-4` | claude-haiku-4-5-20251001 | Anthropic |
-| `openai-gpt-5.5` | gpt-5.5 | OpenAI |
-| `openai-gpt-4o` | gpt-4o | OpenAI |
-| `openai-o3` | o3 | OpenAI |
-| `deepseek-chat` | deepseek-chat | DeepSeek |
-| `deepseek-reasoner` | deepseek-reasoner | DeepSeek |
-| `groq-llama` | llama-3.3-70b-versatile | Groq |
-| `groq-deepseek` | qwen-qwq-32b | Groq |
-| `gemini-2.5-pro` | gemini-2.5-pro | Google |
-| `gemini-2.5-flash` | gemini-2.5-flash | Google |
-| `ollama-local` | llama3.2 | Ollama (local) |
-
-Any OpenAI-compatible API can be added as a custom model.
-
----
-
-## Commands
-
-Full reference with copy-paste examples: **[aegiscloud.org/aegiscode/commands](https://aegiscloud.org/aegiscode/commands)**
-
-### Session & Help
-
-| Command | Alias | Description |
-|---------|-------|-------------|
-| `/help [command]` | `/?` `/h` | Show all commands, or detailed help for one |
-| `/clear` | `/cls` | Clear chat history, same session ID |
-| `/compact` | | Manually compress conversation to free up context window |
-| `/status` | `/st` | Session info — current model, permission mode, message count, context usage |
-| `/tokens` | `/tok` | Token usage graph and estimated dollar spend |
-| `/version` | `/v` | Show installed aegiscode version |
-
-### Models & Routing
-
-| Command | Alias | Description |
-|---------|-------|-------------|
-| `/model [id]` | `/m` | Interactive model switcher, or jump to a model by ID |
-| `/model list` | | List all configured models |
-| `/model add <id> <name> <model> <baseURL> <apiKey>` | | Add a custom model |
-| `/model remove <id>` | | Remove a model |
-| `/router [on\|off\|stats]` | | Auto-pick the cheapest model per task based on complexity |
-| `/router set <tier> <id>` | | Pin a model to the simple/medium/complex tier |
-| `/effort [off\|low\|medium\|high\|max]` | | Set Claude's extended-thinking effort level |
-| `/confirm [on\|off] [model-id\|claude\|deepseek\|all]` | `/confirmations` | Toggle tool-call confirmation prompt per model |
-| `/yolo [on\|off]` | | Toggle auto-approve for all tool calls (no prompts) |
-
-### Multi-Agent
-
-| Command | Alias | Description |
-|---------|-------|-------------|
-| `/multi <task>` | | Orchestrate multiple AI agents on a complex task |
-| `/multiyolo <task>` | | Same as `/multi` with auto-approved tool calls |
-| `/build <description>` | `/forge` | Build an app with multiple AI models in parallel |
-| `/clone <url> [--name <project>]` | `/fetch-site` `/websnap` | Clone a website's structure and styling using DeepSeek |
-| `/council <question>` | | Send to every configured model, surface the majority answer |
-| `/debate <topic> [--models id1,id2] [--rounds N]` | `/db` | Structured multi-round debate between models |
-| `/research <question>` | | Multi-agent deliberation research |
-
-### Agent Apps (prebuilt pipelines)
-
-| Command | Description |
-|---------|-------------|
-| `/audit` | Full security audit — Scanner → Risk Analyzer → Reporter (3 agents) |
-| `/refactor` | Analyze and apply refactoring — Analyzer → Planner → Implementer (3 agents) |
-| `/test-gen` | Generate comprehensive test suite — Explorer → Designer → Writer (3 agents) |
-
-### Memory & Cloud
-
-| Command | Alias | Description |
-|---------|-------|-------------|
-| `/memory activate <token>` | | Activate persistent cross-session semantic memory |
-| `/memory stats` | | Show memory usage and quota |
-| `/memory clear` | | Wipe stored memory |
-| `/memory load <url\|path>` | | Load content into memory index |
-| `/memory upload` | | Upload memory to cloud |
-| `/cloud [status\|key <k>\|activate\|deactivate]` | | Manage AEGIS Cloud sync — sessions browsable at aegiscloud.org/dashboard |
-| `/billing` | | Show subscription tier, next billing date, memory quota |
-
-### Customization
-
-| Command | Alias | Description |
-|---------|-------|-------------|
-| `/theme [name]` | `/t` | Show or switch UI theme |
-| `/thinking` | | Toggle extended-thinking blocks expanded/collapsed |
-| `/copy [n\|last\|list\|raw]` | `/cp` | Copy a code block to clipboard |
-| `/skills [name\|refresh]` | `/sk` | List, show, or refresh discovered skills |
-| `/hooks [status\|list]` | | View configured hooks and their status |
-| `/mcp [tools\|<server-name>]` | | Show connected MCP server status and tools |
-
-### Copy, paste & text selection
-
-| Action | How |
-|--------|-----|
-| Copy last assistant reply | `Alt+C` or `Ctrl+C` at idle (markdown stripped) |
-| Copy your last message | `Alt+U` |
-| Copy a code block | `/copy [n\|last\|list\|raw]` or `/cp` |
-| Select text with the mouse + copy | `Alt+S` toggles **selection mode** — suspends mouse-wheel tracking and pauses the idle cursor blink (which would otherwise erase your selection every 800 ms) so the terminal's native mark/select + `Ctrl+Shift+C` works, then `Alt+S` again to resume wheel scrolling |
-| Paste into the input | Works via bracketed paste (`Ctrl+Shift+V` / middle-click); a multi-line paste is collapsed to a **first-line + `…`** preview while the full text is kept and submitted |
-
-> Note: on VTE-based terminals (gnome-terminal, xfce4-terminal) and Windows Terminal, the app's mouse-wheel tracking disables native mouse selection — use `Alt+S` there. On kitty/iTerm2/wezterm selection works alongside wheel scrolling, so the toggle is rarely needed.
-
----
-
-## /router — automatic model routing
-
-aegiscode can pick which configured model handles each message for you, based on how hard the task actually looks — so a quick lookup doesn't pay for an expensive model, and a real architecture question doesn't get shortchanged by a cheap one.
-
-```
-/router on                          # start auto-picking a model per message
-/router set simple deepseek-chat    # pin a tier to a specific model id
-/router                             # show current status + tier mapping
-```
+**It is not a Claude Code look-alike.** Violet-and-cyan on ink; a hexagonal
+shield sigil rather than a mascot; a `»` prompt and a `┃` transcript rail rather
+than `❯` and `✻`; heavy box corners rather than rounded ones. This is a
+deliberate divergence, not an accident of taste: `test/cli-identity.test.mjs`
+fails if any of Claude Code's exact RGB triples, glyphs, spinner frames or art
+rows appear in this host.
 
-Classification is a handful of cheap heuristics (message length, question phrasing, keywords like "architecture" or "security") — no extra model call to decide. When no tier is pinned explicitly, it defaults to a fixed cost-ordered list of the built-in models filtered to ones you have an API key for — and learns from there: if you abort (`Esc`/`Ctrl+C`) a response, that costs the model handling it some confidence for that tier, so a model that keeps getting cut off loses ground to the next cheapest one over time. `/router stats` shows the learned success rate per tier and model. This is a noisy signal (people abort for reasons that have nothing to do with quality too), so don't expect it to be perfectly tuned after a handful of sessions — it's real adaptation from real usage, not a black box.
+**A linear transcript, not a full-screen TUI.** Finished turns are written once
+to the scrollback; only the one live line (spinner, elapsed time) is redrawn.
+Output stays selectable, searchable and pipeable, which matters for a tool you
+script.
 
-Running `/model <id>` always wins — it pins your choice for the rest of the session and the router backs off until you run `/router on` again. The status bar shows `model: <name> (auto)` whenever the router picked it for you.
+**Tokens beside money, always.** A turn prints what it consumed and what it
+settled at, in the same line: `1,562 tok ∙ 1,250/312 ∙ €0.0007`. Sub-cent
+amounts keep four decimals, because a €0.0007 call rendered at 2dp reads as
+free usage next to a token count.
 
----
-
-## /build — parallel multi-model app builder
-
-`/build` decomposes your task into components, assigns each to the best available AI model, and builds everything simultaneously.
-
-```
-/build a REST API for a todo app with PostgreSQL
-/build a CLI tool that summarizes git commits
-/build a Flask web app with login and dashboard
-```
-
-**How it works:**
-
-1. **Plan** — primary model produces a component tree (JSON)
-2. **Build** — all components built in parallel, each by the best model for that role:
-   - DeepSeek → backend, algorithms (`DEEPSEEK_API_KEY`)
-   - GPT-4o → frontend, UI (`OPENAI_API_KEY`)
-   - Llama via Groq → tests, docs (`GROQ_API_KEY`)
-   - Primary model → architecture, integration
-3. **Sync** — summary of files written and how to run the app
-
-All agents write real files to your current directory. The more API keys you have configured, the more models work in parallel.
-
----
-
-## /council & /debate — many models, one answer
-
-Don't trust a single model on a hard call. Put several to work on it.
-
-```
-/council "is a state machine overkill for this form?"   # they vote, consensus wins
-/debate  "monorepo vs polyrepo for this team" --rounds 3 # they argue it out across rounds
-/debate  "React vs SolidJS" --models gpt-4o,deepseek      # pick the panel
-```
-
-`/council` sends the question to multiple configured models simultaneously, then surfaces the majority answer with the dissents. `/debate` runs a structured, multi-round discussion — each model sees the others' arguments and refines or pushes back — so you get reasoning, not just a tally. Both auto-pick from the models you have keys for; add more keys, get a bigger panel.
-
----
-
-## Tools
-
-aegiscode can read, write, and execute files in your project. Tool permissions are configured per-project in `.aegiscode/settings.json`:
-
-```json
-{
-  "permissions": {
-    "allow": ["Bash(git *)", "Bash(ls *)"],
-    "ask":   ["Bash(curl *)", "Bash(rm -r *)"],
-    "deny":  ["Bash(sudo *)", "Read(.env)"]
-  }
-}
-```
-
-Permission modes:
-
-| Mode | Behavior |
-|------|----------|
-| `default` | Read auto, write requires confirmation |
-| `autoEdit` | Read + write auto, execute requires confirmation |
-| `yolo` | Everything auto-approved |
-| `plan` | Read only, everything else blocked |
-
----
-
-## Memory
-
-Persistent cross-session memory requires an active subscription (€2/month).
-
-**How to activate:**
-
-1. Subscribe at [aegiscloud.org](https://aegiscloud.org)
-2. Check your inbox for the activation token
-3. Run inside aegiscode:
-
-```
-/memory activate <token>
-```
-
-Once active, the AI remembers your stack, past decisions, and project context across every session — no re-explaining needed.
-
-```
-/memory stats    # usage and quota
-/memory clear    # wipe stored memory
-```
-
----
-
-## Sessions
-
-Sessions are stored locally as JSONL files. Resume a previous session:
+## Tests
 
 ```bash
-aegis-cli --continue              # resume most recent
-aegis-cli --resume <session-id>   # resume by ID
-```
-
-If cloud sync is active (`/cloud activate`, requires an aegiscloud.org API key), every session is also uploaded and browsable from **[aegiscloud.org/dashboard](https://aegiscloud.org/dashboard)** — search, folders, notes, and bulk export, from any browser. The desktop GUI's Cloud tab links straight there.
-
----
-
-## Skills
-
-Skills are Markdown files (`SKILL.md`) that teach aegiscode a specialized capability or house rule — discovered automatically, loaded only when relevant so they don't cost tokens up front.
-
-```
-.aegis/skills/<name>/SKILL.md     # project-level, git-tracked
-~/.aegis/skills/<name>/SKILL.md   # user-level, global
-```
-
-`.claude/skills/` is also scanned for compatibility with Claude Code skills. Project-level skills win over user-level ones with the same name, so a project can override a global skill with local knowledge.
-
-```
-/skills              # list discovered skills
-/skills <name>       # show a skill's full details
-/skills refresh      # rescan skill directories
-```
-
-A `SKILL.md` is just frontmatter + instructions:
-
-```markdown
----
-name: my-skill
-description: What it does and when to use it — this is what the AI sees by default.
-allowed-tools: [Read, Grep, Bash]
-user-invocable: true
----
-
-Full instructions, loaded only when the skill is actually triggered.
-```
-
----
-
-## MCP
-
-aegiscode supports MCP (Model Context Protocol) servers. Configure in `~/.aegiscode/config.json`:
-
-```json
-{
-  "mcpEnabled": true,
-  "mcpServers": {
-    "my-server": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@my/mcp-server"]
-    }
-  }
-}
-```
-
----
-
-## Built by
-
-**Niklas Borneklint** — [aegiscloud.org](https://aegiscloud.org) · [@aegisinfo](https://github.com/aegisinfo)
-
-Part of the ÆGIS ecosystem.
+node ../../test/cli-identity.test.mjs   # the divergence guard
+node ../../test/cli-render.test.mjs     # width safety, accounting, live region
+node ../../test/cli-tools.test.mjs      # registry parity with the MCP host + dispatch
+node ../../test/cli-run.test.mjs        # the real binary against a real backend
+node ../../test/cli-package.test.mjs    # the published layout, isolated from the repo
+npm test                                # all of the above
+```
+
+`npm run predist` stages `client/`, `mcp/tools.js` and the desktop's `usage.js`
+into `cli/vendor/` (gitignored) so the published package resolves its own
+modules. `test/cli-package.test.mjs` copies that tree somewhere with no repo
+around it and runs the binary there.