@astralyn/pi 0.82.1 → 0.82.3

package/docs/bundled/README.md

@@ -0,0 +1,38 @@
+# Bundled features
+
+The installed `@astralyn/pi` package includes a small set of workflows and presentation choices on top of its coding-agent behavior. Upstream Pi release tags are synchronization input, not a separate user documentation set.
+
+## Extensions
+
+The following extensions are loaded as hidden built-ins. They use the same public Extension API available to external extensions.
+
+| Extension | Tool or command | Purpose |
+|---|---|---|
+| `llama.cpp` | `/llama` | Manage models served by the local llama.cpp router |
+| `deepwiki` | `deepwiki` | Query indexed public GitHub repository documentation |
+| `question` | `question` | Ask structured questions through native interactive UI |
+| `rewind` | `/rewind` | Create and restore project snapshots around session lifecycle operations |
+| `router` | `/router` | Configure and probe Codex-style routing endpoints |
+| `statusline` | Footer status | Show concise extension-managed activity state |
+| `subagent` | `subagent`, `/agents` | Delegate bounded work to isolated child Pi sessions |
+| `todo` | `todo`, `/todos` | Track multi-step work with dependencies and status |
+
+See the [bundled extension catalog](extensions/README.md) for configuration and behavior details.
+
+## Context safety
+
+Long tool loops are checked after a completed tool batch and before another provider request. When the active context crosses the configured auto-compaction threshold, Pi compacts and rebuilds the context before continuing the same run. Cancellation, compaction failure, an unavailable cut point, or retained context that remains unsafe stops before another provider request.
+
+See [Compaction](../compaction.md).
+
+## Tool presentation
+
+Native tool calls use a consistent `●` call and `│` result shell with bounded collapsed output. Built-in semantic renderers remain responsible for paths, diffs, syntax highlighting, command output, and images.
+
+See [Native tool presentation](tool-presentation.md).
+
+## Themes
+
+The package includes `ice-cream-dark` and `ice-cream-light` alongside the standard `dark` and `light` themes.
+
+See [Bundled themes](themes.md) and [Theme authoring](../themes.md).

package/docs/bundled/extensions/README.md

@@ -0,0 +1,18 @@
+# Bundled extensions
+
+These are extensions shipped in the `@astralyn/pi` npm package. For the public API used to write external extensions, see the [Extension API documentation](../../extensions.md).
+
+They are registered as hidden built-in extensions and use the same public Extension API available to external extensions. Their implementation details are internal to the package and are not required for installation or configuration.
+
+| Extension | Tool or command | Documentation |
+|---|---|---|
+| `llama.cpp` | `/llama` | [llama.cpp](../../llama-cpp.md) |
+| `deepwiki` | `deepwiki` | [deepwiki.md](deepwiki.md) |
+| `question` | `question` | [question.md](question.md) |
+| `todo` | `todo`, `/todos` | [todo.md](todo.md) |
+| `rewind` | `/rewind`, `/tree` lifecycle | [rewind.md](rewind.md) |
+| `router` | `/router` | [router.md](router.md) |
+| `statusline` | Footer | [statusline.md](statusline.md) |
+| `subagent` | `subagent`, `/agents` | [subagent.md](subagent.md) |
+
+The catalog documents installed-package behavior and configuration; it does not require access to the package's internal source.

package/docs/bundled/extensions/deepwiki.md

@@ -0,0 +1,62 @@
+# DeepWiki
+
+`deepwiki` is a Pi-native tool for querying DeepWiki's generated documentation for GitHub repositories.
+
+It is intentionally not a general MCP bridge. The extension exposes one dedicated tool with three fixed actions:
+
+| Action | Behavior |
+|---|---|
+| `structure` | List the generated wiki topics for a repository. |
+| `contents` | Read the generated wiki — one page via `page` (recommended), or everything when `page` is omitted (truncated past ~120k chars). |
+| `question` | Ask a focused question about a repository. |
+
+## Usage
+
+### Parameters
+
+- `action`: `structure`, `contents`, or `question`
+- `repoName`: one `owner/repo` string for `structure` and `contents`; for `question`, one repo as a string, or 2–10 repos as an array (comma-separated string also accepted)
+- `question`: required only for `action: "question"`
+- `page`: optional, only for `action: "contents"` — 1-based index or page title from `structure` (plain titles such as `Extension System`, not numbered outline lines like `4.4 …`). Leading outline numbers on titles are stripped when matching. Unknown `page` fails with available titles listed.
+
+`repoName` is normalized before validation (`owner/repo`, GitHub/DeepWiki URLs, JSON-array strings for multi-repo mistakes). `pageName`/`pageTitle` are accepted as `page` aliases. If `action` is omitted, defaults to `question` when a question is present, `contents` when `page` is present, else `structure`. Repositories not indexed on DeepWiki return repository-not-found errors — run `structure` first to detect that.
+
+### Strategy
+
+Recommended flow for studying a repo:
+
+1. `structure` — get the page outline.
+2. `contents` + `page` — read the specific pages you need, one at a time.
+3. Avoid `contents` without `page` (the full wiki) unless the wiki is genuinely small; oversized output is truncated at ~120k chars.
+4. `question` — when the wiki pages don't cover what you need, or directly for a quick answer without reading.
+
+Use DeepWiki when generated docs for public repositories are useful context:
+
+- Understanding an unfamiliar public repo's architecture, module layout, APIs, data flow, or extension points.
+- Researching reference implementations while designing or building a new feature or project.
+- Asking a focused question about how a public repo implements something.
+- Comparing patterns or extension surfaces across multiple public repos with `question` and a repo array.
+- Pulling a broad topic map with `structure` before deciding which part of a repo matters.
+
+The prompt is model-facing: when these conditions apply, the model should call the tool itself instead of telling the user to open DeepWiki manually.
+
+Avoid DeepWiki when the authoritative source is local or time-sensitive:
+
+- Local workspace files, private code, uncommitted changes, or exact current checkout state.
+- Latest releases, pricing, security advisories, schedules, or facts that need current primary-source verification.
+- Package names without a known GitHub repo; resolve the repo first instead of guessing.
+
+## Limits
+
+- A repository may not be indexed. DeepWiki can return that as normal text, so the extension treats repository-not-found messages as tool errors.
+- `contents` responses are truncated at a ~120k-character budget on `# Page:` boundaries (whole pages kept in order; at least the first page survives, cut mid-page if it alone exceeds the budget). A trailing notice reports shown/total pages, the full length, up to 20 omitted page titles, and points at `page` reads and `action: "question"` for the rest. Details carry `shownPages` / `truncatedChars` when this happens; `outputLength` always reflects the full untruncated response. Single-page reads set `requestedPage` / `pageIndex` instead and share the same budget.
+- Network requests time out after 45 seconds and surface as Pi tool errors.
+- Use local Pi tools (`read`, `grep`, `find`, `ls`) for workspace state. DeepWiki answers describe repository snapshots indexed by DeepWiki, not local uncommitted files.
+
+## Implementation notes
+
+DeepWiki's public MCP endpoint exposes exactly three operations: list a wiki's page titles, return the whole generated wiki as one document, and answer a question. There is no per-page fetch upstream — `page` is implemented by this extension: it fetches the full wiki (or reuses the 10-minute cache) and slices out the requested page locally. The first `contents` call for a repo pays the network cost; subsequent page reads within the cache window are instant and free.
+
+DeepWiki may return generated explanations with source-file citations and "related pages" links. The TUI uses a local renderer (`render.ts`) for a one-line collapsed summary and Markdown when expanded; Pi's default fallback would dump the full (often large) `content` text.
+
+Successful responses are cached in-process for 10 minutes, keyed by action, repo, and question. Failed, aborted, and timed-out requests are not cached. The cache stores the full response; `contents` truncation is recomputed per call, so cached and fresh calls return identical text.

package/docs/bundled/extensions/question.md

@@ -0,0 +1,48 @@
+# question — structured user questions
+
+Adds a `question` tool for asking one to four multiple-choice questions when the agent needs a user decision. A Pi-native take on AskUserQuestion: a lightweight custom dialog with concise transcript summaries and a bounded model-facing result.
+
+## Behavior
+
+- Each option requires a concise description of its consequence or trade-off. Questions, labels, descriptions, and previews have input-length limits so the dialog stays usable.
+- A single single-select question submits as soon as the user selects an option.
+- A multi-question flow advances after each single-select answer; multi-select uses `Space` to toggle choices and Enter to continue. Once every question is answered, a **Review answers** view requires explicit submission.
+- `←` / `→` switch between adjacent questions without wrapping. The tab bar marks answered questions and the Review state.
+- `Chat about this` is available after the choices. It returns a `needs_clarification` outcome so the model explains or reformulates instead of treating the user as having declined.
+- `Type something.` is appended automatically for custom answers. Authored options may not use reserved labels (`Other`, `Type something.`, `Chat about this`, `Next`).
+- `Tab` opens a note editor for the focused option; in multi-select, the option must be selected first. On the custom-answer row, it opens custom-answer input.
+- Multi-select custom answers stay on the `Type something.` row, are selected when saved, and can be toggled with `Space` without losing text.
+- `preview` shows focused single-select content beside the choices on wide terminals and beneath them on narrow terminals. Preview height is capped and reports hidden lines.
+- The dialog is available only in TUI mode. RPC, JSON, and print calls return a structured `no_ui` error rather than attempting a custom component.
+
+## Result contract
+
+`details` preserves structured state for rendering and session history:
+
+```ts
+{
+  answers,
+  outcome: "answered" | "cancelled" | "needs_clarification" | "error",
+  cancelled,
+  error?,
+}
+```
+
+Only `content` reaches the model. Successful results are numbered, clearly identify single/custom/multi answers, retain notes, and state when a preview was selected without echoing its full source. Model-facing output is capped at 12,000 characters; if it is truncated, the result instructs the model to ask a focused follow-up question. Notes and custom answers are capped at 4,000 characters in the dialog.
+
+The transcript uses a private `renderCall` / `renderResult` only to replace raw question JSON and model-oriented result text with concise user summaries. Pi retains its native tool shell, pending/error state, and collapsed/expanded behavior.
+
+## Limits
+
+- Questions, labels, descriptions, and previews have input-length limits so the dialog stays usable.
+- Notes and custom answers are capped at 4,000 characters.
+- Model-facing output is capped at 12,000 characters; if truncated, the result instructs the model to ask a focused follow-up question.
+- Only available in TUI mode. RPC, JSON, and print calls return a structured `no_ui` error.
+
+## Implementation notes
+
+- Uses Pi's native `ctx.ui.custom()` lifecycle; no state is shared with another extension.
+- The render cache is keyed by terminal width **and height**, because preview height depends on available rows and Pi resize only requests a render.
+- `validateQuestions` enforces uniqueness, reserved-label rejection, and text budgets beyond what the JSON schema can express.
+- Dialog navigation follows Pi's injected select/input keybindings where applicable; custom actions such as Space-to-toggle remain explicit in the footer.
+

package/docs/bundled/extensions/rewind.md

@@ -0,0 +1,75 @@
+# rewind — checkpoints & rewind
+
+Per-edit file backups plus a `/rewind` settings menu. Instead of snapshotting the
+whole working tree, rewind backs up **only the files Pi's `edit`/`write` tools are
+about to change** — one `copyFile` before each edit. Cost is proportional to how
+many files Pi changed, never to project size, so it never blocks the session
+lifecycle (the old shadow-git design froze the UI in large multi-project
+directories) and storage stays tiny.
+
+## Behavior
+
+Per turn: `before_agent_start` opens a snapshot frame (re-recording every tracked
+file at its turn-start state, reusing the latest backup when unchanged);
+`tool_call(edit|write)` backs up each newly edited file *before* it lands;
+`agent_settled` persists the frame to the session JSONL as a `pi-rewind-snapshot`
+custom entry **only when files changed**. Using `agent_settled` (not `agent_end`)
+keeps auto-retry, overflow compaction-retry, and queued follow-ups in one logical
+turn — `agent_end` can fire while Pi still continues. Requires **Pi ≥ 0.80.4**
+(when `agent_settled` was added); older hosts never fire that event, so frames
+would not finalize. Entries survive `/reload` and compaction; the index is
+rebuilt from them on `session_start`.
+
+- **Scope (deliberate trade-off):** rewind covers edits made through Pi's built-in
+  `edit` and `write` tools. Files written by `bash` (redirects, codegen, `mv`) or
+  edited by hand outside Pi are **not** tracked — same boundary as Claude Code's
+  file-history. Rewind undoes *Pi's edits*, not arbitrary filesystem state.
+- **Time-travel is via `/tree`.** Navigating to a node whose turn changed files
+  prompts to restore them, listing the affected files (cwd-relative, up to 8
+  then *"+N more"*) under *"Restore 3 files to this point?  (+120 / −40)"*
+  when coarse line stats are available; choosing yes restores the work tree to
+  that turn's start state. Nodes with no file changes navigate silently. Only
+  files that actually differ are rewritten. Line totals are a bag-of-lines
+  estimate (capped at 1 MB per file), not a full Myers diff.
+- **`/rewind` is a settings + storage menu**, not a restore picker:
+  - toggle rewind on/off,
+  - set the auto-clean retention window,
+  - inspect storage and prune (clean aged + orphaned / remove orphaned / remove
+    all except current).
+- **New files** created by `write` are tracked with a "did not exist" marker, so
+  rewinding deletes them.
+- **Resume/fork** hard-links the prior session's backup blobs into the new
+  session (falling back to copy), so rewind keeps working without duplicating
+  storage.
+
+## Storage & cleanup
+
+- **Layout:** `~/.pi/agent/rewind/`
+  - `config.json` — `{ enabled, retentionDays, maxSnapshots }`
+  - `backups/<sessionId>/<sha256(relpath)[:16]>@v<n>` — backup blobs (flat, hashed
+    names keep paths short on Windows; mode preserved)
+- **Auto-clean:** at `session_start`, backup directories older than
+  `retentionDays` (default **30**, set in `/rewind`) are reclaimed, plus an
+  **orphan sweep** of directories whose session id has no session JSONL (crashed
+  sessions). The GC is time-boxed and deletion-capped so it never slows startup.
+- The former `pi-config` storage layout is **not** read or migrated by this
+  engine. Remove any old `~/.pi/agent/pi-config/` data manually if it is no
+  longer needed.
+
+## Limits
+
+- Covers edits made through Pi's built-in `edit` and `write` tools only. Files written by `bash` or edited outside Pi are not tracked.
+- A backup failure is swallowed — the edit proceeds without checkpointing rather than blocking the tool.
+- `/rewind` on its own does not restore files. Restoration uses `/tree` — navigate to a turn and confirm the prompt.
+- Restore is coarse: only files that differ are rewritten, but line totals are a bag-of-lines estimate (capped at 1 MB per file), not a full Myers diff.
+
+## Implementation notes
+
+- **Never blocks the edit.** Backup runs before the write lands; a backup failure is swallowed so the session never stalls.
+- **Restore safety.** `applySnapshot` only rewrites files that differ and degrades gracefully on unreadable backups.
+- **Change detection.** A file is re-backed-up only when its stat or content differs from the latest backup. Content comparison streams in 64 KiB chunks instead of buffering whole files up to the 25 MB cap.
+- **Config is memory-cached.** `config.json` is re-read on `session_start` and updated in memory when `/rewind` saves.
+- **Restore path is single-scan.** The `/tree` confirm pass caches changed absolute paths; IO is concurrency-capped (16).
+
+
+Architecture informed by oh-my-pi (GPL-3.0) and Claude Code's file-history; independent implementation.

package/docs/bundled/extensions/router.md

@@ -0,0 +1,126 @@
+# `router` — Codex-style API relays
+
+`/router` connects Pi to OpenAI-compatible API relays — self-hosted gateways such as sub2api, CPA, or codex2api, and any similar proxy — using a **Codex-shaped** Responses client.
+
+Configuration lives at `~/.pi/agent/router.json`.
+
+Providers are registered at extension load via `pi.registerProvider` (config form + `streamSimple`). They do **not** go through `models.json`. This follows Pi's documented custom-provider path ([providers.md](../../providers.md), [custom-provider.md](../../custom-provider.md)): the stream wraps the built-in `openAIResponsesApi()` from `@earendil-works/pi-ai/compat` (same approach as the GitLab Duo example), then reshapes the request for Codex-style relays.
+
+---
+
+## Usage
+
+```
+/router          Browse relays
+/router add      Add a relay
+/router reload   Re-register from disk
+/router <id>     Open a relay
+```
+
+### UI map
+
+```
+API relays                  ← relays first; add / reload at bottom
+ └─ Relay · {id}            ← models · base URL · API key · remove
+     └─ Models              ← Fetch catalog + one row per configured model
+         └─ {model id}      ← display name · thinking levels
+```
+
+Edits **auto-save** to `router.json` and re-register the provider. There is no separate Save step — Back never discards committed field or model changes.
+
+Nested multi-select (catalog) and the thinking-level editor require **Ctrl+S to apply** that screen's working set. If you press Esc with unsaved toggles, the footer warns once; pressing Esc again discards that screen only.
+
+### Add flow
+
+1. **Name** — provider id (e.g. `my-relay`); appears as `my-relay/gpt-5.6-sol` in `/model`
+2. **Base URL** — usually ends with `/v1`
+3. **API key** — literal `sk-…` or `$ENV_VAR`
+4. **Fetch models** — `GET {baseUrl}/models`
+5. **Select** — Space to toggle, Ctrl+S to apply (TUI); the relay is then written immediately
+
+Each selected model gets these defaults:
+
+| Field | Default |
+|:-:|:-:|
+| `name` | **Omitted** — `/model` shows the model **id** |
+| `reasoning` | `true` |
+| `input` | `text` + `image` |
+| `contextWindow` | 272000 |
+| `maxTokens` | 128000 |
+| `thinkingLevelMap` | off…medium hidden; high / xhigh / max on |
+
+### Customize models
+
+Relay → **Models** → pick a model:
+
+- **Display name** — optional label (e.g. `Luna`). Leave empty to show the id. Saved on confirm.
+- **Thinking levels** — toggle each Pi level between **on** and **hidden** (`null`). Ctrl+S applies, then auto-saves the relay.
+
+---
+
+## Config shape
+
+```jsonc
+{
+  "version": 1,
+  "relays": [
+    {
+      "id": "my-relay",
+      "baseUrl": "https://relay.example/v1",
+      "apiKey": "sk-…",
+      "models": [
+        {
+          "id": "gpt-5.6-sol",
+          "reasoning": true,
+          "input": ["text", "image"],
+          "contextWindow": 272000,
+          "maxTokens": 128000,
+          "thinkingLevelMap": {
+            "off": null,
+            "minimal": null,
+            "low": null,
+            "medium": null,
+            "high": "high",
+            "xhigh": "xhigh",
+            "max": "max"
+          }
+        },
+        {
+          "id": "gpt-5.6-luna",
+          "name": "Luna",
+          "reasoning": true,
+          "input": ["text", "image"],
+          "contextWindow": 272000,
+          "maxTokens": 128000
+        }
+      ]
+    }
+  ]
+}
+```
+
+There is **no migration** from any older models-manager config. Add relays with `/router add` (or edit `router.json` and run `/router reload`).
+
+---
+
+## Limits
+
+- SSE only — no Codex WebSocket or zstd-compressed request body.
+- Catalog probe expects OpenAI-style `{ data: [{ id }] }` response format.
+- Empty model list → provider is not registered (nothing appears in `/model`).
+- Body is Codex-oriented for transparent gateways; auth and URL remain Platform Responses (`sk-` + `/responses`).
+- Same relay + same model: tool/reasoning multi-turn matches Codex-style Responses. Switching model or provider mid-session may normalize tool-call ids more strictly (upstream allow-list); this is not worked around here.
+- Interactive `/router` requires a TUI (`ctx.hasUI`); otherwise a warning is shown and no dialog opens.
+- Catalog multi-select and thinking editor are apply-on-Ctrl+S screens; only those screens can be discarded with double Esc.
+
+## Implementation notes
+
+**Request shape.** `stream.ts` calls `openAIResponsesApi().streamSimple` with a model configured as Platform Responses (`api: "openai-responses"`). The `onPayload` callback reshapes the body toward Pi's built-in `openai-codex-responses` format, with `store: false`, system prompt as `instructions`, `parallel_tool_calls: true`, and rejected fields such as `prompt_cache_retention` and `temperature` dropped.
+
+Session affinity headers use hyphenated form (`session-id`, `x-client-request-id`). Compat settings: `sessionAffinityFormat: "openai-nosession"`, `supportsLongCacheRetention: false`. Originator header: `codex`.
+
+**Differences from ChatGPT Codex OAuth.** Auth uses Bearer `sk-…` (not OAuth JWT), endpoint is `{baseUrl}/responses` (not `/codex/responses`), transport is SSE only (no WebSocket or zstd), and `OpenAI-Beta` is not set. These match **sk- relays**, not the official ChatGPT backend.
+
+**Multi-turn tool calls.** On a fixed relay + fixed model, tool-call ids preserve the Responses form and replay like Codex. Pi only rewrites ids across model boundaries. Staying on one model for long tool + reasoning sessions avoids id sanitization.
+
+

package/docs/bundled/extensions/statusline.md

@@ -0,0 +1,109 @@
+# statusline — fixed two-line footer
+
+Replaces Pi's built-in footer with a fixed, color-coded two-line status display
+using a balanced left/right layout. It registers no tool or command and has no
+configuration file. The footer auto-enables on `session_start` in TUI mode and
+clears itself on `session_shutdown`.
+
+## What it shows
+
+```text
+DeepSeek V4 Pro (opencode-go) · xhigh          ~/Projects · main
+CTX 2.1%/1.0M                    ↑13k ↓13k R440k CH99.4% $0.074
+```
+
+### Line 1 — session identity (left) · location (right)
+
+**Left**
+
+- **Model:** human-readable model name, falling back to the model id.
+- **Provider:** the model source in parentheses, such as `(deepseek)` or
+  `(opencode-go)`.
+- **Effort:** the latest thinking level when the model supports reasoning and
+  the level is not `off`.
+
+**Right**
+
+- **Working directory:** full cwd shortened against the home directory with `~`.
+- **Git branch:** appended when available.
+
+### Line 2 — context (left) · usage (right)
+
+**Left**
+
+- **Context:** used percentage plus context-window size. The percentage uses
+  fixed semantic tiers: accent normally, warning above 70%, error above 90%.
+
+**Right**
+
+- `↑` cumulative input tokens.
+- `↓` cumulative output tokens.
+- `R` cumulative cache-read tokens.
+- `W` cumulative cache-write tokens, omitted when zero.
+- `CH` cache-hit percentage for the latest assistant request, calculated as
+  `cacheRead / (input + cacheRead + cacheWrite)` and shown only when that
+  request used cache.
+- `$` cumulative cost; `(sub)` is appended when the current model uses an OAuth
+  subscription.
+
+**Middle (optional)**
+
+- Extension status text from `ctx.ui.setStatus()` is sorted by key and centered
+  in the gap between context and usage when space permits; otherwise it is
+  dropped so CTX and usage stay readable. Plain text is muted; strings that
+  already carry ANSI color are left unchanged.
+
+Zero-value usage fields are omitted. Before the first assistant response, the
+right side of line 2 is empty (or holds extension status only).
+
+## Narrow-width drop order
+
+When the terminal is too narrow for the full layout:
+
+**Line 1** (first drop → last):
+
+1. Drop the git branch.
+2. Keep the full path alone on the right.
+3. Shorten the path to `~/basename` (or bare basename).
+4. Drop the provider parentheses.
+5. Truncate the remaining left/right text.
+
+**Line 2** (first drop → last):
+
+1. Drop extension status from the middle gap.
+2. Drop `W`, then `R`, from the usage cluster.
+3. Truncate CTX / remaining usage as a last resort.
+
+## Layout and colors
+
+- Model name uses `toolTitle` and bold; provider uses `muted`.
+- Effort uses Pi's thinking-level color.
+- Context uses `accent`, `warning`, or `error` according to the fixed thresholds.
+- Working directory uses `success`; Git branch uses `accent`.
+- Usage statistics use `dim`; extension status text uses `muted`.
+- Each line left-aligns its primary cluster and right-aligns the secondary
+  cluster, filling the gap with spaces so wide terminals stay balanced.
+
+Pi does not expose auto-compaction state to extension footer factories, so the
+native `(auto)` marker is intentionally not reproduced.
+
+## Migration
+
+The previous `/statusline` command and `~/.pi/agent/pi-config/statusline.json`
+configuration are no longer used. An existing config file is left untouched and
+may be removed manually.
+
+## Limits
+
+- Auto-enables only in TUI mode on `session_start`; RPC and print modes have no TUI footer.
+- The native `(auto)` compaction marker is not reproduced because Pi does not expose that state to extensions.
+
+## Implementation notes
+
+Footer paint is hot (every TUI render). The extension caches:
+
+- **Branch path** by current leaf id.
+- **Branch stats** (thinking level + cumulative usage) by branch length, leaf entry identity, and a leaf usage fingerprint.
+
+Both caches clear on footer `invalidate()`.
+

package/docs/bundled/extensions/subagent.md

@@ -0,0 +1,95 @@
+# subagent — isolated foreground delegation
+
+Adds the `subagent` tool and `/agents` profile settings command. It delegates a bounded task to an isolated in-process `AgentSession`; it is not a background worker or a fleet manager.
+
+## Tool modes
+
+Exactly one mode is required per call:
+
+- **Single**: `agent`, `description`, and `prompt`.
+- **Parallel**: `tasks`, an array of independent task objects.
+- **Chain**: `chain`, an array of sequential task objects. `{previous}` in a later prompt is replaced by the previous worker's bounded final response.
+
+Every task object has:
+
+```text
+agent?       Agent profile name; defaults to general
+description  Short UI label
+prompt       Self-contained worker briefing
+cwd?         Relative directory inside the parent working directory
+model?       Temporary provider/model override
+thinking?    Temporary thinking-level override
+```
+
+Parallel and chain batches allow at most eight tasks. A session-scoped gate runs at most three workers concurrently, including sibling `subagent` calls from the same parent session.
+
+## Agent profiles
+
+Profiles are Markdown files with YAML frontmatter:
+
+```yaml
+---
+name: reviewer
+description: Read-only implementation reviewer
+tools: read, grep, find, ls
+model: anthropic/claude-sonnet-4-5
+thinking: medium
+backend: sdk
+---
+
+Review the delegated task independently and report exact evidence.
+```
+
+Sources and precedence are:
+
+```text
+built-in < ~/.pi/agent/agents/*.md < trusted-project/.pi/agents/*.md
+```
+
+Project definitions are loaded only after Pi trusts the project. Invalid Markdown definitions appear as `/agents` diagnostics without hiding valid profiles.
+
+Built-in profiles:
+
+- `general`: read, bash, edit, write, grep, find, and ls.
+- `explorer`: read-only `read`, `grep`, `find`, and `ls`, with low thinking by default.
+
+A profile may only allow Pi built-in tools. Child sessions load no extensions, skills, or prompt templates, so a worker cannot recursively call `subagent` or inherit unrelated extension capabilities. Project context files such as `AGENTS.md` remain available.
+
+## Model and thinking selection
+
+The model/thinking resolution order is:
+
+```text
+per-call tool fields
+  > saved /agents profile override
+  > profile Markdown frontmatter
+  > current parent session
+```
+
+Run `/agents` to choose a profile and set either field to:
+
+- **inherit**: force the active parent-session value;
+- **agent default**: clear the saved override and use Markdown/default inheritance;
+- a configured `provider/model` or explicit supported thinking level.
+
+Overrides are user-owned and saved atomically in:
+
+```text
+~/.pi/agent/subagent.json
+```
+
+They apply only to future subagent runs and never change the parent session's `/model` or thinking level.
+
+## Lifecycle and output
+
+- The parent tool call waits until every worker reaches a terminal state.
+- Parent abort, `/reload`, `/new`, `/resume`, `/fork`, and session shutdown abort active child sessions. Queued workers do not survive the call.
+- Parallel worker failures do not cancel other independent workers. A failed or aborted chain step skips its remaining steps.
+- Progress is rendered in Pi's native tool transcript. The collapsed view shows status, recent activity, usage, and the configured expand hint; `Ctrl+O` shows bounded activities and final Markdown reports.
+- Full child transcripts are not stored separately. Bounded run details remain in the parent tool result, so completed calls restore naturally in the parent session tree.
+- Nested usage is returned with the tool result and included in parent session accounting.
+
+## Deliberate non-features
+
+There are no background agents, persistent worker IDs, unread state, fleet panel, statusline widget, send/stop/resume control plane, completion notifications, swarm/coordinator, worktree isolation, nested agents, MCP, hooks, or agent memory.
+

package/docs/bundled/extensions/todo.md

@@ -0,0 +1,28 @@
+# todo — task list overlay
+
+Adds a `todo` tool plus `/todos` for multi-step work, with a live overlay above the editor.
+
+## Behavior
+
+- Actions: `create`, `update`, `list`, `get`, `delete`, `clear`. Statuses: `pending`, `in_progress`, `completed`, `deleted`. `list` accepts an optional `status` filter and `includeDeleted`; `status: "deleted"` includes tombstones directly.
+- The live overlay renders above the editor and hides itself when there are no visible tasks.
+- Creation always starts a task as `pending`; `blockedBy` dependencies are supported for sequencing, and missing dependencies, deleted dependencies, self-dependencies, and cycles are rejected. A task cannot move to `in_progress` or `completed` until every `blockedBy` dependency is `completed`.
+- Deletion — via `delete` or `update` with `status: "deleted"` — leaves an immutable tombstone for branch history, removes that task from every dependent `blockedBy` list, and therefore releases dependents. `clear` empties the list without reusing ids.
+- Newly completed tasks remain visible for 30 seconds, then drop from the overlay; historical completions loaded by `/reload` or `/tree` stay hidden so live work remains prominent.
+- **Exactly one `in_progress`.** Moving a task to `in_progress` auto-demotes any other `in_progress` tasks to `pending`; the tool result lists demoted ids so the model sees the side effect.
+- **Verification soft nudge.** When a completion leaves the list fully done with 3+ completed tasks and no subject/description matching `verif|test|check|review`, the tool result appends a short NOTE (text only — `details` schema unchanged).
+
+## Limits
+
+- `list` output is bounded at 50 items by default, with a trailing notice when truncated.
+- The overlay body is capped at 10 rows; its truncation summary includes hidden status counts.
+- Newly completed tasks remain visible for 30 seconds then drop from the overlay.
+
+## Implementation notes
+
+- **Conversation-backed state.** Every tool result stores a full snapshot in `details`; lifecycle handlers replay the current branch on `/reload`, compaction, and session-tree navigation. There is no separate disk database. Compaction-safe by design: `sessionManager.getBranch()` returns the full branch history — only `buildSessionContext` summarizes for the LLM. Replay walks the branch **tail → head** and stops at the latest todo `toolResult`.
+- **State is keyed per session id.** Resume and `/tree` can switch sessions within one process; `execute` and the lifecycle handlers re-point the active bucket before touching state.
+- **Status transitions are gated.** `completed` can be reopened to `in_progress` or `pending`, but a `deleted` tombstone is terminal. Single-active is enforced on demote (not hard-reject) so the model does not need a retry loop.
+- **Tool execution is sequential** (`executionMode: "sequential"`) so parallel tool calls cannot race on in-memory state. Validation failures **throw** so Pi marks `isError: true` and the branch replays the last good snapshot.
+- **Overlay paint is pure + width-cached.** Completion visibility bookkeeping runs in `update()` plus a disposable timeout, never during `render`. Same terminal width reuses the last line array.
+

package/docs/bundled/themes.md

@@ -0,0 +1,51 @@
+# Bundled theme design
+
+This document describes the themes shipped in the `@astralyn/pi` package. For theme discovery, JSON format, and custom theme authoring, see the [Theme API documentation](../themes.md).
+
+The package bundles two Pi themes using the native theme schema and loader:
+
+| Theme | Use |
+|---|---|
+| `ice-cream-dark` | Cool sea-salt dark palette with warm cream tool titles. |
+| `ice-cream-light` | Light counterpart with the same semantic mapping. |
+
+Both themes are built into `@astralyn/pi`. They do not require the external `pi-config` package.
+
+## Selecting a theme
+
+Use `/settings`, or set a single theme:
+
+```json
+{
+  "theme": "ice-cream-dark"
+}
+```
+
+For automatic terminal light/dark selection:
+
+```json
+{
+  "theme": "ice-cream-light/ice-cream-dark"
+}
+```
+
+The left side is used for light terminals and the right side for dark terminals.
+
+## Design intent
+
+The palette keeps an ice-cream / sea-salt identity: cool cyan-blue accents with warm cream tooling on a calm neutral base.
+
+- `accent` and borders use the sea-salt family;
+- `toolTitle` uses cream/gold tones;
+- `toolOutput`, `muted`, and `dim` form a readable text ladder;
+- tool backgrounds remain transparent so the native `●` / `│` presentation stays light;
+- `success`, `error`, and `warning` remain semantic pastel colors;
+- thinking levels move from cool blue through green and gold to coral/red.
+
+## Extension UI
+
+Bundled dialogs, overlays, and the statusline use semantic theme helpers such as `theme.fg(...)` and `theme.bg(...)`. They do not hard-code ANSI colors or hex values.
+
+## Theme assets
+
+The built-in theme names are stable user-facing identifiers. In an installed package, the JSON assets are available under `dist/modes/interactive/theme/` if you need to inspect them; normal use does not require accessing those internal files.