@aragon-agent/cli 0.5.4 → 0.5.6

package/README.md

@@ -1,995 +1,1105 @@
-# @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]` |
-| `--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 |
-| `/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.
-
-## 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.
-
-## 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_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. |
-| `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 |
+| `--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