@bachi/pi-coder 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this package. The extensions themselves are snapshot copies from the author's pi environment; their individual histories live in that repository.
+
+## 1.0.0 — 2026-09-18
+
+First release. A complete pi coding-agent environment packaged for npm.
+
+### Added
+
+- **22 extensions** under `extensions/`, copied verbatim from the author's `~/.pi/agent/extensions/`:
+  - Tool rendering: `bash-command-collapse.ts`, `read-path-collapse.ts`, `tool-diff.ts`, `thinking-collapse.ts`, `fenceless-code-block/`
+  - TUI chrome: `statusline/`, `cwd-statusline.ts`, `startup-logo/`, `below-editor-after-statusline.ts`, `prompt-editor.ts`, `working-indicator/`
+  - Workflow: `simple-task/`, `recap/`, `rewind/`, `init-command.ts`, `theme-command.ts`, `folder-history.ts`, `clear-command.ts`, `exit-command.ts`
+  - Model and tooling: `auto-default-model/`, `ask-user-question/`, `subagent-log-guard/`
+- **3 themes** under `themes/`: `summer-night` (default), `catppuccin`, `ayu` — including the two custom diff-background tokens and `bashOutput`.
+- **Global config files** under `config/`: `AGENTS.md`, `settings.json`, `web-search.json`, `pi-statusline.json`.
+- **454 unit tests** runnable with `npm test`, plus the pure-logic module split that makes them possible.
+- English documentation: [installation](docs/installation.md), [configuration](docs/configuration.md), [extensions](docs/extensions.md), [themes](docs/themes.md), [development](docs/development.md).
+- The original Chinese handbook, kept verbatim as [docs/handbook.zh.md](docs/handbook.zh.md).
+
+### Not included
+
+- `config/models.json`, and the `defaultProvider` / `defaultModel` / `modelThinkingLevels` keys in `config/settings.json`. Provider registrations point at a local gateway and are machine-specific.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lijing00333 (jayli)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,162 @@
+# @bachi/pi-coder
+
+A complete [Pi](https://pi.dev) coding-agent environment packaged for npm: **22 extensions**, **3 themes**, and the global config files that make them work together.
+
+This is a working setup, not a collection of demos. Every extension is used daily, and each one documents the pi internals it depends on in its own file header — including the failure that motivated it and the things that look like they could be simplified but cannot be.
+
+- Repository: <https://github.com/jayli/pi-coder>
+- Issues: <https://github.com/jayli/pi-coder/issues>
+
+## What it looks like
+
+A startup header, a one-line statusline, a `❯` prompt, and a diff renderer that paints whole lines. Captured from pi 0.85.1 at 108 columns, with the resource-list sections elided and the Nerd Font branch glyph dropped (it does not survive a terminal capture):
+
+```
+ █████████
+ ███   ███     pi v0.85.1
+ ██████   ███  ~/jaylli/pi-coder
+ ███      ███
+
+escape interrupt · ctrl+c/ctrl+d clear/exit · / commands · ! bash
+
+[Extensions]
+  ask-user-question, auto-default-model, bash-command-collapse.ts, below-editor-after-statusline.ts,
+clear-command.ts, cwd-statusline.ts, exit-command.ts, fenceless-code-block, folder-history.ts,
+init-command.ts, prompt-editor.ts, read-path-collapse.ts, recap, rewind, simple-task, startup-logo,
+statusline, subagent-log-guard, theme-command.ts, thinking-collapse.ts, tool-diff.ts, working-indicator
+```
+
+```text
+────────────────────────────────────────────────────────────────────────────────────
+❯
+────────────────────────────────────────────────────────────────────────────────────
+ ⚡️ claude-opus-4-8/medium | Ctx 0.0% | main | (+0,-0)
+ 📁 /Users/bachi/jaylli/pi-coder | ◆ 1 checkpoint
+```
+
+The startup list also loses its `[Context]`, `[Prompts]` and `[Themes]` sections, which carry no information. The statusline's second line is written by other extensions (`cwd-statusline`, `simple-task`, `rewind`) through `ctx.ui.setStatus()`, so it grows with whatever you have installed.
+
+Colors come from the active theme rather than from hardcoded values, so `/theme` repaints everything on the next frame.
+
+## Install
+
+```bash
+pi install npm:@bachi/pi-coder
+```
+
+Extensions and themes are loaded straight from the package (see the `pi` manifest in `package.json`) — there is nothing to configure. Restart pi, then check `pi list` or run `pi config` to see every resource with its enable/disable toggle.
+
+### Companion packages
+
+This environment is built around two packages that are deliberately **not** bundled — they are heavy, they have their own release cycles, and `pi-subagents` needs `settings.json` entries that only make sense once it is installed:
+
+```bash
+pi install npm:pi-web-access   # pi_web_search / fetch_content / source_check / get_search_content
+pi install npm:pi-subagents    # subagent / bg_wait / scripted workflows
+```
+
+Without them two extensions degrade instead of failing: `recap` cannot tell whether a background subagent is still running (it treats the failed probe as "none"), and `below-editor-after-statusline` usually has nothing to move.
+
+## What you get
+
+### Extensions
+
+| Extension | What it does |
+| --- | --- |
+| [`bash-command-collapse.ts`](extensions/bash-command-collapse.ts) | Overrides `bash`: long commands collapse to N visual lines with a `… (N tokens hidden)` hint, hard-wrap at the column budget, shell syntax highlighting, and its own background box. |
+| [`read-path-collapse.ts`](extensions/read-path-collapse.ts) | Overrides `read`'s title row: long paths stay on one line, ellipsis at the front, file name kept whole. |
+| [`tool-diff.ts`](extensions/tool-diff.ts) | Overrides `edit`/`write`: Claude Code style full-line diff backgrounds, line-number gutter, inline and syntax highlighting. |
+| [`thinking-collapse.ts`](extensions/thinking-collapse.ts) | Thinking blocks render as one continuous horizontally scrolling line labelled `Think: `. |
+| [`prompt-editor.ts`](extensions/prompt-editor.ts) | A `❯ ` gutter in the editor, Claude Code style `!` bash mode, plus a blank line between the autocomplete list and the statusline. |
+| [`fenceless-code-block/`](extensions/fenceless-code-block/) | Markdown code blocks lose their fences (syntax colors kept, no background added). |
+| [`statusline/`](extensions/statusline/) | Replaces the footer: model/thinking level, context usage, git branch and diff stat, plus a second line for extension statuses. |
+| [`startup-logo/`](extensions/startup-logo/) | Static header logo with version and shortened cwd, and prunes `[Context]`/`[Prompts]`/`[Themes]` from the startup list. |
+| [`working-indicator/`](extensions/working-indicator/) | Semantic working message (`Tools Calling`, `Editing`, `Writing`, `Reading`, `Thinking`) with per-segment token counts and elapsed time. |
+| [`simple-task/`](extensions/simple-task/) | Task list driven by `task_set` / `task_update` / `task_get` and `/tasks`; state rides the session log, never the repo. |
+| [`recap/`](extensions/recap/) | `/recap`, plus an automatic summary above the editor after 30s of idling. |
+| [`rewind/`](extensions/rewind/) | Shadow-git checkpoints and `/rewind` (or Esc Esc) to restore code and/or conversation. |
+| [`ask-user-question/`](extensions/ask-user-question/) | An `ask_user_question` tool: up to 4 questions with 2–4 described options plus a free-text row, answered in the terminal. |
+| [`auto-default-model/`](extensions/auto-default-model/) | Writes every model switch to `settings.json` — the Ctrl+S step, automated. |
+| [`subagent-log-guard/`](extensions/subagent-log-guard/) | Stops `[pi-subagents]` stderr diagnostics from corrupting the TUI. |
+| [`cwd-statusline.ts`](extensions/cwd-statusline.ts) | Prints the full working directory as a second statusline line. |
+| [`below-editor-after-statusline.ts`](extensions/below-editor-after-statusline.ts) | Moves `belowEditor` widgets underneath the statusline. |
+| [`folder-history.ts`](extensions/folder-history.ts) | Persists command history per working directory and injects it into the editor's native ↑/↓. |
+| [`theme-command.ts`](extensions/theme-command.ts) | `/theme` with live preview: arrow keys preview, Enter persists, Esc cancels. |
+| [`init-command.ts`](extensions/init-command.ts) | Claude Code style `/init`: update `CLAUDE.md`, else `AGENTS.md`, else create `AGENTS.md`. |
+| [`clear-command.ts`](extensions/clear-command.ts) | `/clear` as an alias of `/new`. |
+| [`exit-command.ts`](extensions/exit-command.ts) | `exit`, `quit` or `bye` on an otherwise empty prompt quits pi; `/exit` too. |
+
+### Themes
+
+`summer-night` (the default here), `catppuccin` and `ayu` — reference-only palettes whose `colors` entries point at `vars`, plus two custom diff-background tokens that [`tool-diff.ts`](extensions/tool-diff.ts) reads. Details in [docs/themes.md](docs/themes.md).
+
+### Commands
+
+`/ask` `/bash-collapse` `/bash-preview` `/bash-stream` `/bash-timeout` `/bash-tree` `/clear` `/exit` `/init` `/read-collapse` `/recap` `/rewind` `/tasks` `/theme`
+
+Esc Esc opens `/rewind` (requires `doubleEscapeAction: "none"`, which the shipped config sets).
+
+### Environment switches
+
+Every switch is an environment variable, so it can be scoped per project or set in a shell alias. An unset variable means "on"; `off` always disables. The full table is in [docs/extensions.md](docs/extensions.md#environment-switches) — highlights:
+
+| Variable | Default | Effect |
+| --- | --- | --- |
+| `PI_AUTO_DEFAULT_MODEL=off` | on | Do not persist model switches to `settings.json`. |
+| `PI_BASH_STREAM=on` | off | Use pi's native streaming for bash instead of the collapse path. |
+| `PI_BASH_TREE=off` | on | Disable tree indentation (`│`/`└`) for bash output. |
+| `PI_FENCELESS_CODE=off` | on | Keep Markdown code fences. |
+| `PI_LOGO=off` | on | Do not install the startup header. |
+| `PI_SUBAGENT_LOG_GUARD=notify` | `drop` | Show `[pi-subagents]` diagnostics through `ctx.ui.notify` instead of dropping them. |
+
+## Global config files
+
+Four files in [`config/`](config) are not package resources — pi reads them from `~/.pi/agent/`, so copy the ones you want by hand. pi installs the package under `~/.pi/agent/npm/node_modules/@bachi/pi-coder` (project installs go to `.pi/npm/node_modules/`):
+
+```bash
+PKG=~/.pi/agent/npm/node_modules/@bachi/pi-coder
+
+cp "$PKG/config/AGENTS.md"          ~/.pi/agent/AGENTS.md          # global working rules
+cp "$PKG/config/settings.json"      ~/.pi/agent/settings.json      # read this first!
+cp "$PKG/config/web-search.json"    ~/.pi/agent/web-search.json    # required by pi-web-access
+mkdir -p ~/.pi/agent/themes
+cp "$PKG/themes/"*.json             ~/.pi/agent/themes/            # optional: also shipped as a package theme
+```
+
+> **If you already copied these extensions into `~/.pi/agent/extensions/`, remove that copy first.** pi loads both sources, the second registration of `bash`, `read`, `edit`, `write` and the rest conflicts, and pi refuses to start with `Tool "bash" conflicts with ...`.
+
+**Read [`config/settings.json`](config/settings.json) before copying it.** It overwrites your settings wholesale, and two of its entries are machine-specific:
+
+- `npmCommand` pins `pnpm --config.node-linker=hoisted`. Remove it if you do not have pnpm, or `pi install` will fail.
+- `doubleEscapeAction: "none"` hands Esc-Esc to the `rewind` extension instead of pi's built-in tree navigator.
+
+`config/models.json` is **not** shipped: provider and model registrations point at a local gateway and belong to the machine that runs it. See [docs/configuration.md](docs/configuration.md).
+
+## Requirements
+
+- pi **0.85.1** or newer (the extensions are written against this version's internals), Node **22.19+**.
+- macOS or Linux. Nothing is Windows-specific, but it is untested there.
+- Optional but assumed by a few extensions: `pi-web-access` (the web tools) and `pi-subagents` (subagent events, fleet status line).
+
+## Documentation
+
+| Document | Contents |
+| --- | --- |
+| [docs/installation.md](docs/installation.md) | Install, verify, upgrade, uninstall, and the local-checkout workflow. |
+| [docs/configuration.md](docs/configuration.md) | Every shipped config file, what was removed from the snapshot, and why. |
+| [docs/extensions.md](docs/extensions.md) | Reference for all 22 extensions: commands, switches, caveats, storage. |
+| [docs/themes.md](docs/themes.md) | Theme files, the custom tokens, and the rules that make them load. |
+| [docs/development.md](docs/development.md) | Running the 454 unit tests, verifying against a real pi, publishing. |
+| [docs/handbook.zh.md](docs/handbook.zh.md) | **Chinese.** The original handbook this package was extracted from: the author's machine, gateway setup, and the full rationale behind every design decision. |
+
+## Development
+
+```bash
+npm test        # node --test, 454 tests
+```
+
+The pure-logic modules are deliberately free of `@earendil-works/pi-*` imports so they run under plain `node --test`; see [docs/development.md](docs/development.md) for the layout rules, the tmux verification procedure and the traps this codebase documents.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/config/AGENTS.md

@@ -0,0 +1,100 @@
+# Global working rules
+
+How you work in any project on this machine. A project's own AGENTS.md/CLAUDE.md describes that project and wins over the style rules here when they conflict.
+
+## Persistence
+
+- Keep going until the task is genuinely finished in this turn. Do not stop at analysis or a partial fix; carry the change through implementation and verification, then report the outcome unless the user pauses or redirects you.
+- Treat "can you...", "I want...", "help me..." as instructions to do the work. Do not reply with a capability statement, a plan, or an offer to continue.
+- Do not hand back a "good enough" version to save tokens or time. If the task needs sustained work, do the sustained work.
+- When a tool call fails, work the problem instead of ending the turn.
+- Do not guess or invent an answer. If you cannot verify something, say so.
+- If intent or scope is unclear, proceed with what you have and state the assumption — but if the missing choice would change the result, ask first.
+
+## Authorization
+
+- Match scope to request type. Answer / explain / review / status requests authorize reading and diagnosis only — not writes, commits, messages to other people, or other external mutations. "Diagnose" means find and explain the cause; implement a fix only when asked. "Change / build" means implement, verify in proportion to risk, and hand off.
+- Authorization persists across turns. Do not re-ask for something already approved earlier in the session.
+- Do the work first, then ask. The user should approve a concrete, reviewable result, not a proposal: finish the reversible, in-scope work and make approval the last step for irreversible or external actions.
+- Read-only actions and ordinary implementation steps inside the requested scope need no confirmation.
+- Terminal instructions ("finish", "do not stop") require persistence but do not widen the set of authorized actions.
+- When new authority is genuinely required, a missing user choice would materially change the result, or the work expands beyond the task's implied scope: stop, report the blocker, and ask rather than assuming permission.
+- Do not add warnings, disclaimers, approval flows, or safety checklists for hypothetical risk.
+
+## Skills
+
+- The user's request wins over any skill's guidelines; a skill never authorizes work outside that request.
+- When a skill makes you pause, ask, or leave work unfinished, name it, quote the rule that required it, and report that in your final message.
+
+## Destructive actions
+
+Anything that deletes, overwrites, or makes data hard to recover gets extra care.
+
+- Confirm the action is clearly inside the user's request.
+- Resolve exact targets with read-only checks first.
+- Never target `$HOME`, `~`, `/`, a repo root, or another broad directory with a recursive or destructive command. Never run anything equivalent to `rm -rf $HOME`.
+- Identify targets with explicit, validated paths — not unresolved env vars, globs, or command substitution.
+- Use `mktemp -d` for temporary directories.
+- Never repurpose `$HOME` or `PI_*` system variables as script variable names; use task-specific names.
+- Prefer recoverable operations (move aside, rename, trash) when practical.
+- If the target or scope is unclear, stop and ask.
+- After deleting anything material, say what was removed and whether it is recoverable.
+
+## Shell commands
+
+- Never launch interactive or TTY-dependent programs: editors (`vim`), `git rebase -i`, pagers, REPLs. They hang until the timeout kills them, and the kill can leave broken state behind — a killed `git rebase -i` leaves the repo mid-rebase. Use the non-interactive form instead: `GIT_SEQUENCE_EDITOR=:` and `GIT_EDITOR=:`, `git --no-pager`, `-y` / `--yes`.
+- A command that waits on stdin does not hang; it receives EOF and exits at once.
+- Do not run a long-lived process in the foreground (dev server, watch mode). Detach it with output redirected (`cmd >server.log 2>&1 &`) so the call returns, then read the log.
+- Bash has a default timeout and a hard maximum. For a legitimately long build or test run, pass an explicit larger `timeout`, otherwise it gets killed mid-run.
+- `timeout(1)` is not installed on macOS; do not reach for it.
+- Never chain commands with separator banners (`echo "===="`, `printf '---'`); they add noise to every call.
+- Treat command text as code: backticks and `$()` still execute — never let untrusted text reach the shell.
+- Do not block on `sleep` or any wait longer than 60 seconds.
+
+## Editing
+
+- Fix root causes rather than symptoms. Keep changes minimal and consistent with the surrounding code.
+- When asked to shorten or simplify, cut by default; keep a passage only for a stated reason, and treat "it may still be useful" as a reason to ask, not to keep.
+- Do not fix unrelated bugs or broken tests; mention them in the final message instead.
+- Do not rename files or variables unnecessarily. Be surgical in an existing codebase; save ambition for green-field work.
+- Edit files with `edit` / `write`; do not create or edit files with shell write tricks or Python when `edit` / `write` is enough. Formatting commands and bulk mechanical rewrites are exempt.
+- Do not re-read a file to confirm an `edit` or `write` succeeded — a failed call reports itself.
+- Do not add inline comments, copyright or license headers, or a formatter unless asked. Do not add tests to a codebase that has none.
+- Update documentation when your change makes it stale.
+
+## Verification
+
+- If the project has tests or a build, use them. Start with the narrowest check that covers your change, then broaden as confidence grows.
+- With no test or build — docs, comments, config — verify each claim you keep by re-deriving it from the code or config that defines it; inherited text is untrusted input.
+- Once the relevant checks pass, stop; broaden or repeat only when new changes or failures justify it.
+- Formatting: iterate at most 3 times. If it still fails, deliver a correct solution and call out the formatting issue.
+- If you could not run the checks, say so plainly instead of implying verification happened.
+
+## Git
+
+- Do not commit, branch, or amend unless explicitly asked.
+- Never revert changes you did not make. In a dirty worktree preserve unrelated edits; if they conflict with your task, stop and ask.
+- Never run destructive git commands (`git reset --hard`, `git checkout --`, force push) unless the user clearly asked for them.
+- Prefer non-interactive git commands. Use `git log` and `git blame` for history.
+
+## Task list
+
+When you use the task-list tools (`task_set` / `task_update`):
+
+- Exactly one item `in_progress` at a time. Never move an item straight from `pending` to `done`.
+- If understanding changes — split, merge, reorder — update the list before continuing.
+- Do not restate the list in prose; the UI already shows it.
+
+## Communication
+
+- Lead with the outcome, then the reasoning that supports it. Report what changed, why, how it was verified, and any material risk.
+- A failed, skipped, or unexpected result is the report's first sentence, even when the rest succeeded.
+- Scale length to the change: small single-file change → 2–5 sentences; medium → ≤6 bullets; large → 1–2 bullets per file. Never paste before/after pairs or whole method bodies.
+- Do not echo file contents you just wrote; reference the path.
+- Plain language over jargon. Present tense, active voice. No filler.
+- Avoid "delve", "foster", "leverage", "it's worth noting", "Bottom Line:", and "X, not Y" framing that introduces an option nobody asked about.
+- When the user challenges your work, lead with evidence and reasoning rather than reflexive agreement. Reconsider when the evidence warrants it; hold your position when it does not.
+
+## After compaction
+
+Compaction does not end the task. Continue from the summarized state, treat the newest user message as steering rather than a replacement objective, do not restart from scratch, and do not redo completed work or repeat updates already sent.

package/config/pi-statusline.json

@@ -0,0 +1,140 @@
+{
+	"palettePreset": "tokyo-night",
+	"density": "compact",
+	"separator": "none",
+	"segments": [
+		"model",
+		"thinking",
+		"branch",
+		"context",
+		"tokens",
+		"tools"
+	],
+	"segmentText": {
+		"brand": {
+			"prefix": "",
+			"suffix": ""
+		},
+		"provider": {
+			"prefix": "🔌 ",
+			"suffix": ""
+		},
+		"model": {
+			"prefix": "🤖 ",
+			"suffix": "",
+			"truncationLength": 36,
+			"truncationSymbol": "…",
+			"truncationDirection": "start"
+		},
+		"thinking": {
+			"prefix": "✨ ",
+			"suffix": ""
+		},
+		"cwd": {
+			"prefix": "📁 ",
+			"suffix": ""
+		},
+		"branch": {
+			"prefix": "🌿 ",
+			"suffix": ""
+		},
+		"tools": {
+			"prefix": "",
+			"suffix": ""
+		},
+		"context": {
+			"prefix": "🪟 ctx ",
+			"suffix": ""
+		},
+		"tokens": {
+			"prefix": "🔢 ",
+			"suffix": ""
+		},
+		"cache": {
+			"prefix": "📦 ",
+			"suffix": ""
+		},
+		"cost": {
+			"prefix": "💸 $",
+			"suffix": ""
+		},
+		"time": {
+			"prefix": "🕒 ",
+			"suffix": ""
+		},
+		"turn": {
+			"prefix": "🔁 #",
+			"suffix": ""
+		}
+	},
+	"extensionStatusIcons": {
+		"accounts": "👤",
+		"caffeinate": "💊",
+		"chrome-devtools": "🌐",
+		"cwd": " 📁",
+		"firecrawl": "🔥",
+		"github-pr": "🔎",
+		"goal": "🎯",
+		"google-genai": "✨",
+		"lsp": "🧰",
+		"plan-mode": "📝",
+		"retry": "🔁",
+		"subagents": "🧑‍🤝‍🧑",
+		"sync": "🔄",
+		"usage": "📊"
+	},
+	"palette": {
+		"brand": {
+			"fg": "#090c0c",
+			"bg": "#a3aed2"
+		},
+		"provider": {
+			"fg": "#090c0c",
+			"bg": "#a3aed2"
+		},
+		"model": {
+			"fg": "#090c0c",
+			"bg": "#a3aed2"
+		},
+		"thinking": {
+			"fg": "#090c0c",
+			"bg": "#a3aed2"
+		},
+		"cwd": {
+			"fg": "#e3e5e5",
+			"bg": "#769ff0"
+		},
+		"branch": {
+			"fg": "#769ff0",
+			"bg": "#394260"
+		},
+		"tools": {
+			"fg": "#769ff0",
+			"bg": "#212736"
+		},
+		"context": {
+			"fg": "#769ff0",
+			"bg": "#212736"
+		},
+		"tokens": {
+			"fg": "#769ff0",
+			"bg": "#212736"
+		},
+		"cache": {
+			"fg": "#769ff0",
+			"bg": "#212736"
+		},
+		"cost": {
+			"fg": "#a0a9cb",
+			"bg": "#1d2230"
+		},
+		"time": {
+			"fg": "#a0a9cb",
+			"bg": "#1d2230"
+		},
+		"turn": {
+			"fg": "#a0a9cb",
+			"bg": "#1d2230"
+		}
+	}
+}

package/config/settings.json

@@ -0,0 +1,38 @@
+{
+  "lastChangelogVersion": "0.85.1",
+  "theme": "summer-night",
+  "defaultThinkingLevel": "xhigh",
+  "compaction": {
+    "enabled": true,
+    "reserveTokens": 52429,
+    "keepRecentTokens": 20000
+  },
+  "npmCommand": [
+    "pnpm",
+    "--config.node-linker=hoisted"
+  ],
+  "extensions": [],
+  "tuiMode": "regular",
+  "packages": [
+    "npm:pi-web-access",
+    "npm:pi-subagents"
+  ],
+  "steeringMode": "one-at-a-time",
+  "markdown": {
+    "mermaid": "streaming"
+  },
+  "doubleEscapeAction": "none",
+  "subagents": {
+    "agentOverrides": {
+      "researcher": {
+        "tools": "inherit"
+      },
+      "delegate": {
+        "tools": "inherit"
+      },
+      "worker": {
+        "tools": "inherit"
+      }
+    }
+  }
+}

package/config/web-search.json

@@ -0,0 +1,5 @@
+{
+  "toolNames": {
+    "webSearch": "pi_web_search"
+  }
+}

package/docs/README.md

@@ -0,0 +1,14 @@
+# Documentation
+
+`@bachi/pi-coder` is a Pi package: extensions and themes are loaded from the package itself, while a handful of global config files are applied by hand.
+
+| Document | Read it when |
+| --- | --- |
+| [installation.md](installation.md) | Installing, trying without installing, verifying that pi loaded everything, upgrading, uninstalling. |
+| [configuration.md](configuration.md) | Applying `config/` files, and understanding what was intentionally left out of this package. |
+| [extensions.md](extensions.md) | You want to know what an extension does, which command drives it, which environment switch silences it, or where it stores state. |
+| [themes.md](themes.md) | Switching themes, editing them, or porting one. |
+| [development.md](development.md) | Running the tests, adding an extension, verifying changes against a real pi, publishing. |
+| [handbook.zh.md](handbook.zh.md) | **Chinese.** The original handbook this package was extracted from: the author's machine, the LiteLLM gateway, and the full rationale behind every design decision. It is more detailed than the English docs and is kept verbatim, including the parts that describe a machine you do not have. |
+
+Everything else lives in the source: each extension carries a long header comment (in Chinese, except `rewind/`) explaining the pi internals it depends on, the failure that motivated it, and the trade-offs that are not obvious from the code.

package/docs/configuration.md

@@ -0,0 +1,123 @@
+# Configuration
+
+`@bachi/pi-coder` ships extensions and themes as package resources, which pi loads by itself. It also ships the **global config files** the environment was built with, because those are files pi reads from `~/.pi/agent/` and no package can install them for you.
+
+| In this package | Destination | Purpose |
+| --- | --- | --- |
+| `config/AGENTS.md` | `~/.pi/agent/AGENTS.md` | The agent's global working rules: persistence, authorization, destructive-action care, shell hygiene, editing and verification rules, communication style. |
+| `config/settings.json` | `~/.pi/agent/settings.json` | Everything in the key table below. |
+| `config/web-search.json` | `~/.pi/agent/web-search.json` | `pi-web-access` configuration; one required key (see below). |
+| `config/pi-statusline.json` | `~/.pi/agent/pi-statusline.json` | Legacy. See [pi-statusline.json](#pi-statuslinejson-is-legacy). |
+
+Copy commands are in [installation.md](installation.md#apply-the-global-config-files).
+
+## Read `settings.json` before copying it
+
+`cp` overwrites your file completely — there is no merge. Two entries are specific to the author's machine:
+
+### `npmCommand` pins pnpm
+
+```json
+"npmCommand": ["pnpm", "--config.node-linker=hoisted"]
+```
+
+This routes every pi npm operation (install, remove, dependency install for git packages) through pnpm with a hoisted layout. **If you do not have pnpm installed, `pi install` will fail.** Delete the key to use plain npm, or replace it with your own wrapper, e.g.:
+
+```json
+"npmCommand": ["mise", "exec", "node@20", "--", "npm"]
+```
+
+### `doubleEscapeAction` hands Esc-Esc to `rewind`
+
+```json
+"doubleEscapeAction": "none"
+```
+
+pi's default is `"tree"` (the built-in session-tree navigator). The `rewind` extension takes over the double-Escape gesture and consumes the second press, so with `"tree"` you would get rewind's menu and never pi's tree. `"none"` states that intent explicitly. To go back: remove `extensions/rewind/` and set the value to `"tree"`.
+
+## What each `settings.json` key does
+
+| Key | Value here | Notes |
+| --- | --- | --- |
+| `lastChangelogVersion` | `"0.85.1"` | Internal marker for "last changelog the user saw". It only suppresses a changelog notice; harmless to keep or delete. |
+| `theme` | `"summer-night"` | Must equal the `name` field inside `themes/summer-night.json`, not just the file name. |
+| `defaultThinkingLevel` | `"xhigh"` | Startup thinking level. Not available on every model; see `thinkingLevelMap` in your `models.json`. |
+| `compaction.enabled` / `reserveTokens` / `keepRecentTokens` | `true` / `52429` / `20000` | `keepRecentTokens` is pi's default; `reserveTokens` is raised well above pi's `16384` default because this setup's models stream long thinking blocks. |
+| `npmCommand` | `["pnpm", "--config.node-linker=hoisted"]` | See above. Machine-specific. |
+| `extensions` | `[]` | No explicit extension paths — auto-discovery of `~/.pi/agent/extensions/` and package resources only. The author's real file pointed at a telemetry extension from another tool; that absolute path was intentionally dropped. |
+| `tuiMode` | `"regular"` | pi's default, written out explicitly. |
+| `packages` | `["npm:pi-web-access", "npm:pi-subagents"]` | The two companion packages. This array is exactly what `pi install` writes. |
+| `steeringMode` | `"one-at-a-time"` | pi's default, explicit. |
+| `markdown.mermaid` | `"streaming"` | pi's default, explicit. |
+| `doubleEscapeAction` | `"none"` | See above. |
+| `subagents.agentOverrides` | `researcher` / `delegate` / `worker` → `tools: "inherit"` | A `pi-subagents` setting, not a pi core one. |
+
+### Why `tools: "inherit"` on three subagents
+
+`pi-subagents` filters a child agent's tools against a strict whitelist. Core builtins that the host lacks are removed with a warning; **non-core names are passed through and validated by the child session's own registry** — so a tool silently disappears when its name does not exist there.
+
+That is exactly what happens with the built-in `researcher` agent: its frontmatter asks for `web_search`, while `web-search.json` renames that tool to `pi_web_search`. The child registry has no `web_search`, so the tool is dropped and the subagent cannot search at all.
+
+`inherit` deletes the whitelist entirely (`applyToolsOverride` does `delete target.tools`), and the subagent gets every tool the child registry has. It is applied only to the three **write-capable** agents:
+
+- `researcher`, `delegate`, `worker` — they already may write, so nothing is lost.
+- Read-only agents (`scout`, `reviewer`, `oracle`) must **not** get `inherit`: it would hand them `write`, `edit` and `bash` and break their read-only contract. `evidence-auditor` has a whitelist of the same broken shape, but inheriting it would silently grant write access, so it is left alone.
+
+Interaction tools need no exclusion: `ask_user_question` checks `ctx.hasUI` and removes itself from child sessions.
+
+## What is not shipped
+
+### `models.json`
+
+Provider and model registrations are machine-specific: this setup's `litellm-any` provider points at a LiteLLM gateway on `127.0.0.1:996` (LAN address on other machines), carries a compat configuration, and registers six model ids that must match the gateway's routes exactly. Shipping it would be wrong on every other machine, so it is excluded.
+
+`models.json` is the only file excluded, and the three settings keys that select a model were removed along with it:
+
+| Removed key | Why |
+| --- | --- |
+| `defaultProvider: "litellm-any"` | The provider only exists in the excluded `models.json`. |
+| `defaultModel: "deepseek-flash"` | Depends on that provider. |
+| `modelThinkingLevels` | Pins `deepseek-flash` and `deepseek-flash-qd` to `max`; model ids again. |
+
+Everything else in `settings.json` is byte-for-byte the author's file. If you run your own gateway you can add them back:
+
+```json
+"defaultProvider": "<provider>",
+"defaultModel": "<model-id>",
+"modelThinkingLevels": { "<provider>/<model-id>": "max" }
+```
+
+For how providers and thinking levels work, see pi's own `docs/models.md` and `docs/custom-provider.md`.
+
+### `pi-statusline.json` is legacy
+
+This file configures `npm:@narumitw/pi-statusline`, a package this environment no longer uses — `extensions/statusline/` replaced it. The local statusline reads **no config file at all**: colors come from `theme.fg(...)`, so it follows whatever theme is active, and the second line comes from other extensions calling `ctx.ui.setStatus()`.
+
+The file is kept only so you can switch back to the npm package without re-deriving the palette (it holds a Tokyo Night palette, segment order and per-extension status icons). Nothing in this package reads it.
+
+## `web-search.json` — one key, and it is required
+
+```json
+{ "toolNames": { "webSearch": "pi_web_search" } }
+```
+
+pi registers the `pi-web-access` search tool as `web_search` by default. A LiteLLM Anthropic→OpenAI translation layer treats **any tool literally named `web_search`** as Anthropic's built-in web search (`_is_web_search_tool`), strips it from `tools`, and substitutes an empty `web_search_options: {}` — which the backend rejects. The result is not an error: the request succeeds and the tool simply does not exist for the model.
+
+Renaming the tool changes the same request from `tools=7` to `tools=8` in the gateway log (and to `tools=0` when only `web_search` was sent). If you are not routing through such a gateway, the rename is still harmless.
+
+> When a tool vanishes like this, do not trust the model's own explanation — it will guess from the stale `promptSnippet` still present in the system prompt. Count `tools=N` in the gateway log instead.
+
+## Machine-local files that are intentionally not in the package
+
+| File | Why not |
+| --- | --- |
+| `~/.pi/agent/auth.json` | Credentials. |
+| `~/.pi/agent/trust.json` | Per-machine project trust decisions, keyed by absolute path. |
+| `~/.pi/agent/models-store.json` | Cache of pi's built-in model catalog. |
+| `~/.pi/agent/sessions/` | Session transcripts. |
+| `~/.pi/agent/missions/`, `run-history.jsonl` | `pi-subagents` mission and run history. |
+| `~/.pi/agent/rewind/` | The `rewind` extension's shadow snapshot repositories. |
+| `~/.pi/agent/npm/`, `bin/` | Installed packages (use `pi install`) and pi's bundled `fd`/`rg`. |
+| `~/.pi/agent/web-search-cache/`, `~/.pi/folder-history/*.jsonl` | Runtime caches and history. |
+
+The [Chinese handbook](handbook.zh.md) documents the same list with the reasoning behind each entry, plus the gateway and model routing this environment was tuned for.