@armadra/agent 0.8.0 → 0.8.1

package/dist/tools/types.d.ts

@@ -12,7 +12,7 @@
  * - `defineTool()` 是恒等函数，只为推断 `I`；放在契约文件里供 SDK 再导出。
  * - `ToolRegistryApi` 是 Runtime 需要的最小接口，B3 的 `ToolRegistry` 实现它。
  * - （W3-C0）`SubagentResult.cache` 可选：子会话的命中率与重计费 token。
- * - （W5-C0）第五波（docs/wave5-plan.md §7.3–§7.6、§8.2 C4、§8.3 H1）：`annotations.pollable /
+ * - （W5-C0）第五波（docs/history/wave5-plan.md §7.3–§7.6、§8.2 C4、§8.3 H1）：`annotations.pollable /
  *   keepInContext`；`SubagentRequest` 加 `agent / background / taskId / isolation / budgetUsd`；
  *   `SubagentResult` 加 `taskId / status / outputFile / sessionRef`（契约要求向后兼容，全部可选）；
  *   统一入口 `SubagentRunner / RunnerHandle / SubagentEvent`（ama 子会话、外部 CLI、宿主 runner）；
@@ -158,7 +158,7 @@ export type SubagentEvent = {
     turn: number;
 }
 /**
- * [W6-C0] 外部 Agent 一个回合结束时的骨架（docs/wave6-plan.md §2.2）：任务注册表写成父会话的
+ * [W6-C0] 外部 Agent 一个回合结束时的骨架（docs/history/wave6-plan.md §2.2）：任务注册表写成父会话的
  * `ama.trace{kind:"external_turn"}`。只有种类、状态、时间与计数——不含工具标题、命令行、路径。
  */
  | {
@@ -281,7 +281,7 @@ export interface ToolContext {
         /** 活动分支上最近一条该类型 custom 条目的 data。 */
         lastCustom(customType: string): unknown;
     };
-    /** 检查点（docs/rewind-plan.md §2）：edit / write 写文件前后调用；未启用时为 undefined。 */
+    /** 检查点（docs/history/rewind-plan.md §2）：edit / write 写文件前后调用；未启用时为 undefined。 */
     readonly checkpoint?: CheckpointHooks;
     /** 仅 depth 0 且 task 可用时存在。 */
     readonly spawnSubagent?: (request: SubagentRequest) => Promise<SubagentResult>;

package/dist/tools/types.js

@@ -12,7 +12,7 @@
  * - `defineTool()` 是恒等函数，只为推断 `I`；放在契约文件里供 SDK 再导出。
  * - `ToolRegistryApi` 是 Runtime 需要的最小接口，B3 的 `ToolRegistry` 实现它。
  * - （W3-C0）`SubagentResult.cache` 可选：子会话的命中率与重计费 token。
- * - （W5-C0）第五波（docs/wave5-plan.md §7.3–§7.6、§8.2 C4、§8.3 H1）：`annotations.pollable /
+ * - （W5-C0）第五波（docs/history/wave5-plan.md §7.3–§7.6、§8.2 C4、§8.3 H1）：`annotations.pollable /
  *   keepInContext`；`SubagentRequest` 加 `agent / background / taskId / isolation / budgetUsd`；
  *   `SubagentResult` 加 `taskId / status / outputFile / sessionRef`（契约要求向后兼容，全部可选）；
  *   统一入口 `SubagentRunner / RunnerHandle / SubagentEvent`（ama 子会话、外部 CLI、宿主 runner）；

package/dist/trace/build.d.ts

@@ -1,5 +1,5 @@
 /**
- * 轨迹构建器（docs/wave6-plan.md §2.3、D6）。[W6-T1]
+ * 轨迹构建器（docs/history/wave6-plan.md §2.3、D6）。[W6-T1]
  *
  * `buildTrace(input, opts)` 把会话条目重建成 `Trace`（Turn → Step → Tool → Subcall / Subagent）：
  * TUI `/trace`、`ama sessions trace`、RPC `get_trace` 三方共用同一棵树。

package/dist/trace/build.js

@@ -1,5 +1,5 @@
 /**
- * 轨迹构建器（docs/wave6-plan.md §2.3、D6）。[W6-T1]
+ * 轨迹构建器（docs/history/wave6-plan.md §2.3、D6）。[W6-T1]
  *
  * `buildTrace(input, opts)` 把会话条目重建成 `Trace`（Turn → Step → Tool → Subcall / Subagent）：
  * TUI `/trace`、`ama sessions trace`、RPC `get_trace` 三方共用同一棵树。

package/dist/trace/detail.d.ts

@@ -1,5 +1,5 @@
 /**
- * 轨迹节点的正文预览与详情卡片（docs/wave6-plan.md §2.4：Enter 详情——概要 / 用量与缓存 / 参数与结果预览）。
+ * 轨迹节点的正文预览与详情卡片（docs/history/wave6-plan.md §2.4：Enter 详情——概要 / 用量与缓存 / 参数与结果预览）。
  * [W6-T1]
  *
  * 轨迹树不含正文；这里按节点的 `entryIds` 回会话条目取：回合 → 用户提示，请求 → 助手文字，工具 → 参数

package/dist/trace/detail.js

@@ -1,5 +1,5 @@
 /**
- * 轨迹节点的正文预览与详情卡片（docs/wave6-plan.md §2.4：Enter 详情——概要 / 用量与缓存 / 参数与结果预览）。
+ * 轨迹节点的正文预览与详情卡片（docs/history/wave6-plan.md §2.4：Enter 详情——概要 / 用量与缓存 / 参数与结果预览）。
  * [W6-T1]
  *
  * 轨迹树不含正文；这里按节点的 `entryIds` 回会话条目取：回合 → 用户提示，请求 → 助手文字，工具 → 参数

package/dist/trace/flatten.d.ts

@@ -1,5 +1,5 @@
 /**
- * 轨迹树扁平化（docs/wave6-plan.md §2.4）。[W6-T1]
+ * 轨迹树扁平化（docs/history/wave6-plan.md §2.4）。[W6-T1]
  *
  * 把 `Trace` 按展开状态摊成行数组（列表模型），TUI 只渲染可见窗口、line 模式整表输出。
  * - 行 key 是从根开始的路径（`t:<turnId>/s:<stepId>/x:<toolCallId>/a:<taskId>/…`），刷新后仍稳定，

package/dist/trace/flatten.js

@@ -1,5 +1,5 @@
 /**
- * 轨迹树扁平化（docs/wave6-plan.md §2.4）。[W6-T1]
+ * 轨迹树扁平化（docs/history/wave6-plan.md §2.4）。[W6-T1]
  *
  * 把 `Trace` 按展开状态摊成行数组（列表模型），TUI 只渲染可见窗口、line 模式整表输出。
  * - 行 key 是从根开始的路径（`t:<turnId>/s:<stepId>/x:<toolCallId>/a:<taskId>/…`），刷新后仍稳定，

package/dist/trace/format.d.ts

@@ -1,5 +1,5 @@
 /**
- * 轨迹行的文本格式（docs/wave6-plan.md §2.4）。[W6-T1]
+ * 轨迹行的文本格式（docs/history/wave6-plan.md §2.4）。[W6-T1]
  *
  * 一行：`光标 缩进 折叠符 状态 标签   耗时  ▕████▒▒▒░░▏  ↑in ↓out  缓存%`
  * - 条形是所在回合的相对时间轴：`▒` = TTFT、`█` = 解码、`░` = 工具、`│` = 进行中节点的起点（不编造时长）；

package/dist/trace/format.js

@@ -1,5 +1,5 @@
 /**
- * 轨迹行的文本格式（docs/wave6-plan.md §2.4）。[W6-T1]
+ * 轨迹行的文本格式（docs/history/wave6-plan.md §2.4）。[W6-T1]
  *
  * 一行：`光标 缩进 折叠符 状态 标签   耗时  ▕████▒▒▒░░▏  ↑in ↓out  缓存%`
  * - 条形是所在回合的相对时间轴：`▒` = TTFT、`█` = 解码、`░` = 工具、`│` = 进行中节点的起点（不编造时长）；

package/dist/trace/html-template.d.ts

@@ -1,5 +1,5 @@
 /**
- * 轨迹 HTML 的页面骨架、样式与脚本（docs/wave6-plan.md §2.5）。[W6-T2]
+ * 轨迹 HTML 的页面骨架、样式与脚本（docs/history/wave6-plan.md §2.5）。[W6-T2]
  *
  * 全部静态：页面只插入三样东西——`lang`、转义过的 `<title>`、已做脚本安全转义的 JSON（`html.ts`）。
  * 脚本只用 `textContent` / `createElement` 写 DOM，不用 `innerHTML`；没有任何外部资源（CSP 见 `CSP`）。

package/dist/trace/html-template.js

@@ -1,5 +1,5 @@
 /**
- * 轨迹 HTML 的页面骨架、样式与脚本（docs/wave6-plan.md §2.5）。[W6-T2]
+ * 轨迹 HTML 的页面骨架、样式与脚本（docs/history/wave6-plan.md §2.5）。[W6-T2]
  *
  * 全部静态：页面只插入三样东西——`lang`、转义过的 `<title>`、已做脚本安全转义的 JSON（`html.ts`）。
  * 脚本只用 `textContent` / `createElement` 写 DOM，不用 `innerHTML`；没有任何外部资源（CSP 见 `CSP`）。

package/dist/trace/html.d.ts

@@ -1,5 +1,5 @@
 /**
- * 轨迹 HTML 导出：`ama sessions trace --html`（docs/wave6-plan.md §2.5、D7）。[W6-T2]
+ * 轨迹 HTML 导出：`ama sessions trace --html`（docs/history/wave6-plan.md §2.5、D7）。[W6-T2]
  *
  * 产物是**单文件、零依赖**的页面：样式与脚本内联（`html-template.ts`），数据放
  * `<script type="application/json">`，`<meta>` CSP 禁止一切外联。页面在浏览器里只用 `textContent` 写字，

package/dist/trace/html.js

@@ -1,5 +1,5 @@
 /**
- * 轨迹 HTML 导出：`ama sessions trace --html`（docs/wave6-plan.md §2.5、D7）。[W6-T2]
+ * 轨迹 HTML 导出：`ama sessions trace --html`（docs/history/wave6-plan.md §2.5、D7）。[W6-T2]
  *
  * 产物是**单文件、零依赖**的页面：样式与脚本内联（`html-template.ts`），数据放
  * `<script type="application/json">`，`<meta>` CSP 禁止一切外联。页面在浏览器里只用 `textContent` 写字，

package/dist/trace/query-session.d.ts

@@ -1,5 +1,5 @@
 /**
- * 运行中会话的轨迹查询：RPC `get_trace` 与 SDK `session.trace()`（docs/wave6-plan.md §2.6、D29）。[W6-T2]
+ * 运行中会话的轨迹查询：RPC `get_trace` 与 SDK `session.trace()`（docs/history/wave6-plan.md §2.6、D29）。[W6-T2]
  *
  * 构建器输入取自会话（`traceInputOf`）；运行中时叠一层 `{ running: true }`（没有结果的工具算 running 而不是
  * interrupted，不编造时长）；子会话读取按会话缓存（mtime + 大小没变就不重读）。

package/dist/trace/query-session.js

@@ -1,5 +1,5 @@
 /**
- * 运行中会话的轨迹查询：RPC `get_trace` 与 SDK `session.trace()`（docs/wave6-plan.md §2.6、D29）。[W6-T2]
+ * 运行中会话的轨迹查询：RPC `get_trace` 与 SDK `session.trace()`（docs/history/wave6-plan.md §2.6、D29）。[W6-T2]
  *
  * 构建器输入取自会话（`traceInputOf`）；运行中时叠一层 `{ running: true }`（没有结果的工具算 running 而不是
  * interrupted，不编造时长）；子会话读取按会话缓存（mtime + 大小没变就不重读）。

package/dist/trace/query.d.ts

@@ -1,5 +1,5 @@
 /**
- * 轨迹查询：RPC `get_trace`、SDK `session.trace()`、`ama sessions trace --json` 共用（docs/wave6-plan.md §2.6）。
+ * 轨迹查询：RPC `get_trace`、SDK `session.trace()`、`ama sessions trace --json` 共用（docs/history/wave6-plan.md §2.6）。
  * [W6-T2]
  *
  * - **窗口**：在 `Trace.turns` 上切。缺省尾部 `turnLimit`（50，上限 500）个回合；`before`（回合 id）向前翻页；

package/dist/trace/query.js

@@ -1,5 +1,5 @@
 /**
- * 轨迹查询：RPC `get_trace`、SDK `session.trace()`、`ama sessions trace --json` 共用（docs/wave6-plan.md §2.6）。
+ * 轨迹查询：RPC `get_trace`、SDK `session.trace()`、`ama sessions trace --json` 共用（docs/history/wave6-plan.md §2.6）。
  * [W6-T2]
  *
  * - **窗口**：在 `Trace.turns` 上切。缺省尾部 `turnLimit`（50，上限 500）个回合；`before`（回合 id）向前翻页；

package/dist/trace/types.d.ts

@@ -1,5 +1,5 @@
 /**
- * 轨迹（docs/wave6-plan.md §2.1、§2.2、D5、D6）。[W6-C0] 纯类型，经 `@armadra/agent` 导出。
+ * 轨迹（docs/history/wave6-plan.md §2.1、§2.2、D5、D6）。[W6-C0] 纯类型，经 `@armadra/agent` 导出。
  *
  * 两部分：
  * - **持久化**：`custom{customType:"ama.trace"}` 条目的 `data`（`TraceEntryData`），由

package/dist/trace/types.js

@@ -1,5 +1,5 @@
 /**
- * 轨迹（docs/wave6-plan.md §2.1、§2.2、D5、D6）。[W6-C0] 纯类型，经 `@armadra/agent` 导出。
+ * 轨迹（docs/history/wave6-plan.md §2.1、§2.2、D5、D6）。[W6-C0] 纯类型，经 `@armadra/agent` 导出。
  *
  * 两部分：
  * - **持久化**：`custom{customType:"ama.trace"}` 条目的 `data`（`TraceEntryData`），由

package/dist/tui/components/settings-list.d.ts

@@ -1,5 +1,5 @@
 /**
- * Grouped settings list (docs/wave6-plan.md §6.3). [W6-S]
+ * Grouped settings list (docs/history/wave6-plan.md §6.3). [W6-S]
  *
  * Rows `› label  value  tag  note` under muted group headers; the selected row uses the prompt glyph,
  * accent + bold and the `selection` background (same look as ChoiceDialog). A query filters rows by id,

package/dist/tui/components/settings-list.js

@@ -1,5 +1,5 @@
 /**
- * Grouped settings list (docs/wave6-plan.md §6.3). [W6-S]
+ * Grouped settings list (docs/history/wave6-plan.md §6.3). [W6-S]
  *
  * Rows `› label  value  tag  note` under muted group headers; the selected row uses the prompt glyph,
  * accent + bold and the `selection` background (same look as ChoiceDialog). A query filters rows by id,

package/docs/README.md

@@ -0,0 +1,85 @@
+# 文档索引
+
+[English](en/README.md) · 简体中文
+
+本文件是 `docs/` 的入口，新增文档登记在这里。仓库内的相对链接与源码注释里的 `docs/…md` 路径由
+`pnpm check:docs`（`scripts/check-doc-links.mjs`）校验。
+
+| 目录          | 内容                                                          |
+| ------------- | ------------------------------------------------------------- |
+| `guides/`     | 使用说明与现行行为，与代码同步维护                            |
+| `reference/`  | 协议与文件格式，形状改动必须同步（见 `AGENTS.md`「协议面」）  |
+| `design/`     | 目标设计与视觉规范；首段写明状态，现状以代码与 `guides/` 为准 |
+| `history/`    | 已完成的实施计划与审计，只用于追溯，不作为实施要求            |
+| `research/`   | 调研报告，只用于追溯                                          |
+| `benchmarks/` | 实测记录与原始数据                                            |
+| `en/`         | 英文译本，按同样的分层放；中英不一致时以中文版为准            |
+| `assets/`     | README 用的字标等图片                                         |
+
+## guides/ 使用与现状
+
+| 文档                                      | 内容                                                                        |
+| ----------------------------------------- | --------------------------------------------------------------------------- |
+| [终端界面](guides/tui.md)                 | 布局、状态栏、按键、命令、回滚、审批、Agent 栏、轨迹、`/config`；组件库 API |
+| [供应商与模型](guides/providers.md)       | 内置供应商、渠道、API Key、ChatGPT 登录、中转、models.dev、图像、缓存       |
+| [权限](guides/permissions.md)             | 六种模式、判定顺序、`auto` 的三层判定                                       |
+| [Plan 模式](guides/plan.md)               | 只读调研、计划格式、审批入口与持久化                                        |
+| [会话](guides/sessions.md)                | 统计、检索、`--from` 复用、导出、轨迹、检查点                               |
+| [子 Agent 与外部 Agent](guides/agents.md) | `task` / `task_ctl`、fork、worktree 隔离、外部 Agent 驱动与能力矩阵         |
+| [记忆](guides/memory.md)                  | 跨会话笔记，缺省关闭                                                        |
+| [命令式 Hook](guides/hooks.md)            | `hooks.json` 的事件、退出码与 stdout JSON                                   |
+| [codemode](guides/codemode.md)            | 模型写脚本批量调用工具，子进程与权限                                        |
+| [操作系统级沙箱](guides/sandbox.md)       | macOS `sandbox-exec` 与 Linux bubblewrap，codemode 与 bash 接入             |
+| [界面语言](guides/i18n.md)                | 中英双语的选择规则与开发约定                                                |
+
+## reference/ 协议与格式
+
+| 文档                                        | 内容                                                     |
+| ------------------------------------------- | -------------------------------------------------------- |
+| [RPC 协议](reference/rpc.md)                | `ama --mode rpc` 的 stdio JSONL 命令、响应与事件         |
+| [ACP](reference/acp.md)                     | `ama --mode acp` 服务端、登录方法、偏差，以及 ACP 客户端 |
+| [宿主适配器 API](reference/host-api.md)     | `@armadra/agent/host`：注册工具、审批、注入消息、状态    |
+| [会话文件格式](reference/session-format.md) | JSONL 条目树、头、条目类型与版本                         |
+
+## design/ 目标设计
+
+| 文档                                     | 状态与内容                                                                 |
+| ---------------------------------------- | -------------------------------------------------------------------------- |
+| [总体设计](design/design.md)             | 架构、工程约定、缓存保证与决定表；硬约束仍以此为准，细节现状见 `guides/`   |
+| [终端界面视觉规范](design/tui-design.md) | 主题、逐屏样稿与交互细节；已按此实现，作为界面改动的规范                   |
+| [检索与网络搜索](design/search-plan.md)  | 只实施了本地检索增强；`web_fetch`、`web_search` 与引用呈现保留为将来的设计 |
+| [本地扩展](design/extensions.md)         | 设计草案，尚未实现                                                         |
+
+## history/ 已完成的计划与审计
+
+| 文档                                                       | 内容                                                         |
+| ---------------------------------------------------------- | ------------------------------------------------------------ |
+| [第二、三波实施设计](history/implementation-plan.md)       | 组装根、RPC / SDK、交互模式、codemode 各批次                 |
+| [第三波计划](history/wave3-plan.md)                        | 缓存设计与验收、其余批次编排                                 |
+| [第五波计划](history/wave5-plan.md)                        | 状态栏、模型元数据、渠道、外部 Agent、Plan、子 Agent、压缩   |
+| [第六波计划](history/wave6-plan.md)                        | Agent 栏、轨迹、记忆、ChatGPT 登录、双语、`/config`          |
+| [检查点与回滚](history/rewind-plan.md)                     | 检查点、回滚与影子 git                                       |
+| [ACP 补全](history/acp-plan.md)                            | 对照 ACP v1 schema 的补全                                    |
+| [Agent 切换与并行交流](history/agents-concurrency-plan.md) | Agent 栏进入方式、后台审批停靠                               |
+| [内存占用优化](history/memory-plan.md)                     | read 流式、ACP 释放、图片驻留                                |
+| [模型调用效率](history/model-efficiency-plan.md)           | 缓存、用量、重试与元数据                                     |
+| [未关闭 Issue 设计与分批](history/open-issues-plan.md)     | #149–#156、#183：fork 缺省、子会话防串台、取样、上限持久化等 |
+| [内存优化遗留项](history/memory-residue-plan.md)           | #165–#173：常驻会话、通知回合、图片释放、读窗口等            |
+| [缺口与默认值审计](history/gap-audit-2026-10.md)           | 2026-10-02 的只读审计                                        |
+
+## research/ 与 benchmarks/
+
+- [调研报告](research/README.md)：第五波 R1–R5、第六波 R6–R10、ACP 差距审计、模型调用效率与内存占用审计。
+- 实测记录：
+  - [外部 Agent 驱动实测](benchmarks/external-agents-2026-10.md)
+  - [模型调用效率实测](benchmarks/efficiency-2026-10.md)
+  - [内存占用实测](benchmarks/memory-2026-10.md)
+  - [缓存验收实验](benchmarks/cache-2026-10-02.md)、[自动压缩 E6](benchmarks/cache-e6-2026-10-02.md)、[对话中途的 system 消息](benchmarks/cache-midconvo-2026-10-09.md)
+  - [三预设基准](benchmarks/presets-2026-10-02.md)、[todo 进 default](benchmarks/presets-todo-2026-10-02.md)、[多步长任务复测](benchmarks/presets-todo-2026-10-03.md)
+
+## en/ 英文译本
+
+[终端界面](en/guides/tui.md)、[供应商与模型](en/guides/providers.md)、[权限](en/guides/permissions.md)、
+[会话](en/guides/sessions.md)、[RPC 协议](en/reference/rpc.md)、[ACP](en/reference/acp.md)、
+[宿主适配器 API](en/reference/host-api.md)。译本头部记着翻译时的中文版提交，`pnpm release:check` 在中文版
+之后改动较多时提示同步。

package/docs/assets/ama-wordmark-dark.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="#5fafff">
+    <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="#87afff">
+    <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="#af87ff">
+    <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/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
 
@@ -449,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.
 
@@ -538,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.