@bachi/pi-coder 1.0.0

package/docs/development.md

@@ -0,0 +1,177 @@
+# Development
+
+## Layout rules pi enforces
+
+These come from pi's extension discovery and they decide where a file may live:
+
+| Path | Loaded as an extension? |
+| --- | --- |
+| `extensions/*.ts`, `extensions/*.js` | **Yes** — top-level files only. |
+| `extensions/<dir>/index.ts` or `index.js` | **Yes**. |
+| `extensions/<dir>/*.ts` without an `index` | No. Helper modules, imported by other extensions. |
+| `extensions/<dir>/*.test.ts` | No — only the directory's `index.ts` is loaded. |
+| `extensions/*.test.ts` (top level) | **Yes** — pi would try to load it. Never put tests at the top level. |
+
+`thinking-collapse/`, `tool-diff/` and `prompt-editor/` are the three helper-only directories here: `thinking-collapse.ts`, `tool-diff.ts` and `prompt-editor.ts` import them, and pi never loads them directly.
+
+Two consequences worth remembering:
+
+- `recap/index.ts` imports `../simple-task/gap.ts` across directories. Both must ship together.
+- `package.json`'s `pi.extensions: ["./extensions"]` resolves a directory with exactly these rules, so the manifest and the convention directory behave identically.
+
+## Tests
+
+```bash
+npm test        # node --test — 454 tests, ~72 s
+```
+
+The pure-logic modules are written so this works: they do not import `@earendil-works/pi-*` at all, take injected dependencies instead (a `widthOf` function, an `exec` function, a minimal theme interface), and are duck-typed against structural interfaces. That is why `thinking-collapse/window.ts`, `statusline/line.ts`, `tool-diff/title-row.ts`, `rewind/checkpoints.ts`, `prompt-editor/bash-prompt.ts` and the rest can run under plain `node --test`.
+
+One test file goes the other way: [`prompt-editor/render.test.ts`](../extensions/prompt-editor/render.test.ts) loads the **real** extension through pi's own loader and asserts the `!` bash-mode render contract line by line and column by column, with only the surroundings faked (a `tui` that has just `terminal.rows` and `requestRender()`, an identity `borderColor`, keybindings that never match). It locates pi's library entry by reading the `# cmd-shim-target=` line out of the `pi` shim, and it **skips** — rather than failing or faking a pass — when pi cannot be resolved, because the copy under `~/.pi/agent/npm` is often an empty shell after `pi update --extensions`. Point it at a real entry with `PI_TEST_PI_ENTRY=/path/to/index.js`.
+
+**Tests passing is not enough.** pi loads `.ts` with its own loader, and a construct node accepts can still fail there:
+
+> A single invalid annotation (`readonly (readonly 0 | 1)[][]`) left 22 unit tests green while pi raised `ParseError` and refused to load the whole extension.
+
+So every change ends with a real pi start. The cheapest reliable procedure is below.
+
+## Running your checkout against a real pi
+
+The extensions are already in this package, so a plain `pi -e ./path` **collides with any copy in `~/.pi/agent/extensions/`** and aborts:
+
+```
+Error: Failed to load extension ".../extensions/bash-command-collapse.ts":
+  Tool "bash" conflicts with .../pi-coder/extensions/bash-command-collapse.ts
+Hint: Start without extensions using "pi -ne".
+```
+
+Isolate the run instead — a scratch agent directory has no global extensions, so only the checkout loads:
+
+```bash
+PI_CODING_AGENT_DIR=$(mktemp -d) pi -e /absolute/path/to/pi-coder
+```
+
+Then check that all 22 loaded by reading the startup list:
+
+```
+[Extensions]
+  ask-user-question, auto-default-model, bash-command-collapse.ts, ... working-indicator
+```
+
+`/reload` re-reads the checkout, so the loop is: edit → `/reload` → look. That works for `pi -e` runs as well as for an installed package; you do not need to restart pi for extension edits. `settings.json` and `AGENTS.md` are read once at startup, so those do need a restart.
+
+For scripted checks, run pi inside tmux and grep the pane rather than trusting a single screenshot:
+
+```bash
+tmux new-session -d -s pi-check -x 200 -y 50 \
+  "PI_CODING_AGENT_DIR=$(mktemp -d) pi -e $PWD; sleep 60"
+sleep 15
+tmux capture-pane -p -t pi-check | grep -i "failed to load\|parseerror"
+tmux kill-session -t pi-check
+```
+
+## Traps this codebase already paid for
+
+Everything below is documented because it cost real debugging time. The full reasoning is in the file headers named next to each item.
+
+- **A hidden column still accepts the cursor.** `prompt-editor` hides the `!` of bash mode, but `Editor` keeps the cursor column in private state with no public setter, so the extension calls `setCursorCol(1)` directly and degrades to "the cursor stays at column 0" if pi ever renames it — a cosmetic regression only. Letting the cursor sit on the hidden column writes `x!ls` into the text, at which point pi decides it is no longer bash mode.
+- **A `ctx` captured before a session replacement goes stale**, and reading `ctx.ui` throws `This extension ctx is stale after session replacement or reload`. The throw happens when you read the property, before any widget `render()` runs, so a `try/catch` inside `render()` cannot catch it. A timer that outlives the session takes the host process down with it (`exit=1`). `simple-task/` and `working-indicator/` therefore all three: catch inside the callback and stop the timer, wrap every `ctx.ui` access, and stop timers in `session_shutdown`.
+- **A throwing `renderCall` is silently swallowed** and replaced by `createCallFallback()`: something disappears from the UI and nothing is logged.
+- **Tool registration is first-registration-wins per name.** A second extension registering `bash` is ignored without a warning — which is why everything that shapes `bash` rendering lives in one file.
+- **`keyHint` and `keyText` must not be imported from the package root.** In the bundled CLI, `@earendil-works/pi-coding-agent` is aliased to a different module instance, so the extension gets another copy of the stateful APIs (`Theme not initialized`, or an empty string). Read key names from `~/.pi/agent/keybindings.json` instead. `startup-logo` is the one file that imports from the package root, wrapped in a `try/catch`.
+- **Patching a pi-tui prototype works; patching the copy in `node_modules` does nothing** — silently. pi's bundled loader points extensions at its own inlined namespace, which is why `fenceless-code-block/` can patch `Markdown.prototype` and `index.test.ts` can assert it with pi's own renderer.
+- **`usage.output` is always `0` while streaming**, so token counts must be estimated from streamed characters.
+- **`renderResult` receives no `isError`**; read it from `context`. Reading `result.isError` silently paints failures as successes.
+
+## Adding an extension
+
+1. Decide the shape: a single `extensions/<name>.ts`, or `extensions/<name>/index.ts` plus helper modules.
+2. Export `default function (pi: ExtensionAPI)`.
+3. Put logic that deserves tests in a module that imports nothing from pi, and inject what it needs.
+4. Add a header comment: what problem it solves, which pi internals it depends on, what you tried that did not work. These headers are the reason this package is maintainable.
+5. `npm test`, then the tmux check above.
+6. If the extension has a switch, follow the existing convention: `PI_<NAME>=off` disables it, read on each use rather than cached at load, and document it in the README table and [extensions.md](extensions.md).
+
+A new tool name and a new command name must not collide with any other extension here; the list is in [extensions.md](extensions.md#commands).
+
+## Keeping this package in sync
+
+This package is a distribution copy, not the master copy. The author's live environment is `~/.pi/agent/`, snapshotted into a separate repository under `clients/pi/`; this package was produced by copying that snapshot verbatim (extensions, themes, and the config files) with two deliberate deltas:
+
+1. `config/models.json` is not shipped, and the three model-selection keys were removed from `config/settings.json` (`defaultProvider`, `defaultModel`, `modelThinkingLevels`). See [configuration.md](configuration.md#what-is-not-shipped).
+2. `docs/handbook.zh.md` is the snapshot's README, kept verbatim as the Chinese handbook.
+
+So when the extensions change upstream:
+
+```bash
+SRC=/Users/bachi/jaylli/litellm-any/clients/pi   # the snapshot the extension lives in
+DST=/Users/bachi/jaylli/pi-coder                 # this package
+cp -R "$SRC/extensions/." "$DST/extensions/"
+cp "$SRC/themes/"*.json "$DST/themes/"
+diff -r "$SRC/extensions" "$DST/extensions"          # expect: no output
+npm test
+# bump "version" in package.json, add a CHANGELOG entry
+```
+
+Keep the copies byte-identical. The only files that should ever differ from the snapshot are `config/settings.json` (the removed model keys) and anything under `docs/`.
+
+## Publishing
+
+```bash
+npm login                 # first time only
+npm pack --dry-run        # inspect the tarball before publishing
+npm publish
+```
+
+- The name is scoped, so `publishConfig.access: "public"` is already set — without it npm refuses to publish a scoped package publicly on a free account.
+- `keywords` includes `pi-package`, which is what makes the package appear in the [pi.dev gallery](https://pi.dev/packages). Keep it.
+- `files` decides the tarball contents; nothing else is uploaded. `.git` and `node_modules` are never included.
+- Bump `version` before each publish (npm rejects re-publishing an existing version) and add the corresponding `CHANGELOG.md` entry.
+- To test the exact artifact that would be published, pack it and install the **extracted directory** — pi treats a file path as a single extension, so a `.tgz` path fails with `Unknown file extension ".tgz"`:
+
+  ```bash
+  npm pack
+  mkdir -p /tmp/pi-pkg && tar -xzf bachi-pi-coder-1.0.0.tgz -C /tmp/pi-pkg
+  PI_CODING_AGENT_DIR=$(mktemp -d) pi install /tmp/pi-pkg/package
+  ```
+
+## How the package appears on pi.dev
+
+The [package catalog](https://pi.dev/packages) is indexed from npm — there is no submission form or upload endpoint (`/api/*` answers `501 API routes are reserved for future features`). Publishing to npm with `pi-package` in `keywords` is the whole mechanism; the crawl picks the package up within minutes and it appears in the *Recently published* feed and in the full list.
+
+The **detail page renders this README as its body**, so `README.md` is the gallery landing page, not just npm metadata:
+
+- Relative links (`docs/extensions.md`, `extensions/tool-diff.ts`) are rewritten against the `repository` field, so they resolve in the gallery — both `https://github.com/jayli/pi-coder/blob/main/docs/...` and a jsDelivr CDN form are used.
+- The page leads with the description, badges, and any `pi.image` / `pi.video` preview, then the README.
+- Resource chips (`extension`, `theme`, …) come from the `pi` manifest, so an accurate manifest is also accurate marketing.
+- The catalog adds a `report` link to `earendil-works/pi` issues automatically.
+
+### Post-publish checklist
+
+```bash
+npm view @bachi/pi-coder version --registry=https://registry.npmjs.org   # the version you just pushed
+curl -s -o /dev/null -w '%{http_code}\n' https://pi.dev/packages/@bachi/pi-coder   # 404 before indexing, 200 after
+pi install npm:@bachi/pi-coder
+```
+
+Once the package exists on npm, two optional additions become safe (they render as broken until then):
+
+1. **Badges** at the top of the README, as the reference packages do:
+
+   ```markdown
+   ![npm](https://img.shields.io/npm/v/@bachi/pi-coder?style=for-the-badge)
+   ![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)
+   ![Platform](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux-blue?style=for-the-badge)
+   ```
+
+2. **A preview asset**, which is what makes a TUI package legible in the gallery. Upload a screenshot (PNG/JPEG/GIF/WebP) or a screencast (MP4 only) — a `github.com/user-attachments/...` URL from a README upload works — then declare it:
+
+   ```json
+   "pi": {
+     "extensions": ["./extensions"],
+     "themes": ["./themes"],
+     "video": "https://github.com/user-attachments/assets/..."
+   }
+   ```
+
+   `video` takes precedence over `image` when both are set; on desktop the video autoplays on hover and opens fullscreen on click. Re-publish after changing the manifest.

package/docs/extensions.md

@@ -0,0 +1,292 @@
+# Extensions reference
+
+22 extensions load from this package. Twelve are single files in `extensions/`, ten are directories whose entry point is `index.ts`. Three more directories (`thinking-collapse/`, `tool-diff/`, `prompt-editor/`) contain pure-logic modules only — they have no `index.ts`, so pi never loads them as extensions, but the top-level files import them.
+
+Every extension is also documented in its own header comment (Chinese, except `rewind/`): the pi internals it relies on, the failure that motivated it and the trade-offs that are not visible in the code. This page is the map.
+
+## Commands
+
+| Command | Extension | Arguments |
+| --- | --- | --- |
+| `/ask` | `ask-user-question` | — Previews the questionnaire with a demo question. |
+| `/bash-collapse` | `bash-command-collapse` | `off` \| `on` \| `<1-50>` — Collapsed visual lines for the command. |
+| `/bash-preview` | `bash-command-collapse` | `off` \| `<1-50>` — Output preview lines; `off` restores pi's built-in preview. |
+| `/bash-stream` | `bash-command-collapse` | `off` \| `on` — `on` uses pi's native streaming instead of the collapse path. |
+| `/bash-timeout` | `bash-command-collapse` | — Prints the default, maximum and env-overridden bash timeout. |
+| `/bash-tree` | `bash-command-collapse` | `off` \| `on` — Tree indentation (`│`/`└`) for bash output. |
+| `/clear` | `clear-command` | — Alias of `/new`. |
+| `/exit` | `exit-command` | — Alias of `/quit` (the argument-free form of the quit words). |
+| `/init` | `init-command` | `[file.md] [extra instructions]` |
+| `/read-collapse` | `read-path-collapse` | `off` \| `on` |
+| `/recap` | `recap` | — Summarizes the conversation now. |
+| `/rewind` | `rewind` | — Checkpoint menu; also Esc Esc at an empty prompt. |
+| `/tasks` | `simple-task` | `status` (default) \| `clear` \| `on` \| `off` |
+| `/theme` | `theme-command` | `[name]` — Without arguments: picker with live preview. |
+
+## Tool overrides
+
+pi registers one handler per tool name (first registration wins), so each of these owns a builtin tool outright.
+
+### `bash-command-collapse.ts` — the `bash` tool
+
+Collapses long commands to N visual lines (default 3) followed by `… (123 tokens hidden)`, hard-wrapping at the column budget the way CSS `word-break: break-all` does rather than pre-wrapping whole words: a 78-column path fills the line completely and breaks at the edge. `ctrl+o` expansion shows the command in full. The extension also draws its own background box, tree-indents output, syntax-highlights the command line, and can give bash output its own color through the `bashOutput` theme token ([themes.md](themes.md#bashoutput-in-detail)).
+
+- `PI_BASH_MIN_TIME_MS` (default `2000`) — only show the elapsed-time footer above this duration.
+- `PI_BASH_HIGHLIGHT=off` — disable shell syntax highlighting.
+- `PI_BASH_TREE=off` — disable tree indentation.
+- `PI_BASH_SPINNER=off` — disable the `●` on running rows (implemented in `working-indicator`).
+
+Two details that look simplified but cannot be: it decides "arguments are still streaming" from `!streaming && !argsComplete && isPartial === true` (both thresholds are required, or `/resume` replays lose the command line entirely), and `isError` must be read from `context`, not `result`, because pi's result renderer is called without that field.
+
+### `read-path-collapse.ts` — the `read` tool
+
+Keeps the `read` title row on exactly one line. Long paths lose their front and keep the informative tail — the file name and last directories — as `Read …@earendil-works/pi-coding-agent/dist/core/extensions/loader.js:62-116`. No folding, no second row.
+
+- `/read-collapse off | on`, `PI_READ_COLLAPSE=off` — restore pi's builtin title row.
+
+### `tool-diff.ts` — the `edit` and `write` tools
+
+Claude Code style diffs: full-line background for added and removed lines (including the line-number gutter), inline highlight of the changed span, and syntax highlighting. Both tools are re-registered with `renderShell: "self"`, which is what makes per-line backgrounds possible — the default shell paints whole blocks by status and would cover them.
+
+The two line backgrounds come from theme tokens that pi's official schema does not define: `toolDiffAddedBg` and `toolDiffRemovedBg`. When a theme omits them, the extension falls back to the much flatter `toolSuccessBg` / `toolErrorBg`. See [themes.md](themes.md#custom-tokens).
+
+### `thinking-collapse.ts` — thinking blocks
+
+Registered as a markdown transformer for `assistant-thinking`. Every thinking block renders as **one continuous line**, no matter how many paragraphs, list items or fenced blocks the model wrote:
+
+```
+Think: …latest token keeps appending at the end
+```
+
+- Nothing is line-wrapped. When the line exceeds the terminal width, characters are dropped **from the front** and a leading `…` is added, so the end of the line is always the newest token.
+- At paragraph seams (blank lines in the original) a Chinese comma is inserted between two Chinese paragraphs; a paragraph that already ends in punctuation is left alone, and Latin text keeps the space rule.
+- There is deliberately no "backfill to fill the row" logic, and no `… (N tokens hidden)` notice — the spinner below already counts tokens.
+- No command, no environment switch. The only form is this one.
+
+### `fenceless-code-block/` — markdown code blocks
+
+Removes code fences, including the language label, and lays the code out with pi's own indentation and syntax colors — no background is added. It works by patching `Markdown.prototype.renderToken` at module evaluation time, which is effective because pi's bundled loader points extensions at its own inlined `@earendil-works/pi-tui` namespace. Installing twice (after `/reload`) wraps only once.
+
+- `PI_FENCELESS_CODE=off` — keep the fences.
+
+## TUI chrome
+
+### `statusline/` — the footer
+
+Replaces pi's footer with one status line and one status row:
+
+```
+⚡️ qwen3.8-flash/xhigh | Ctx 0.0% | main | (+0,-0)
+📁 /Users/you/project
+```
+
+The main row shows model/thinking level, context usage, git branch and diff stat; when the working directory is not a git repository it says `no git`. The second row renders whatever other extensions pass to `ctx.ui.setStatus()` (this is where `cwd-statusline`, `simple-task` and `rewind` write). Lines are truncated, never wrapped. Git reads happen on a debounced background path (400 ms after `turn_end`/`agent_end`/`tool_execution_end`, immediately on branch change, with a 30 s fallback poll) so the render path is a map lookup.
+
+- `PI_STATUSLINE_FREEZE=off` — disable the footer freeze. On every session switch pi unconditionally restores its builtin footer and clears all `setStatus` values, and no extension hook runs before that frame. The guard replays the previous frame's lines instead, which removes a visible flash. Turning it off restores the flash.
+- No config file. Colors come from `theme.fg(...)`, so `/theme` repaints on the next frame.
+
+### `cwd-statusline.ts` — full working directory
+
+Prints the complete `ctx.cwd` as an extension status line, deliberately uncompressed: no `~` shortening, no truncation of middle segments. Only terminal width truncates it, with an ellipsis, never a wrap.
+
+- `PI_CWD_STATUSLINE=off`, `PI_CWD_ICON` (default ` 📁`).
+
+### `startup-logo/` — the header
+
+Replaces pi's header with a static pi logo, the version and the working directory (shortened to `~/...` inside the home directory), keeping the compact key hints below so no information is lost. It also prunes the `[Context]`, `[Prompts]` and `[Themes]` sections from the startup resource list — those three carry no information — while keeping `[Skills]`, `[Extensions]` and every diagnostic section. Pruning works by locating the mounted header component, so it only happens when the logo is installed.
+
+The logo is static by design: no frame table, no timers, no `requestRender`. Narrow terminals degrade to a single-line wordmark.
+
+- `PI_LOGO=off` — do not install the header.
+- `header-guard.ts` freezes the header across session switches for the same reason the statusline freeze exists: pi restores its builtin header first, and that frame is visible.
+
+### `below-editor-after-statusline.ts` — widget placement
+
+pi mounts `belowEditor` widgets between the editor and the footer, which pushes the statusline to the very bottom of the screen. `pi-subagents`' fleet status line is registered that way. This extension finds the container holding the probe widget by object identity (never by index) and moves it to the end, so the fleet line sinks below the statusline and the editor keeps the statusline next to it.
+
+The probe must be registered with `placement: "belowEditor"`. Omitting it silently moves the *upper* container instead, with no runtime error. Nothing happens if the container cannot be found.
+
+- `PI_BELOW_EDITOR_AFTER_STATUSLINE=off`.
+
+### `prompt-editor.ts` — the input box
+
+Three changes to the editor.
+
+**A `❯ ` gutter.** The real editing area is narrowed and the gutter is re-added per line, so cursor placement, IME positioning and mouse clicks all stay correct.
+
+**A blank line** between a visible autocomplete list and the statusline, added only when the list is actually rendered (judged by the public `isShowingAutocomplete()`), so the static layout is unchanged.
+
+**`!` bash mode**, matching Claude Code: when the prompt starts with `!` the gutter shows `!` instead of `❯` and the `!` you typed is hidden, so the body reads as the command itself. The mode is render-only — not a single character of the text changes. Detection copies pi's own (`text.trimStart().startsWith("!")`, the same flag that colors the editor border), and Enter submission, ↑ history and Esc clearing keep going through pi's own paths, so there is nothing to keep in sync. Hiding a column has two consequences: the body shifts one column left, so mouse clicks count one extra column, and the cursor has to be pushed off column 0 — otherwise the reverse-video cursor lands on the blank column, and typing there would inject `x!ls` into the text and drop pi out of bash mode. Leaving the mode needs no code: backspacing over the `!`, submitting, or Esc all make pi's own `isBashMode` false again and the next frame draws `❯`. `PI_EDITOR_PROMPT` changes the `❯` but not the bash `!`.
+
+- `PI_EDITOR_PROMPT` (default `❯`), `PI_EDITOR_AUTOCOMPLETE_GAP=off`, `PI_EDITOR_AUTOCOMPLETE_SHIFT` (default 1 column).
+- Pure logic lives in [`prompt-editor/bash-prompt.ts`](../extensions/prompt-editor/bash-prompt.ts); the render contract is covered by [`prompt-editor/render.test.ts`](../extensions/prompt-editor/render.test.ts), which loads the real extension through pi's own loader.
+
+### `working-indicator/` — the working message
+
+Replaces the fixed `Working` loader with a semantic label, a token count for the current segment and an elapsed time:
+
+```
+Tools Calling (↓ 70 tokens · 10s)      Editing (↓ 40 tokens · 3s)
+Writing (↓ 120 tokens · 8s)            Reading (↓ 12 tokens · 1s)
+Thinking (↓ 900 tokens · 22s)          Working (5s)
+```
+
+The token count is **per segment**, not per turn: each reasoning segment and each tool-argument segment starts from zero, so a `bash` command's count reflects that command. Body text is deliberately not counted. `usage.output` is always `0` while streaming, so counts are estimated from streamed characters. Elapsed time is `42s`, `1m 23s` or `1h 23m 32s`. The label uses the normal foreground color while the statistics stay muted, which requires composing everything into the single string pi receives.
+
+The same extension draws the `●` on a running bash row.
+
+- `PI_BASH_SPINNER=off`, `PI_SPINNER_RAINBOW=off`, `PI_SPINNER_COLOR_HOLD` (default `19` frames per color).
+- `PI_WORKING_SUMMARY=off` — disable the prompt summary line entirely.
+- `PI_WORKING_SUMMARY_LLM=off` — truncate long prompts instead of asking a model to compress them.
+- `PI_WORKING_SUMMARY_TRIGGER` (default `1.2`) — ask for a summary when the prompt exceeds the available width by this factor.
+- `PI_WORKING_SUMMARY_MODEL` — `provider/modelId` for that request; defaults to the session model so a typo can only cost the summary, never the request.
+- `PI_WORKING_SUMMARY_GAP` (default `1`).
+
+## Workflow
+
+### `simple-task/` — task list
+
+A lightweight task list: `task_set`, `task_update`, `task_get` and `/tasks`. Three states (`pending`, `in_progress`, `done`), no blocks, no dependency graph, no notes, no title-length validation.
+
+State is written with `pi.appendEntry()`, so it rides the session log and **nothing is written into your repository** — no `.pi/tasks/*.json` to gitignore. Rebuilding reads `ctx.sessionManager.getBranch()`, not `getEntries()`, so branch navigation cannot resurrect a discarded branch's tasks.
+
+`/tasks` with no argument or `status` prints the list, `clear` empties it, `on` / `off` toggle the widget.
+
+### `recap/` — conversation summary
+
+`/recap` summarizes the conversation on demand; the same summary appears automatically above the editor after **30 seconds of idling** with no new input, and disappears as soon as you type.
+
+The delay is the point: the recap exists to tell you what a session was doing when you come back to the window, so it is idle-based rather than turn-based. The timer first asks whether any subagent is still running (an in-process RPC to `pi-subagents`, no file import — a missing package is treated as "no subagents") so a background delegation is never summarized as finished.
+
+Deliberately not implemented: no local storage, no session entry, no configuration. The summary lives in memory only, so `/new` or `/resume` does not restore it and it is never sent to the model as context. The summary text itself is **generated in Chinese** (the prompt is hardcoded), which is worth knowing if you do not read Chinese.
+
+### `rewind/` — checkpoints and `/rewind`
+
+Claude Code style checkpointing. Before every prompt that starts a turn, the working tree is snapshotted into a **shadow git repository** under `~/.pi/agent/rewind/<project-hash>/git` with `GIT_DIR` pointed at it and `GIT_WORK_TREE` at your project. Your repository's HEAD, index, refs and status are never touched, and this works in directories that are not git repositories at all.
+
+Files the snapshot cannot see — anything `edit`/`write` touches outside the project root, inside it but `.gitignore`d, or inside a nested repository — are covered by lazy pre-image mirroring driven by tool-call events, with blobs addressed by content.
+
+`/rewind`, or Esc Esc at an empty prompt, opens a menu: restore code and conversation, conversation only, code only, summarize from here, or never mind. Conversation restore uses pi's native session-tree navigation, which drops the selected user message and puts its text back into the editor.
+
+- **Requires `doubleEscapeAction: "none"`** in `settings.json`. The extension warns once at session start if the built-in tree navigator would fire instead. It consumes the second Esc (the selector takes focus synchronously, so letting it through would cancel the menu it just opened) while leaving the first Esc alone, so Esc still aborts streaming.
+- Known limits: only the `edit` and `write` tools are tracked (`bash` writes outside the root cannot be parsed), and files larger than 8 MB are not copied.
+
+### `init-command.ts` — `/init`
+
+Claude Code style repository memory file generation. Target selection looks only at `ctx.cwd`:
+
+1. `CLAUDE.md` exists → update `CLAUDE.md`
+2. else `AGENTS.md` exists → update `AGENTS.md`
+3. else create `AGENTS.md`
+
+`/init <file.md> [extra instructions]` overrides the target and appends your requirements. The extension writes nothing itself: it resolves the target and sends a prompt as a user message, so the model's own `read`/`write`/`edit` calls do the work and you can watch and correct them. It waits for the current turn to finish before sending.
+
+### `theme-command.ts` — `/theme`
+
+A one-step theme picker with live preview. Arrow keys preview, Enter persists, Esc cancels. `/theme <name>` switches and persists directly.
+
+The preview works because `ctx.ui.setTheme()` has two distinct paths: passing a **Theme object** only recolors the running UI (`setThemeInstance()`), while passing a **name** applies it and immediately writes `settings.json` (`setThemeName()`). So browsing never touches your settings, and only Enter does. In non-TUI modes the command notifies instead of silently failing.
+
+### `folder-history.ts` — cross-session command history
+
+Persists command history per working directory in `~/.pi/folder-history/<path-with-dashes>.jsonl` and injects previous sessions' entries into the editor's own history array, which makes the **native ↑/↓** walk across sessions.
+
+The mechanism matters: previous sessions' entries are appended to the tail of `Editor.history` (tail = older), so ↑ goes further back in time. No shortcut is registered — a registered `up` key would swallow cursor movement in multi-line prompts and arrow navigation in every selector. `PI_FOLDER_HISTORY_INJECT` (default `100`) caps how many entries come from earlier sessions.
+
+### `clear-command.ts` — `/clear`
+
+Alias of `/new` implemented through `ctx.newSession()` — the same replacement flow the builtin uses, so behavior and on-disk format match. It calls `ctx.waitForIdle()` first so an in-flight turn (including retries and auto-compaction) is never racing the session swap.
+
+### `exit-command.ts` — quit words
+
+Typing `exit`, `quit` or `bye` as the entire prompt quits pi cleanly (sessions are saved; `session_shutdown` still runs). Matching is exact and case-insensitive, so "exit the loop and print a summary" is untouched, and messages with attachments pass through. It only applies in TUI mode: in `--print`, `--mode json` and RPC mode these remain ordinary prompts. Also registers `/exit` as an alias of `/quit`.
+
+- `PI_EXIT_WORDS="exit,quit"` — replace the words; `off` disables the interception.
+
+## Model and tooling
+
+### `auto-default-model/` — persistent model switches
+
+pi's `/model` picker only changes the current session; persisting it takes a separate Ctrl+S (`setModel(model, { persist: true })`). This extension performs that step automatically on every model switch — the picker, Ctrl+P cycling, a subagent profile switch, anything that calls `pi.setModel()`.
+
+It writes through pi's own `SettingsManager`, so it uses the same file lock as pi (`proper-lockfile`), merges only the changed fields into the newest on-disk content, and therefore cannot clobber concurrent `/theme` or `/settings` writes. It skips session restore (`source === "restore"`) and skips no-op writes. Failures are notified; successes are silent, because the model name is already visible in the statusline.
+
+- `PI_AUTO_DEFAULT_MODEL=off`.
+
+### `ask-user-question/` — the `ask_user_question` tool
+
+A Claude Code style structured question tool. The model asks instead of guessing; a questionnaire appears in the terminal with up to **4 questions**, each with **2–4** described options, a free-text row appended automatically, Space to multi-select, ↑/↓ to navigate and Esc to abandon the whole questionnaire. Answers return to the model as structured text.
+
+The labels `Other` and `Type something.` are reserved — validation rejects them — and the number of questions and options is enforced by the tool's TypeBox schema, while string length limits are enforced by runtime truncation. Non-TUI hosts (RPC, print) fall back to sequential `select`/`input` dialogs. The tool removes itself in child sessions where `ctx.hasUI` is false.
+
+- `PI_ASK_USER_QUESTION=off` — do not register the tool.
+- `/ask` previews the dialog with a demo questionnaire.
+
+### `subagent-log-guard/` — stderr guard
+
+`pi-subagents` prints launch diagnostics such as `[pi-subagents] Agent 'researcher': host runtime tool availability omitted [...]` with `console.warn`. In interactive mode pi does not take over stdout/stderr, so that text is written straight into the alternate screen at the hardware cursor — right on top of the editor row — and the differential renderer will not repaint it. The result is permanent garbage across the input box.
+
+This extension wraps `process.stderr.write` in processes that have a UI and stops lines beginning with `[pi-subagents]` from reaching the terminal. Only that prefix is filtered; everything else writes through untouched. Processes without a UI (RPC, print, subagent runners) are not patched at all, which is why background subagent diagnostics still land in `runner.stderr.log`.
+
+- `PI_SUBAGENT_LOG_GUARD=notify` — route the messages through `ctx.ui.notify(..., "warning")` instead of dropping them.
+- `PI_SUBAGENT_LOG_GUARD=off` — remove the guard (useful when tracing who printed a line).
+
+## Environment switches
+
+Every switch is an environment variable read at use time, not cached at load, so it can be scoped per project or set in a shell alias. An unset variable means "on"; `off` always disables.
+
+| Variable | Default | Owning extension | Effect |
+| --- | --- | --- | --- |
+| `PI_ASK_USER_QUESTION=off` | on | `ask-user-question` | Do not register the `ask_user_question` tool. |
+| `PI_AUTO_DEFAULT_MODEL=off` | on | `auto-default-model` | Do not persist model switches to `settings.json`. |
+| `PI_BASH_HIGHLIGHT=off` | on | `bash-command-collapse` | Disable shell syntax highlighting in bash title rows. |
+| `PI_BASH_MIN_TIME_MS` | `2000` | `bash-command-collapse` | Only show the elapsed-time footer above this duration. |
+| `PI_BASH_PREVIEW` | `3` | `bash-command-collapse` | bash output preview lines (1–50); `off` restores pi's built-in preview. |
+| `PI_BASH_SPINNER=off` | on | `working-indicator` | Disable the `●` spinner on running bash rows. |
+| `PI_BASH_STREAM=on` | off | `bash-command-collapse` | Use pi's native streaming for bash instead of the collapse path. |
+| `PI_BASH_TREE=off` | on | `bash-command-collapse` | Disable tree indentation (`│`/`└`) for bash output. |
+| `PI_BELOW_EDITOR_AFTER_STATUSLINE=off` | on | `below-editor-after-statusline` | Leave `belowEditor` widgets where pi puts them. |
+| `PI_CWD_ICON` | ` 📁` | `cwd-statusline` | Icon used by the cwd status line. |
+| `PI_CWD_STATUSLINE=off` | on | `cwd-statusline` | Do not print the cwd status line. |
+| `PI_EDITOR_AUTOCOMPLETE_GAP=off` | on | `prompt-editor` | Do not add the blank line under the autocomplete list. |
+| `PI_EDITOR_AUTOCOMPLETE_SHIFT` | `1` | `prompt-editor` | Columns to shift the autocomplete list left. |
+| `PI_EDITOR_PROMPT` | `❯` | `prompt-editor` | Editor prompt character. The bash-mode `!` is not affected. |
+| `PI_EXIT_WORDS` | `exit,quit,bye` | `exit-command` | Comma-separated quit words; `off` disables the input interception. |
+| `PI_FENCELESS_CODE=off` | on | `fenceless-code-block` | Keep Markdown code fences. |
+| `PI_FOLDER_HISTORY_INJECT` | `100` | `folder-history` | History entries injected from previous sessions. |
+| `PI_LOGO=off` | on | `startup-logo` | Do not install the startup header. |
+| `PI_READ_COLLAPSE=off` | on | `read-path-collapse` | Keep pi's built-in `read` title row. |
+| `PI_SPINNER_COLOR_HOLD` | `19` | `working-indicator` | Frames per color in the spinner cycle. |
+| `PI_SPINNER_RAINBOW=off` | on | `working-indicator` | Disable the rainbow spinner. |
+| `PI_STATUSLINE_FREEZE=off` | on | `statusline` | Disable the footer freeze that hides the one-frame flash on session switch. |
+| `PI_SUBAGENT_LOG_GUARD` | `drop` | `subagent-log-guard` | `notify` shows the diagnostics through `ctx.ui.notify`; `off` disables the guard. |
+| `PI_WORKING_SUMMARY=off` | on | `working-indicator` | Disable the prompt summary line. |
+| `PI_WORKING_SUMMARY_GAP` | `1` | `working-indicator` | Minimum blank columns between the working label and the summary. |
+| `PI_WORKING_SUMMARY_LLM=off` | on | `working-indicator` | Truncate the summary instead of asking a model to compress it. |
+| `PI_WORKING_SUMMARY_MODEL` | session model | `working-indicator` | `provider/modelId` used for the summary request. |
+| `PI_WORKING_SUMMARY_TRIGGER` | `1.2` | `working-indicator` | Ask for a summary when the prompt exceeds this multiple of the available width. |
+
+## Extension interactions
+
+- **Esc Esc is shared.** `rewind` replaces pi's built-in double-Escape action and needs `doubleEscapeAction: "none"`; see above.
+- **The `bash` tool can only be registered once.** Everything that shapes its rendering lives in `bash-command-collapse.ts` for that reason — a second file registering `bash` would be ignored silently.
+- **`recap` imports `simple-task/gap.ts`.** The neighbour-gap heuristic is shared rather than duplicated, so `recap` and `simple-task` must be installed together. In this package they always are; if you copy extensions individually, copy both.
+- **The theme preview and the theme files are coupled.** `/theme` persists the name it previewed, and the name must match the `theme` field's expectations in [themes.md](themes.md).
+- **Three extensions read theme tokens that pi's schema does not define** (`toolDiffAddedBg`, `toolDiffRemovedBg`, `bashOutput`) and degrade quietly when a theme omits them.
+
+## State on disk
+
+| Location | Written by | Contents |
+| --- | --- | --- |
+| `~/.pi/agent/settings.json` | `auto-default-model` | `defaultProvider` / `defaultModel` on every model switch. |
+| `~/.pi/agent/rewind/<project-hash>/git` | `rewind` | Shadow git repository with pre-turn snapshots. Never touched by your repository. |
+| `~/.pi/folder-history/<path-with-dashes>.jsonl` | `folder-history` | Command history per working directory. |
+| Session log (via `appendEntry`) | `simple-task` | Task list state; discarded with the session, never written to the repo. |
+| In memory only | `recap` | The current summary; lost on `/new` or `/resume` by design. |
+| Nothing | everything else | The remaining extensions are pure display or event wiring. |
+
+## Adding, disabling and removing extensions
+
+- **Disable one** — `pi config` lists every resource from packages and local directories with an on/off toggle, in global or project scope. Or set the switch listed above when the extension has one.
+- **Remove one** — delete its file (or its directory) from the package, or copy the ones you want into `~/.pi/agent/extensions/` and stop installing the package. Deleting subdirectories is safe except for the directories other files import: the helper-only `thinking-collapse/`, `tool-diff/` and `prompt-editor/`, and `simple-task/`, whose `gap.ts` is imported by `recap`.
+- **Edit one** — work in a checkout and run pi against it; see [development.md](development.md).