@armadra/agent 0.7.6 → 0.8.1

package/docs/assets/ama-wordmark-light.svg

@@ -0,0 +1,37 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="216" height="96" viewBox="0 0 216 96" shape-rendering="crispEdges" role="img" aria-label="ama">
+  <title>ama</title>
+  <g fill="#005fd7">
+    <rect x="24" y="8" width="24" height="8"/>
+    <rect x="16" y="16" width="40" height="8"/>
+    <rect x="8" y="24" width="24" height="8"/>
+    <rect x="40" y="24" width="24" height="8"/>
+    <rect x="8" y="32" width="16" height="8"/>
+    <rect x="48" y="32" width="16" height="8"/>
+    <rect x="8" y="40" width="56" height="16"/>
+    <rect x="8" y="56" width="16" height="24"/>
+    <rect x="48" y="56" width="16" height="24"/>
+  </g>
+  <g fill="#005faf">
+    <rect x="72" y="8" width="16" height="8"/>
+    <rect x="128" y="8" width="16" height="8"/>
+    <rect x="72" y="16" width="24" height="16"/>
+    <rect x="120" y="16" width="24" height="16"/>
+    <rect x="72" y="32" width="32" height="8"/>
+    <rect x="112" y="32" width="32" height="8"/>
+    <rect x="72" y="40" width="16" height="40"/>
+    <rect x="96" y="40" width="24" height="8"/>
+    <rect x="128" y="40" width="16" height="40"/>
+    <rect x="104" y="48" width="8" height="8"/>
+  </g>
+  <g fill="#8700af">
+    <rect x="168" y="8" width="24" height="8"/>
+    <rect x="160" y="16" width="40" height="8"/>
+    <rect x="152" y="24" width="24" height="8"/>
+    <rect x="184" y="24" width="24" height="8"/>
+    <rect x="152" y="32" width="16" height="8"/>
+    <rect x="192" y="32" width="16" height="8"/>
+    <rect x="152" y="40" width="56" height="16"/>
+    <rect x="152" y="56" width="16" height="24"/>
+    <rect x="192" y="56" width="16" height="24"/>
+  </g>
+</svg>

package/docs/en/README.md

@@ -0,0 +1,39 @@
+# Documentation index
+
+English · [简体中文](../README.md)
+
+Most documents are written in Chinese; seven have English translations, kept in the same layout under `docs/en/`.
+When a translation and the Chinese version differ, the Chinese version is authoritative. Relative links and the
+`docs/…md` paths in source comments are checked by `pnpm check:docs` (`scripts/check-doc-links.mjs`).
+
+| Directory     | Contents                                                                      |
+| ------------- | ----------------------------------------------------------------------------- |
+| `guides/`     | How to use ama and how it behaves today; kept in step with the code           |
+| `reference/`  | Protocols and file formats; shape changes must update these                   |
+| `design/`     | Target designs and the visual spec; each states its status in the first lines |
+| `history/`    | Finished implementation plans and audits, kept for the record only            |
+| `research/`   | Research reports, kept for the record only                                    |
+| `benchmarks/` | Measurements and raw data                                                     |
+
+## English translations
+
+| Document                                    | Contents                                                                            |
+| ------------------------------------------- | ----------------------------------------------------------------------------------- |
+| [Terminal UI](guides/tui.md)                | Layout, status bar, keys, commands, rewind, approvals, agent bar, traces, `/config` |
+| [Providers and models](guides/providers.md) | Built-in providers, channels, keys, ChatGPT login, relays, models.dev, caching      |
+| [Permissions](guides/permissions.md)        | The six modes, decision order, auto's three tiers                                   |
+| [Sessions](guides/sessions.md)              | Stats, search, `--from`, export, traces, checkpoints                                |
+| [RPC protocol](reference/rpc.md)            | `ama --mode rpc`: stdio JSONL commands, responses and events                        |
+| [ACP](reference/acp.md)                     | `ama --mode acp`, sign-in methods, deviations, the ACP client                       |
+| [Host adapter API](reference/host-api.md)   | `@armadra/agent/host`: tools, approvals, injected messages, status                  |
+
+## Chinese only
+
+- Guides: [plan mode](../guides/plan.md), [sub-agents and external agents](../guides/agents.md) (with the
+  capability matrix), [memory](../guides/memory.md), [command hooks](../guides/hooks.md),
+  [codemode](../guides/codemode.md), [OS sandbox](../guides/sandbox.md), [interface language](../guides/i18n.md).
+- Reference: [session file format](../reference/session-format.md).
+- Design: [overall design](../design/design.md), [terminal UI visual spec](../design/tui-design.md),
+  [search and web access](../design/search-plan.md) (only local search is implemented),
+  [local extensions](../design/extensions.md) (draft, not implemented).
+- History, research and benchmarks: see the [Chinese index](../README.md).

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

@@ -1,22 +1,22 @@
 # Permission modes and auto decisions
 
-English · [简体中文](../permissions.md)
+English · [简体中文](../../guides/permissions.md)
 
-> Translated from the Chinese [docs/permissions.md](../permissions.md) as of commit `6b5455a`. When the two differ, the
+> Translated from the Chinese [docs/guides/permissions.md](../../guides/permissions.md) as of commit `6b5455a`. When the two differ, the
 > Chinese version is authoritative.
 
-This document covers ama's six permission modes, the decision order for every tool call, and how the three tiers of `auto` mode, "rule tier → static judgement → model classifier", decide between allowing and asking. The overall design is in [design.md](../design.md) §6.3 and §7 (Chinese); hook input and output are in [hooks.md](../hooks.md) (Chinese).
+This document covers ama's six permission modes, the decision order for every tool call, and how the three tiers of `auto` mode, "rule tier → static judgement → model classifier", decide between allowing and asking. The overall design is in [design.md](../../design/design.md) §6.3 and §7 (Chinese); hook input and output are in [hooks.md](../../guides/hooks.md) (Chinese).
 
 ## Modes
 
-| Value       | Display name       | Read | Write (inside the project)                      | Execute (bash etc.)                                         | When to use                                                                   |
-| ----------- | ------------------ | ---- | ----------------------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------- |
-| `default`   | Manual             | ✓    | ask                                             | ask                                                         | Default                                                                       |
-| `auto-edit` | Accept edits       | ✓    | ✓                                               | ask                                                         | You trust it to edit code but want to see each command                        |
-| `plan`      | Plan               | ✓    | deny                                            | read-only commands allowed, everything else denied          | Read-only research, then a plan for approval ([plan.md](../plan.md), Chinese) |
-| `auto`      | Auto               | ✓    | ✓ (protected paths and outside the project ask) | safe-list commands allowed, the rest judged by a classifier | Recommended: routine work is not interrupted, only risky steps ask            |
-| `full-auto` | Bypass permissions | ✓    | ✓                                               | ✓                                                           | Throwaway sandboxes, containers                                               |
-| `allowlist` | Allowlist only     | ✓    | only calls matching allow rules                 | read-only commands and calls matching allow rules           | CI: never asks; anything not listed is denied                                 |
+| Value       | Display name       | Read | Write (inside the project)                      | Execute (bash etc.)                                         | When to use                                                                             |
+| ----------- | ------------------ | ---- | ----------------------------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| `default`   | Manual             | ✓    | ask                                             | ask                                                         | Default                                                                                 |
+| `auto-edit` | Accept edits       | ✓    | ✓                                               | ask                                                         | You trust it to edit code but want to see each command                                  |
+| `plan`      | Plan               | ✓    | deny                                            | read-only commands allowed, everything else denied          | Read-only research, then a plan for approval ([plan.md](../../guides/plan.md), Chinese) |
+| `auto`      | Auto               | ✓    | ✓ (protected paths and outside the project ask) | safe-list commands allowed, the rest judged by a classifier | Recommended: routine work is not interrupted, only risky steps ask                      |
+| `full-auto` | Bypass permissions | ✓    | ✓                                               | ✓                                                           | Throwaway sandboxes, containers                                                         |
+| `allowlist` | Allowlist only     | ✓    | only calls matching allow rules                 | read-only commands and calls matching allow rules           | CI: never asks; anything not listed is denied                                           |
 
 In every mode, deny rules and hook denies are checked first and deny outright; the dangerous-command list (`rm -rf /`, `git push --force`, `curl … | sh` and so on, see the README "Safety" section) always asks, which becomes deny under `allowlist` and when unattended.
 
@@ -47,11 +47,11 @@ Approvals do not only come from the main session. The dialog (and RPC `permissio
 | Permission requests from external agents (claude / codex / ACP) | `[claude · session abc12345]`                        | The title, kind, paths involved and input summary given by the external agent | A human only: host → interface → deny when unattended; neither the auto classifier nor the model takes part |
 | First run of an external agent in this session                  | Title "first run of an external agent"               | An explanation (runs with your login in that CLI) and the mode                | allow / deny rules `task(<id>)` and `full-auto` let it through; otherwise a human decides (no classifier)   |
 
-"Allow for this session" of an external agent is remembered by that agent itself. In Manual mode the approval of a `task(agent=…)` call and the first-run confirmation are merged into one (see [agents.md](../agents.md), Chinese). The RPC `context` is `{ depth, taskId, origin }` ([rpc.md](rpc.md) "Approvals").
+"Allow for this session" of an external agent is remembered by that agent itself. In Manual mode the approval of a `task(agent=…)` call and the first-run confirmation are merged into one (see [agents.md](../../guides/agents.md), Chinese). The RPC `context` is `{ depth, taskId, origin }` ([rpc.md](../reference/rpc.md) "Approvals").
 
 ## Plan mode and read-only commands
 
-Step ③ of plan mode looks at the input (implemented by `planDecision` in `src/permissions/pipeline.ts`); the flow and plan approval are in [plan.md](../plan.md) (Chinese):
+Step ③ of plan mode looks at the input (implemented by `planDecision` in `src/permissions/pipeline.ts`); the flow and plan approval are in [plan.md](../../guides/plan.md) (Chinese):
 
 | Call                                  | Under plan                                                                                                                                               |
 | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -105,7 +105,7 @@ schema validation
 
 ### Approval-free commands inside the sandbox
 
-With `sandbox.bash: auto` and an OS sandbox on the machine that can restrict writes ([sandbox.md](../sandbox.md) "phase two", Chinese), bash runs through the sandbox. Under default / auto-edit, a bash call needs no approval (`PermissionVerdict.sandboxed: true`) when all of the following hold:
+With `sandbox.bash: auto` and an OS sandbox on the machine that can restrict writes ([sandbox.md](../../guides/sandbox.md) "phase two", Chinese), bash runs through the sandbox. Under default / auto-edit, a bash call needs no approval (`PermissionVerdict.sandboxed: true`) when all of the following hold:
 
 1. It will run inside the sandbox: no `sandbox: false`;
 2. `sandbox.network: deny` (network access can exfiltrate data, so `allow` asks as usual);

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

@@ -1,11 +1,11 @@
 # Providers and models
 
-English · [简体中文](../providers.md)
+English · [简体中文](../../guides/providers.md)
 
-> Translated from the Chinese [docs/providers.md](../providers.md) as of commit `514202f`. When the two differ, the
+> Translated from the Chinese [docs/guides/providers.md](../../guides/providers.md) as of commit `514202f`. When the two differ, the
 > Chinese version is authoritative.
 
-Built-in providers, model references, API keys, custom providers and relays, the compat switches of each protocol, and caching. The design rationale is in [design.md](../design.md) §3 and §9.1 (Chinese).
+Built-in providers, model references, API keys, custom providers and relays, the compat switches of each protocol, and caching. The design rationale is in [design.md](../../design/design.md) §3 and §9.1 (Chinese).
 
 ## Config directory
 
@@ -182,12 +182,13 @@ ama auth logout chatgpt                # siwc revokes the refresh token first, t
 
 **Error codes** (error messages start with the code; hosts decide by code):
 
-| Code             | Source                                                                                                       | Handling                                                  |
-| ---------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------- |
-| `quota_exceeded` | siwc 429 `subscription_sharing_usage_limit_exceeded`; codex 429 `usage_limit_reached` / `usage_not_included` | no retry; carries the reset time and emits `quota_update` |
-| `auth_expired`   | a 401 still failing after one refresh, a permanently failed refresh, an entry marked `needsLogin`            | no retry; run `ama auth login chatgpt` again              |
-| `not_eligible`   | siwc 403 `subscription_sharing_user_not_eligible`                                                            | no retry, no re-login; see troubleshooting below          |
-| (as is)          | 503 and similar                                                                                              | the session layer's existing backoff retries              |
+| Code                | Source                                                                                                       | Handling                                                                                                                     |
+| ------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
+| `quota_exceeded`    | siwc 429 `subscription_sharing_usage_limit_exceeded`; codex 429 `usage_limit_reached` / `usage_not_included` | no retry; carries the reset time and emits `quota_update`                                                                    |
+| `auth_expired`      | a 401 still failing after one refresh, a permanently failed refresh, an entry marked `needsLogin`            | no retry; run `ama auth login chatgpt` again                                                                                 |
+| `not_eligible`      | siwc 403 `subscription_sharing_user_not_eligible`                                                            | no retry, no re-login; see troubleshooting below                                                                             |
+| `model_unavailable` | codex 400 "model is not supported when using Codex with a ChatGPT account"                                   | no retry; the backend's model list changed (stale discovery cache): run `ama models discover chatgpt` and pick another model |
+| (as is)             | 503 and similar                                                                                              | the session layer's existing backoff retries                                                                                 |
 
 **Troubleshooting `not_eligible`**: the account cannot share its plan usage with ama. Possible causes: the plan (sharing is offered to Plus / Pro only); a workspace account (Team / Enterprise / Edu may not offer it); a region restriction or a preview that has not rolled out yet — **the most likely cause when a Pro account still gets this error**. You can sign in with `ama auth login chatgpt --flavor codex` instead. A successful siwc login only means authorization passed; whether plan usage can be shared is only confirmed on the first request.
 
@@ -448,9 +449,9 @@ OpenRouter's Messages endpoint only gives cache usage in `message_delta`; parsin
 
 Most usage in long tasks is cache reads: once the prefix changes, every later request re-reads it at full price. ama handles caching in three layers: the **protocol layer** places breakpoints, sends cache keys and retention tiers the way each provider expects, and marks whether a response had cache fields; the **session layer** records each request's prefix fingerprint, detects misses, decides whether the endpoint reports cache usage and warms the cache during long tool runs; the **display layer** is the status bar, `/session`, RPC stats and `ama models cache-probe` (how to read the interface is in [tui.md](tui.md) "Cache and context").
 
-Prefix stability is guaranteed by assembly: the system prompt sections have a fixed order without timestamps, tools are sorted by name, and mid-session changes are only appended at the end as system patches ([session-format.md](../session-format.md), Chinese).
+Prefix stability is guaranteed by assembly: the system prompt sections have a fixed order without timestamps, tools are sorted by name, and mid-session changes are only appended at the end as system patches ([session-format.md](../../reference/session-format.md), Chinese).
 
-**The leading system prompt and the tool declarations are written once per session.** Section patches after the conversation has started (AGENTS.md, Skills or SessionStart hook output changed on resume, host instructions refreshed, the memory section re-rendered after compaction) do not rewrite the head: protocols without `supportsMidConvoSystemMessages` render them as a user message wrapped in `<system-reminder>` at the patch's position, so the previous request stays a byte-for-byte prefix. Measured on DeepSeek, a mid-conversation system message is accepted and the prefix cache holds, but the model still answers from the leading one, so DeepSeek keeps the switch off ([cache-midconvo-2026-10-09](../benchmarks/cache-midconvo-2026-10-09.md), Chinese).
+**The leading system prompt and the tool declarations are written once per session.** Section patches after the conversation has started (AGENTS.md, Skills or SessionStart hook output changed on resume, host instructions refreshed, the memory section re-rendered after compaction) do not rewrite the head: protocols without `supportsMidConvoSystemMessages` render them as a user message wrapped in `<system-reminder>` at the patch's position, so the previous request stays a byte-for-byte prefix. Measured on DeepSeek, a mid-conversation system message is accepted and the prefix cache holds, but the model still answers from the leading one, so DeepSeek keeps the switch off ([cache-midconvo-2026-10-09](../../benchmarks/cache-midconvo-2026-10-09.md), Chinese).
 
 The tool table works the same way: tools added after the conversation started are appended at the end of the table; **removing a tool keeps its declaration**, and the reminder says `Tool "X" is no longer available in this session; calls to it are rejected.` — if the model still calls it, the execution layer rejects the call (`Tool "X" is not available in this session.`); adding it back only says `Tool "X" is available again.` and keeps the declaration that was sent first. The `tools` / `rules` sections of the system prompt are also frozen to the text already sent once the conversation has started.
 
@@ -537,7 +538,7 @@ While a tool runs for a long time (long tests, `task` sub-tasks, codemode script
 | Cancellation  | Cancelled on model switch, thinking level change, compaction, `/tree` and exit; restarts with the next real request                                                                                                                                                        |
 | Accounting    | A successful warming appends a `usage{kind:"cache_warm"}` entry (never in the context), counted in `/session` cost and RPC stats; events `cache_warm{scheduled｜sent｜stopped}`                                                                                            |
 
-Hosts can veto or force every warming through `api.cache.onWarmingDecision` ([host-api.md](host-api.md) "Cache warming"). Sub-sessions do not warm by default (`cache.warmSubagents: true` turns it on). By catalog prices, warming during long tool runs almost always pays off; idle warming only pays off for expensive models with long prefixes.
+Hosts can veto or force every warming through `api.cache.onWarmingDecision` ([host-api.md](../reference/host-api.md) "Cache warming"). Sub-sessions do not warm by default (`cache.warmSubagents: true` turns it on). By catalog prices, warming during long tool runs almost always pays off; idle warming only pays off for expensive models with long prefixes.
 
 ### Compaction summary continuation
 

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

@@ -1,11 +1,11 @@
 # Session stats, search, reuse, export and checkpoints
 
-English · [简体中文](../sessions.md)
+English · [简体中文](../../guides/sessions.md)
 
-> Translated from the Chinese [docs/sessions.md](../sessions.md) as of commit `e57b54f`. When the two differ, the Chinese
+> Translated from the Chinese [docs/guides/sessions.md](../../guides/sessions.md) as of commit `e57b54f`. When the two differ, the Chinese
 > version is authoritative. Sample command output below is illustrative; exact wording follows the interface language.
 
-These commands only read the session directory (`<data dir>/sessions`, changeable with `--session-dir`; the file format is in [session-format.md](../session-format.md), Chinese): no locks, no repair of half-written lines, no file changes, so sessions that are still running can be read too. Session files are read line by line in chunks rather than loaded whole: `ama sessions list` parses only each file's header, first entry, renames and first prompt and looks at just the type of every other line, so sessions of tens of MB do not make memory grow with file size; `--resume` likewise parses a session line by line. By default the scope is the sessions of the **current directory**; `--all` covers everything.
+These commands only read the session directory (`<data dir>/sessions`, changeable with `--session-dir`; the file format is in [session-format.md](../../reference/session-format.md), Chinese): no locks, no repair of half-written lines, no file changes, so sessions that are still running can be read too. Session files are read line by line in chunks rather than loaded whole: `ama sessions list` parses only each file's header, first entry, renames and first prompt and looks at just the type of every other line, so sessions of tens of MB do not make memory grow with file size; `--resume` likewise parses a session line by line. By default the scope is the sessions of the **current directory**; `--all` covers everything.
 
 ## Stats: `ama stats`
 
@@ -171,7 +171,7 @@ running sessions can be exported too.
   embedded. External agents only have skeletons anyway.
 - Previews are truncated per item (arguments 500, others 2000 characters) with a 4 M-character budget for the whole file; past
   the budget, earlier previews are dropped and the details say so.
-- `--json` (or `--format json`): JSON in the same shape as RPC `get_trace` ([rpc.md](rpc.md) "Traces"), with every turn, the
+- `--json` (or `--format json`): JSON in the same shape as RPC `get_trace` ([rpc.md](../reference/rpc.md) "Traces"), with every turn, the
   loaded child-session traces and `previews` for this session's nodes (none with `--no-content`).
 - Output: `--html <file>` (taken as the value only when the name ends in `.html` / `.htm`; otherwise use `--output`) or
   `--output <file>` writes a file (mode 0600), otherwise stdout. `--open` opens the written file in the system browser (a
@@ -182,7 +182,7 @@ running sessions can be exported too.
 
 ## Checkpoints and file backups
 
-Rolling back code (`/rewind`, design in [rewind-plan.md](../rewind-plan.md), Chinese) relies on checkpoints: at the start of each new turn, ama records the contents of the files changed by edit / write at that moment.
+Rolling back code (`/rewind`, design in [rewind-plan.md](../../history/rewind-plan.md), Chinese) relies on checkpoints: at the start of each new turn, ama records the contents of the files changed by edit / write at that moment.
 
 - **Storage**: backups are stored by content sha256 at `<data dir>/file-history/blobs/<first 2 chars>/<sha256>`, raw bytes, uncompressed; shared across sessions and checkpoints, so identical content is stored once. Session files only hold two kinds of `custom` entries, `ama.checkpoint` / `ama.checkpoint-track` (hashes only, never in the context). When the session directory is not in the default location (`--session-dir`, the host profile's `sessionDir`), the directory is registered in `file-history/roots.json` and scanned during cleanup as well.
 - **What is tracked**: edit / write (including codemode inner calls and task sub-sessions) back up a file before writing it the first time; afterwards each new turn re-snapshots the tracked files from the current disk contents, so bash or manual changes to those files also enter the next checkpoint. Other files created or changed by bash are not tracked.
@@ -211,7 +211,7 @@ Rolling back code (`/rewind`, design in [rewind-plan.md](../rewind-plan.md), Chi
 
 ## Rewind (within a session)
 
-`/rewind`, RPC `rewind` and SDK `session.rewind()` return to before a user message (design in [rewind-plan.md](../rewind-plan.md), Chinese):
+`/rewind`, RPC `rewind` and SDK `session.rewind()` return to before a user message (design in [rewind-plan.md](../../history/rewind-plan.md), Chinese):
 
 - Rewind points are the user messages on the active path that start new turns, oldest first; steers, queued messages and messages continued by the Stop hook belong to the current turn and are not listed separately. Rewinding while running reports `busy`.
 - Conversation rewind reuses the `/tree` leaf switch: the abandoned branch stays in the file and can be revisited from `/tree`; the model, thinking level and permission mode stay as they are and do not change with the rewind. The system prompt, tool table and messages before the target of the next request are byte-identical to before the rewind, so the prompt cache hits as usual.

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.