@aliou/pi-dev-kit 0.6.4 → 0.6.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliou/pi-dev-kit",
-  "version": "0.6.4",
+  "version": "0.6.5",
   "license": "MIT",
   "type": "module",
   "private": false,
@@ -35,18 +35,19 @@
     "README.md"
   ],
   "dependencies": {
-    "@aliou/pi-utils-ui": "^0.1.0",
-    "@sinclair/typebox": "^0.34.41"
+    "@aliou/pi-utils-ui": "^0.1.0"
   },
   "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "0.68.0",
-    "@mariozechner/pi-tui": "0.68.0"
+    "@mariozechner/pi-coding-agent": "0.70.0",
+    "@mariozechner/pi-tui": "0.70.0",
+    "typebox": ">=1.1.24"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.3.13",
     "@changesets/cli": "^2.27.11",
-    "@mariozechner/pi-coding-agent": "0.68.0",
-    "@mariozechner/pi-tui": "0.68.0",
+    "@mariozechner/pi-coding-agent": "0.70.0",
+    "@mariozechner/pi-tui": "0.70.0",
+    "typebox": "1.1.24",
     "@types/node": "^25.0.10",
     "husky": "^9.1.7",
     "typescript": "^5.9.3"
@@ -57,6 +58,9 @@
     },
     "@mariozechner/pi-tui": {
       "optional": true
+    },
+    "typebox": {
+      "optional": true
     }
   },
   "scripts": {

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

@@ -14,7 +14,7 @@ Pi injects these packages via jiti at runtime. Extensions do not need to install
 - `@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
+- `typebox` — TypeBox 1.x schema definitions for tool parameters and related types. Do not use `@sinclair/typebox` in new code.
 
 ```typescript
 // Tool UI components (from @aliou/pi-utils-ui)
@@ -42,12 +42,12 @@ import { Container, Markdown, Text } from "@mariozechner/pi-tui";
 ### Creating a New Extension
 
 1. Read `references/structure.md` for the project layout and package.json template.
-2. Create the entry point (`src/index.ts`) with a default export function.
-3. Decide what the extension provides:
-   - **Tools** (LLM-callable): Read `references/tools.md`.
-   - **Commands** (user-invoked): Read `references/commands.md`.
-   - **Providers** (LLM backends): Read `references/providers.md`.
-   - **Hooks** (event handlers): Read `references/hooks.md`. Includes both `tool_call` blocking hooks and spawn hooks for transparent command rewriting via `createBashTool`.
+2. Decide what the extension provides and create one feature entry point per directory:
+   - **Tools** (LLM-callable): `src/tools/index.ts`; read `references/tools.md`.
+   - **Commands** (user-invoked): `src/commands/index.ts`; read `references/commands.md`.
+   - **Providers** (LLM backends): `src/providers/index.ts`; read `references/providers.md`.
+   - **Hooks** (event handlers): `src/hooks/index.ts`; read `references/hooks.md`. Includes both `tool_call` blocking hooks and spawn hooks for transparent command rewriting via `createBashTool`.
+3. Add each feature entry point to `package.json` `pi.extensions`. Each entry point exports a default function that receives `ExtensionAPI` and calls `pi.registerTool`, `pi.registerCommand`, `pi.registerProvider`, or `pi.on` directly.
 4. Read `references/modes.md` for mode-awareness guidelines. Every extension must handle Interactive, RPC, and Print modes.
 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`.
@@ -104,24 +104,28 @@ When implementing, look at these existing extensions for patterns:
 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**: 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>`.
+11. **Tool definitions use `defineTool()`**: Define standalone tools with `defineTool({...})` from `@mariozechner/pi-coding-agent` so `execute`, `renderCall`, and `renderResult` infer typed params from the `parameters` field without casts or explicit generic arguments. Also define `type MyToolParams = Static<typeof parameters>` at the top of each tool file and use it everywhere.
 12. **Tool metadata**: Every tool must have `label` (required). Add `promptSnippet` for system prompt tool listing. Add `promptGuidelines` for usage instructions, but write them as standalone global bullets that name the exact tool. 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 `*`.
+16. **peerDependencies**: Pi injects `@mariozechner/pi-coding-agent`, `@mariozechner/pi-tui`, `@mariozechner/pi-ai`, and `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 `*`. Pi 0.69+ uses `typebox` 1.x; do not import from `@sinclair/typebox`.
 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`.
+22. **Entry point deviations must be documented**: The standard entry point pattern for each feature entry is load config → check `enabled` → register with `pi`. Deviations (no config, API-key-first ordering, no `enabled` toggle) are acceptable when justified, but must be noted in `AGENTS.md`.
+23. **Session replacement uses `withSession`**: After `ctx.newSession()`, `ctx.fork()`, or `ctx.switchSession()`, captured old `pi`, command `ctx`, and `ctx.sessionManager` are stale and may throw. Put post-switch work in `withSession` and use only that fresh callback context.
 
 ## Checklist
 
 Before considering an extension complete:
 
-- [ ] Entry point has correct default export signature.
+- [ ] Each feature entry point listed in `package.json` `pi.extensions` has the correct default export signature.
+- [ ] Tools, commands, providers, and hooks are separate feature entry directories; no root `src/index.ts` fan-out registrar.
+- [ ] TUI components are colocated with the feature that uses them, or in `src/components/` only when genuinely shared; they are not listed in `pi.extensions`.
+- [ ] Every standalone tool is wrapped in `defineTool()` so typed params flow into `execute`, `renderCall`, and `renderResult` without casts.
 - [ ] All tools have correct execute parameter order.
 - [ ] All `onUpdate` calls use optional chaining.
 - [ ] No `.js` file extensions in imports.
@@ -153,5 +157,7 @@ Before considering an extension complete:
 - [ ] `@mariozechner/pi-tui` (and any other Pi-provided package) is in `peerDependencies` with `optional: true` if imported at runtime, not just `devDependencies`.
 - [ ] `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 deviating from the standard feature entry pattern (load-config → check-enabled → register), the reason is documented in `AGENTS.md`.
 - [ ] Settings use `registerSettingsCommand` from `@aliou/pi-utils-settings` when the extension has user-configurable settings.
+- [ ] New code imports TypeBox from `typebox`, not `@sinclair/typebox`.
+- [ ] Any session replacement code uses `withSession` for post-switch work and does not reuse stale session-bound objects.

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

@@ -94,10 +94,14 @@ Setting active tools restricts which tools the LLM can use.
 
 ```typescript
 // Set the active model
-pi.setModel("anthropic/claude-sonnet-4-20250514");
+const model = ctx.modelRegistry.find("anthropic", "claude-sonnet-4-5");
+if (model) {
+  const success = await pi.setModel(model);
+  if (!success) ctx.ui.notify("No API key for this model", "error");
+}
 
 // Get/set thinking level
-const level = pi.getThinkingLevel(); // "none" | "low" | "medium" | "high"
+const level = pi.getThinkingLevel(); // "off" | "minimal" | "low" | "medium" | "high" | "xhigh"
 pi.setThinkingLevel("high");
 ```
 
@@ -112,7 +116,7 @@ pi.on("before_agent_start", async (_event, ctx) => {
 });
 ```
 
-The system prompt resets each turn, so modifications are not cumulative.
+The system prompt resets each turn, so modifications are not cumulative. In `before_agent_start`, `ctx.getSystemPrompt()` reflects prompt changes from earlier handlers, and the event includes `systemPromptOptions` for structured prompt inputs.
 
 ### Guidance Injection Pattern
 
@@ -239,6 +243,23 @@ Call `registerGuidance(pi)` from your hooks setup function.
 - `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.
 
+## Session Replacement
+
+`ctx.newSession()`, `ctx.fork()`, and `ctx.switchSession()` invalidate captured pre-replacement session-bound objects after the replacement. Use `withSession` for post-switch work and only use the fresh callback context there.
+
+```typescript
+await ctx.newSession({
+  setup: async (sm) => {
+    sm.appendCustomMessageEntry("my-source", "Seed context", true);
+  },
+  withSession: async (ctx) => {
+    await ctx.sendUserMessage("Continue from the new session");
+  },
+});
+```
+
+Do not reuse captured `pi`, command `ctx`, or `ctx.sessionManager` after a session replacement.
+
 ## Compaction
 
 Trigger compaction programmatically:
@@ -303,4 +324,22 @@ ctx.ui.setEditorComponent((tui, theme, kb) => {
 
 // Prefill the editor
 ctx.ui.setEditorText("Prefilled content");
+
+// Customize the streaming working indicator
+ctx.ui.setWorkingIndicator({ frames: [ctx.ui.theme.fg("accent", "●")] }); // static
+ctx.ui.setWorkingIndicator({ frames: [] }); // hidden
+ctx.ui.setWorkingIndicator(); // restore default
+
+// Stack autocomplete on top of built-in slash/path completion
+ctx.ui.addAutocompleteProvider((current) => ({
+  async getSuggestions(lines, cursorLine, cursorCol) {
+    const beforeCursor = (lines[cursorLine] ?? "").slice(0, cursorCol);
+    const match = beforeCursor.match(/(?:^|[ \t])#([^\s#]*)$/);
+    if (!match) return current.getSuggestions(lines, cursorLine, cursorCol);
+    return [{ label: `#${match[1]}123`, value: `#${match[1]}123` }];
+  },
+  shouldTriggerFileCompletion(input) {
+    return current.shouldTriggerFileCompletion?.(input) ?? false;
+  },
+}));
 ```

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

@@ -11,14 +11,14 @@ Hooks let extensions react to lifecycle events. They are registered with `pi.on(
 | `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_shutdown` | Current session runtime is shutting down or being replaced | No | `{ reason: "quit" | "reload" | "new-session" | "resume" | "fork", targetSessionFile? }` |
 | `session_before_compact` | Before compaction | Yes (cancel or provide custom compaction) | event-specific compaction data |
 
 ### Agent Events
 
 | Event | When | Payload |
 |---|---|---|
-| `before_agent_start` | Before agent turn starts | `{}` |
+| `before_agent_start` | Before agent turn starts | `{ systemPrompt, systemPromptOptions }` |
 | `agent_start` | Agent turn started | `{}` |
 | `turn_start` | Turn begins processing | `{}` |
 | `turn_end` | Turn finishes processing | `{}` |
@@ -133,7 +133,7 @@ pi.on("user_bash", async (event, ctx) => {
 
 This event fires before each agent turn. It is commonly used to modify the system prompt.
 
-The handler receives a `BeforeAgentStartEvent` with a `systemPrompt` field containing the current prompt. Return a `{ systemPrompt }` object to replace it. If multiple extensions return a modified prompt, they are chained.
+The handler receives a `BeforeAgentStartEvent` with `systemPrompt` and `systemPromptOptions` fields. `systemPromptOptions` exposes the structured inputs used to build the prompt. Return a `{ systemPrompt }` object to replace it. If multiple extensions return a modified prompt, they are chained. `ctx.getSystemPrompt()` reflects changes made by earlier `before_agent_start` handlers.
 
 ```typescript
 pi.on("before_agent_start", async (event) => {
@@ -151,7 +151,7 @@ To access flags inside hooks, use `pi.getFlag()` (see `references/additional-api
 
 ## Bash Spawn Hook (Command Rewriting)
 
-The `createBashTool` function lets you replace the built-in bash tool with one that transparently rewrites commands before shell execution. This is different from `tool_call` blocking -- the agent never sees that the command was rewritten.
+The `createBashTool(cwd, options)` function lets you replace the built-in bash tool with one that transparently rewrites commands before shell execution. Always pass an explicit cwd. This is different from `tool_call` blocking -- the agent never sees that the command was rewritten.
 
 Use spawn hooks when you have a clear rewrite target (e.g. `npm` -> `pnpm`). Use `tool_call` blocking when you need to stop a command entirely or show a confirmation dialog.
 

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

@@ -36,19 +36,36 @@ pi.sendMessage({
 Registers a custom renderer for messages with a specific `customType`:
 
 ```typescript
-pi.registerMessageRenderer("balance-result", (message, theme) => {
-  const { balance } = message.details;
-  return [
-    theme.bold("Account Balance"),
-    "",
-    theme.fg("success", `  $${balance.toFixed(2)}`),
-  ].join("\n");
-});
+import type {
+  ExtensionAPI,
+  MessageRenderOptions,
+  Theme,
+} from "@mariozechner/pi-coding-agent";
+import { Text } from "@mariozechner/pi-tui";
+
+interface BalanceDetails {
+  balance?: number;
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.registerMessageRenderer<BalanceDetails>(
+    "balance-result",
+    (message, _options: MessageRenderOptions, theme: Theme) => {
+      const balance = message.details?.balance;
+      const text =
+        typeof balance === "number"
+          ? `Account Balance: $${balance.toFixed(2)}`
+          : message.content;
+
+      return new Text(theme.fg("success", text), 0, 0);
+    },
+  );
+}
 ```
 
-The renderer receives the full message object and the theme. It returns a string for display in the TUI.
+The renderer receives the full message object, render options, and theme. It returns a TUI `Component` such as `Text`, `Box`, `Markdown`, or a custom component. If no renderer is registered for a `customType`, the message's `content` field is displayed as plain text.
 
-If no renderer is registered for a `customType`, the message's `content` field is displayed as plain text.
+For larger renderers, keep the renderer implementation next to the hook or command that emits that `customType`. See `pi-processes/src/hooks/message-renderer.ts` for a compact lifecycle-message renderer and `pi-harness/extensions/breadcrumbs/lib/session-link.ts` for richer persistent session-link renderers.
 
 ## Custom Message Design Guide (breadcrumbs-style)
 

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

@@ -7,27 +7,27 @@ This covers the standalone repository structure for a Pi extension. This is the
 ```
 my-extension/
   src/
-    index.ts              # Entry point (default export)
     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 (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
+      index.ts            # Tool extension entry point (default export, calls pi.registerTool)
+      actions/            # Optional one file per action for multi-action tools
+        create.ts
+        list.ts
+        show.ts
+      render.ts           # Optional separate render module
+      types.ts            # Optional serialized types for tool details
     commands/
-      my-command.ts        # One file per command
-    components/
-      my-renderer.ts       # Shared TUI components
+      index.ts            # Command extension entry point (default export, calls pi.registerCommand)
+      components.ts       # Optional command UI components
+    hooks/
+      index.ts            # Hook extension entry point (default export, calls pi.on)
+    components/           # Optional shared TUI components used by tools/commands/hooks
+      my-component.ts
     providers/
-      index.ts             # Provider registration
-      models.ts            # Model definitions
-    utils/                 # Internal helpers (matching, parsing, etc.)
+      index.ts            # Provider extension entry point (default export, calls pi.registerProvider)
+      models.ts           # Model definitions
+    utils/                # Internal helpers (matching, parsing, etc.)
       my-helper.ts
   package.json
   tsconfig.json
@@ -38,12 +38,14 @@ my-extension/
   README.md
 ```
 
-Not every extension needs every directory. A simple extension with one tool might only have `src/index.ts` and `src/tools/my-tool.ts`.
+Not every extension needs every directory. A simple extension with one tool might only have `src/tools/index.ts` plus `src/config.ts` if it has settings.
 
 ### Organization principles
 
-- **`index.ts` and `config.ts`** stay at root. These are the two core files every non-trivial extension has.
-- **Tools, commands, components, providers, hooks** each get their own directory. One file per tool/command/component.
+- **Each Pi feature directory is its own extension entry point.** `tools/index.ts`, `commands/index.ts`, `hooks/index.ts`, and `providers/index.ts` each export a default function that receives `ExtensionAPI` and registers that feature with `pi`.
+- **`config.ts`** stays at root and is shared by feature entry points. Each entry point loads config and gates itself with `enabled` when applicable.
+- **Do not use a single root `src/index.ts` that imports and registers everything.** Declare each feature entry point in `package.json` under `pi.extensions` instead.
+- **Components are not entry points.** TUI components are support modules used by tools, commands, or hooks. Keep them colocated with the feature that uses them, or in `src/components/` only when genuinely shared.
 - **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`.
@@ -70,7 +72,12 @@ Not every extension needs every directory. A simple extension with one tool migh
   },
   "files": ["src", "README.md"],
   "pi": {
-    "extensions": ["./src/index.ts"],
+    "extensions": [
+      "./src/tools/index.ts",
+      "./src/commands/index.ts",
+      "./src/hooks/index.ts",
+      "./src/providers/index.ts"
+    ],
     "skills": ["./skills"],
     "themes": ["./themes"],
     "prompts": ["./prompts"],
@@ -80,13 +87,13 @@ Not every extension needs every directory. A simple extension with one tool migh
     "@mariozechner/pi-coding-agent": ">=CURRENT_VERSION",
     "@mariozechner/pi-ai": ">=CURRENT_VERSION",
     "@mariozechner/pi-tui": ">=CURRENT_VERSION",
-    "@sinclair/typebox": ">=0.34.0"
+    "typebox": ">=1.1.24"
   },
   "peerDependenciesMeta": {
     "@mariozechner/pi-coding-agent": { "optional": true },
     "@mariozechner/pi-ai": { "optional": true },
     "@mariozechner/pi-tui": { "optional": true },
-    "@sinclair/typebox": { "optional": true }
+    "typebox": { "optional": true }
   },
   "devDependencies": {
     "@aliou/biome-plugins": "^0.3.0",
@@ -95,7 +102,7 @@ Not every extension needs every directory. A simple extension with one tool migh
     "@mariozechner/pi-ai": "CURRENT_VERSION",
     "@mariozechner/pi-coding-agent": "CURRENT_VERSION",
     "@mariozechner/pi-tui": "CURRENT_VERSION",
-    "@sinclair/typebox": "0.34.41",
+    "typebox": "1.1.24",
     "@types/node": "^25.0.0",
     "husky": "^9.0.0",
     "typescript": "^5.8.0"
@@ -120,7 +127,7 @@ Not every extension needs every directory. A simple extension with one tool migh
 }
 ```
 
-Replace `CURRENT_VERSION` with the actual installed version of pi (e.g., `0.52.7`).
+Replace `CURRENT_VERSION` with the actual installed version of pi (e.g., `0.70.0`).
 
 Only include `pi` sub-fields that are actually used. `skills`, `themes`, `prompts`, and `video` are optional.
 
@@ -130,7 +137,7 @@ Only include `pi` sub-fields that are actually used. `skills`, `themes`, `prompt
 
 | Field | Description |
 |---|---|
-| `extensions` | Array of entry point paths. Each is a TypeScript file with a default export function. |
+| `extensions` | Array of extension entry point paths. Each file or directory `index.ts` exports a default function receiving `ExtensionAPI`. Prefer one entry point per feature directory (`tools/index.ts`, `commands/index.ts`, etc.). |
 | `skills` | Array of directories containing skill definitions. Optional. |
 | `themes` | Array of directories containing theme files. Optional. |
 | `prompts` | Array of directories containing prompt files. Optional. |
@@ -141,9 +148,9 @@ Only include `pi` sub-fields that are actually used. `skills`, `themes`, `prompt
 - `@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
+- `typebox` — TypeBox 1.x 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.
+List any of these you import at runtime in `peerDependencies` as optional peers. Pi 0.69+ uses `typebox` 1.x; do not import from `@sinclair/typebox` in new code. 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.
 
@@ -405,33 +412,78 @@ const wizard = new Wizard({
 
 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)
+## Extension Entry Points
 
-The entry point is a default export function that receives the `ExtensionAPI` object.
+Each extension entry point is a default export function that receives the `ExtensionAPI` object. Do not centralize registration in one root `src/index.ts`; instead, make each feature directory an entry point and list those paths in `package.json` `pi.extensions`.
 
 ### Standard Pattern
 
 ```typescript
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { configLoader } from "./config";
-import { registerCommands } from "./commands";
-import { registerHooks } from "./hooks";
-import { registerTools } from "./tools";
+// src/tools/index.ts
+import type { AgentToolResult, ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { defineTool } from "@mariozechner/pi-coding-agent";
+import { type Static, Type } from "typebox";
+import { configLoader } from "../config";
+
+const parameters = Type.Object({
+  query: Type.String({ description: "Search query" }),
+});
+type MyToolParams = Static<typeof parameters>;
+interface MyToolDetails {
+  results: string[];
+}
+
+const myTool = defineTool({
+  name: "my_tool",
+  label: "My Tool",
+  description: "Search for items",
+  parameters,
+  async execute(_toolCallId, params, signal, onUpdate, ctx): Promise<AgentToolResult<MyToolDetails>> {
+    const results = await search(params.query, { signal });
+    return {
+      content: [{ type: "text", text: JSON.stringify(results) }],
+      details: { results },
+    };
+  },
+});
 
 export default async function (pi: ExtensionAPI) {
   await configLoader.load();
   const config = configLoader.getConfig();
   if (!config.enabled) return;
 
-  registerTools(pi);
-  registerCommands(pi);
-  registerHooks(pi);
+  pi.registerTool(myTool);
+}
+```
+
+Declare the entry point directly:
+
+```json
+{
+  "pi": {
+    "extensions": ["./src/tools/index.ts"]
+  }
+}
+```
+
+For multiple features, list multiple entries:
+
+```json
+{
+  "pi": {
+    "extensions": [
+      "./src/tools/index.ts",
+      "./src/commands/index.ts",
+      "./src/hooks/index.ts",
+      "./src/providers/index.ts"
+    ]
+  }
 }
 ```
 
 ### Acceptable Exceptions
 
-Not all extensions follow the standard pattern exactly. These deviations are valid:
+Not all entry points follow the standard pattern exactly. These deviations are valid:
 
 **No config**: Extensions that use environment variables exclusively and have no user-configurable settings skip config loading entirely. The entry point reads the env var directly and gates registration on its presence.
 
@@ -439,6 +491,8 @@ Not all extensions follow the standard pattern exactly. These deviations are val
 
 **No `enabled` check**: Extensions that are always active by design omit the `enabled` field and the early-return check. The entry point still loads config for other settings. Document this decision in `AGENTS.md`.
 
+**Shared setup required**: If multiple feature entry points need a shared setup step, extract a helper module (for example `src/bootstrap.ts`) and call it from each entry. Do not reintroduce a central root entry point just to fan out registration.
+
 When deviating from the standard pattern, note the reason in the extension's `AGENTS.md`.
 
 ## API Key Pattern