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

package/README.md

@@ -11,9 +11,9 @@
 of extensions, skills, and themes to the agent you already use — install the pack, turn
 off what you do not want, and keep using Pi unchanged.
 
-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/).
+This page is the catalog and the setup instructions. Each feature's own page
+under [`docs/extensions/`](./docs/extensions/) carries the keys, the commands, and
+what you should see.
 
 ![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)
 
@@ -57,13 +57,10 @@ like any other.
 Requires a working [Pi](https://pi.dev) installation.
 
 ```bash
-pi install npm:@gavin-hu/my-pi-agent
+pi install npm:@gavin-hu/my-pi-agent                        # the latest release
+pi install git:github.com/gavin-hu/my-pi-agent@v0.22.0      # a pinned release
 ```
 
-[User guide](./docs/user-guide/) has the other sources — git, a
-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`](./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.
@@ -78,10 +75,10 @@ Then, from inside Pi:
   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
+- `/bytefly settings` opens the control center's Settings section: the fifteen
   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,
+  Board, 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 and at most one verdict word, what its `SKILL.md`
@@ -108,16 +105,15 @@ document. `PI_OFFLINE` skips the check;
 
 ## What you get
 
-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.
+22 extensions, 3 packaged skills, and 2 themes, grouped by the promises this
+README makes. 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`](./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`. |
+| [`plan`](./docs/extensions/plan.md) | `plan`, `/plan`, `--plan` | Read-only planning, one tool with five actions — `enter`, `write`, `exit`, `steps`, `cancel`: 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. |
@@ -126,15 +122,16 @@ the full tool and command surface, opening with its capabilities.
 | [`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. |
+| [`serve`](./docs/extensions/serve.md) | — | The session's one loopback server. `/board`, `/browse`, and a browser plan review mount path prefixes on it instead of binding their own listeners, so a session has one port, one chip, and one close path — and a second session (a peer conversation, another worktree, another Pi) still gets its own. The port is the project's own number, hashed from its repository key into `4780`–`5779`, so a bookmarked URL survives a restart without a setting, `serve.port` in `bytefly.json` overrides it, and a shared review borrows exactly one LAN address for the one page that asked. |
+| [`board`](./docs/extensions/board.md) | `board`, `/board` | One shared feature board per repository: a card per feature, moving through five lanes — `backlog`, `plan`, `execute`, `blocked`, `done` — where a contract (`goal`, `acceptance`, `scopeOut`) must name the plan `plan` action `write` saved in this repository's plan store and be approved by the lead (`board.lead` in `bytefly.json`, never the card's holder) or by the person with `/board approve` before it may be executed, and the finished work spot-checked the same way (`/board review`) before it may be done; `plan` and `execute` are held to a WIP limit from `bytefly.json`. A finished card leaves the board for an `archive/` pile with its notes and landed commit still readable, and one loopback page 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 board's lead (`board.lead`, `lead` by default), 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. The Team tab folds the owners a bus has no record of into one row, because a label that ever claimed a card stays an owner. The page answers at `/board` on the project's own port, hashed from its repository key, so the bookmark survives a restart without a setting; `serve.port` in `bytefly.json` overrides it. Off by default: load it with `PI_ENABLED_EXTENSIONS=board`. |
+| [`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 under the name the page serves as; 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 — `reclaim` takes a card back to Backlog, and `claim` takes one for the lead itself, whose plan and contract are then `board`'s. 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. Off by default with `board`: load both with `PI_ENABLED_EXTENSIONS=board,team`. |
 | [`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`](./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. |
+| [`worktree`](./docs/extensions/worktree.md) | `worktree`, `/worktree` (screen), `/worktree enter\|exit\|prune`, `--worktree` | Work inside an isolated `git worktree` on its own branch — one tool with four actions: `enter`, `exit`, `list`, `prune`; 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. |
 
@@ -152,7 +149,7 @@ the full tool and command surface, opening with its capabilities.
 
 | Extension | Tools and commands | What it does |
 |---|---|---|
-| [`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. |
+| [`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 the composer's top border (a `working` count, the run's tools, 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
 
@@ -164,7 +161,6 @@ advertised to the model, and its instructions load only when the task matches
 |---|---|
 | [`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. 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
@@ -194,6 +190,17 @@ README use `bytefly-dark`.
 </tr>
 </table>
 
+The plan review as the terminal draws it, then the three browser pages this
+package serves: the board, the browser-based plan review, and the file browser.
+
+![The terminal plan review: a Plan Review title rule, a notice that one section changed since the last review, the plan body with its headings and ◼/◻ task checkboxes, a scroll gauge naming the current section and the visible line range, and the Esc/a/r/w, scroll, and section-jump hints](assets/screens/plan.png)
+
+![The board page: a toolbar with the repository's name and a live badge, Board and Team tabs, done-of-total progress, a filter, the keys button and a theme toggle; five lane trays, each with a dot, a count and a fold control; and cards carrying an owner chip, a note count and its age, path hints, a line naming what the card waits for, a line naming the cards it holds up, and a reason line, with no button on any of them](assets/screens/board.png)
+
+![The browser-based plan review: a sticky header with the plan title, a status chip, and the Approve & run, Save feedback, and Back to Pi actions, a Share action, a side panel with step progress and a section outline, and the plan as one measured column with a comment rail holding the owner's own comment and a teammate's @priya comment](assets/screens/plan-review.png)
+
+![The loopback file browser, showing the path filter, the file tree, and a rendered Markdown preview](assets/screens/file-browse.png)
+
 ### Tool renderings
 
 Every tool block as the transcript draws it — the tool's own call line as the
@@ -202,13 +209,13 @@ 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, board, team, the plan tools, and the worktree tools](assets/screens/tool-renderings.png)
+<img src="assets/screens/tool-renderings.png" alt="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" width="100%">
 
 `bun run screenshot:tools` regenerates it; `bun run screenshot:tool-pngs` writes
 one image per tool under [`assets/tools/`](./assets/tools).
 
-Ready to use one? The [user guide](./docs/user-guide/) has a walkthrough for
-each: the first run, the keys that matter, and what to expect on screen.
+Ready to use one? Each extension's page under [`docs/extensions/`](./docs/extensions/)
+opens with what it does and the keys and commands it answers.
 
 ## Configuration
 
@@ -222,7 +229,16 @@ around its keys, and
 settings screen walkthrough, and every section's keys with their type, default,
 and bounds.
 
-Every extension is on by default. To load the pack without some of them, set
+Almost every extension is on by default. `board` and `team` are the exception: the
+work list and the lead's half of it are one workflow a session either runs or does
+not, so a session that never works a board should not carry those tools, commands,
+and page. Set `PI_ENABLED_EXTENSIONS` to the opt-in names to load:
+
+```bash
+PI_ENABLED_EXTENSIONS=board,team pi -e .
+```
+
+To load the pack without some of the extensions that are on by default, set
 `PI_DISABLED_EXTENSIONS` to a comma- or whitespace-separated list of extension
 names (the directory names under [`extensions/`](./extensions/)):
 
@@ -230,21 +246,21 @@ names (the directory names under [`extensions/`](./extensions/)):
 PI_DISABLED_EXTENSIONS=todo,job pi -e .
 ```
 
-Names are compared case-insensitively and unknown names are ignored. This only
-stops the factories from registering; to drop the whole package, use Pi's
-`--no-extensions` or remove the package from your settings.
+Names are compared case-insensitively and unknown names are ignored.
+`PI_ENABLED_EXTENSIONS` only switches on the opt-in extensions, so naming one
+there never disables another, and `PI_DISABLED_EXTENSIONS` still wins over it.
+Both only stop the factories from registering; to drop the whole package, use
+Pi's `--no-extensions` or remove the package from your settings.
 
 ## Documentation
 
 | Guide | What it covers |
 |---|---|
-| [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 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

@@ -10,8 +10,8 @@
 `my-pi-agent` 是一个 [Pi](https://pi.dev) 包，在你已经使用的智能体之上新增一组精选
 扩展、技能和主题 —— 安装整个包，关掉你不需要的部分，其余照常使用 Pi。
 
-本页是目录与安装说明。要了解某个功能怎么用 —— 按键、命令以及应有的效果 ——
-请先看[用户指南](./docs/user-guide/)。
+本页是目录与安装说明。每个功能在 [`docs/extensions/`](./docs/extensions/) 下都有自己的页面，
+写清按键、命令以及应有的效果。
 
 ![一个运行 Pi TUI 的终端窗口：bytefly 头部标出 Pi 与 bytefly 的版本、三行按键提示、带名板的消息及其回答与编辑差异（位于竖线内）、两个后台任务完成的通知（一个通过的测试任务与一个失败的构建任务）、回合分隔线、目标与待办栏、夹在两条横线之间且已输入半句的输入框，以及两行页脚（上下文指示、按价目计算的费用、模型名）](assets/screens/chrome.png)
 
@@ -50,12 +50,10 @@ Pi 通过 [`package.json`](./package.json) 里的 `pi` manifest 发现这些资
 需要一个可用的 [Pi](https://pi.dev) 安装。
 
 ```bash
-pi install npm:@gavin-hu/my-pi-agent
+pi install npm:@gavin-hu/my-pi-agent                        # 最新发布版
+pi install git:github.com/gavin-hu/my-pi-agent@v0.22.0      # 固定版本
 ```
 
-[用户指南](./docs/user-guide/) 介绍其余安装方式——git、固定版本、
-仅项目本地安装，以及不写入任何内容的试用——还有适用性判断、首个工作流和移除方式。
-
 `git` 需在 `PATH` 上，供 [`worktree`](./docs/extensions/worktree.md) 与
 [`rewind`](./docs/extensions/rewind.md) 使用；其余部分会优雅降级或禁用，
 `/bytefly doctor` 会指出缺少什么，包括可选的运行时组件。
@@ -68,8 +66,8 @@ Windows、macOS 和 Linux 均可运行，完整检查套件在每个平台上都
   标出各区的数量与写入作用域。它按名称列出每个已加载扩展及其复选框与至多一个
   结论词，启用或禁用一个扩展，并用 `x` 清除项目级覆盖；`/` 过滤行，`!` 只保留
   需要注意的行，`?` 显示全部按键。
-- `/bytefly settings` 打开控制中心的 Settings 区：一次会话会改动的十二项设置按
-  Startup、Notifications、Session、Price 四组排列，值对齐在同一列；用
+- `/bytefly settings` 打开控制中心的 Settings 区：一次会话会改动的十五项设置按
+  Startup、Notifications、Session、Board、Price 五组排列，值对齐在同一列；用
   `Space`/`Enter` 修改一项，用 `s` 切换 Global/Project 作用域。其余键都是
   `bytefly.json` 编辑，见配置参考。
 - `/bytefly skills` 打开控制中心的 Skills 区：每个 Pi 技能一行，带启用复选框与
@@ -92,15 +90,14 @@ Pi 自己的版本请求只是被重新绘制，本包的最新版本则来自
 
 ## 包含内容
 
-21 个扩展、4 个随包技能，以及 2 个主题，按 [路线图](./ROADMAP.md) 追踪的承诺分组；
-[用户指南](./docs/user-guide/) 按章节讲述同样的内容。每个扩展在 `docs/extensions/`
-下的页面提供完整的工具与命令说明，并以能力表开头。
+22 个扩展、3 个随包技能，以及 2 个主题，按本 README 的承诺分组。
+每个扩展在 `docs/extensions/` 下的页面提供完整的工具与命令说明，并以能力表开头。
 
 ### 规划与委派
 
 | 扩展 | 工具与命令 | 说明 |
 |---|---|---|
-| [`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`。 |
+| [`plan`](./docs/extensions/plan.md) | `plan`, `/plan`, `--plan` | 只读规划（一个工具五个动作：`enter`、`write`、`exit`、`steps`、`cancel`）：模型先调研，把计划保存到 `~/.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。 |
@@ -109,15 +106,16 @@ Pi 自己的版本请求只是被重新绘制，本包的最新版本则来自
 | [`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` 在终端里打印同一份轮次，不用开浏览器，也不启动任何进程。 |
+| [`serve`](./docs/extensions/serve.md) | — | 每个 session 一个 loopback 服务。`/board`、`/browse` 和浏览器里的 plan review 都在它上面挂载路径前缀，而不是各自监听端口，因此一个 session 只有一个端口、一个 chip、一条关闭路径——而第二个 session（peer 会话、另一个 worktree、另一个 Pi）依然有自己的端口。端口由仓库自身的 key 哈希到 `4780`–`5779`，每个项目各有自己的编号，因此收藏的地址在重启后依然有效、无需任何设置；`bytefly.json` 里的 `serve.port` 可以覆盖它；共享 review 只为发起共享的那一个页面借用同一个网段上的一个地址。 |
+| [`board`](./docs/extensions/board.md) | `board`、`/board` | 每个仓库一块共享看板：一张卡片代表一个 feature，在五条车道间移动——`backlog`、`plan`、`execute`、`blocked`、`done`——契约（`goal`、`acceptance`、`scopeOut`）必须写明，并指向 `plan` 的 `write` 动作存进本仓库 plan store 的那份 plan 文件，由 lead（`bytefly.json` 里的 `board.lead`，且不能是卡片持有者）或本人用 `/board approve` 批准——之后才能进入执行，完成的工作同样要经过 `/board review` 抽检才能收尾；`plan` 与 `execute` 受 `bytefly.json` 里的 WIP 上限约束。已完成的卡片会离开看板进入 `archive/`，其注记与落地 commit 仍可读；同一个看板在浏览器里以 **Board** 和 **Team** 两个 tab 实时显示。页面只读——写入只走工具——以看板 lead（`board.lead`，默认 `lead`）的席位对外服务，因此第二个 session 打开的是同一张页面；把卡片交给队友由 `team` 负责，因为只有它能给对端发消息。卡片可以带上优先级、声明自己在等待哪几张卡片。步骤留在 owner 的 plan 和 `todo` 里，卡片就是 feature、它的 owner，以及解释它的历史。Team tab 会把 bus 没有记录的 owner 收成一行，因为只要某张卡片曾归属它，它就会一直是 owner。页面以 `/board` 挂在该项目自身的端口上（由仓库 key 哈希得到），因此收藏的地址重启后依然有效、无需设置；`bytefly.json` 里的 `serve.port` 可以覆盖它。默认关闭：用 `PI_ENABLED_EXTENSIONS=board` 加载。 |
+| [`team`](./docs/extensions/team.md) | `team`、`/team` | 同一块看板上的 lead 轮次。`/team join <label>` 让一个 session 加入团队，lead 打开 `/board` 时则以页面席位之名自动加入；随后 `assign` 把一个 feature 交给运行中的 session，`offer` 交给谁有空谁接——广播而不写卡片，由第一个认领的人拿走——`reclaim` 把卡片收回 Backlog，`claim` 则让 lead 自己接手，之后的 plan 与 contract 交给 `board`。结果会说明谁会因此被叫醒、谁会在下一轮才读到；`/team` 在终端里打印同一份轮次，不用开浏览器，也不启动任何进程。与 `board` 一并默认关闭：用 `PI_ENABLED_EXTENSIONS=board,team` 加载。 |
 | [`context`](./docs/extensions/context.md) | `/context` | 显示上下文窗口的去向 —— 系统提示、工具定义、按角色拆分的对话、注入的笔记 —— 并从报告中触发压缩，给出压缩前后的数字。 |
 
 ### 保护你的工作
 
 | 扩展 | 工具与命令 | 说明 |
 |---|---|---|
-| [`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 工具会跟随，清理时也不会丢弃工作。 |
+| [`worktree`](./docs/extensions/worktree.md) | `worktree`, `/worktree` (screen), `/worktree enter\|exit\|prune`, `--worktree` | 在隔离的 `git worktree` 里、在独立分支上工作（一个工具四个动作：`enter`、`exit`、`list`、`prune`）；内置的 read/write/edit/bash 工具会跟随，清理时也不会丢弃工作。 |
 | [`rewind`](./docs/extensions/rewind.md) | `/rewind`, `/review`, `↺ N` 状态标记 | 在每次提示的首次改动前于 `refs/pi/rewind` 下对仓库生成快照，可恢复代码、对话或两者，并在还原文件前审阅本轮改动。 |
 | [`memory`](./docs/extensions/memory.md) | `memory`, `/memory` | 跨会话的持久笔记，以可人工编辑的 Markdown 保存，注入每次运行，并通过 `/memory` 选择器管理。 |
 
@@ -135,7 +133,7 @@ Pi 自己的版本请求只是被重新绘制，本包的最新版本则来自
 
 | 扩展 | 工具与命令 | 说明 |
 |---|---|---|
-| [`bytefly`](./docs/extensions/bytefly.md) | `/bytefly`（`doctor`、`settings`、`skills`、`update`、`upgrade` 子命令）、`run_doctor` | 可见的那一层：主题化头部配宽度自适应页脚，Pi 工作行上实时显示工具、调用次数与计时，转录中每个工具块以调用行为标题、结果正文挂在其下方。`/bytefly` 可开关扩展与技能，并集中存放精选设置；`/bytefly upgrade` 在确认后通过 Pi 自己的包管理器安装待更新版本；可选的 `notify` 会在一次运行、后台任务或待回答的问题需要你时发出系统通知，Pi 自己的启动更新块也会变成主题化 notice 与头部标记。`bytefly.json` 是每个扩展都会读取的配置文档。 |
+| [`bytefly`](./docs/extensions/bytefly.md) | `/bytefly`（`doctor`、`settings`、`skills`、`update`、`upgrade` 子命令）、`run_doctor` | 可见的那一层：主题化头部配宽度自适应页脚，输入框上边框实时显示 `working` 计数、本次运行的工具数与计时，转录中每个工具块以调用行为标题、结果正文挂在其下方。`/bytefly` 可开关扩展与技能，并集中存放精选设置；`/bytefly upgrade` 在确认后通过 Pi 自己的包管理器安装待更新版本；可选的 `notify` 会在一次运行、后台任务或待回答的问题需要你时发出系统通知，Pi 自己的启动更新块也会变成主题化 notice 与头部标记。`bytefly.json` 是每个扩展都会读取的配置文档。 |
 
 ### 技能
 
@@ -145,7 +143,6 @@ Pi 自己的版本请求只是被重新绘制，本包的最新版本则来自
 |---|---|
 | [`init`](./skills/init/SKILL.md) | 通过内置的交互式访谈和计划审阅，基于仓库证据创建或更新 Pi 实际读取的指令文件（`AGENTS.md`；存在覆盖它的 `AGENTS.override.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) | 按优先级建议接下来的待办——未收尾的工作、已破坏或未兑现的承诺——会话已有工作时基于本次会话，仅当会话为空时才基于代码树；命令后的文字说明问什么、路径说明看哪里。只读，输出带证据和启动命令的简短编号清单。 |
 
 ### 主题
@@ -174,6 +171,16 @@ Pi 自己的版本请求只是被重新绘制，本包的最新版本则来自
 </tr>
 </table>
 
+下面是终端里画出的计划审查，以及本包在浏览器中提供的三个页面：看板、浏览器版计划审查和文件浏览器。
+
+![终端计划审查：Plan Review 标题线、一条说明自上次审查以来有一节已改动的通知、带标题与 ◼/◻ 任务复选框的计划正文、标出当前章节和可见行范围的滚动指示线，以及 Esc/a/r/w、滚动与章节跳转提示](assets/screens/plan.png)
+
+![看板页：带仓库名与实时徽标的工具栏、Board 与 Team 两个标签页、完成数/总数进度、过滤器、按键按钮和主题切换；五个泳道托盘，各带一个点、一个计数和一个折叠控件；卡片带负责人标签、笔记数及其时长、路径提示、一行说明该卡在等什么、一行说明它卡住了哪些卡，以及一行理由，卡片上没有任何按钮](assets/screens/board.png)
+
+![浏览器版计划审查：粘性头部带计划标题、状态标签，以及 Approve & run、Save feedback、Back to Pi 三个动作和一个 Share 动作；侧栏带步骤进度与章节大纲；计划本身是一列有度量宽度的正文，注释栏里放着负责人自己的评论和队友 @priya 的评论](assets/screens/plan-review.png)
+
+![回环文件浏览器：路径过滤器、文件树，以及渲染好的 Markdown 预览](assets/screens/file-browse.png)
+
 ### 工具渲染
 
 每个工具块都按转录中的样子绘制：工具自身的调用行作为标题，结果正文在其下方两列、
@@ -181,13 +188,13 @@ 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、board、team、plan 工具与 worktree 工具](assets/screens/tool-renderings.png)
+<img src="assets/screens/tool-renderings.png" alt="每个工具块的全页参考图：用户铭牌、通知、回合分隔线，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 工具" width="100%">
 
 `bun run screenshot:tools` 重新生成它；`bun run screenshot:tool-pngs` 在
 [`assets/tools/`](./assets/tools) 下为每个工具输出一张图。
 
-准备上手了？[用户指南](./docs/user-guide/) 为每个扩展都准备了分步讲解：
-第一次运行、关键按键，以及屏幕上会出现什么。
+准备上手了？每个扩展在 [`docs/extensions/`](./docs/extensions/) 下的页面开头便说明它做什么，
+以及它对应的按键与命令。
 
 ## 配置
 
@@ -197,7 +204,15 @@ Pi 自己的版本请求只是被重新绘制，本包的最新版本则来自
 [`docs/configuration.md`](./docs/configuration.md) 则给出解析规则、设置界面操作方式，
 以及每个 section 的键、类型、默认值和取值范围。
 
-每个扩展默认都开启。若要在加载整包时排除其中一些，把 `PI_DISABLED_EXTENSIONS`
+几乎所有扩展默认都开启。例外是 `board` 与 `team`：看板和它的 lead 那一半是同一个
+工作流，session 要么在做，要么不做；从不处理看板的 session 不该背着这些工具、命令和页面。
+把 opt-in 扩展名写进 `PI_ENABLED_EXTENSIONS` 就会加载：
+
+```bash
+PI_ENABLED_EXTENSIONS=board,team pi -e .
+```
+
+若要在加载整包时排除一些默认开启的扩展，把 `PI_DISABLED_EXTENSIONS`
 设为一个以逗号或空白分隔的扩展名列表（即 [`extensions/`](./extensions/) 下的目录
 名）：
 
@@ -205,20 +220,20 @@ Pi 自己的版本请求只是被重新绘制，本包的最新版本则来自
 PI_DISABLED_EXTENSIONS=todo,job pi -e .
 ```
 
-名称比较不区分大小写，未知名称会被忽略。这只会阻止工厂注册；若要移除整包，请使用
-Pi 的 `--no-extensions`，或从你的设置中删除该包。
+名称比较不区分大小写，未知名称会被忽略。`PI_ENABLED_EXTENSIONS` 只负责打开 opt-in
+扩展，写在这里的名字不会关掉别的扩展；而 `PI_DISABLED_EXTENSIONS` 仍然优先于它。
+两者都只会阻止工厂注册；若要移除整包，请使用 Pi 的 `--no-extensions`，或从你的设置中
+删除该包。
 
 ## 文档
 
 | 指南 | 内容 |
 |---|---|
-| [用户指南](./docs/user-guide/) | 分章手册：安装、每项功能、设置、故障排查与命令参考。 |
 | [配置](./docs/configuration.md) | 解析规则、设置界面，以及 `bytefly.json` 每个键的默认值与取值范围。 |
 | [架构](./docs/architecture.md) | 目标形态：加载路径、扩展契约、一次回合、状态、分层、长生命周期，以及改动应放在哪里。 |
 | [扩展文档](./docs/extensions/) | 每个扩展一页，以能力表开头：工具与命令面、集成契约，以及设计说明。 |
 | [开发](./docs/development.md) | 本地设置、检查、测试、跨平台注意事项与发布流程。 |
 | [安全](./docs/security.md) | 回环与远程界面的信任边界。 |
-| [路线图](./ROADMAP.md) | 包的下一步方向，按 README 的承诺分组，并列出每条事项的依据。 |
 | [文档索引](./docs/README.md) | 全部文档的地图：各份指南，以及它们背后的深度契约，按读者归类。 |
 
 ## 参与贡献

package/docs/extensions/README.md

@@ -6,29 +6,28 @@ 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) |
+- [`plan`](./plan.md)
+- [`check`](./check.md)
+- [`subagent`](./subagent.md)
+- [`todo`](./todo.md)
+- [`goal`](./goal.md)
+- [`question`](./question.md)
+- [`job`](./job.md)
+- [`watch`](./watch.md)
+- [`session-bus`](./session-bus.md)
+- [`serve`](./serve.md)
+- [`board`](./board.md)
+- [`team`](./team.md)
+- [`context`](./context.md)
+- [`worktree`](./worktree.md)
+- [`rewind`](./rewind.md)
+- [`memory`](./memory.md)
+- [`web-access`](./web-access.md)
+- [`file-browse`](./file-browse.md)
+- [`file-read`](./file-read.md)
+- [`file-open`](./file-open.md)
+- [`wechat`](./wechat.md)
+- [`bytefly`](./bytefly.md)
 
 The template every page follows is
 [`docs/development.md#one-doc-per-extension`](../development.md#one-doc-per-extension).