@astralyn/pi 0.82.2 → 0.82.4

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
 
@@ -284,7 +284,7 @@ Fired before auto-compaction or `/compact`. Can cancel or provide custom summary
 
 ```typescript
 pi.on("session_before_compact", async (event, ctx) => {
-  const { preparation, branchEntries, customInstructions, reason, willRetry, signal } = event;
+  const { preparation, branchEntries, customInstructions, reason, timing, willRetry, signal } = event;
 
   // preparation.messagesToSummarize - messages to summarize
   // preparation.turnPrefixMessages - split turn prefix (if isSplitTurn)
@@ -296,10 +296,14 @@ pi.on("session_before_compact", async (event, ctx) => {
 
   // branchEntries - all entries on current branch (for custom state)
   // reason - "manual" (/compact), "threshold", or "overflow"
+  // timing - "manual", "midTurn" (between tool batches), "postRun", or "prePrompt"
   // willRetry - whether overflow recovery intends to retry if compaction produces a safe retained context
   // signal - AbortSignal (pass to LLM calls)
 
-  // Cancel:
+  // Cancel. Consequences depend on timing: a "midTurn" cancel skips compaction
+  // for the rest of the run and the run continues at your risk of overflowing;
+  // other timings leave the over-threshold context to fail closed before the
+  // next provider request.
   return { cancel: true };
 
   // Custom summary:

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,59 @@
         }
       ]
     },
+    {
+      "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": "Plan",
+          "path": "bundled/extensions/plan.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 +138,10 @@
     {
       "title": "Reference",
       "items": [
+        {
+          "title": "Environment Variables",
+          "path": "environment-variables.md"
+        },
         {
           "title": "Session Format",
           "path": "session-format.md"
@@ -132,15 +193,6 @@
           "path": "shell-aliases.md"
         }
       ]
-    },
-    {
-      "title": "Development",
-      "items": [
-        {
-          "title": "Development",
-          "path": "development.md"
-        }
-      ]
     }
   ],
   "redirects": [

package/docs/extensions.md

@@ -454,12 +454,14 @@ Fired on compaction. See [compaction.md](compaction.md) for details.
 
 ```typescript
 pi.on("session_before_compact", async (event, ctx) => {
-  const { preparation, branchEntries, customInstructions, reason, willRetry, signal } = event;
+  const { preparation, branchEntries, customInstructions, reason, timing, willRetry, signal } = event;
 
   // reason - "manual" (/compact), "threshold", or "overflow"
+  // timing - "manual", "midTurn" (between tool batches), "postRun", or "prePrompt"
   // willRetry - whether overflow recovery intends to retry if compaction produces a safe retained context
 
-  // Cancel:
+  // Cancel. A "midTurn" cancel skips compaction for the rest of the run and the
+  // run continues at your risk; other timings fail closed on the oversized context.
   return { cancel: true };
 
   // Custom summary:
@@ -2043,13 +2045,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 +2182,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 +2795,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 +2803,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 +2944,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");

package/docs/session-format.md

@@ -28,11 +28,11 @@ Existing sessions are automatically migrated to the current version (v3) when lo
 
 ## Source Files
 
-Source on GitHub ([pi-mono](https://github.com/earendil-works/pi-mono)):
-- [`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) - Session entry types and SessionManager
-- [`packages/coding-agent/src/core/messages.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/messages.ts) - Extended message types (BashExecutionMessage, CustomMessage, etc.)
-- [`packages/ai/src/types.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/types.ts) - Base message types (UserMessage, AssistantMessage, ToolResultMessage)
-- [`packages/agent/src/types.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/agent/src/types.ts) - AgentMessage union type
+Distribution source on GitHub ([ming-kang/pi](https://github.com/ming-kang/pi)):
+- [`src/core/session-manager.ts`](https://github.com/ming-kang/pi/blob/main/src/core/session-manager.ts) - Session entry types and SessionManager
+- [`src/core/messages.ts`](https://github.com/ming-kang/pi/blob/main/src/core/messages.ts) - Extended message types (BashExecutionMessage, CustomMessage, etc.)
+- [`packages/ai/src/types.ts`](https://github.com/earendil-works/pi/blob/v0.82.1/packages/ai/src/types.ts) - Base message types (UserMessage, AssistantMessage, ToolResultMessage)
+- [`packages/agent/src/types.ts`](https://github.com/earendil-works/pi/blob/v0.82.1/packages/agent/src/types.ts) - AgentMessage union type
 
 For TypeScript definitions in your project, inspect `node_modules/@astralyn/pi/dist/` and `node_modules/@earendil-works/pi-ai/dist/`.
 

package/docs/skills.md

@@ -131,7 +131,7 @@ cd /path/to/skill && npm install
 Use relative paths from the skill directory:
 
 ```markdown
-See [the reference guide](references/REFERENCE.md) for details.
+See the reference guide at `references/REFERENCE.md` for details.
 ```
 
 ## Frontmatter

package/docs/themes.md

@@ -52,7 +52,7 @@ vim ~/.pi/agent/themes/my-theme.json
 
 ```json
 {
-  "$schema": "https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
+  "$schema": "https://raw.githubusercontent.com/ming-kang/pi/main/src/modes/interactive/theme/theme-schema.json",
   "name": "my-theme",
   "vars": {
     "primary": "#00aaff",
@@ -123,7 +123,7 @@ vim ~/.pi/agent/themes/my-theme.json
 
 ```json
 {
-  "$schema": "https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
+  "$schema": "https://raw.githubusercontent.com/ming-kang/pi/main/src/modes/interactive/theme/theme-schema.json",
   "name": "my-theme",
   "vars": {
     "blue": "#0066cc",
@@ -292,10 +292,6 @@ echo $COLORTERM  # Should output "truecolor" or "24bit"
 
 ## Examples
 
-See the built-in themes:
-- [dark.json](../src/modes/interactive/theme/dark.json)
-- [light.json](../src/modes/interactive/theme/light.json)
-- [ice-cream-dark.json](../src/modes/interactive/theme/ice-cream-dark.json)
-- [ice-cream-light.json](../src/modes/interactive/theme/ice-cream-light.json)
+The built-in themes are selected by name: `dark`, `light`, `ice-cream-dark`, and `ice-cream-light`. When inspecting an installed package, their JSON assets are under `node_modules/@astralyn/pi/dist/modes/interactive/theme/` (the global-install equivalent is under Pi's npm package directory).
 
-The ice-cream palette and distribution-specific design notes are documented in [`docs/distribution/themes.md`](distribution/themes.md).
+The ice-cream palette and bundled design notes are documented in [Bundled themes](bundled/themes.md).

package/docs/tui.md

@@ -4,7 +4,7 @@
 
 Extensions and custom tools can render custom TUI components for interactive user interfaces. This page covers the component system and available building blocks.
 
-**Source:** [`@earendil-works/pi-tui`](https://github.com/earendil-works/pi-mono/tree/main/packages/tui)
+**Source:** [`@earendil-works/pi-tui@0.82.1`](https://github.com/earendil-works/pi/tree/v0.82.1/packages/tui)
 
 ## Component Interface
 

package/examples/extensions/README.md

@@ -42,7 +42,6 @@ cp permission-gate.ts ~/.pi/agent/extensions/
 | `minimal-mode.ts` | Override built-in tool rendering for minimal display (only tool calls, no output in collapsed mode) |
 | `truncated-tool.ts` | Wraps ripgrep with proper output truncation (50KB/2000 lines) |
 | `ssh.ts` | Delegate all tools to a remote machine via SSH using pluggable operations |
-| `subagent/` | Delegate tasks to specialized subagents with isolated context windows |
 
 ### Commands & UI
 

package/examples/extensions/custom-provider-anthropic/index.ts

@@ -8,15 +8,15 @@
  * - API key support via environment variable
  * - Two model definitions
  *
- * Usage:
+ * Usage (from the repository or package root):
  *   # First install dependencies
- *   cd packages/coding-agent/examples/extensions/custom-provider && npm install
+ *   npm install --prefix examples/extensions/custom-provider-anthropic
  *
  *   # With OAuth (run /login custom-anthropic first)
- *   pi -e ./packages/coding-agent/examples/extensions/custom-provider
+ *   pi -e examples/extensions/custom-provider-anthropic
  *
  *   # With API key
- *   CUSTOM_ANTHROPIC_API_KEY=sk-ant-... pi -e ./packages/coding-agent/examples/extensions/custom-provider
+ *   CUSTOM_ANTHROPIC_API_KEY=sk-ant-... pi -e examples/extensions/custom-provider-anthropic
  *
  * Then use /model to select custom-anthropic/claude-sonnet-4-5
  */

package/examples/extensions/custom-provider-gitlab-duo/index.ts

@@ -4,8 +4,8 @@
  * Provides access to GitLab Duo AI models (Claude and GPT) through GitLab's AI Gateway.
  * Delegates to pi-ai's built-in Anthropic and OpenAI streaming implementations.
  *
- * Usage:
- *   pi -e ./packages/coding-agent/examples/extensions/custom-provider-gitlab-duo
+ * Usage (from the repository or package root):
+ *   pi -e examples/extensions/custom-provider-gitlab-duo
  *   # Then /login gitlab-duo, or set GITLAB_TOKEN=glpat-...
  */
 

package/examples/extensions/dynamic-resources/dynamic.json

@@ -1,5 +1,5 @@
 {
-	"$schema": "https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
+	"$schema": "https://raw.githubusercontent.com/ming-kang/pi/main/src/modes/interactive/theme/theme-schema.json",
 	"name": "dynamic-resources",
 	"vars": {
 		"cyan": "#00d7ff",

package/examples/extensions/gondolin/index.ts

@@ -6,13 +6,11 @@
  * /workspace write through to the host; other guest filesystem changes are
  * isolated to the VM.
  *
- * Setup:
- *   cd packages/coding-agent/examples/extensions/gondolin
- *   npm install --ignore-scripts
+ * Setup (from the repository or package root):
+ *   npm install --ignore-scripts --prefix examples/extensions/gondolin
  *
- * Usage:
- *   cd /path/to/project
- *   pi -e /path/to/pi/packages/coding-agent/examples/extensions/gondolin
+ * Usage (from the project that should be mounted at /workspace):
+ *   pi -e /absolute/path/to/pi/examples/extensions/gondolin
  *
  * Requirements:
  *   - Node.js >= 23.6.0 for @earendil-works/gondolin

package/examples/extensions/message-renderer.ts

@@ -12,7 +12,7 @@ import { Box, Text } from "@earendil-works/pi-tui";
 
 export default function (pi: ExtensionAPI) {
 	// Register custom renderer for "status-update" messages
-	pi.registerMessageRenderer("status-update", (message, { expanded }, theme) => {
+	pi.registerMessageRenderer("status-update", (message, { expanded, outputPad }, theme) => {
 		const details = message.details as { level: string; timestamp: number } | undefined;
 		const level = details?.level ?? "info";
 
@@ -29,7 +29,7 @@ export default function (pi: ExtensionAPI) {
 		}
 
 		// Use Box with customMessageBg for consistent styling
-		const box = new Box(1, 1, (t) => theme.bg("customMessageBg", t));
+		const box = new Box(outputPad, 1, (t) => theme.bg("customMessageBg", t));
 		box.addChild(new Text(text, 0, 0));
 		return box;
 	});