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

package/README.md

@@ -43,8 +43,8 @@ want the agent to *think first and work safely*:
 - **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
-  documents from inside the session, and answer a WeChat chat through a bridge to
-  the live session.
+  documents and spreadsheets from inside the session, and answer a WeChat chat
+  through a bridge to the live session.
 
 Everything is optional and independently toggleable. Nothing is forked, and no
 installed Pi file is modified: Pi discovers the resources through the `pi`
@@ -73,10 +73,10 @@ 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: 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 settings` opens the control center's Settings section: one flat list
+  of the fourteen 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 doctor [extension] [refresh]` prints the doctor report —
   `run_doctor`'s text — and checks that each enabled extension has what it needs
   at runtime.
@@ -94,9 +94,8 @@ Nothing about the session is sent, and `PI_OFFLINE` skips the check;
 
 ## What you get
 
-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.
+18 extensions, 3 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.
 
 ### Plan and delegate
 
@@ -110,6 +109,7 @@ command surface.
 | [`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. |
+| [`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. |
 
 ### Keep your work safe
 
@@ -124,8 +124,8 @@ command surface.
 | 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 and a fuzzy quick-open palette. |
-| [`document`](./extensions/document/) | `read_doc` | Extract text from a local PDF, DOCX, DOC, ODT, RTF, or XLSX in process, paged. |
+| [`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, and live status for a page left open. |
+| [`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. |
 
@@ -145,6 +145,7 @@ advertised to the model, and its instructions load only when the task matches
 |---|---|
 | [`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. |
+| [`changelog`](./skills/changelog/SKILL.md) | Drafts the candidate bullet before implementation, records one user-visible bullet in the same commit, audits commits since the last tag for missing or weak entries, and curates a release section from the project's own rules. |
 
 ### Themes
 

package/README.zh-CN.md

@@ -37,7 +37,7 @@ Pi 提供一个精简而锐利的内核。这个包是在其之上的一层，
 - **绝不搞乱检出区。** 隔离只需一条命令：任务切到自己分支的 `git worktree` 中，
   每次提示还会生成快照，因此一次糟糕的回合只需一个 `/rewind` 就能回退。
 - **跨会话记忆。** 持久笔记以纯 Markdown 保存，可读、可改、可纳入版本控制。
-- **连通网络与文件。** 在会话内搜索、抓取、浏览、打开和读取文档，还可通过桥接
+- **连通网络与文件。** 在会话内搜索、抓取、浏览、打开和读取文档与表格，还可通过桥接
   在微信里直接回答当前会话。
 
 一切都是可选的，且可独立开关。没有任何东西被分叉，也没有修改已安装的 Pi 文件：
@@ -64,9 +64,9 @@ Windows、macOS 和 Linux 均可运行，完整检查套件在每个平台上都
 
 - `/bytefly [extension] [refresh]` 打开控制中心的 Extensions 区，列出每个已加载扩展
   及其运行时健康状况，启用或禁用一个扩展，并用 `x` 清除项目级覆盖。
-- `/bytefly settings` 打开控制中心的 Settings 区：十个分组覆盖启动、通知、
-  诊断、计价、转录、终端、worktree、快照、任务与监听器、记忆，并提供 **Theme**
-  行；用 `Space`/`Enter` 修改，用 `Tab` 切换 Global/Project 作用域。
+- `/bytefly settings` 打开控制中心的 Settings 区：一次会话会改动的十四项设置排成
+  一列，值紧跟在名称之后；用 `Space`/`Enter` 修改，用 `Tab` 切换 Global/Project
+  作用域。其余键都是 `bytefly.json` 编辑，见配置参考。
 - `/bytefly doctor [extension] [refresh]` 打印 doctor 报告（`run_doctor` 的文本），
   检查每个已启用扩展在运行时是否具备所需条件。
 - `/bytefly update` 立即重跑包更新检查，报告可更新的包、本包版本与 release URL，
@@ -81,7 +81,7 @@ Windows、macOS 和 Linux 均可运行，完整检查套件在每个平台上都
 
 ## 包含内容
 
-十七个扩展和两个随包技能，按你想达成的目标分组，外加两个主题。每个扩展自己的 `README.md`
+18 个扩展、3 个随包技能，以及 2 个主题，按你想达成的目标分组。每个扩展自己的 `README.md`
 提供完整的工具与命令说明。
 
 ### 规划与委派
@@ -96,6 +96,7 @@ Windows、macOS 和 Linux 均可运行，完整检查套件在每个平台上都
 | [`question`](./extensions/question/) | `ask_user_question` | 向你提出一个或多个结构化问题（带标签的选项外加自由填写的“其他”）并等待回答。 |
 | [`job`](./extensions/job/) | `job`, `/jobs` | 在后台运行长时 shell 命令；查看日志、等待或结束它们。 |
 | [`watch`](./extensions/watch/) | `watch`, `/watch` | 跟踪文件或命令输出，按模式匹配行，并提醒你或把匹配的行交给智能体。 |
+| [`context`](./extensions/context/) | `/context` | 显示上下文窗口的去向 —— 系统提示、工具定义、按角色拆分的对话、注入的笔记 —— 并从报告中触发压缩，给出压缩前后的数字。 |
 
 ### 保护你的工作
 
@@ -110,8 +111,8 @@ Windows、macOS 和 Linux 均可运行，完整检查套件在每个平台上都
 | 扩展 | 工具与命令 | 说明 |
 |---|---|---|
 | [`web-access`](./extensions/web-access/) | `web_search`, `web_fetch` | 搜索网络（默认无密钥的 DuckDuckGo，可选 SearXNG 或 Brave），并把页面抓取为可读文本，支持分页、`find`、逐跳 SSRF 检查以及可选的 PDF 支持。 |
-| [`file-browse`](./extensions/file-browse/) | `/browse` | 启动一个以工作目录为根的本地回环、只读文件浏览器，带 Markdown 预览和模糊快速打开面板。 |
-| [`document`](./extensions/document/) | `read_doc` | 在进程内从本地 PDF、DOCX、DOC、ODT、RTF 或 XLSX 提取文本，支持分页。 |
+| [`file-browse`](./extensions/file-browse/) | `/browse` | 启动一个以工作目录为根的本地回环、只读文件浏览器，带 Markdown 预览、模糊快速打开面板，以及为常开页面提供的实时状态。 |
+| [`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 把微信聊天桥接到实时会话；入站文本、图片和文件会变成回合。 |
 
@@ -129,6 +130,7 @@ Windows、macOS 和 Linux 均可运行，完整检查套件在每个平台上都
 |---|---|
 | [`init`](./skills/init/SKILL.md) | 基于仓库证据，通过内置的交互式访谈和计划审阅创建或更新项目的 `AGENTS.md`。 |
 | [`refactor`](./skills/refactor/SKILL.md) | 审计项目或路径中的重构机会：重复代码、过大的模块、耦合、结构漂移，以及测试薄弱且改动频繁的代码。返回带证据和验证命令的排序清单；发现阶段只读。 |
+| [`changelog`](./skills/changelog/SKILL.md) | 实现前先起草候选条目，实施后在同一次提交中记录一条用户可见的变更，审计上一个 tag 以来缺失或薄弱的条目，并按项目自己的规则整理发布段落。 |
 
 ### 主题
 

package/extensions/bytefly/README.md

@@ -217,7 +217,10 @@ job · 2 background jobs finished
 ```
 
 The rail is painted by the notice's worst severity, so a failure reads red at the
-edge like an errored tool result.
+edge like an errored tool result, and the headline's title takes the notice's own
+severity — a warning reads yellow where its sentence is, while an `info` or `ok`
+notice stays body text. A row's label stays body text too: its severity is the
+glyph it hangs on, so one failing row never tints the rest of the list.
 
 `job` and `watch` post one when a background job finishes or a watched line
 matches, so the report the model reads is visible too. `doctor` posts one when a
@@ -336,7 +339,7 @@ failed read is silent and not cached, so the next session tries again; see
 | Command | What it does |
 |---|---|
 | `/bytefly [extension] [refresh]` | Open the control center on Extensions. In `tui` it mounts a docked list; every other mode prints the grouped listing, or one extension's full findings when named. |
-| `/bytefly settings` | Open the control center on Settings. Outside `tui` it prints the grouped settings listing with each row's value. |
+| `/bytefly settings` | Open the control center on Settings. Outside `tui` it prints one `Label: Value` line per setting. |
 | `/bytefly doctor [extension] [refresh]` | Print the doctor report. Outside `tui` it prints `run_doctor`'s text for every extension, or one named extension's findings; in `tui` it mounts the same docked screen. |
 | `/bytefly update` | Re-run the package update check now, ignoring the cache window, and report what it found — the updateable packages, this package's version and release URL when known, `PI_OFFLINE`, or an unreadable list. It resolves no packages and probes no extension. |
 
@@ -355,7 +358,7 @@ print the grouped listing with a per-row health suffix and the headline, or that
 extension's full findings when one is named. In `tui` the screen opens on the
 session's cached report and probes on the first Extensions view; the text modes
 probe before they print. `/bytefly settings` prints the
-grouped settings listing with each row's value outside `tui`; it does not
+flat settings listing with each row's value outside `tui`; it does not
 resolve packages or probe the doctor. The
 proactive session-start check posts a transcript notice through the shared
 `my-pi-agent/notice` renderer rather than a transient notification, and is
@@ -499,7 +502,7 @@ it with its own rates for the models they match:
 For example, DeepSeek flash at `¥2` in and `¥8` out per million, with the
 published peak windows and `offPeakMultiplier: 0.5`, prices a 1M-in + 1M-out
 turn at `¥10.00` at peak and `¥5.00` off-peak. That example is worked end to end
-in [`footer/price/price.test.ts`](./footer/price/price.test.ts), which also prices the built-in
+in [`footer/footer.test.ts`](./footer/footer.test.ts), which also prices the built-in
 table with no config file at all.
 
 ## Content and colors
@@ -642,92 +645,59 @@ installs or fetches a package.
   without leaving the session.
 
 **Settings.** The second section uses the same frame and the same `Tab` scope
-switch, with its own cursor. It lists twenty-nine preferences in ten groups:
+switch, with its own cursor. It is the shortlist a session changes: fourteen
+preferences on one flat line each, the value beside its label, and no group
+headings. The whole list fits a 24-row terminal, and the frame stops growing
+there however tall the terminal is.
 
 ```
 bytefly ──────────────────────────────────────────────────────────────
-  Extensions · Settings                           Global · 29 settings
-
-  Startup (1)
-❯ ◻ Bytefly startup TUI                                            Off
-  Notifications (7)
-  ◻ Desktop notifications                                          Off
-  ◼ Turn finished                                                   On
-  ◼ Needs input                                                     On
-  ◼ Job finished                                                    On
-  ◼ Watcher matched                                                 On
-    Delivery method                                               Auto
-    Notification title                                              Pi
-  Diagnostics (2)
-  ◼ Proactive health check                                          On
-    Probe timeout                                                 2000
-  Pricing (3)
-    Currency                                                    CNY (¥)
-    Cost decimals                                                    2
-    Session budget                                                   0
-  Transcript (3)
-    Rail glyph                                                       ╎
-    Achieved goal                                                  Hide
-    Output padding                                                   1
-  Terminal (2)
-    Theme                                                       system
-  ◻ Hardware cursor                                                Off
-  Worktree (4)
-    ◼ Fetch remote                                                 On
-    Base ref                                                    Fresh
-    Branch prefix                                          worktree-
-    Prune after (days)                                             7
-  Snapshots (3)
-    ◼ Automatic snapshots                                          On
-    Snapshots kept                                               20
-    ◼ Safety snapshot                                               On
-  Jobs and watchers (3)
-    ◻ Wake when a job finishes                                     Off
-    ◻ Keep jobs after exit                                         Off
-    ◻ Wake on a match                                              Off
-  Memory (1)
-    ◼ Inject notes                                                  On
+  Extensions · Settings                           Global · 14 settings
+
+❯ ◻ Bytefly startup TUI  Off
+  ◼ Theme  system
+  ◻ Desktop notifications  Off
+  ◼ Turn finished  On
+  ◼ Needs input  On
+  ◼ Job finished  On
+  ◼ Watcher matched  On
+    Delivery method  Auto
+  ◻ Wake when a job finishes  Off
+  ◻ Wake on a match  Off
+  ◼ Automatic snapshots  On
+  ◼ Proactive health check  On
+    Currency  CNY (¥)
+    Session budget  0
+
   Bytefly startup TUI — Pi setting
   Use bytefly's startup header in place of Pi's startup TUI.
   Default · ~/.pi/agent/settings.json
 
-  Esc close · ←/→ · Space change · Tab scope · u reset · J JSON · [ ] group
+  Esc close · ←/→ · Space change · Tab scope · u reset · J JSON · ↑/↓ select
 ```
 
-| Group | Row | Source | Values |
-|---|---|---|---|
-| Startup | Bytefly startup TUI | Pi `settings.json` (`quietStartup`) | Off, On |
-| Notifications | Desktop notifications | `notify.enabled` | Off, On |
-| Notifications | Turn finished | `notify.turnFinished` | Off, On |
-| Notifications | Needs input | `notify.needsInput` | Off, On |
-| Notifications | Job finished | `notify.jobFinished` | Off, On |
-| Notifications | Watcher matched | `notify.matchFound` | Off, On |
-| Notifications | Delivery method | `notify.method` | Auto, OSC 777, OSC 99, Windows toast, macOS, Linux |
-| Notifications | Notification title | `notify.title` | Text, up to 40 characters |
-| Diagnostics | Proactive health check | `doctor.proactive` | Off, On |
-| Diagnostics | Probe timeout | `doctor.timeoutMs` | Number, 100–30000 ms |
-| Pricing | Currency | `price.currency.code` | CNY, USD |
-| Pricing | Cost decimals | `price.currency.decimals` | 0, 1, 2, 3, 4 |
-| Pricing | Session budget | `price.budget` | Number, `0` = off |
-| Transcript | Rail glyph | `chrome.rail` | Text, exactly one column |
-| Transcript | Achieved goal | `goal.achieved` | Show, Hide |
-| Transcript | Output padding | Pi `settings.json` | 0, 1 |
-| Terminal | Theme | Pi `settings.json` (`theme`) | `system`, `bytefly-dark`, `bytefly-light` |
-| Terminal | Hardware cursor | Pi `settings.json` | Off, On |
-| Worktree | Base ref | `worktree.baseRef` | Fresh, Head |
-| Worktree | Branch prefix | `worktree.branchPrefix` | Text, trimmed, required |
-| Worktree | Fetch remote | `worktree.fetchRemote` | Off, On |
-| Worktree | Prune after (days) | `worktree.pruneAfterDays` | Number, 0–3650 |
-| Snapshots | Automatic snapshots | `rewind.autoSnapshots` | Off, On |
-| Snapshots | Snapshots kept | `rewind.max` | Number, 0–1000 |
-| Snapshots | Safety snapshot | `rewind.safetySnapshot` | Off, On |
-| Jobs and watchers | Wake when a job finishes | `job.wakeOnFinish` | Off, On |
-| Jobs and watchers | Keep jobs after exit | `job.detachedByDefault` | Off, On |
-| Jobs and watchers | Wake on a match | `watch.wakeOnMatch` | Off, On |
-| Memory | Inject notes | `memory.inject` | Off, On |
-
-Choosing **Currency** also writes that currency's default precision. Both rows
-stay editable afterwards, so the footer follows the explicit values.
+<img src="../../assets/bytefly-settings.png" alt="The /bytefly Settings section: one flat list of fourteen preferences with each value beside its label, the `Global · 14 settings` counts, and a three-row detail pane naming the focused row's source, description, and file" width="100%">
+
+| Row | Source | Values |
+|---|---|---|
+| Bytefly startup TUI | Pi `settings.json` (`quietStartup`) | Off, On |
+| Theme | Pi `settings.json` (`theme`) | `system`, `bytefly-dark`, `bytefly-light` |
+| Desktop notifications | `notify.enabled` | Off, On |
+| Turn finished | `notify.turnFinished` | Off, On |
+| Needs input | `notify.needsInput` | Off, On |
+| Job finished | `notify.jobFinished` | Off, On |
+| Watcher matched | `notify.matchFound` | Off, On |
+| Delivery method | `notify.method` | Auto, OSC 777, OSC 99, Windows toast, macOS, Linux |
+| Wake when a job finishes | `job.wakeOnFinish` | Off, On |
+| Wake on a match | `watch.wakeOnMatch` | Off, On |
+| Automatic snapshots | `rewind.autoSnapshots` | Off, On |
+| Proactive health check | `doctor.proactive` | Off, On |
+| Currency | `price.currency.code` | CNY, USD |
+| Session budget | `price.budget` | Number, `0` = off |
+
+Choosing **Currency** also writes that currency's default precision
+(`price.currency.decimals`). Both stay editable in `bytefly.json` afterwards, so
+the footer follows the explicit values.
 
 The **Theme** row lists `system` first, then the palettes this package ships,
 `bytefly-dark` and `bytefly-light`; it cycles no further, so a bytefly screen
@@ -739,24 +709,34 @@ and is replaced by the next choice here, so manage those in Pi's `/settings` →
 **Theme**.
 
 `Space` (or `Enter`) changes the focused row: a boolean toggles, an enum cycles
-forward, and a text row opens an inline editor on its value — the notification
-title, the probe timeout, the branch prefix, and the rail glyph. `u` deletes the
-focused row's key so its default applies again (`Already at its default.` when
-nothing is stored in that scope; an inherited Project value says so instead),
-`J` swaps the detail pane for the focused row's whole section as the active
-scope stores it — the only view of the keys this screen leaves to JSON — and
-`[` / `]` jump to the previous or next group. The detail pane names
-the source, describes the preference, and shows
-where the value comes from — `Global · ~/.pi/agent/bytefly.json`, `Project ·
+forward, and the one text row — **Session budget** — opens an inline editor on its
+amount. `u` deletes the focused row's key so its default applies again (`Already
+at its default.` when nothing is stored in that scope; an inherited Project value
+says so instead), and `J` swaps the detail pane for the focused row's whole
+section as the active scope stores it — the only view of the keys this screen
+leaves to JSON. The detail pane names the source, describes the preference, and
+shows where the value comes from — `Global · ~/.pi/agent/bytefly.json`, `Project ·
 .pi/bytefly.json`, `Inherited from Global · ~/.pi/agent/bytefly.json`, or
 `Default · <the active scope's file>`; an app row names the personal
 `settings.json`. A successful change marks the screen `Saved · reload to apply`
 — even when the terminal is too short for the detail body — and closing offers
 the same reload confirm as an extension toggle.
 
-Six of the ten `bytefly.json` sections belong to other extensions. The screen
-cannot import their normalizers, so it reports the leaf as the file states it and
-declares the loader's default; `test/settings-coverage.test.ts` holds the
+The list is capped at fourteen rows so the screen keeps fitting a 24-row
+terminal: adding a setting means removing one (`panel/panel.test.ts` holds the
+ceiling). Everything else stays in `bytefly.json` — the tuning numbers, the
+cosmetic labels, and the Pi preferences Pi's own `/settings` owns — and
+`test/settings-coverage.test.ts` keeps the split honest: every loader key is
+either a row or a declared JSON-only edit with the reason it left. Four
+`bytefly.json` sections therefore have no row at all (`chrome`, `goal`,
+`worktree`, `memory`), as do `notify.title`, `doctor.timeoutMs`,
+`price.currency.decimals`, `rewind.max`, `rewind.safetySnapshot`, and
+`job.detachedByDefault` inside sections that do. Each is documented in
+[`docs/configuration.md`](../../docs/configuration.md).
+
+Three of the six sections belong to other extensions (`rewind`, `job`, and
+`watch`). The screen cannot import their normalizers, so it reports the leaf as
+the file states it and declares the loader's default; the same test holds the
 catalogue to every loader's defaults and bounds in both directions.
 
 **Bytefly startup TUI** is the one row whose label differs from the Pi key it
@@ -767,31 +747,28 @@ with `true` or `false`.
 
 App rows are **Global only**: Pi's setters for them write the personal
 `settings.json`, and only resource paths have public project setters. Project
-scope therefore lists the twenty-five `bytefly.json` rows and a
+scope therefore lists the twelve `bytefly.json` rows and a
 `App settings are Global only.` note rather than promising a write that cannot
 happen. A `bytefly.json` row writes one leaf in the selected scope (a depth-1
-key, or a nested one such as `price.currency.decimals`) through a per-key
-writer, so every sibling key, section, `$schema`, and `version` is preserved. A
-malformed document is refused with a notice instead of overwritten, and `u`
-removes that one leaf through the same writer's `unsetConfigValueAt`.
+key, or a nested one such as `price.currency.code`) through a per-key writer, so
+every sibling key, section, `$schema`, and `version` is preserved. A malformed
+document is refused with a notice instead of overwritten, and `u` removes that
+one leaf through the same writer's `unsetConfigValueAt`.
 
-The non-`tui` form prints the headline, the groups, and `Label: Value` rows:
+The non-`tui` form prints the headline and one `Label: Value` row per line, in
+screen order:
 
 ```
-bytefly: Settings · Global · 29 settings
-
-Startup (1)
+bytefly: Settings · Global · 14 settings
   Bytefly startup TUI: Off
-
-Notifications (7)
+  Theme: system
   Desktop notifications: Off
   Turn finished: On
   Needs input: On
   Job finished: On
   Watcher matched: On
   Delivery method: Auto
-  Notification title: Pi
-...
+  ...
 ```
 
 The doctor side probes every declared extension and reports each check as `ok`,
@@ -1004,12 +981,17 @@ command.
 - **Project overrides of app settings are not shown.** App rows read the
   personal file; a `.pi/settings.json` override still wins at runtime, and
   `pi config` is the place to manage it.
-- **Arrays and tables stay JSON.** A row is one boolean, enum, string, or number.
-  `doctor.skip` (an array), the `rates` table, and `price.peak` (a nested object)
-  are still `bytefly.json` edits; every scalar preference has a row.
-- **A custom rail glyph must be one column.** The editor refuses anything else,
+- **The list is a shortlist, not the whole document.** A row is one boolean,
+  enum, string, or number; the tuning numbers, the labels, and the Pi
+  preferences `/settings` owns stay in their files, and the catalogue is capped
+  at fourteen rows so the screen fits a 24-row terminal. `doctor.skip` (an
+  array), the `rates` table, and `price.peak` (a nested object) could never be a
+  row; the rest are declared JSON-only with their reason in
+  `test/settings-coverage.test.ts`.
+- **The rail glyph is typed in `bytefly.json`.** It must be exactly one column,
   because a two-column glyph would push every railed body one cell right; the
-  former four-glyph menu is now the description's example list.
+  loader drops anything else, and the former four-glyph menu is the
+  configuration reference's example list.
 - **`doctor`, `settings`, and `update` are reserved first arguments.**
   `/bytefly doctor` always selects the report, so an extension literally named
   `doctor` cannot be narrowed to by name; `settings` and `update` are reserved
@@ -1134,9 +1116,9 @@ rather than showing a wrong value.
 | Header | `ctx.ui.setHeader` with a custom component, replacing Pi's built-in header; installed only when `ctx.mode === "tui"` and `pi.getSettings().quietStartup === true` (the **Bytefly startup TUI** row). `false`, `"header"`, and unset call `setHeader(undefined)`, leaving Pi's built-in header in place. The nameplate insets by Pi's `outputPad` (read through `pi.getSettings()`), so it sits on the transcript margin, and the help hangs one body indent inside it. The mark and text are drawn from the active theme's tokens, the help keys resolve live through `keyText`, and the mark falls back to a wordmark on Apple Terminal (`isAppleTerminalSession`), mirroring Pi's built-in. The factory reads `tui.terminal.rows` on every render, so the height ladder in `header/config.ts` sheds help groups and then the leading blank row as the terminal shortens (unknown height keeps the full header). The chrome version gains `↑<latest>` from the `UpdateSource`, and `registerHeader` returns a `refresh()` handle that re-installs the last context's header when that value arrives. |
 | Footer | `ctx.ui.setFooter` with a custom component, replacing Pi's built-in footer; installed only when `ctx.mode === "tui"`. |
 | User message | `pi.registerMarkdownTransformer` puts a two-row `You` nameplate (the label over a full-width rule) above each user message; one padded level-2 heading carries the accent through `mdHeading` for both rows, and the shipped themes set `userMessageBg` to the terminal default, so the block has no fill. Pi renders the result as Markdown, so the surface adds no component or color of its own. |
-| Notice | `registerMessageRenderer(NOTICE_TYPE)` draws every shared transcript notice at the margin from its `details`; the headline stays at the margin and its rows hang from the transcript rail, painted by the notice's worst severity, whose glyph comes from the shared `RailSource`. `job` and `watch` post one when their work settles, and `doctor` posts one at `session_start` for a missing hard requirement. The type and shape come from `lib/notice.ts`. A message without `details` falls back to Pi's default custom-message box. |
+| Notice | `registerMessageRenderer(NOTICE_TYPE)` draws every shared transcript notice at the margin from its `details`; the headline stays at the margin with its title painted by the notice's own severity, and its rows hang from the transcript rail, painted by the notice's worst severity, whose glyph comes from the shared `RailSource`. `job` and `watch` post one when their work settles, and `doctor` posts one at `session_start` for a missing hard requirement. The type and shape come from `lib/notice.ts`. A message without `details` falls back to Pi's default custom-message box. |
 | Tool blocks | `registerToolRenderer` returns, for every tool, `renderShell: "self"`; `renderCall` leaves the tool's own first line as the block's headline (a shell prompt shown as the tool name, its command repainted in the body colour, and a primary subject demoted to the body colour) and indents the rest of the call two columns under it, `renderResult` indents its body the same and leads it with the status-coloured rail, and each wraps the tool's own renderer (or a generic fallback). `edit` and `write` carry their result on the call body, so that body is railed too. |
-| Screen command | `pi.registerCommand("bytefly")` takes `[doctor] [settings] [extension] [refresh]`: `tui` mounts a dock screen via `ctx.ui.custom()` with the rails suppressed; other modes print through `ctx.ui.notify()` — the grouped listing, `run_doctor`'s report for `doctor`, or the grouped settings listing with values for `settings`. A named extension is checked against the discovered set before any probe. Tab completes the subcommands, extension names after `doctor`, and `refresh`; `/bytefly settings` rejects a name. |
+| Screen command | `pi.registerCommand("bytefly")` takes `[doctor] [settings] [extension] [refresh]`: `tui` mounts a dock screen via `ctx.ui.custom()` with the rails suppressed; other modes print through `ctx.ui.notify()` — the grouped listing, `run_doctor`'s report for `doctor`, or the flat settings listing with values for `settings`. A named extension is checked against the discovered set before any probe. Tab completes the subcommands, extension names after `doctor`, and `refresh`; `/bytefly settings` rejects a name. |
 | Turn separator | `registerEntryRenderer("bytefly-separator")` draws each stored receipt; `agent_start` opens it, top-level `tool_execution_start`/`tool_execution_end` count tools and failures, and `agent_settled` appends `pi.appendEntry("bytefly-separator", { turn, durationMs, tools, failures, aborted })` in `tui` mode only. The receipt fields are omitted when no `agent_start` was seen, so an older or partially observed entry stays `{ turn }`. |
 | Working line | `turn_start` starts a 1s tick that drives `ctx.ui.setWorkingMessage` in `tui` mode; before a tool runs the message is `Working… Ns`, and each top-level `tool_execution_start` repaints it as `tool · N tools · Ns` (nested calls carrying `parentToolCallId` are skipped). `agent_end` restores Pi's default and cancels the tick (also on `session_shutdown`). No config file and no persisted state; the count lives in the register's closure. |
 | Notifications | `agent_settled` (skipped when aborted), `ui_prompt_start` only while `agent_start`…`agent_settled` marks a run active, and `my-pi-agent/job-finished` on `pi.events`; the `notify` section of `bytefly.json` gates each. Delivery writes an OSC 777/99 sequence to stdout or spawns `osascript`, `notify-send`, or `powershell.exe`. The bus subscription is created in `session_start` and released in `session_shutdown`, and the `job` extension never imports bytefly. |
@@ -1344,7 +1326,7 @@ rather than showing a wrong value.
   a third layer.** An extension cannot import another extension's modules, so
   the only legal home for a shared prerequisite table is `lib/requirements.ts`;
   the report itself is a pure function of the probe results.
-- **The install hint has one home.** `document` and `web-access` format their
+- **The install hint has one home.** `file-read` and `web-access` format their
   tool errors from the same `REQUIREMENTS` entries `doctor` prints, so a user
   reads the same command whether a tool failed or the report named it.
 - **Settings are a curated table, not a schema walker.** The rows cover every
@@ -1456,8 +1438,8 @@ columns, gauge), so the look follows the active theme.
 | `working/register.ts` | Starts the tick on `turn_start`, tracks top-level tools on `tool_execution_start`, and cancels on `agent_end`/`session_shutdown`. |
 | `panel/types.ts` | `PanelSection` (`extensions` | `settings`), `PanelRow`, and `PanelModel`, the merged row model. |
 | `panel/join.ts` | The item/report union with the unambiguous-name health rule and unique row keys, groups, and ordering. |
-| `panel/format.ts` | Non-TUI text: the extension headline and grouped listing with a per-row health suffix, plus the section segments, the Settings counts/headline, and the grouped Settings listing. |
-| `panel/settings.ts` | The curated Settings catalogue: descriptors, snapshot views and origins, value cycling, stored-value mapping, validation, and grouping, plus the per-section readers that resolve a row's leaf over the global and project documents. |
+| `panel/format.ts` | Non-TUI text: the extension headline and grouped listing with a per-row health suffix, plus the section segments, the Settings counts/headline, and the flat Settings listing. |
+| `panel/settings.ts` | The curated Settings catalogue: the fourteen descriptors in screen order, snapshot views and origins, value cycling, stored-value mapping, validation, plus the per-section readers that resolve a row's leaf over the global and project documents. |
 | `panel/settings-runtime.ts` | The Settings runtime: snapshot cache, scope guards, app setters, per-leaf `bytefly.json` writes, dirty state, and change listeners. |
 | `panel/themes.ts` | Which themes the Theme row offers: the host's resolved list narrowed to the palettes under this package's `themes/`, identified by directory rather than name. |
 | `panel/tui.ts` | `PanelComponent`, the two-section dock screen (Extensions list and Settings list) and its section composition; the editing key map is `tui/editing.ts` and the shared frame is `tui/frame.ts`. |

package/extensions/bytefly/notice/component.ts

@@ -7,7 +7,9 @@
  * — so it goes through `sanitizeLine` before it reaches the terminal, and every
  * line is clipped to the width it is given. The rail is painted by the notice's
  * worst severity, so a failure reads red at the edge like an errored tool
- * result; the `source · title` headline stays at the margin.
+ * result, and the headline's title is painted by the notice's own severity, so a
+ * warning reads yellow where its sentence is; the source name stays at the
+ * margin and a row's label stays body text behind its glyph.
  */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
@@ -65,16 +67,16 @@ export function noticeLines(
 	glyph = DEFAULT_RAIL_GLYPH,
 ): string[] {
 	const w = Math.max(1, width);
+	const fallback = knownSeverity(details.severity, "info");
 	const sep = paint(theme, NOTICE_CONFIG.detailRole, SEPARATORS.item);
 	const source = paint(theme, NOTICE_CONFIG.sourceRole, sanitizeLine(details.source));
-	const title = paint(theme, NOTICE_CONFIG.titleRole, sanitizeLine(details.title));
+	const title = paint(theme, NOTICE_CONFIG.titleRoles[fallback], sanitizeLine(details.title));
 	const items = details.items ?? [];
 	const shown = items.slice(0, NOTICE_CONFIG.maxItems);
-	const fallback = knownSeverity(details.severity, "info");
 	const gap = " ".repeat(GLYPH_GAP);
 
 	const rows = shown.map((item) => {
-		const label = paint(theme, NOTICE_CONFIG.titleRole, sanitizeLine(item.label));
+		const label = paint(theme, NOTICE_CONFIG.rowRole, sanitizeLine(item.label));
 		const detail = item.detail ? `${sep}${paint(theme, NOTICE_CONFIG.detailRole, sanitizeLine(item.detail))}` : "";
 		return `${severityGlyph(theme, severityOf(item, fallback))}${gap}${label}${detail}`;
 	});

package/extensions/bytefly/notice/config.ts

@@ -6,6 +6,10 @@
  * glyph. The glyphs come from the shared vocabulary, the roles from the shared
  * rail map, and the rail glyph from the `chrome` config, so a notice reads like
  * the tool results around it.
+ *
+ * Severity reaches two surfaces: the rail (the block's worst severity) and the
+ * headline's title (the notice's own). A row carries no colour of its own, so a
+ * notice reporting one success and one failure stays readable as a list.
  */
 
 import type { NoticeSeverity } from "../../../lib/notice.ts";
@@ -16,8 +20,18 @@ import { RAIL_ROLES } from "../chrome.ts";
 export const NOTICE_CONFIG = {
 	/** Role for the source name at the head of the block. */
 	sourceRole: "accent" as TuiRole,
-	/** Role for the headline's title text and each row's label. */
-	titleRole: "label" as TuiRole,
+	/**
+	 * Role for the headline's title, keyed by the notice's own severity: an alert
+	 * reads in colour where the sentence is, a routine notice stays body text.
+	 */
+	titleRoles: {
+		info: "label",
+		ok: "label",
+		warn: "warn",
+		bad: "bad",
+	} as Record<NoticeSeverity, TuiRole>,
+	/** Role for each row's label; a row states its severity with its glyph. */
+	rowRole: "label" as TuiRole,
 	/** Role for the `·` separators and each row's trailing detail. */
 	detailRole: "faint" as TuiRole,
 	/** Width-1 glyph per severity, from the shared vocabulary. */

package/extensions/bytefly/panel/format.ts

@@ -18,7 +18,7 @@ import { sanitizeLine } from "../../../lib/format.ts";
 import { GLYPHS } from "../../../lib/tui/glyphs.ts";
 import type { TuiRole } from "../../../lib/tui/tokens.ts";
 import { reportSeverity, reportSummary, severityGlyphChar, severityRole } from "../doctor/format.ts";
-import { groupViews, type SettingView } from "./settings.ts";
+import type { SettingView } from "./settings.ts";
 import type { PanelModel, PanelRow, PanelSection } from "./types.ts";
 
 /** The settings scope the screen shows. */
@@ -125,15 +125,10 @@ export function formatSettingsHeadline(count: number): string {
 	return `bytefly: Settings · Global · ${count} settings`;
 }
 
-/** The grouped Settings listing for non-TUI modes. */
+/** The Settings listing for non-TUI modes, one row per line, in screen order. */
 export function formatSettingsListing(views: readonly SettingView[]): string {
 	const lines = [formatSettingsHeadline(views.length)];
-	for (const group of groupViews(views)) {
-		lines.push("", `${group.label} (${group.views.length})`);
-		for (const view of group.views) {
-			lines.push(`  ${sanitizeLine(view.label)}: ${sanitizeLine(view.valueLabel)}`);
-		}
-	}
+	for (const view of views) lines.push(`  ${sanitizeLine(view.label)}: ${sanitizeLine(view.valueLabel)}`);
 	return lines.join("\n");
 }
 

package/extensions/bytefly/panel/join.ts

@@ -20,7 +20,7 @@
 
 import { basename, dirname } from "node:path";
 import type { ExtensionReport } from "../../../lib/requirements.ts";
-import { buildEntries } from "../picker/resources.ts";
+import { buildEntries, resourceKey } from "../picker/resources.ts";
 import type { ResourceItem } from "../picker/types.ts";
 import type { PanelGroup, PanelModel, PanelRow } from "./types.ts";
 
@@ -29,11 +29,6 @@ export function extensionName(path: string): string {
 	return basename(dirname(path));
 }
 
-/** Unique identity of a resolved resource, independent of the directory name. */
-export function resourceKey(item: ResourceItem): string {
-	return `${item.metadata.source}:${item.path}`;
-}
-
 /** Row key for a report that has no resolved extension item. */
 function reportKey(name: string): string {
 	return `report:${name}`;