@aliou/pi-dev-kit 0.5.0 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliou/pi-dev-kit",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "license": "MIT",
   "type": "module",
   "private": false,
@@ -39,13 +39,14 @@
     "@sinclair/typebox": "^0.34.41"
   },
   "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "0.61.0"
+    "@mariozechner/pi-coding-agent": "0.65.2",
+    "@mariozechner/pi-tui": "0.65.2"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.3.13",
     "@changesets/cli": "^2.27.11",
-    "@mariozechner/pi-coding-agent": "0.61.0",
-    "@mariozechner/pi-tui": "0.61.0",
+    "@mariozechner/pi-coding-agent": "0.65.2",
+    "@mariozechner/pi-tui": "0.65.2",
     "@types/node": "^25.0.10",
     "husky": "^9.1.7",
     "typescript": "^5.9.3"
@@ -53,6 +54,9 @@
   "peerDependenciesMeta": {
     "@mariozechner/pi-coding-agent": {
       "optional": true
+    },
+    "@mariozechner/pi-tui": {
+      "optional": true
     }
   },
   "scripts": {

package/src/skills/pi-extension/SKILL.md

@@ -9,25 +9,32 @@ Guide for creating and maintaining Pi extensions. Read the relevant reference fi
 
 ## Key Imports
 
-```typescript
-// Core types
-import type { ExtensionAPI, ExtensionContext, ToolDefinition, ProviderDefinition } from "@mariozechner/pi-coding-agent";
+Pi injects these packages via jiti at runtime. Extensions do not need to install them — they are available as peer dependencies:
 
-// Schema (TypeBox)
-import { Type } from "@mariozechner/pi-coding-agent";
-
-// TUI components
-import type { Component, Theme } from "@mariozechner/pi-tui";
-import { Text, Box, Container, Markdown, SelectList } from "@mariozechner/pi-tui";
+- `@mariozechner/pi-coding-agent` — core types, utilities, and extension APIs
+- `@mariozechner/pi-tui` — TUI components
+- `@mariozechner/pi-ai` — AI utilities (`StringEnum`, etc.)
+- `@sinclair/typebox` — schema definitions for tool parameters and related types
 
+```typescript
 // Tool UI components (from @aliou/pi-utils-ui)
 import { ToolCallHeader, ToolBody, ToolFooter } from "@aliou/pi-utils-ui";
 
+// Core types
+import type {
+  AgentToolResult,
+  AgentToolUpdateCallback,
+  ExtensionAPI,
+  ExtensionContext,
+  Theme,
+  ToolRenderResultOptions,
+} from "@mariozechner/pi-coding-agent";
+
 // Rendering utilities
-import { getMarkdownTheme, keyHint } from "@mariozechner/pi-coding-agent";
+import { getMarkdownTheme, keyHint, truncateHead, formatSize } from "@mariozechner/pi-coding-agent";
 
-// General utilities
-import { truncateHead, highlightCode, getLanguageFromPath, DynamicBorder, BorderedLoader } from "@mariozechner/pi-coding-agent";
+// TUI components
+import { Container, Markdown, Text } from "@mariozechner/pi-tui";
 ```
 
 ## Workflow
@@ -45,8 +52,9 @@ import { truncateHead, highlightCode, getLanguageFromPath, DynamicBorder, Border
 5. If the extension displays rich UI: Read `references/components.md` for TUI components and `references/messages.md` for message display patterns.
 6. If the extension tracks state: Read `references/state.md`.
 7. For less common APIs: Read `references/additional-apis.md`.
-8. If the extension adds a tool that competes with a natural bash fallback (process managers, CI watchers, search tools): inject system prompt guidance. Read the **Guidance Injection Pattern** section in `references/additional-apis.md`.
-9. Before publishing: Read `references/publish.md` and `references/documentation.md`.
+8. If the extension has user-configurable settings: Use `registerSettingsCommand` from `@aliou/pi-utils-settings`. Read `references/structure.md` for settings command and auth wizard patterns.
+9. If the extension adds a tool that competes with a natural bash fallback: use `promptSnippet` and `promptGuidelines` on the tool definition for simple guidance. Use system prompt hooks only for complex cross-tool orchestration. Read the **Guidance** section in `references/additional-apis.md`.
+10. Before publishing: Read `references/publish.md` and `references/documentation.md`.
 
 ### Modifying an Existing Extension
 
@@ -78,15 +86,11 @@ import { truncateHead, highlightCode, getLanguageFromPath, DynamicBorder, Border
 When implementing, look at these existing extensions for patterns:
 
 **Standalone repos (recommended structure):**
-- `pi-linkup` (`/Users/alioudiallo/code/src/github.com/aliou/pi-linkup/`): Tools wrapping a third-party API. Has tools, a command, custom message rendering, API key gating, system prompt guidance injection (`src/guidance.ts` + `src/hooks/system-prompt.ts`).
-- `pi-synthetic` (`/Users/alioudiallo/code/src/github.com/aliou/pi-synthetic/`): Provider + tools. Has a provider with models, a command with `custom()` component, API key gating, async entry point.
-- `pi-processes` (`/Users/alioudiallo/code/src/github.com/aliou/pi-processes/`): Multi-action tool with system prompt guidance injection (`src/guidance.ts` + `src/hooks/system-prompt.ts`), config toggle, background blocker hook.
-
-**Monorepo extensions (simpler structure):**
-- `extensions/defaults/` in this repo: Simple tool registration (get_current_time).
-- `extensions/guardrails/` in this repo: Event hooks (tool_call blocking). Has `hooks/`, `commands/`, `components/`, `utils/` directories with config types in `config.ts`.
-- `extensions/toolchain/` in this repo: Bash spawn hooks (command rewriting via `createBashTool`) combined with tool_call blockers. Has `blockers/`, `rewriters/`, `commands/`, `utils/` directories.
-- `extensions/processes/` in this repo: Multi-action tool with StringEnum parameters.
+- `pi-linkup` (`/Users/alioudiallo/code/src/pi.dev/pi-linkup/`): Tools wrapping a third-party API. Has tools with `promptSnippet`/`promptGuidelines`, custom rendering with `ToolCallHeader`/`ToolBody`/`ToolFooter`, output truncation with temp files, API key gating. Moved from system-prompt hooks to per-tool metadata.
+- `pi-synthetic` (`/Users/alioudiallo/code/src/pi.dev/pi-synthetic/`): Provider + tools. Has a provider with models, a command with `custom()` component, API key gating.
+- `pi-processes` (`/Users/alioudiallo/code/src/pi.dev/pi-processes/`): Multi-action tool with `promptSnippet`/`promptGuidelines` plus system prompt guidance hook for complex multi-tool orchestration, core `ProcessManager` class with unit tests, `ToolBody` with `showCollapsed` fields, conditional footers.
+- `pi-linear` (`/Users/alioudiallo/code/src/pi.dev/pi-linear/`): Multi-action tool with action modules, auth wizard using `Wizard` from `@aliou/pi-utils-settings`, settings command with `registerSettingsCommand`, config migrations, `ToolBody`/`ToolFooter` rendering, system prompt guidance for cross-tool orchestration.
+- `pi-obsidian` (`/Users/alioudiallo/code/src/pi.dev/pi-obsidian/`): Tools wrapping a CLI. Has a separate `obsidian-vault-core` package for domain logic. Uses `pi.exec()` for shell commands, `ToolCallHeader`/`ToolFooter` rendering, throws errors.
 
 ## Critical Rules
 
@@ -96,17 +100,22 @@ When implementing, look at these existing extensions for patterns:
 4. **Mode awareness**: Every `ctx.ui.custom()` call needs an RPC fallback (use `select`/`confirm`/`notify` -- they work in RPC). Do not use `done(undefined)` for normal interactive close paths when you detect fallback with `result === undefined`; use explicit sentinels (`null`, `"closed"`, boolean). Every `tool_call` hook with dialogs needs a `ctx.hasUI` check.
 5. **API key gating**: Check before registering tools that require the key. Providers handle missing keys internally via their `models()` function.
 6. **Tool naming**: Prefix with API name for third-party integrations (`linkup_web_search`). No prefix for internal tools (`get_current_time`).
-7. **Tool call header pattern**: Keep `renderCall` consistent: first line `[Tool Name]: [Action] [Main arg] [Option args]`, extra lines for long args. Use display names, not raw tool IDs.
+7. **Tool rendering uses `ToolCallHeader`**: First line `[Tool Name]: [Action] [Main arg] [Option args]`, long args on follow-up lines. Use display names, not raw tool IDs.
 8. **Deterministic call rendering**: Build `renderCall` with a stable extraction order (action → main arg → option args → long args), process-style. Same input should produce same header layout.
 9. **Long args placement**: Put long prompt/task/question/context strings on following lines. Keep first line scannable.
-10. **Result layout consistency**: In `renderResult`, handle `isPartial` first, start final output with a clear state summary, use `expanded` for compact-vs-full detail, and keep one blank line before any footer.
-11. **peerDependencies**: Any package Pi already ships (`@mariozechner/pi-coding-agent`, `@mariozechner/pi-tui`, `@mariozechner/pi-ai`) must be listed in `peerDependencies` with `optional: true` in `peerDependenciesMeta` if imported at runtime. Without `optional: true`, npm 7+ auto-installs peers, adding hundreds of packages on every install even though Pi already provides them. Keep them in `devDependencies` too for local type checking — `pnpm install` installs peers, so development is unaffected. Use `>=CURRENT_VERSION` range, not `*`.
-12. **Check existing components**: Before creating a new TUI component, check if `pi-tui` or `pi-coding-agent` already exports one that fits.
-13. **Forward abort signals**: Always pass `signal` through to `fetch()`, `pi.exec()`, and API client methods. A tool that ignores its signal prevents cancellation from reaching the underlying operation. Never prefix with `_signal` unless the tool truly has no async work to cancel.
-14. **Never use Node child_process APIs**: Do not use `child_process.exec`, `execSync`, `spawn`, `spawnSync`, `execFile`, or `execFileSync` to run binaries or shell scripts. Always use `pi.exec()`. `pi.exec` handles CWD, signal propagation, and output capture consistently. The only exception is if you need a long-lived streaming process with stdin/stdout piping that `pi.exec` cannot support — document the reason in code comments.
-15. **Never use `homedir()` for pi paths**: Use the SDK helpers from `@mariozechner/pi-coding-agent` instead. They respect the `PI_CODING_AGENT_DIR` env var which is used for testing and custom setups. Key functions: `getAgentDir()`, `getSettingsPath()`, `getSessionsDir()`, `getPromptsDir()`, `getToolsDir()`, `getCustomThemesDir()`, `getModelsPath()`, `getAuthPath()`, `getBinDir()`, `getDebugLogPath()`. All exported from the main package entry point.
-16. **Config uses the interface pattern**: `config.ts` defines two TypeScript interfaces (`RawConfig` with all fields optional, `ResolvedConfig` with all fields required) and a `ConfigLoader<Raw, Resolved>` instance. Do not use TypeBox schemas for config types.
-17. **Entry point deviations must be documented**: The standard entry point pattern is load config → check `enabled` → register. Deviations (no config, API-key-first ordering, no `enabled` toggle) are acceptable when justified, but must be noted in `AGENTS.md`.
+10. **Result layout**: In `renderResult(result, options, theme)`, handle `isPartial` first with a stable tool-scoped message. Detect errors by checking for missing expected fields in `details` (framework sets `details: {}` on throw). Use `ToolBody` from `@aliou/pi-utils-ui` with `showCollapsed` fields. Use `ToolFooter` conditionally (omit when empty). Use `Container`/`Markdown` for rich content.
+11. **Typed param alias**: Define `type MyToolParams = Static<typeof parameters>` at the top of each tool file. Use it everywhere instead of repeating `Static<typeof parameters>`.
+12. **Tool metadata**: Every tool must have `label` (required). Add `promptSnippet` for system prompt tool listing. Add `promptGuidelines` for usage instructions. These replace system-prompt hooks for simple tools.
+13. **Output truncation**: For tools returning large text, use `truncateHead()` from `@mariozechner/pi-coding-agent`. Write full content to temp file. Append footer with line/byte counts and temp file path.
+14. **Core/lib pattern**: Extract domain logic into modules (`client.ts`, `manager.ts`) that don't import from Pi. Tools are thin wrappers. Core modules are unit-testable with vitest.
+15. **Humanize messages**: Show display names first, IDs in dim/parens. `"Started \"backend\" (proc_42)"` not `"Started proc_42"`.
+16. **peerDependencies**: Pi injects `@mariozechner/pi-coding-agent`, `@mariozechner/pi-tui`, `@mariozechner/pi-ai`, and `@sinclair/typebox` via jiti at runtime. Any of these that your extension imports must be listed in `peerDependencies` with `optional: true` in `peerDependenciesMeta`. Without `optional: true`, npm 7+ auto-installs peers, adding hundreds of packages on every install even though Pi already provides them. Keep them in `devDependencies` too for local type checking — `pnpm install` installs peers, so development is unaffected. Use `>=CURRENT_VERSION` range, not `*`.
+17. **Check existing components**: Before creating a new TUI component, check if `pi-tui` or `pi-coding-agent` already exports one that fits.
+18. **Forward abort signals**: Always pass `signal` through to `fetch()`, `pi.exec()`, and API client methods. A tool that ignores its signal prevents cancellation from reaching the underlying operation. Never prefix with `_signal` unless the tool truly has no async work to cancel.
+19. **Never use Node child_process APIs**: Do not use `child_process.exec`, `execSync`, `spawn`, `spawnSync`, `execFile`, or `execFileSync` to run binaries or shell scripts. Always use `pi.exec()`. `pi.exec` handles CWD, signal propagation, and output capture consistently. The only exception is if you need a long-lived streaming process with stdin/stdout piping that `pi.exec` cannot support — document the reason in code comments.
+20. **Never use `homedir()` for pi paths**: Use the SDK helpers from `@mariozechner/pi-coding-agent` instead. They respect the `PI_CODING_AGENT_DIR` env var which is used for testing and custom setups. Key functions: `getAgentDir()`, `getSettingsPath()`, `getSessionsDir()`, `getPromptsDir()`, `getToolsDir()`, `getCustomThemesDir()`, `getModelsPath()`, `getAuthPath()`, `getBinDir()`, `getDebugLogPath()`. All exported from the main package entry point.
+21. **Config uses the interface pattern**: `config.ts` defines two TypeScript interfaces (`RawConfig` with all fields optional, `ResolvedConfig` with all fields required) and a `ConfigLoader<Raw, Resolved>` instance. Do not use TypeBox schemas for config types. For config migrations, use `ConfigLoader` `migrations` option. For settings UI, use `registerSettingsCommand` from `@aliou/pi-utils-settings`.
+22. **Entry point deviations must be documented**: The standard entry point pattern is load config → check `enabled` → register. Deviations (no config, API-key-first ordering, no `enabled` toggle) are acceptable when justified, but must be noted in `AGENTS.md`.
 
 ## Checklist
 
@@ -116,12 +125,17 @@ Before considering an extension complete:
 - [ ] All tools have correct execute parameter order.
 - [ ] All `onUpdate` calls use optional chaining.
 - [ ] No `.js` file extensions in imports.
-- [ ] `renderCall` uses a consistent first-line pattern (tool, action if any, main arg, options).
+- [ ] `renderCall` uses `ToolCallHeader` with consistent first-line pattern (tool, action if any, main arg, options).
 - [ ] `renderCall` arg extraction is deterministic (action → main arg → option args → long args).
 - [ ] Long call arguments are moved to follow-up lines, not crammed into first line.
-- [ ] `renderResult` handles `isPartial`, starts with a clear state summary, and uses `expanded` for compact-vs-full detail.
-- [ ] If result includes a footer, there is a blank line above it.
-- [ ] `renderResult` handles errors from thrown exceptions: checks for missing expected fields in `details` (framework passes `{}`, not `undefined`), extracts error message from `content`.
+- [ ] `renderResult` handles `isPartial` first with a stable tool-scoped message.
+- [ ] `renderResult` detects errors by checking for missing expected fields in `details` (framework sets `details: {}` on throw).
+- [ ] `renderResult` uses `ToolBody` with `showCollapsed` fields.
+- [ ] `renderResult` uses `ToolFooter` conditionally (omits when empty).
+- [ ] Every tool has `label` field.
+- [ ] Tools have `promptSnippet` and/or `promptGuidelines` when appropriate.
+- [ ] Large output tools use `truncateHead()` + temp file pattern.
+- [ ] Domain logic is extracted to testable core modules.
 - [ ] `ctx.ui.custom()` calls have RPC fallback, and interactive close/cancel paths do not rely on `done(undefined)` when fallback detection uses `result === undefined`.
 - [ ] `tool_call` hooks check `ctx.hasUI` before dialog methods.
 - [ ] Fire-and-forget methods (notify, setStatus, etc.) are used without hasUI guards.
@@ -137,4 +151,4 @@ Before considering an extension complete:
 - [ ] `prepare` script is `"[ -d .git ] && husky || true"`, not bare `"husky"`.
 - [ ] `config.ts` uses `ConfigLoader<Raw, Resolved>` with TypeScript interfaces, not TypeBox schemas.
 - [ ] If deviating from the standard entry point pattern (load-config → check-enabled → register), the reason is documented in `AGENTS.md`.
-- [ ] If the extension adds a tool that competes with a bash fallback: guidance is injected via `src/guidance.ts` + `src/hooks/system-prompt.ts`, with a `systemPromptGuidance` config toggle defaulting to `true`.
+- [ ] Settings use `registerSettingsCommand` from `@aliou/pi-utils-settings` when the extension has user-configurable settings.

package/src/skills/pi-extension/references/additional-apis.md

@@ -127,6 +127,41 @@ Extensions that add tools or behavioral patterns the agent may not know how to u
 - The tool description alone is self-explanatory
 - The tool has no plausible bash alternative
 
+---
+
+There are two ways to inject guidance, depending on complexity:
+
+#### Tier 1: Per-Tool Metadata (Preferred for Simple Tools)
+
+For most tools, use the SDK-level `promptSnippet` and `promptGuidelines` fields directly on the tool definition. No hook is needed.
+
+- **`promptSnippet`** — Injected into the "Available tools" system prompt section. Use for a concise (1–2 sentence) description of when to prefer this tool.
+- **`promptGuidelines`** — Appended to the "Guidelines" section. Use for a short list of usage rules.
+
+```typescript
+const myTool = {
+  name: "my_tool",
+  label: "My Tool",
+  description: "...",
+  promptSnippet: "Manage background processes without blocking the conversation.",
+  promptGuidelines: [
+    "Use this tool for long-running commands instead of bash.",
+    "After starting a process, continue other work instead of waiting.",
+  ],
+  parameters: ...,
+  execute: ...,
+};
+```
+
+This is the simplest approach and works well when guidance is specific to a single tool.
+
+#### Tier 2: System Prompt Hook (For Complex Cross-Tool Orchestration)
+
+Use the `before_agent_start` hook when:
+- Guidance involves **cross-tool workflow instructions** (e.g. "use tool A, then tool B, then tool C")
+- You need **dynamic context from config** (e.g. workspace names, team keys, feature flags)
+- The per-tool metadata fields aren't expressive enough
+
 **Structure: three files**
 
 `src/guidance.ts` — the guidance text as a named export:
@@ -187,6 +222,8 @@ export interface MyExtensionConfig {
 
 Call `registerGuidance(pi)` from your hooks setup function.
 
+---
+
 **What makes guidance effective:**
 
 - Lead with the decision rule: **when to use AND when not to use**. The when-not-to-use is as important — it gives the agent permission to keep using `bash` for quick tasks and prevents overcorrection.
@@ -195,7 +232,10 @@ Call `registerGuidance(pi)` from your hooks setup function.
 - Keep the guidance section header (`## My Extension`) so it reads as a named capability, not a restriction.
 - Avoid stacking emphasis markers (`NEVER`, `ALWAYS`, `IMPORTANT`). One or two land; more are ignored.
 
-**Reference implementations:** `pi-linkup` (`src/hooks/system-prompt.ts`, `src/guidance.ts`) and `pi-processes` (`src/hooks/system-prompt.ts`, `src/guidance.ts`).
+**Reference implementations:**
+- `pi-linkup` — Uses per-tool `promptSnippet`/`promptGuidelines` (simple tools, no hook needed).
+- `pi-linear` — Uses `guidance.ts` + `before_agent_start` hook (cross-tool workflow instructions + dynamic workspace context).
+- `pi-processes` — Uses both: `promptSnippet`/`promptGuidelines` on tools for basic guidance, plus system prompt hook for complex multi-tool orchestration patterns.
 
 ## Compaction
 

package/src/skills/pi-extension/references/hooks.md

@@ -8,13 +8,11 @@ Hooks let extensions react to lifecycle events. They are registered with `pi.on(
 
 | Event | When | Can Cancel | Payload |
 |---|---|---|---|
-| `session_start` | New session created | No | `{}` |
-| `session_switch` | Switched to different session | No | `{ reason: "new" \| "switch" \| "fork" }` |
-| `session_before_switch` | Before switching sessions | Yes (`{ cancel: true }`) | `{ reason: "new" \| "switch" \| "fork" }` |
-| `session_before_fork` | Before forking a session | Yes (`{ cancel: true }`) | `{}` |
-| `session_fork` | After session was forked | No | `{}` |
-| `session_shutdown` | Pi is shutting down | No | `{}` |
-| `session_before_compact` | Before compaction | Yes (return custom summary string) | `{ summary: string }` |
+| `session_start` | Session starts, reloads, or is replaced | No | `{ reason: "startup" \| "reload" \| "new" \| "resume" \| "fork", previousSessionFile? }` |
+| `session_before_switch` | Before `/new` or `/resume` replaces the current session | Yes (`{ cancel: true }`) | `{ reason: "new" \| "resume", targetSessionFile? }` |
+| `session_before_fork` | Before forking a session | Yes (`{ cancel: true }`) | `{ entryId }` |
+| `session_shutdown` | Current session runtime is shutting down or being replaced | No | `{}` |
+| `session_before_compact` | Before compaction | Yes (cancel or provide custom compaction) | event-specific compaction data |
 
 ### Agent Events
 
@@ -98,8 +96,13 @@ pi.on("session_before_switch", async (event, ctx) => {
 
 ```typescript
 pi.on("session_before_compact", async (event, ctx) => {
-  // Return a custom summary string to replace the default compaction
-  return `Custom summary: ${event.summary.slice(0, 200)}...`;
+  return {
+    compaction: {
+      summary: "Custom summary",
+      firstKeptEntryId: event.preparation.firstKeptEntryId,
+      tokensBefore: event.preparation.tokensBefore,
+    },
+  };
 });
 ```
 

package/src/skills/pi-extension/references/state.md

@@ -1,42 +1,53 @@
 # State Management
 
-Extensions can persist state in the session history using `appendEntry`. State is reconstructed by replaying entries when a session is loaded.
+Extensions can persist state in the session history. In modern Pi extensions, the usual pattern is to store reconstructible state in tool result `details` and rebuild it from the current branch on `session_start`.
 
-## appendEntry
+## Recommended Pattern: Store State in Tool Result Details
 
-Adds an entry to the session conversation. Unlike `sendMessage`, entries from `appendEntry` are explicitly for state tracking and are rendered via the tool result rendering system.
+When a tool changes extension state, return the latest state in `details`. That keeps the state aligned with normal tool history, branching, and reconstruction.
 
 ```typescript
-pi.appendEntry({
-  toolName: "todo",
-  toolCallId: `todo-${Date.now()}`,
-  input: { action: "add", text: "Buy groceries" },
-  output: "Added: Buy groceries",
-  display: true,
-  details: { items: ["Buy groceries"] },
-});
-```
+export default function (pi: ExtensionAPI) {
+  let items: string[] = [];
 
-| Field | Type | Description |
-|---|---|---|
-| `toolName` | `string` | Which tool this entry is associated with. Used for rendering. |
-| `toolCallId` | `string` | Unique ID for this entry. |
-| `input` | `object` | The "input" shown in the entry (as if the tool was called with these params). |
-| `output` | `string` | The text output (what the LLM sees). |
-| `display` | `boolean` | Whether to show in TUI. |
-| `details` | `object` | Rich data for the tool's `renderResult`. |
+  pi.on("session_start", async (_event, ctx) => {
+    items = [];
+    for (const entry of ctx.sessionManager.getBranch()) {
+      if (entry.type === "message" && entry.message.role === "toolResult") {
+        if (entry.message.toolName === "todo") {
+          items = entry.message.details?.items ?? [];
+        }
+      }
+    }
+  });
+
+  pi.registerTool({
+    name: "todo",
+    // ...
+    async execute() {
+      items.push("Buy groceries");
+      return {
+        content: [{ type: "text", text: "Added todo item" }],
+        details: { items: [...items] },
+      };
+    },
+  });
+}
+```
 
 ## Reconstructing State from Session
 
-When a session loads, you can reconstruct state by iterating over existing entries. This is typically done in a `session_start` or `session_switch` handler:
+When a session loads, reconstruct state in `session_start` by iterating over the current branch or full session through `ctx.sessionManager`:
 
 ```typescript
 pi.on("session_start", async (_event, ctx) => {
-  // Rebuild state from session entries
-  const entries = ctx.getEntries();
-  for (const entry of entries) {
-    if (entry.toolName === "todo" && entry.details) {
-      todoItems = entry.details.items;
+  todoItems = [];
+
+  for (const entry of ctx.sessionManager.getBranch()) {
+    if (entry.type === "message" && entry.message.role === "toolResult") {
+      if (entry.message.toolName === "todo") {
+        todoItems = entry.message.details?.items ?? [];
+      }
     }
   }
 });
@@ -53,4 +64,4 @@ This pattern makes state survive session reloads, forks, and compactions (as lon
 | Use for | State changes, action logs | Information display, command results |
 | LLM sees | The `output` field | The `content` field |
 
-Use `appendEntry` when you are tracking state changes that need to be replayed. Use `sendMessage` when you are displaying a one-time result.
+Use tool result `details` when the state naturally belongs to a tool call and should follow normal conversation branching. Use `appendEntry` for extension-specific state/history that does not fit a normal tool result. Use `sendMessage` when you are displaying a one-time result.

package/src/skills/pi-extension/references/structure.md

@@ -11,7 +11,15 @@ my-extension/
     config.ts             # Config schema (types) + loader + defaults
     client.ts             # API client (if wrapping a third-party API)
     tools/
-      my-tool.ts          # One file per tool
+      my-tool.ts          # One file per tool (simple tool)
+      my-multi-tool/      # Multi-action tool
+        index.ts           # Tool registration + renderCall/renderResult
+        actions/           # One file per action
+          create.ts
+          list.ts
+          show.ts
+        render.ts          # Separate render module (when rendering is complex)
+        types.ts           # Serialized types for tool details
     commands/
       my-command.ts        # One file per command
     components/
@@ -39,6 +47,8 @@ Not every extension needs every directory. A simple extension with one tool migh
 - **Config types live in `config.ts`**, not a separate `types.ts` or `config-schema.ts`. The config file exports both the types (raw and resolved) and the config loader instance.
 - **Utility/helper files** go in `utils/`. This includes pattern matching, shell parsing, event helpers, migrations, etc. Anything that is not a tool, command, component, provider, or hook.
 - **No separate `types.ts`** unless the extension has shared types unrelated to config (rare). Config types are the most common shared types, and they belong in `config.ts`.
+- **Multi-action tools** get their own directory under `tools/`. The tool registration + rendering lives in `index.ts`, each action gets its own file in `actions/`, and complex rendering logic goes in `render.ts`. Serialized types for tool details go in `types.ts`.
+- **Core/domain logic** lives in dedicated modules at the `src/` root (`client.ts`, `manager.ts`). These contain the business logic, are testable without the Pi framework, and don't import from `@mariozechner/pi-coding-agent`. Tools are thin wrappers that call these modules and format results.
 
 ## package.json
 
@@ -68,16 +78,19 @@ Not every extension needs every directory. A simple extension with one tool migh
   },
   "peerDependencies": {
     "@mariozechner/pi-coding-agent": ">=CURRENT_VERSION",
+    "@mariozechner/pi-ai": ">=CURRENT_VERSION",
     "@mariozechner/pi-tui": ">=CURRENT_VERSION"
   },
   "peerDependenciesMeta": {
     "@mariozechner/pi-coding-agent": { "optional": true },
+    "@mariozechner/pi-ai": { "optional": true },
     "@mariozechner/pi-tui": { "optional": true }
   },
   "devDependencies": {
     "@aliou/biome-plugins": "^0.3.0",
     "@biomejs/biome": "^2.0.0",
     "@changesets/cli": "^2.27.0",
+    "@mariozechner/pi-ai": "CURRENT_VERSION",
     "@mariozechner/pi-coding-agent": "CURRENT_VERSION",
     "@mariozechner/pi-tui": "CURRENT_VERSION",
     "@types/node": "^25.0.0",
@@ -120,7 +133,14 @@ Only include `pi` sub-fields that are actually used. `skills`, `themes`, `prompt
 | `prompts` | Array of directories containing prompt files. Optional. |
 | `video` | URL to an `.mp4` demo video. Displayed on the pi website package listing. Not used by pi itself. Optional. |
 
-**`peerDependencies`**: Declares the minimum pi version required. Both `@mariozechner/pi-coding-agent` and `@mariozechner/pi-tui` must be listed here as optional peers if your extension imports from either at runtime. Pi already ships these packages, so marking them as optional peers prevents npm from installing duplicate copies when a user installs your extension. Use `>=` with the current version when creating.
+**`peerDependencies`**: Declares the minimum pi version required. Pi ships these packages and injects them via jiti at runtime, so extensions never need to install them:
+
+- `@mariozechner/pi-coding-agent` — core types, utilities, and extension APIs
+- `@mariozechner/pi-tui` — TUI components
+- `@mariozechner/pi-ai` — AI utilities (`StringEnum`, etc.)
+- `@sinclair/typebox` — schema definitions for tool parameters and related types
+
+List any of these you import at runtime in `peerDependencies` as optional peers. This prevents npm from installing duplicate copies when a user installs your extension. Use `>=` with the current version when creating.
 
 **`peerDependenciesMeta`**: Marks peer dependencies as optional. Without `optional: true`, npm 7+ auto-installs peers that are not already present, which defeats the purpose — Pi already provides them.
 
@@ -288,6 +308,100 @@ export const configLoader = new ConfigLoader<MyExtensionConfig, ResolvedMyExtens
 );
 ```
 
+### Config Migrations
+
+For evolving config shape across versions, pass named migrations to `ConfigLoader`:
+
+```typescript
+import { ConfigLoader, type Migration, buildSchemaUrl } from "@aliou/pi-utils-settings";
+import pkg from "../package.json" with { type: "json" };
+
+const legacyMigration: Migration<MyExtensionConfig> = {
+  name: "legacy-flat-key-to-nested",
+  shouldRun: (config) => Boolean(config.apiKey && !config.workspaces),
+  run: (config) => {
+    const migrated = structuredClone(config);
+    migrated.workspaces = { default: { apiKey: config.apiKey } };
+    delete migrated.apiKey;
+    return migrated;
+  },
+};
+
+const schemaUrl = buildSchemaUrl(pkg.name, pkg.version);
+
+export const configLoader = new ConfigLoader<MyConfig, ResolvedMyConfig>(
+  "my-extension",
+  DEFAULTS,
+  {
+    schemaUrl,
+    migrations: [legacyMigration],
+  },
+);
+```
+
+Each migration has:
+- `name`: unique identifier for idempotency
+- `shouldRun(config)`: predicate that returns true if migration is needed
+- `run(config)`: returns the migrated config (must not mutate the input)
+
+### JSON Schema for Config Validation
+
+Use `buildSchemaUrl(pkg.name, pkg.version)` from `@aliou/pi-utils-settings` to generate a schema URL. Config files get a `$schema` field pointing to the published schema, enabling editor validation and autocompletion.
+
+## Settings Command
+
+Extensions with user-configurable settings use `registerSettingsCommand` from `@aliou/pi-utils-settings` to create a settings UI with Local/Global tabs:
+
+```typescript
+import { registerSettingsCommand, type SettingsSection } from "@aliou/pi-utils-settings";
+
+registerSettingsCommand<MyConfig, ResolvedMyConfig>(pi, {
+  commandName: "my-extension:settings",
+  commandDescription: "Configure my extension",
+  title: "My Extension Settings",
+  configStore: configLoader,
+  onSave: () => { /* invalidate caches */ },
+  buildSections: (tabConfig, resolved, ctx): SettingsSection[] => [
+    {
+      label: "General",
+      items: [
+        {
+          id: "enabled",
+          label: "Enabled",
+          description: "Enable or disable the extension",
+          currentValue: (tabConfig?.enabled ?? resolved.enabled) ? "enabled" : "disabled",
+          values: ["enabled", "disabled"],
+        },
+      ],
+    },
+  ],
+});
+```
+
+For complex nested config (workspaces, profiles), use `submenu` fields with `SettingsDetailEditor` or `FuzzySelector` components. See `pi-linear/src/commands/settings.ts` for a full example.
+
+### Auth Wizard
+
+For extensions requiring API credentials, use the `Wizard` component from `@aliou/pi-utils-settings` for multi-step onboarding:
+
+```typescript
+import { Wizard, FuzzySelector, type WizardStepContext } from "@aliou/pi-utils-settings";
+
+const wizard = new Wizard({
+  title: "My Auth",
+  theme,
+  steps: [
+    { label: "Key", build: (ctx) => new ApiKeyStep(state, ctx) },
+    { label: "Validate", build: (ctx) => new ValidateStep(state, ctx) },
+    { label: "Scope", build: (ctx) => new ScopeStep(state, ctx) },
+  ],
+  onComplete: async () => { /* save config */ },
+  onCancel: () => done(false),
+});
+```
+
+Each step receives a `WizardStepContext` with `markComplete()`/`markIncomplete()` to control navigation gates. See `pi-linear/src/commands/auth-wizard.ts` for a full example with async validation and spinner.
+
 ## Entry Point (src/index.ts)
 
 The entry point is a default export function that receives the `ExtensionAPI` object.