@lenylvt/pi-coding-agent 0.64.0

package/docs/json.md

@@ -0,0 +1,82 @@
+# JSON Event Stream Mode
+
+```bash
+pi --mode json "Your prompt"
+```
+
+Outputs all session events as JSON lines to stdout. Useful for integrating pi into other tools or custom UIs.
+
+## Event Types
+
+Events are defined in [`AgentSessionEvent`](../src/core/agent-session.ts#L102):
+
+```typescript
+type AgentSessionEvent =
+  | AgentEvent
+  | { type: "queue_update"; steering: readonly string[]; followUp: readonly string[] }
+  | { type: "compaction_start"; reason: "manual" | "threshold" | "overflow" }
+  | { type: "compaction_end"; reason: "manual" | "threshold" | "overflow"; result: CompactionResult | undefined; aborted: boolean; willRetry: boolean; errorMessage?: string }
+  | { type: "auto_retry_start"; attempt: number; maxAttempts: number; delayMs: number; errorMessage: string }
+  | { type: "auto_retry_end"; success: boolean; attempt: number; finalError?: string };
+```
+
+`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`](../../agent/src/types.ts#L179):
+
+```typescript
+type AgentEvent =
+  // Agent lifecycle
+  | { type: "agent_start" }
+  | { type: "agent_end"; messages: AgentMessage[] }
+  // Turn lifecycle
+  | { type: "turn_start" }
+  | { type: "turn_end"; message: AgentMessage; toolResults: ToolResultMessage[] }
+  // Message lifecycle
+  | { type: "message_start"; message: AgentMessage }
+  | { type: "message_update"; message: AgentMessage; assistantMessageEvent: AssistantMessageEvent }
+  | { type: "message_end"; message: AgentMessage }
+  // Tool execution
+  | { type: "tool_execution_start"; toolCallId: string; toolName: string; args: any }
+  | { type: "tool_execution_update"; toolCallId: string; toolName: string; args: any; partialResult: any }
+  | { type: "tool_execution_end"; toolCallId: string; toolName: string; result: any; isError: boolean };
+```
+
+## Message Types
+
+Base messages from [`packages/ai/src/types.ts`](../../ai/src/types.ts#L134):
+- `UserMessage` (line 134)
+- `AssistantMessage` (line 140)
+- `ToolResultMessage` (line 152)
+
+Extended messages from [`packages/coding-agent/src/core/messages.ts`](../src/core/messages.ts#L29):
+- `BashExecutionMessage` (line 29)
+- `CustomMessage` (line 46)
+- `BranchSummaryMessage` (line 55)
+- `CompactionSummaryMessage` (line 62)
+
+## Output Format
+
+Each line is a JSON object. The first line is the session header:
+
+```json
+{"type":"session","version":3,"id":"uuid","timestamp":"...","cwd":"/path"}
+```
+
+Followed by events as they occur:
+
+```json
+{"type":"agent_start"}
+{"type":"turn_start"}
+{"type":"message_start","message":{"role":"assistant","content":[],...}}
+{"type":"message_update","message":{...},"assistantMessageEvent":{"type":"text_delta","delta":"Hello",...}}
+{"type":"message_end","message":{...}}
+{"type":"turn_end","message":{...},"toolResults":[]}
+{"type":"agent_end","messages":[...]}
+```
+
+## Example
+
+```bash
+pi --mode json "List files" 2>/dev/null | jq -c 'select(.type == "message_end")'
+```

package/docs/keybindings.md

@@ -0,0 +1,173 @@
+# Keybindings
+
+All keyboard shortcuts can be customized via `~/.pi/agent/keybindings.json`. Each action can be bound to one or more keys.
+
+The config file uses the same namespaced keybinding ids that pi uses internally and that extension authors use in `keyHint()` and injected `keybindings` managers.
+
+Older configs using pre-namespaced ids such as `cursorUp` or `expandTools` are migrated automatically to the namespaced ids on startup.
+
+After editing `keybindings.json`, run `/reload` in pi to apply the changes without restarting the session.
+
+## Key Format
+
+`modifier+key` where modifiers are `ctrl`, `shift`, `alt` (combinable) and keys are:
+
+- **Letters:** `a-z`
+- **Digits:** `0-9`
+- **Special:** `escape`, `esc`, `enter`, `return`, `tab`, `space`, `backspace`, `delete`, `insert`, `clear`, `home`, `end`, `pageUp`, `pageDown`, `up`, `down`, `left`, `right`
+- **Function:** `f1`-`f12`
+- **Symbols:** `` ` ``, `-`, `=`, `[`, `]`, `\`, `;`, `'`, `,`, `.`, `/`, `!`, `@`, `#`, `$`, `%`, `^`, `&`, `*`, `(`, `)`, `_`, `+`, `|`, `~`, `{`, `}`, `:`, `<`, `>`, `?`
+
+Modifier combinations: `ctrl+shift+x`, `alt+ctrl+x`, `ctrl+shift+alt+x`, `ctrl+1`, etc.
+
+## All Actions
+
+### TUI Editor Cursor Movement
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `tui.editor.cursorUp` | `up` | Move cursor up |
+| `tui.editor.cursorDown` | `down` | Move cursor down |
+| `tui.editor.cursorLeft` | `left`, `ctrl+b` | Move cursor left |
+| `tui.editor.cursorRight` | `right`, `ctrl+f` | Move cursor right |
+| `tui.editor.cursorWordLeft` | `alt+left`, `ctrl+left`, `alt+b` | Move cursor word left |
+| `tui.editor.cursorWordRight` | `alt+right`, `ctrl+right`, `alt+f` | Move cursor word right |
+| `tui.editor.cursorLineStart` | `home`, `ctrl+a` | Move to line start |
+| `tui.editor.cursorLineEnd` | `end`, `ctrl+e` | Move to line end |
+| `tui.editor.jumpForward` | `ctrl+]` | Jump forward to character |
+| `tui.editor.jumpBackward` | `ctrl+alt+]` | Jump backward to character |
+| `tui.editor.pageUp` | `pageUp` | Scroll up by page |
+| `tui.editor.pageDown` | `pageDown` | Scroll down by page |
+
+### TUI Editor Deletion
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `tui.editor.deleteCharBackward` | `backspace` | Delete character backward |
+| `tui.editor.deleteCharForward` | `delete`, `ctrl+d` | Delete character forward |
+| `tui.editor.deleteWordBackward` | `ctrl+w`, `alt+backspace` | Delete word backward |
+| `tui.editor.deleteWordForward` | `alt+d`, `alt+delete` | Delete word forward |
+| `tui.editor.deleteToLineStart` | `ctrl+u` | Delete to line start |
+| `tui.editor.deleteToLineEnd` | `ctrl+k` | Delete to line end |
+
+### TUI Input
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `tui.input.newLine` | `shift+enter` | Insert new line |
+| `tui.input.submit` | `enter` | Submit input |
+| `tui.input.tab` | `tab` | Tab / autocomplete |
+
+### TUI Kill Ring
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `tui.editor.yank` | `ctrl+y` | Paste most recently deleted text |
+| `tui.editor.yankPop` | `alt+y` | Cycle through deleted text after yank |
+| `tui.editor.undo` | `ctrl+-` | Undo last edit |
+
+### TUI Clipboard and Selection
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `tui.input.copy` | `ctrl+c` | Copy selection |
+| `tui.select.up` | `up` | Move selection up |
+| `tui.select.down` | `down` | Move selection down |
+| `tui.select.pageUp` | `pageUp` | Page up in list |
+| `tui.select.pageDown` | `pageDown` | Page down in list |
+| `tui.select.confirm` | `enter` | Confirm selection |
+| `tui.select.cancel` | `escape`, `ctrl+c` | Cancel selection |
+
+### Application
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `app.interrupt` | `escape` | Cancel / abort |
+| `app.clear` | `ctrl+c` | Clear editor |
+| `app.exit` | `ctrl+d` | Exit (when editor empty) |
+| `app.suspend` | `ctrl+z` | Suspend to background |
+| `app.editor.external` | `ctrl+g` | Open in external editor (`$VISUAL` or `$EDITOR`) |
+| `app.clipboard.pasteImage` | `ctrl+v` (`alt+v` on Windows) | Paste image from clipboard |
+
+### Sessions
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `app.session.new` | *(none)* | Start a new session (`/new`) |
+| `app.session.tree` | *(none)* | Open session tree navigator (`/tree`) |
+| `app.session.fork` | *(none)* | Fork current session (`/fork`) |
+| `app.session.resume` | *(none)* | Open session resume picker (`/resume`) |
+| `app.session.togglePath` | `ctrl+p` | Toggle path display |
+| `app.session.toggleSort` | `ctrl+s` | Toggle sort mode |
+| `app.session.toggleNamedFilter` | `ctrl+n` | Toggle named-only filter |
+| `app.session.rename` | `ctrl+r` | Rename session |
+| `app.session.delete` | `ctrl+d` | Delete session |
+| `app.session.deleteNoninvasive` | `ctrl+backspace` | Delete session when query is empty |
+
+### Models and Thinking
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `app.model.select` | `ctrl+l` | Open model selector |
+| `app.model.cycleForward` | `ctrl+p` | Cycle to next model |
+| `app.model.cycleBackward` | `shift+ctrl+p` | Cycle to previous model |
+| `app.thinking.cycle` | `shift+tab` | Cycle thinking level |
+| `app.thinking.toggle` | `ctrl+t` | Collapse or expand thinking blocks |
+
+### Display and Message Queue
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `app.tools.expand` | `ctrl+o` | Collapse or expand tool output |
+| `app.message.followUp` | `alt+enter` | Queue follow-up message |
+| `app.message.dequeue` | `alt+up` | Restore queued messages to editor |
+
+### Tree Navigation
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `app.tree.foldOrUp` | `ctrl+left`, `alt+left` | Fold current branch segment, or jump to the previous segment start |
+| `app.tree.unfoldOrDown` | `ctrl+right`, `alt+right` | Unfold current branch segment, or jump to the next segment start or branch end |
+
+## Custom Configuration
+
+Create `~/.pi/agent/keybindings.json`:
+
+```json
+{
+  "tui.editor.cursorUp": ["up", "ctrl+p"],
+  "tui.editor.cursorDown": ["down", "ctrl+n"],
+  "tui.editor.deleteWordBackward": ["ctrl+w", "alt+backspace"]
+}
+```
+
+Each action can have a single key or an array of keys. User config overrides defaults.
+
+### Emacs Example
+
+```json
+{
+  "tui.editor.cursorUp": ["up", "ctrl+p"],
+  "tui.editor.cursorDown": ["down", "ctrl+n"],
+  "tui.editor.cursorLeft": ["left", "ctrl+b"],
+  "tui.editor.cursorRight": ["right", "ctrl+f"],
+  "tui.editor.cursorWordLeft": ["alt+left", "alt+b"],
+  "tui.editor.cursorWordRight": ["alt+right", "alt+f"],
+  "tui.editor.deleteCharForward": ["delete", "ctrl+d"],
+  "tui.editor.deleteCharBackward": ["backspace", "ctrl+h"],
+  "tui.input.newLine": ["shift+enter", "ctrl+j"]
+}
+```
+
+### Vim Example
+
+```json
+{
+  "tui.editor.cursorUp": ["up", "alt+k"],
+  "tui.editor.cursorDown": ["down", "alt+j"],
+  "tui.editor.cursorLeft": ["left", "alt+h"],
+  "tui.editor.cursorRight": ["right", "alt+l"],
+  "tui.editor.cursorWordLeft": ["alt+left", "alt+b"],
+  "tui.editor.cursorWordRight": ["alt+right", "alt+w"]
+}
+```

package/docs/models.md

@@ -0,0 +1,197 @@
+# Custom Models
+
+Add custom providers and models via `~/.pi/agent/models.json`.
+
+This fork only ships built-in support for:
+
+- `anthropic`
+- `github-copilot`
+- `openai-codex`
+- `openrouter`
+
+Custom providers remain available for internal gateways, private endpoints, or any compatible proxy.
+
+## Minimal Example
+
+```json
+{
+  "providers": {
+    "openrouter": {
+      "baseUrl": "https://openrouter.ai/api/v1",
+      "api": "openai-completions",
+      "apiKey": "OPENROUTER_API_KEY",
+      "models": [
+        { "id": "anthropic/claude-sonnet-4-5" },
+        { "id": "openai/gpt-5.4-mini" }
+      ]
+    }
+  }
+}
+```
+
+## Supported APIs
+
+| API | Description |
+|-----|-------------|
+| `openai-completions` | OpenAI Chat Completions compatible APIs |
+| `openai-responses` | OpenAI Responses compatible APIs |
+| `openai-codex-responses` | Codex Responses compatible APIs |
+| `anthropic-messages` | Anthropic-compatible APIs |
+
+Set `api` at provider level or override it per model.
+
+## Provider Configuration
+
+| Field | Description |
+|-------|-------------|
+| `baseUrl` | API endpoint URL |
+| `api` | API type |
+| `apiKey` | API key |
+| `headers` | Custom headers |
+| `authHeader` | Add `Authorization: Bearer <apiKey>` automatically |
+| `models` | Array of model configurations |
+| `modelOverrides` | Per-model overrides for built-in models on this provider |
+| `compat` | OpenAI-compatible request tweaks |
+
+### Value Resolution
+
+The `apiKey` and `headers` fields support three formats:
+
+- shell command: `"!command"`
+- environment variable name
+- literal value
+
+Example:
+
+```json
+{
+  "providers": {
+    "custom-proxy": {
+      "baseUrl": "https://proxy.example.com/v1",
+      "apiKey": "MY_API_KEY",
+      "api": "anthropic-messages",
+      "headers": {
+        "x-portkey-api-key": "PORTKEY_API_KEY",
+        "x-secret": "!op read 'op://vault/item/secret'"
+      },
+      "models": []
+    }
+  }
+}
+```
+
+## Model Configuration
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `id` | Yes | — | Model identifier |
+| `name` | No | `id` | Human-readable label |
+| `api` | No | provider `api` | Per-model API override |
+| `reasoning` | No | `false` | Supports extended thinking |
+| `input` | No | `["text"]` | Supported input types |
+| `contextWindow` | No | `128000` | Context window size |
+| `maxTokens` | No | `16384` | Maximum output tokens |
+| `cost` | No | all zeros | Cost per million tokens |
+| `compat` | No | provider `compat` | OpenAI-compatible overrides |
+
+## Overriding Built-in Providers
+
+```json
+{
+  "providers": {
+    "anthropic": {
+      "baseUrl": "https://my-proxy.example.com/v1"
+    }
+  }
+}
+```
+
+All built-in Anthropic models remain available.
+
+To merge custom models into a built-in provider:
+
+```json
+{
+  "providers": {
+    "openrouter": {
+      "baseUrl": "https://my-proxy.example.com/v1",
+      "apiKey": "OPENROUTER_API_KEY",
+      "api": "openai-completions",
+      "models": [
+        {
+          "id": "anthropic/custom-sonnet",
+          "name": "Custom Sonnet Route",
+          "reasoning": true
+        }
+      ]
+    }
+  }
+}
+```
+
+Merge semantics:
+
+- built-in models are kept
+- custom models are upserted by `id`
+- a custom model with the same `id` replaces the built-in entry
+
+## Per-model Overrides
+
+```json
+{
+  "providers": {
+    "openrouter": {
+      "modelOverrides": {
+        "anthropic/claude-sonnet-4": {
+          "name": "Claude Sonnet 4 (Anthropic Route)",
+          "compat": {
+            "openRouterRouting": {
+              "only": ["anthropic"],
+              "order": ["anthropic"]
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+`modelOverrides` supports `name`, `reasoning`, `input`, `cost`, `contextWindow`, `maxTokens`, `headers`, and `compat`.
+
+## OpenAI Compatibility
+
+For partial OpenAI-compatible providers, use `compat`:
+
+```json
+{
+  "providers": {
+    "local-llm": {
+      "baseUrl": "http://localhost:8080/v1",
+      "api": "openai-completions",
+      "compat": {
+        "supportsUsageInStreaming": false,
+        "maxTokensField": "max_tokens",
+        "supportsDeveloperRole": false,
+        "supportsReasoningEffort": false
+      },
+      "models": []
+    }
+  }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `supportsStore` | Provider supports `store` |
+| `supportsDeveloperRole` | Uses `developer` instead of `system` |
+| `supportsReasoningEffort` | Supports `reasoning_effort` |
+| `reasoningEffortMap` | Maps pi thinking levels to provider values |
+| `supportsUsageInStreaming` | Supports `stream_options.include_usage` |
+| `maxTokensField` | `max_completion_tokens` or `max_tokens` |
+| `requiresToolResultName` | Include `name` on tool results |
+| `requiresAssistantAfterToolResult` | Insert an assistant message before the next user message |
+| `requiresThinkingAsText` | Convert thinking blocks to text |
+| `thinkingFormat` | `openai` or `openrouter` |
+| `supportsStrictMode` | Include `strict` in tool definitions |
+| `openRouterRouting` | OpenRouter routing config |

package/docs/packages.md

@@ -0,0 +1,218 @@
+> pi can help you create pi packages. Ask it to bundle your extensions, skills, prompt templates, or themes.
+
+# Pi Packages
+
+Pi packages bundle extensions, skills, prompt templates, and themes so you can share them through Bun package specs or git. A package can declare resources in `package.json` under the `pi` key, or use conventional directories.
+
+## Table of Contents
+
+- [Install and Manage](#install-and-manage)
+- [Package Sources](#package-sources)
+- [Creating a Pi Package](#creating-a-pi-package)
+- [Package Structure](#package-structure)
+- [Dependencies](#dependencies)
+- [Package Filtering](#package-filtering)
+- [Enable and Disable Resources](#enable-and-disable-resources)
+- [Scope and Deduplication](#scope-and-deduplication)
+
+## Install and Manage
+
+> **Security:** Pi packages run with full system access. Extensions execute arbitrary code, and skills can instruct the model to perform any action including running executables. Review source code before installing third-party packages.
+
+```bash
+pi install bun:@foo/bar@1.0.0
+pi install git:github.com/user/repo@v1
+pi install https://github.com/user/repo  # raw URLs work too
+pi install /absolute/path/to/package
+pi install ./relative/path/to/package
+
+pi remove bun:@foo/bar
+pi list    # show installed packages from settings
+pi update  # update all non-pinned packages
+```
+
+By default, `install` and `remove` write to global settings (`~/.pi/agent/settings.json`). Use `-l` to write to project settings (`.pi/settings.json`) instead. Project settings can be shared with your team, and pi installs any missing packages automatically on startup.
+
+To try a package without installing it, use `--extension` or `-e`. This installs to a temporary directory for the current run only:
+
+```bash
+pi -e bun:@foo/bar
+pi -e git:github.com/user/repo
+```
+
+## Package Sources
+
+Pi accepts three source types in settings and `pi install`.
+
+### bun
+
+```
+bun:@scope/pkg@1.2.3
+bun:pkg
+```
+
+- Versioned specs are pinned and skipped by `pi update`.
+- Global installs use `bun add -g`.
+- Project installs go under `.pi/bun/`.
+- Set `bunCommand` in `settings.json` to pin Bun package lookup and install operations to a specific wrapper command such as `mise`.
+
+Example:
+
+```json
+{
+  "bunCommand": ["mise", "exec", "bun@1.3", "--", "bun"]
+}
+```
+
+### git
+
+```
+git:github.com/user/repo@v1
+git:git@github.com:user/repo@v1
+https://github.com/user/repo@v1
+ssh://git@github.com/user/repo@v1
+```
+
+- Without `git:` prefix, only protocol URLs are accepted (`https://`, `http://`, `ssh://`, `git://`).
+- With `git:` prefix, shorthand formats are accepted, including `github.com/user/repo` and `git@github.com:user/repo`.
+- HTTPS and SSH URLs are both supported.
+- SSH URLs use your configured SSH keys automatically (respects `~/.ssh/config`).
+- For non-interactive runs (for example CI), you can set `GIT_TERMINAL_PROMPT=0` to disable credential prompts and set `GIT_SSH_COMMAND` (for example `ssh -o BatchMode=yes -o ConnectTimeout=5`) to fail fast.
+- Refs pin the package and skip `pi update`.
+- Cloned to `~/.pi/agent/git/<host>/<path>` (global) or `.pi/git/<host>/<path>` (project).
+- Runs `bun install` after clone or pull if `package.json` exists.
+
+**SSH examples:**
+```bash
+# git@host:path shorthand (requires git: prefix)
+pi install git:git@github.com:user/repo
+
+# ssh:// protocol format
+pi install ssh://git@github.com/user/repo
+
+# With version ref
+pi install git:git@github.com:user/repo@v1.0.0
+```
+
+### Local Paths
+
+```
+/absolute/path/to/package
+./relative/path/to/package
+```
+
+Local paths point to files or directories on disk and are added to settings without copying. Relative paths are resolved against the settings file they appear in. If the path is a file, it loads as a single extension. If it is a directory, pi loads resources using package rules.
+
+## Creating a Pi Package
+
+Add a `pi` manifest to `package.json` or use conventional directories. Include the `pi-package` keyword for discoverability.
+
+```json
+{
+  "name": "my-package",
+  "keywords": ["pi-package"],
+  "pi": {
+    "extensions": ["./extensions"],
+    "skills": ["./skills"],
+    "prompts": ["./prompts"],
+    "themes": ["./themes"]
+  }
+}
+```
+
+Paths are relative to the package root. Arrays support glob patterns and `!exclusions`.
+
+### Gallery Metadata
+
+The [package gallery](https://shittycodingagent.ai/packages) displays packages tagged with `pi-package`. Add `video` or `image` fields to show a preview:
+
+```json
+{
+  "name": "my-package",
+  "keywords": ["pi-package"],
+  "pi": {
+    "extensions": ["./extensions"],
+    "video": "https://example.com/demo.mp4",
+    "image": "https://example.com/screenshot.png"
+  }
+}
+```
+
+- **video**: MP4 only. On desktop, autoplays on hover. Clicking opens a fullscreen player.
+- **image**: PNG, JPEG, GIF, or WebP. Displayed as a static preview.
+
+If both are set, video takes precedence.
+
+## Package Structure
+
+### Convention Directories
+
+If no `pi` manifest is present, pi auto-discovers resources from these directories:
+
+- `extensions/` loads `.ts` and `.js` files
+- `skills/` recursively finds `SKILL.md` folders and loads top-level `.md` files as skills
+- `prompts/` loads `.md` files
+- `themes/` loads `.json` files
+
+## Dependencies
+
+Third party runtime dependencies belong in `dependencies` in `package.json`. Dependencies that do not register extensions, skills, prompt templates, or themes also belong in `dependencies`. When pi installs a package from Bun package specs or git, it runs `bun install`, so those dependencies are installed automatically.
+
+Pi bundles core packages for extensions and skills. If you import any of these, list them in `peerDependencies` with a `"*"` range and do not bundle them: `@lenylvt/pi-ai`, `@lenylvt/pi-agent-core`, `@lenylvt/pi-coding-agent`, `@lenylvt/pi-tui`, `@sinclair/typebox`.
+
+Other pi packages must be bundled in your tarball. Add them to `dependencies` and `bundledDependencies`, then reference their resources through `node_modules/` paths. Pi loads packages with separate module roots, so separate installs do not collide or share modules.
+
+Example:
+
+```json
+{
+  "dependencies": {
+    "shitty-extensions": "^1.0.1"
+  },
+  "bundledDependencies": ["shitty-extensions"],
+  "pi": {
+    "extensions": ["extensions", "node_modules/shitty-extensions/extensions"],
+    "skills": ["skills", "node_modules/shitty-extensions/skills"]
+  }
+}
+```
+
+## Package Filtering
+
+Filter what a package loads using the object form in settings:
+
+```json
+{
+  "packages": [
+    "bun:simple-pkg",
+    {
+      "source": "bun:my-package",
+      "extensions": ["extensions/*.ts", "!extensions/legacy.ts"],
+      "skills": [],
+      "prompts": ["prompts/review.md"],
+      "themes": ["+themes/legacy.json"]
+    }
+  ]
+}
+```
+
+`+path` and `-path` are exact paths relative to the package root.
+
+- Omit a key to load all of that type.
+- Use `[]` to load none of that type.
+- `!pattern` excludes matches.
+- `+path` force-includes an exact path.
+- `-path` force-excludes an exact path.
+- Filters layer on top of the manifest. They narrow down what is already allowed.
+
+## Enable and Disable Resources
+
+Use `pi config` to enable or disable extensions, skills, prompt templates, and themes from installed packages and local directories. Works for both global (`~/.pi/agent`) and project (`.pi/`) scopes.
+
+## Scope and Deduplication
+
+Packages can appear in both global and project settings. If the same package appears in both, the project entry wins. Identity is determined by:
+
+- bun: package name
+- git: repository URL without ref
+- local: resolved absolute path