@armadra/agent 0.8.0 → 0.8.1

package/docs/en/{tui.md → guides/tui.md}

@@ -1,18 +1,18 @@
 # Terminal UI
 
-English · [简体中文](../tui.md)
+English · [简体中文](../../guides/tui.md)
 
-> Translated from the Chinese [docs/tui.md](../tui.md) as of commit `4b85f89`. When the two differ, the Chinese version is
+> Translated from the Chinese [docs/guides/tui.md](../../guides/tui.md) as of commit `4b85f89`. When the two differ, the Chinese version is
 > authoritative. Screens below are illustrative; the exact interface wording follows the interface language
 > (`ui.language`, `--lang`, `AMA_LANG`).
 
-How to use interactive mode, plus the API of the terminal component library `@armadra/agent/tui`. The design rationale is in [design.md](../design.md) §12 (Chinese).
+How to use interactive mode, plus the API of the terminal component library `@armadra/agent/tui`. The design rationale is in [design.md](../../design/design.md) §12 (Chinese).
 
 Running `ama` directly in a terminal (stdin / stdout both TTYs, `TERM` not `dumb`, no `--no-tui`) enters interactive mode. The interface uses the **main screen** only: the conversation history scrolls into the terminal scrollback without switching to the alternate screen, so `capture-pane` in tmux can read the whole conversation, and it stays on screen after exit.
 
 ## Layout
 
-The visual spec (colors, glyphs, screen-by-screen mockups) is in [tui-design.md](../tui-design.md) (Chinese). Hierarchy is expressed by indentation: column 0 holds the user `›`, the tool `⏺` and notice symbols, column 2 the result connector `⎿`, column 4 the tool output; the structure stays readable without colors (`NO_COLOR`, `capture-pane` without `-e`).
+The visual spec (colors, glyphs, screen-by-screen mockups) is in [tui-design.md](../../design/tui-design.md) (Chinese). Hierarchy is expressed by indentation: column 0 holds the user `›`, the tool `⏺` and notice symbols, column 2 the result connector `⎿`, column 4 the tool output; the structure stays readable without colors (`NO_COLOR`, `capture-pane` without `-e`).
 
 ```
  ▄███▄  ██▄   ▄██  ▄███▄    ama 0.6.2                     ← startup header (normal)
@@ -57,7 +57,7 @@ Accept edits | shift+tab to cycle    claude-opus-5-5 medium | Ctx 3.0% 8.2k/272k
   - **`compact`**: one line; on the right model · thinking level · `↑ ↓` · cache · cost · re-billing · context usage · dir ⎇ branch commit +a −b · session duration · queue count · codemode · preset · host status · a short subscription quota item (`5h 10% wk 31%`, only with quota data; no `·` inside the item); when narrow, these drop in order: the quota item, the switch hint, host status, preset, re-billing, cost, cache, tokens, thinking level, queue count, codemode, line changes, directory name, branch and commit, duration, context, model.
   - **git**: branch and short commit are read directly from `.git/HEAD` (worktrees understood; detached shows only the short commit; outside git the whole part is omitted, leaving only the directory name). `+a −b` is the working tree (staged included) line diff against HEAD, computed in the background with `git diff --numstat HEAD` after a turn ends, a writing tool finishes, a rewind or `/tree`, at most once every 10 seconds; if it takes longer than 2 seconds or fails, line changes are hidden for the rest of the session; `AMA_STATUS_GIT=0` turns it off. In `full`, `↑N` / `↓N` count the commits the current branch is ahead of / behind its upstream: when the branch has an upstream in the git config (`branch.<name>.merge`), the same throttled cycle then runs `git rev-list --left-right --count @{upstream}...HEAD` (same 2-second timeout; after a timeout it stops for the session); zero, no upstream or detached shows nothing; ASCII uses `^N` / `vN`.
   - **Cost** includes sub-tasks, warming, the classifier and external agent usage priced in USD (other units only in `/session`); **duration** counts from when this process opened the current session (`Ns` / `Nm` / `NhMm`).
-  - When bash commands run in the OS sandbox (`sandbox.bash: "auto"` and available on this machine, see [sandbox.md](../sandbox.md), Chinese), the usage items gain a sandbox marker, dropped first together with codemode when space runs out.
+  - When bash commands run in the OS sandbox (`sandbox.bash: "auto"` and available on this machine, see [sandbox.md](../../guides/sandbox.md), Chinese), the usage items gain a sandbox marker, dropped first together with codemode when space runs out.
   - During a model fallback (`fallbackModel`: when the main model is overloaded or retries are exhausted, one retry with the fallback model) the `compact` model item shows `main model → fallback model` (the fallback in yellow), while `full` keeps only the main model there and shows `→ fallback model` on the left of the rate line; it disappears once the fallback model replies and the main model is restored, and the message area gets an explanatory line.
   - **Context refresh**: it updates right after a message is submitted (the new message counted as an estimate); while streaming, once the reply carries usage (some protocols report input tokens at the start) it switches to the measured value of the in-flight request, at most twice a second; after the reply ends, a compaction or a model change it goes back to the session stats.
   - Model names abbreviate with width (provider dropped below 100 columns, channel below 60, version suffix below 48); `compact` at ≥ 110 columns shows context as a meter `ctx ▮▮▮▯▯▯▯▯▯▯ 34%`, keeping one decimal below 1% (`ctx ≈0.4%` rather than 0%), with the same `≈` for estimates; changing numbers reserve their widest shape, so items never flicker in and out as values change. In ASCII mode `⎇` → `git`, `−` → `-`, `♨` → `~`, `↻` → `@`.
@@ -154,11 +154,11 @@ While running, Enter **queues** by default (steer): the message waits for the ne
 
 Why `Ctrl+X` by default: macOS Terminal, iTerm2, tmux and Windows Terminal all pass it through and nothing else is bound to it; `Ctrl+Enter` is indistinguishable from Enter without the kitty keyboard protocol, `Ctrl+S` may be swallowed by XOFF flow control, `Alt+Enter` is already followUp, `Alt+letter` sends no Meta by default on macOS, and `Ctrl+]` is awkward on non-US layouts. Rebind it in `keybindings.json`.
 
-In line mode (`--no-tui`), typing `/interrupt <text>` while running does the same (when idle it is an ordinary prompt); the TUI accepts the command too. Over RPC it is `interrupt: true` on `prompt` / `steer`, see [rpc.md](rpc.md).
+In line mode (`--no-tui`), typing `/interrupt <text>` while running does the same (when idle it is an ordinary prompt); the TUI accepts the command too. Over RPC it is `interrupt: true` on `prompt` / `steer`, see [rpc.md](../reference/rpc.md).
 
 ## Rewind
 
-Design in [rewind-plan.md](../rewind-plan.md) (Chinese). Every user message that starts a new turn is a rewind point; files changed by edit / write have a checkpoint before the message is sent (`checkpoints.mode`; bash changes are only picked up when the next turn re-snapshots tracked files).
+Design in [rewind-plan.md](../../history/rewind-plan.md) (Chinese). Every user message that starts a new turn is a rewind point; files changed by edit / write have a checkpoint before the message is sent (`checkpoints.mode`; bash changes are only picked up when the next turn re-snapshots tracked files).
 
 - **Entry**: `/rewind`, or double Esc while idle with an empty input box: the first press shows a hint at the bottom to press Esc again to rewind (gone after 1 second), and a second press within 800 ms opens the list. With text in the input box, double Esc clears it instead (with a matching hint), and the text goes into input history, recallable with ↑. While running, Esc still interrupts; when an approval dialog or a picker is open, Esc belongs to them.
 - **Interrupt to withdraw**: when Esc interrupts a run and this turn has no reply text or tool call yet and the input box is empty (`ui.restoreOnCancel`, default true), the message is withdrawn automatically and the original text put back into the input box, with a line in the message area saying the interrupted message was withdrawn.
@@ -326,11 +326,11 @@ After the input summary comes the **pre-execution preview**: what this step will
 - write: whether the target exists, its current line count and size → the new content; overwriting a file not read in this session is marked yellow.
 - edit: a dry run against the original, listing −n/+m lines per change and the total; when a match fails or is not unique, this is said up front.
 
-The preview is colored by severity (danger red, warning yellow, the rest dim), read-only and bounded: at most 2000 entries counted per directory and a 200 ms budget for the whole preview; beyond that it only gives a hint without lowering severity; files over 2 MiB only report their size. A failed preview does not affect the approval. Line mode prints the same preview line by line before the question; RPC clients get it from `permission_request.preview` ([rpc.md](rpc.md) "Approvals").
+The preview is colored by severity (danger red, warning yellow, the rest dim), read-only and bounded: at most 2000 entries counted per directory and a 200 ms budget for the whole preview; beyond that it only gives a hint without lowering severity; files over 2 MiB only report their size. A failed preview does not affect the approval. Line mode prints the same preview line by line before the question; RPC clients get it from `permission_request.preview` ([rpc.md](../reference/rpc.md) "Approvals").
 
 ## Plan approval
 
-In Plan mode (Shift+Tab, `/permission plan`, `/plan <goal>`, `--permission-mode plan`) the model researches read-only and ends with a `<proposed_plan>` block (rules in [plan.md](../plan.md), Chinese). When the turn ends and the session is idle, an approval box pops up at the bottom:
+In Plan mode (Shift+Tab, `/permission plan`, `/plan <goal>`, `--permission-mode plan`) the model researches read-only and ends with a `<proposed_plan>` block (rules in [plan.md](../../guides/plan.md), Chinese). When the turn ends and the session is idle, an approval box pops up at the bottom:
 
 ```
 ╭─ Plan awaiting approval ─────────────────────────────────────────────────────╮
@@ -359,7 +359,7 @@ In Plan mode (Shift+Tab, `/permission plan`, `/plan <goal>`, `--permission-mode
 
 ## Sub-agents
 
-Sub-agents started by the `task` tool ([agents.md](../agents.md), Chinese) fold into a task tool line in the message area, with one status line while running:
+Sub-agents started by the `task` tool ([agents.md](../../guides/agents.md), Chinese) fold into a task tool line in the message area, with one status line while running:
 
 ```
 ⏺ task check test coverage gaps in src/tui
@@ -372,7 +372,7 @@ Sub-agents started by the `task` tool ([agents.md](../agents.md), Chinese) fold
     ↳ t3 explore · running 30s · 2 turns · grep
 ```
 
-- The status line shows the type (external agents show a runner such as `claude (claude)`), status and elapsed time, turns, the latest 3 tools and usage; after a foreground task ends it is replaced by the result summary. A background task's tool call (background is the default in the interactive UI, see [agents.md](../agents.md) "foreground and background", Chinese) returns immediately; the summary line says "started in the background", with an extra follow-up status line below (refreshed every second while running). A foreground task moved to the background shows "moved to the background · elapsed" with the same follow-up line (the explanation meant for the model is hidden; `Ctrl+O` shows it). A task moved by the auto timeout (`subagents.autoBackgroundAfterMs`) or by the host also gets a one-line notice; when it completes, the `<task-notification>` the model receives shows in the message area as a single line (e.g. "↳ sub-agent notification: t2 explore done · 7 turns · see /tasks for output"), plus a yellow notice on failure or stop.
+- The status line shows the type (external agents show a runner such as `claude (claude)`), status and elapsed time, turns, the latest 3 tools and usage; after a foreground task ends it is replaced by the result summary. A background task's tool call (background is the default in the interactive UI, see [agents.md](../../guides/agents.md) "foreground and background", Chinese) returns immediately; the summary line says "started in the background", with an extra follow-up status line below (refreshed every second while running). A foreground task moved to the background shows "moved to the background · elapsed" with the same follow-up line (the explanation meant for the model is hidden; `Ctrl+O` shows it). A task moved by the auto timeout (`subagents.autoBackgroundAfterMs`) or by the host also gets a one-line notice; when it completes, the `<task-notification>` the model receives shows in the message area as a single line (e.g. "↳ sub-agent notification: t2 explore done · 7 turns · see /tasks for output"), plus a yellow notice on failure or stop.
 - `/tasks`: focus the agent bar (below); `/tasks <id>` opens that task's sub-agent view directly; `/tasks stop <id>` stops it; `/tasks bg [id]` moves it to the background (without an id: every blocking foreground task, same as `Ctrl+B`). With `ui.agentBar: "off"` `/tasks` is still the task picker (newest on top, Enter shows the output, running tasks can be stopped). Line mode: `/tasks` lists, `/tasks <id>` shows output, `/tasks stop <id>` stops, `/tasks bg [id]` moves to the background (typed while running it is still a command, not a steer).
 - Moving to the background (`Ctrl+B`, key action `app.tasks.background`): while the main turn waits for a foreground task (`task` with `background: false`, the `-p` default, or `task_ctl wait`), press it and the tool call returns at once, the task keeps running, the main turn carries on and you can keep sending messages; when the task ends the `<task-notification>` arrives and opens a turn as usual. The hint says "Moved to the background: t2; you'll be notified when it finishes". With nothing to move, `Ctrl+B` falls through to the editor (cursor left) and is not swallowed. tmux's default prefix is `C-b`: in tmux press `C-b C-b` (default `send-prefix`) to pass it to ama, or press `b` in the agent bar; you can also rebind it in `keybindings.json`.
 - Esc interrupts only the foreground: Esc while running stops the main turn and the sub-tasks still in the foreground; tasks already in the background keep running, and the hint says "Interrupted (background task t2 keeps running; Esc doesn't affect it)".
@@ -396,7 +396,7 @@ Above the status line (below the hint line) the bar lists sub-agent tasks, one l
 - When the key does not get you in, a one-line hint shows for 3 seconds: text in the input box — "Input is not empty; clear it and press ↓ for the Agent bar" (once per draft, with the cursor on the last line; `↓` still moves down); the bar is off — "Agent bar is off (ui.agentBar); use /tasks"; no tasks — "No sub-agent tasks yet". While browsing input history with `↑` `↓`, `↓` only steps through history.
 - `Ctrl+B` does not enter the bar; it moves foreground tasks to the background (above). For the old "`Ctrl+B` enters the bar", set `"app.agents.focus": ["down", "ctrl+b"]` in `keybindings.json` and rebind `app.tasks.background`.
 - In the bar: `↑` `↓` select (lists every task of the session, the window scrolls along; `↑` on the first item returns to the input box), Enter opens the sub-agent view (a docked approval of the selected task pops up right away), `b` / `Ctrl+B` moves the selected foreground task to the background (a one-line hint when it is not running in the foreground), `x` stops the selected task (the first press hints "Press x again to stop t2"; it stops only on a second press within 1.5 seconds), Esc returns to the input box; other letters return to the input box with the text filled in. The last line is the key hint `↑↓ select · Enter open · b background · x stop · Esc back`; narrow screens drop the `b` / `x` items.
-- Embedding hosts (with a profile) no longer turn the bar off by default; a host that shows sub-tasks itself and does not want the bar sets `ui.agentBar: "off"` in its profile (see [host-api.md](host-api.md) "Embedding in Armadra"). With the bar off it is not shown, and `↓` with tasks points to `/tasks`.
+- Embedding hosts (with a profile) no longer turn the bar off by default; a host that shows sub-tasks itself and does not want the bar sets `ui.agentBar: "off"` in its profile (see [host-api.md](../reference/host-api.md) "Embedding in Armadra"). With the bar off it is not shown, and `↓` with tasks points to `/tasks`.
 
 ### Sub-agent view
 
@@ -416,7 +416,7 @@ t2 explore · running 1m05s · 3 turns · ↑12k ↓3.4k · Esc back · /tasks s
 
 - The body follows live: for ama sub-agents it shows every message and tool call of the sub-session (rendered like the message area); when the sub-session handle has been released (at most 16 are kept) or the session was resumed, the sub-session file is loaded read-only and live events are attached when the task runs again. External agents (claude / codex / ACP) show the live output held in this process's memory (text, thinking, tool start / end, turns, notices; at most 2000 items / 1 MB, never written to disk); after ama restarts only one line remains, saying to use the original CLI's resume <session id> for the full text.
 - With an empty input box: `↑` / PgUp scroll up (pausing follow, with "follow paused · End to resume" at the bottom), `↓` / PgDn scroll down, End (or `f` while paused) resumes following; `←` `→` switch to the previous / next task; Esc returns to the main screen. With text in the input box, Esc clears it first.
-- Enter sends the input to this sub-agent (recorded in the sub-session as a user message with `origin: "direct"`, see [session-format.md](../session-format.md), Chinese): ama sub-agent running → delivered when its current turn ends; external agent running or task still queued → continued after this run ends; finished → continued in the background (like `task_ctl send`; the main session receives the `<task-notification>` as usual when it completes). A line at the bottom reports the result. The parent session's model does not know you talked to the sub-agent directly; the result comes back through the completion notification.
+- Enter sends the input to this sub-agent (recorded in the sub-session as a user message with `origin: "direct"`, see [session-format.md](../../reference/session-format.md), Chinese): ama sub-agent running → delivered when its current turn ends; external agent running or task still queued → continued after this run ends; finished → continued in the background (like `task_ctl send`; the main session receives the `<task-notification>` as usual when it completes). A line at the bottom reports the result. The parent session's model does not know you talked to the sub-agent directly; the result comes back through the completion notification.
 - `Ctrl+X` interrupts this sub-agent and sends now: an ama sub-agent that is running stops its current turn (tools finish as interrupted) and starts a new turn with the message at once; the task completes and notifies the main session as usual. An external agent whose driver can interrupt a single turn (ACP `session/cancel`, Claude stream-json interrupt, Codex `turn/interrupt`) is interrupted and its next turn starts with the message (and any messages queued before it); when it cannot (oneshot, host drivers) or the task is still waiting in the concurrency pool, the message is queued instead with a hint; a finished task continues in the background as with Enter. Swapped with Enter under `ui.enterWhileRunning: "interrupt"`. The main session is not affected.
 - Esc in the view interrupts nothing: it only goes back. To stop the task use `/tasks stop <id>`; to move it to the background use `Ctrl+B` or `/tasks bg [id]`. Both work in the view's input box (the only commands the view accepts).
 - When the viewed task waits for approval the title says "awaiting approval", and the approval dialog pops up over the view as usual (with the `[task:<type>]` origin); if its approval is docked in the bar, opening the view pops it up.
@@ -466,11 +466,11 @@ Trace · 1 turn · 2 requests · 3 tool calls · 12s · ↑8.1k ↓240 · cache
 - Auxiliary requests such as warming and permission classification are grouped at the end under "N auxiliary requests", collapsed by default.
 - In line mode (`--ui line`, pipes) `/trace [task id]` prints the same tree as text (fully expanded, no bars).
 
-Timing comes from `custom{customType:"ama.trace"}` entries in the session file ([session-format.md](../session-format.md), Chinese), which hold only ids, times and counts; previews of prompts, arguments and results are read from session entries on demand and never enter the trace itself. The HTML export `ama sessions trace` and RPC `get_trace` are described in [sessions.md](sessions.md) and [rpc.md](rpc.md).
+Timing comes from `custom{customType:"ama.trace"}` entries in the session file ([session-format.md](../../reference/session-format.md), Chinese), which hold only ids, times and counts; previews of prompts, arguments and results are read from session entries on demand and never enter the trace itself. The HTML export `ama sessions trace` and RPC `get_trace` are described in [sessions.md](sessions.md) and [rpc.md](../reference/rpc.md).
 
 ## Memory
 
-Requires memory to be enabled (`ama memory enable` or `--memory`, see [memory.md](../memory.md), Chinese). `/memory` draws a card in the message area: one section per scope (`user /memories/user/ · N entries · index X / 4.0 KiB`), one line per entry "name — description updated date", entries not updated for over 90 days greyed out; when the index exceeds its limit a yellow line says how many entries did not make it into the system prompt; an untrusted project and writes disabled for this session each add a line at the bottom of the card.
+Requires memory to be enabled (`ama memory enable` or `--memory`, see [memory.md](../../guides/memory.md), Chinese). `/memory` draws a card in the message area: one section per scope (`user /memories/user/ · N entries · index X / 4.0 KiB`), one line per entry "name — description updated date", entries not updated for over 90 days greyed out; when the index exceeds its limit a yellow line says how many entries did not make it into the system prompt; an untrusted project and writes disabled for this session each add a line at the bottom of the card.
 
 `/memory show <name>` renders the body as a card; `/memory edit [name|scope]` suspends the interface and opens `$VISUAL` / `$EDITOR` (on a temporary copy, saved back and the index rebuilt after you save and quit, with the same credential and size checks as model writes); `/memory rm <name>` asks for confirmation (default "Cancel", `y` deletes, `n` / Esc cancels); `/memory on|off` toggles writes for this session; `/memory reload` re-renders the system prompt's `memory` section (breaking the cache once). Line mode has the same commands with text output; `edit` uses `ama memory edit` instead and `rm` needs `--yes`. When memory is not enabled for the session it only explains how to enable it.
 

package/docs/en/{acp.md → reference/acp.md}

@@ -1,16 +1,16 @@
 # ACP (Agent Client Protocol)
 
-English · [简体中文](../acp.md)
+English · [简体中文](../../reference/acp.md)
 
-> Translated from the Chinese [docs/acp.md](../acp.md) as of commit `f6419be`. When the two differ, the Chinese version is
+> Translated from the Chinese [docs/reference/acp.md](../../reference/acp.md) as of commit `f6419be`. When the two differ, the Chinese version is
 > authoritative.
 
 ama works on both sides of ACP:
 
 - **Agent**: `ama --mode acp` exposes ama as an ACP agent for Zed, JetBrains and Armadra's ACP nodes;
-- **Client**: ama drives external agents over ACP (native ACP agents such as Gemini CLI, OpenCode, Kimi and Copilot, or Claude Code / Codex with an adapter installed); see [agents.md](../agents.md) (Chinese).
+- **Client**: ama drives external agents over ACP (native ACP agents such as Gemini CLI, OpenCode, Kimi and Copilot, or Claude Code / Codex with an adapter installed); see [agents.md](../../guides/agents.md) (Chinese).
 
-The protocol stack is hand-written with no dependencies and maintained in one place: `@armadra/agent/acp` exports the types, framing, client and fake agent, and Armadra reuses them directly. The design rationale is in [wave5-plan.md](../wave5-plan.md) §5 (D14, Chinese).
+The protocol stack is hand-written with no dependencies and maintained in one place: `@armadra/agent/acp` exports the types, framing, client and fake agent, and Armadra reuses them directly. The design rationale is in [wave5-plan.md](../../history/wave5-plan.md) §5 (D14, Chinese).
 
 ## Wire
 
@@ -73,7 +73,7 @@ The full before / after text of a diff only travels with live events and is neve
 
 ### Approvals
 
-Calls that ama needs to ask about go to the client as `session/request_permission` with three options: `allow_once` (Allow), `allow_always` (Allow for this session) and `reject_once` (Deny). `toolCall.toolCallId` refers to the id of an earlier `tool_call` — including calls inside codemode, which point at the inner `tool_call`, not the outer `codemode` one. While the question is open the call goes back to `pending`, then `in_progress` once allowed (so an approved call goes `pending → in_progress → pending → in_progress → completed`); a denied call goes straight to `failed`. When the client answers `cancelled`, the connection drops or the turn is interrupted, it counts as unanswered (denied). When ama no longer needs an answer (the turn was interrupted by `session/cancel` / `$/cancel_request`, or the 10-minute approval timeout passed), it withdraws the pending `session/request_permission` with `$/cancel_request { requestId }` so the client can close its dialog. In auto mode ama's own classifier still works — this only applies to ama's own tools; requests from external agents that ama drives go to a human only (see [agents.md](../agents.md), Chinese).
+Calls that ama needs to ask about go to the client as `session/request_permission` with three options: `allow_once` (Allow), `allow_always` (Allow for this session) and `reject_once` (Deny). `toolCall.toolCallId` refers to the id of an earlier `tool_call` — including calls inside codemode, which point at the inner `tool_call`, not the outer `codemode` one. While the question is open the call goes back to `pending`, then `in_progress` once allowed (so an approved call goes `pending → in_progress → pending → in_progress → completed`); a denied call goes straight to `failed`. When the client answers `cancelled`, the connection drops or the turn is interrupted, it counts as unanswered (denied). When ama no longer needs an answer (the turn was interrupted by `session/cancel` / `$/cancel_request`, or the 10-minute approval timeout passed), it withdraws the pending `session/request_permission` with `$/cancel_request { requestId }` so the client can close its dialog. In auto mode ama's own classifier still works — this only applies to ama's own tools; requests from external agents that ama drives go to a human only (see [agents.md](../../guides/agents.md), Chinese).
 
 ### Without a model
 
@@ -145,7 +145,7 @@ These are deliberate choices, not omissions:
 
 ## As a client
 
-The model uses ACP agents through `task(agent="acp:<program>")` (ama itself is `task(agent="acp:ama")`; see "Using them in task" in [agents.md](../agents.md), Chinese).
+The model uses ACP agents through `task(agent="acp:<program>")` (ama itself is `task(agent="acp:ama")`; see "Using them in task" in [agents.md](../../guides/agents.md), Chinese).
 
 `AcpClient` (`@armadra/agent/acp`): `initialize`, `newSession`, `resumeSession` (preferred, no replay), `loadSession`, `listSessions`, `closeSession`, `prompt`, `setMode`, `cancel`.
 

package/docs/en/{host-api.md → reference/host-api.md}

@@ -1,11 +1,11 @@
 # Host adapter API (@armadra/agent/host)
 
-English · [简体中文](../host-api.md)
+English · [简体中文](../../reference/host-api.md)
 
-> Translated from the Chinese [docs/host-api.md](../host-api.md) as of commit `979608b`. When the two differ, the Chinese
+> Translated from the Chinese [docs/reference/host-api.md](../../reference/host-api.md) as of commit `979608b`. When the two differ, the Chinese
 > version is authoritative.
 
-A host adapter is a local JS module that ama loads at startup and hands a `HostApi`. With it the adapter can register tools, append to the system prompt, observe events, answer approvals, inject user messages and show notifications and status in the interface. The Armadra canvas plugs in as a host adapter (the canvas tools `canvas_*` / `context_*` are all registered by the adapter). The types are defined in `src/host/types.ts` and exported from `@armadra/agent/host`; `HOST_API_VERSION = 1`. The design rationale is in [design.md](../design.md) §6.2, §6.3 and §11.1 step 13 (Chinese).
+A host adapter is a local JS module that ama loads at startup and hands a `HostApi`. With it the adapter can register tools, append to the system prompt, observe events, answer approvals, inject user messages and show notifications and status in the interface. The Armadra canvas plugs in as a host adapter (the canvas tools `canvas_*` / `context_*` are all registered by the adapter). The types are defined in `src/host/types.ts` and exported from `@armadra/agent/host`; `HOST_API_VERSION = 1`. The design rationale is in [design.md](../../design/design.md) §6.2, §6.3 and §11.1 step 13 (Chinese).
 
 ## Module shape
 
@@ -100,7 +100,7 @@ interface ToolResult {
 }
 ```
 
-`ToolContext` provides `toolCallId`, `cwd`, `sessionId`, `sessionFile?`, `signal`, `depth`, `model?`, `thinkingLevel?`, `outputDir?`, `onUpdate(partial)` (output while running), `readFiles` / `markRead`, `activeTools?` (read-only snapshot of the session's active tool set, so tools can give actionable hints), `tools.executeTool(name, input)` (nested calls through the same pipeline), `session.appendCustom` / `lastCustom` (custom entries that never enter the context, see [session-format.md](../session-format.md), Chinese), `spawnSubagent?` and `log`.
+`ToolContext` provides `toolCallId`, `cwd`, `sessionId`, `sessionFile?`, `signal`, `depth`, `model?`, `thinkingLevel?`, `outputDir?`, `onUpdate(partial)` (output while running), `readFiles` / `markRead`, `activeTools?` (read-only snapshot of the session's active tool set, so tools can give actionable hints), `tools.executeTool(name, input)` (nested calls through the same pipeline), `session.appendCustom` / `lastCustom` (custom entries that never enter the context, see [session-format.md](../../reference/session-format.md), Chinese), `spawnSubagent?` and `log`.
 
 Host tools take the same path as built-in tools: schema validation → command hook PreToolUse → permission pipeline (classified by `permission`) → approval → execution → PostToolUse. They can also be called from codemode scripts as `tools.<name>()`.
 
@@ -137,7 +137,7 @@ For token-level streaming content or the full event stream, use RPC or the SDK's
 - `request`: `requestId`, `toolName`, `input`, `reason: "mode" | "dangerous" | "hook"`, `hookReason?`, `preview?` (the pre-execution preview, see [rpc.md](rpc.md) "Approvals"), `context?` (`depth > 0` means it comes from a `task` sub-agent; codemode inner calls carry `parentToolCallId`).
 - On timeout (10 minutes by default, `AMA_APPROVAL_TIMEOUT_MS`) or when the run is interrupted, `signal` aborts and the decision is deny. Approvals are serial: only one request waits at a time.
 - Timing: the broker is looked up at each approval, so it can be set in `create()` or set / replaced at any later time; the last `setBroker` wins.
-- The host broker only decides "who answers an ask"; it cannot loosen deny rules, command hook denies or dangerous-command detection ([design.md](../design.md) §6.3, Chinese).
+- The host broker only decides "who answers an ask"; it cannot loosen deny rules, command hook denies or dangerous-command detection ([design.md](../../design/design.md) §6.3, Chinese).
 
 ## Cache warming
 
@@ -155,7 +155,7 @@ interface WarmDecision {
 }
 ```
 
-Return `"warm"` / `"stop"` (a Promise is fine). `"stop"` skips the request and stops this warming round (when the built-in decision was warm, the stop reason is recorded as `declined`); `"warm"` can override a built-in stop. If the handler fails, the built-in decision applies. With several handlers, the last one registered and not unsubscribed wins; the return value is an unsubscribe function. The warming mechanism itself is described in [providers.md](providers.md) "Caching".
+Return `"warm"` / `"stop"` (a Promise is fine). `"stop"` skips the request and stops this warming round (when the built-in decision was warm, the stop reason is recorded as `declined`); `"warm"` can override a built-in stop. If the handler fails, the built-in decision applies. With several handlers, the last one registered and not unsubscribed wins; the return value is an unsubscribe function. The warming mechanism itself is described in [providers.md](../guides/providers.md) "Caching".
 
 ## Exit
 
@@ -168,4 +168,4 @@ Armadra starts ama with a profile: `ama --profile <path>`. The profile's `host`
 
 Interface defaults with a profile: `ui.quietStartup: "header"` and `ui.statusLine: "compact"` (the last line is the status bar, which the host parses by `·`). The agent bar (`ui.agentBar`) is no longer off by default; it is `auto` as in a standalone terminal. A host that shows sub-tasks itself and does not want the bar writes `{ "ui": { "agentBar": "off" } }` into the config file its profile's `config` points to.
 
-Contract details are in [docs/design/coordinator-agent.md](https://github.com/yovinchen/Armadra/blob/main/docs/design/coordinator-agent.md) in the Armadra repository.
+Contract details are in [docs/design/coordinator-agent.md](https://github.com/AMA-Link/Armadra/blob/main/docs/design/coordinator-agent.md) in the Armadra repository.

package/docs/en/{rpc.md → reference/rpc.md}

@@ -1,11 +1,11 @@
 # RPC protocol (stdio JSONL)
 
-English · [简体中文](../rpc.md)
+English · [简体中文](../../reference/rpc.md)
 
-> Translated from the Chinese [docs/rpc.md](../rpc.md) as of commit `a567833`. When the two differ, the Chinese version is
+> Translated from the Chinese [docs/reference/rpc.md](../../reference/rpc.md) as of commit `a567833`. When the two differ, the Chinese version is
 > authoritative.
 
-`ama --mode rpc` reads commands from stdin and writes responses and events to stdout, one JSON value per line. The types are defined in `@armadra/agent/rpc` (`src/rpc.ts`) and implemented in `src/modes/rpc/`. The events printed by `ama -p --output-format stream-json` have the same shapes. The design rationale is in [design.md](../design.md) §13.2 (Chinese).
+`ama --mode rpc` reads commands from stdin and writes responses and events to stdout, one JSON value per line. The types are defined in `@armadra/agent/rpc` (`src/rpc.ts`) and implemented in `src/modes/rpc/`. The events printed by `ama -p --output-format stream-json` have the same shapes. The design rationale is in [design.md](../../design/design.md) §13.2 (Chinese).
 
 ## Wire
 
@@ -35,7 +35,7 @@ A command has the shape `{ "id"?: string, "type": <command name>, ...parameters
 
 - A response carries the request's `id` back (only string ids). Commands are processed concurrently: `prompt` does not block later commands, so responses may arrive in a different order than requests; match them by `id`.
 - On failure `error` is human-readable text and `code` is the `AmaError.code` (when there is one). Unknown commands → `code: "invalid_arguments"`.
-  **Hosts must decide by `code` and never parse `error` / `message`**: human-readable text follows the interface language (`AMA_LANG`, `--lang`, `ui.language`; bilingual since wave 6, see [i18n.md](../i18n.md), Chinese). The same holds for the `message` of `notification` events.
+  **Hosts must decide by `code` and never parse `error` / `message`**: human-readable text follows the interface language (`AMA_LANG`, `--lang`, `ui.language`; bilingual since wave 6, see [i18n.md](../../guides/i18n.md), Chinese). The same holds for the `message` of `notification` events.
 - A line that is not valid JSON or lacks `type` → `{ "type": "response", "command": "parse", "success": false, "error": … }`, without `id`.
 - Commands that need extension methods of the session implementation (marked † below) return `code: "not_implemented"` on sessions that are not `AgentSessionImpl`; sessions created by the CLI and the SDK are all `AgentSessionImpl`.
 
@@ -100,7 +100,7 @@ Prompt commands **do not wait for the run to finish**: they are answered as soon
 
 ### Rewind
 
-Details in [rewind-plan.md](../rewind-plan.md) §3 (Chinese). Rewind points are the user messages on the active path that start new turns (steers and queued messages belong to the current turn and are not listed). Calling while running returns `busy`.
+Details in [rewind-plan.md](../../history/rewind-plan.md) §3 (Chinese). Rewind points are the user messages on the active path that start new turns (steers and queued messages belong to the current turn and are not listed). Calling while running returns `busy`.
 
 | Command             | Parameters                                                                                                | `data`                                                                                                                                                                                            |
 | ------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -111,7 +111,7 @@ Details in [rewind-plan.md](../rewind-plan.md) §3 (Chinese). Rewind points are
 
 `CodeRestoreResult`: `restored` / `deleted` / `conflicts` (left untouched with `skip`, overwritten with `overwrite`) / `skipped: { path, reason }[]` (`symlink` / `hardlink` / `not_regular` / `parent_moved` / `too_large` / `backup_missing`) / `failed: { path, message }[]` / `insertions` / `deletions`; paths inside cwd are relative (`/`-separated). Error codes: restoring code without a checkpoint → `no_checkpoint`; everything failed and nothing was restored → `rewind_failed` (the conversation is left alone); the entry is not a rewind point on the active path → `invalid_arguments`. For conversation-only or code-only rewinds, a `custom_message{customType: "ama.rewind-note"}` is appended to the end of the context before the next prompt, telling the model which files disagree with the conversation.
 
-After a session switch the server re-subscribes to events and sends `session_start` for the new session (`reason` `new` / `resume` / `fork`). `new_session` does not use the `parentSession` parameter yet. Entry shapes are in [session-format.md](../session-format.md) (Chinese).
+After a session switch the server re-subscribes to events and sends `session_start` for the new session (`reason` `new` / `resume` / `fork`). `new_session` does not use the `parentSession` parameter yet. Entry shapes are in [session-format.md](../../reference/session-format.md) (Chinese).
 
 ### Approvals
 
@@ -120,7 +120,7 @@ After a session switch the server re-subscribes to events and sends `session_sta
 | `set_client_capabilities` | `capabilities: ("approvals" \| "images" \| "hooks" \| "plans" \| "compact_events")[]` | `{ capabilities }`                                                                                               |
 | `permission_response`     | `requestId: string`, `decision: "allow" \| "deny" \| "allow_session"`                 | `{ accepted: boolean }` (false = not currently waiting for this id; kept and applied when that request is asked) |
 
-`compact_events` (docs/memory-plan.md D9, Chinese): once declared, `turn_end.toolResults`, `message_start` and `entry_appended` no longer repeat the body of tool results and of user messages with images (marked `contentOmitted: true`); the body is sent only in `message_end` and `tool_execution_end`. Without it the event shapes are byte-for-byte unchanged. Shapes are in [Compact events](#compact-events-compact_events). `stream-json` has no such switch and always emits the full shapes.
+`compact_events` (docs/history/memory-plan.md D9, Chinese): once declared, `turn_end.toolResults`, `message_start` and `entry_appended` no longer repeat the body of tool results and of user messages with images (marked `contentOmitted: true`); the body is sent only in `message_end` and `tool_execution_end`. Without it the event shapes are byte-for-byte unchanged. Shapes are in [Compact events](#compact-events-compact_events). `stream-json` has no such switch and always emits the full shapes.
 
 ### Tools, permissions, discovery
 
@@ -144,7 +144,7 @@ After a session switch the server re-subscribes to events and sends `session_sta
 
 ### Traces (wave 6)
 
-`get_trace` returns the session trace (the same tree as the TUI `/trace` and `ama sessions trace`, see [tui.md](tui.md)
+`get_trace` returns the session trace (the same tree as the TUI `/trace` and `ama sessions trace`, see [tui.md](../guides/tui.md)
 "Traces"). There is no new event: after `entry_appended`, fetch again with the previous `cursor.since` to refresh incrementally.
 
 | Parameter    | Meaning                                                                                                                                                                                   |
@@ -227,7 +227,7 @@ There is also the non-session event `{"type":"notification","level":"info"|"warn
 
 `parentToolCallId` appears only on inner calls made through `tools.*` inside codemode scripts; its value is the id of the outer `codemode` call, which clients use to fold the display. Inner calls do not enter the transcript.
 
-Assistant messages in `message_end`, `turn_end`, `done` / `error` and in replays (`get_messages`, `get_entries`) may carry two optional fields (model efficiency batch, docs/model-efficiency-plan.md §1.10, Chinese): `retryAfterMs` on failed messages (`Retry-After`, in ms) and `rawArguments` on tool-call blocks (the raw argument string the model produced). `subagent_*` events are unchanged; `TaskInfo` from `get_tasks` may carry `context?: "fork" | "fresh"` (the sub-session's actual context mode). All are new optional fields, `RPC_PROTOCOL_VERSION` is unchanged, and clients can ignore fields they do not know.
+Assistant messages in `message_end`, `turn_end`, `done` / `error` and in replays (`get_messages`, `get_entries`) may carry two optional fields (model efficiency batch, docs/history/model-efficiency-plan.md §1.10, Chinese): `retryAfterMs` on failed messages (`Retry-After`, in ms) and `rawArguments` on tool-call blocks (the raw argument string the model produced). `subagent_*` events are unchanged; `TaskInfo` from `get_tasks` may carry `context?: "fork" | "fresh"` (the sub-session's actual context mode). All are new optional fields, `RPC_PROTOCOL_VERSION` is unchanged, and clients can ignore fields they do not know.
 
 ### Compact events (`compact_events`)
 
@@ -243,7 +243,7 @@ In the full shapes, the result of one tool call appears once each in `message_st
 
 ### Sub-agent events (wave 5)
 
-Sub-agents started by `task` / `task_ctl` (ama sub-sessions and external agents share the same events, see [agents.md](../agents.md), Chinese):
+Sub-agents started by `task` / `task_ctl` (ama sub-sessions and external agents share the same events, see [agents.md](../../guides/agents.md), Chinese):
 
 | Event                 | Fields                                                                                                                                                                                                                      |
 | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -349,7 +349,7 @@ The `data` of `get_session_stats` is `SessionStats`:
 {"type":"context_pressure","percent":71,"threshold":70,"remainingTokens":57990,"estimatedTurnsLeft":6}
 ```
 
-`cache_miss` gives `detail` only for `prefix_changed` (`tools`, `system`, or `system:<section,…>` naming the changed sections, such as `system:hooks,memory`). The values and meanings of `reason` for `cache_warm{stopped}` are in [tui.md](tui.md) "Cache and context". The result object of `ama -p --output-format json` also has a `cache` field of the same shape.
+`cache_miss` gives `detail` only for `prefix_changed` (`tools`, `system`, or `system:<section,…>` naming the changed sections, such as `system:hooks,memory`). The values and meanings of `reason` for `cache_warm{stopped}` are in [tui.md](../guides/tui.md) "Cache and context". The result object of `ama -p --output-format json` also has a `cache` field of the same shape.
 
 It also carries `context: { tokens, window, percent }` (context used, window size and usage 0–100, defined like `contextTokens` / `contextWindow` / `contextPercent` in the table above); an unknown item is omitted (for a model without a window only `tokens` is present), and when all are unknown there is no `context`.
 
@@ -363,7 +363,7 @@ It also carries `context: { tokens, window, percent }` (context used, window siz
 
 ## Plan approval
 
-Plan mode and the plan format are described in [plan.md](../plan.md) (Chinese).
+Plan mode and the plan format are described in [plan.md](../../guides/plan.md) (Chinese).
 
 1. When a turn ends in plan mode with plain text and the reply contains a `<proposed_plan>` block, the server saves the plan and sends `plan_proposed{ planId, version, markdown, steps, filePath? }` (`steps[]`: `{ id, text, dependsOn?, agent? }`), followed by `agent_settled` as usual.
 2. The client answers only if it declared `set_client_capabilities{capabilities:["plans"]}`; otherwise the config `plan.unattended` applies: `stop` by default (the plan stays proposed, no mode switch, no execution; the client can still answer later with `plan_response`), and `approve` approves and executes within the same run.
@@ -381,7 +381,7 @@ Plan mode and the plan format are described in [plan.md](../plan.md) (Chinese).
 
 - stdin closed: no more commands are accepted and approvals are withdrawn (later asks resolve as unanswered → deny); in-flight commands and started runs finish and their responses are written, then the exit code is 0. So `printf '{"type":"prompt","message":"hi"}\n' | ama --mode rpc` gets a complete reply; to stop early, send `abort` first.
 - SIGINT / SIGTERM: the current run is interrupted and the process exits in order, with exit code 130 / 143.
-- Startup failures use the CLI exit codes ([design.md](../design.md) §11.3, Chinese): config error 3, no model or key 4, session error 5, host / hook startup failure 6, host API version mismatch 78.
+- Startup failures use the CLI exit codes ([design.md](../../design/design.md) §11.3, Chinese): config error 3, no model or key 4, session error 5, host / hook startup failure 6, host API version mismatch 78.
 
 ## Examples
 

package/docs/{agents.md → guides/agents.md}

@@ -1,7 +1,7 @@
 # Agent：子 Agent 与外部 Agent
 
 模型只认识两个工具：`task`（委派）与 `task_ctl`（管理后台任务）。`task(agent=…)` 的 `agent` 既可以是 ama 自己的子 Agent
-类型，也可以是外部 CLI Agent（外部部分见下文「外部 Agent」节）。设计依据：[wave5-plan.md](wave5-plan.md) §7、D13、D22–D24。
+类型，也可以是外部 CLI Agent（外部部分见下文「外部 Agent」节）。设计依据：[wave5-plan.md](../history/wave5-plan.md) §7、D13、D22–D24。
 
 ## 子 Agent
 
@@ -92,7 +92,7 @@ ama 再跑一轮、在消息里要求「不要调用工具、直接给最终报
 `<task-notification>`：
 
 - 交互界面：`Ctrl+B` / `/tasks bg [id]` / Agent 栏里按 `b`（见 [tui.md](tui.md)「子 Agent」）；
-- RPC：`background_task { taskId? }`（[rpc.md](rpc.md)），SDK：`session.backgroundTask(taskId?)`，返回实际转了的 `taskId`；
+- RPC：`background_task { taskId? }`（[rpc.md](../reference/rpc.md)），SDK：`session.backgroundTask(taskId?)`，返回实际转了的 `taskId`；
   不给 `taskId` 时转全部前台运行中任务，正在 `task_ctl wait` 的等待也一并打断；
 - 自动：`subagents.autoBackgroundAfterMs` 大于 0 时，前台任务运行超过该毫秒数自动转后台（缺省 0 关闭）。
 
@@ -133,7 +133,7 @@ ama 再跑一轮、在消息里要求「不要调用工具、直接给最终报
 每个任务有会话内唯一的 `taskId`（`t1`、`t2` …）。子会话结束后不立即释放，最多保留 4 个（`subagents.retainSessions`；
 最久未用的先释放内存，JSONL 一直在）。`task{taskId}` / `task_ctl send` 续聊时，保留中的直接追加消息，已释放的按会话文件重新打开再追加——
 同一个任务始终写同一个 JSONL。父会话在任务开始、每次续聊与结束时写一条 `custom{ama.task}`
-（[session-format.md](session-format.md)）；`--resume` 时据此重建任务列表，当时还在运行的标 `interrupted`，仍可续聊。
+（[session-format.md](../reference/session-format.md)）；`--resume` 时据此重建任务列表，当时还在运行的标 `interrupted`，仍可续聊。
 内存会话（`--no-session`）的任务被释放后不能续聊。子会话转录常达数十 MB，保留得越多常驻内存越大；频繁轮换续聊
 5 个以上任务时可调大保留数，代价只是被释放的任务续聊时多一次从磁盘重开。
 
@@ -159,7 +159,7 @@ worktree 里与父 cwd 对应的目录。结束时没有改动（工作区干净
 - 类型声明了 `tools` / `disallowed-tools`（或参数给了 `tools`）时，工具表不变，不可用的工具在执行层拒绝
   （`Tool "X" is not available in this session.`），并在 `<task>` 里列出。只读类型照旧走只读管线。
 - `<task>` 同时列出按深度拒绝的 `task` / `task_ctl` 并要求不要调用它们（执行层仍是深度拒绝的文案）。实测仍有模型把父消息里
-  「调用 task」的指令当成自己的：调一次被拒，多一轮请求，有时随后只回报失败、不做子任务（见 [benchmarks](benchmarks/efficiency-2026-10.md)「F2」）。
+  「调用 task」的指令当成自己的：调一次被拒，多一轮请求，有时随后只回报失败、不做子任务（见 [benchmarks](../benchmarks/efficiency-2026-10.md)「F2」）。
 - `isolation: "worktree"` 时子会话的 cwd 是 worktree，`<task>` 里说明上文的相对路径指父目录；cwd 节变化以尾部补丁发送，
   不影响已缓存的前缀。
 
@@ -171,12 +171,12 @@ worktree 里与父 cwd 对应的目录。结束时没有改动（工作区干净
 何时用 fork：子任务需要你已经读过、讨论过的内容时。fork 的首个请求把父上下文整段带上，按命中价计费；fresh 只发系统提示、
 工具表与任务说明，但你得在 `prompt` 里写清全部背景，子 Agent 往往还要重新读文件。
 
-| 供应商（命中价 / 未命中价）     | 8k 父上下文 fork 一次（实测，见 [benchmarks](benchmarks/efficiency-2026-10.md)「F」） | 适合                         |
-| ------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------- |
-| DeepSeek（约 1/50）             | 命中 77%，与父自己的下一回合相同；折合约 1.9k 全价 token                              | 需要父上下文时几乎总划算     |
-| Kimi（约 1/4–1/10）             | 命中 97.5%                                                                            | 需要父上下文、且要重读较多时 |
-| OpenAI 系（经中转，不发路由键） | 两次分别 0% 与 85%，取决于中转把请求路由到哪个上游                                    | 视中转而定                   |
-| Anthropic（1/10，写入 1.25×）   | 未实测；前缀相同，命中应与父的下一回合相同                                            | 需要父上下文时               |
+| 供应商（命中价 / 未命中价）     | 8k 父上下文 fork 一次（实测，见 [benchmarks](../benchmarks/efficiency-2026-10.md)「F」） | 适合                         |
+| ------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------- |
+| DeepSeek（约 1/50）             | 命中 77%，与父自己的下一回合相同；折合约 1.9k 全价 token                                 | 需要父上下文时几乎总划算     |
+| Kimi（约 1/4–1/10）             | 命中 97.5%                                                                               | 需要父上下文、且要重读较多时 |
+| OpenAI 系（经中转，不发路由键） | 两次分别 0% 与 85%，取决于中转把请求路由到哪个上游                                       | 视中转而定                   |
+| Anthropic（1/10，写入 1.25×）   | 未实测；前缀相同，命中应与父的下一回合相同                                               | 需要父上下文时               |
 
 fork 的成本不止首请求：子会话**每一回合**都重读整段父前缀。按命中价折算，8k 父上下文 × 30 回合在 DeepSeek（1/50）上约
 4.8k 全价 token，在 Kimi / Anthropic（1/4–1/10）上约 24k–60k，中转落空时全价。所以 DeepSeek 上子任务只要重读 ≥ 1 份
@@ -189,7 +189,7 @@ fork 的成本不止首请求：子会话**每一回合**都重读整段父前
 
 ### 事件与统计
 
-RPC / SDK 事件 `subagent_start` / `subagent_update` / `subagent_background` / `subagent_end` 见 [rpc.md](rpc.md)「子 Agent 事件」。
+RPC / SDK 事件 `subagent_start` / `subagent_update` / `subagent_background` / `subagent_end` 见 [rpc.md](../reference/rpc.md)「子 Agent 事件」。
 `getStats().tasks` 给出任务总数、运行中数量与按状态的计数；子会话的缓存命中与重计费仍汇总在 `cache.subagents`。
 RPC `get_tasks` / `get_agents` 返回任务快照与可用类型（来源、定义文件路径）。交互界面的 `/tasks`、`/agents` 与 task 工具行的折叠显示见 [tui.md](tui.md)「子 Agent」。
 
@@ -245,7 +245,7 @@ ama 改为直接驱动 `pi --mode rpc`，并以 `-e` 给这一次运行加载一
 
 每条路径在临时目录各跑两个会话：非 git 目录里两轮「只回 OK」+ 一次触发审批的写文件（`default` 模式）；git 目录里长输出时中断，再续一轮。
 模型用各家最便宜的：Claude `haiku`、Codex `gpt-6-luna`、Copilot `gpt-5-mini`、OpenCode `opencode/mimo-v2.6-flash-free`、pi `openai-codex/gpt-6-luna`。
-记录与原始数字见 [benchmarks/external-agents-2026-10.md](benchmarks/external-agents-2026-10.md)。
+记录与原始数字见 [benchmarks/external-agents-2026-10.md](../benchmarks/external-agents-2026-10.md)。
 
 | 路径                       | 两轮续聊 | 审批写文件                                        | 中断后续聊    | 用量 / 上下文                     | 非 git 目录    |
 | -------------------------- | -------- | ------------------------------------------------- | ------------- | --------------------------------- | -------------- |
@@ -313,7 +313,7 @@ ama 改为直接驱动 `pi --mode rpc`，并以 `-e` 给这一次运行加载一
 | `full-auto` | `auto`（从不给 `bypassPermissions`） | `never` / `workspace-write`（从不给 `danger-full-access`） | 同上                                                     |
 
 上表 ACP 一列是缺省规则；模式 id 与 ama 不同名的 Agent 在驱动表里有显式映射（见上文「实测能力矩阵」后的说明）。
-ACP Agent 不给 `modes`、改用 category `mode` 的配置项表达模式时，按上表同一映射在配置项的可选值里找，经 `session/set_config_option` 设置（见 [acp.md](acp.md)「作为客户端」）。
+ACP Agent 不给 `modes`、改用 category `mode` 的配置项表达模式时，按上表同一映射在配置项的可选值里找，经 `session/set_config_option` 设置（见 [acp.md](../reference/acp.md)「作为客户端」）。
 
 一次性打印模式不能审批，只在只读任务下用。
 

package/docs/{codemode.md → guides/codemode.md}

@@ -1,6 +1,6 @@
 # codemode
 
-设计依据见 [design.md](design.md) §5.5、§5.6、§9.1。
+设计依据见 [design.md](../design/design.md) §5.5、§5.6、§9.1。
 
 `codemode` 工具让模型写一段 JavaScript，在脚本里经 `tools.*` 编排多次工具调用，只有脚本输出回到模型。长流程、工具密集的任务里，它把多次往返合成一次，减少往返次数与缓存读取；短任务里模型照常直接调用工具，codemode 只多占约 400 token 前缀，所以 `default` 预设在网络隔离的运行时上缺省开着它。
 
@@ -24,7 +24,7 @@
 
 缺省配置里不写 `codemode.mode`（`ama init` 生成的 `config.json` 也不写），所以这张映射以后调整时老用户同样生效。`ama config show` / `ama doctor` 显示生效模式与原因（跟随哪个预设、网络由 Node 还是操作系统沙箱隔离）；`ama doctor` 另列操作系统沙箱能力。
 
-`minimal` / `coordinator` 预设缺省不带 codemode，也没有 grep / glob：模型找代码只能用 bash（`default` 权限模式下每次审批、`-p` 下被拒）。要检索就 `tools.default: ["+grep","+glob"]` 直接加上，比为了检索打开 codemode 便宜（见 [design.md](design.md) §5.6）；`codemode-only` 的脚本里 `tools.grep()` / `tools.glob()` / `tools.ls()` 都可调用。
+`minimal` / `coordinator` 预设缺省不带 codemode，也没有 grep / glob：模型找代码只能用 bash（`default` 权限模式下每次审批、`-p` 下被拒）。要检索就 `tools.default: ["+grep","+glob"]` 直接加上，比为了检索打开 codemode 便宜（见 [design.md](../design/design.md) §5.6）；`codemode-only` 的脚本里 `tools.grep()` / `tools.glob()` / `tools.ls()` 都可调用。
 
 `coordinator` 预设即使显式 `on`，脚本里能调用的工具也只限它的活动集（read 与宿主工具）：`tools.bash`、`tools.write` 在脚本里同样不存在，协调者「不写文件、不跑 bash」的约定不能经 codemode 绕过。
 
@@ -87,7 +87,7 @@
 
 - `codemode` 本身作为一次工具调用经过 PreToolUse、权限与 PostToolUse。
 - 脚本里的每次 `tools.*` 再各自经过完整流程，Hook 按**真实工具名**匹配（`bash`，不是 `codemode`）；Hook 输入多两个字段：`viaCodemode: true` 与 `parentToolCallId`（外层 `codemode` 调用的 id）。
-- 事件：`tool_execution_update` 透传脚本输出（最近 4000 字符）；内层调用发 `tool_execution_start / end`，带 `parentToolCallId`，不进转录、不进模型上下文。`ama --mode acp` 把每次内层调用单列为一条 `tool_call`（标题前缀 `codemode › `，`_meta.ama.parentToolCallId` 指向外层），其权限请求关联到这条内层调用（见 [acp.md](acp.md)）。
+- 事件：`tool_execution_update` 透传脚本输出（最近 4000 字符）；内层调用发 `tool_execution_start / end`，带 `parentToolCallId`，不进转录、不进模型上下文。`ama --mode acp` 把每次内层调用单列为一条 `tool_call`（标题前缀 `codemode › `，`_meta.ama.parentToolCallId` 指向外层），其权限请求关联到这条内层调用（见 [acp.md](../reference/acp.md)）。
 
 ## 沙箱
 

package/docs/{hooks.md → guides/hooks.md}

@@ -1,6 +1,6 @@
 # 命令式 Hook（hooks.json）
 
-命令式 Hook 是在固定时机运行的 shell 命令：ama 把事件写成 JSON 交给命令的 stdin，按退出码与 stdout JSON 决定放行、阻止或改写。它是**用户策略**层——可以改工具输入、一票否决工具调用、给提示追加上下文、让运行再跑一轮。类型定义在 `src/hooks/types.ts`（经 `@armadra/agent` 导出 `HookInput`、`HookOutput`、`HookConfig` 等）。设计依据见 [design.md](design.md) §6.1、§6.3、§7.3。
+命令式 Hook 是在固定时机运行的 shell 命令：ama 把事件写成 JSON 交给命令的 stdin，按退出码与 stdout JSON 决定放行、阻止或改写。它是**用户策略**层——可以改工具输入、一票否决工具调用、给提示追加上下文、让运行再跑一轮。类型定义在 `src/hooks/types.ts`（经 `@armadra/agent` 导出 `HookInput`、`HookOutput`、`HookConfig` 等）。设计依据见 [design.md](../design/design.md) §6.1、§6.3、§7.3。
 
 ## 配置
 
@@ -125,7 +125,7 @@ interface HookOutput {
 - `additionalContext` / `customInstructions` 按配置顺序拼接。
 - 任一 Hook 返回 `continue: false` 即请求结束运行。
 
-一次工具调用的完整顺序（[design.md](design.md) §6.3）：
+一次工具调用的完整顺序（[design.md](../design/design.md) §6.3）：
 
 ```text
 模型产出工具调用

package/docs/guides/i18n.md

@@ -0,0 +1,93 @@
+# 界面语言（中英双语）
+
+> 第六波（docs/history/wave6-plan.md §5、D18–D23）。本文是开发约定：怎么选语言、文案放哪、键怎么起名、怎么测。
+> 调研依据见 [research/wave6/R8-i18n.md](../research/wave6/R8-i18n.md)。
+
+## 语言怎么定
+
+优先级从高到低，**进程启动时定一次**，不做运行中切换：
+
+1. 环境变量 `AMA_LANG`（`zh` / `en`，`zh_CN` 之类也认；写错的值忽略）；
+2. 命令行 `--lang zh|en`（也可写在子命令前：`ama --lang en doctor`）；SDK `createRuntime({ language })` / `createAgentSession({ language })` 等价；
+3. profile 的 `language`（嵌入宿主跟随画布界面语言）；
+4. 配置 `ui.language`（`auto` / `zh` / `en`，缺省 `auto`；用户级 / 项目级都可设）；
+5. `LC_ALL` → `LC_MESSAGES` → `LANG` 第一个非空值：`zh*` 为中文，其余（含 `C`、`POSIX`、`en_*`）为英文；
+6. 都没有：英文。
+
+`cli/main.ts` 在解析参数后、任何输出前按 1、2、用户级 `ui.language`、5 定语言；bootstrap 合并 profile 与项目级后，若它们给了 `ui.language` / `language`，再补定一次（仍以 1、2 为准）。`ama doctor` 显示「界面语言：zh（来源 LANG=zh_CN.UTF-8）」（`resolveLocaleWithSource`）。
+
+**界面语言只影响给人看的文字。** 发给模型的一切（系统提示、工具描述、工具结果里的标记、截断 / 裁剪占位、外部 Agent 报告、Hook 阻止理由、拒绝理由）固定英文，两种语言下请求逐字节相同。想让模型用某种语言回复，用 `ui.replyLanguage`（在 `rules` 节末尾追加一句英文规则，不设时零字节变化）。
+
+## 文案放哪
+
+```text
+src/i18n/
+  index.ts      Locale、resolveLocale / resolveLocaleWithSource、setLocale / getLocale、msg()、messagesFor()
+  types.ts      Messages<T>
+  format.ts     plural()、formatDuration()
+  catalog.ts    汇总全部领域（第六波 C0 一次登记，之后无人再改）
+  messages/<领域>.ts
+```
+
+| 领域文件                                                                    | 归属批次                              |
+| --------------------------------------------------------------------------- | ------------------------------------- |
+| `cli`、`subcommands`                                                        | W6-I1                                 |
+| `interactive`、`approval`、`plan`、`rewind`、`panels`、`permissions`        | W6-I2                                 |
+| `report`、`print`、`drivers`、`session`、`errors`                           | W6-I3                                 |
+| `config`                                                                    | W6-I4                                 |
+| `agents` / `trace` / `memory` / `auth` / `settings`                         | W6-A / W6-T1、T2 / W6-M / W6-O / W6-S |
+| `acp`（子对象 `core` / `auth` / `session` / `tools` / `config` / `client`） | ACP-C0 建，各子对象归 ACP 补全的批次  |
+
+每个领域文件同时导出 `en`（形状源）与 `zh`：
+
+```ts
+import { plural } from "../format.js";
+import type { Messages } from "../types.js";
+
+export const en = {
+  limitTurns: (limit: number) => `ama: reached the turn limit ${limit}; run ended early`,
+  dirSummary: (files: number, size: string) => `directory, ${plural(files, "file")}, ${size}`,
+  approval: { title: "Approve tool call", keys: { allow: "allow", deny: "deny" } },
+};
+
+export const zh = {
+  limitTurns: (limit) => `ama: 已达到回合上限 ${limit}，运行在完成前结束`,
+  dirSummary: (files, size) => `目录，${files} 个文件，${size}`,
+  approval: { title: "Approve tool call", keys: { allow: "allow", deny: "deny" } },
+} satisfies Messages<typeof en>;
+```
+
+`satisfies Messages<typeof en>` 让缺键、多键、参数个数 / 类型不符都在 `tsc` 期报错——两种语言必须同时给。
+
+取用：`const m = msg().print; io.stderr(m.limitTurns(limit))`。用嵌套属性访问，不用字符串键。
+
+## 键名规范
+
+- 领域文件名即一级命名空间（`msg().approval…`）；
+- 叶子 camelCase，按「组件.用途」分组：`approval.title`、`approval.keys.allow`、`rewind.skip.failed`；
+- 不以文案内容命名（`notInstalled` 可以，`weiAnZhuang` 不行）；
+- **整句一个键，禁止片段拼接**：英文语序不同，`"追加写入" + 词 + 路径` 这种要写成一个函数，条件分支写进函数体；
+- 插值写成箭头函数，参数类型写在 en 上；复数只英文需要，用 `plural(n, "file")`（不规则词给第三参数）；
+- 紧凑时长 `formatDuration(ms)`（`45s` / `2m 10s` / `1h24m`）两种语言共用；`formatTokens` / `formatUsd` / `formatPercent`、日期（ISO）与 compact 状态行记号（`ctx`、`cache`、`$`、`↑ ↓`、`⎇`、`·`）不译；
+- 枚举值、命令名、配置键、动作 id、错误码不译。
+
+## 不要这样做
+
+- **模块顶层求值**：`const HELP = msg().cli.help` 会按 import 时的语言定死（SDK / 嵌入场景显示错语言）。改成函数或 getter；`scripts/check-i18n.mjs` 会拦。
+- **按文案判断逻辑**：`text === "未安装"`、`reason.startsWith("失败")`。界面文案会随语言变，逻辑用枚举 / 码（第六波 C0 已把三处改掉）。用户**输入**的别名（`批准`、`步骤`、粘贴标记 `[粘贴 #` / `[paste #`）两种语言同时识别，与界面语言无关。
+- **模型侧模块 import `src/i18n`**：系统提示、工具（`src/tools/**`）、Plan 提示、内置子 Agent、Skill、压缩、codemode 声明、Memory 工具不得 import——`src/i18n/guard.test.ts` 守着。这些模块需要给人看的错误时抛 `AmaError(code, englishMessage, { detail })`，由界面层按 `detail` 渲染（例：`tools/image-file.ts` → `modes/image-input.ts` 的 `msg().errors.imageFile(detail)`）。
+- **宿主解析 `message`**：RPC / ACP 的 `error.message`、`-p` 的 stderr 是人读文本，会随语言变；宿主按 `code` 判断。
+
+## 测试
+
+- 测试缺省钉 zh：`test/helpers/setup.ts` 设 `AMA_LANG=zh` 并 `setLocale("zh")`，子进程也是 zh。迁移批次的验收是现有 zh 帧黄金与断言**字节不变**。
+- en 用例自己 `setLocale("en")`（或传 `AMA_LANG=en`），用完在 `afterEach` 里 `setLocale("zh")`；en 帧黄金放 `test/fixtures/tui/en/`。
+- `src/cli/lang-independence.test.ts`：同一脚本在 zh / en 下各跑一遍，发给供应商的请求逐字节相同。
+- `scripts/check-i18n.mjs`（`pnpm check:i18n`，在 `pnpm ci` 里）：
+  1. 严格（W6-I5 起，基线已清零删除）：`src/**` 源码里含汉字的代码行（注释不算）**出现即失败**。不扫的文件（测试、测试支撑、`src/i18n/`、models.dev 上游快照）在脚本的 `SKIPPED`，允许的行（用户输入别名、粘贴标记识别、价格覆盖数据的 `_reason`）在 `ALLOWED_LINES`，每条都写了理由；新增条目要在 PR 里说明；
+  2. `en` 目录里不得有汉字，`zh` 目录里不得留 `TODO`；
+  3. 顶层常量不得立即调用 `msg()`。
+
+## 体积
+
+bundle 用 `charset: "utf8"` 输出（中文按 UTF-8 原样，不转 `\uXXXX`），抵消英文目录带来的增量。

package/docs/{memory.md → guides/memory.md}

@@ -1,6 +1,6 @@
 # 记忆（Memory）
 
-> 第六波 W6-M（设计见 [wave6-plan.md](wave6-plan.md) §3、D8–D12；调研 [research/wave6/R7-memory.md](research/wave6/R7-memory.md)）。
+> 第六波 W6-M（设计见 [wave6-plan.md](../history/wave6-plan.md) §3、D8–D12；调研 [research/wave6/R7-memory.md](../research/wave6/R7-memory.md)）。
 
 跨会话的个人笔记：你说「记住……」，模型把它写成一条 Markdown，下次会话开始时索引进系统提示，正文按需读取。
 **缺省关闭**；关闭时不读盘、不注册工具、不渲染节，发给模型的请求与没有这个功能时逐字节相同。