@astralyn/pi 0.82.2 → 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/{distribution → bundled}/extensions/question.md

@@ -46,14 +46,3 @@ The transcript uses a private `renderCall` / `renderResult` only to replace raw
 - `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.
 
-**Files:**
-
-- `constants.ts` — tool identity and model-facing prompt copy
-- `index.ts` — tool registration and execution
-- `dialog.ts` — interactive dialog, review, and discussion flow
-- `schema.ts` — params and semantic validation
-- `state.ts` — per-question dialog state helpers and answer ordering
-- `results.ts` — bounded model-result builders
-- `render.ts` — compact transcript summaries within Pi's native tool frame
-- `limits.ts` — UI and model-output budgets
-- `types.ts` — shared interfaces and the `OTHER_OPTION` sentinel

package/docs/{distribution → bundled}/extensions/rewind.md

@@ -71,15 +71,5 @@ rebuilt from them on `session_start`.
 - **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).
 
-**Files:**
-
-- `index.ts` — lifecycle hooks (`tool_call`, `before_agent_start`, `agent_settled`, `session_start`, `session_before_tree`/`session_tree`, `session_shutdown`) and the `/rewind` command
-- `engine.ts` — the file-history backup engine (track / snapshot / apply / resume-migrate), ported from Claude Code's file-history
-- `snapshot.ts` — persisted snapshot data shapes (pure)
-- `config.ts` — load/save `rewind/config.json`
-- `gc.ts` — age + orphan storage reclamation; storage inventory for the menu
-- `menu.ts` — the `/rewind` settings + storage menu
-- `restore.ts` — `/tree`-target → snapshot matching and restore
-- `paths.ts`, `text.ts`, `tool-path.ts` — private helpers owned by this plugin
 
 Architecture informed by oh-my-pi (GPL-3.0) and Claude Code's file-history; independent implementation.

package/docs/{distribution → bundled}/extensions/router.md

@@ -4,7 +4,7 @@
 
 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](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/providers.md), [custom-provider.md](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/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.
+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.
 
 ---
 
@@ -123,17 +123,4 @@ Session affinity headers use hyphenated form (`session-id`, `x-client-request-id
 
 **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.
 
-**Files:**
 
-| File | Role |
-|:-:|:-:|
-| `index.ts` | Async factory: load config, register providers, handle `/router` commands |
-| `store.ts` | `router.json` read / write |
-| `register.ts` | `registerProvider` / unregister |
-| `stream.ts` | Wraps `openAIResponsesApi` + payload reshape |
-| `probe.ts` | `GET …/models` catalog fetch |
-| `presets.ts` | 272k defaults + thinking-level map helpers |
-| `dialog.ts` | Selectors, multi-select, thinking editor (dirty Esc warning) |
-| `ui.ts` | Command flows; auto-save on relay mutations |
-| `constants.ts` | Command name, defaults, `router-codex` API tag |
-| `types.ts` | Config types |

package/docs/{distribution → bundled}/extensions/statusline.md

@@ -95,7 +95,7 @@ may be removed manually.
 
 ## Limits
 
-- Auto-enables only in TUI mode on `session_start`; RPC and print modes show the upstream footer.
+- 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
@@ -107,4 +107,3 @@ Footer paint is hot (every TUI render). The extension caches:
 
 Both caches clear on footer `invalidate()`.
 
-**Files:** `index.ts` — footer lifecycle, formatting, usage aggregation, and responsive two-line left/right layout.

package/docs/{distribution → bundled}/extensions/subagent.md

@@ -93,10 +93,3 @@ They apply only to future subagent runs and never change the parent session's `/
 
 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.
 
-**Files:** `src/extensions/subagent/`
-
-- `index.ts` — registration, parent provider synchronization, `/agents`, shutdown cleanup
-- `agents.ts` / `settings.ts` / `resolve.ts` — profile discovery, persistent overrides, task validation
-- `sdk-runner.ts` / `runner.ts` — isolated sessions, progress, abort, concurrency, modes
-- `activity.ts` / `render.ts` — bounded evidence, usage, native transcript rendering
-- `schema.ts` / `types.ts` / `constants.ts` — public tool contract and data model

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/{distribution → bundled}/themes.md

@@ -1,8 +1,8 @@
 # Bundled theme design
 
-This document describes the themes shipped by the distribution. For theme discovery, JSON format, and custom theme authoring, see the [Theme API documentation](../themes.md).
+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 Fork bundles two Pi themes using the native theme schema and loader:
+The package bundles two Pi themes using the native theme schema and loader:
 
 | Theme | Use |
 |---|---|
@@ -46,13 +46,6 @@ The palette keeps an ice-cream / sea-salt identity: cool cyan-blue accents with
 
 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 files
+## Theme assets
 
-The source assets are:
-
-```text
-src/modes/interactive/theme/ice-cream-dark.json
-src/modes/interactive/theme/ice-cream-light.json
-```
-
-The normal package build copies all theme JSON assets into the runtime package. The themes use the schema at `src/modes/interactive/theme/theme-schema.json`.
+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.

package/docs/{distribution → bundled}/tool-presentation.md

@@ -1,6 +1,6 @@
 # Native tool presentation
 
-This Fork changes Pi's native tool transcript presentation rather than replacing it with a separate `tools-view` extension.
+The `@astralyn/pi` package uses Pi's native tool transcript presentation rather than replacing it with a separate `tools-view` extension.
 
 ## Visual language
 
@@ -20,13 +20,7 @@ States use the same shell:
 
 ## Implementation boundary
 
-The main entry point is:
-
-```text
-src/modes/interactive/components/tool-execution.ts
-```
-
-It owns:
+The native tool presentation owns:
 
 - the default call/result shell;
 - pending, success, and error states;
@@ -43,7 +37,7 @@ Consecutive tools may opt into a shared collapsed group through `toolGroup`. Bui
 
 | Tool definition | Behavior |
 |---|---|
-| No `renderCall`/`renderResult` | Uses the Fork's native call and result fallback. |
+| No `renderCall`/`renderResult` | Uses the package's native call and result fallback. |
 | Custom renderer with the default shell | Uses the native shell around the custom content. |
 | `renderShell: "self"` | Keeps complete ownership of the tool's layout. |
 
@@ -80,7 +74,7 @@ The native path continues to preserve:
 
 ## Deliberately rejected approaches
 
-This Fork does not use:
+The package does not use:
 
 - prototype patching of `ToolExecutionComponent` from an extension;
 - same-name re-registration to replace built-in tools;

package/docs/compaction.md

@@ -2,12 +2,12 @@
 
 LLMs have limited context windows. When conversations grow too long, pi uses compaction to summarize older content while preserving recent work. This page covers both auto-compaction and branch summarization.
 
-**Source files** ([pi-mono](https://github.com/earendil-works/pi-mono)):
-- [`packages/coding-agent/src/core/compaction/compaction.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/compaction/compaction.ts) - Auto-compaction logic
-- [`packages/coding-agent/src/core/compaction/branch-summarization.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/compaction/branch-summarization.ts) - Branch summarization
-- [`packages/coding-agent/src/core/compaction/utils.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/compaction/utils.ts) - Shared utilities (file tracking, serialization)
-- [`packages/coding-agent/src/core/session-manager.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/session-manager.ts) - Entry types (`CompactionEntry`, `BranchSummaryEntry`)
-- [`packages/coding-agent/src/core/extensions/types.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/extensions/types.ts) - Extension event types
+**Source files** ([ming-kang/pi](https://github.com/ming-kang/pi)):
+- [`src/core/compaction/compaction.ts`](https://github.com/ming-kang/pi/blob/main/src/core/compaction/compaction.ts) - Auto-compaction logic
+- [`src/core/compaction/branch-summarization.ts`](https://github.com/ming-kang/pi/blob/main/src/core/compaction/branch-summarization.ts) - Branch summarization
+- [`src/core/compaction/utils.ts`](https://github.com/ming-kang/pi/blob/main/src/core/compaction/utils.ts) - Shared utilities (file tracking, serialization)
+- [`src/core/session-manager.ts`](https://github.com/ming-kang/pi/blob/main/src/core/session-manager.ts) - Entry types (`CompactionEntry`, `BranchSummaryEntry`)
+- [`src/core/extensions/types.ts`](https://github.com/ming-kang/pi/blob/main/src/core/extensions/types.ts) - Extension event types
 
 For TypeScript definitions in your project, inspect `node_modules/@astralyn/pi/dist/`.
 
@@ -124,7 +124,7 @@ Never cut at tool results (they must stay with their tool call).
 
 ### CompactionEntry Structure
 
-Defined in [`session-manager.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/session-manager.ts):
+Defined in [`session-manager.ts`](https://github.com/ming-kang/pi/blob/main/src/core/session-manager.ts):
 
 ```typescript
 interface CompactionEntry<T = unknown> {
@@ -149,7 +149,7 @@ interface CompactionDetails {
 
 Extensions can store any JSON-serializable data in `details`. The default compaction tracks file operations, but custom extension implementations can use their own structure. Generated and extension-provided summaries store their LLM `usage` when available so session totals include summarization work.
 
-See [`prepareCompaction()`](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/compaction/compaction.ts) and [`compact()`](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/compaction/compaction.ts) for the implementation. For direct programmatic summarization, `generateSummary()` returns the summary text and `generateSummaryWithUsage()` returns `{ text, usage }`.
+See [`prepareCompaction()`](https://github.com/ming-kang/pi/blob/main/src/core/compaction/compaction.ts) and [`compact()`](https://github.com/ming-kang/pi/blob/main/src/core/compaction/compaction.ts) for the implementation. For direct programmatic summarization, `generateSummary()` returns the summary text and `generateSummaryWithUsage()` returns `{ text, usage }`.
 
 ## Branch Summarization
 
@@ -192,7 +192,7 @@ This means file tracking accumulates across multiple compactions or nested branc
 
 ### BranchSummaryEntry Structure
 
-Defined in [`session-manager.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/session-manager.ts):
+Defined in [`session-manager.ts`](https://github.com/ming-kang/pi/blob/main/src/core/session-manager.ts):
 
 ```typescript
 interface BranchSummaryEntry<T = unknown> {
@@ -216,7 +216,7 @@ interface BranchSummaryDetails {
 
 Same as compaction, extensions can store custom data in `details`.
 
-See [`collectEntriesForBranchSummary()`](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/compaction/branch-summarization.ts), [`prepareBranchEntries()`](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/compaction/branch-summarization.ts), and [`generateBranchSummary()`](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/compaction/branch-summarization.ts) for the implementation.
+See [`collectEntriesForBranchSummary()`](https://github.com/ming-kang/pi/blob/main/src/core/compaction/branch-summarization.ts), [`prepareBranchEntries()`](https://github.com/ming-kang/pi/blob/main/src/core/compaction/branch-summarization.ts), and [`generateBranchSummary()`](https://github.com/ming-kang/pi/blob/main/src/core/compaction/branch-summarization.ts) for the implementation.
 
 ## Summary Format
 
@@ -260,7 +260,7 @@ path/to/changed.ts
 
 ### Message Serialization
 
-Before summarization, messages are serialized to text via [`serializeConversation()`](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/compaction/utils.ts):
+Before summarization, messages are serialized to text via [`serializeConversation()`](https://github.com/ming-kang/pi/blob/main/src/core/compaction/utils.ts):
 
 ```
 [User]: What they said
@@ -276,7 +276,7 @@ Tool results are truncated to 2000 characters during serialization. Content beyo
 
 ## Custom Summarization via Extensions
 
-Extensions can intercept and customize both compaction and branch summarization. See [`extensions/types.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/extensions/types.ts) for event type definitions.
+Extensions can intercept and customize both compaction and branch summarization. See [`extensions/types.ts`](https://github.com/ming-kang/pi/blob/main/src/core/extensions/types.ts) for event type definitions.
 
 ### session_before_compact
 

package/docs/custom-provider.md

@@ -397,12 +397,12 @@ interface OAuthCredentials {
 For providers with non-standard APIs, implement `streamSimple`. Study the existing provider implementations before writing your own:
 
 **Reference implementations:**
-- [anthropic.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/providers/anthropic.ts) - Anthropic Messages API
-- [mistral.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/providers/mistral.ts) - Mistral Conversations API
-- [openai-completions.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/providers/openai-completions.ts) - OpenAI Chat Completions
-- [openai-responses.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/providers/openai-responses.ts) - OpenAI Responses API
-- [google.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/providers/google.ts) - Google Generative AI
-- [amazon-bedrock.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/providers/amazon-bedrock.ts) - AWS Bedrock
+- [anthropic.ts](https://github.com/earendil-works/pi/blob/v0.82.1/packages/ai/src/providers/anthropic.ts) - Anthropic Messages API
+- [mistral.ts](https://github.com/earendil-works/pi/blob/v0.82.1/packages/ai/src/providers/mistral.ts) - Mistral Conversations API
+- [openai-completions.ts](https://github.com/earendil-works/pi/blob/v0.82.1/packages/ai/src/providers/openai-completions.ts) - OpenAI Chat Completions
+- [openai-responses.ts](https://github.com/earendil-works/pi/blob/v0.82.1/packages/ai/src/providers/openai-responses.ts) - OpenAI Responses API
+- [google.ts](https://github.com/earendil-works/pi/blob/v0.82.1/packages/ai/src/providers/google.ts) - Google Generative AI
+- [amazon-bedrock.ts](https://github.com/earendil-works/pi/blob/v0.82.1/packages/ai/src/providers/amazon-bedrock.ts) - AWS Bedrock
 
 ### Stream Pattern
 
@@ -565,7 +565,7 @@ When a request exceeds the model's context window, pi can recover automatically
 Detection runs on the finalized assistant message:
 
 - `stopReason === "error"`
-- `errorMessage` matches one of pi's known overflow patterns (see [`packages/ai/src/utils/overflow.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/utils/overflow.ts))
+- `errorMessage` matches one of pi's known overflow patterns (see [`packages/ai/src/utils/overflow.ts`](https://github.com/earendil-works/pi/blob/v0.82.1/packages/ai/src/utils/overflow.ts))
 
 If your provider returns overflow errors with a message pi does not recognize, normalize the error from the same extension that registers the provider. Use a `message_end` handler to rewrite the assistant message so its `errorMessage` starts with a phrase pi recognizes. The generic fallback `context_length_exceeded` is the safest choice.
 
@@ -628,7 +628,7 @@ pi.registerProvider("my-provider", {
 
 ## Testing Your Implementation
 
-Test your provider against the same test suites used by built-in providers. Copy and adapt these test files from [packages/ai/test/](https://github.com/earendil-works/pi-mono/tree/main/packages/ai/test):
+Test your provider against the same test suites used by built-in providers. Copy and adapt these test files from [packages/ai/test/](https://github.com/earendil-works/pi/tree/v0.82.1/packages/ai/test):
 
 | Test | Purpose |
 |------|---------|

package/docs/docs.json

@@ -19,6 +19,10 @@
           "title": "Providers",
           "path": "providers.md"
         },
+        {
+          "title": "llama.cpp",
+          "path": "llama-cpp.md"
+        },
         {
           "title": "Security",
           "path": "security.md"
@@ -45,6 +49,55 @@
         }
       ]
     },
+    {
+      "title": "Bundled features",
+      "items": [
+        {
+          "title": "Overview",
+          "path": "bundled/README.md"
+        },
+        {
+          "title": "Extension catalog",
+          "path": "bundled/extensions/README.md"
+        },
+        {
+          "title": "DeepWiki",
+          "path": "bundled/extensions/deepwiki.md"
+        },
+        {
+          "title": "Question",
+          "path": "bundled/extensions/question.md"
+        },
+        {
+          "title": "Rewind",
+          "path": "bundled/extensions/rewind.md"
+        },
+        {
+          "title": "Router",
+          "path": "bundled/extensions/router.md"
+        },
+        {
+          "title": "Statusline",
+          "path": "bundled/extensions/statusline.md"
+        },
+        {
+          "title": "Subagent",
+          "path": "bundled/extensions/subagent.md"
+        },
+        {
+          "title": "Todo",
+          "path": "bundled/extensions/todo.md"
+        },
+        {
+          "title": "Bundled themes",
+          "path": "bundled/themes.md"
+        },
+        {
+          "title": "Native tool presentation",
+          "path": "bundled/tool-presentation.md"
+        }
+      ]
+    },
     {
       "title": "Customization",
       "items": [
@@ -81,6 +134,10 @@
     {
       "title": "Reference",
       "items": [
+        {
+          "title": "Environment Variables",
+          "path": "environment-variables.md"
+        },
         {
           "title": "Session Format",
           "path": "session-format.md"
@@ -132,15 +189,6 @@
           "path": "shell-aliases.md"
         }
       ]
-    },
-    {
-      "title": "Development",
-      "items": [
-        {
-          "title": "Development",
-          "path": "development.md"
-        }
-      ]
     }
   ],
   "redirects": [

package/docs/extensions.md

@@ -2043,13 +2043,13 @@ See [examples/extensions/tool-override.ts](../examples/extensions/tool-override.
 **Your implementation must match the exact result shape**, including the `details` type. The UI and session logic depend on these shapes for rendering and state tracking.
 
 Built-in tool implementations:
-- [read.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/read.ts) - `ReadToolDetails`
-- [bash.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/bash.ts) - `BashToolDetails`
-- [edit.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/edit.ts)
-- [write.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/write.ts)
-- [grep.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/grep.ts) - `GrepToolDetails`
-- [find.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/find.ts) - `FindToolDetails`
-- [ls.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/ls.ts) - `LsToolDetails`
+- [read.ts](https://github.com/ming-kang/pi/blob/main/src/core/tools/read.ts) - `ReadToolDetails`
+- [bash.ts](https://github.com/ming-kang/pi/blob/main/src/core/tools/bash.ts) - `BashToolDetails`
+- [edit.ts](https://github.com/ming-kang/pi/blob/main/src/core/tools/edit.ts)
+- [write.ts](https://github.com/ming-kang/pi/blob/main/src/core/tools/write.ts)
+- [grep.ts](https://github.com/ming-kang/pi/blob/main/src/core/tools/grep.ts) - `GrepToolDetails`
+- [find.ts](https://github.com/ming-kang/pi/blob/main/src/core/tools/find.ts) - `FindToolDetails`
+- [ls.ts](https://github.com/ming-kang/pi/blob/main/src/core/tools/ls.ts) - `LsToolDetails`
 
 ### Remote Execution
 
@@ -2180,7 +2180,7 @@ export default function (pi: ExtensionAPI) {
 
 ### Custom Rendering
 
-Tools can provide `renderCall` and `renderResult` for custom TUI display. See [tui.md](tui.md) for the full component API and [tool-execution.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/modes/interactive/components/tool-execution.ts) for how tool rows are composed.
+Tools can provide `renderCall` and `renderResult` for custom TUI display. See [tui.md](tui.md) for the full component API and [tool-execution.ts](https://github.com/ming-kang/pi/blob/main/src/modes/interactive/components/tool-execution.ts) for how tool rows are composed.
 
 By default, tool output is wrapped in a `Box` that handles padding and background. A defined `renderCall` or `renderResult` must return a `Component`. If a slot renderer is not defined, `tool-execution.ts` uses fallback rendering for that slot.
 
@@ -2793,7 +2793,7 @@ Register a custom renderer for messages with your `customType`. Use message rend
 import { Text } from "@earendil-works/pi-tui";
 
 pi.registerMessageRenderer("my-extension", (message, options, theme) => {
-  const { expanded } = options;
+  const { expanded, outputPad } = options;
   let text = theme.fg("accent", `[${message.customType}] `);
   text += message.content;
 
@@ -2801,7 +2801,7 @@ pi.registerMessageRenderer("my-extension", (message, options, theme) => {
     text += "\n" + theme.fg("dim", JSON.stringify(message.details, null, 2));
   }
 
-  return new Text(text, 0, 0);
+  return new Text(text, outputPad, 0);
 });
 ```
 
@@ -2942,7 +2942,6 @@ All examples in [examples/extensions/](../examples/extensions/).
 | `interactive-shell.ts` | Persistent shell session | `on("user_bash")` |
 | `sandbox/` | Sandboxed tool execution | Tool operations |
 | `gondolin/` | Route built-in tools and `!` commands into a Gondolin micro-VM | Tool operations, built-in tool overrides, `on("user_bash")` |
-| `subagent/` | Spawn sub-agents | `registerTool`, `exec` |
 | **Games** |||
 | `snake.ts` | Snake game | `registerCommand`, `ui.custom`, keyboard handling |
 | `space-invaders.ts` | Space Invaders game | `registerCommand`, `ui.custom` |

package/docs/index.md

@@ -1,8 +1,8 @@
-# Pi user and API documentation
+# @astralyn/pi user and API documentation
 
-Pi is a minimal terminal coding harness. It is designed to stay small at the core while being extended through TypeScript extensions, skills, prompt templates, themes, and pi packages.
+@astralyn/pi is a minimal terminal coding harness. It is designed to stay small at the core while being extended through TypeScript extensions, skills, prompt templates, themes, and pi packages.
 
-This documentation covers product usage and public APIs. Distribution architecture, bundled behavior, upstream synchronization, and publishing are documented in [`docs/distribution/`](distribution/README.md).
+This documentation is owned by @astralyn/pi and describes the behavior of the installed npm package, including its bundled features and public APIs. Upstream Pi documentation and release tags are used only as synchronization input; they are not the user-facing source for these docs.
 
 ## Quick start
 
@@ -45,6 +45,15 @@ For the full first-run flow, see [Quickstart](quickstart.md).
 - [Sessions](sessions.md) - session management, branching, and tree navigation.
 - [Compaction](compaction.md) - context compaction and branch summarization.
 
+## Bundled features
+
+The installed package includes built-in extensions, themes, and native tool presentation:
+
+- [Bundled overview](bundled/README.md) - package features and how they fit together.
+- [Bundled extensions](bundled/extensions/README.md) - catalog and links to every bundled extension.
+- [Bundled themes](bundled/themes.md) - the ice-cream themes included with the package.
+- [Native tool presentation](bundled/tool-presentation.md) - the shared tool-call and result layout.
+
 ## Customization
 
 - [Extensions](extensions.md) - TypeScript modules for tools, commands, events, and custom UI.
@@ -74,7 +83,3 @@ For the full first-run flow, see [Quickstart](quickstart.md).
 - [tmux](tmux.md)
 - [Terminal setup](terminal-setup.md)
 - [Shell aliases](shell-aliases.md)
-
-## Development
-
-- [Development](development.md) - local setup, project structure, and debugging.

package/docs/json.md

@@ -8,7 +8,7 @@ Outputs all session events as JSON lines to stdout. Useful for integrating pi in
 
 ## Event Types
 
-Events are defined in [`AgentSessionEvent`](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/agent-session.ts#L102):
+Events are defined in [`AgentSessionEvent`](https://github.com/ming-kang/pi/blob/main/src/core/agent-session.ts#L102):
 
 ```typescript
 type AgentSessionEvent =
@@ -26,7 +26,7 @@ type AgentSessionEvent =
 
 `queue_update` emits the full pending steering and follow-up queues whenever they change. `compaction_start` and `compaction_end` cover both manual and automatic compaction.
 
-Base events from [`AgentEvent`](https://github.com/earendil-works/pi-mono/blob/main/packages/agent/src/types.ts#L179):
+Base events from [`AgentEvent`](https://github.com/earendil-works/pi/blob/v0.82.1/packages/agent/src/types.ts#L179):
 
 ```typescript
 type AgentEvent =
@@ -48,12 +48,12 @@ type AgentEvent =
 
 ## Message Types
 
-Base messages from [`packages/ai/src/types.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/types.ts#L134):
+Base messages from [`packages/ai/src/types.ts`](https://github.com/earendil-works/pi/blob/v0.82.1/packages/ai/src/types.ts#L134):
 - `UserMessage` (line 134)
 - `AssistantMessage` (line 140)
 - `ToolResultMessage` (line 152)
 
-Extended messages from [`packages/coding-agent/src/core/messages.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/messages.ts#L29):
+Extended messages from [`src/core/messages.ts`](https://github.com/ming-kang/pi/blob/main/src/core/messages.ts#L29):
 - `BashExecutionMessage` (line 29)
 - `CustomMessage` (line 46)
 - `BranchSummaryMessage` (line 55)

package/docs/providers.md

@@ -101,7 +101,7 @@ pi
 | Xiaomi MiMo Token Plan (Amsterdam) | `XIAOMI_TOKEN_PLAN_AMS_API_KEY` | `xiaomi-token-plan-ams` |
 | Xiaomi MiMo Token Plan (Singapore) | `XIAOMI_TOKEN_PLAN_SGP_API_KEY` | `xiaomi-token-plan-sgp` |
 
-Reference for environment variables and `auth.json` keys: [`const envMap`](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/env-api-keys.ts) in [`packages/ai/src/env-api-keys.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/env-api-keys.ts).
+Reference for environment variables and `auth.json` keys: [`const envMap`](https://github.com/earendil-works/pi/blob/v0.82.1/packages/ai/src/env-api-keys.ts) in [`packages/ai/src/env-api-keys.ts`](https://github.com/earendil-works/pi/blob/v0.82.1/packages/ai/src/env-api-keys.ts).
 
 #### Auth File
 

package/docs/rpc.md

@@ -2,7 +2,7 @@
 
 RPC mode enables headless operation of the coding agent via a JSON protocol over stdin/stdout. This is useful for embedding the agent in other applications, IDEs, or custom UIs.
 
-**Note for Node.js/TypeScript users**: If you're building a Node.js application, consider using `AgentSession` directly from `@astralyn/pi` instead of spawning a subprocess. See [`src/core/agent-session.ts`](../src/core/agent-session.ts) for the API. For a subprocess-based TypeScript client, see [`src/modes/rpc/rpc-client.ts`](../src/modes/rpc/rpc-client.ts).
+**Note for Node.js/TypeScript users**: If you're building a Node.js application, consider using `AgentSession` directly from `@astralyn/pi` instead of spawning a subprocess; see the [public SDK API](sdk.md). For a subprocess-based client, use the RPC protocol described below. The published [RPC extension UI example](../examples/rpc-extension-ui.ts) pairs with the published [RPC demo extension](../examples/extensions/rpc-demo.ts).
 
 ## Starting RPC Mode
 
@@ -1358,11 +1358,7 @@ Parse errors:
 
 ## Types
 
-Source files:
-- [upstream AI types](https://github.com/earendil-works/pi/blob/main/packages/ai/src/types.ts) - `Model`, `UserMessage`, `AssistantMessage`, `ToolResultMessage`
-- [upstream Agent types](https://github.com/earendil-works/pi/blob/main/packages/agent/src/types.ts) - `AgentMessage`, `AgentEvent`
-- [`src/core/messages.ts`](../src/core/messages.ts) - `BashExecutionMessage`
-- [`src/modes/rpc/rpc-types.ts`](../src/modes/rpc/rpc-types.ts) - RPC command/response types, extension UI request/response types
+RPC messages use the public SDK and protocol types documented by this package. The model and agent message shapes are summarized below; applications embedding Pi should import the public API from `@astralyn/pi` rather than relying on package source files.
 
 ### Model
 
@@ -1519,9 +1515,7 @@ for event in read_events():
 
 ## Example: Interactive Client (Node.js)
 
-See [`test/rpc-example.ts`](../test/rpc-example.ts) for a complete interactive example, or [`src/modes/rpc/rpc-client.ts`](../src/modes/rpc/rpc-client.ts) for a typed client implementation.
-
-For a complete example of handling the extension UI protocol, see [`examples/rpc-extension-ui.ts`](../examples/rpc-extension-ui.ts) which pairs with the [`examples/extensions/rpc-demo.ts`](../examples/extensions/rpc-demo.ts) extension.
+For a complete interactive example, see the published [RPC extension UI example](../examples/rpc-extension-ui.ts), which pairs with the published [RPC demo extension](../examples/extensions/rpc-demo.ts). For embedded Node.js or TypeScript clients, use the [public SDK API](sdk.md).
 
 ```javascript
 const { spawn } = require("child_process");