@aragon-agent/cli 0.5.6 → 0.5.9

package/README.md

@@ -1,1105 +1,1429 @@
-# @aragon-agent/cli
-
-A Claude-Code / Codex-style **interactive terminal UI** for the
-[`@aragon-agent/core`](../core) engine. Type a task, watch the agent think and
-stream its answer, see each tool call render as a live card, and interrupt /
-steer / configure the session — all without leaving the terminal.
-
-> ⚠️ **Full permission, no sandbox.** This first version runs at **maximum
-> permission**: `bash` executes directly, file writes hit the real filesystem,
-> and there is **no per-action approval gate by default**. Only run it in
-> workspaces you trust. An opt-in confirmation mode is available via `--confirm`.
-
-## Install
-
-```bash
-# Global
-npm i -g @aragon-agent/cli
-aragon
-
-# Zero-install
-npx @aragon-agent/cli
-```
-
-> **Release note (R3):** `npx @aragon-agent/cli` resolves `@aragon-agent/core`
-> from the npm registry, so `@aragon-agent/core@^0.1.0` must be published first
-> (or bundled into the CLI `dist`). During local development inside this
-> monorepo, npm workspaces link the local `packages/core` automatically.
-
-## Quick start
-
-```bash
-# Set a key (any one of these)
-export ANTHROPIC_API_KEY=sk-ant-...
-# ...or paste it live in the TUI via /settings, or pass --api-key
-
-aragon                       # interactive TUI
-aragon "summarize README.md" # interactive, auto-submitting the prompt
-echo "list files" | aragon -p   # one-shot, prints to stdout then exits
-```
-
-## Usage
-
-```
-aragon [prompt]                 Start the interactive TUI (or one-shot with -p / piped stdin)
-aragon -p, --print [prompt]     Headless: stream the answer to stdout, then exit
-aragon config                   Open the settings screen
-aragon config set <key> <value> Non-interactive config write (e.g. model, provider)
-aragon config path              Print the config file path
-aragon models [--provider p]    List builtin + discovered models
-aragon --version | -v           Print the version
-aragon --help  | -h             Print help
-```
-
-### Global flags
-
-| Flag | Meaning |
-| --- | --- |
-| `--provider <id>` | `anthropic` \| `openai` \| `google` |
-| `--model <id>` | Model id |
-| `--base-url <url>` | Override the provider base URL (OpenAI-compatible endpoints) |
-| `--api-key <key>` | One-shot key override (not persisted) |
-| `--thinking <level>` | `off\|minimal\|low\|medium\|high\|xhigh` |
-| `--max-tokens <n\|auto>` | Output token cap: a number, or `auto` for the model's own ceiling (default `64000`) |
-| `--cwd <dir>` | Working directory for tools |
-| `--confirm` | Confirm each mutating tool call |
-| `--tool-timeout <ms>` | Per-tool executor ceiling (default 180000) |
-| `--idle-timeout <ms>` | Watchdog idle timeout (auto-raised to ≥ tool-timeout + 30s) |
-| `--theme <name>` | `auto\|warm\|cool\|light` (`dark` is a compatibility alias for `cool`) |
-| `--compact` / `--no-compact` | Transcript density: no blank rows between turns, or the default |
-| `--hints` / `--no-hints` | Show or hide the composer hint row |
-| `--fullscreen` | Force the full-screen TUI, overriding the automatic downgrades |
-| `--no-fullscreen` | Force the inline renderer (the 0.2.0 behavior) |
-| `--no-exit-transcript` | Do not replay the session summary after exiting |
-| `--plan` / `--no-plan` | Start the session in PLAN mode (read-only research + review) or force BUILD |
-| `--team` / `--no-team` | Enable or disable team subagents. `--no-team` does not register the `task` tool at all |
-| `--team-max <n>` | Max subagents per dispatch for this run, clamped to `[1, 10]` |
-| `--todo` / `--no-todo` | Enable or disable todo planning. `--no-todo` does not register the `todo_write` tool at all |
-| `--todo-panel` / `--no-todo-panel` | Show or hide the right-hand todo rail. The tool stays registered either way |
-| `--todo-follow <mode>` | What happens when a run ends with steps left: `notify` (default), `auto`, `off` |
-| `--no-skills` | Disable the skill system entirely (no catalog, no skill tools) |
-| `--skill <name>` | Force-load a skill's full body for this run (repeatable) |
-| `--skills-yes` | Approve skill installs for this run (CI / headless) |
-| `--no-color` | Disable ANSI color |
-| `--quiet` | (print mode) suppress tool/usage lines on stderr |
-
-Exit codes: `0` success · `1` agent/runtime error · `2` config/usage error ·
-`130` interrupted.
-
-## Slash commands (interactive)
-
-| Command | Action |
-| --- | --- |
-| `/help` | Keybindings + command help |
-| `/model` | Open the model picker |
-| `/settings` | Open the settings screen |
-| `/thinking <level>` | Set the thinking level |
-| `/max-tokens [<n>\|auto\|default]` | Output token cap; with no argument, reports the setting **and** the effective cap for the live model |
-| `/tools` | List active tools |
-| `/clear` | Clear the visible transcript |
-| `/reset` | New conversation |
-| `/cwd [dir]` | Show / change the tool working directory |
-| `/save [file]` | Save the session to JSON |
-| `/resume [file]` | Load a saved session |
-| `/plan [on\|off\|status]` | Toggle plan mode - the keyboard-free equivalent of `Shift+Tab` |
-| `/team [on\|off\|max <n>]` | Team subagents: status and the live roster, the on/off switch, the fan-out width |
-| `/todo [on\|off\|panel on\|off\|follow <mode>\|clear\|continue]` | Todo planning: status, the on/off switch, the rail, follow-through, and picking an unfinished plan back up |
-| `/theme <auto\|warm\|cool\|light>` | Switch the color theme live (persisted) |
-| `/expand [n]` | Expand / collapse the n-th-from-last (default last) tool card |
-| `/copy` | Copy the last answer to the clipboard |
-| `/logs` | Show where this session is being logged, and at what level |
-| `/reload` | Re-read `config.json` after editing it in another window (refused mid-run) |
-| `/skills [sub]` | List and manage skills (see below) |
-| `/<skill-name> [args]` | Run an installed skill directly |
-| `/exit` (`/quit`) | Exit |
-
-A leading `/` meant literally can be escaped as `//`. Typing `/` opens a
-command palette and `@` opens a file-path completion popup — `Tab` / `→`
-completes, `Up` / `Down` moves the selection, `Esc` closes it.
-
-## Keybindings
-
-| Key | Action |
-| --- | --- |
-| `Enter` | Submit (idle) / queue a steering message (running) |
-| `Alt+Enter` / `Shift+Enter` | Insert a newline |
-| `Shift+Tab` | Toggle **plan mode** (`BUILD` <-> `PLAN`). Equivalent: `/plan` |
-| `Esc` | Abort the run / close an overlay / close a popup |
-| `Ctrl+C` ×2 | Exit (first press warns) |
-| `Ctrl+L` | Redraw the frame (clear the screen in inline mode) |
-| `Ctrl+T` | Toggle thinking blocks |
-| `Ctrl+O` | Expand / collapse the most recent tool card |
-| `PgUp` / `PgDn` | Scroll the transcript a page (full-screen mode) |
-| `Shift+↑` / `Shift+↓` | Scroll the transcript a line (full-screen mode) |
-| Mouse wheel | Scroll the transcript (over the input box: prompt history) |
-| `Shift`+wheel | Scroll the transcript a page |
-| `Home` / `End`, `Ctrl+A` / `Ctrl+E` | Cursor to line start / end |
-| `Alt/Ctrl+←` / `→` | Word-wise cursor jump |
-| `Ctrl+W`, `Alt+Backspace` | Delete the previous word |
-| `Ctrl+U` / `Ctrl+K` | Kill to line start / end |
-| `Up` / `Down` | Move between draft lines; recall prompt history at the edges |
-| `?` | Open help (empty input) |
-
-In **full-screen mode** the transcript is scrolled by the app itself: `PgUp` /
-`PgDn` and `Shift+↑` / `Shift+↓`. While pinned to the bottom the viewport follows
-new output automatically; once you scroll away the status bar shows `↑N`, a slim
-rail on the right edge shows where you are, and a hint counts the lines below
-you. Submitting a message always re-pins to the newest output. In **inline mode**
-(`--no-fullscreen`) history lives in your terminal's native scrollback, printed
-once via Ink `<Static>`.
-
-**The mouse wheel scrolls whatever is under the pointer.** Over the transcript
-it scrolls the transcript three rows per notch (a page with `Shift`); over an
-open overlay it scrolls that overlay; over the input box at the bottom it steps
-prompt history one entry per notch, exactly as `↑` / `↓` do — including the rule
-that an in-progress draft is never overwritten.
-
-Two things follow from the app owning the mouse, and they are worth knowing
-before you meet them:
-
-- **Selecting text now needs `Shift`+drag** in most terminals. That is the
-  terminal's convention for "an application is tracking the mouse", not
-  something this CLI can opt out of while still reading wheel events.
-- **`tmux` with `mouse on` keeps the wheel for itself**, so the app never sees
-  it. `set -g mouse off` hands it back.
-
-Turn the whole thing off with `--no-mouse`, `ARAGON_MOUSE=0`, or
-`aragon config set mouse false`. With mouse support off the wheel simply does
-nothing in full-screen mode — it does not fall back to editing your draft, which
-is what it used to do. Inline mode is unaffected either way.
-
-## Themes
-
-Three palettes plus `auto`:
-
-| Name | Look |
-| --- | --- |
-| `warm` | Terracotta + amber over warm neutrals. The default (`auto` resolves here). |
-| `cool` | The blue/violet palette that shipped as `dark` through 0.3.x. |
-| `light` | For light terminal backgrounds. |
-
-`auto` never guesses `light`: terminals cannot report their background reliably,
-and guessing wrong makes the app unreadable rather than merely wrong-looking.
-
-**Migrating from 0.3.x** — `dark` was renamed `cool` when `warm` became the
-default, and the old name still works everywhere: `--theme dark`,
-`aragon config set theme dark`, `/theme dark`, and a config file containing
-`"theme": "dark"` all resolve to `cool`, so a screen you explicitly chose does
-not change under you. The value is rewritten as `cool` the next time the config
-is saved. Only users who never picked a theme see the new default.
-
-Density and hints are settable the same three ways: `--compact` / `--no-hints`
-for one run, `aragon config set density compact` / `aragon config set hints false`
-to persist. The composer hint row also shortens to `? help` on its own after a
-few sessions — except while a run is in progress, when it always spells out
-`esc abort` in full.
-
-## Full-screen mode
-
-`aragon` takes over the terminal's **alternate screen buffer** — the mechanism
-`vim`, `htop`, and `lazygit` use. Two consequences worth knowing:
-
-- Your previous shell output is **covered, not erased**, and returns untouched
-  when you exit. Nothing in your scrollback is destroyed.
-- The frame is fixed at `rows - 1` tall, which is what keeps the composer and the
-  status bar at the bottom of the screen even on an empty session.
-
-On exit the session is replayed into the normal buffer as plain text so the
-conversation survives leaving the screen (`--no-exit-transcript` opts out;
-`/save` still exports the full JSON).
-
-It downgrades to the inline renderer automatically when stdout is not a TTY,
-`TERM=dumb`, a CI environment variable is set, or the terminal is under 12 rows
-or 40 columns. `--fullscreen` overrides all of those except the non-TTY check —
-writing screen-control sequences into a pipe or a redirected file is never safe.
-`--no-fullscreen`, `ARAGON_FULLSCREEN=0`, or `aragon config set fullscreen false`
-opt out permanently.
-
-The terminal's native scrollback and mouse wheel do not scroll the transcript in
-this mode, and mouse tracking is deliberately left off because enabling it costs
-text selection and copy in most terminals. If a crash ever strands your terminal
-on the alternate screen, `reset` restores it.
-
-## Plan mode
-
-`aragon` has two postures, and `Shift+Tab` switches between them. `/plan` does
-the same thing for terminals that swallow the key (see below).
-
-| Mode | What it means |
-| --- | --- |
-| `BUILD` | The default, and unchanged from earlier versions: you ask, the agent does it. |
-| `PLAN` | Research and design only. The agent reads, asks you the decisions it cannot settle by reading, and submits a plan for approval before anything is written. |
-
-`BUILD` is right for "rename this symbol". `PLAN` is right for "add multi-tenant
-support" — anything where you want to see and steer the *approach* before a
-single byte changes.
-
-### What plan mode actually stops
-
-In `PLAN`, five tools are refused at the tool boundary: `write_file`,
-`edit_file`, `bash`, `skill_install` and `skill_create`. That is a property of
-the wiring, not a promise in a prompt — the refusal happens before the tool runs,
-so the badge is telling you something that is structurally true.
-
-**`bash` is refused in full, `git status` included.** This is the most likely
-question this feature generates, so: there is no reliable way to classify a shell
-string as read-only, and a gate that is right 95 % of the time is worse than one
-that is always right, because you stop trusting the badge. Use `read_file`,
-`list_dir`, `glob` and `grep`, which stay available; the refusal message names
-them so the agent has somewhere to go. There is no allowlist and there will not
-be one built out of substring matching.
-
-Everything else still works: reading, searching, loading skills, and asking you
-questions.
-
-### The two plan-mode tools
-
-- **`ask_user`** renders a keyboard-driven wizard: 1–5 questions, 2–4 options
-  each, exactly one marked `RECOMMENDED`, plus an `Other…` free-text option.
-  `↑`/`↓` choose, `Enter` confirms and advances, `←` goes back, `Esc` cancels.
-  Pressing `Enter` through the whole wizard accepts every recommendation, which
-  is a deliberate "use your judgement" path rather than an accident. A last
-  screen lets you review before submitting.
-- **`submit_plan`** renders the plan as a scrollable card: `a` approves, `r`
-  opens a one-line feedback field (`Enter` sends it, `←` goes back to the card),
-  `Esc` dismisses. **Approving flips the session to `BUILD` immediately and the
-  same run continues straight into implementation** — you do not have to re-ask.
-
-Cancelling either one is not an error. The agent is told to proceed on stated
-assumptions rather than to retry.
-
-**Dismissing a plan is not how you stop.** `Esc` on a plan card asks for a
-*better* plan — the agent is told to refine it and submit again — so a model that
-keeps submitting keeps getting cards. To stop the run itself, **press `Esc`
-twice**: the first closes the card, the second aborts the run. `Ctrl+C` twice
-still exits the session outright.
-
-### Where the mode is shown
-
-The status bar always names a non-default mode (`PLAN`, or `PLAN → BUILD` while
-a switch is pending), including on short terminals, with `--no-hints`, and in
-inline mode. The composer additionally shows a `PLAN` chip on its hint row and
-tints its border, where there is room for it.
-
-### Switching mid-run
-
-Tightening applies at once; loosening waits. Pressing `Shift+Tab` toward `PLAN`
-during a run takes effect immediately — you pressed it *because* the agent is
-about to do something. Pressing it toward `BUILD` during a run is **deferred to
-the end of the run**, so a session you launched under a read-only guarantee
-cannot start writing files because of one stray keypress. The status bar shows
-`PLAN → BUILD` while that is pending. Approving a plan is the one exception, and
-it is an informed act rather than a stray keypress.
-
-### If `Shift+Tab` does nothing
-
-Some multiplexers and remote-desktop stacks never send `CSI Z`. `/plan`,
-`/plan on`, `/plan off` and `/plan status` are first-class equivalents, and
-`--plan` / `ARAGON_PLAN=1` / `planModeDefault` cover the startup case.
-
-### Headless
-
-`aragon -p --plan "add SSO"` is a useful combination: the read-only gate still
-applies, so it means *"tell me how you would do this, and do not touch my
-repository"*. No question or plan tool is registered there — there is nobody to
-ask — and the agent writes the finished plan as its final message in markdown.
-
-## TODO planning
-
-For work with three or more distinct steps the agent keeps a **visible plan**:
-it writes a checklist with the `todo_write` tool, marks exactly one item as in
-progress, and ticks it off before starting the next. In full-screen mode that
-list is rendered as a right-hand rail, about a fifth of the terminal wide.
-
-```
-  transcript ...                            | TODO             2/7
-                                            | ####------
-                                            |
-                                            | v  1 Read the reducer
-                                            | v  2 Design the store
-                                            | >  3 Wiring the rail into
-                                            |      AppShell
-                                            | o  4 Add the panel-rows test
-                                            | o  5 Update the README
-                                            |      +2 more
-```
-
-Ask for something small and nothing appears. The agent is told, in its system
-prompt, **not** to use the tool for anything it can finish in one or two steps,
-for a question, or for a search with no work attached — and a one-item list
-against an empty plan is refused outright. A session that never plans has
-byte-identical layout to a build without this feature.
-
-**The list is a projection of what the model believes**, so nothing that does
-not also tell the model may change it:
-
-- `/clear` wipes the transcript but not the conversation, so the plan stays.
-- `/reset` clears the conversation, so the plan goes with it.
-- `/save` writes the list and `/resume` restores it. Resuming a session that has
-  no list clears the current one, rather than leaving a plan on screen whose
-  conversation has just been replaced.
-- A finished plan is dropped at the START of your next message, so you still get
-  to see `7/7 done`. An unfinished one survives "continue" / "now do the rest",
-  and is dropped after three unrelated turns rather than holding a fifth of the
-  screen for the rest of the session.
-
-### When a run ends with steps left
-
-By default you get a notice and `/todo continue` — nothing auto-continues on
-your behalf. `/todo continue` no longer says "continue the remaining items"; it
-sends the model the numbered list of steps that are still open, so a plan that
-scrolled out of the context window some turns ago is still followed exactly.
-
-`/todo follow auto` (or `--todo-follow auto`, or `todo.followThrough` in
-`config.json`) turns that into an actual loop: the CLI announces
-`Continuing with 4 remaining steps in 3s - Esc to stop.`, waits, and then sends
-the continuation itself. Two structural limits bound it, and neither is a
-setting:
-
-- A continuation that completes no step buys exactly **one** more attempt.
-  After that you get a sentence and the keyboard back.
-- A single plan is continued at most **25** times however productive it looks.
-  A re-plan forgives the first counter but never the second, so a model that
-  reshapes its list every turn cannot lift the ceiling.
-
-`Esc` during the grace window cancels; so does typing anything. A run that ended
-with an **error** never auto-continues in any mode — you get a warning instead.
-A run **you** aborted with `Esc` now says nothing at all, where it used to
-report what you had just interrupted.
-
-`/todo follow off` is the third mode: no notice, no continuation, silence.
-
-Under `-p` there is no grace window (there is nobody there to use it), so the
-two counters are the whole of the protection. `[todo] continuing (3 steps left)`
-goes to stderr before each continuation and `[todo] 3 steps unfinished` when it
-stops; both are suppressed by `--quiet`, and an unfinished plan never changes
-the exit code.
-
-### Inline mode
-
-Inline mode has no fixed frame and therefore no rail, but it does get a one-row
-plan strip under the transcript:
-
-```
-todo 3/7  >  Adding the rail to AppShell                        +2 done
-```
-
-It never wraps and never grows past one row, so the composer does not move. The
-`+N done` suffix drops below 80 columns and the counter compacts to `[3/7]`
-below 100, matching the status bar. `--no-todo-panel` hides the strip as well as
-the rail.
-
-`/todo` reports status and switches things off: `/todo off` unregisters nothing
-(the tool list is fixed when the session starts) but stops the tool working and
-drops the guidance from the system prompt, while `/todo panel off` keeps the
-planning discipline and hides the column — which is what you want with a screen
-reader, and what `--no-todo-panel` does for a whole session. Under `-p` the plan
-is written to stderr as `[todo] 3/7 <step>` lines, suppressed by `--quiet`.
-
-The rail is not mounted below 80 columns, while an overlay is open, in inline
-mode, or when the viewport is too short to say anything useful; the transcript
-keeps at least 62 columns at every width. In those cases the counter appears in
-the status bar instead, and the checklist is still written into the transcript
-as one card per turn.
-
-## Built-in tools
-
-`read_file`, `write_file`, `edit_file`, `list_dir`, `glob`, `grep`, `bash` — all
-at full permission. Paths resolve against the session working directory. The
-per-tool timeout and 100 KB output truncation are enforced by the core executor;
-`bash`'s `timeout` param only shrinks within that ceiling.
-
-When skills are enabled, four more are added — the two read tools `skill` and
-`skill_find`, then the two mutating ones `skill_install` and `skill_create` (see
-below). `--no-skills` removes them again. Updating a skill is deliberately not
-among them; that is a `aragon skills update` decision for you, not the model.
-
-With team mode on — which is the default — one more is added: `task`, the
-delegation tool (see below). `--no-team` removes it again.
-
-With todo planning on — also the default — one more is added: `todo_write`, the
-planning tool (see above). `--no-todo` removes it again.
-
-## Team subagents
-
-The agent can hand parts of a job to short-lived **subagents** that run in
-parallel, then read one combined report of what they each found. It decides for
-itself whether to delegate; a session that never calls `task` is the session
-that existed before this feature.
-
-```
-> read the auth middleware, map the route table, and check the migration
-
- ◆ team  2 running · 1 done · 84s                             ✉ 1
- ⠋ a1  read the auth middleware      tool: grep         22.1s
- ⠙ a2  map the route table           thinking           31.6s
- ✔ a3  check the migration           done  4 turns      18.2s
-```
-
-**What a subagent is.** A full agent with its own message history, the same
-tools and the same working directory — but no memory of your conversation, so
-its brief has to be self-contained. It cannot delegate further (depth is capped
-at one by construction) and it cannot ask you anything.
-
-**Delegate wide, not deep.** Two to four subagents is the usual size. The
-default cap is 5 per dispatch and 3 in flight at once; the hard maximum is 10
-and no config file can raise it. `maxConcurrent` is separate from `maxSubagents`
-on purpose: five simultaneous streams against one API key is a reliable way to
-collect rate-limit errors, and each one would land in the report as a failed
-subagent.
-
-**The report.** One text result: a header with the ok/failed counts, aggregate
-tokens and cost, then one section per subagent with its status, timing, the
-files it wrote and its own final summary. A failed subagent never fails the
-dispatch — partial results are the normal outcome of a fan-out. When two
-subagents wrote the same file the header says so, phrased as a warning rather
-than a fact: the file list is derived from `write_file` / `edit_file`, so a
-write made through `bash` is invisible to it.
-
-**Talking to each other.** Subagents get two extra tools, `team_send` and
-`team_wait`. Messages are delivered by attaching them to the recipient's next
-tool result, so nobody has to poll and nobody's work is interrupted. The limits
-are the point rather than an afterthought: **6 messages per subagent, one every
-15 seconds, 24 per dispatch**, a broadcast costing two. Every refusal is a plain
-result naming the limit, never an error — an error reads as a malfunction and
-invites a retry, which is the behaviour the limits exist to prevent.
-
-**What you see.** While a dispatch runs, the roster above sits between the
-transcript and the composer and the status bar carries `agents 3/5` (`[3]` under
-100 columns). Both disappear when it finishes and the transcript keeps a card
-with the per-agent results; `Ctrl+O` expands it to their summaries. Under `-p`
-the same transitions go to stderr as `[team] a1 ok 22.1s 7 tools` lines, and the
-children's tokens are folded into the `[usage]` footer.
-
-**Interaction with the other subsystems.**
-
-- **Plan mode reaches one level down.** In PLAN, every subagent is built with
-  the same read-only gate, so `write_file` / `edit_file` / `bash` are refused
-  inside them too. Parallel research is plan mode's best use, so `task` itself
-  is allowed. A single subagent can be pinned read-only with `readOnly: true`
-  even in a BUILD session — the field can only ever tighten.
-- **A skill's `allowed-tools` ceiling reaches one level down too**, so
-  delegating is not a way around it. Subagents get `skill_find` but not `skill`:
-  loading a skill mutates a turn-scoped registry the lead owns, and three
-  subagents doing it at once would narrow what the lead may do next in a way
-  nothing would report. Always-on skills still reach them.
-- **`--confirm`** queues subagent confirmations one at a time, labelled with the
-  subagent that is asking (`[a2] Write: src/routes.ts`).
-- **Logs.** `dispatch_start` and `dispatch_end` are recorded at `info` with the
-  ok / failed / aborted counts and aggregate usage; phase transitions at
-  `debug`. A `team_send` subject is recorded, never its body; a subagent's brief
-  and summary only at `trace`.
-
-**`Esc`** aborts the whole dispatch — every subagent within a couple of seconds
-— and the report comes back marked `ABORTED` with whatever was finished.
-
-## Skills
-
-A skill is a reusable expert procedure stored on disk: a directory containing a
-`SKILL.md` (YAML frontmatter + Markdown body) and, optionally, `reference/`,
-`scripts/` and `assets/`. The format matches Claude Code's, so an existing
-community skill directory works as-is.
-
-### Progressive disclosure
-
-This is the part that makes skills cheap enough to install a lot of:
-
-| Level | What the model gets | When |
-| --- | --- | --- |
-| 1 | Name, scope, and a one-line "what + when" | Always, in the system prompt. Whole catalog capped at 6 000 bytes. |
-| 2 | The full `SKILL.md` body + a list of bundled files | Only when the model calls `skill(name=…)` |
-| 3 | The bundled files themselves | Only when it reads them with `read_file` / `bash` |
-
-A skill costs a line in the prompt rather than its whole body, so installing
-many of them stays cheap. The model decides on its own whether a task matches a
-skill — you do not have to name one.
-
-At Level 2 the file list is split into what to read and what to run, and carries
-the skill's absolute root so the model can build real paths. The accompanying
-guidance is **platform-specific**: on Windows the `bash` tool runs `cmd.exe`, so
-the model is told to run `.py` with `python <abs path>` and that a `.sh` file
-will not work — rather than the previous, flatly untrue "run scripts with bash".
-`aragon skills doctor` warns when a skill bundles only scripts for the other
-shell.
-
-**How many fit in Level 1 depends on your descriptions, and on the language they
-are written in.** The 6 000-byte ceiling is measured in UTF-8 bytes: a terse
-English description costs roughly 180 bytes a line (~30 skills), while a Chinese
-one at the 220-character cap can cost 660 (~10 skills). Past that point the
-catalog truncates.
-
-Truncation is not a dead end. Entries are ranked before it happens, and what
-falls off is still reachable:
-
-- **Ranking**: scope first (`env` > `project` > `user` > `bundled`), then how
-  recently and how often you have actually used each skill. A skill you ran an
-  hour ago outranks one you have never used, so what survives truncation is what
-  you actually work with — not whatever sorts first alphabetically.
-- **`skill_find`**: when the catalog *does* truncate, it says so and names this
-  tool, which searches everything installed by name, description and keyword.
-  It only ever searches **what is already on this machine** — it never reaches
-  the network and never suggests something to install.
-
-Both are off the critical path: with no usage data recorded the order is exactly
-the plain scope-then-name order, and `skill_find` is only advertised in the
-prompt when something was actually omitted.
-
-### Using them
-
-```bash
-aragon skills list [--sort=recent]          # what is installed
-aragon skills info <name>                   # version, path, provenance, files
-aragon skills install <source> [--yes]      # dir | git repo | https .md / .zip
-aragon skills install github:owner/repo#v1.2.0
-aragon skills update <name> [--yes] [--force] [--dry-run]
-aragon skills update --all [--yes]          # every skill that has an upstream
-aragon skills update --check [<name>|--all] # is there a newer version?
-aragon skills remove <name> [--yes]
-aragon skills create <name> --description "what + when" [--yes]
-aragon skills path                          # user skills directory
-aragon skills doctor                        # validate + detect tampering
-aragon skills usage [--json]                # local use counters
-aragon skills usage --reset --yes           # delete them
-aragon skills trust <dir>                   # allow a project skills directory
-```
-
-#### Updating
-
-`update` re-fetches a skill from the source recorded in its install manifest,
-keeping `installedAt` and recording `updatedAt` + `previousVersion`.
-
-- **Local edits are protected.** If you have changed an installed skill, `update`
-  refuses and names the files, *before downloading anything*. `--force`
-  overwrites them — and **`--force` discards your edits**; copy them out first.
-  The replaced directory is parked under the staging trash, so a mistake is
-  recoverable by hand.
-- **The host allowlist is re-checked** against your *current*
-  `skills.allowedHosts`, not the one in force when you installed. Narrowing that
-  list therefore also constrains updates.
-- **`--all` never stops on one failure.** Skills that cannot be updated
-  (hand-authored, bundled, or locally modified) are reported as `skipped`, which
-  is not an error; only a genuine I/O or validation failure exits non-zero.
-- **`--check` reports `unknown` freely.** It compares the commit recorded at
-  install time against `git ls-remote`, so it can only answer for git sources
-  installed by a version that records one. Anything else is honestly reported as
-  unknown rather than guessed.
-- **The model cannot call `update`.** Installing is something you pointed it at;
-  swapping working instructions for different ones is a maintenance decision and
-  stays with you.
-
-Interactively the same lives under `/skills …` (`/skills update <name> [--force]`,
-`/skills update --all`, `/skills list --sort=recent`, `/skills policy [mode]`,
-`/skills unload`, `/skills usage [--reset]`). Every usable skill also becomes a
-slash command:
-
-```
-/pdf-forms invoice.pdf --flatten
-```
-
-Both delivery paths share `skills.bodyMaxBytes`, so an oversized `SKILL.md` is
-truncated with a visible marker rather than submitted whole. Loading the same
-skill twice in one conversation returns a short digest (description, file list,
-guidance) instead of a second copy of the body; the model can ask for the full
-text back with `skill(name="…", force=true)`.
-
-Bodies may use `$ARGUMENTS` and `$1..$9`; `$$` is a literal `$`. If a skill
-declares no placeholder, the arguments are appended under an `## Arguments`
-heading instead. Where a skill's name collides with a built-in command, the
-**built-in wins** and the skill is reachable as `/skill:<name>`.
-
-### Where skills come from
-
-Four scopes, later ones overriding earlier ones by name:
-
-| Scope | Location | Writable |
-| --- | --- | --- |
-| `bundled` | `<package>/skills/` | no |
-| `user` | `aragon skills path` | yes — the default install target |
-| `project` | `<cwd>/.aragon/skills/` | yes |
-| `project` | `<cwd>/.claude/skills/` | no — read-only Claude Code interop |
-| `env` | `ARAGON_SKILLS_PATH` (`:`/`;`-separated) | no |
-
-A shadowed skill is not lost: `/skills` shows it as `~shadowed by <scope>`.
-
-### Frontmatter
-
-```yaml
----
-name: pdf-forms          # required, kebab-case, ≤ 64 chars
-description: Fill, flatten and validate AcroForm PDFs. Use when the task
-  mentions PDF forms, field filling, or flattening a fillable PDF.
-version: 1.2.0
-license: MIT
-author: Jane Doe
-homepage: https://github.com/jane/pdf-forms
-keywords: [pdf, forms]
-allowed-tools: [read_file, bash]   # enforced as a per-turn tool ceiling (union)
-activation: auto                   # auto | always | manual
----
-```
-
-`description` is the only text a model sees before deciding to load the skill,
-so it has to say both what the skill does and when to use it. Unknown keys are
-preserved, so a newer Claude Code field will not break parsing.
-
-`activation: always` injects the body into every session's system prompt (12 000
-bytes total across all such skills); `manual` keeps it out of the catalog so it
-runs only when explicitly invoked.
-
-### Security model — and its limits
-
-Be clear about what this does and does not buy you:
-
-- **Installing requires a human.** The approval gate checks whether a person is
-  actually reachable *before* asking, and refuses when nobody is. Under `-p`
-  there is no TUI and therefore no approver, so `skill_install` fails with an
-  actionable message instead of writing to disk unattended. Opt out
-  deliberately with `--skills-yes` or `skills.requireApproval=false`.
-- **Project directories need trusting once.** Cloning an unfamiliar repository
-  does not grant it the right to inject instructions into your session.
-- **Nothing is executed at install time.** No postinstall, no dependency
-  install; the executable bit is not preserved. Scripts run only when the model
-  invokes `bash`.
-- **Archives are gated on real bytes** — total size, per-entry size, compression
-  ratio and entry count, all abortable mid-extraction. Path traversal,
-  absolute paths, symlinks and Windows device names are refused.
-- **Git is never run through a shell**, and ref / owner / repo fragments are
-  whitelisted and refused if they start with `-`.
-- **Third-party text cannot break out of its prompt block**: angle brackets in
-  descriptions, bodies and file names are neutralized before rendering.
-
-- **A changed `SKILL.md` is noticed at load time.** Every install records a
-  sha256; discovery re-checks the one file that reaches the model's context and
-  flags it as `!modified` if it no longer matches what you approved. See
-  `skills.integrity` below.
-- **Concurrent installs cannot corrupt a skill.** Writes take a per-directory
-  advisory lock, so two `aragon` processes installing at once queue instead of
-  interleaving their atomic-replace steps. *Limit:* the lock relies on exclusive
-  file creation, which is not reliably atomic on every NFS implementation. It
-  self-expires after 60 seconds and waits at most 5, so the worst case there is
-  no mutual exclusion — never a hang.
-
-What it does **not** do: there is **no sandbox**. Approval blocks *silent*
-installation; it does not make a skill you approved safe. A skill you accept can
-contain adversarial instructions, and its scripts run with your full user
-permissions — the same trust model as pasting text into the prompt and the same
-as the `bash` tool. `/skills info` records provenance and a sha256 per file so
-you can audit what arrived and notice if it changed. The integrity check answers
-"is this still the file I approved?", **not** "is this file from someone I
-trust" — there is no signing and no key distribution.
-
-`allowed-tools` **is** enforced now (see below), but read the next section before
-treating it as a permission boundary: it is blast-radius control, not a security
-boundary, and a skill can widen its own ceiling by loading another skill.
-
-### The tool ceiling (`allowed-tools`)
-
-A skill that declares `allowed-tools` constrains which tools the model may use
-**for the rest of the current turn**:
-
-```yaml
-allowed-tools: [read_file, write_file]
-```
-
-- **Scope is one turn.** The ceiling appears when a skill is loaded — by the
-  model calling `skill(...)`, or by you running `/<skill-name>` — and it is gone
-  as soon as you send the next message. A skill you used this morning does not
-  restrict unrelated work this afternoon.
-- **Read-only tools are always allowed**, declared or not: `read_file`,
-  `list_dir`, `glob`, `grep`, plus `skill` and `skill_find`. What the declaration
-  actually controls is the five tools that change something — `write_file`,
-  `edit_file`, `bash`, `skill_install`, `skill_create`.
-- **Claude Code names work.** `[Read, Bash, MultiEdit]` maps onto this host's
-  `read_file` / `bash` / `edit_file`. Tools that exist there but not here
-  (`WebFetch`, `Task`, `TodoWrite`, …) are ignored rather than treated as errors.
-- **A name we cannot resolve waives the whole declaration**, and says so. One
-  typo means that skill imposes no ceiling at all — never a narrower one you did
-  not write. `aragon skills doctor` reports these up front.
-- **`activation: always` skills never impose a ceiling.** They are ambient
-  reference material, not a procedure you chose to run.
-
-Three modes, via `skills.toolPolicy` (default `enforce`),
-`aragon --skill-tool-policy <mode>` for one run, or `/skills policy <mode>` for
-the current session (which takes effect immediately, even mid-turn):
-
-| Mode | Behaviour |
-| --- | --- |
-| `enforce` | The call is refused; the model is told what it may use instead. |
-| `warn` | The call runs, and you get one notice per tool per turn. |
-| `off` | No ceiling, and nothing about `allowed-tools` reaches the model. |
-
-`/skills unload` drops the ceiling for the current turn. It does **not** remove
-skill text already in the conversation — nothing can.
-
-**What this is and is not.** It is **blast-radius control, not a security
-boundary**. The declaration is written by the skill's own author, so a malicious
-skill can simply declare `[bash]`. Its value is that a declaration is now
-binding: you can read one in `/skills info` and decide whether to install, and an
-honest author's `[read_file]` means a "while you're there, run `rm -rf`" line
-smuggled into that skill's text — or into a file it tells the model to read —
-cannot execute.
-
-**And a known limit:** the ceiling is a **union** across every skill loaded this
-turn, and `skill` is always available. So a skill can widen its own ceiling by
-instructing the model to load a second, more permissive skill. This is not
-blocked — blocking it would either strand the model inside a skill it cannot
-escape, or break every multi-skill workflow — but every widening is printed to
-the transcript:
-
-```
-Tool ceiling widened by skill "skill-creator": +write_file, +skill_create
-```
-
-So it stops the smuggled instruction; it does not stop a skill that deliberately
-teaches the model to reach for another one.
-
-### Usage counters
-
-To rank the catalog, the CLI keeps a small file next to your skills directory:
-
-```jsonc
-// <aragon skills path>/../skill-usage.json
-{ "schema": 1, "skills": { "deploy-preview": { "useCount": 12, "lastUsedAt": 1785050000000 } } }
-```
-
-**It contains the skill name, a count, and a timestamp. Nothing else** — no
-arguments, no conversation content, no working directory, no machine identifier.
-It is never transmitted anywhere, by anything. Delete it whenever you like; the
-only effect is that the catalog falls back to plain scope-then-name order. Set
-`skills.usageTracking=false` to switch it off entirely, after which the file is
-neither read nor written.
-
-Automatically injected `activation: always` skills are deliberately **not**
-counted — they load on every turn, so counting them would say nothing about what
-you actually use.
-
-## Configuration
-
-Config is layered (highest priority last): **defaults → user config file →
-env / `.env` → CLI flags**.
-
-- **Env / `.env`**: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`,
-  `GOOGLE_API_KEY` / `GEMINI_API_KEY`, plus `ARAGON_PROVIDER`, `ARAGON_MODEL`,
-  `ARAGON_BASE_URL`, `ARAGON_THINKING`,
-  `ARAGON_MAX_TOKENS` (a number, or `auto` / `0` for the per-model ceiling),
-  `ARAGON_THEME`,
-  `ARAGON_FULLSCREEN`, `ARAGON_PLAN` (`1` starts in plan mode),
-  `ARAGON_TEAM` (`0` disables team subagents), `ARAGON_TEAM_MAX` (fan-out width),
-  `ARAGON_TODO` (`0` disables todo planning entirely),
-  `ARAGON_TODO_FOLLOW` (`notify` / `auto` / `off`),
-  `ARAGON_SKILLS` (`0` disables), `ARAGON_SKILLS_PATH`,
-  `ARAGON_SKILLS_DISABLED` (comma-separated names), `ARAGON_LOG_LEVEL`,
-  `ARAGON_LOG_FILE` (`0` disables), `ARAGON_LOG_DIR`.
-  `ARAGON_HOME` is the exception that **cannot** come from `.env`: it is read
-  before any `.env` is loaded. See [Files & logs](#files--logs).
-- **User config file** (`aragon config path`): JSON, written `0600` on POSIX.
-  Holds provider / model / keys and your preferences, and nothing else — the
-  prompts you type and the counters behind one-time notices live in their own
-  files (see [Files & logs](#files--logs)). Keys are masked in the UI and never
-  logged. It lives in your home directory — see [Files & logs](#files--logs) —
-  and editing it by hand is supported: `aragon config edit` opens it, and an
-  invalid edit is reported rather than silently resetting every setting.
-
-| Config key | Default | Meaning |
-| --- | --- | --- |
-| `maxTokens` | `64000` | Output token cap, clamped to `[256, 200000]`. `null` means **auto** — use each model's own ceiling, never above 64000. Absent means the default. See [Output token limits](#output-token-limits). |
-| `fullscreen` | `true` | Use the full-screen TUI (still subject to the automatic downgrades). Setting it to `false` opts out permanently; leaving it `true` is *not* a force — only `--fullscreen` / `ARAGON_FULLSCREEN=1` override the heuristics. |
-| `exitTranscript` | `true` | Replay a plain-text session summary after exiting (full-screen only). |
-| `transcriptWindow` | `300` | How many trailing entries the full-screen viewport renders, clamped to `[50, 2000]`. The full history stays in memory and in `/save`. |
-| `planModeDefault` | `false` | Start every session in plan mode. `--no-plan` still overrides it for a single run. |
-| `planModeMaxAskRounds` | `4` | `ask_user` rounds allowed per user message, clamped to `[1, 10]`. The counter resets on your next message; steering does **not** reset it. |
-| `planModeHumanTimeoutMs` | `1800000` | Ceiling on a single question / plan wait, clamped to `[60000, 7200000]`. Thirty minutes is far outside "went to get coffee", but a ceiling has to exist so an unattended terminal cannot wedge a CI job forever. |
-| `historyEnabled` | `true` | Record submitted prompts to `prompt-history.jsonl` for `↑` recall. Setting it to `false` stops new writes; it does not delete what is already stored (that is `aragon history clear --yes`) and does not stop reading. See [Prompt history](#prompt-history). |
-| `team.enabled` | `true` | Master switch for team subagents. `false` means the `task` tool is never registered — `/team on` in such a session saves the setting for next launch and says so, rather than advertising a tool that is not there. |
-| `team.maxSubagents` | `5` | Subagents per dispatch, clamped to `[1, 10]`. The 10 is the hard ceiling and is enforced twice — on the config value and again on what the model asks for — so hand-editing this file cannot raise it. |
-| `team.maxConcurrent` | `3` | Subagents in flight at once, clamped to `[1, 10]` and capped at `maxSubagents`. A separate knob because provider rate limits are a different constraint from context economics. |
-| `team.subagentTimeoutMs` | `300000` | One subagent's wall clock before it is aborted, clamped to `[30000, 1800000]`. A wedged subagent dies on its own ceiling without taking the dispatch with it. |
-| `team.dispatchTimeoutMs` | `900000` | The whole dispatch's wall clock, clamped to `[60000, 3600000]`. |
-| `team.maxTurnsPerSubagent` | `24` | Runaway-loop cap, clamped to `[4, 100]`. A subagent stopped here is reported as `stopped: turn cap reached`, with whatever it had produced. |
-| `todo.enabled` | `true` | Master switch for todo planning. `false` means the `todo_write` tool is never registered — `/todo on` in such a session saves the setting for next launch and says so, rather than advertising a tool that is not there. |
-| `todo.panel` | `true` | Render the right-hand rail (and, in inline mode, the one-row plan strip). Independent of `todo.enabled` on purpose: a screen-reader user wants the planning discipline without the column, and the system prompt varies one sentence accordingly. |
-| `todo.followThrough` | `"notify"` | What happens when a run ends with steps left. `notify` says so and stops; `auto` continues the plan after a 3-second grace window, bounded by two structural limits (one fruitless attempt, 25 continuations per plan) that are deliberately **not** settings; `off` is silent. An unrecognized value falls back to `notify`. |
-| `skills.enabled` | `true` | Master switch for the skill system. |
-| `skills.requireApproval` | `true` | Require a human to approve `skill_install` / `skill_create`. |
-| `skills.catalogMaxBytes` | `6000` | Level 1 catalog ceiling, in UTF-8 **bytes**, clamped to `[500, 40000]`. |
-| `skills.bodyMaxBytes` | `30000` | Level 2 body ceiling, in UTF-8 **bytes**, clamped to `[1000, 50000]`. |
-| `skills.allowedHosts` | GitHub / GitLab hosts | Hosts an install **or update** may fetch from. Re-checked on every update, not just at install time. |
-| `skills.disabled` | `[]` | Skill names switched off. |
-| `skills.trustedProjectDirs` | `[]` | Project skill directories you have trusted. |
-| `skills.integrity` | `warn` | What to do when `SKILL.md` no longer matches the copy you approved. `off` skips the check; `warn` flags it in `/skills list` and once per session; `strict` removes it from the catalog and makes `skill()` refuse it. Defaults to `warn` because editing an installed skill is a legitimate thing to do — `strict` suits CI and managed environments. |
-| `skills.usageTracking` | `true` | Keep local per-skill use counters to rank the catalog. Name, count and timestamp only; never transmitted. Inspect with `aragon skills usage`, erase with `--reset --yes`. |
-| `skills.toolPolicy` | `enforce` | How hard a skill's `allowed-tools` bites, for the turn it is loaded in. `off` disables it and says nothing about it to the model; `warn` runs the tool and reports it; `enforce` refuses. Unlike `skills.integrity`, a false positive here means a skill AUTHOR under-declared their own skill — which `aragon skills doctor` reports before it can bite. |
-| `log.level` | `info` | `silent` · `error` · `warn` · `info` · `debug` · `trace`. See [Files & logs](#files--logs) for what each level records. |
-| `log.toFile` | `true` | Write records to a file at all. `false` here is respected; `--log-file` overrides it for one run. |
-| `log.dir` | `""` | Log directory. Empty means `<home>/logs`. Only **absolute** paths are accepted — a relative one would mean a different directory for every working directory you launch from. |
-| `log.maxFileBytes` | `5242880` | Rotate once a file would exceed this, clamped to `[65536, 268435456]`. |
-| `log.maxFiles` | `10` | Files kept in the log directory, clamped to `[1, 200]`. The oldest beyond this are deleted — on rotation **and** on the first write of each day. |
-| `log.redactSecrets` | `true` | Run every record through redaction. Setting it to `false` is the one way to get credentials onto disk, so it prints a warning and has no settings-screen entry. |
-| `log.previewChars` | `512` | How much user content `debug` keeps per field, clamped to `[0, 8192]`. `trace` is never truncated. |
-
-Byte, not character: `ToolExecutor` truncates at 100 000 **bytes**, so a
-character-based budget would be roughly triple its nominal size for CJK text
-and would get cut mid-tag.
-
-### Output token limits
-
-Every model and every provider defaults to **64000** output tokens. You never
-have to configure this, and if you never touch it the number stays 64000.
-
-The number you set is an **ambition, not a promise**: it is clamped down to
-whatever the target model actually accepts. `gpt-4o` caps at 16384 and
-`gemini-1.5-pro` at 8192, and sending 64000 to either is an HTTP 400 that ends
-the turn — so `aragon` sends what the model will take, silently. When the model
-is one it has never seen (a proxy, an endpoint behind `--base-url`, a model that
-shipped last week), it sends 64000, and if the provider objects it reads the real
-ceiling out of the provider's own error, repairs the request, sends it again, and
-remembers the answer for the rest of the session. You see one warning line and
-the run continues.
-
-Four ways to change it, highest priority first:
-
-```bash
-aragon --max-tokens 32000            # this run only
-aragon --max-tokens auto             # this run only, per-model ceiling
-ARAGON_MAX_TOKENS=32000 aragon       # env layer, between the flag and the file
-aragon config set maxTokens 32000    # persisted; prints "Set maxTokens = 32000"
-aragon config set maxTokens auto     # persisted as null
-aragon config set maxTokens default  # back to 64000
-aragon config get maxTokens          # "64000" | "auto"
-```
-
-Inside the TUI, `/max-tokens` reports the current setting **and** the effective
-cap for the live model, and `/max-tokens <n|auto|default>` changes it. The
-settings screen (`/settings`) has the same field with an `Effective:` line under
-it, so a value the model will not honour is visible before you save it.
-
-And by hand, in `~/.aragon-agent/config.json` (`aragon config path` prints the
-exact location; `aragon config edit` opens it, and `/reload` picks up an edit
-made in another window):
-
-```jsonc
-{
-  "version": 1,
-  "provider": "anthropic",
-  "model": "claude-sonnet-4-5-20250929",
-
-  // Output token cap.
-  //   64000  (or any 256..200000 integer) — an explicit cap, clamped down to
-  //          the target model's real ceiling when that ceiling is lower.
-  //   null   — auto: use each model's own ceiling, never above 64000.
-  //   absent — the product default, 64000.
-  "maxTokens": 64000
-}
-```
-
-Out-of-range numbers are clamped on the way in **and** on the way out, so a
-hand-edited `900000` becomes `200000` on disk rather than reverting to the
-default on every launch.
-
-Extended thinking is reconciled with the cap automatically: `--thinking xhigh`
-asks for a 65536-token budget, Anthropic requires `max_tokens` to be strictly
-greater than it, and the two are resolved together rather than left to collide.
-
-These are additive: a config file written by an earlier version loads
-unchanged, with no migration and no version bump.
-
-## Files & logs
-
-Everything AragonAgent keeps for you lives under one directory in your home:
-
-```
-~/.aragon-agent/                    (Windows: C:\Users\<you>\.aragon-agent\)
-├── config.json                     settings + API keys (0600 on POSIX)
-├── config.json.bak                 written by `aragon config edit` before it opens
-├── prompt-history.jsonl            prompts you submitted, for ↑ recall (0600 on POSIX)
-├── state.json                      UI bookkeeping: submit count, one-shot notices
-├── logs/
-│   ├── aragon-2026-07-27.log       today, JSON Lines
-│   └── aragon-2026-07-27.1.log     rotated at log.maxFileBytes
-├── sessions/                       /save and /resume
-├── skills/                         aragon skills install
-└── skill-usage.json
-```
-
-`config.json` holds **settings only**. What you typed and how often you have
-typed it live in the two files next to it, so that editing your config means
-scrolling past your own settings and nothing else, and so that submitting a
-prompt no longer rewrites the file that holds your API keys.
-
-`ARAGON_HOME` moves the whole tree. **It cannot come from a `.env` file** — the
-path is resolved when the process starts, long before a `.env` is read — so set
-it as a real environment variable. `aragon config home` always prints the
-directory actually in use.
-
-Upgrading from 0.5.0 or earlier moves your config, sessions and skills here
-automatically, once, and prints a line on stderr when it does. The old
-`%APPDATA%\aragon-agent-nodejs` / `%LOCALAPPDATA%\aragon-agent-nodejs`
-directories are **left in place** so that reinstalling an older build stays
-lossless; `aragon config home` names them, and you can delete them once you are
-satisfied.
-
-### Prompt history
-
-Every prompt you submit is appended to `~/.aragon-agent/prompt-history.jsonl`,
-one JSON object per line, so that `↑` recalls it — in this session and in every
-later one. It is written `0600` on POSIX, it never leaves the machine, and it is
-**stored verbatim**: a redacted history would recall the wrong text, which is
-worse than not recalling at all.
-
-The last 100 distinct prompts are what `↑` walks. The file is rewritten down to
-that many entries once it passes 400 lines, and a single submission longer than
-16 KiB is not recorded at all rather than recorded truncated.
-
-```bash
-aragon history path           # where it is, plus a reminder of what is in it
-aragon history list -n 50     # the 50 most recent, newest first
-aragon history list --json    # raw entries with timestamps
-aragon history clear --yes    # delete the file
-```
-
-Set `historyEnabled` to `false` (`aragon config set historyEnabled false`) to
-stop recording. Switching it off does **not** delete what is already stored —
-`aragon history clear --yes` does that — and reading keeps working either way,
-so you can look before you erase.
-
-Upgrading from 0.5.x moves an existing `promptHistory` out of `config.json` into
-this file once, automatically and silently.
-
-### What gets logged
-
-Logs are local files. Nothing is uploaded, ever — there is no network path out
-of this subsystem at all.
-
-| Level | Records | Contains your content? |
-| --- | --- | --- |
-| `error` | crashes, failed requests, config write/parse failures | no |
-| `warn` | degraded migrations, clamped values, dropped records | no |
-| `info` *(default)* | start/exit, config writes, turn boundaries with token counts, tool names and durations | **no** |
-| `debug` | the above, plus prompts, replies and tool arguments truncated to `log.previewChars` | yes, truncated |
-| `trace` | full message bodies and full tool output | yes, in full |
-
-The default is `info` specifically so that attaching a log to a bug report is
-safe. **`debug` and `trace` write what you typed and what the model replied** —
-check before sharing one.
-
-API keys are removed at every level, by two independent passes: any field whose
-name looks like a credential is blanked whatever it holds, and every string is
-scanned for known key formats *and* for the literal keys this process is
-holding. The second half is what covers a custom endpoint whose key looks like
-nothing in particular. Setting `log.redactSecrets false` disables both, and says
-so on stdout when you do.
-
-### Commands
-
-```bash
-aragon logs path              # where records are going right now, and at what level
-aragon logs list              # files, sizes, timestamps
-aragon logs tail -n 50        # render the last 50 records
-aragon logs tail --follow     # keep printing new ones
-aragon logs tail --json       # raw JSON Lines, for jq
-aragon logs tail --level warn # only warn and above
-aragon logs clear --yes       # delete every log file
-aragon logs open              # open the directory in your file manager
-
-aragon history path           # where prompt history is kept
-aragon history list -n 50     # the 50 most recent prompts, newest first
-aragon history clear --yes    # delete the prompt history
-
-aragon config home            # the user-state root (and whether ARAGON_HOME set it)
-aragon config get log.level   # one value; secrets always masked
-aragon config list --json     # everything; secrets always masked here too
-aragon config edit            # open config.json in $VISUAL / $EDITOR
-```
-
-Per-run overrides, none of which are persisted:
-
-```bash
-aragon --log-level debug "…"   # or --verbose, which means the same thing
-aragon --no-log-file "…"       # nothing reaches a file this run
-aragon --log-dir D:\logs "…"
-```
-
-`ARAGON_LOG_LEVEL`, `ARAGON_LOG_FILE=0` and `ARAGON_LOG_DIR` do the same from the
-environment, and unlike `ARAGON_HOME` these three *can* come from a `.env`.
-
-### Insecure TLS opt-in
-
-When `NODE_TLS_REJECT_UNAUTHORIZED` is the exact string `0`, the installed or
-locally built `aragon` process honors that setting and suppresses only Node's
-standard insecure-TLS warning. Every unrelated process warning remains visible,
-and any other value leaves warning behavior unchanged. The check happens when a
-warning is emitted, so a `0` loaded from the project `.env` is covered too; the
-CLI never creates, normalizes, or persists this variable.
-
-> **Security warning:** `0` genuinely disables certificate verification. It does
-> not make an insecure connection safe and can expose credentials or request
-> contents to interception. Use it only in a controlled environment where you
-> accept that risk.
-
-The automatic filter starts with the `aragon` process. An earlier `npm install`
-or `npx` bootstrap belongs to npm and is outside the installed package's process
-boundary, so that parent may still print Node's warning. The official repository
-release flow covers its npm children through `publish-latest.ps1`; callers that
-own another npm/npx parent must preload the filter in that parent themselves if
-quiet output is required.
-
-### Theming & color
-
-`--theme` / `config.theme` / `/theme` pick a palette: `warm`, `cool`, `light`, or
-`auto` (which resolves to `warm` — terminals can't reliably report their
-background). `dark` remains accepted everywhere as an alias for `cool`.
-Colors degrade automatically to your terminal's depth (truecolor → 256 → 16 →
-monochrome) and glyphs fall back to ASCII on terminals without Unicode. Color is
-disabled — and the UI renders plain monochrome with ASCII glyphs — when any of
-`NO_COLOR`, `--no-color`, `TERM=dumb`, or `config.color=false` is set; `FORCE_COLOR`
-is respected. `reducedMotion` (also `ARAGON_REDUCED_MOTION`, and implied by
-`--no-color`) replaces spinners with a static glyph.
-
-### Timeout invariant
-
-The core idle watchdog (60 s by default) is **shorter** than the tool timeout
-(120 s), so a long single tool run (a build, `npm install`) would be killed
-mid-run. The CLI fixes this by always constructing the agent with
-`idleTimeout ≥ toolTimeout` (defaults 210 s ≥ 180 s), re-derived after config
-merge. Raise both `--tool-timeout` / `--idle-timeout` for genuinely long jobs.
-
-## Development
-
-```bash
-npm run build -w packages/cli   # tsc + shebang → dist/cli.js
-npm test    -w packages/cli     # vitest
-node packages/cli/dist/cli.js --version
-```
-
-### Manual smoke checklist
-
-- `npm run build -w packages/cli` produces an executable `dist/cli.js` with a
-  shebang; `node packages/cli/dist/cli.js --version` prints the version.
-- `npm pack -w packages/cli --dry-run --json` lists `dist/cli.js` under `files`.
-- With `ANTHROPIC_API_KEY` set: `aragon` streams a reply, a tool card renders,
-  `Esc` aborts mid-run, `/model` switches models, `/settings` saves a key,
-  `Ctrl+C` twice exits.
-- `echo "list files" | node dist/cli.js -p` prints an answer and exits `0`.
-- A missing/invalid key produces a visible, actionable message (never a blank
-  screen), both in the TUI and headless.
-- `Shift+Tab` at 40, 80 and 120 columns - the chip, the hint and the status bar
-  are all legible and nothing wraps onto a second row.
-- The question wizard at 24 rows with 5 questions x 4 options - no clipping, and
-  the `n/N` counter matches what is on screen.
-- Approve a plan and watch the SAME run start writing files, with no second
-  prompt.
-- `--no-color` on a legacy `cmd.exe` - the chip renders `[PLAN]`, radios render
-  `*`/`o`, checkboxes render `[x]`/`[ ]`, no mojibake anywhere.
-- A plan with a 600-character summary and a 400-character step detail - the text
-  wraps and scrolls, the footer count matches the real number of rows, and
-  nothing is truncated to a single line.
-- `--no-hints` on a 20-row terminal in plan mode - the status bar still says
-  `PLAN` with no chip on screen.
-- Dismiss a plan card with `Esc`, let the agent resubmit, then press `Esc` twice:
-  the run aborts and the session returns to an idle prompt. Do this one BY HAND
-  as well as in a test - the point of the check is whether the exit is findable,
-  which no assertion can tell you.
-
-## License
-
-MIT
+# @aragon-agent/cli
+
+A Claude-Code / Codex-style **interactive terminal UI** for the
+[`@aragon-agent/core`](../core) engine. Type a task, watch the agent think and
+stream its answer, see each tool call render as a live card, and interrupt /
+steer / configure the session — all without leaving the terminal.
+
+> ⚠️ **Full permission, no sandbox.** This first version runs at **maximum
+> permission**: `bash` executes directly, file writes hit the real filesystem,
+> and there is **no per-action approval gate by default**. Only run it in
+> workspaces you trust. An opt-in confirmation mode is available via `--confirm`.
+
+## Install
+
+```bash
+# Global
+npm i -g @aragon-agent/cli
+aragon
+
+# Zero-install
+npx @aragon-agent/cli
+```
+
+> **Release note (R3):** `npx @aragon-agent/cli` resolves `@aragon-agent/core`
+> from the npm registry, so `@aragon-agent/core@^0.1.0` must be published first
+> (or bundled into the CLI `dist`). During local development inside this
+> monorepo, npm workspaces link the local `packages/core` automatically.
+
+## Quick start
+
+```bash
+# Set a key (any one of these)
+export ANTHROPIC_API_KEY=sk-ant-...
+# ...or paste it live in the TUI via /settings, or pass --api-key
+
+aragon                       # interactive TUI
+aragon "summarize README.md" # interactive, auto-submitting the prompt
+echo "list files" | aragon -p   # one-shot, prints to stdout then exits
+```
+
+## Usage
+
+```
+aragon [prompt]                 Start the interactive TUI (or one-shot with -p / piped stdin)
+aragon -p, --print [prompt]     Headless: stream the answer to stdout, then exit
+aragon config                   Open the settings screen
+aragon config set <key> <value> Non-interactive config write (e.g. model, provider)
+aragon config path              Print the config file path
+aragon models [--provider p]    List builtin + discovered models
+aragon --version | -v           Print the version
+aragon --help  | -h             Print help
+```
+
+### Global flags
+
+| Flag | Meaning |
+| --- | --- |
+| `--provider <id>` | `anthropic` \| `openai` \| `google` |
+| `--model <id>` | Model id |
+| `--base-url <url>` | Override the provider base URL (OpenAI-compatible endpoints) |
+| `--api-key <key>` | One-shot key override (not persisted) |
+| `--thinking <level>` | `off\|minimal\|low\|medium\|high\|xhigh` |
+| `--max-tokens <n\|auto>` | Output token cap: a number, or `auto` for the model's own ceiling (default `64000`) |
+| `--cwd <dir>` | Working directory for tools |
+| `--confirm` | Confirm each mutating tool call |
+| `--tool-timeout <ms>` | Per-tool executor ceiling (default 180000) |
+| `--idle-timeout <ms>` | Watchdog idle timeout (auto-raised to ≥ tool-timeout + 30s) |
+| `--theme <name>` | `auto\|warm\|cool\|light` (`dark` is a compatibility alias for `cool`) |
+| `--compact` / `--no-compact` | Transcript density: no blank rows between turns, or the default |
+| `--hints` / `--no-hints` | Show or hide the composer hint row |
+| `--show-thinking` / `--no-show-thinking` | Draw the model's reasoning blocks in the transcript. Off by default — see [What you see while it runs](#what-you-see-while-it-runs) |
+| `--live-tool-output` / `--no-live-tool-output` | Show a bounded tail of a running command's output on its card. **On** by default — see [What you see while it runs](#what-you-see-while-it-runs) |
+| `--fullscreen` | Force the full-screen TUI, overriding the automatic downgrades |
+| `--no-fullscreen` | Force the inline renderer (the 0.2.0 behavior) |
+| `--no-exit-transcript` | Do not replay the session summary after exiting |
+| `--plan` / `--no-plan` | Start the session in PLAN mode (read-only research + review) or force BUILD |
+| `--team` / `--no-team` | Enable or disable team subagents. `--no-team` does not register the `task` tool at all |
+| `--team-max <n>` | Max subagents per dispatch for this run, clamped to `[1, 10]` |
+| `--todo` / `--no-todo` | Enable or disable todo planning. `--no-todo` does not register the `todo_write` tool at all |
+| `--todo-panel` / `--no-todo-panel` | Show or hide the right-hand todo rail. The tool stays registered either way |
+| `--todo-follow <mode>` | What happens when a run ends with steps left: `notify` (default), `auto`, `off` |
+| `--retry` / `--no-retry` | Retry a failed provider call with backoff (the default), or fail on the first error |
+| `--retry-max <n>` | Retries after the first attempt for this run, clamped to `[0, 20]`. `0` turns retry off |
+| `--fast` / `--no-fast` | Enable or disable the fast model tier. Off by default; see **Fast model tier** |
+| `--fast-model <id>` | The fast model id. Implies nothing about `--fast` on its own |
+| `--fast-provider <id>` | Provider for the fast model. Absent inherits the main provider |
+| `--fast-review <n\|off>` | Turns between automatic fast reviews, or `off` |
+| `--no-skills` | Disable the skill system entirely (no catalog, no skill tools) |
+| `--skill <name>` | Force-load a skill's full body for this run (repeatable) |
+| `--skills-yes` | Approve skill installs for this run (CI / headless) |
+| `--transcript-retain <n>` | Entries kept in memory, clamped to `[200, 20000]`. Older ones are dropped and counted |
+| `--render-governor` / `--no-render-governor` | Adapt the frame interval under load, or pin it at 33 ms |
+| `--max-render-interval <ms>` | Governor ceiling, clamped to `[33, 1000]`. `33` flattens the ladder |
+| `--no-color` | Disable ANSI color |
+| `--quiet` | (print mode) suppress tool/usage lines on stderr |
+
+Exit codes: `0` success · `1` agent/runtime error · `2` config/usage error ·
+`130` interrupted.
+
+## Slash commands (interactive)
+
+| Command | Action |
+| --- | --- |
+| `/help` | Keybindings + command help |
+| `/model` | Open the model picker |
+| `/settings` | Open the settings screen |
+| `/thinking <level>` | Set the thinking level |
+| `/max-tokens [<n>\|auto\|default]` | Output token cap; with no argument, reports the setting **and** the effective cap for the live model |
+| `/tools` | List active tools |
+| `/clear` | Clear the visible transcript |
+| `/reset` | New conversation |
+| `/cwd [dir]` | Show / change the tool working directory |
+| `/save [file]` | Save the session to JSON |
+| `/resume [file]` | Load a saved session |
+| `/plan [on\|off\|status]` | Toggle plan mode - the keyboard-free equivalent of `Shift+Tab` |
+| `/team [on\|off\|max <n>]` | Team subagents: status and the live roster, the on/off switch, the fan-out width |
+| `/todo [on\|off\|panel on\|off\|follow <mode>\|clear\|continue]` | Todo planning: status, the on/off switch, the rail, follow-through, and picking an unfinished plan back up |
+| `/retry [show\|on\|off\|max <n>]` | API retry: the effective ladder, the on/off switch, the retry count. Takes effect **in the running session**, children included |
+| `/fast [on\|off\|model <id>\|provider <id>\|same\|review <n\|off>\|delegate on\|off]` | Fast model tier: status and this session's totals, the on/off switch, which model, the review cadence |
+| `/theme <auto\|warm\|cool\|light>` | Switch the color theme live (persisted) |
+| `/expand [n]` | Expand / collapse the n-th-from-last (default last) tool card |
+| `/copy` | Copy the last answer to the clipboard |
+| `/perf` | What the renderer is doing: frame interval, mounted entries, dropped entries, cache occupancy. `/perf reset` clears the caches and the governor |
+| `/logs` | Show where this session is being logged, and at what level |
+| `/reload` | Re-read `config.json` after editing it in another window (refused mid-run) |
+| `/skills [sub]` | List and manage skills (see below) |
+| `/<skill-name> [args]` | Run an installed skill directly |
+| `/exit` (`/quit`) | Exit |
+
+A leading `/` meant literally can be escaped as `//`. Typing `/` opens a
+command palette and `@` opens a file-path completion popup — `Tab` / `→`
+completes, `Up` / `Down` moves the selection, `Esc` closes it.
+
+## Keybindings
+
+| Key | Action |
+| --- | --- |
+| `Enter` | Submit (idle) / queue a steering message (running) |
+| `Alt+Enter` / `Shift+Enter` | Insert a newline |
+| `Shift+Tab` | Toggle **plan mode** (`BUILD` <-> `PLAN`). Equivalent: `/plan` |
+| `Esc` | Abort the run / close an overlay / close a popup |
+| `Ctrl+C` ×2 | Exit (first press warns) |
+| `Ctrl+L` | Redraw the frame (clear the screen in inline mode) |
+| `Ctrl+T` | Show / hide thinking (**off by default**). In inline mode it applies to the live entry and everything drawn after it — settled entries are already in your terminal's scrollback and cannot be repainted |
+| `Ctrl+O` | Expand / collapse the most recent tool card — including its diff |
+| `PgUp` / `PgDn` | Scroll the transcript a page (full-screen mode) |
+| `Shift+↑` / `Shift+↓` | Scroll the transcript a line (full-screen mode) |
+| Mouse wheel | Scroll the transcript (or the open overlay) |
+| `Shift`+wheel | Scroll the transcript a page |
+| `Home` / `End`, `Ctrl+A` / `Ctrl+E` | Cursor to line start / end |
+| `Alt/Ctrl+←` / `→` | Word-wise cursor jump |
+| `Ctrl+W`, `Alt+Backspace` | Delete the previous word |
+| `Ctrl+U` / `Ctrl+K` | Kill to line start / end |
+| `Up` / `Down` | Move between draft lines; recall prompt history at the edges |
+| `?` | Open help (empty input) |
+
+In **full-screen mode** the transcript is scrolled by the app itself: `PgUp` /
+`PgDn` and `Shift+↑` / `Shift+↓`. While pinned to the bottom the viewport follows
+new output automatically; once you scroll away the status bar shows `↑N`, a slim
+rail on the right edge shows where you are, and a hint counts the lines below
+you. Submitting a message always re-pins to the newest output. In **inline mode**
+(`--no-fullscreen`) history lives in your terminal's native scrollback, printed
+once via Ink `<Static>`.
+
+**The mouse wheel is a viewport gesture and nothing else.** Wherever the pointer
+happens to be — including right on top of the composer — a notch scrolls the
+transcript three rows (a page with `Shift`), or scrolls the overlay when one is
+open. It never touches your draft, and it never recalls prompt history: that is
+`↑` / `↓`, and only `↑` / `↓`.
+
+Two things follow from the app owning the mouse, and they are worth knowing
+before you meet them:
+
+- **Selecting text now needs `Shift`+drag** in most terminals. That is the
+  terminal's convention for "an application is tracking the mouse", not
+  something this CLI can opt out of while still reading wheel events.
+- **`tmux` with `mouse on` keeps the wheel for itself**, so the app never sees
+  it. `set -g mouse off` hands it back.
+
+Turn the whole thing off with `--no-mouse`, `ARAGON_MOUSE=0`, or
+`aragon config set mouse false`. With mouse support off the wheel simply does
+nothing in full-screen mode — it does not fall back to editing your draft, which
+is what it used to do. Inline mode is unaffected either way.
+
+## Themes
+
+Three palettes plus `auto`:
+
+| Name | Look |
+| --- | --- |
+| `warm` | Terracotta + amber over warm neutrals. The default (`auto` resolves here). |
+| `cool` | The blue/violet palette that shipped as `dark` through 0.3.x. |
+| `light` | For light terminal backgrounds. |
+
+`auto` never guesses `light`: terminals cannot report their background reliably,
+and guessing wrong makes the app unreadable rather than merely wrong-looking.
+
+**Migrating from 0.3.x** — `dark` was renamed `cool` when `warm` became the
+default, and the old name still works everywhere: `--theme dark`,
+`aragon config set theme dark`, `/theme dark`, and a config file containing
+`"theme": "dark"` all resolve to `cool`, so a screen you explicitly chose does
+not change under you. The value is rewritten as `cool` the next time the config
+is saved. Only users who never picked a theme see the new default.
+
+Density and hints are settable the same three ways: `--compact` / `--no-hints`
+for one run, `aragon config set density compact` / `aragon config set hints false`
+to persist. The composer hint row also shortens to `? help` on its own after a
+few sessions — except while a run is in progress, when it always spells out
+`esc abort` in full.
+
+## What you see while it runs
+
+Four rules, and each of them exists because the opposite was worse.
+
+**Reasoning is not shown.** A model at `thinkingLevel: high` emits more
+chain-of-thought than answer, and it used to scroll the answer and the tool calls
+off the top of the screen. It is written for the model, not for you. So it is off
+by default, and a settled turn that thought leaves one muted row in its place:
+
+```
+  ✱ thought for 12s · ctrl+t to show
+```
+
+That row is the whole point — hiding information without saying that it exists
+is how a "clean" UI becomes a dishonest one. `Ctrl+T` shows the bodies for the
+session, `showThinking: true` (or `--show-thinking`, or `ARAGON_SHOW_THINKING=1`)
+shows them permanently, and `/settings` has a **Show thinking** row next to
+**Thinking**.
+
+In **inline** mode (`--no-fullscreen`) the marker reads `✱ thought for 12s` with
+no key hint, and the toast on `Ctrl+T` says `Thinking shown for new output.`
+Settled entries there have already been printed into your terminal's own
+scrollback, which cannot be repainted — so the key applies to the live entry and
+to everything drawn after it, and the row does not offer what it cannot deliver.
+
+**There is something to look at while it thinks.** One row above the composer,
+for as long as a run is in flight:
+
+```
+  ⠋ Percolating…
+```
+
+The word rotates every four seconds. It carries no clock and no token count on
+purpose: the status bar one row below already has both, under the same
+condition, driven by the same ticker. Under `reducedMotion` the spinner is a
+static glyph and the word is chosen once and holds — rotating text is motion too.
+An idle frame is exactly what it was before this existed, down to the row count.
+
+While a **tool** is in flight the row stops guessing and names it instead:
+
+```
+  ⠙ Running bash
+```
+
+`running` covers the whole turn, including the minutes the model is idle and a
+child process is doing the work. "Pondering" is right for the gap before the
+first token and simply untrue during a build.
+
+**A long command is not a blank card.** `bash` is the only tool here that can run
+for minutes — `npm test`, a `git clone`, a training job — and while it ran, its
+card used to be one line of text that never changed. Now it shows the last eight
+lines of what the command is printing, plus one honest footer row:
+
+```
+  bash npm test   ⠹ running
+  │  ✓ src/__tests__/patch.test.ts (49 tests)
+  │  ✓ src/__tests__/diff-view.test.tsx (9 tests)
+  │  (running)
+```
+
+and, when the child goes quiet, `no output for 45s` instead of a spinner that
+means nothing. A `\r`-driven progress bar — npm, pip, curl, docker — is *one*
+line rewritten a thousand times, and it renders as one row counting up in place,
+not a thousand rows of nearly the same string.
+
+**What the tail deliberately does not do.** It is a display, not a transcript.
+ANSI colour, cursor motion and every other control byte are **stripped**, not
+interpreted (keeping colour would mean validating it, and an unterminated escape
+leaks into the rest of the frame; interpreting cursor motion would mean owning a
+screen buffer). It keeps eight rows, so `Ctrl+O` does nothing while a command is
+running — expansion is a promise about stored content, and there is no stored
+rest of a 400 MB stream to show. It is not saved: `/save` during a run writes no
+tail, because a resumed one would describe a process that died with the session.
+And it never reaches the model — at settle the card is replaced by the
+authoritative result, exactly as before. Set `liveToolOutput: false` (or
+`--no-live-tool-output`, or `ARAGON_LIVE_TOOL_OUTPUT=0`, or the **Live output**
+row in `/settings`) and the card is a single `running` row again, with no store
+allocated and no recorder attached.
+
+**A file modification looks like a file modification.** `write_file` and
+`edit_file` now produce a real diff — hunks, line numbers, `+N -M`:
+
+```
+  +6 -5
+  1163   top level of the file where the section never takes effect. It
+  1164 - `applyFastConfigSet` (`:259`). A key missing from the list is
+  1164 + `applyFastConfigSet` (`:252`). A key missing from the list is
+  1165   `Unknown config key`; a key in the list but missing from the switch
+  +13 lines (Ctrl+O)
+```
+
+Creating a 300-line file is the single most consequential thing an agent does,
+and it used to be reported as a byte count. Diffs collapse at 12 rows behind the
+existing `Ctrl+O`; there is no new keybinding.
+
+**This costs the model nothing — it saves.** The structured patch reaches the
+screen on a CLI-local channel, not through the tool result, and the text the
+model reads gained a 4 000-character ceiling it did not have before. For a
+single-region edit that text is what it always was plus one `@@` header; for a
+multi-region edit it is strictly smaller, because a change at line 40 and one at
+line 900 are now two small hunks instead of 860 removed rows followed by 860
+near-identical added ones.
+
+## Full-screen mode
+
+`aragon` takes over the terminal's **alternate screen buffer** — the mechanism
+`vim`, `htop`, and `lazygit` use. Two consequences worth knowing:
+
+- Your previous shell output is **covered, not erased**, and returns untouched
+  when you exit. Nothing in your scrollback is destroyed.
+- The frame is fixed at `rows - 1` tall, which is what keeps the composer and the
+  status bar at the bottom of the screen even on an empty session.
+
+On exit the session is replayed into the normal buffer as plain text so the
+conversation survives leaving the screen (`--no-exit-transcript` opts out;
+`/save` still exports the full JSON).
+
+It downgrades to the inline renderer automatically when stdout is not a TTY,
+`TERM=dumb`, a CI environment variable is set, or the terminal is under 12 rows
+or 40 columns. `--fullscreen` overrides all of those except the non-TTY check —
+writing screen-control sequences into a pipe or a redirected file is never safe.
+`--no-fullscreen`, `ARAGON_FULLSCREEN=0`, or `aragon config set fullscreen false`
+opt out permanently.
+
+The terminal's native scrollback and mouse wheel do not scroll the transcript in
+this mode, and mouse tracking is deliberately left off because enabling it costs
+text selection and copy in most terminals. If a crash ever strands your terminal
+on the alternate screen, `reset` restores it.
+
+## Render performance
+
+A long session used to get slower and slower, and past a point it stopped
+responding at all. The cause was structural rather than incidental: Ink has no
+output caching, so every frame re-walked the whole mounted tree, re-measured
+every text node and re-serialised the frame. The cost was therefore proportional
+to **every character the session had ever produced**, not to the characters
+actually on screen — and `transcriptWindow` bounded the entry *count*, which is
+not the same thing when one entry can be fifty thousand lines.
+
+Four things changed, and you should not have to think about any of them:
+
+- **Off-screen entries are not mounted.** The viewport renders the band you can
+  see plus a couple of entries either side, and replaces the rest with two
+  spacers of the right height. Scrolling and the `↑N` readout are unchanged.
+- **The expensive pure work is cached.** Syntax highlighting and markdown
+  parsing now run once per distinct block instead of once per frame. Themes are
+  still applied at render time, so `/theme` takes effect immediately.
+- **The transcript is bounded.** A single answer cannot exceed 256 KiB in the
+  view, and `transcriptRetain` caps how many entries are kept. Both bounds
+  report what they removed rather than dropping it silently.
+- **The frame interval adapts.** If a frame is genuinely expensive, updates
+  coalesce into a wider window — 33 ms up to a 320 ms ceiling — so the terminal
+  stays responsive to typing and to `Ctrl+C`. A muted **`eco`** chip appears in
+  the status bar whenever this is in effect: the stream getting chunkier is
+  something you should be able to see a reason for.
+
+`/perf` reports exactly what the renderer is doing:
+
+```
+render     rung 2  -  interval 80ms  -  last commit 61ms  -  eco
+transcript 4213 entries  -  1000 retained  -  3213 dropped  -  38 mounted
+heights    412 cached  -  6 estimated  -  cols 132
+caches     md 178 (1.9MB)  -  hl 96 (1.4MB)  -  lines 340
+mode       fullscreen  -  viewport 44 rows  -  offset 0
+```
+
+`/perf reset` clears the render caches and returns the governor to its fastest
+rung. `--no-render-governor` (or `renderGovernor: false`, or
+`ARAGON_RENDER_GOVERNOR=0`) turns the adaptation off entirely; the output is
+identical, just heavier under load.
+
+**Inline mode** (`--no-fullscreen`, `TERM=dumb`, CI, a very small terminal) gets
+one extra guarantee. Ink repaints the *entire session history* on every frame
+once a live entry grows taller than the terminal, which is a genuine freeze
+rather than a slowdown. The live region is now clamped to stay below that
+threshold, with a `... N earlier lines` marker naming what is deferred; the
+entry prints **in full** into your scrollback the moment it finishes.
+
+## Plan mode
+
+`aragon` has two postures, and `Shift+Tab` switches between them. `/plan` does
+the same thing for terminals that swallow the key (see below).
+
+| Mode | What it means |
+| --- | --- |
+| `BUILD` | The default, and unchanged from earlier versions: you ask, the agent does it. |
+| `PLAN` | Research and design only. The agent reads, asks you the decisions it cannot settle by reading, and submits a plan for approval before anything is written. |
+
+`BUILD` is right for "rename this symbol". `PLAN` is right for "add multi-tenant
+support" — anything where you want to see and steer the *approach* before a
+single byte changes.
+
+### What plan mode actually stops
+
+In `PLAN`, five tools are refused at the tool boundary: `write_file`,
+`edit_file`, `bash`, `skill_install` and `skill_create`. That is a property of
+the wiring, not a promise in a prompt — the refusal happens before the tool runs,
+so the badge is telling you something that is structurally true.
+
+**`bash` is refused in full, `git status` included.** This is the most likely
+question this feature generates, so: there is no reliable way to classify a shell
+string as read-only, and a gate that is right 95 % of the time is worse than one
+that is always right, because you stop trusting the badge. Use `read_file`,
+`list_dir`, `glob` and `grep`, which stay available; the refusal message names
+them so the agent has somewhere to go. There is no allowlist and there will not
+be one built out of substring matching.
+
+Everything else still works: reading, searching, loading skills, and asking you
+questions.
+
+### The two plan-mode tools
+
+- **`ask_user`** renders a keyboard-driven wizard: 1–5 questions, 2–4 options
+  each, exactly one marked `RECOMMENDED`, plus an `Other…` free-text option.
+  `↑`/`↓` choose, `Enter` confirms and advances, `←` goes back, `Esc` cancels.
+  Pressing `Enter` through the whole wizard accepts every recommendation, which
+  is a deliberate "use your judgement" path rather than an accident. A last
+  screen lets you review before submitting.
+- **`submit_plan`** renders the plan as a scrollable card: `a` approves, `r`
+  opens a one-line feedback field (`Enter` sends it, `←` goes back to the card),
+  `Esc` dismisses. **Approving flips the session to `BUILD` immediately and the
+  same run continues straight into implementation** — you do not have to re-ask.
+
+Cancelling either one is not an error. The agent is told to proceed on stated
+assumptions rather than to retry.
+
+**Dismissing a plan is not how you stop.** `Esc` on a plan card asks for a
+*better* plan — the agent is told to refine it and submit again — so a model that
+keeps submitting keeps getting cards. To stop the run itself, **press `Esc`
+twice**: the first closes the card, the second aborts the run. `Ctrl+C` twice
+still exits the session outright.
+
+### Where the mode is shown
+
+The status bar always names a non-default mode (`PLAN`, or `PLAN → BUILD` while
+a switch is pending), including on short terminals, with `--no-hints`, and in
+inline mode. The composer additionally shows a `PLAN` chip on its hint row and
+tints its border, where there is room for it.
+
+### Switching mid-run
+
+Tightening applies at once; loosening waits. Pressing `Shift+Tab` toward `PLAN`
+during a run takes effect immediately — you pressed it *because* the agent is
+about to do something. Pressing it toward `BUILD` during a run is **deferred to
+the end of the run**, so a session you launched under a read-only guarantee
+cannot start writing files because of one stray keypress. The status bar shows
+`PLAN → BUILD` while that is pending. Approving a plan is the one exception, and
+it is an informed act rather than a stray keypress.
+
+### If `Shift+Tab` does nothing
+
+Some multiplexers and remote-desktop stacks never send `CSI Z`. `/plan`,
+`/plan on`, `/plan off` and `/plan status` are first-class equivalents, and
+`--plan` / `ARAGON_PLAN=1` / `planModeDefault` cover the startup case.
+
+### Headless
+
+`aragon -p --plan "add SSO"` is a useful combination: the read-only gate still
+applies, so it means *"tell me how you would do this, and do not touch my
+repository"*. No question or plan tool is registered there — there is nobody to
+ask — and the agent writes the finished plan as its final message in markdown.
+
+## TODO planning
+
+For work with three or more distinct steps the agent keeps a **visible plan**:
+it writes a checklist with the `todo_write` tool, marks exactly one item as in
+progress, and ticks it off before starting the next. In full-screen mode that
+list is rendered as a right-hand rail, about a fifth of the terminal wide.
+
+```
+  transcript ...                            | TODO             2/7
+                                            | ####------
+                                            |
+                                            | v  1 Read the reducer
+                                            | v  2 Design the store
+                                            | >  3 Wiring the rail into
+                                            |      AppShell
+                                            | o  4 Add the panel-rows test
+                                            | o  5 Update the README
+                                            |      +2 more
+```
+
+Ask for something small and nothing appears. The agent is told, in its system
+prompt, **not** to use the tool for anything it can finish in one or two steps,
+for a question, or for a search with no work attached — and a one-item list
+against an empty plan is refused outright. A session that never plans has
+byte-identical layout to a build without this feature.
+
+**The list is a projection of what the model believes**, so nothing that does
+not also tell the model may change it:
+
+- `/clear` wipes the transcript but not the conversation, so the plan stays.
+- `/reset` clears the conversation, so the plan goes with it.
+- `/save` writes the list and `/resume` restores it. Resuming a session that has
+  no list clears the current one, rather than leaving a plan on screen whose
+  conversation has just been replaced.
+- A finished plan is dropped at the START of your next message, so you still get
+  to see `7/7 done`. An unfinished one survives "continue" / "now do the rest",
+  and is dropped after three unrelated turns rather than holding a fifth of the
+  screen for the rest of the session.
+
+### When a run ends with steps left
+
+By default you get a notice and `/todo continue` — nothing auto-continues on
+your behalf. `/todo continue` no longer says "continue the remaining items"; it
+sends the model the numbered list of steps that are still open, so a plan that
+scrolled out of the context window some turns ago is still followed exactly.
+
+`/todo follow auto` (or `--todo-follow auto`, or `todo.followThrough` in
+`config.json`) turns that into an actual loop: the CLI announces
+`Continuing with 4 remaining steps in 3s - Esc to stop.`, waits, and then sends
+the continuation itself. Two structural limits bound it, and neither is a
+setting:
+
+- A continuation that completes no step buys exactly **one** more attempt.
+  After that you get a sentence and the keyboard back.
+- A single plan is continued at most **25** times however productive it looks.
+  A re-plan forgives the first counter but never the second, so a model that
+  reshapes its list every turn cannot lift the ceiling.
+
+`Esc` during the grace window cancels; so does typing anything. A run that ended
+with an **error** never auto-continues in any mode — you get a warning instead.
+A run **you** aborted with `Esc` now says nothing at all, where it used to
+report what you had just interrupted.
+
+`/todo follow off` is the third mode: no notice, no continuation, silence.
+
+Under `-p` there is no grace window (there is nobody there to use it), so the
+two counters are the whole of the protection. `[todo] continuing (3 steps left)`
+goes to stderr before each continuation and `[todo] 3 steps unfinished` when it
+stops; both are suppressed by `--quiet`, and an unfinished plan never changes
+the exit code.
+
+### Inline mode
+
+Inline mode has no fixed frame and therefore no rail, but it does get a one-row
+plan strip under the transcript:
+
+```
+todo 3/7  >  Adding the rail to AppShell                        +2 done
+```
+
+It never wraps and never grows past one row, so the composer does not move. The
+`+N done` suffix drops below 80 columns and the counter compacts to `[3/7]`
+below 100, matching the status bar. `--no-todo-panel` hides the strip as well as
+the rail.
+
+`/todo` reports status and switches things off: `/todo off` unregisters nothing
+(the tool list is fixed when the session starts) but stops the tool working and
+drops the guidance from the system prompt, while `/todo panel off` keeps the
+planning discipline and hides the column — which is what you want with a screen
+reader, and what `--no-todo-panel` does for a whole session. Under `-p` the plan
+is written to stderr as `[todo] 3/7 <step>` lines, suppressed by `--quiet`.
+
+The rail is not mounted below 80 columns, while an overlay is open, in inline
+mode, or when the viewport is too short to say anything useful; the transcript
+keeps at least 62 columns at every width. In those cases the counter appears in
+the status bar instead, and the checklist is still written into the transcript
+as one card per turn.
+
+## Built-in tools
+
+`read_file`, `write_file`, `edit_file`, `list_dir`, `glob`, `grep`, `bash` — all
+at full permission. Paths resolve against the session working directory. The
+per-tool timeout and 100 KB output truncation are enforced by the core executor;
+`bash`'s `timeout` param only shrinks within that ceiling.
+
+When skills are enabled, four more are added — the two read tools `skill` and
+`skill_find`, then the two mutating ones `skill_install` and `skill_create` (see
+below). `--no-skills` removes them again. Updating a skill is deliberately not
+among them; that is a `aragon skills update` decision for you, not the model.
+
+With team mode on — which is the default — one more is added: `task`, the
+delegation tool (see below). `--no-team` removes it again.
+
+With todo planning on — also the default — one more is added: `todo_write`, the
+planning tool (see above). `--no-todo` removes it again.
+
+## Team subagents
+
+The agent can hand parts of a job to short-lived **subagents** that run in
+parallel, then read one combined report of what they each found. It decides for
+itself whether to delegate; a session that never calls `task` is the session
+that existed before this feature.
+
+```
+> read the auth middleware, map the route table, and check the migration
+
+ ◆ team  2 running · 1 done · 84s                             ✉ 1
+ ⠋ a1  read the auth middleware      tool: grep         22.1s
+ ⠙ a2  map the route table           thinking           31.6s
+ ✔ a3  check the migration           done  4 turns      18.2s
+```
+
+**What a subagent is.** A full agent with its own message history, the same
+tools and the same working directory — but no memory of your conversation, so
+its brief has to be self-contained. It cannot delegate further (depth is capped
+at one by construction) and it cannot ask you anything.
+
+**Delegate wide, not deep.** Two to four subagents is the usual size. The
+default cap is 5 per dispatch and 3 in flight at once; the hard maximum is 10
+and no config file can raise it. `maxConcurrent` is separate from `maxSubagents`
+on purpose: five simultaneous streams against one API key is a reliable way to
+collect rate-limit errors, and each one would land in the report as a failed
+subagent.
+
+**The report.** One text result: a header with the ok/failed counts, aggregate
+tokens and cost, then one section per subagent with its status, timing, the
+files it wrote and its own final summary. A failed subagent never fails the
+dispatch — partial results are the normal outcome of a fan-out. When two
+subagents wrote the same file the header says so, phrased as a warning rather
+than a fact: the file list is derived from `write_file` / `edit_file`, so a
+write made through `bash` is invisible to it.
+
+**Talking to each other.** Subagents get two extra tools, `team_send` and
+`team_wait`. Messages are delivered by attaching them to the recipient's next
+tool result, so nobody has to poll and nobody's work is interrupted. The limits
+are the point rather than an afterthought: **6 messages per subagent, one every
+15 seconds, 24 per dispatch**, a broadcast costing two. Every refusal is a plain
+result naming the limit, never an error — an error reads as a malfunction and
+invites a retry, which is the behaviour the limits exist to prevent.
+
+**What you see.** While a dispatch runs, the roster above sits between the
+transcript and the composer and the status bar carries `agents 3/5` (`[3]` under
+100 columns). Both disappear when it finishes and the transcript keeps a card
+with the per-agent results; `Ctrl+O` expands it to their summaries. Under `-p`
+the same transitions go to stderr as `[team] a1 ok 22.1s 7 tools` lines, and the
+children's tokens are folded into the `[usage]` footer.
+
+**Interaction with the other subsystems.**
+
+- **Plan mode reaches one level down.** In PLAN, every subagent is built with
+  the same read-only gate, so `write_file` / `edit_file` / `bash` are refused
+  inside them too. Parallel research is plan mode's best use, so `task` itself
+  is allowed. A single subagent can be pinned read-only with `readOnly: true`
+  even in a BUILD session — the field can only ever tighten.
+- **A skill's `allowed-tools` ceiling reaches one level down too**, so
+  delegating is not a way around it. Subagents get `skill_find` but not `skill`:
+  loading a skill mutates a turn-scoped registry the lead owns, and three
+  subagents doing it at once would narrow what the lead may do next in a way
+  nothing would report. Always-on skills still reach them.
+- **`--confirm`** queues subagent confirmations one at a time, labelled with the
+  subagent that is asking (`[a2] Write: src/routes.ts`).
+- **Logs.** `dispatch_start` and `dispatch_end` are recorded at `info` with the
+  ok / failed / aborted counts and aggregate usage; phase transitions at
+  `debug`. A `team_send` subject is recorded, never its body; a subagent's brief
+  and summary only at `trace`.
+
+**`Esc`** aborts the whole dispatch — every subagent within a couple of seconds
+— and the report comes back marked `ABORTED` with whatever was finished.
+
+## Fast model tier
+
+A second, cheaper model can be made a first-class citizen of a session. It is
+**off by default** — with `fast.enabled: false` the system prompt, the `task`
+tool schema, the transcript and the request payloads are exactly what they were
+before this feature existed — and it buys you two things once you turn it on.
+
+**Delegation (the agent decides).** `task` gains one optional field per
+subagent, `model: "fast"`. A child marked that way runs on the fast model and is
+otherwise identical: same tools, same working directory, same `--confirm` gate,
+same plan-mode gate, same skills ceiling. Delegating to a cheaper model is a
+*model* choice, never a permission boundary. This is where "not complicated, but
+very expensive in context" is actually paid for: a child that reads nine files
+and reports four sentences moves ~200 KB of file bodies out of the lead's window
+and onto a model that costs a fraction as much per token.
+
+**Periodic review (the harness decides).** Every *N* completed turns, a small
+digest of what the lead has been doing goes to the fast model with one question
+— is this still on track? — and if the answer is not "on track" it is injected
+back into the running loop as a `<fast_review>` block. The lead sees a short
+second opinion mid-run, when it can still act on it, for a few hundred tokens
+instead of a second full-size turn.
+
+```
+> refactor the config loader and keep the tests green
+
+  fast review #2 · claude-haiku-4-5 · turn 12 · 1.4s
+  You have edited config/schema.ts three times without running the tests.
+  The clamp for reviewEveryTurns is missing its upper bound.
+```
+
+**The digest is bounded, and that is the whole economic argument.** The reviewer
+keeps its own ring of recent turns — the tools you called, whether they failed,
+the tail of what the model said — and never reads the message history. Sending
+that history to the "cheap" model would make a review cost more than the turn it
+is reviewing.
+
+**Cost is attributed per tier.** A fast-tier subagent's tokens are priced at the
+fast model's table, not the lead's, and the dispatch report states the two
+separately. If the fast model is not in the built-in price table the number is
+shown as `unknown` rather than as `$0.00` — a feature that looks free while it
+is spending money is worse than one that admits it does not know.
+
+**The review has a session budget, and delegation deliberately does not.** A
+session is not one run — it is one run per message you send — so a cadence alone
+bounds nothing over a working afternoon. `fast.reviewMaxPerSession` (default
+**40**) is the total number of reviews a session may *start*; reaching it prints
+one `info` notice naming the remedy, and `/fast status` reads `12/40` from the
+first review rather than a bare count you can only size afterwards. Raise it live
+with `/fast budget 80`. The budget is denominated in **reviews, not currency**,
+because the fast tier is precisely where a model the price table has never seen
+lives — a dollar ceiling would silently never fire for the configuration that
+most needs one. Delegation is never budgeted: it is spend the lead chose in
+service of a message you sent, it is already bounded by `team.*`, and it exists
+to *reduce* total cost.
+
+### Turning it on
+
+```bash
+aragon config set fast.model claude-haiku-4-5
+aragon config set fast.enabled true
+```
+
+or, in a session: `/fast model claude-haiku-4-5` then `/fast on`. Either way the
+tier is on for the next launch; `/fast on` in a session that started without it
+saves the setting and says so, because the `task` schema is fixed at startup and
+cannot grow a field mid-session.
+
+| key | default | meaning |
+|---|---|---|
+| `fast.enabled` | `false` | Resolve the tier at all. |
+| `fast.provider` | `''` | Empty inherits the main provider. |
+| `fast.model` | `''` | The fast model id. Empty means *not configured* — it never falls back to the main model, so "same as main" stays distinguishable from a typo. |
+| `fast.baseUrl` | `''` | Empty inherits the session's base URL **only** when the provider matches. |
+| `fast.thinkingLevel` | `'off'` | Applied to fast children and to reviews. |
+| `fast.delegate` | `true` | Allow `model:"fast"` on `task`. |
+| `fast.review` | `true` | Run the periodic review. |
+| `fast.reviewEveryTurns` | `5` | Turns between reviews (1–50). |
+| `fast.reviewContextTurns` | `3` | Turns included in one digest (1–10). |
+| `fast.reviewMaxChars` | `280` | Ceiling on an injected critique (80–600). |
+| `fast.reviewMaxPerSession` | `40` | Reviews started per session, across all runs (1–500). There is no "unlimited" sentinel. |
+
+**Flags:** `--fast` / `--no-fast`, `--fast-model <id>`, `--fast-provider <id>`,
+`--fast-review <n|off>`. **Environment:** `ARAGON_FAST`,
+`ARAGON_FAST_PROVIDER`, `ARAGON_FAST_MODEL`, `ARAGON_FAST_BASE_URL` — the four
+that a container or a wrapper owning argv cannot otherwise reach. There is
+deliberately no env var for the review cadence: tuning it is what the config
+file is for.
+
+**`/fast`** is the discoverable surface and `/fast status` is the guaranteed
+reporting one:
+
+```
+/fast                      status, the resolved model, the cadence, session totals
+/fast on | off             live switch
+/fast model <id>           accepts provider:model
+/fast provider <id>
+/fast same                 run the fast tier on the main model
+/fast review <n> | off
+/fast budget [n]           the session review budget; bare form reads it
+/fast delegate on | off
+```
+
+`/fast budget` with no argument is a **read**, so it is answerable while a `task`
+dispatch is running; `/fast budget <n>` is a write and is refused mid-dispatch
+like every other `/fast` setting.
+
+**What you see.** A `fast` chip in the status bar's right cluster while the tier
+is live (`fast*` while a review is in flight, dropped below 100 columns), a
+one-line card per review in the transcript, and `n fast` plus a trailing `~` on
+fast children in the team roster. `/fast status` reports the session totals the
+status bar cannot: reviews run, children delegated, tokens and cost. Under `-p`
+nothing extra is written to stdout or stderr — the review spend is folded into
+the `[usage]` footer and the reviews are in the log.
+
+**When the tier stops resolving.** `fast.provider: ''` inherits from the main
+provider, so switching model or clearing a key can leave the tier unusable
+mid-session. When that happens `model:"fast"` is downgraded to the main model,
+the downgrade is **counted and stated in the dispatch report**, and one notice
+names the reason. A silent downgrade would leave the agent believing its cost
+model while paying full price.
+
+**When the review fails.** Three consecutive *misconfiguration* failures (a
+wrong model id, a dead gateway, a key with no access) disable the reviewer for
+the session with exactly one warning. A busy provider — rate-limited or
+overloaded — is treated as transient and never counts, because that condition
+fixes itself and a session-long silent shutdown over it would not. A review that
+you *cancelled* — Esc, a run that ended first, quitting — is neither: it leaves a
+`cancelled` card and no strike.
+
+**The review fails fast, and your own work does not.** The reviewer calls through
+its own provider registry with **one** retry — not the ten `retry.maxRetries`
+defaults to for the lead — and it does not observe `retry.*` or `/retry` at all.
+That policy is a statement about how hard to fight for *your* answer; inheriting
+it for a background advisory is how an unrequested call ends up competing with
+you for a rate-limited provider's quota. The review's own wall-clock bound is
+20 s.
+
+## Skills
+
+A skill is a reusable expert procedure stored on disk: a directory containing a
+`SKILL.md` (YAML frontmatter + Markdown body) and, optionally, `reference/`,
+`scripts/` and `assets/`. The format matches Claude Code's, so an existing
+community skill directory works as-is.
+
+### Progressive disclosure
+
+This is the part that makes skills cheap enough to install a lot of:
+
+| Level | What the model gets | When |
+| --- | --- | --- |
+| 1 | Name, scope, and a one-line "what + when" | Always, in the system prompt. Whole catalog capped at 6 000 bytes. |
+| 2 | The full `SKILL.md` body + a list of bundled files | Only when the model calls `skill(name=…)` |
+| 3 | The bundled files themselves | Only when it reads them with `read_file` / `bash` |
+
+A skill costs a line in the prompt rather than its whole body, so installing
+many of them stays cheap. The model decides on its own whether a task matches a
+skill — you do not have to name one.
+
+At Level 2 the file list is split into what to read and what to run, and carries
+the skill's absolute root so the model can build real paths. The accompanying
+guidance is **platform-specific**: on Windows the `bash` tool runs `cmd.exe`, so
+the model is told to run `.py` with `python <abs path>` and that a `.sh` file
+will not work — rather than the previous, flatly untrue "run scripts with bash".
+`aragon skills doctor` warns when a skill bundles only scripts for the other
+shell.
+
+**How many fit in Level 1 depends on your descriptions, and on the language they
+are written in.** The 6 000-byte ceiling is measured in UTF-8 bytes: a terse
+English description costs roughly 180 bytes a line (~30 skills), while a Chinese
+one at the 220-character cap can cost 660 (~10 skills). Past that point the
+catalog truncates.
+
+Truncation is not a dead end. Entries are ranked before it happens, and what
+falls off is still reachable:
+
+- **Ranking**: scope first (`env` > `project` > `user` > `bundled`), then how
+  recently and how often you have actually used each skill. A skill you ran an
+  hour ago outranks one you have never used, so what survives truncation is what
+  you actually work with — not whatever sorts first alphabetically.
+- **`skill_find`**: when the catalog *does* truncate, it says so and names this
+  tool, which searches everything installed by name, description and keyword.
+  It only ever searches **what is already on this machine** — it never reaches
+  the network and never suggests something to install.
+
+Both are off the critical path: with no usage data recorded the order is exactly
+the plain scope-then-name order, and `skill_find` is only advertised in the
+prompt when something was actually omitted.
+
+### Using them
+
+```bash
+aragon skills list [--sort=recent]          # what is installed
+aragon skills info <name>                   # version, path, provenance, files
+aragon skills install <source> [--yes]      # dir | git repo | https .md / .zip
+aragon skills install github:owner/repo#v1.2.0
+aragon skills update <name> [--yes] [--force] [--dry-run]
+aragon skills update --all [--yes]          # every skill that has an upstream
+aragon skills update --check [<name>|--all] # is there a newer version?
+aragon skills remove <name> [--yes]
+aragon skills create <name> --description "what + when" [--yes]
+aragon skills path                          # user skills directory
+aragon skills doctor                        # validate + detect tampering
+aragon skills usage [--json]                # local use counters
+aragon skills usage --reset --yes           # delete them
+aragon skills trust <dir>                   # allow a project skills directory
+```
+
+#### Updating
+
+`update` re-fetches a skill from the source recorded in its install manifest,
+keeping `installedAt` and recording `updatedAt` + `previousVersion`.
+
+- **Local edits are protected.** If you have changed an installed skill, `update`
+  refuses and names the files, *before downloading anything*. `--force`
+  overwrites them — and **`--force` discards your edits**; copy them out first.
+  The replaced directory is parked under the staging trash, so a mistake is
+  recoverable by hand.
+- **The host allowlist is re-checked** against your *current*
+  `skills.allowedHosts`, not the one in force when you installed. Narrowing that
+  list therefore also constrains updates.
+- **`--all` never stops on one failure.** Skills that cannot be updated
+  (hand-authored, bundled, or locally modified) are reported as `skipped`, which
+  is not an error; only a genuine I/O or validation failure exits non-zero.
+- **`--check` reports `unknown` freely.** It compares the commit recorded at
+  install time against `git ls-remote`, so it can only answer for git sources
+  installed by a version that records one. Anything else is honestly reported as
+  unknown rather than guessed.
+- **The model cannot call `update`.** Installing is something you pointed it at;
+  swapping working instructions for different ones is a maintenance decision and
+  stays with you.
+
+Interactively the same lives under `/skills …` (`/skills update <name> [--force]`,
+`/skills update --all`, `/skills list --sort=recent`, `/skills policy [mode]`,
+`/skills unload`, `/skills usage [--reset]`). Every usable skill also becomes a
+slash command:
+
+```
+/pdf-forms invoice.pdf --flatten
+```
+
+Both delivery paths share `skills.bodyMaxBytes`, so an oversized `SKILL.md` is
+truncated with a visible marker rather than submitted whole. Loading the same
+skill twice in one conversation returns a short digest (description, file list,
+guidance) instead of a second copy of the body; the model can ask for the full
+text back with `skill(name="…", force=true)`.
+
+Bodies may use `$ARGUMENTS` and `$1..$9`; `$$` is a literal `$`. If a skill
+declares no placeholder, the arguments are appended under an `## Arguments`
+heading instead. Where a skill's name collides with a built-in command, the
+**built-in wins** and the skill is reachable as `/skill:<name>`.
+
+### Where skills come from
+
+Four scopes, later ones overriding earlier ones by name:
+
+| Scope | Location | Writable |
+| --- | --- | --- |
+| `bundled` | `<package>/skills/` | no |
+| `user` | `aragon skills path` | yes — the default install target |
+| `project` | `<cwd>/.aragon/skills/` | yes |
+| `project` | `<cwd>/.claude/skills/` | no — read-only Claude Code interop |
+| `env` | `ARAGON_SKILLS_PATH` (`:`/`;`-separated) | no |
+
+A shadowed skill is not lost: `/skills` shows it as `~shadowed by <scope>`.
+
+### Frontmatter
+
+```yaml
+---
+name: pdf-forms          # required, kebab-case, ≤ 64 chars
+description: Fill, flatten and validate AcroForm PDFs. Use when the task
+  mentions PDF forms, field filling, or flattening a fillable PDF.
+version: 1.2.0
+license: MIT
+author: Jane Doe
+homepage: https://github.com/jane/pdf-forms
+keywords: [pdf, forms]
+allowed-tools: [read_file, bash]   # enforced as a per-turn tool ceiling (union)
+activation: auto                   # auto | always | manual
+---
+```
+
+`description` is the only text a model sees before deciding to load the skill,
+so it has to say both what the skill does and when to use it. Unknown keys are
+preserved, so a newer Claude Code field will not break parsing.
+
+`activation: always` injects the body into every session's system prompt (12 000
+bytes total across all such skills); `manual` keeps it out of the catalog so it
+runs only when explicitly invoked.
+
+### Security model — and its limits
+
+Be clear about what this does and does not buy you:
+
+- **Installing requires a human.** The approval gate checks whether a person is
+  actually reachable *before* asking, and refuses when nobody is. Under `-p`
+  there is no TUI and therefore no approver, so `skill_install` fails with an
+  actionable message instead of writing to disk unattended. Opt out
+  deliberately with `--skills-yes` or `skills.requireApproval=false`.
+- **Project directories need trusting once.** Cloning an unfamiliar repository
+  does not grant it the right to inject instructions into your session.
+- **Nothing is executed at install time.** No postinstall, no dependency
+  install; the executable bit is not preserved. Scripts run only when the model
+  invokes `bash`.
+- **Archives are gated on real bytes** — total size, per-entry size, compression
+  ratio and entry count, all abortable mid-extraction. Path traversal,
+  absolute paths, symlinks and Windows device names are refused.
+- **Git is never run through a shell**, and ref / owner / repo fragments are
+  whitelisted and refused if they start with `-`.
+- **Third-party text cannot break out of its prompt block**: angle brackets in
+  descriptions, bodies and file names are neutralized before rendering.
+
+- **A changed `SKILL.md` is noticed at load time.** Every install records a
+  sha256; discovery re-checks the one file that reaches the model's context and
+  flags it as `!modified` if it no longer matches what you approved. See
+  `skills.integrity` below.
+- **Concurrent installs cannot corrupt a skill.** Writes take a per-directory
+  advisory lock, so two `aragon` processes installing at once queue instead of
+  interleaving their atomic-replace steps. *Limit:* the lock relies on exclusive
+  file creation, which is not reliably atomic on every NFS implementation. It
+  self-expires after 60 seconds and waits at most 5, so the worst case there is
+  no mutual exclusion — never a hang.
+
+What it does **not** do: there is **no sandbox**. Approval blocks *silent*
+installation; it does not make a skill you approved safe. A skill you accept can
+contain adversarial instructions, and its scripts run with your full user
+permissions — the same trust model as pasting text into the prompt and the same
+as the `bash` tool. `/skills info` records provenance and a sha256 per file so
+you can audit what arrived and notice if it changed. The integrity check answers
+"is this still the file I approved?", **not** "is this file from someone I
+trust" — there is no signing and no key distribution.
+
+`allowed-tools` **is** enforced now (see below), but read the next section before
+treating it as a permission boundary: it is blast-radius control, not a security
+boundary, and a skill can widen its own ceiling by loading another skill.
+
+### The tool ceiling (`allowed-tools`)
+
+A skill that declares `allowed-tools` constrains which tools the model may use
+**for the rest of the current turn**:
+
+```yaml
+allowed-tools: [read_file, write_file]
+```
+
+- **Scope is one turn.** The ceiling appears when a skill is loaded — by the
+  model calling `skill(...)`, or by you running `/<skill-name>` — and it is gone
+  as soon as you send the next message. A skill you used this morning does not
+  restrict unrelated work this afternoon.
+- **Read-only tools are always allowed**, declared or not: `read_file`,
+  `list_dir`, `glob`, `grep`, plus `skill` and `skill_find`. What the declaration
+  actually controls is the five tools that change something — `write_file`,
+  `edit_file`, `bash`, `skill_install`, `skill_create`.
+- **Claude Code names work.** `[Read, Bash, MultiEdit]` maps onto this host's
+  `read_file` / `bash` / `edit_file`. Tools that exist there but not here
+  (`WebFetch`, `Task`, `TodoWrite`, …) are ignored rather than treated as errors.
+- **A name we cannot resolve waives the whole declaration**, and says so. One
+  typo means that skill imposes no ceiling at all — never a narrower one you did
+  not write. `aragon skills doctor` reports these up front.
+- **`activation: always` skills never impose a ceiling.** They are ambient
+  reference material, not a procedure you chose to run.
+
+Three modes, via `skills.toolPolicy` (default `enforce`),
+`aragon --skill-tool-policy <mode>` for one run, or `/skills policy <mode>` for
+the current session (which takes effect immediately, even mid-turn):
+
+| Mode | Behaviour |
+| --- | --- |
+| `enforce` | The call is refused; the model is told what it may use instead. |
+| `warn` | The call runs, and you get one notice per tool per turn. |
+| `off` | No ceiling, and nothing about `allowed-tools` reaches the model. |
+
+`/skills unload` drops the ceiling for the current turn. It does **not** remove
+skill text already in the conversation — nothing can.
+
+**What this is and is not.** It is **blast-radius control, not a security
+boundary**. The declaration is written by the skill's own author, so a malicious
+skill can simply declare `[bash]`. Its value is that a declaration is now
+binding: you can read one in `/skills info` and decide whether to install, and an
+honest author's `[read_file]` means a "while you're there, run `rm -rf`" line
+smuggled into that skill's text — or into a file it tells the model to read —
+cannot execute.
+
+**And a known limit:** the ceiling is a **union** across every skill loaded this
+turn, and `skill` is always available. So a skill can widen its own ceiling by
+instructing the model to load a second, more permissive skill. This is not
+blocked — blocking it would either strand the model inside a skill it cannot
+escape, or break every multi-skill workflow — but every widening is printed to
+the transcript:
+
+```
+Tool ceiling widened by skill "skill-creator": +write_file, +skill_create
+```
+
+So it stops the smuggled instruction; it does not stop a skill that deliberately
+teaches the model to reach for another one.
+
+### Usage counters
+
+To rank the catalog, the CLI keeps a small file next to your skills directory:
+
+```jsonc
+// <aragon skills path>/../skill-usage.json
+{ "schema": 1, "skills": { "deploy-preview": { "useCount": 12, "lastUsedAt": 1785050000000 } } }
+```
+
+**It contains the skill name, a count, and a timestamp. Nothing else** — no
+arguments, no conversation content, no working directory, no machine identifier.
+It is never transmitted anywhere, by anything. Delete it whenever you like; the
+only effect is that the catalog falls back to plain scope-then-name order. Set
+`skills.usageTracking=false` to switch it off entirely, after which the file is
+neither read nor written.
+
+Automatically injected `activation: always` skills are deliberately **not**
+counted — they load on every turn, so counting them would say nothing about what
+you actually use.
+
+## Configuration
+
+Config is layered (highest priority last): **defaults → user config file →
+env / `.env` → CLI flags**.
+
+- **Env / `.env`**: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`,
+  `GOOGLE_API_KEY` / `GEMINI_API_KEY`, plus `ARAGON_PROVIDER`, `ARAGON_MODEL`,
+  `ARAGON_BASE_URL`, `ARAGON_THINKING`, `ARAGON_SHOW_THINKING` (`1` shows
+  reasoning blocks), `ARAGON_LIVE_TOOL_OUTPUT` (`0` keeps a running tool card to
+  one line),
+  `ARAGON_MAX_TOKENS` (a number, or `auto` / `0` for the per-model ceiling),
+  `ARAGON_THEME`,
+  `ARAGON_FULLSCREEN`, `ARAGON_PLAN` (`1` starts in plan mode),
+  `ARAGON_TEAM` (`0` disables team subagents), `ARAGON_TEAM_MAX` (fan-out width),
+  `ARAGON_TODO` (`0` disables todo planning entirely),
+  `ARAGON_TODO_FOLLOW` (`notify` / `auto` / `off`),
+  `ARAGON_RETRY` (`0` disables API retry), `ARAGON_RETRY_MAX` (retry count; `0`
+  also disables),
+  `ARAGON_SKILLS` (`0` disables), `ARAGON_SKILLS_PATH`,
+  `ARAGON_SKILLS_DISABLED` (comma-separated names), `ARAGON_LOG_LEVEL`,
+  `ARAGON_LOG_FILE` (`0` disables), `ARAGON_LOG_DIR`,
+  `ARAGON_TRANSCRIPT_RETAIN`, `ARAGON_RENDER_GOVERNOR` (`0` disables),
+  `ARAGON_MAX_RENDER_INTERVAL_MS`.
+  `ARAGON_HOME` is the exception that **cannot** come from `.env`: it is read
+  before any `.env` is loaded. See [Files & logs](#files--logs).
+- **User config file** (`aragon config path`): JSON, written `0600` on POSIX.
+  Holds provider / model / keys and your preferences, and nothing else — the
+  prompts you type and the counters behind one-time notices live in their own
+  files (see [Files & logs](#files--logs)). Keys are masked in the UI and never
+  logged. It lives in your home directory — see [Files & logs](#files--logs) —
+  and editing it by hand is supported: `aragon config edit` opens it, and an
+  invalid edit is reported rather than silently resetting every setting.
+
+| Config key | Default | Meaning |
+| --- | --- | --- |
+| `maxTokens` | `64000` | Output token cap, clamped to `[256, 200000]`. `null` means **auto** — use each model's own ceiling, never above 64000. Absent means the default. See [Output token limits](#output-token-limits). |
+| `showThinking` | `false` | Draw the reasoning the model returns. `thinkingLevel` is the effort the provider is asked to **spend**; this is whether the terminal **shows** it. Off by default: a settled turn that thought leaves one muted `thought for 12s` row in its place, so nothing is hidden silently. |
+| `liveToolOutput` | `true` | Draw up to eight sanitised rows of a **running** tool's output on its card, plus a `no output for Ns` row when the child goes quiet. On by default, unlike `showThinking`: this ADDS the information a long `bash` call otherwise hides, and its cost is bounded by construction — eight rows per call, sixteen calls, whatever the command emits. Turn it off and the card is a single `running` row again, with no store allocated and no recorder attached. |
+| `fullscreen` | `true` | Use the full-screen TUI (still subject to the automatic downgrades). Setting it to `false` opts out permanently; leaving it `true` is *not* a force — only `--fullscreen` / `ARAGON_FULLSCREEN=1` override the heuristics. |
+| `exitTranscript` | `true` | Replay a plain-text session summary after exiting (full-screen only). |
+| `transcriptWindow` | `1000` | How far back you can scroll, clamped to `[50, 20000]`. Entries beyond it collapse into one line. It is no longer a rendering budget: the viewport is virtualised, so off-screen entries are not laid out at all. |
+| `transcriptRetain` | `1000` | Entries kept in memory, clamped to `[200, 20000]` and raised to `transcriptWindow` if the two conflict — with a startup notice saying so, because retaining less than you can scroll to would otherwise make part of the horizon quietly unreachable. Older entries are dropped, counted, and reported by `/perf` and by the exit replay. |
+| `renderGovernor` | `true` | Widen the streaming frame interval when a frame is genuinely expensive. See [Render performance](#render-performance). |
+| `maxRenderIntervalMs` | `320` | Ceiling of the governor ladder, clamped to `[33, 1000]`. `33` flattens it to the pre-0.6 cadence without disabling the mechanism. |
+| `planModeDefault` | `false` | Start every session in plan mode. `--no-plan` still overrides it for a single run. |
+| `planModeMaxAskRounds` | `4` | `ask_user` rounds allowed per user message, clamped to `[1, 10]`. The counter resets on your next message; steering does **not** reset it. |
+| `planModeHumanTimeoutMs` | `1800000` | Ceiling on a single question / plan wait, clamped to `[60000, 7200000]`. Thirty minutes is far outside "went to get coffee", but a ceiling has to exist so an unattended terminal cannot wedge a CI job forever. |
+| `historyEnabled` | `true` | Record submitted prompts to `prompt-history.jsonl` for `↑` recall. Setting it to `false` stops new writes; it does not delete what is already stored (that is `aragon history clear --yes`) and does not stop reading. See [Prompt history](#prompt-history). |
+| `team.enabled` | `true` | Master switch for team subagents. `false` means the `task` tool is never registered — `/team on` in such a session saves the setting for next launch and says so, rather than advertising a tool that is not there. |
+| `team.maxSubagents` | `5` | Subagents per dispatch, clamped to `[1, 10]`. The 10 is the hard ceiling and is enforced twice — on the config value and again on what the model asks for — so hand-editing this file cannot raise it. |
+| `team.maxConcurrent` | `3` | Subagents in flight at once, clamped to `[1, 10]` and capped at `maxSubagents`. A separate knob because provider rate limits are a different constraint from context economics. |
+| `team.subagentTimeoutMs` | `300000` | One subagent's wall clock before it is aborted, clamped to `[30000, 1800000]`. A wedged subagent dies on its own ceiling without taking the dispatch with it. |
+| `team.dispatchTimeoutMs` | `900000` | The whole dispatch's wall clock, clamped to `[60000, 3600000]`. |
+| `team.maxTurnsPerSubagent` | `24` | Runaway-loop cap, clamped to `[4, 100]`. A subagent stopped here is reported as `stopped: turn cap reached`, with whatever it had produced. |
+| `todo.enabled` | `true` | Master switch for todo planning. `false` means the `todo_write` tool is never registered — `/todo on` in such a session saves the setting for next launch and says so, rather than advertising a tool that is not there. |
+| `todo.panel` | `true` | Render the right-hand rail (and, in inline mode, the one-row plan strip). Independent of `todo.enabled` on purpose: a screen-reader user wants the planning discipline without the column, and the system prompt varies one sentence accordingly. |
+| `todo.followThrough` | `"notify"` | What happens when a run ends with steps left. `notify` says so and stops; `auto` continues the plan after a 3-second grace window, bounded by two structural limits (one fruitless attempt, 25 continuations per plan) that are deliberately **not** settings; `off` is silent. An unrecognized value falls back to `notify`. |
+| `retry.enabled` | `true` | Retry a failed provider call at all. Unlike `team.enabled` / `todo.enabled` this decides nothing at construction — the policy lives on the provider registry, so `/retry on` / `/retry off` takes effect **in the running session**, subagents included. |
+| `retry.maxRetries` | `10` | Retries **after** the first attempt, clamped to `[0, 20]`. `0` is the kill switch and is a real value here, not a typo for the default. The 20 is a hard ceiling enforced twice — on the config value and again inside the engine — so hand-editing this file cannot raise it. |
+| `retry.initialDelayMs` | `1000` | The first wait, clamped to `[100, 30000]`. |
+| `retry.maxDelayMs` | `30000` | Ceiling on one wait, clamped to `[1000, 120000]` and raised to `initialDelayMs` if the two conflict. Kept below the engine's 60 s idle window on purpose, so the mechanism does not depend on the watchdog pause being correct — it merely benefits from it. |
+| `retry.multiplier` | `2` | Growth factor, clamped to `[1, 5]`. The one **float** key in this section: `2.5` is a legitimate factor and is stored as typed. |
+| `retry.jitter` | `true` | Equal jitter (`d/2 + rand·d/2`), which de-correlates concurrent subagents hitting the same 429 while keeping the announced countdown within a factor of two of the truth. Full jitter can fire 40 ms after announcing 30 s, which reads as a bug. |
+| `retry.respectRetryAfter` | `true` | Honour `Retry-After` (and the provider rate-limit reset headers) as a **floor**, never a replacement — a `Retry-After: 1` on the ninth retry does not undo eight retries of backoff. A stated wait above 60 s is surfaced immediately instead of waited out. |
+| `retry.maxElapsedMs` | `240000` | Wall-clock budget from the first failure, clamped to `[10000, 1800000]`. Deliberately **below** `team.subagentTimeoutMs`: an equal budget means a subagent is killed at the same instant its ladder ends, and the user is then told "subagent timed out" for what was a provider outage. |
+| `retry.onPartialStream` | `true` | Allow a restart after content has already streamed to the transcript. The view is rewound and the discarded tool cards removed; engine history is provably clean at that point, because it is only written on a completed turn. `false` refuses the whole path. |
+| `skills.enabled` | `true` | Master switch for the skill system. |
+| `skills.requireApproval` | `true` | Require a human to approve `skill_install` / `skill_create`. |
+| `skills.catalogMaxBytes` | `6000` | Level 1 catalog ceiling, in UTF-8 **bytes**, clamped to `[500, 40000]`. |
+| `skills.bodyMaxBytes` | `30000` | Level 2 body ceiling, in UTF-8 **bytes**, clamped to `[1000, 50000]`. |
+| `skills.allowedHosts` | GitHub / GitLab hosts | Hosts an install **or update** may fetch from. Re-checked on every update, not just at install time. |
+| `skills.disabled` | `[]` | Skill names switched off. |
+| `skills.trustedProjectDirs` | `[]` | Project skill directories you have trusted. |
+| `skills.integrity` | `warn` | What to do when `SKILL.md` no longer matches the copy you approved. `off` skips the check; `warn` flags it in `/skills list` and once per session; `strict` removes it from the catalog and makes `skill()` refuse it. Defaults to `warn` because editing an installed skill is a legitimate thing to do — `strict` suits CI and managed environments. |
+| `skills.usageTracking` | `true` | Keep local per-skill use counters to rank the catalog. Name, count and timestamp only; never transmitted. Inspect with `aragon skills usage`, erase with `--reset --yes`. |
+| `skills.toolPolicy` | `enforce` | How hard a skill's `allowed-tools` bites, for the turn it is loaded in. `off` disables it and says nothing about it to the model; `warn` runs the tool and reports it; `enforce` refuses. Unlike `skills.integrity`, a false positive here means a skill AUTHOR under-declared their own skill — which `aragon skills doctor` reports before it can bite. |
+| `log.level` | `info` | `silent` · `error` · `warn` · `info` · `debug` · `trace`. See [Files & logs](#files--logs) for what each level records. |
+| `log.toFile` | `true` | Write records to a file at all. `false` here is respected; `--log-file` overrides it for one run. |
+| `log.dir` | `""` | Log directory. Empty means `<home>/logs`. Only **absolute** paths are accepted — a relative one would mean a different directory for every working directory you launch from. |
+| `log.maxFileBytes` | `5242880` | Rotate once a file would exceed this, clamped to `[65536, 268435456]`. |
+| `log.maxFiles` | `10` | Files kept in the log directory, clamped to `[1, 200]`. The oldest beyond this are deleted — on rotation **and** on the first write of each day. |
+| `log.redactSecrets` | `true` | Run every record through redaction. Setting it to `false` is the one way to get credentials onto disk, so it prints a warning and has no settings-screen entry. |
+| `log.previewChars` | `512` | How much user content `debug` keeps per field, clamped to `[0, 8192]`. `trace` is never truncated. |
+
+Byte, not character: `ToolExecutor` truncates at 100 000 **bytes**, so a
+character-based budget would be roughly triple its nominal size for CJK text
+and would get cut mid-tag.
+
+### Output token limits
+
+Every model and every provider defaults to **64000** output tokens. You never
+have to configure this, and if you never touch it the number stays 64000.
+
+The number you set is an **ambition, not a promise**: it is clamped down to
+whatever the target model actually accepts. `gpt-4o` caps at 16384 and
+`gemini-1.5-pro` at 8192, and sending 64000 to either is an HTTP 400 that ends
+the turn — so `aragon` sends what the model will take, silently. When the model
+is one it has never seen (a proxy, an endpoint behind `--base-url`, a model that
+shipped last week), it sends 64000, and if the provider objects it reads the real
+ceiling out of the provider's own error, repairs the request, sends it again, and
+remembers the answer for the rest of the session. You see one warning line and
+the run continues.
+
+Four ways to change it, highest priority first:
+
+```bash
+aragon --max-tokens 32000            # this run only
+aragon --max-tokens auto             # this run only, per-model ceiling
+ARAGON_MAX_TOKENS=32000 aragon       # env layer, between the flag and the file
+aragon config set maxTokens 32000    # persisted; prints "Set maxTokens = 32000"
+aragon config set maxTokens auto     # persisted as null
+aragon config set maxTokens default  # back to 64000
+aragon config get maxTokens          # "64000" | "auto"
+```
+
+Inside the TUI, `/max-tokens` reports the current setting **and** the effective
+cap for the live model, and `/max-tokens <n|auto|default>` changes it. The
+settings screen (`/settings`) has the same field with an `Effective:` line under
+it, so a value the model will not honour is visible before you save it.
+
+And by hand, in `~/.aragon-agent/config.json` (`aragon config path` prints the
+exact location; `aragon config edit` opens it, and `/reload` picks up an edit
+made in another window):
+
+```jsonc
+{
+  "version": 1,
+  "provider": "anthropic",
+  "model": "claude-sonnet-4-5-20250929",
+
+  // Output token cap.
+  //   64000  (or any 256..200000 integer) — an explicit cap, clamped down to
+  //          the target model's real ceiling when that ceiling is lower.
+  //   null   — auto: use each model's own ceiling, never above 64000.
+  //   absent — the product default, 64000.
+  "maxTokens": 64000
+}
+```
+
+Out-of-range numbers are clamped on the way in **and** on the way out, so a
+hand-edited `900000` becomes `200000` on disk rather than reverting to the
+default on every launch.
+
+Extended thinking is reconciled with the cap automatically: `--thinking xhigh`
+asks for a 65536-token budget, Anthropic requires `max_tokens` to be strictly
+greater than it, and the two are resolved together rather than left to collide.
+
+These are additive: a config file written by an earlier version loads
+unchanged, with no migration and no version bump.
+
+## Files & logs
+
+Everything AragonAgent keeps for you lives under one directory in your home:
+
+```
+~/.aragon-agent/                    (Windows: C:\Users\<you>\.aragon-agent\)
+├── config.json                     settings + API keys (0600 on POSIX)
+├── config.json.bak                 written by `aragon config edit` before it opens
+├── prompt-history.jsonl            prompts you submitted, for ↑ recall (0600 on POSIX)
+├── state.json                      UI bookkeeping: submit count, one-shot notices
+├── logs/
+│   ├── aragon-2026-07-27.log       today, JSON Lines
+│   └── aragon-2026-07-27.1.log     rotated at log.maxFileBytes
+├── sessions/                       /save and /resume
+├── skills/                         aragon skills install
+└── skill-usage.json
+```
+
+`config.json` holds **settings only**. What you typed and how often you have
+typed it live in the two files next to it, so that editing your config means
+scrolling past your own settings and nothing else, and so that submitting a
+prompt no longer rewrites the file that holds your API keys.
+
+`ARAGON_HOME` moves the whole tree. **It cannot come from a `.env` file** — the
+path is resolved when the process starts, long before a `.env` is read — so set
+it as a real environment variable. `aragon config home` always prints the
+directory actually in use.
+
+Upgrading from 0.5.0 or earlier moves your config, sessions and skills here
+automatically, once, and prints a line on stderr when it does. The old
+`%APPDATA%\aragon-agent-nodejs` / `%LOCALAPPDATA%\aragon-agent-nodejs`
+directories are **left in place** so that reinstalling an older build stays
+lossless; `aragon config home` names them, and you can delete them once you are
+satisfied.
+
+### Prompt history
+
+Every prompt you submit is appended to `~/.aragon-agent/prompt-history.jsonl`,
+one JSON object per line, so that `↑` recalls it — in this session and in every
+later one. It is written `0600` on POSIX, it never leaves the machine, and it is
+**stored verbatim**: a redacted history would recall the wrong text, which is
+worse than not recalling at all.
+
+The last 100 distinct prompts are what `↑` walks. The file is rewritten down to
+that many entries once it passes 400 lines, and a single submission longer than
+16 KiB is not recorded at all rather than recorded truncated.
+
+```bash
+aragon history path           # where it is, plus a reminder of what is in it
+aragon history list -n 50     # the 50 most recent, newest first
+aragon history list --json    # raw entries with timestamps
+aragon history clear --yes    # delete the file
+```
+
+Set `historyEnabled` to `false` (`aragon config set historyEnabled false`) to
+stop recording. Switching it off does **not** delete what is already stored —
+`aragon history clear --yes` does that — and reading keeps working either way,
+so you can look before you erase.
+
+Upgrading from 0.5.x moves an existing `promptHistory` out of `config.json` into
+this file once, automatically and silently.
+
+### What gets logged
+
+Logs are local files. Nothing is uploaded, ever — there is no network path out
+of this subsystem at all.
+
+| Level | Records | Contains your content? |
+| --- | --- | --- |
+| `error` | crashes, failed requests, config write/parse failures | no |
+| `warn` | degraded migrations, clamped values, dropped records | no |
+| `info` *(default)* | start/exit, config writes, turn boundaries with token counts, tool names and durations | **no** |
+| `debug` | the above, plus prompts, replies and tool arguments truncated to `log.previewChars` | yes, truncated |
+| `trace` | full message bodies and full tool output | yes, in full |
+
+The default is `info` specifically so that attaching a log to a bug report is
+safe. **`debug` and `trace` write what you typed and what the model replied** —
+check before sharing one.
+
+API keys are removed at every level, by two independent passes: any field whose
+name looks like a credential is blanked whatever it holds, and every string is
+scanned for known key formats *and* for the literal keys this process is
+holding. The second half is what covers a custom endpoint whose key looks like
+nothing in particular. Setting `log.redactSecrets false` disables both, and says
+so on stdout when you do.
+
+### Commands
+
+```bash
+aragon logs path              # where records are going right now, and at what level
+aragon logs list              # files, sizes, timestamps
+aragon logs tail -n 50        # render the last 50 records
+aragon logs tail --follow     # keep printing new ones
+aragon logs tail --json       # raw JSON Lines, for jq
+aragon logs tail --level warn # only warn and above
+aragon logs clear --yes       # delete every log file
+aragon logs open              # open the directory in your file manager
+
+aragon history path           # where prompt history is kept
+aragon history list -n 50     # the 50 most recent prompts, newest first
+aragon history clear --yes    # delete the prompt history
+
+aragon config home            # the user-state root (and whether ARAGON_HOME set it)
+aragon config get log.level   # one value; secrets always masked
+aragon config list --json     # everything; secrets always masked here too
+aragon config edit            # open config.json in $VISUAL / $EDITOR
+```
+
+Per-run overrides, none of which are persisted:
+
+```bash
+aragon --log-level debug "…"   # or --verbose, which means the same thing
+aragon --no-log-file "…"       # nothing reaches a file this run
+aragon --log-dir D:\logs "…"
+```
+
+`ARAGON_LOG_LEVEL`, `ARAGON_LOG_FILE=0` and `ARAGON_LOG_DIR` do the same from the
+environment, and unlike `ARAGON_HOME` these three *can* come from a `.env`.
+
+### Insecure TLS opt-in
+
+When `NODE_TLS_REJECT_UNAUTHORIZED` is the exact string `0`, the installed or
+locally built `aragon` process honors that setting and suppresses only Node's
+standard insecure-TLS warning. Every unrelated process warning remains visible,
+and any other value leaves warning behavior unchanged. The check happens when a
+warning is emitted, so a `0` loaded from the project `.env` is covered too; the
+CLI never creates, normalizes, or persists this variable.
+
+> **Security warning:** `0` genuinely disables certificate verification. It does
+> not make an insecure connection safe and can expose credentials or request
+> contents to interception. Use it only in a controlled environment where you
+> accept that risk.
+
+The automatic filter starts with the `aragon` process. An earlier `npm install`
+or `npx` bootstrap belongs to npm and is outside the installed package's process
+boundary, so that parent may still print Node's warning. The official repository
+release flow covers its npm children through `publish-latest.ps1`; callers that
+own another npm/npx parent must preload the filter in that parent themselves if
+quiet output is required.
+
+### Theming & color
+
+`--theme` / `config.theme` / `/theme` pick a palette: `warm`, `cool`, `light`, or
+`auto` (which resolves to `warm` — terminals can't reliably report their
+background). `dark` remains accepted everywhere as an alias for `cool`.
+Colors degrade automatically to your terminal's depth (truecolor → 256 → 16 →
+monochrome) and glyphs fall back to ASCII on terminals without Unicode. Color is
+disabled — and the UI renders plain monochrome with ASCII glyphs — when any of
+`NO_COLOR`, `--no-color`, `TERM=dumb`, or `config.color=false` is set; `FORCE_COLOR`
+is respected. `reducedMotion` (also `ARAGON_REDUCED_MOTION`, and implied by
+`--no-color`) replaces spinners with a static glyph.
+
+### Timeout invariant
+
+The core idle watchdog (60 s by default) is **shorter** than the tool timeout
+(120 s), so a long single tool run (a build, `npm install`) would be killed
+mid-run. The CLI fixes this by always constructing the agent with
+`idleTimeout ≥ toolTimeout` (defaults 210 s ≥ 180 s), re-derived after config
+merge. Raise both `--tool-timeout` / `--idle-timeout` for genuinely long jobs.
+
+## Development
+
+```bash
+npm run build -w packages/cli   # tsc + shebang → dist/cli.js
+npm test    -w packages/cli     # vitest
+node packages/cli/dist/cli.js --version
+```
+
+### Manual smoke checklist
+
+- `npm run build -w packages/cli` produces an executable `dist/cli.js` with a
+  shebang; `node packages/cli/dist/cli.js --version` prints the version.
+- `npm pack -w packages/cli --dry-run --json` lists `dist/cli.js` under `files`.
+- With `ANTHROPIC_API_KEY` set: `aragon` streams a reply, a tool card renders,
+  `Esc` aborts mid-run, `/model` switches models, `/settings` saves a key,
+  `Ctrl+C` twice exits.
+- `echo "list files" | node dist/cli.js -p` prints an answer and exits `0`.
+- A missing/invalid key produces a visible, actionable message (never a blank
+  screen), both in the TUI and headless.
+- `Shift+Tab` at 40, 80 and 120 columns - the chip, the hint and the status bar
+  are all legible and nothing wraps onto a second row.
+- The question wizard at 24 rows with 5 questions x 4 options - no clipping, and
+  the `n/N` counter matches what is on screen.
+- Approve a plan and watch the SAME run start writing files, with no second
+  prompt.
+- `--no-color` on a legacy `cmd.exe` - the chip renders `[PLAN]`, radios render
+  `*`/`o`, checkboxes render `[x]`/`[ ]`, no mojibake anywhere.
+- A plan with a 600-character summary and a 400-character step detail - the text
+  wraps and scrolls, the footer count matches the real number of rows, and
+  nothing is truncated to a single line.
+- `--no-hints` on a 20-row terminal in plan mode - the status bar still says
+  `PLAN` with no chip on screen.
+- Dismiss a plan card with `Esc`, let the agent resubmit, then press `Esc` twice:
+  the run aborts and the session returns to an idle prompt. Do this one BY HAND
+  as well as in a test - the point of the check is whether the exit is findable,
+  which no assertion can tell you.
+
+## License
+
+MIT