@gavin-hu/my-pi-agent 0.18.0 → 0.20.0

package/README.md

@@ -15,7 +15,7 @@ This page is the catalog and the setup instructions. For how to use a feature
 the keys, the commands, and what you should see — start with the
 [user guide](./docs/user-guide/).
 
-![A terminal window running the Pi TUI with the bytefly header, hint row, context and loaded extensions, a turn separator, and the status bar](assets/chrome.png)
+![A terminal window running the Pi TUI: the bytefly header naming Pi and bytefly's versions, three key-hint rows, a nameplated message with its answer and an edit diff behind the rail, a notice that two background jobs finished, naming the test run that passed and the build that failed, the turn rule, the goal and todo rails, the input editor with a half-typed request between its two rules, and the two-line footer — the plan chip and the branch above, the context gauge, the priced cost against its $5 budget, and the model below](assets/screens/chrome.png)
 
 ## Contents
 
@@ -39,8 +39,8 @@ want the agent to *think first and work safely*:
   log until it matters — then run several sessions on one repository through a
   shared bus, each owning its slice, all while you keep the thread.
 - **Never wreck the checkout.** Isolation is one command: the task moves onto its
-  own branch in a `git worktree`, and every prompt is snapshotted so a bad turn
-  is one `/rewind` away.
+  own branch in a `git worktree`, and each prompt's first change is snapshotted,
+  so a bad turn is one `/rewind` away.
 - **Remember across sessions.** Durable notes live in plain markdown that you
   can read, edit, and version.
 - **Reach the web and your files.** Search, fetch, browse, open, and read
@@ -64,23 +64,29 @@ pi install npm:@gavin-hu/my-pi-agent
 pinned release, a project-local install, and a trial that writes nothing — plus
 the fit decision, the first workflows, and how to remove the pack.
 
-`git` on `PATH` is needed by [`worktree`](./extensions/worktree/) and
-[`rewind`](./extensions/rewind/); everything else degrades or disables cleanly,
+`git` on `PATH` is needed by [`worktree`](./docs/extensions/worktree.md) and
+[`rewind`](./docs/extensions/rewind.md); everything else degrades or disables cleanly,
 and `/bytefly doctor` names what is missing, including optional runtime pieces.
 Windows, macOS, and Linux all work, and the full check suite runs on each in CI.
 
 Then, from inside Pi:
 
-- `/bytefly [extension] [refresh]` opens the control center on Extensions, lists
-  every loaded extension with its runtime health, enables or disables one, and
-  clears a project override with `x`.
-- `/bytefly settings` opens the control center's Settings section: one flat list
-  of the thirteen preferences a session changes, each with its value beside the
-  label, `Space`/`Enter` to change one and `Tab` for Global/Project scope. Every
-  other key is a `bytefly.json` edit, listed in the configuration reference.
+- `/bytefly [extension] [refresh]` opens the control center on Extensions: one
+  frame for all three sections, its header rule carrying the attention at the
+  right (or `all clear`), a tab row with each section's count and the write scope.
+  It lists every loaded extension by name, with a checkbox and at most one
+  verdict word, enables or disables one, and clears a project override with `x`;
+  `/` filters the rows, `!` keeps only what needs attention, and `?` shows every
+  key.
+- `/bytefly settings` opens the control center's Settings section: the twelve
+  preferences a session changes, grouped under Startup, Notifications, Session,
+  and Price with each value in an aligned column, `Space`/`Enter` to change one
+  and `s` for Global/Project scope. Every other key is a `bytefly.json` edit,
+  listed in the configuration reference.
 - `/bytefly skills` opens the control center's Skills section: one row per Pi
-  skill with its enable checkbox, its declared description underneath, and
-  `Space` to switch it on or off for the active scope.
+  skill with its enable checkbox and at most one verdict word, what its `SKILL.md`
+  declares in the block beside it, and `Space` to switch it on or off for the
+  active scope.
 - `/bytefly doctor [extension] [refresh]` prints the doctor report —
   `run_doctor`'s text — and checks that each enabled extension has what it needs
   at runtime.
@@ -95,53 +101,58 @@ asks Pi's package manager which configured packages are behind, suppresses Pi's
 own startup update blocks, and posts one themed notice naming
 `pi update --extensions`, plus one for a newer Pi that names `pi update` and the
 changelog; a new version also marks the header — this package's, and Pi's own.
-Nothing about the session is sent — Pi's own release request is only re-rendered —
-and `PI_OFFLINE` skips the check;
+Nothing about the session is sent: Pi's own release request is re-rendered, and
+this package's newest version comes from one fixed `GET` of npm's `latest`
+document. `PI_OFFLINE` skips the check;
 [`docs/security.md`](./docs/security.md) covers the trust boundaries.
 
 ## What you get
 
-19 extensions, 5 packaged skills, and 2 themes, grouped by what you are trying
-to do. Each extension's own `README.md` has the full tool and command surface.
+21 extensions, 4 packaged skills, and 2 themes, grouped by the promises the
+[roadmap](./ROADMAP.md) tracks; the [guide](./docs/user-guide/) covers the same
+ground chapter by chapter. Each extension's own page in `docs/extensions/` has
+the full tool and command surface, opening with its capabilities.
 
 ### Plan and delegate
 
 | Extension | Tools and commands | What it does |
 |---|---|---|
-| [`plan`](./extensions/plan/) | `enter_plan_mode`, `write_plan`, `exit_plan_mode`, `cancel_plan_mode`, `set_plan_steps`, `/plan`, `--plan` | Read-only planning: the model investigates, saves a plan under `~/.pi/agent/plans/<repo-key>` — one store per repository, shared by its worktrees — and you approve it before anything is written; with `plan.split` on, the approval can also split it into slices that separate sessions join by name. Review in the TUI, or open it in a browser to leave inline comments: the page follows the plan file live, and you can hand one reviewer link per teammate so each comments under their own name. The `init` skill uses the same review to create or update a project's `AGENTS.md`. |
-| [`check`](./extensions/check/) | `run_check`, `/check` | Detect the project's test, lint, or typecheck command (or take `check.command`), run it in a supervised process, and turn failures into a navigable `file:line` list. |
-| [`subagent`](./extensions/subagent/) | `subagent`, `/agents` | Delegate a task to a specialist agent (`explorer`, `planner`, `reviewer`, `worker`, `researcher`, `tester`, `debugger`, `documenter`) in its own Pi process — single, parallel, chained, or in the background, with a footer chip while it runs and a finish notice. |
-| [`todo`](./extensions/todo/) | `todo`, `/todos` | A persistent task list (`pending` / `in_progress` / `completed`) with a one-line widget. |
-| [`goal`](./extensions/goal/) | `goal`, `/goal` | A persistent session objective, kept in a widget and restated before each turn. |
-| [`question`](./extensions/question/) | `ask_user_question` | Ask you one or more structured questions (labelled options plus free-form "Other") and wait. |
-| [`job`](./extensions/job/) | `job`, `/jobs` | Run long-lived shell commands in the background; inspect logs, wait, or kill them. |
-| [`watch`](./extensions/watch/) | `watch`, `/watch` | Tail a file or command output, match lines against patterns, and alert you or hand matching lines to the agent. |
-| [`session-bus`](./extensions/session-bus/) | `session`, `/sessions` (screen) | Coordinate parallel Pi sessions on one repository: discover peers, exchange short messages/events, consume an inbox, join a slice of an approved split or claim paths before editing, with `/sessions` as a live board of peers, unread mail, and claims. Local, pull-based by default, with an opt-in inbox watch that raises this session's turn once it is idle; it never spawns an agent. |
-| [`context`](./extensions/context/) | `/context` | Show where the context window goes — system prompt, tool definitions, conversation by role, injected notes — and compact from the report with the before and after numbers. |
+| [`plan`](./docs/extensions/plan.md) | `enter_plan_mode`, `write_plan`, `exit_plan_mode`, `cancel_plan_mode`, `set_plan_steps`, `/plan`, `--plan` | Read-only planning: the model investigates, saves a plan under `~/.pi/agent/plans/<repo-key>` — one store per repository, shared by its worktrees — and you approve it before anything is written. Review in the TUI, or open it in a browser to leave inline comments: the page follows the plan file live, and you can hand one reviewer link per teammate so each comments under their own name. The `init` skill uses the same review to create or update a project's `AGENTS.md`. |
+| [`check`](./docs/extensions/check.md) | `run_check`, `/check` | Detect the project's test, lint, or typecheck command (or take `check.command`), run it in a supervised process, and turn failures into a navigable `file:line` list. |
+| [`subagent`](./docs/extensions/subagent.md) | `subagent`, `/agents` | Delegate a task to a specialist agent (`explorer`, `planner`, `reviewer`, `worker`, `researcher`, `tester`, `debugger`, `documenter`) in its own Pi process — single, parallel, chained, or in the background, with a footer chip while it runs and a finish notice. |
+| [`todo`](./docs/extensions/todo.md) | `todo`, `/todos` | A persistent task list (`pending` / `in_progress` / `completed`) with a one-line widget. |
+| [`goal`](./docs/extensions/goal.md) | `goal`, `/goal` | A persistent session objective, kept in a widget and restated before each turn. |
+| [`question`](./docs/extensions/question.md) | `ask_user_question` | Ask you one or more structured questions (labelled options plus free-form "Other") and wait. |
+| [`job`](./docs/extensions/job.md) | `job`, `/jobs` | Run long-lived shell commands in the background; inspect logs, wait, or kill them. |
+| [`watch`](./docs/extensions/watch.md) | `watch`, `/watch` | Tail a file or command output, match lines against patterns, and alert you or hand matching lines to the agent. |
+| [`session-bus`](./docs/extensions/session-bus.md) | `session`, `/sessions` (screen) | Coordinate parallel Pi sessions on one repository: discover peers, exchange short messages/events, consume an inbox, or claim paths before editing, with `/sessions` as a live board of peers, unread mail, and claims. Local, pull-based by default, with an opt-in inbox watch that raises this session's turn once it is idle; it never spawns an agent. |
+| [`board`](./docs/extensions/board.md) | `board`, `/board` | One shared feature board per repository: a card per feature, which any session claims, moves, edits, notes, finishes, and archives — a finished card leaves the board for an `archive/` pile with its notes and landed commit still readable, so a long history stops costing every read — and one loopback page that shows the same cards live in a **Board** and a **Team** tab. The page is a read view — the tools are the only writers — served as the seat `team-lead`, so a second session opens the same page instead of starting a rival one, and handing a card to a teammate is `team`'s job because only it can message them. A card can carry a priority and name the cards it waits on. Steps stay in the owner's plan and `todo`; a card is the feature, its owner, and the history that explains it. `board.port` in `bytefly.json` pins the page's port, so a bookmarked URL survives a restart. |
+| [`team`](./docs/extensions/team.md) | `team`, `/team` | The lead's round over the same board. `/team join <label>` puts a session on the team, and `/board` does it for the lead as `team-lead`; then `assign` hands a feature to a running session, `offer` hands one to whoever is free — a broadcast that writes nothing, claimed by the first taker — and `reclaim` takes a card back to To do. A result says who will be woken for it and who will read it at their next turn, `/team` prints the round in the terminal without a browser, and nothing is spawned. |
+| [`context`](./docs/extensions/context.md) | `/context` | Show where the context window goes — system prompt, tool definitions, conversation by role, injected notes — and compact from the report with the before and after numbers. |
 
 ### Keep your work safe
 
 | Extension | Tools and commands | What it does |
 |---|---|---|
-| [`worktree`](./extensions/worktree/) | `enter_worktree`, `exit_worktree`, `prune_worktrees`, `list_worktrees`, `/worktree` (screen), `/worktree enter|exit|prune`, `--worktree` | Work inside an isolated `git worktree` on its own branch; the built-in read/write/edit/bash tools follow, and cleanup refuses to throw work away. |
-| [`rewind`](./extensions/rewind/) | `/rewind`, `/review`, `↺ N` status chip | Snapshot the repo on every prompt under `refs/pi/rewind`, restore code, conversation, or both, and review the latest turn's changes before reverting a file. |
-| [`memory`](./extensions/memory/) | `memory`, `/memory` | Durable cross-session notes as human-editable markdown, injected into each run and managed through the `/memory` picker. |
+| [`worktree`](./docs/extensions/worktree.md) | `enter_worktree`, `exit_worktree`, `prune_worktrees`, `list_worktrees`, `/worktree` (screen), `/worktree enter\|exit\|prune`, `--worktree` | Work inside an isolated `git worktree` on its own branch; the built-in read/write/edit/bash tools follow, and cleanup refuses to throw work away. |
+| [`rewind`](./docs/extensions/rewind.md) | `/rewind`, `/review`, `↺ N` status chip | Snapshot the repo before each prompt's first change, under `refs/pi/rewind`, restore code, conversation, or both, and review the latest turn's changes before reverting a file. |
+| [`memory`](./docs/extensions/memory.md) | `memory`, `/memory` | Durable cross-session notes as human-editable markdown, injected into each run and managed through the `/memory` picker. |
 
 ### Reach the world
 
 | Extension | Tools and commands | What it does |
 |---|---|---|
-| [`web-access`](./extensions/web-access/) | `web_search`, `web_fetch` | Search the web (keyless DuckDuckGo by default, optional SearXNG or Brave) and fetch a page as readable text, with paging, `find`, per-hop SSRF checks, and optional PDF support. |
-| [`file-browse`](./extensions/file-browse/) | `/browse` | Start a loopback, read-only file browser rooted at the working directory, with Markdown preview, a fuzzy quick-open palette, a `path:12-30` reference copied from a selection, live status for a page left open, and a reload hint when the folder it lists changes. |
-| [`file-read`](./extensions/file-read/) | `read_doc` | Extract text from a local PDF, DOCX, DOC, ODT, RTF, or XLSX in process, paged. |
-| [`file-open`](./extensions/file-open/) | `/open`, `open_path` | Open or reveal a file or directory in the OS-native application. |
-| [`wechat`](./extensions/wechat/) | `/wechat`, `send_wechat` | Bridge a WeChat chat to the live session over the Weixin iLink bot API; inbound text, images, and files become turns. |
+| [`web-access`](./docs/extensions/web-access.md) | `web_search`, `web_fetch` | Search the web (keyless DuckDuckGo by default, optional SearXNG or Brave) and fetch a page as readable text, with paging, `find`, per-hop SSRF checks, a JSON/CSV/XML body rendered as a table or a tree, and optional PDF support. |
+| [`file-browse`](./docs/extensions/file-browse.md) | `/browse` | Start a loopback, read-only file browser rooted at the working directory, with Markdown preview, a fuzzy quick-open palette, a `path:12-30` reference copied from a selection, live status for a page left open, and a reload hint when the folder it lists changes. |
+| [`file-read`](./docs/extensions/file-read.md) | `read_doc` | Extract text from a local PDF, DOCX, DOC, ODT, RTF, or XLSX in process, paged. |
+| [`file-open`](./docs/extensions/file-open.md) | `/open`, `open_path` | Open or reveal a file or directory in the OS-native application. |
+| [`wechat`](./docs/extensions/wechat.md) | `/wechat`, `send_wechat` | Bridge a WeChat chat to the live session over the Weixin iLink bot API; inbound text, images, and files become turns. |
 
 ### Chrome and upkeep
 
 | Extension | Tools and commands | What it does |
 |---|---|---|
-| [`bytefly`](./extensions/bytefly/) | `/bytefly` (with the `doctor`, `settings`, `skills`, and `update` subcommands), `run_doctor` | The visible layer: a themed header with a width-adaptive footer, a live run line on Pi's working row (tool, tool count, and elapsed time), and a transcript where every tool block leads with its call line and rails its result under it. `/bytefly` switches extensions and skills and holds the curated settings; opt-in `notify` raises OS notifications when a run, a job, or a question needs you, and Pi's own startup update blocks become themed notices and header markers. `bytefly.json` is the config document every extension reads. |
+| [`bytefly`](./docs/extensions/bytefly.md) | `/bytefly` (with the `doctor`, `settings`, `skills`, `update`, and `upgrade` subcommands), `run_doctor` | The visible layer: a themed header with a width-adaptive footer, a live run line on Pi's working row (tool, tool count, and elapsed time), and a transcript where every tool block leads with its call line and rails its result under it. `/bytefly` switches extensions and skills and holds the curated settings, and `/bytefly upgrade` installs a pending update through Pi's own package manager behind a confirmation; opt-in `notify` raises OS notifications when a run, a job, or a question needs you, and Pi's own startup update blocks become themed notices and header markers. `bytefly.json` is the config document every extension reads. |
 
 ### Skills
 
@@ -152,9 +163,8 @@ advertised to the model, and its instructions load only when the task matches
 | Skill | What it does |
 |---|---|
 | [`init`](./skills/init/SKILL.md) | Creates or updates the instruction file Pi actually reads (`AGENTS.md`, or `AGENTS.override.md` when it shadows it) through a built-in interactive interview and plan review, deriving commands, generated paths, packages, and purpose from repository evidence. |
-| [`refactor`](./skills/refactor/SKILL.md) | Audits a project or path for refactoring opportunities: duplication, oversized modules, coupling, drift, and high-churn code with weak tests. Returns a ranked shortlist with evidence and verification commands; discovery is read-only. |
-| [`changelog`](./skills/changelog/SKILL.md) | Records one user-visible bullet in the same commit as the change, audits commits since the last tag for missing or weak entries, and curates a release section from the project's own rules. |
-| [`parallel-dev`](./skills/parallel-dev/SKILL.md) | Runs parallel development as a lead and a team: a lead accountable for the contract, shared files, merge order and a green baseline who also owns a workstream, one owner per disjoint workstream, a walking skeleton first, advisory path claims, a turn-boundary protocol, and independent verification. |
+| [`refactor`](./skills/refactor/SKILL.md) | Audits a project or path for refactoring opportunities: duplication, oversized modules, coupling, drift, and high-churn code with weak tests. A bundled `scripts/inventory.ts` measures sizes, fan-in, churn, and test proximity so a finding is a number with a source, and the ranked shortlist has evidence and verification commands; it then carries the candidate you choose through a behaviour-preserving refactor, and the audit itself is read-only. |
+| [`project-docs`](./skills/project-docs/SKILL.md) | Keeps a project's documents telling the truth about the code: a read-only audit of the front door, the roadmap, the contributor path, and the changelog against the tree and against each other, then one mode per act that writes — a changelog bullet in the same commit as the change, a release section curated from the project's own rules, a shipped roadmap item deleted with the rest renumbered, and the front door's catalog, counts, and examples synced. Discovers each project's category names, scope spelling, item form, and guards rather than assuming a template, and a bundled `scripts/state.ts` prints the changelog's tag, window, and unreleased categories. |
 | [`next`](./skills/next/SKILL.md) | Suggests the next todos by priority — loose work, a broken or unfinished promise — from this conversation once it has done work, and from the tree only when it is empty, with the words and a path after the command saying what to ask and where to look. Read-only, and capped at a short numbered list with evidence and the command that starts each. |
 
 ### Themes
@@ -171,16 +181,16 @@ README use `bytefly-dark`.
 
 <table>
 <tr>
-<td width="50%"><img src="assets/todo.png" alt="The /todos screen: a Todos title rule, a 3/7 completed summary, and the list with check, spinner, and circle glyphs" width="100%"></td>
-<td width="50%"><img src="assets/question.png" alt="The ask_user_question dialog: Auth and Scope tabs, a question, four numbered options with descriptions, and the navigation hint" width="100%"></td>
+<td width="50%"><img src="assets/screens/todo.png" alt="The /todos screen: a Todos title rule, a 3/7 completed summary, and the list with check, spinner, and circle glyphs" width="100%"></td>
+<td width="50%"><img src="assets/screens/question.png" alt="The ask_user_question dialog: Auth and Scope tabs, a question, four numbered options with descriptions, and the navigation hint" width="100%"></td>
 </tr>
 <tr>
-<td width="50%"><img src="assets/job.png" alt="The /jobs screen: a summary line, the job rows with status glyphs and elapsed times, and the focused job's command, cwd, and last output line" width="100%"></td>
-<td width="50%"><img src="assets/rewind.png" alt="The /rewind screen: prompt rows newest first, a diamond marking prompts with a code snapshot, and the focused prompt's snapshot detail" width="100%"></td>
+<td width="50%"><img src="assets/screens/job.png" alt="The /jobs screen: a summary line, the job rows with status glyphs and elapsed times, and the focused job's command, cwd, and last output line" width="100%"></td>
+<td width="50%"><img src="assets/screens/rewind.png" alt="The /rewind screen: prompt rows newest first, a diamond marking prompts with a code snapshot, and a detail line naming the snapshot the focused prompt holds" width="100%"></td>
 </tr>
 <tr>
-<td width="50%"><img src="assets/session.png" alt="The /sessions screen: a counts summary, session rows with unread and claim counts, the focused session's cwd, claims, and identity, and the Tab scope and watch hints" width="100%"></td>
-<td width="50%"><img src="assets/watch.png" alt="The /watch screen: a summary line and watcher rows with live match counts and the focused watcher's pattern and source" width="100%"></td>
+<td width="50%"><img src="assets/screens/session.png" alt="The /sessions screen: a counts summary, session rows with unread and claim counts, the focused session's cwd, claims, and identity, and the Tab scope and watch hints" width="100%"></td>
+<td width="50%"><img src="assets/screens/watch.png" alt="The /watch screen: a summary line and watcher rows with live match counts and the focused watcher's pattern and source" width="100%"></td>
 </tr>
 </table>
 
@@ -192,7 +202,7 @@ each tool's own renderer (or bytefly's generic fallback): the user nameplate and
 a notice, Pi's built-ins, and every tool this package registers. The rail glyph
 is the `chrome.rail` setting.
 
-![A full-page reference of every tool block: the user nameplate, a notice, the turn rule, Pi's read, write, edit, bash, grep, find, and ls renderers, and every package tool — todo, goal, memory, job, watch, subagent, web_search, web_fetch, read_doc, open_path, run_doctor, run_check, send_wechat, ask_user_question, session, the plan tools, and the worktree tools](assets/tool-renderings.png)
+![A full-page reference of every tool block: the user nameplate, a notice, the turn rule, Pi's read, write, edit, bash, grep, find, and ls renderers, and every package tool — todo, goal, memory, job, watch, subagent, web_search, web_fetch, read_doc, open_path, run_doctor, run_check, send_wechat, ask_user_question, session, board, team, the plan tools, and the worktree tools](assets/screens/tool-renderings.png)
 
 `bun run screenshot:tools` regenerates it; `bun run screenshot:tool-pngs` writes
 one image per tool under [`assets/tools/`](./assets/tools).
@@ -202,10 +212,12 @@ each: the first run, the keys that matter, and what to expect on screen.
 
 ## Configuration
 
-Most extensions need no configuration. Every setting lives in one shared
-document, `bytefly.json`, read from `<agent-dir>/bytefly.json` and merged with
-`<cwd>/.pi/bytefly.json` (project wins), under a top-level section named for the
-extension. Each extension's `README.md` covers the behaviour around its keys, and
+Most extensions need no configuration. Every extension setting lives in one
+shared document, `bytefly.json`, read from `<agent-dir>/bytefly.json` and
+merged with `<cwd>/.pi/bytefly.json` (project wins), under a top-level section
+named for the extension. Each extension's page under `docs/extensions/` covers
+the behaviour
+around its keys, and
 [`docs/configuration.md`](./docs/configuration.md) has the resolution rules, the
 settings screen walkthrough, and every section's keys with their type, default,
 and bounds.
@@ -228,10 +240,12 @@ stops the factories from registering; to drop the whole package, use Pi's
 |---|---|
 | [User guide](./docs/user-guide/) | A chaptered manual: install, every feature, settings, troubleshooting, and a command reference. |
 | [Configuration](./docs/configuration.md) | Resolution, the settings screen, and every `bytefly.json` key with its default and bounds. |
-| [Architecture](./docs/architecture.md) | The load path, runtime model, state, process shapes, and where new code belongs. |
+| [Architecture](./docs/architecture.md) | The target shape: the load path, the extension contract, the turn, state, layers, lifetimes, and where a change belongs. |
+| [Extension docs](./docs/extensions/) | One page per extension, opening with its capabilities: the tool and command surface, the integration contract, and the design notes. |
 | [Development](./docs/development.md) | Local setup, checks, tests, cross-platform notes, and the release process. |
 | [Security](./docs/security.md) | Trust boundaries for the loopback and remote surfaces. |
 | [Roadmap](./ROADMAP.md) | Where the pack is going, grouped by the README's promises, with the evidence behind each item. |
+| [Documentation index](./docs/README.md) | The map of everything: the guides, and the deep contracts behind them, by audience. |
 
 ## Contributing
 

package/README.zh-CN.md

@@ -13,7 +13,7 @@
 本页是目录与安装说明。要了解某个功能怎么用 —— 按键、命令以及应有的效果 ——
 请先看[用户指南](./docs/user-guide/)。
 
-![一个运行 Pi TUI 的终端窗口，包含 bytefly 头部、提示行、上下文与已加载扩展、回合分隔线以及状态栏](assets/chrome.png)
+![一个运行 Pi TUI 的终端窗口：bytefly 头部标出 Pi 与 bytefly 的版本、三行按键提示、带名板的消息及其回答与编辑差异（位于竖线内）、两个后台任务完成的通知（一个通过的测试任务与一个失败的构建任务）、回合分隔线、目标与待办栏、夹在两条横线之间且已输入半句的输入框，以及两行页脚（上下文指示、按价目计算的费用、模型名）](assets/screens/chrome.png)
 
 ## 目录
 
@@ -36,7 +36,7 @@ Pi 提供一个精简而锐利的内核。这个包是在其之上的一层，
   让 watcher 盯住日志直到出现关键行，还能让同一仓库上的多个会话通过共享总线协作、
   各自负责自己的一摊 —— 你继续把握主线。
 - **绝不搞乱检出区。** 隔离只需一条命令：任务切到自己分支的 `git worktree` 中，
-  每次提示还会生成快照，因此一次糟糕的回合只需一个 `/rewind` 就能回退。
+  每次提示的首次改动都会生成快照，因此一次糟糕的回合只需一个 `/rewind` 就能回退。
 - **跨会话记忆。** 持久笔记以纯 Markdown 保存，可读、可改、可纳入版本控制。
 - **连通网络与文件。** 在会话内搜索、抓取、浏览、打开和读取文档与表格，还可通过桥接
   在微信里直接回答当前会话。
@@ -56,20 +56,25 @@ pi install npm:@gavin-hu/my-pi-agent
 [用户指南](./docs/user-guide/) 介绍其余安装方式——git、固定版本、
 仅项目本地安装，以及不写入任何内容的试用——还有适用性判断、首个工作流和移除方式。
 
-`git` 需在 `PATH` 上，供 [`worktree`](./extensions/worktree/) 与
-[`rewind`](./extensions/rewind/) 使用；其余部分会优雅降级或禁用，
+`git` 需在 `PATH` 上，供 [`worktree`](./docs/extensions/worktree.md) 与
+[`rewind`](./docs/extensions/rewind.md) 使用；其余部分会优雅降级或禁用，
 `/bytefly doctor` 会指出缺少什么，包括可选的运行时组件。
 Windows、macOS 和 Linux 均可运行，完整检查套件在每个平台上都会执行。
 
 然后在 Pi 中：
 
-- `/bytefly [extension] [refresh]` 打开控制中心的 Extensions 区，列出每个已加载扩展
-  及其运行时健康状况，启用或禁用一个扩展，并用 `x` 清除项目级覆盖。
-- `/bytefly settings` 打开控制中心的 Settings 区：一次会话会改动的十三项设置排成
-  一列，值紧跟在名称之后；用 `Space`/`Enter` 修改，用 `Tab` 切换 Global/Project
-  作用域。其余键都是 `bytefly.json` 编辑，见配置参考。
+- `/bytefly [extension] [refresh]` 打开控制中心的 Extensions 区：三个区共用一个
+  框架，头部横线的右端写着需要注意的事项（没有问题时为 `all clear`），一行 tab
+  标出各区的数量与写入作用域。它按名称列出每个已加载扩展及其复选框与至多一个
+  结论词，启用或禁用一个扩展，并用 `x` 清除项目级覆盖；`/` 过滤行，`!` 只保留
+  需要注意的行，`?` 显示全部按键。
+- `/bytefly settings` 打开控制中心的 Settings 区：一次会话会改动的十二项设置按
+  Startup、Notifications、Session、Price 四组排列，值对齐在同一列；用
+  `Space`/`Enter` 修改一项，用 `s` 切换 Global/Project 作用域。其余键都是
+  `bytefly.json` 编辑，见配置参考。
 - `/bytefly skills` 打开控制中心的 Skills 区：每个 Pi 技能一行，带启用复选框与
-  `SKILL.md` 声明的描述，用 `Space` 在当前作用域开关它。
+  至多一个结论词，`SKILL.md` 声明的描述显示在旁边的区块中，用 `Space` 在当前
+  作用域开关它。
 - `/bytefly doctor [extension] [refresh]` 打印 doctor 报告（`run_doctor` 的文本），
   检查每个已启用扩展在运行时是否具备所需条件。
 - `/bytefly update` 立即重跑包更新检查，报告可更新的包、本包版本与 release URL，
@@ -80,53 +85,57 @@ Windows、macOS 和 Linux 均可运行，完整检查套件在每个平台上都
 还有一件包会自行做的事：每次交互式会话启动时，`bytefly` 询问 Pi 的包管理器
 哪些已配置的包有更新，抑制 Pi 自己的启动更新块，并用主题化 notice 列出它们
 和 `pi update --extensions`；Pi 自身的新版本也由它绘制，提示 `pi update` 与
-changelog。新版本还会标在头部 —— 本包的与 Pi 自己的。不会发送任何会话内容
-（Pi 自己的版本请求只是被重新绘制），`PI_OFFLINE` 可跳过检查；信任边界见
+changelog。新版本还会标在头部 —— 本包的与 Pi 自己的。不会发送任何会话内容：
+Pi 自己的版本请求只是被重新绘制，本包的最新版本则来自一次固定的 npm
+`latest` 请求，`PI_OFFLINE` 可跳过检查；信任边界见
 [`docs/security.md`](./docs/security.md)。
 
 ## 包含内容
 
-19 个扩展、5 个随包技能，以及 2 个主题，按你想达成的目标分组。每个扩展自己的 `README.md`
-提供完整的工具与命令说明。
+21 个扩展、4 个随包技能，以及 2 个主题，按 [路线图](./ROADMAP.md) 追踪的承诺分组；
+[用户指南](./docs/user-guide/) 按章节讲述同样的内容。每个扩展在 `docs/extensions/`
+下的页面提供完整的工具与命令说明，并以能力表开头。
 
 ### 规划与委派
 
 | 扩展 | 工具与命令 | 说明 |
 |---|---|---|
-| [`plan`](./extensions/plan/) | `enter_plan_mode`, `write_plan`, `exit_plan_mode`, `cancel_plan_mode`, `set_plan_steps`, `/plan`, `--plan` | 只读规划：模型先调研，把计划保存到 `~/.pi/agent/plans/<repo-key>` 下（每个仓库一份，各 worktree 共享），你在写入任何内容前先批准；开启 `plan.split` 后，批准时还可以把计划拆成切片，由独立会话按名字加入。可在 TUI 中审阅，或在浏览器中打开以留下行内评论：页面会跟随计划文件实时更新，你也可以给每位同事各一个审阅链接，各自以绑定的名义评论。`init` 技能复用同一审阅流程来创建或更新项目的 `AGENTS.md`。 |
-| [`check`](./extensions/check/) | `run_check`, `/check` | 检测项目的测试、lint 或类型检查命令（或使用 `check.command`），在受监管的进程中运行，并把失败整理成可导航的 `file:line` 列表。 |
-| [`subagent`](./extensions/subagent/) | `subagent`, `/agents` | 把任务委派给专职智能体（`explorer`、`planner`、`reviewer`、`worker`、`researcher`、`tester`、`debugger`、`documenter`），运行在它自己的 Pi 进程中 —— 单个、并行、链式或在后台运行；后台运行时在页脚显示数量，完成后发出提示。 |
-| [`todo`](./extensions/todo/) | `todo`, `/todos` | 持久任务列表（`pending` / `in_progress` / `completed`），配一行式 widget。 |
-| [`goal`](./extensions/goal/) | `goal`, `/goal` | 持久会话目标，保存在 widget 中，并在每个回合前重述。 |
-| [`question`](./extensions/question/) | `ask_user_question` | 向你提出一个或多个结构化问题（带标签的选项外加自由填写的“其他”）并等待回答。 |
-| [`job`](./extensions/job/) | `job`, `/jobs` | 在后台运行长时 shell 命令；查看日志、等待或结束它们。 |
-| [`watch`](./extensions/watch/) | `watch`, `/watch` | 跟踪文件或命令输出，按模式匹配行，并提醒你或把匹配的行交给智能体。 |
-| [`session-bus`](./extensions/session-bus/) | `session`, `/sessions`（屏幕） | 在同一仓库的多个 Pi 会话之间协调：发现彼此、交换简短消息/事件、读取收件箱、加入已批准拆分中的一个切片或编辑前声明路径；`/sessions` 是显示对等会话、未读邮件和路径声明的实时面板。本地、默认拉取式；会话可以自行开启收件箱监视，在空闲时唤起本会话的一轮，从不创建智能体。 |
-| [`context`](./extensions/context/) | `/context` | 显示上下文窗口的去向 —— 系统提示、工具定义、按角色拆分的对话、注入的笔记 —— 并从报告中触发压缩，给出压缩前后的数字。 |
+| [`plan`](./docs/extensions/plan.md) | `enter_plan_mode`, `write_plan`, `exit_plan_mode`, `cancel_plan_mode`, `set_plan_steps`, `/plan`, `--plan` | 只读规划：模型先调研，把计划保存到 `~/.pi/agent/plans/<repo-key>` 下（每个仓库一份，各 worktree 共享），你在写入任何内容前先批准。可在 TUI 中审阅，或在浏览器中打开以留下行内评论：页面会跟随计划文件实时更新，你也可以给每位同事各一个审阅链接，各自以绑定的名义评论。`init` 技能复用同一审阅流程来创建或更新项目的 `AGENTS.md`。 |
+| [`check`](./docs/extensions/check.md) | `run_check`, `/check` | 检测项目的测试、lint 或类型检查命令（或使用 `check.command`），在受监管的进程中运行，并把失败整理成可导航的 `file:line` 列表。 |
+| [`subagent`](./docs/extensions/subagent.md) | `subagent`, `/agents` | 把任务委派给专职智能体（`explorer`、`planner`、`reviewer`、`worker`、`researcher`、`tester`、`debugger`、`documenter`），运行在它自己的 Pi 进程中 —— 单个、并行、链式或在后台运行；后台运行时在页脚显示数量，完成后发出提示。 |
+| [`todo`](./docs/extensions/todo.md) | `todo`, `/todos` | 持久任务列表（`pending` / `in_progress` / `completed`），配一行式 widget。 |
+| [`goal`](./docs/extensions/goal.md) | `goal`, `/goal` | 持久会话目标，保存在 widget 中，并在每个回合前重述。 |
+| [`question`](./docs/extensions/question.md) | `ask_user_question` | 向你提出一个或多个结构化问题（带标签的选项外加自由填写的“其他”）并等待回答。 |
+| [`job`](./docs/extensions/job.md) | `job`, `/jobs` | 在后台运行长时 shell 命令；查看日志、等待或结束它们。 |
+| [`watch`](./docs/extensions/watch.md) | `watch`, `/watch` | 跟踪文件或命令输出，按模式匹配行，并提醒你或把匹配的行交给智能体。 |
+| [`session-bus`](./docs/extensions/session-bus.md) | `session`, `/sessions`（屏幕） | 在同一仓库的多个 Pi 会话之间协调：发现彼此、交换简短消息/事件、读取收件箱、编辑前声明路径；`/sessions` 是显示对等会话、未读邮件和路径声明的实时面板。本地、默认拉取式；收件箱监视需会话自行开启，空闲时会唤起本会话的一轮，从不创建智能体。 |
+| [`board`](./docs/extensions/board.md) | `board`、`/board` | 每个仓库一块共享看板：一张卡片代表一个 feature，任何 session 都可以认领、移动、编辑、加注、完成、归档——已完成的卡片会离开看板进入 `archive/`，其注记与落地 commit 仍可读，长历史不再拖累每次读取——同一个看板在浏览器里以 **Board** 和 **Team** 两个 tab 实时显示。页面只读——写入只走工具——并以固定席位 `team-lead` 对外服务，因此第二个 session 打开的是同一张页面，而不是另起一个；把卡片交给队友由 `team` 负责，因为只有它能给对端发消息。卡片可以带上优先级、声明自己在等待哪几张卡片。步骤留在 owner 的 plan 和 `todo` 里，卡片就是 feature、它的 owner，以及解释它的历史。在 `bytefly.json` 里设置 `board.port` 可以固定看板端口，收藏的地址在重启后依然有效。 |
+| [`team`](./docs/extensions/team.md) | `team`、`/team` | 同一块看板上的 lead 轮次。`/team join <label>` 让一个 session 加入团队，lead 打开 `/board` 时则以 `team-lead` 自动加入；随后 `assign` 把一个 feature 交给运行中的 session，`offer` 交给谁有空谁接——广播而不写卡片，由第一个认领的人拿走——`reclaim` 把卡片收回 To do。结果会说明谁会因此被叫醒、谁会在下一轮才读到；`/team` 在终端里打印同一份轮次，不用开浏览器，也不启动任何进程。 |
+| [`context`](./docs/extensions/context.md) | `/context` | 显示上下文窗口的去向 —— 系统提示、工具定义、按角色拆分的对话、注入的笔记 —— 并从报告中触发压缩，给出压缩前后的数字。 |
 
 ### 保护你的工作
 
 | 扩展 | 工具与命令 | 说明 |
 |---|---|---|
-| [`worktree`](./extensions/worktree/) | `enter_worktree`, `exit_worktree`, `prune_worktrees`, `list_worktrees`, `/worktree` (screen), `/worktree enter|exit|prune`, `--worktree` | 在隔离的 `git worktree` 里、在独立分支上工作；内置的 read/write/edit/bash 工具会跟随，清理时也不会丢弃工作。 |
-| [`rewind`](./extensions/rewind/) | `/rewind`, `/review`, `↺ N` 状态标记 | 每次提示时在 `refs/pi/rewind` 下对仓库生成快照，可恢复代码、对话或两者，并在还原文件前审阅本轮改动。 |
-| [`memory`](./extensions/memory/) | `memory`, `/memory` | 跨会话的持久笔记，以可人工编辑的 Markdown 保存，注入每次运行，并通过 `/memory` 选择器管理。 |
+| [`worktree`](./docs/extensions/worktree.md) | `enter_worktree`, `exit_worktree`, `prune_worktrees`, `list_worktrees`, `/worktree` (screen), `/worktree enter\|exit\|prune`, `--worktree` | 在隔离的 `git worktree` 里、在独立分支上工作；内置的 read/write/edit/bash 工具会跟随，清理时也不会丢弃工作。 |
+| [`rewind`](./docs/extensions/rewind.md) | `/rewind`, `/review`, `↺ N` 状态标记 | 在每次提示的首次改动前于 `refs/pi/rewind` 下对仓库生成快照，可恢复代码、对话或两者，并在还原文件前审阅本轮改动。 |
+| [`memory`](./docs/extensions/memory.md) | `memory`, `/memory` | 跨会话的持久笔记，以可人工编辑的 Markdown 保存，注入每次运行，并通过 `/memory` 选择器管理。 |
 
 ### 连通外部世界
 
 | 扩展 | 工具与命令 | 说明 |
 |---|---|---|
-| [`web-access`](./extensions/web-access/) | `web_search`, `web_fetch` | 搜索网络（默认无密钥的 DuckDuckGo，可选 SearXNG 或 Brave），并把页面抓取为可读文本，支持分页、`find`、逐跳 SSRF 检查以及可选的 PDF 支持。 |
-| [`file-browse`](./extensions/file-browse/) | `/browse` | 启动一个以工作目录为根的本地回环、只读文件浏览器，带 Markdown 预览、模糊快速打开面板、从选区复制 `path:12-30` 引用、为常开页面提供的实时状态，以及所列目录变化时的重新加载提示。 |
-| [`file-read`](./extensions/file-read/) | `read_doc` | 在进程内从本地 PDF、DOCX、DOC、ODT、RTF 或 XLSX 提取文本，支持分页。 |
-| [`file-open`](./extensions/file-open/) | `/open`, `open_path` | 用操作系统原生应用打开或定位文件/目录。 |
-| [`wechat`](./extensions/wechat/) | `/wechat`, `send_wechat` | 通过微信 iLink 机器人 API 把微信聊天桥接到实时会话；入站文本、图片和文件会变成回合。 |
+| [`web-access`](./docs/extensions/web-access.md) | `web_search`, `web_fetch` | 搜索网络（默认无密钥的 DuckDuckGo，可选 SearXNG 或 Brave），并把页面抓取为可读文本，支持分页、`find`、逐跳 SSRF 检查、把 JSON/CSV/XML 正文渲染为表格或树状结构，以及可选的 PDF 支持。 |
+| [`file-browse`](./docs/extensions/file-browse.md) | `/browse` | 启动一个以工作目录为根的本地回环、只读文件浏览器，带 Markdown 预览、模糊快速打开面板、从选区复制 `path:12-30` 引用、为常开页面提供的实时状态，以及所列目录变化时的重新加载提示。 |
+| [`file-read`](./docs/extensions/file-read.md) | `read_doc` | 在进程内从本地 PDF、DOCX、DOC、ODT、RTF 或 XLSX 提取文本，支持分页。 |
+| [`file-open`](./docs/extensions/file-open.md) | `/open`, `open_path` | 用操作系统原生应用打开或定位文件/目录。 |
+| [`wechat`](./docs/extensions/wechat.md) | `/wechat`, `send_wechat` | 通过微信 iLink 机器人 API 把微信聊天桥接到实时会话；入站文本、图片和文件会变成回合。 |
 
 ### 界面与维护
 
 | 扩展 | 工具与命令 | 说明 |
 |---|---|---|
-| [`bytefly`](./extensions/bytefly/) | `/bytefly`（`doctor`、`settings`、`skills`、`update` 子命令）、`run_doctor` | 可见的那一层：主题化头部配宽度自适应页脚，Pi 工作行上实时显示工具、调用次数与计时，转录中每个工具块以调用行为标题、结果正文挂在其下方。`/bytefly` 可开关扩展与技能，并集中存放精选设置；可选的 `notify` 会在一次运行、后台任务或待回答的问题需要你时发出系统通知，Pi 自己的启动更新块也会变成主题化 notice 与头部标记。`bytefly.json` 是每个扩展都会读取的配置文档。 |
+| [`bytefly`](./docs/extensions/bytefly.md) | `/bytefly`（`doctor`、`settings`、`skills`、`update`、`upgrade` 子命令）、`run_doctor` | 可见的那一层：主题化头部配宽度自适应页脚，Pi 工作行上实时显示工具、调用次数与计时，转录中每个工具块以调用行为标题、结果正文挂在其下方。`/bytefly` 可开关扩展与技能，并集中存放精选设置；`/bytefly upgrade` 在确认后通过 Pi 自己的包管理器安装待更新版本；可选的 `notify` 会在一次运行、后台任务或待回答的问题需要你时发出系统通知，Pi 自己的启动更新块也会变成主题化 notice 与头部标记。`bytefly.json` 是每个扩展都会读取的配置文档。 |
 
 ### 技能
 
@@ -135,9 +144,8 @@ changelog。新版本还会标在头部 —— 本包的与 Pi 自己的。不
 | 技能 | 说明 |
 |---|---|
 | [`init`](./skills/init/SKILL.md) | 通过内置的交互式访谈和计划审阅，基于仓库证据创建或更新 Pi 实际读取的指令文件（`AGENTS.md`；存在覆盖它的 `AGENTS.override.md` 时则是该文件），并从仓库推导命令、生成路径与包范围。 |
-| [`refactor`](./skills/refactor/SKILL.md) | 审计项目或路径中的重构机会：重复代码、过大的模块、耦合、结构漂移，以及测试薄弱且改动频繁的代码。返回带证据和验证命令的排序清单；发现阶段只读。 |
-| [`changelog`](./skills/changelog/SKILL.md) | 在变更的同一次提交中记录一条用户可见的条目，审计上一个 tag 以来缺失或薄弱的条目，并按项目自己的规则整理发布段落。 |
-| [`parallel-dev`](./skills/parallel-dev/SKILL.md) | 以“负责人加团队”的方式组织并行开发：负责人对契约、共享文件、合并顺序和绿色基线负责，同时自己承担一个工作流；每个互不重叠的工作流各有一名所有者，先做可运行的纵向骨架，声明路径，在每个回合的边界协作，并由他人独立验证。 |
+| [`refactor`](./skills/refactor/SKILL.md) | 审计项目或路径中的重构机会：重复代码、过大的模块、耦合、结构漂移，以及测试薄弱且改动频繁的代码。随包的 `scripts/inventory.ts` 会量出体积、扇入、churn 和测试邻近度，让每条发现都带来源，排序清单附证据和验证命令；选定一个候选项后，它会把该重构带到不改行为地完成，而审计本身只读。 |
+| [`project-docs`](./skills/project-docs/SKILL.md) | 让项目的四份文档如实描述代码：只读审计门面、路线图、贡献路径与 changelog，既对照代码树也互相对照；然后每个写入动作一个模式——在变更的同一次提交里记下 changelog 条目、按项目自己的规则整理发布段落、在已发布的路线图条目上删除并把其余重新编号、同步门面的目录、计数与示例。它先摸清各项目的类目名、范围拼写、条目形制与守卫，而不是套用模板；随包的 `scripts/state.ts` 会打印 changelog 的 tag、窗口与未发布类目。 |
 | [`next`](./skills/next/SKILL.md) | 按优先级建议接下来的待办——未收尾的工作、已破坏或未兑现的承诺——会话已有工作时基于本次会话，仅当会话为空时才基于代码树；命令后的文字说明问什么、路径说明看哪里。只读，输出带证据和启动命令的简短编号清单。 |
 
 ### 主题
@@ -153,16 +161,16 @@ changelog。新版本还会标在头部 —— 本包的与 Pi 自己的。不
 
 <table>
 <tr>
-<td width="50%"><img src="assets/todo.png" alt="/todos 屏幕：Todos 标题线、3/7 完成摘要，以及带对勾、进行中和圆圈字形的列表" width="100%"></td>
-<td width="50%"><img src="assets/question.png" alt="ask_user_question 对话框：Auth 与 Scope 标签页、问题、四个带说明的编号选项，以及导航提示" width="100%"></td>
+<td width="50%"><img src="assets/screens/todo.png" alt="/todos 屏幕：Todos 标题线、3/7 完成摘要，以及带对勾、进行中和圆圈字形的列表" width="100%"></td>
+<td width="50%"><img src="assets/screens/question.png" alt="ask_user_question 对话框：Auth 与 Scope 标签页、问题、四个带说明的编号选项，以及导航提示" width="100%"></td>
 </tr>
 <tr>
-<td width="50%"><img src="assets/job.png" alt="/jobs 屏幕：摘要行、带状态字形和耗时的任务行，以及焦点任务的命令、工作目录和最后一行输出" width="100%"></td>
-<td width="50%"><img src="assets/rewind.png" alt="/rewind 屏幕：从新到旧的提示行、标记有代码快照的菱形，以及焦点提示的快照详情" width="100%"></td>
+<td width="50%"><img src="assets/screens/job.png" alt="/jobs 屏幕：摘要行、带状态字形和耗时的任务行，以及焦点任务的命令、工作目录和最后一行输出" width="100%"></td>
+<td width="50%"><img src="assets/screens/rewind.png" alt="/rewind 屏幕：从新到旧的提示行、标记有代码快照的菱形，以及一行标明焦点提示所持快照的详情" width="100%"></td>
 </tr>
 <tr>
-<td width="50%"><img src="assets/session.png" alt="/sessions 屏幕：计数摘要、带未读数和路径声明数的会话行、焦点会话的工作目录、声明和身份，以及 Tab 范围与监视提示" width="100%"></td>
-<td width="50%"><img src="assets/watch.png" alt="/watch 屏幕：摘要行和带实时匹配数的监视行，以及焦点监视的模式与来源" width="100%"></td>
+<td width="50%"><img src="assets/screens/session.png" alt="/sessions 屏幕：计数摘要、带未读数和路径声明数的会话行、焦点会话的工作目录、声明和身份，以及 Tab 范围与监视提示" width="100%"></td>
+<td width="50%"><img src="assets/screens/watch.png" alt="/watch 屏幕：摘要行和带实时匹配数的监视行，以及焦点监视的模式与来源" width="100%"></td>
 </tr>
 </table>
 
@@ -173,7 +181,7 @@ changelog。新版本还会标在头部 —— 本包的与 Pi 自己的。不
 （每个工具自身的渲染器或 bytefly 的通用回退）——用户铭牌与通知、Pi 内置工具，以及本包注册的每个工具。
 侧栏字形由 `chrome.rail` 设置。
 
-![每个工具块的全页参考图：用户铭牌、通知、回合分隔线，Pi 的 read、write、edit、bash、grep、find、ls 渲染器，以及每个包内工具——todo、goal、memory、job、watch、subagent、web_search、web_fetch、read_doc、open_path、run_doctor、send_wechat、ask_user_question、session、plan 工具与 worktree 工具](assets/tool-renderings.png)
+![每个工具块的全页参考图：用户铭牌、通知、回合分隔线，Pi 的 read、write、edit、bash、grep、find、ls 渲染器，以及每个包内工具——todo、goal、memory、job、watch、subagent、web_search、web_fetch、read_doc、open_path、run_doctor、send_wechat、ask_user_question、session、board、team、plan 工具与 worktree 工具](assets/screens/tool-renderings.png)
 
 `bun run screenshot:tools` 重新生成它；`bun run screenshot:tool-pngs` 在
 [`assets/tools/`](./assets/tools) 下为每个工具输出一张图。
@@ -183,9 +191,9 @@ changelog。新版本还会标在头部 —— 本包的与 Pi 自己的。不
 
 ## 配置
 
-大多数扩展无需配置。所有设置都在一个共享文档 `bytefly.json` 中，从
+大多数扩展无需配置。所有扩展设置都在一个共享文档 `bytefly.json` 中，从
 `<agent-dir>/bytefly.json` 读取，并与 `<cwd>/.pi/bytefly.json` 合并（项目优先），
-位于一个以扩展名命名的顶层 section 下。每个扩展的 `README.md` 说明其键位的行为，
+位于一个以扩展名命名的顶层 section 下。每个扩展在 `docs/extensions/` 下的页面说明其键位的行为，
 [`docs/configuration.md`](./docs/configuration.md) 则给出解析规则、设置界面操作方式，
 以及每个 section 的键、类型、默认值和取值范围。
 
@@ -206,10 +214,12 @@ Pi 的 `--no-extensions`，或从你的设置中删除该包。
 |---|---|
 | [用户指南](./docs/user-guide/) | 分章手册：安装、每项功能、设置、故障排查与命令参考。 |
 | [配置](./docs/configuration.md) | 解析规则、设置界面，以及 `bytefly.json` 每个键的默认值与取值范围。 |
-| [架构](./docs/architecture.md) | 加载路径、运行时模型、状态、进程形态，以及新代码应放在哪里。 |
+| [架构](./docs/architecture.md) | 目标形态：加载路径、扩展契约、一次回合、状态、分层、长生命周期，以及改动应放在哪里。 |
+| [扩展文档](./docs/extensions/) | 每个扩展一页，以能力表开头：工具与命令面、集成契约，以及设计说明。 |
 | [开发](./docs/development.md) | 本地设置、检查、测试、跨平台注意事项与发布流程。 |
 | [安全](./docs/security.md) | 回环与远程界面的信任边界。 |
 | [路线图](./ROADMAP.md) | 包的下一步方向，按 README 的承诺分组，并列出每条事项的依据。 |
+| [文档索引](./docs/README.md) | 全部文档的地图：各份指南，以及它们背后的深度契约，按读者归类。 |
 
 ## 参与贡献
 

package/docs/extensions/README.md

@@ -0,0 +1,34 @@
+# Extension docs
+
+One page per extension, in the order the
+[catalog](../../README.md#what-you-get) lists them. Every page opens with its **Capabilities** table — one row per thing
+the extension can do, the tool, command, or key that delivers it, and what you
+get — then the Quickstart, the surface, the behaviour, and the contributor
+sections behind them.
+
+| Extension | What it is | Page |
+|---|---|---|
+| `plan` | Read-only planning, saved to disk and reviewed in the TUI or a browser | [`plan.md`](./plan.md) |
+| `check` | The project's test, lint, or typecheck command, run and parsed | [`check.md`](./check.md) |
+| `subagent` | Delegation to a specialist agent in its own Pi process | [`subagent.md`](./subagent.md) |
+| `todo` | A whole-list task tracker that follows the session branch | [`todo.md`](./todo.md) |
+| `goal` | One persistent session objective, restated before each turn | [`goal.md`](./goal.md) |
+| `question` | Structured questions with labelled options and a free-form answer | [`question.md`](./question.md) |
+| `job` | Long-lived shell commands in the background, with logs and a wait | [`job.md`](./job.md) |
+| `watch` | Tailing a file or command and matching new lines | [`watch.md`](./watch.md) |
+| `session-bus` | Coordination between parallel Pi sessions on one repository | [`session-bus.md`](./session-bus.md) |
+| `board` | One shared feature board per repository, written by the tools and shown by one page a lead serves | [`board.md`](./board.md) |
+| `team` | The lead's round: hand a card to a running session, take one back, or print it with `/team` | [`team.md`](./team.md) |
+| `context` | Where the context window went, and compacting from the report | [`context.md`](./context.md) |
+| `worktree` | An isolated `git worktree` per task, and the built-in tools following it | [`worktree.md`](./worktree.md) |
+| `rewind` | Prompt-anchored snapshots, restoring code, conversation, or both | [`rewind.md`](./rewind.md) |
+| `memory` | Durable cross-session notes as human-editable markdown | [`memory.md`](./memory.md) |
+| `web-access` | Searching the web and fetching a page as readable text | [`web-access.md`](./web-access.md) |
+| `file-browse` | A loopback, read-only browser for the working directory | [`file-browse.md`](./file-browse.md) |
+| `file-read` | Text out of a PDF, DOCX, DOC, ODT, RTF, or XLSX, in process | [`file-read.md`](./file-read.md) |
+| `file-open` | Opening or revealing a path in the OS-native application | [`file-open.md`](./file-open.md) |
+| `wechat` | A WeChat bridge with one Pi conversation per peer | [`wechat.md`](./wechat.md) |
+| `bytefly` | The header, footer, turn rule, control center, notices, and update check | [`bytefly.md`](./bytefly.md) |
+
+The template every page follows is
+[`docs/development.md#one-doc-per-extension`](../development.md#one-doc-per-extension).