@pikaa-ai/pikaa 0.2.4 → 0.3.0

package/skills/pi-agent/references/overview.md

@@ -0,0 +1,37 @@
+# Pi Documentation Overview
+
+Source: https://pi.dev/docs/latest
+
+Pi is a minimal terminal coding harness. The core stays small and most workflow-specific behavior lives in TypeScript extensions, skills, prompt templates, themes, and Pi packages. Positioning on `https://pi.dev/`: "There are many agent harnesses but this one is yours" — four run modes (interactive, print/JSON, RPC, SDK), 15+ providers with mid-session model switching, tree-structured shareable sessions, steering and follow-up during a run, and extensible primitives instead of baked-in features.
+
+## Top-Level Areas
+
+- Start here: quickstart, usage, providers, llama.cpp, security, containerization, settings, keybindings, sessions, compaction.
+- Customization: extensions, skills, prompt templates, themes, Pi packages, custom models, custom providers.
+- Programmatic usage: SDK, RPC mode, JSON event stream mode, TUI components.
+- Reference: environment variables, session file format and SessionManager API.
+- Platform setup: Windows, Termux, tmux, terminal setup, shell aliases.
+- Development: local source setup, rebranding, debug logs, tests, package structure.
+
+## Quick Install
+
+```bash
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent
+pi
+```
+
+On Linux/macOS the installer is also available:
+
+```bash
+curl -fsSL https://pi.dev/install.sh | sh
+```
+
+pnpm and bun global installs work too (`pnpm add -g --ignore-scripts ...`, `bun add -g --ignore-scripts ...`).
+
+Authenticate with `/login` for subscription providers or set API keys such as `ANTHROPIC_API_KEY` before startup.
+
+## Ecosystem
+
+Package gallery at `https://pi.dev/packages` lists community extensions tagged `pi-package`. Source: `https://github.com/earendil-works/pi` (formerly `pi-mono`; docs live under `packages/coding-agent/docs/`, and doc pages still link the old repo name, which redirects).
+
+Pi requires Node.js >= 22.19.0. The published version this skill was written against is `0.84.2` (`https://pi.dev/api/latest-version` reports the current one).

package/skills/pi-agent/references/packages.md

@@ -0,0 +1,103 @@
+# Pi Packages
+
+Source: https://pi.dev/docs/latest/packages
+
+Pi packages bundle extensions, skills, prompt templates, and themes for sharing through npm, git, URL, or local paths. Packages run with full system access — extensions execute arbitrary code and skills can instruct the model to run executables. Review third-party source before installing.
+
+## Install and Manage
+
+```bash
+pi install npm:@foo/bar@1.0.0
+pi install git:github.com/user/repo@v1
+pi install https://github.com/user/repo
+pi install /absolute/path/to/package
+pi install ./relative/path/to/package
+
+pi remove npm:@foo/bar
+pi list                     # installed packages from settings
+pi update                   # update pi only
+pi update --all             # pi + packages; reconcile pinned git refs
+pi update --extensions      # packages only; reconcile pinned git refs
+pi update --models          # refresh model catalogs only
+pi update --self            # update pi only
+pi update --self --force    # reinstall pi even if current
+pi update npm:@foo/bar      # update one package
+pi update --extension npm:@foo/bar
+pi config                   # enable/disable package resources
+```
+
+`install`/`remove` write to user settings by default; `-l` writes to project settings (`.pi/settings.json`), which can be shared with a team — Pi installs missing project packages automatically on startup after the project is trusted. To try a package for one run without installing, use `-e`/`--extension` (installs to a temporary directory):
+
+```bash
+pi -e npm:@foo/bar
+pi -e git:github.com/user/repo
+```
+
+## Sources
+
+**npm** — `npm:@scope/pkg@1.2.3` or `npm:pkg`. Versioned specs are pinned and skipped by package updates. User installs go under `~/.pi/agent/npm/`, project installs under `.pi/npm/`. `npmCommand` in settings pins npm operations to a wrapper such as `mise`.
+
+**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 the `git:` prefix only protocol URLs are accepted (`https://`, `http://`, `ssh://`, `git://`); with it, shorthand forms work. SSH URLs use your configured keys and respect `~/.ssh/config`. For CI, set `GIT_TERMINAL_PROMPT=0` and `GIT_SSH_COMMAND` (e.g. `ssh -o BatchMode=yes -o ConnectTimeout=5`) to fail fast. Refs are pinned tags or commits — updates reconcile an existing clone to the configured ref but never move it to a newer ref; use `pi install git:host/user/repo@new-ref` to move it. Clones live in `~/.pi/agent/git/<host>/<path>` or `.pi/git/<host>/<path>`. Reconciliation resets and cleans the clone, then runs `npm install` when `package.json` exists.
+
+**Local paths** — absolute or relative, added to settings without copying. Relative paths resolve against the settings file. A file loads as a single extension; a directory loads using package rules.
+
+## Package Manifest
+
+```json
+{
+  "name": "my-package",
+  "keywords": ["pi-package"],
+  "pi": {
+    "extensions": ["./extensions"],
+    "skills": ["./skills"],
+    "prompts": ["./prompts"],
+    "themes": ["./themes"]
+  }
+}
+```
+
+Paths are relative to the package root and support glob patterns and `!exclusions`. The `pi-package` keyword makes the package visible in the [gallery](https://pi.dev/packages); add `pi.video` (MP4 only, autoplays on hover) or `pi.image` (PNG/JPEG/GIF/WebP) for a preview — video wins if both are set.
+
+Without a manifest, Pi auto-discovers convention directories: `extensions/` (`.ts` and `.js`), `skills/` (recursive `SKILL.md` folders plus top-level `.md` files), `prompts/` (`.md`), `themes/` (`.json`).
+
+## Dependencies
+
+Third-party runtime dependencies belong in `dependencies`; Pi runs `npm install` when installing from npm or git.
+
+Pi bundles core packages for extensions and skills. If you import `@earendil-works/pi-ai`, `@earendil-works/pi-agent-core`, `@earendil-works/pi-coding-agent`, `@earendil-works/pi-tui`, or `typebox`, list them in `peerDependencies` with `"*"` and do not bundle them.
+
+Other Pi packages must be bundled: add them to `dependencies` **and** `bundledDependencies`, then reference their resources through `node_modules/` paths. Pi loads packages with separate module roots, so separate installs neither collide nor share modules.
+
+## Filtering
+
+```json
+{
+  "packages": [
+    "npm:simple-pkg",
+    {
+      "source": "npm:my-package",
+      "extensions": ["extensions/*.ts", "!extensions/legacy.ts"],
+      "skills": [],
+      "prompts": ["prompts/review.md"],
+      "themes": ["+themes/legacy.json"]
+    }
+  ]
+}
+```
+
+Omit a key to load all of that type, `[]` to load none, `!pattern` to exclude matches, `+path` to force-include an exact path, `-path` to force-exclude. `+`/`-` paths are exact and relative to the package root. Filters narrow what the manifest already allows.
+
+## Enable/Disable and Scope
+
+`pi config` toggles extensions, skills, prompt templates, and themes from installed packages and local directories. It starts in global settings; Tab switches between global and project-local, and `pi config -l` starts in project overrides with inherited global resources dimmed.
+
+A package can appear in both global and project settings. The project entry wins unless it sets `autoload: false`, in which case it applies as a delta over the global entry. Identity: npm package name, git repository URL without ref, or resolved absolute path for local packages.
+
+## Notable Ecosystem Packages
+
+- `pi install npm:pi-subagents` — delegation, chains, parallel runs: `references/pi-subagents.md`
+- `pi install npm:pi-mcp-adapter` — token-efficient MCP server access: `references/pi-mcp-adapter.md`
+- `pi install npm:pi-web-access` — web search, URL/PDF/repo fetching, video understanding: `references/pi-web-access.md`
+- `pi install npm:pi-interview` — interactive interview forms: `references/pi-interview.md`
+- `pi install npm:glimpseui` — native macOS WebView windows used by several packages
+- `pi install npm:@gotgenes/pi-permission-system` — runtime allow/ask/deny policy, composes with pi-subagents

package/skills/pi-agent/references/pi-interview.md

@@ -0,0 +1,123 @@
+# pi-interview Package
+
+Source: https://pi.dev/packages/pi-interview
+
+Interactive interview forms: the agent collects structured user responses through a form with single/multi-select, text input, image upload, and info panels, plus rich media (code, diffs, Markdown, images, Chart.js charts, Mermaid diagrams, tables, HTML).
+
+```bash
+pi install npm:pi-interview
+pi install npm:glimpseui   # optional: native macOS window; browser fallback otherwise
+```
+
+Requires Pi v0.82.1 or later. Restart Pi after installing.
+
+## Invocation
+
+```javascript
+await interview({
+  questions: '/path/to/questions.json',
+  timeout: 600,    // optional, seconds (default 600)
+  verbose: false   // optional, debug logging
+});
+```
+
+Lifecycle: the tool starts a local server and opens a Glimpse window (macOS), an Orca tab, or a browser tab → the user answers at their own pace with auto-save and timeout reset on any activity → the session ends by Submit (`⌘+Enter`), timeout (warning overlay with an option to stay), or Escape twice → the window closes and the agent receives responses, or `null` if cancelled.
+
+Remote and Moshi sessions: when the session looks remote (ssh/mosh env, or an active remote login on the host), the tool skips or supplements the local window and prints the form URL with access hints — a Moshi tip when the moshi-hook gateway is running (tap the preview button in the terminal title bar and pick the interview server), and an exact `ssh -L` command for plain SSH (mosh cannot forward ports). The server binds low ports (8377+, scanning forward on collision) and answers tokenless loopback opens with a landing page that hops to the form, so Moshi's browser preview reaches it in one tap. Requests with a non-loopback `Host` header are rejected.
+
+With multiple concurrent interviews, only the first auto-opens; the rest are queued and surfaced as URLs in tool output, plus a top-right toast with a dropdown to open queued sessions. Submitting the active interview redirects the window to the next queued one. A status bar shows project path, git branch, and session ID.
+
+## Question Schema
+
+```json
+{
+  "title": "Project Setup",
+  "description": "Review my suggestions and adjust as needed.",
+  "questions": [
+    { "id": "context", "type": "info", "question": "Architecture context",
+      "context": "This project needs SSR and edge deployment support." },
+    { "id": "framework", "type": "single", "question": "Which framework?",
+      "options": ["React", "Vue", "Svelte"],
+      "recommended": "React", "conviction": "strong", "weight": "critical" },
+    { "id": "features", "type": "multi", "question": "Which features?",
+      "options": ["Auth", "Database", "API"], "recommended": ["Auth", "Database"] },
+    { "id": "notes", "type": "text", "question": "Additional requirements?" },
+    { "id": "mockup", "type": "image", "question": "Upload a design mockup" }
+  ]
+}
+```
+
+Question types: `single` (radio), `multi` (checkbox), `text`, `image` (upload), `info` (non-interactive panel).
+
+| Field | Purpose |
+|---|---|
+| `id`, `type`, `question` | Identifier, type, question text |
+| `options` | Choices for single/multi; strings or `{ label, content? }` objects |
+| `recommended` | Pre-selected option(s) with a "Recommended" badge |
+| `conviction` | `"strong"` or `"slight"` (slight opts out of pre-selection); requires `recommended` |
+| `weight` | `"critical"` (prominent card) or `"minor"` (compact card) |
+| `context` | Help text below the question |
+| `content` | Code/diff/Markdown block: `{ source, lang, file, lines, highlights, showSource }`; `lang: "diff"` renders a diff, `lang: "md"`/`"markdown"` previews Markdown |
+| `media` | Object or array of `image`, `table`, `chart`, `mermaid`, `html`; each supports `position` (`"above"`/`"below"`/`"side"`) and `caption`; tables take `{ headers, rows, highlights }` |
+
+Single/multi questions also support an "Other" custom-text option, per-question image attachments (button or drag & drop), "✦ Generate more" and "↻ Review options" LLM actions, an "Ask about an option" inline assistant panel with prompt chips and provider/model overrides, and an optional per-option clarification field.
+
+## Response Format
+
+```typescript
+interface Response {
+  id: string;
+  value: string | string[];
+  attachments?: string[];  // image paths attached to non-image questions
+}
+```
+
+## Settings
+
+`~/.pi/agent/settings.json`:
+
+```json
+{
+  "interview": {
+    "timeout": 600,
+    "port": 19847,
+    "snapshotDir": "~/.pi/interview-snapshots/",
+    "autoSaveOnSubmit": true,
+    "generateModel": "anthropic/claude-haiku-4-5",
+    "launcher": "browser",
+    "browser": "Firefox",
+    "glimpseFloating": false,
+    "theme": {
+      "mode": "auto",
+      "name": "default",
+      "lightPath": "/path/to/light.css",
+      "darkPath": "/path/to/dark.css",
+      "toggleHotkey": "mod+shift+l"
+    }
+  }
+}
+```
+
+Timeout precedence: function parameter > settings > default 600s. A fixed `port` keeps the URL stable across sessions. `generateModel` drives the generate/review option actions, defaulting to the agent's current model then a cheap available model; if an explicitly configured model fails and the session uses a different one, it retries once with the session model. `glimpseFloating` keeps the native macOS window above others (browser fallback unaffected).
+
+`launcher` chooses where the form opens; omit it for the default (Glimpse on a local macOS session with `glimpseui` installed, otherwise a browser tab):
+
+- `"glimpse"` — native macOS Glimpse window; requires a local macOS session with `glimpseui`, and reports why the window could not open instead of falling back to a browser.
+- `"browser"` — browser tab even when Glimpse is installed.
+- `"orca"` — a browser tab in the current [Orca](https://github.com/stablyai/orca)-managed worktree, or Orca's focused worktree when the cwd is outside one; the tab is focused when that worktree is visible, otherwise staged in its tab bar. Needs `orca` on `PATH`.
+
+`browser` names the application used for browser tabs (`"Firefox"`, `"Brave Browser"`, …). It applies to `launcher: "browser"` and to an omitted `launcher` when Glimpse is unavailable; it has no effect under `"glimpse"` or `"orca"`.
+
+Themes: built-ins are `default` (monospace) and `tufte` (serif); modes are `dark` (default), `light`, and `auto` (follows the OS, user override persists in localStorage). Custom themes are CSS files overriding variables such as `--bg-body`, `--bg-card`, `--bg-elevated`, `--bg-selected`, `--fg`, `--fg-muted`, `--accent`, `--border`, `--success`, `--warning`, `--error`, `--focus-ring`.
+
+## Keyboard
+
+`↑`/`↓` navigate options, `⌘+←`/`⌘+→` navigate questions (Ctrl off macOS), `Tab` cycles, `Enter`/`Space` selects, `⌘+V` pastes into the focused input, `⌘+Enter` submits, `Esc` shows the exit overlay (twice to quit), `⌘+Shift+L` toggles the theme when enabled.
+
+## Recovery and Snapshots
+
+Abandoned or timed-out interviews save their questions to `~/.pi/interview-recovery/{date}_{time}_{project}_{branch}_{sessionId}.json`, auto-deleted after 7 days. Snapshots (manual Save button, or automatic on submit with `autoSaveOnSubmit`) land in `~/.pi/interview-snapshots/{title}-{project}-{branch}-{timestamp}[-submitted]/` as `index.html` plus an `images/` subfolder. Resume either by passing the recovery JSON or the snapshot `index.html` path as `questions` — the form reopens with answers pre-populated.
+
+## Limits
+
+Max 12 images per submission, 5 MB per image, 4096×4096 pixels, types PNG/JPG/GIF/WebP.

package/skills/pi-agent/references/pi-mcp-adapter.md

@@ -0,0 +1,191 @@
+# pi-mcp-adapter Package
+
+Source: https://pi.dev/packages/pi-mcp-adapter
+
+MCP adapter extension for Pi. Instead of loading hundreds of tool definitions upfront, it exposes one `mcp` proxy tool (~200 tokens) that discovers and calls tools on demand. Servers connect lazily and disconnect when idle; tool metadata is cached to disk so search/describe work offline.
+
+```bash
+pi install npm:pi-mcp-adapter
+```
+
+Restart Pi after installation. On first run the adapter reads standard MCP files automatically. If you only have host-specific configs (Cursor, Claude Code, Codex, …), run `/mcp setup` to adopt them, or `pi-mcp-adapter init` to scan and add compatibility imports to the Pi agent dir config.
+
+## Configuration Files
+
+Precedence, lowest to highest:
+
+1. `~/.config/mcp/mcp.json` — user-global shared
+2. `~/.agents/mcp.json` — user-global tool-agnostic
+3. `~/.agents/mcp/mcp.json` — user-global tool-agnostic
+4. `<Pi agent dir>/mcp.json` — Pi global override (`~/.pi/agent/mcp.json`, or `$PI_CODING_AGENT_DIR/mcp.json`)
+5. `.mcp.json` — project-local shared (preferred for projects)
+6. `.pi/mcp.json` — Pi project override
+
+```json
+{
+  "mcpServers": {
+    "chrome-devtools": { "command": "npx", "args": ["-y", "chrome-devtools-mcp@1.6.0"] }
+  }
+}
+```
+
+Host-specific configs are detected but **not** loaded automatically, and the normal `/mcp` panel does not scan them while `settings.hostConfigDiscovery` is `"off"` (the default). Opt in with `"on"` (or `pi-mcp-adapter init --discover-host-configs`); `"prompt"` detects without activating. Host configs sit below every shared and Pi-owned source.
+
+Import specific host formats explicitly with `"imports": ["cursor", "claude-code", "claude-desktop", "opencode", "vscode", "windsurf", "codex"]`.
+
+### Agent Plugins
+
+List [Agent Plugins](https://agent-plugins.org/) package directories in `settings.agentPluginPaths` to load their MCP servers:
+
+```json
+{ "settings": { "agentPluginPaths": ["./plugins/acme-tools"] }, "mcpServers": {} }
+```
+
+Each directory needs a valid Agent Plugins 1.0 `plugin.json`; a root `mcp.json` there contributes `mcpServers` entries prefixed `<plugin>__<server>`. The loader uses the transport declared by each server `type` and skips invalid entries without blocking others. For stdio plugin servers, `${PLUGIN_ROOT}` and `${PLUGIN_DATA}` expand only in `args`, `env`, and `cwd`; both are set for the child process and plugin data is stored under the Pi agent directory. Native Pi MCP config remains `.mcp.json`, `~/.config/mcp/mcp.json`, and the Pi-owned overrides.
+
+`/mcp disable <server>` / `/mcp enable <server>` persist only the `disabled` field into `.pi/mcp.json` (never rewriting the source file or copying credentials); run `/reload` to apply. The manual equivalent is `{ "disabled": true }` in any MCP config.
+
+### SDK Configuration
+
+```ts
+import { createMcpAdapter } from "pi-mcp-adapter";
+const extension = createMcpAdapter({ config: { mcpServers: { docs: { url: "https://mcp.example.com/mcp", lifecycle: "eager" } } } });
+```
+
+A supplied `config` is a complete isolated snapshot — never merged with files, imports, or `--mcp-config`, and cloned per adapter/session. Status, reconnect, explicit `/mcp-auth <server>`, proxy calls, and direct tools still work; setup and no-argument auth/status panels report the limitation. With `configPath` and no `config`, normal file merging applies and that path outranks argv and `--mcp-config`. The package ships TypeScript source, so standalone Node processes need a TS-capable loader (e.g. `node --import tsx`).
+
+OAuth credentials are stored in the OS credential store keyed by configured server name, with URL binding so credentials cannot be reused for a different server URL. `settings.oauthDir` / `MCP_OAUTH_DIR` are legacy plaintext `tokens.json` import locations only.
+
+Cooperating Pi extensions can reuse URL-bound tokens through the public `pi-mcp-adapter/oauth` subpath (`getMcpOAuthTokensForUrl(server, url)`, `updateMcpOAuthTokensForUrl(server, url, tokens)`, plus a status helper). The async read path applies the adapter's refresh logic first. It exposes token read/update only — never client registration secrets, PKCE verifiers, or OAuth state — and keeps secure-store storage, URL binding, refresh persistence, chunk handling, legacy import, and fail-closed credential-store errors.
+
+## Server Options
+
+| Field | Description |
+|---|---|
+| `command`, `args` | stdio transport; mutually exclusive with `url` and `socket` |
+| `socket` | `rmcp-mux` Unix socket path; supports `${VAR}`, `$env:VAR`, `~` |
+| `env`, `cwd` | Interpolation supported; an `env` value starting with `!` runs a command at connect (`!!` escapes) |
+| `url`, `headers` | StreamableHTTP with SSE fallback; interpolation supported, missing URL vars fail before any request |
+| `auth` | `"bearer"` or `"oauth"` |
+| `oauth.*` | `grantType` (`authorization_code` default, or `client_credentials`), `clientId` (MCP 2026 prefers pre-registered clients or Client ID Metadata Documents; Dynamic Client Registration is the fallback when omitted), `clientSecret`, `scope`, `redirectUri` (exact localhost callback for pre-registered clients), `clientName`, `clientUri` (defaults to the host manifest's `piConfig.clientUri`, omitted under a rebranded host), `logoUri` (absolute `http(s)` URL, RFC 7591 `logo_uri`), `authorizationParams` (extra authorization-URL parameters; flow-owned ones such as `client_id`, `redirect_uri`, `scope`, `state`, `code_challenge`, `response_type`, `resource` cannot be overridden), `skipIssuerMetadataValidation` |
+| `bearerToken` / `bearerTokenEnv` | Token or env var name; interpolation and `!command` supported |
+| `lifecycle` | `"lazy"` (default), `"eager"`, `"keep-alive"`, `"lazy-keep-alive"` |
+| `idleTimeout` | Minutes before idle disconnect (overrides global) |
+| `requestTimeoutMs` | Per-server request timeout; omitted or `<= 0` uses the MCP SDK default |
+| `protocolVersion` | `"legacy"` (default), `"auto"`, or `"2026-07-28"` — modern negotiation is opt-in |
+| `exposeResources` | Expose MCP resources as tools (default `true`) |
+| `directTools` | `true`, `string[]`, or `false` |
+| `toolPrefix` | Per-server override of the global `toolPrefix` |
+| `includeTools` / `excludeTools` | Names or glob patterns; `excludeTools` applies after `includeTools` |
+| `searchKeywords` | `{ "tool-or-glob": ["keyword", …] }` extra keywords boosting `mcp({ search })` ranking; never shown to the model |
+| `approveTools` | `true` or glob array requiring approval before calls (overrides the global setting) |
+| `debug` | Show server stderr (default `false`) |
+| `trace` | Metadata-only JSONL protocol tracing for this server |
+| `disabled` | Keep visible in config/status but block connections, auth, tools, resources (only literal `true`) |
+
+Secret values in `headers`, `bearerToken`, `oauth.clientSecret`, and stdio `env` may use a leading `!command` resolved at connect/auth time: stdin and stderr suppressed, stdout capped at 1 MiB and trimmed, 10-second limit, non-empty output required. Commands never run during discovery, merging, previewing, hashing, or rendering config.
+
+`oauth.skipIssuerMetadataValidation: true` disables the RFC 8414 issuer echo check for one server. It weakens OAuth mix-up protection — use it only for a known-misconfigured internal server while its metadata is being fixed, never for public or untrusted servers.
+
+**Protocol version negotiation** — the default `"legacy"` uses the classic MCP initialize sequence with no `server/discover` or 2026 headers, preserving compatibility with deployed 2025-era servers. `"auto"` probes for MCP 2026-07-28 and conservatively falls back to the classic handshake on legacy evidence; set it for Cloudflare Workers `createMcpHandler` and other MCP SDK v2 stateless servers. For stdio servers, `"auto"` probes with a short-lived sibling process before starting the session process, so each fresh connection adds one spawn and may wait out the request timeout; explicit Unix sockets probe in place. HTTP auto negotiation uses the real Streamable HTTP connection and falls back to legacy SSE only on definitive rejection (404/405/406/415) — never on auth failures, cancellation, timeouts, or server errors. `"2026-07-28"` pins that revision with no legacy or SSE fallback. Strict OAuth issuer validation applies in every mode. Adapter-level roots support, standard MCP logging presentation, and protocol cache-hint config are not yet implemented.
+
+**Lifecycle modes** — `lazy`: connect on first tool call, disconnect after idle, cached metadata keeps search working. `eager`: connect at startup, no auto-reconnect, no idle timeout unless set. `keep-alive`: connect at startup with health checks and auto-reconnect. `lazy-keep-alive`: connect on first use, then stay resident with auto-reconnect. Any enabled `eager`/`keep-alive` server also triggers initialization at extension load, supporting hosts that never emit `session_start`.
+
+**rmcp-mux** — point `socket` at an [`rmcp-mux`](https://github.com/VetCoders/rmcp-mux) service socket to share one stdio server across Pi sessions. The adapter owns only its client socket; the mux owns the upstream process, routing, restart policy, and socket permissions. A socket is an explicit trusted local endpoint.
+
+## Global Settings
+
+```json
+{ "settings": { "toolPrefix": "server", "idleTimeout": 10, "requestTimeoutMs": 30000, "trace": { "enabled": true } } }
+```
+
+`toolPrefix` (`"server"` default, `"short"` strips a `-mcp` suffix, `"none"`, `"mcp"` prefixes `mcp__`; per-server `toolPrefix` overrides it), `idleTimeout` (minutes, default 10, `0` disables), `requestTimeoutMs`, `showStatusIcon` (default `true`), `mcpFooterStatus` (`"full"` default, `"compact"`, `"off"`), `toolResultRendering` (`"compact"` default self-rendered rows, or `"boxed"` for the legacy Pi tool row), `collapsedResultLines` (`1`–`3`; defaults `1` compact / `3` boxed), `notifyOnStartupConnect` (default `true`; `false` suppresses routine connect notices but keeps errors and auth warnings), `hostConfigDiscovery`, `agentPluginPaths`, `approveTools`, `oauthDir`, `directTools` (global default, default `false`), `freezeDirectTools` (default `false`), `scriptMode` (default `true`; registers the MCP-only `mcpScript` plain-JavaScript tool), `disableProxyTool`, `autoAuth` (default `false`), `sampling` (default `true` when UI approval is available; honors `modelPreferences.hints`), `samplingAutoApprove` (required for sampling in non-UI sessions), `elicitation` (default `true` with UI), `outputGuard`, `trace` (`{ enabled, file, maxBytes: 262144, maxEvents: 10000 }`; the per-session JSONL defaults to `.pi/mcp-traces/` and never records payloads, prompts, arguments/results, auth data, or URLs).
+
+Per-server `idleTimeout`, `requestTimeoutMs`, and `approveTools` override the global values.
+
+### Tool Approval
+
+`approveTools` keeps a tool visible but gates the call — useful for destructive or high-cost actions where hiding the tool would hurt planning:
+
+```json
+{ "settings": { "approveTools": ["github_delete_*", "notion_update_*"] },
+  "mcpServers": { "github": { "approveTools": ["delete_*", "merge_pull_request"] }, "docs": { "approveTools": false } } }
+```
+
+A matching call from the proxy tool, a direct MCP tool, `mcpScript`, a resource call, or an MCP UI iframe prompts **Allow once** / **Allow for session** / **Deny**; session approvals live in memory only, and headless sessions fail closed with an `approval_required` result. `excludeTools` still removes tools entirely — `approveTools` only gates visible ones.
+
+Permission extensions can broker decisions by listening on `MCP_TOOL_APPROVAL_REQUEST_EVENT` (`pi-mcp-adapter:tool-approval-request`) and claiming the request synchronously with `request.claim(async () => "allow_once" | "allow_for_session" | "deny" | "abstain")`. The request carries `serverName`, `originalToolName`, `prefixedToolName`, `args`, `origin`, and an optional `signal`; the first synchronous claim wins, `allow_for_session` updates the same in-memory cache as the dialog, and `abstain`/no claim keeps the fallback behavior. Brokered approval runs for every uncached MCP call regardless of `approveTools` config.
+
+### Search Keywords
+
+Search matches literally, so per-server `searchKeywords` adds vocabulary for tools whose names and descriptions use different words:
+
+```json
+{ "mcpServers": { "github": { "searchKeywords": { "search_code": ["grep"], "*": ["gh"] } } } }
+```
+
+Keys match a tool's original name, prefixed name, or a glob (`*` covers every tool on the server), and all matching entries combine. Keywords are weighted like description text with an extra boost on exact phrase matches. They affect ranked and regex search only (including `tools.search` in `mcpScript`) and never appear in tool schemas, `describe` output, direct-tool registration, or the metadata cache — so keyword search works offline from cached metadata.
+
+## Output Guard
+
+On by default: inline text is capped at **50 KiB / 2000 lines** (matching Pi's `bash` guard), with the full text spilled to a temp file whose path is included so the agent can `read`/`grep` it. Image blocks pass through unchanged. Binary resource blobs up to **10 MiB** are decoded to private temp files and replaced with file references, bounded to 100 MiB and 10,000 files per session and removed at session teardown. In proxy mode `details.mcpResult` stays raw when its JSON is ≤ 16 KiB; larger results become a compact summary with the raw JSON spilled to a temp file (direct tools never carry `mcpResult`). Tune with `{ maxBytes, maxLines, detailsMaxBytes }`; disable with `"outputGuard": false` or `MCP_OUTPUT_GUARD=0`. Temp files are mode `0600` under the system temp dir and are not cleaned up automatically.
+
+## Direct Tools
+
+```json
+{ "mcpServers": { "github": { "directTools": ["search_repositories", "get_file_contents"] } } }
+```
+
+`true` registers all of a server's tools individually, an array registers only those (original MCP names), omitted/`false` is proxy-only. Per-server overrides the global default. `includeTools`/`excludeTools` filter direct tools, proxy search/list/describe, and the `/mcp` panel. Each direct tool costs ~150–300 tokens, so use targeted sets of 5–20; for 75+ tool servers stay on the proxy.
+
+Direct tools register from the metadata cache (`~/.pi/agent/mcp-cache.json`, or `$PI_CODING_AGENT_DIR/mcp-cache.json`), so no startup connections are needed. The first session after adding `directTools` falls back to proxy-only while the cache populates, then hot-loads. Servers advertising list-change notifications refresh the current session. Force a refresh with `/mcp reconnect <server>`.
+
+Set `settings.freezeDirectTools: true` when prompt-cache stability matters more than hot-loading: the initial sync still runs, but later automatic reconnects, lazy-connects, and list-change notifications leave the registered tool surface unchanged. Deliberate refreshes via `mcp({ connect: "server" })` or `/mcp reconnect <server>` still update it.
+
+## Proxy Tool API
+
+```javascript
+mcp({ })                                        // status / list servers
+mcp({ server: "name" })                         // server details (+ instructions preview)
+mcp({ search: "screenshot navigate", limit: 12, offset: 0 })  // ranked tool search
+mcp({ describe: "tool_name" })
+mcp({ instructions: "name" })                   // full server instructions
+mcp({ tool: "chrome_devtools_take_screenshot", args: { format: "png" } })
+mcp({ connect: "server-name" })                 // connect or refresh
+mcp({ action: "ui-messages" })
+mcp({ action: "auth-start", server: "name" })
+mcp({ action: "auth-complete", server: "name", args: { redirectUrl: "http://localhost:19876/callback?code=...&state=..." } })
+```
+
+`args` accepts a JSON object or a JSON string. Search covers MCP tools **and** Pi extension tools (prefixed `[pi tool]`, listed first). Space-separated words are ranked by weighted matches across name, server, description, and any configured `searchKeywords`, then paginated (`limit` defaults to 12; follow `details.nextOffset`). `regex: true` still works but paginates without ranking. Names fuzzy-match on hyphens and underscores, and an unresolvable `describe`/`tool` name returns top suggestions so the agent can fix a typo in the same turn. With `includeSchemas`, search and describe render common JSON Schema parameters as compact TypeScript shapes like `{ query: string; limit?: number; }`. For HTTP servers, a failed connect runs a one-request shape probe that turns opaque transport errors into hints such as `endpoint returned HTML (200) — this URL does not appear to speak MCP`. Server `instructions` surface at three levels: a truncated head in the proxy tool description, a longer preview in `mcp({ server })`, and the full text via `mcp({ instructions })` — captured at connect time and cached.
+
+Remote/headless OAuth: `/mcp-auth <server>` first shows a clickable authorization URL. Open it in your local browser, approve, then select **Yes** in Pi to open the callback input — the browser's localhost callback page will usually fail to load (localhost is your workstation), so copy the full URL from its address bar and paste it into Pi. When the browser can reach Pi's callback directly, the authorization screen closes on its own instead. The same flow is available through the proxy tool (`auth-start` then `auth-complete` with `redirectUrl` or `args: { code }`) for non-interactive clients. Persistent OAuth requires an available OS credential store — on headless Linux, an unlocked Secret Service/libsecret keyring; the adapter fails closed rather than storing plaintext. On Linux, when credential access fails because Pi inherited a revoked session keyring, the adapter attempts recovery through `keyctl session - node <packaged helper>` (requires `keyctl` and `node` on `PATH`) so re-authentication can write fresh credentials without killing a long-lived tmux server.
+
+## Commands
+
+`/mcp` (interactive panel: status, tools, direct/proxy toggles, reconnect, `ctrl+a` or Enter for OAuth, Save on `ctrl+s` — remappable via the `mcp.panel.save` keybinding), `/mcp setup` (imports, a minimal `.mcp.json`, curated known servers — DeepWiki, Context7, Notion, GitHub, Chrome DevTools — RepoPrompt quick-add, config-path inspection), `/mcp tools`, `/mcp prompts`, `/mcp reconnect [server]`, `/mcp disable <server>`, `/mcp enable <server>`, `/mcp logout <server>`, `/mcp-auth [server]`.
+
+## Prompts, Elicitation, UI
+
+MCP prompt templates register as slash commands `/mcp__<server>__<prompt>`, refreshed on connect. Arguments support positional and `key=value` forms with quoting; required arguments are validated before `prompts/get`. Results flatten into one user message preserving `[user]`/`[assistant]` markers.
+
+Elicitation forms use Pi's `select()`/`input()` dialogs with validation and a review step; explicit refusal maps to MCP `decline`, dismissal to `cancel`. URL mode is TUI-only, always shows requesting server/host/URL, and requires consent; `-32042` URL-required tool errors are handled — retry the original call after completing the browser step.
+
+MCP UI resources open in a native macOS window via Glimpse (`pi install npm:glimpseui`) or fall back to the browser. `MCP_UI_VIEWER=browser|glimpse|none` forces or suppresses the viewer (`none` still runs the tool and returns inline results). UIs talk back — message types `prompt`, `intent`, `notify`, `message`, plus custom types forwarded as intents — retrieved with `mcp({ action: "ui-messages" })` (each with `type`, `sessionId`, `serverName`, `toolName`, `timestamp`). Calling the same tool again pushes a new result into the open window instead of replacing it. Tool consent gates whether UIs may call MCP tools (never / once-per-server / always), and `_meta.ui.visibility` controls audience — app-only tools stay out of the model tool list, model-only tools cannot be called from the UI iframe. Browser controls: Cmd/Ctrl+Enter completes, Escape cancels.
+
+## Status Snapshots
+
+```ts
+import { MCP_STATUS_EVENT, type McpStatusSnapshot } from "pi-mcp-adapter";
+pi.events.on(MCP_STATUS_EVENT, (snapshot) => { /* read-only */ });
+```
+
+Includes `totalTools`, `totalResources`, `connectedCount`, `disabledCount`, and per-server `name`, `status` (connected, cached, failed, needs-auth, not-connected, disabled), `toolCount`, `disabled`, plus `resourceCount` when known and `failedAgoSeconds` on active failure. Reading status never connects a lazy server, starts auth, or exposes clients, transports, credentials, or server definitions. An initial snapshot follows initialization; an empty snapshot is emitted on shutdown.
+
+## Behavior Notes and Limitations
+
+npx-based servers resolve to direct binaries, skipping the ~143 MB npm parent process. Advertised `outputSchema` supports JSON Schema draft-07 and 2020-12 (unstamped schemas use the SDK's 2020-12 default), and returned `structuredContent` is validated for both proxy and direct calls. Results use compact self-rendered rows by default — collapsed success output shows the call title and the first result line plus a `Ctrl+O to expand` hint — while the model still receives the full result. Set `toolResultRendering: "boxed"` for the legacy row, or `collapsedResultLines` to `2`/`3` for more collapsed text.
+
+Limitations: no cross-session server sharing (each Pi session runs its own server processes, unless using rmcp-mux); MCP sampling is text-only (context inclusion, tools, stop sequences, audio, and images are rejected); inline images follow Pi's image display settings; Pi still owns one separator row before self-rendered tool output, so compact mode reduces but cannot eliminate the gap.
+
+Subagents (`pi-subagents`) receive direct MCP tools only when listed with an `mcp:` prefix in their `tools:` frontmatter — a global `directTools: true` is not enough. See `references/pi-subagents.md`.