@gavin-hu/my-pi-agent 0.14.0 → 0.15.0

package/README.md

@@ -8,9 +8,13 @@
 [![built for Pi](https://img.shields.io/badge/built%20for-Pi-5A4FCF)](https://pi.dev)
 
 `my-pi-agent` is a single [Pi](https://pi.dev) package that adds a curated set
-of extensions and themes to the agent you already use — install the pack, turn
+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/).
+
 ![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)
 
 ## Contents
@@ -42,10 +46,10 @@ want the agent to *think first and work safely*:
   documents from inside the session, and answer a WeChat chat through a bridge to
   the live session.
 
-Everything is optional and independently toggleable. Nothing is patched or
-forked: Pi discovers the resources through the `pi` manifest in
-[`package.json`](./package.json), so the package upgrades with Pi like any
-other.
+Everything is optional and independently toggleable. Nothing is forked, and no
+installed Pi file is modified: Pi discovers the resources through the `pi`
+manifest in [`package.json`](./package.json), so the package upgrades with Pi
+like any other.
 
 ## Quick start
 
@@ -55,7 +59,7 @@ Requires a working [Pi](https://pi.dev) installation.
 pi install npm:@gavin-hu/my-pi-agent
 ```
 
-[Getting started](./docs/getting-started.md) has the other sources — git, a
+[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.
 
@@ -69,33 +73,38 @@ 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: bytefly
-  startup TUI, desktop notifications and their delivery method, the proactive
-  health check, the currency and cost precision, the transcript
-  rail glyph, output padding, and the hardware cursor, with `Space`/`Enter` to
-  change a value and `Tab` for Global/Project scope.
+- `/bytefly settings` opens the control center's Settings section: ten groups
+  covering startup, notifications, diagnostics, pricing, transcript, terminal,
+  worktree, snapshots, jobs, and memory, plus a **Theme** row, with
+  `Space`/`Enter` to change a value and `Tab` for Global/Project 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.
-- `/settings` → **Theme** selects a theme.
+- `/bytefly update` re-runs the package update check now and reports the
+  updateable packages, this package's version and release URL, or a skip.
 - `/plan <task>` starts a task in read-only planning mode.
+- `/skill:init` creates or updates `AGENTS.md` through a short built-in interview and a plan you review first.
 
-One thing the pack does on its own: once per interactive session, `bytefly` asks
-npm for the newest published version and marks the header when yours is older.
-Nothing about the session is sent, and `PI_OFFLINE` skips the request;
+One thing the pack does on its own: once per interactive session, `bytefly`
+asks Pi's package manager which configured packages are behind, suppresses Pi's
+own startup update block, and posts one themed notice naming
+`pi update --extensions`; this package's new version also marks the header.
+Nothing about the session is sent, and `PI_OFFLINE` skips the check;
 [`docs/security.md`](./docs/security.md) covers the trust boundaries.
 
 ## What you get
 
-Sixteen extensions, grouped by what you are trying to do, plus two themes. Each
-extension's own `README.md` has the full tool and command surface.
+Seventeen extensions and two packaged skills, grouped by what you are trying to
+do, plus two themes. Each extension's own `README.md` has the full tool and
+command surface.
 
 ### Plan and delegate
 
 | Extension | Tools and commands | What it does |
 |---|---|---|
-| [`plan`](./extensions/plan/) | `enter_plan_mode`, `write_plan`, `exit_plan_mode`, `set_plan_steps`, `/plan`, `--plan` | Read-only planning: the model investigates, saves a plan under `.pi/plans`, and you approve it before anything is written. Review in the TUI, or open it in a browser to leave inline comments. |
-| [`subagent`](./extensions/subagent/) | `subagent` | Delegate a task to a specialist agent (`explorer`, `planner`, `reviewer`, `worker`, `researcher`, `tester`, `debugger`, `documenter`) in its own Pi process — single, parallel, or chained. |
+| [`plan`](./extensions/plan/) | `enter_plan_mode`, `write_plan`, `exit_plan_mode`, `set_plan_steps`, `/plan`, `--plan` | Read-only planning: the model investigates, saves a plan under `.pi/plans`, and you approve it before anything is written. Review in the TUI, or open it in a browser to leave inline comments. 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. |
@@ -106,8 +115,8 @@ extension's own `README.md` has the full tool and command surface.
 
 | Extension | Tools and commands | What it does |
 |---|---|---|
-| [`worktree`](./extensions/worktree/) | `enter_worktree`, `exit_worktree`, `prune_worktrees`, `list_worktrees`, `/worktree*`, `--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`, `↺ N` status chip | Snapshot the repo on every prompt under `refs/pi/rewind` and restore code, conversation, or both. |
+| [`worktree`](./extensions/worktree/) | `enter_worktree`, `exit_worktree`, `prune_worktrees`, `list_worktrees`, `/worktree status|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. |
 
 ### Reach the world
@@ -124,14 +133,26 @@ extension's own `README.md` has the full tool and command surface.
 
 | Extension | Tools and commands | What it does |
 |---|---|---|
-| [`bytefly`](./extensions/bytefly/) | `/bytefly` (with the `doctor` and `settings` 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 holds the curated settings; opt-in `notify` raises OS notifications when a run, a job, or a question needs you. `bytefly.json` is the config document every extension reads. |
+| [`bytefly`](./extensions/bytefly/) | `/bytefly` (with the `doctor`, `settings`, 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 holds the curated settings; opt-in `notify` raises OS notifications when a run, a job, or a question needs you. `bytefly.json` is the config document every extension reads. |
+
+### Skills
+
+Packaged workflows loaded on demand: each skill's name and description are
+advertised to the model, and its instructions load only when the task matches
+(`/skill:<name>` forces one).
+
+| Skill | What it does |
+|---|---|
+| [`init`](./skills/init/SKILL.md) | Creates or updates a project's `AGENTS.md` through a built-in interactive interview and plan review, 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. |
 
 ### Themes
 
 [`bytefly-dark`](./themes/bytefly-dark.json) is a GitHub-inspired dark palette
 and [`bytefly-light`](./themes/bytefly-light.json) its light companion, with
 optional automatic light/dark switching. Installing the pack does not change
-your theme: pick one through `/settings` → **Theme**, or set
+your theme: pick one through `/settings` → **Theme** (or `/bytefly settings` →
+**Theme**), or set
 `"theme": "bytefly-light/bytefly-dark"` for switching. The screenshots in this
 README use `bytefly-dark`.
 
@@ -156,20 +177,23 @@ 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, send_wechat, ask_user_question, 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, the plan tools, and the worktree tools](assets/tool-renderings.png)
 
 `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.
+
 ## 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,
-[`docs/configuration.md`](./docs/configuration.md) indexes the sections, and
-[`docs/references/bytefly-config.md`](./docs/references/bytefly-config.md) lists
-every key with its type, default, and bounds.
+extension. Each extension's `README.md` 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.
 
 Every extension is on by default. To load the pack without some of them, set
 `PI_DISABLED_EXTENSIONS` to a comma- or whitespace-separated list of extension
@@ -187,11 +211,9 @@ stops the factories from registering; to drop the whole package, use Pi's
 
 | Guide | What it covers |
 |---|---|
-| [Getting started](./docs/getting-started.md) | Whether the pack fits, a trial run, install options, verifying the load, first workflows, and removal. |
-| [Extensions](./docs/extensions.md) | The full catalog of every extension and theme. |
-| [Configuration](./docs/configuration.md) | Config-file resolution, the per-extension index, environment variables. |
-| [Configuration reference](./docs/references/bytefly-config.md) | Every `bytefly.json` section and key, with its type, default, and bounds. |
-| [Architecture](./docs/architecture.md) | How the package, its extensions, and `lib/` fit together. |
+| [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. |
 | [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. |

package/README.zh-CN.md

@@ -8,7 +8,10 @@
 [![built for Pi](https://img.shields.io/badge/built%20for-Pi-5A4FCF)](https://pi.dev)
 
 `my-pi-agent` 是一个 [Pi](https://pi.dev) 包，在你已经使用的智能体之上新增一组精选
-扩展和主题 —— 安装整个包，关掉你不需要的部分，其余照常使用 Pi。
+扩展、技能和主题 —— 安装整个包，关掉你不需要的部分，其余照常使用 Pi。
+
+本页是目录与安装说明。要了解某个功能怎么用 —— 按键、命令以及应有的效果 ——
+请先看[用户指南](./docs/user-guide/)。
 
 ![一个运行 Pi TUI 的终端窗口，包含 bytefly 头部、提示行、上下文与已加载扩展、回合分隔线以及状态栏](assets/chrome.png)
 
@@ -37,9 +40,9 @@ Pi 提供一个精简而锐利的内核。这个包是在其之上的一层，
 - **连通网络与文件。** 在会话内搜索、抓取、浏览、打开和读取文档，还可通过桥接
   在微信里直接回答当前会话。
 
-一切都是可选的，且可独立开关。没有任何东西被补丁或分叉：Pi 通过
-[`package.json`](./package.json) 里的 `pi` manifest 发现这些资源，因此该包能像
-其他包一样随 Pi 一起升级。
+一切都是可选的，且可独立开关。没有任何东西被分叉，也没有修改已安装的 Pi 文件：
+Pi 通过 [`package.json`](./package.json) 里的 `pi` manifest 发现这些资源，因此
+该包能像其他包一样随 Pi 一起升级。
 
 ## 快速开始
 
@@ -49,7 +52,7 @@ Pi 提供一个精简而锐利的内核。这个包是在其之上的一层，
 pi install npm:@gavin-hu/my-pi-agent
 ```
 
-[快速开始](./docs/getting-started.md) 介绍其余安装方式——git、固定版本、
+[用户指南](./docs/user-guide/) 介绍其余安装方式——git、固定版本、
 仅项目本地安装，以及不写入任何内容的试用——还有适用性判断、首个工作流和移除方式。
 
 `git` 需在 `PATH` 上，供 [`worktree`](./extensions/worktree/) 与
@@ -61,29 +64,33 @@ Windows、macOS 和 Linux 均可运行，完整检查套件在每个平台上都
 
 - `/bytefly [extension] [refresh]` 打开控制中心的 Extensions 区，列出每个已加载扩展
   及其运行时健康状况，启用或禁用一个扩展，并用 `x` 清除项目级覆盖。
-- `/bytefly settings` 打开控制中心的 Settings 区：bytefly 启动 TUI、桌面通知及其
-  投递方式、主动健康检查、货币与费用精度、转录轨道字形、输出内边距和硬件光标；
-  用 `Space`/`Enter` 修改，用 `Tab` 切换 Global/Project 作用域。
+- `/bytefly settings` 打开控制中心的 Settings 区：十个分组覆盖启动、通知、
+  诊断、计价、转录、终端、worktree、快照、任务与监听器、记忆，并提供 **Theme**
+  行；用 `Space`/`Enter` 修改，用 `Tab` 切换 Global/Project 作用域。
 - `/bytefly doctor [extension] [refresh]` 打印 doctor 报告（`run_doctor` 的文本），
   检查每个已启用扩展在运行时是否具备所需条件。
-- `/settings` → **Theme** 选择主题。
+- `/bytefly update` 立即重跑包更新检查，报告可更新的包、本包版本与 release URL，
+  或跳过原因。
 - `/plan <任务>` 以只读规划模式开始一个任务。
+- `/skill:init` 通过内置的简短访谈和先审阅的计划创建或更新 `AGENTS.md`。
 
-还有一件包会自行做的事：每次交互式会话启动时，`bytefly` 向 npm 询问最新发布
-版本，当你的版本较旧时在头部标出。不会发送任何会话内容，`PI_OFFLINE` 可跳过
-该请求；信任边界见 [`docs/security.md`](./docs/security.md)。
+还有一件包会自行做的事：每次交互式会话启动时，`bytefly` 询问 Pi 的包管理器
+哪些已配置的包有更新，抑制 Pi 自己的启动更新块，并用一个主题化 notice 列出它们
+和 `pi update --extensions`；本包的新版本还会标在头部。不会发送任何会话内容，
+`PI_OFFLINE` 可跳过检查；信任边界见 [`docs/security.md`](./docs/security.md)。
 
 ## 包含内容
 
-十六个扩展，按你想达成的目标分组，外加两个主题。每个扩展自己的 `README.md`
+十七个扩展和两个随包技能，按你想达成的目标分组，外加两个主题。每个扩展自己的 `README.md`
 提供完整的工具与命令说明。
 
 ### 规划与委派
 
 | 扩展 | 工具与命令 | 说明 |
 |---|---|---|
-| [`plan`](./extensions/plan/) | `enter_plan_mode`, `write_plan`, `exit_plan_mode`, `set_plan_steps`, `/plan`, `--plan` | 只读规划：模型先调研，把计划保存到 `.pi/plans` 下，你在写入任何内容前先批准。可在 TUI 中审阅，或在浏览器中打开以留下行内评论。 |
-| [`subagent`](./extensions/subagent/) | `subagent` | 把任务委派给专职智能体（`explorer`、`planner`、`reviewer`、`worker`、`researcher`、`tester`、`debugger`、`documenter`），运行在它自己的 Pi 进程中 —— 单个、并行或链式。 |
+| [`plan`](./extensions/plan/) | `enter_plan_mode`, `write_plan`, `exit_plan_mode`, `set_plan_steps`, `/plan`, `--plan` | 只读规划：模型先调研，把计划保存到 `.pi/plans` 下，你在写入任何内容前先批准。可在 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` | 向你提出一个或多个结构化问题（带标签的选项外加自由填写的“其他”）并等待回答。 |
@@ -94,8 +101,8 @@ Windows、macOS 和 Linux 均可运行，完整检查套件在每个平台上都
 
 | 扩展 | 工具与命令 | 说明 |
 |---|---|---|
-| [`worktree`](./extensions/worktree/) | `enter_worktree`, `exit_worktree`, `prune_worktrees`, `list_worktrees`, `/worktree*`, `--worktree` | 在隔离的 `git worktree` 里、在独立分支上工作；内置的 read/write/edit/bash 工具会跟随，清理时也不会丢弃工作。 |
-| [`rewind`](./extensions/rewind/) | `/rewind`, `↺ N` 状态标记 | 每次提示时在 `refs/pi/rewind` 下对仓库生成快照，可恢复代码、对话或两者。 |
+| [`worktree`](./extensions/worktree/) | `enter_worktree`, `exit_worktree`, `prune_worktrees`, `list_worktrees`, `/worktree status|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` 选择器管理。 |
 
 ### 连通外部世界
@@ -112,13 +119,23 @@ Windows、macOS 和 Linux 均可运行，完整检查套件在每个平台上都
 
 | 扩展 | 工具与命令 | 说明 |
 |---|---|---|
-| [`bytefly`](./extensions/bytefly/) | `/bytefly`（`doctor`、`settings` 子命令）、`run_doctor` | 可见的那一层：主题化头部配宽度自适应页脚，Pi 工作行上实时显示工具、调用次数与计时，转录中每个工具块以调用行为标题、结果正文挂在其下方。`/bytefly` 可开关扩展并集中存放精选设置；可选的 `notify` 会在一次运行、后台任务或待回答的问题需要你时发出系统通知。`bytefly.json` 是每个扩展都会读取的配置文档。 |
+| [`bytefly`](./extensions/bytefly/) | `/bytefly`（`doctor`、`settings`、`update` 子命令）、`run_doctor` | 可见的那一层：主题化头部配宽度自适应页脚，Pi 工作行上实时显示工具、调用次数与计时，转录中每个工具块以调用行为标题、结果正文挂在其下方。`/bytefly` 可开关扩展并集中存放精选设置；可选的 `notify` 会在一次运行、后台任务或待回答的问题需要你时发出系统通知。`bytefly.json` 是每个扩展都会读取的配置文档。 |
+
+### 技能
+
+按需加载的随包工作流：每个技能的名称和描述会提供给模型，只有任务匹配时才加载完整说明（`/skill:<name>` 可强制加载）。
+
+| 技能 | 说明 |
+|---|---|
+| [`init`](./skills/init/SKILL.md) | 基于仓库证据，通过内置的交互式访谈和计划审阅创建或更新项目的 `AGENTS.md`。 |
+| [`refactor`](./skills/refactor/SKILL.md) | 审计项目或路径中的重构机会：重复代码、过大的模块、耦合、结构漂移，以及测试薄弱且改动频繁的代码。返回带证据和验证命令的排序清单；发现阶段只读。 |
 
 ### 主题
 
 [`bytefly-dark`](./themes/bytefly-dark.json) 是 GitHub 风格的深色调色板，
 [`bytefly-light`](./themes/bytefly-light.json) 是其浅色搭档，并支持可选的自动
-浅色/深色切换。安装本包不会改变你的主题：通过 `/settings` → **Theme** 选择，
+浅色/深色切换。安装本包不会改变你的主题：通过 `/settings` → **Theme**（或
+`/bytefly settings` → **Theme**）选择，
 或设置 `"theme": "bytefly-light/bytefly-dark"` 以自动切换。本 README 的截图
 使用 `bytefly-dark`。
 
@@ -147,14 +164,16 @@ Windows、macOS 和 Linux 均可运行，完整检查套件在每个平台上都
 `bun run screenshot:tools` 重新生成它；`bun run screenshot:tool-pngs` 在
 [`assets/tools/`](./assets/tools) 下为每个工具输出一张图。
 
+准备上手了？[用户指南](./docs/user-guide/) 为每个扩展都准备了分步讲解：
+第一次运行、关键按键，以及屏幕上会出现什么。
+
 ## 配置
 
 大多数扩展无需配置。所有设置都在一个共享文档 `bytefly.json` 中，从
 `<agent-dir>/bytefly.json` 读取，并与 `<cwd>/.pi/bytefly.json` 合并（项目优先），
 位于一个以扩展名命名的顶层 section 下。每个扩展的 `README.md` 说明其键位的行为，
-[`docs/configuration.md`](./docs/configuration.md) 为其建立索引，
-[`docs/references/bytefly-config.md`](./docs/references/bytefly-config.md) 逐个列出每个键的
-类型、默认值和取值范围。
+[`docs/configuration.md`](./docs/configuration.md) 则给出解析规则、设置界面操作方式，
+以及每个 section 的键、类型、默认值和取值范围。
 
 每个扩展默认都开启。若要在加载整包时排除其中一些，把 `PI_DISABLED_EXTENSIONS`
 设为一个以逗号或空白分隔的扩展名列表（即 [`extensions/`](./extensions/) 下的目录
@@ -171,11 +190,9 @@ Pi 的 `--no-extensions`，或从你的设置中删除该包。
 
 | 指南 | 内容 |
 |---|---|
-| [快速开始](./docs/getting-started.md) | 是否适合你、试用、安装选项、验证加载、首个工作流、移除。 |
-| [扩展](./docs/extensions.md) | 所有扩展与主题的完整目录。 |
-| [配置](./docs/configuration.md) | 配置文件解析、按扩展索引、环境变量。 |
-| [配置参考](./docs/references/bytefly-config.md) | 列出 `bytefly.json` 的每个 section 与键，包括类型、默认值和取值范围。 |
-| [架构](./docs/architecture.md) | 包、各扩展与 `lib/` 如何协同。 |
+| [用户指南](./docs/user-guide/) | 分章手册：安装、每项功能、设置、故障排查与命令参考。 |
+| [配置](./docs/configuration.md) | 解析规则、设置界面，以及 `bytefly.json` 每个键的默认值与取值范围。 |
+| [架构](./docs/architecture.md) | 加载路径、运行时模型、状态、进程形态，以及新代码应放在哪里。 |
 | [开发](./docs/development.md) | 本地设置、检查、测试、跨平台注意事项与发布流程。 |
 | [安全](./docs/security.md) | 回环与远程界面的信任边界。 |
 | [路线图](./ROADMAP.md) | 包的下一步方向，按 README 的承诺分组，并列出每条事项的依据。 |