pi-session-mcp 0.7.0 → 0.8.0

package/docs/architecture.md

@@ -47,13 +47,13 @@ reconciled only when the registration still matches that binding. A changed
 release fails closed and cannot silently inherit or replace another release's
 registration.
 
-`pi_capabilities_get` projects the validated workspace and execution-profile maps plus the immutable configuration metadata captured while loading the file. It returns aliases plus the configured permission/provider/model/thinking intent, sorted by alias, and `configuration: { fingerprint, reloadPolicy: "restart-required" }`. The fingerprint is SHA-256 over the exact loaded file bytes, including formatting; it is not a current-file freshness check. The projection makes no provider, authentication, filesystem, network, server-reachability, or catalog-state probe, so it cannot assert availability.
+`pi_capabilities_get` projects the validated workspace and execution-profile maps plus the immutable configuration metadata captured while loading the file. It returns aliases plus the configured permission/provider/model/thinking intent, the configured extension specs and the selected skill aliases, sorted by alias, and `configuration: { fingerprint, reloadPolicy: "restart-required" }`. The fingerprint is SHA-256 over the exact loaded file bytes, including formatting; it is not a current-file freshness check. The projection makes no provider, authentication, filesystem, network, server-reachability, or catalog-state probe, so it cannot assert availability.
 
 ## Deterministic Pi selection
 
-The SDK adapter owns one durable `ModelRuntime`. For the configured profile, it uses that same runtime to call `getProvider(providerId)`, `getModel(providerId, modelId)`, `checkAuth()`, `getAuth(model)`, and `getAvailable(providerId)`. It rejects an absent provider or model, missing or unavailable local authentication, and a model not present in the local available-model set before constructing a session. Authentication uses only Pi's existing local mechanism; auth objects are presence-checked and never retained, serialized, or logged.
+The SDK adapter owns one durable `ModelRuntime` for profiles without extensions. (A profile with `extensions` creates a fresh runtime for each session; see [Pi extensions design](pi-extensions-design.md).) For the configured profile, it uses that runtime to call `getProvider(providerId)`, `getModel(providerId, modelId)`, `checkAuth()`, `getAuth(model)`, and `getAvailable(providerId)`. It rejects an absent provider or model, missing or unavailable local authentication, and a model not present in the local available-model set before constructing a session. Authentication uses only Pi's existing local mechanism; auth objects are presence-checked and never retained, serialized, or logged.
 
-Only then does the adapter call `createAgentSession` with the same runtime and explicit `model`, `thinkingLevel`, and permission-derived `tools`. It never calls `resolveCliModel` or a fuzzy resolver, and does not depend on SDK settings or first-available fallback behavior. After construction it verifies `session.model.provider`, `session.model.id`, and effective `session.thinkingLevel`. A clamped thinking level or any selection mismatch fails closed. Any post-creation failure disposes the SDK session before a handle can enter the registry.
+Only then does the adapter call `createAgentSession` with that runtime and explicit `model`, `thinkingLevel`, and permission-derived `tools`. It never calls `resolveCliModel` or a fuzzy resolver, and does not depend on SDK settings or first-available fallback behavior. After construction it verifies `session.model.provider`, `session.model.id`, and effective `session.thinkingLevel`. A clamped thinking level or any selection mismatch fails closed. Any post-creation failure disposes the SDK session before a handle can enter the registry.
 
 These postchecks establish the selected provider, model, and effective Pi session
 thinking level. They do not inspect provider-side reasoning or enforce a
@@ -65,11 +65,15 @@ provider/engine behavior rather than inferred from the effective level.
 
 The registry owns public UUIDs, lifecycle state, the turn read model, background turn promises, abort, and disposal. A per-session operation queue serializes prompt admission and close; concurrent abort callers share one bounded abort attempt for the active turn. It registers a session only after adapter creation and postconditions complete. Once shutdown begins, starts fail with `server_stopping`; a handle created by an already-running start is disposed instead of admitted. The SDK session ID is never exposed.
 
+## Skills
+
+`skillCatalog` and each profile's `skills` are parsed by `loadConfig`. A path value resolves against the configuration file's directory, like a workspace; a `builtin:<name>` value resolves through the skill library to the operator's override in `skills/<name>` next to the configuration file, else to the skill shipped in the package. Setup, not the server, installs the controller skill into the clients' skill directories. A profile keeps its selected skills as a frozen list of `{alias, path}` pairs; the path never leaves the server. At session start the adapter loads exactly the selected files through the Pi SDK's public `loadSkills` with no default directories and validates them completely (SDK diagnostics, duplicate Pi skill names, aliases that share one canonical file, `disable-model-invocation: true`, files over 256 KiB). The SDK's skill override returns exactly that set, also after extension hooks add resources, so a package's bundled skills, prompt templates and themes no longer reach a session. Any failure is `skill_load_failed` with a fixed message. The model sees the loaded skills in its system prompt and decides itself whether to read one; the server neither guarantees that nor snapshots skill contents. Capability discovery projects only the selected aliases. See [Pi skills](skills.md) and [ADR 0007](adr/0007-profile-skill-selection.md).
+
 ## Lifecycle and public data
 
 `pi_session_prompt` creates a provisional turn identity, invokes Pi preflight, and only after accepted preflight publishes `{session, turn}`; rejected preflight leaves no orphan turn. Completion returns to `idle`; failure is generic. Each active session retains at most 20 turns. A turn is `running`, `completed`, `failed`, or `aborted`; its public view contains IDs, timestamps, and terminal `completedAt`. Completed text is normalized and capped at 64 KiB UTF-8 with Unicode-safe truncation. It can contain model-visible workspace data and remains potentially sensitive.
 
-Session metadata contains only whitelisted values: public session ID, workspace alias, execution-profile alias, derived permission `profile`, post-verified provider/model/effective thinking level, lifecycle state, and timestamps. Capability metadata uses a separate whitelist: server name/version, loaded configuration fingerprint/reload policy, workspace aliases, and configured profile fields. Neither view contains workspace paths, full model objects, SDK session IDs, auth sources, credential paths, headers, base URLs, prompts, transcripts, or raw provider errors.
+Session metadata contains only whitelisted values: public session ID, workspace alias, execution-profile alias, derived permission `profile`, post-verified provider/model/effective thinking level, lifecycle state, and timestamps. Capability metadata uses a separate whitelist: server name/version, loaded configuration fingerprint/reload policy, workspace aliases, and configured profile fields, including the selected skill aliases. Neither view contains workspace paths, full model objects, SDK session IDs, auth sources, credential paths, headers, base URLs, prompts, transcripts, or raw provider errors.
 
 Profile-specific authentication/catalog operations and session creation have fixed server-side deadlines of 5,000 ms and 10,000 ms. Prompt preflight, abort, close cleanup, registry shutdown, and process shutdown have fixed server-side deadlines of 5,000 ms, 5,000 ms, 5,000 ms, 12,000 ms, and 15,000 ms respectively. A preflight timeout returns `prompt_timeout` without publishing a turn. The unpublished operation remains quarantined until its prompt and abort cannot race with later work; late settlement can release that quarantine but never publish the turn. An abort timeout returns `abort_timeout` without falsely marking the turn aborted; a later normal outcome or successful SDK abort may still terminalize it exactly once. Close marks the session terminal, removes its public registry entry deterministically, and performs best-effort abort/dispose. Repeated close calls return a cached closed view while its tombstone is retained. Each SDK handle is disposed at most once. A late promise cannot revive a removed session or mutate a removed turn.
 
@@ -79,4 +83,4 @@ Public errors are stable and sanitized. They omit caller values, complete prompt
 
 ## Scope
 
-The product boundary is local stdio and in-memory-only operation for one trusted local MCP peer. Allowlisted Pi extensions may persist state of their own outside this boundary; Pi Session MCP itself keeps no state beyond process memory. A controller keeps one immutable configuration/profile snapshot for its lifetime; file edits require a genuinely new controller process and do not hot-reload, mark stale, or mutate running sessions. Each new session performs external catalog discovery within the loaded grants, so catalog changes do not require a controller restart, but a running session's active tools remain fixed. Restarting the controller loses all sessions; reconnecting a client reloads configuration only when it actually starts a new controller process. Capability discovery reports captured metadata only and does not prove current-file freshness, server reachability, provider availability, or catalog state. It excludes HTTP, a web UI, persistence/resume, remote access, multi-user behavior, transcript export, streaming, live provider/model discovery, availability probes during capability discovery, and provider credential management. A coding execution profile is an application-level tool selection, not an OS sandbox.
+The product boundary is local stdio and in-memory-only operation for one trusted local MCP peer. Allowlisted Pi extensions may persist state of their own outside this boundary, and their input hooks see every client prompt as `rpc` input, never `interactive`; Pi Session MCP itself keeps no state beyond process memory. A controller keeps one immutable configuration/profile snapshot for its lifetime; file edits require a genuinely new controller process and do not hot-reload, mark stale, or mutate running sessions. Each new session performs external catalog discovery within the loaded grants, so catalog changes do not require a controller restart, but a running session's active tools remain fixed. Skill selection is part of that snapshot, but skill file contents are not: the SDK keeps file paths, so operators must not change a skill file while sessions that use it are active (see [Pi skills](skills.md)). Restarting the controller loses all sessions; reconnecting a client reloads configuration only when it actually starts a new controller process. Capability discovery reports captured metadata only and does not prove current-file freshness, server reachability, provider availability, or catalog state. It excludes HTTP, a web UI, persistence/resume, remote access, multi-user behavior, transcript export, streaming, live provider/model discovery, availability probes during capability discovery, and provider credential management. A coding execution profile is an application-level tool selection, not an OS sandbox.

package/docs/client-setup-design.md

@@ -10,6 +10,7 @@ The repository-local command shape is:
 
 ```text
 npm run --silent setup -- [--dry-run|--apply|--verify|--rollback|--remove] [--json] --target CLIENT:SCOPE:pi-session-mcp
+npm run --silent setup -- [--apply] [--json] --customize-skill NAME
 ```
 
 The script executes the already-built production entry point. Building is a
@@ -61,6 +62,124 @@ of descendant termination must assert zombie-or-absence without catching their
 own failed assertion; fence retention is checked separately with a live member
 and an indeterminate scan.
 
+## Skill installation
+
+Besides the registration, setup installs the controller skill
+`pi-session-orchestration` (`src/setup-skills.ts`). The skill step runs inside
+the same ownership transaction as the registration, per target and after it.
+`--dry-run` and `--verify` run it for every target. `--apply` runs it only for a
+registration finding of `ok` or `unchanged`, and `--rollback` and `--remove`
+only after the registration finding is `ok`. A skill finding therefore never
+blocks a registration, but `divergent`, `failed` and `unsupported` skill
+findings make the overall result `failed`, like any other finding.
+
+**Source.** The effective skill is the operator's override if
+`<override dir>/pi-session-orchestration/SKILL.md` exists, else the shipped skill
+(see [Pi skills](skills.md#the-skill-library)). Setup reads the tree with a
+bounded reader: regular files only, at most 32 files, 1 MiB and 8 levels, no
+links or special files inside the tree, entries whose name starts with `.`
+skipped. A missing or unusable source is `skill_source_invalid`. The fingerprint
+is a SHA-256 over the sorted relative paths and contents.
+
+**Slots.** A slot is the skill directory a client reads:
+
+| Target | Slot |
+| --- | --- |
+| `codex:user` | `~/.agents/skills/pi-session-orchestration` |
+| `claude-code:user`, `claude-code:local` | `~/.claude/skills/pi-session-orchestration` (one shared slot) |
+| `claude-code:project` | `<project>/.claude/skills/pi-session-orchestration` (the directory in which setup runs) |
+
+**Ownership records.** One record per client slot holds the target client,
+the scope kind (`project` or `user`, so Claude Code `user` and `local` share a
+record), the phase and a content fingerprint, plus `replaces` during an update (see below). A home slot uses the
+alias `skill:pi-session-orchestration`. A project slot uses
+`skill:pi-session-orchestration@<id>`, where `<id>` is the first 16 hex digits
+of a SHA-256 over the project's real path: an opaque identity, not a path, so a
+`--remove` in another project never touches this project's copy. The `pending`
+phase is written before the first filesystem change and promoted to `owned`
+after a post-install inspection. During an update, the pending record also
+keeps the fingerprint of the copy it replaces (`replaces`), so an interrupted
+update leaves a copy that setup still recognizes as its own: the next
+`--apply` finishes the update and `--remove` deletes it. A later run that finds
+a `pending` record whose slot already equals the source promotes it.
+
+**Atomic copy.** Setup creates missing parent directories (mode `0755`), stages
+the tree in a temporary directory in the slot's parent (files `0644`, each file
+and directory fsynced), and re-checks that the slot is unchanged
+(fingerprint, device and inode). It then renames the exact old tree to a backup
+name, renames the staged directory into place, inspects the result, and deletes
+the backup only if it is still the exact old tree it moved. An unhealthy
+ownership fence retains staged and backup content for conservative recovery.
+The slot is never edited in place.
+
+**Divergence rules.** Setup never replaces or deletes, and reports
+`skill_divergent` for:
+
+- an installed copy whose fingerprint differs from setup's own copy (the
+  owned fingerprint, or the one a pending update replaces), even if it happens
+  to equal the new source;
+- a copy that differs from the source without a record (a foreign skill of the
+  same name);
+- any entry whose name starts with `.` inside the installed copy: setup never
+  writes such entries, so they are operator content that the fingerprint over
+  the visible files would not protect;
+- a link to anything other than the effective skill, a non-directory at the
+  skill entry, or a tree that cannot be read.
+
+A copy that equals the source stays unowned when no record exists
+(`skill_equivalent` or `skill_already_equivalent`). A link at the skill entry
+whose real path is exactly the effective library skill directory (your
+override, else the shipped skill) is the operator's own equivalent setup:
+`--dry-run` and `--apply` report `skill_linked` (unchanged), `--verify` reports
+`skill_verified`, and removal leaves it alone (`skill_not_owned`). An unmodified owned copy
+that differs from the source is replaced after a package update or a changed
+override (`skill_update_planned`, `skill_updated`).
+
+**Link rules.** The skill entry itself is never followed. In the home
+directory, the client's skills directory (`~/.claude/skills`, `~/.agents/skills`)
+may be the operator's own link, for example into a dotfiles checkout, and is
+resolved to its real path. A project may be untrusted: only the project root is
+canonicalized, and a link anywhere below it makes the slot divergent, so setup
+never writes outside the project. If a slot cannot be resolved at all, the
+finding is `skill_source_invalid` for `--dry-run`, `skill_install_failed` for
+`--apply`, `skill_missing` for `--verify` and `skill_divergent` for removal.
+
+**Shared slot.** For `--rollback` and `--remove`, the Claude Code `user` and
+`local` registrations share one slot. While the other registration is still
+`owned`, the skill stays and the finding is `skill_kept_shared`. The last
+removal deletes it (`skill_removed`; `skill_absent` if it is already gone;
+`skill_not_owned` if setup never owned it). A modified copy is left in place
+(`skill_divergent`) and its record stays, so a later run can finish after you
+removed the copy.
+
+**Remove retry.** Registration removal can finish before skill cleanup, for
+example after an interruption or a `skill_divergent`. When the registration
+record is gone but setup still owns the skill of that target, `--remove` and
+`--rollback` run once more for that target. They first prove that the
+registration is absent and then report the registration as removed and clean up
+the skill. They never run for a target whose skill setup does not own, nor for
+a Claude Code `user` or `local` target while the other one of the two is still
+registered, and an unowned live registration stays untouched
+(`ownership_unavailable`).
+
+Skill reports carry only client, scope, the alias `pi-session-orchestration`,
+status and a stable code. No skill content, fingerprint or path leaves setup.
+
+## Skill customization
+
+`setup --customize-skill <name>` (and `--apply --customize-skill <name>`,
+`src/skill-customize.ts`) does not touch clients and takes no ownership lock. It
+copies a shipped skill into the override directory `skills/` next to the
+configuration file and records the shipped fingerprint under the skill name in
+`<override dir>/.pi-session-mcp-bases.json` (`{"schemaVersion":1,"bases":{...}}`,
+strictly validated, at most 64 KiB, replaced atomically). The copy is staged in
+a temporary directory and renamed into place; an existing override is never
+overwritten. A changed shipped skill is only reported (`skill_override_outdated`);
+`--apply` then moves the recorded base and nothing else. It cannot be combined
+with `--target`, `--verify`, `--rollback` or `--remove`. The finding target is
+`{ client: "skills", scope: "override", alias: <name> }`; the alias is the
+skill name only if it is valid, else `invalid`.
+
 ## Verification boundary
 
 Production verification requires the offline Doctor, exact public client-CLI registration inspection, and a directly launched bounded MCP handshake. The verifier calls `pi_capabilities_get` with `{}` only; session start/prompt/turn and provider/model operations are forbidden. Its child process is terminated and awaited before success is reported.
@@ -84,7 +203,20 @@ Stable finding codes are grouped by responsibility:
 - verification: `registration_not_equivalent`, `mcp_verified`,
   `mcp_unsupported`, `mcp_timeout`, `mcp_failed`;
 - rollback/removal: `rolled_back`, `removed`, `ownership_diverged`,
-  `cleanup_failed`.
+  `cleanup_failed`;
+- controller skill, dry-run: `skill_absent`, `skill_equivalent`, `skill_linked`,
+  `skill_update_planned`, `skill_divergent`, `skill_source_invalid`;
+- controller skill, apply: `skill_installed`, `skill_already_equivalent`, `skill_linked`,
+  `skill_updated`, `skill_divergent`, `skill_source_invalid`,
+  `skill_install_failed`;
+- controller skill, verify: `skill_verified`, `skill_missing`,
+  `skill_not_equivalent`;
+- controller skill, rollback/removal: `skill_removed`, `skill_kept_shared`,
+  `skill_not_owned`, `skill_absent`, `skill_divergent`;
+- skill customization: `skill_customize_planned`, `skill_customized`,
+  `skill_override_current`, `skill_override_outdated`, `skill_base_updated`,
+  `skill_not_shipped`, `skill_bases_corrupt`, `skill_override_invalid`,
+  `skill_customize_failed`.
 
 The public statuses are `planned`, `ok`, `unchanged`, `absent`, `divergent`,
 `unsupported`, and `failed`. Reports never contain command arguments, command

package/docs/client-setup.md

@@ -90,6 +90,77 @@ bounded direct MCP `initialize`, `tools/list`, and
 `pi_capabilities_get({})` check. It never starts a session or invokes
 a provider.
 
+### Controller skill
+
+Besides the registration, `--apply` installs the controller skill
+`pi-session-orchestration` for each target, as a real copy of the effective
+skill: your override in the skill library if you have one, else the skill
+shipped in the package ([Pi skills](skills.md)). Clients discover it without
+further steps.
+
+| Target | Where the skill goes |
+| --- | --- |
+| `codex:user:pi-session-mcp` | `~/.agents/skills/pi-session-orchestration` |
+| `claude-code:user:pi-session-mcp`, `claude-code:local:pi-session-mcp` | `~/.claude/skills/pi-session-orchestration` (one shared directory) |
+| `claude-code:project:pi-session-mcp` | `<project>/.claude/skills/pi-session-orchestration`, where `<project>` is the directory in which setup runs |
+
+Every result therefore has a second finding per target, with the same client
+and scope and the alias `pi-session-orchestration`:
+
+```text
+apply: ok
+claude-code/user/pi-session-mcp: ok (applied)
+claude-code/user/pi-session-orchestration: ok (skill_installed)
+```
+
+Skill findings per operation:
+
+- `--dry-run`: `skill_absent` (absent), `skill_equivalent` (unchanged),
+  `skill_linked` (unchanged; a link to exactly the effective skill),
+  `skill_update_planned` (planned), `skill_divergent` (divergent),
+  `skill_source_invalid` (failed).
+- `--apply`: `skill_installed` (ok), `skill_already_equivalent` (unchanged),
+  `skill_linked` (unchanged),
+  `skill_updated` (ok; setup replaced its own unmodified copy after a package
+  update or a changed override), `skill_divergent`, `skill_source_invalid`,
+  `skill_install_failed` (failed).
+- `--verify`: `skill_verified` (ok), `skill_missing` and
+  `skill_not_equivalent` (failed).
+- `--rollback` and `--remove`: `skill_removed` (ok), `skill_kept_shared`
+  (unchanged; the other Claude Code `user` or `local` registration still uses
+  the shared directory), `skill_not_owned` (unchanged), `skill_absent` (ok) and
+  `skill_divergent` (a modified copy stays in place).
+
+Setup never replaces or deletes a modified installed copy, a skill of the same
+name that it did not install, or a link or non-directory at the skill entry; it
+reports `skill_divergent`. That does not block the registration, but it makes
+the overall status `failed` (exit 1). Never edit the installed copy. To
+customize the skill, run `--apply --customize-skill pi-session-orchestration`,
+edit the override, and run `--apply` for the target again. Design and trust
+rules: [setup lifecycle design](client-setup-design.md#skill-installation).
+
+Setup installs only `pi-session-orchestration` into clients. Worker skills are
+for Pi profiles and are selected through `builtin:` entries in `skillCatalog`.
+
+### Customize a shipped skill
+
+```bash
+npm run --silent setup -- --customize-skill pi-session-review
+npm run --silent setup -- --apply --customize-skill pi-session-review
+```
+
+This works without `--target` and needs `PI_SESSION_MCP_CONFIG`. It copies the
+shipped skill into the `skills/` directory next to the configuration file and
+records the fingerprint of the shipped skill in
+`.pi-session-mcp-bases.json` there. The finding target is
+`skills/override/<name>`; the codes are `skill_customize_planned` (planned),
+`skill_customized` (ok), `skill_override_current` (unchanged),
+`skill_override_outdated` (planned), `skill_base_updated` (ok),
+`skill_not_shipped`, `skill_bases_corrupt`, `skill_override_invalid` and
+`skill_customize_failed` (failed). An existing override is never overwritten.
+After `skill_override_outdated`, `--apply` moves only the recorded base, which
+acknowledges a change you reviewed. Details: [Pi skills](skills.md#customize-and-add-skills).
+
 ## Local configuration
 
 Create an unversioned JSON configuration file such as `pi-session-mcp.json`:
@@ -118,7 +189,7 @@ Create an unversioned JSON configuration file such as `pi-session-mcp.json`:
 }
 ```
 
-Configuration is strict. A profile has exactly `default`, `permissionProfile`, `provider`, `model`, and `thinkingLevel`, plus the optional `mcpServers` and `extensions` described in [Installation](installation.md); aliases follow the configured alias naming rules. At least one profile and exactly one default are required, and that default must be `read-only`. `thinkingLevel` is one of `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. Workspace paths resolve relative to the configuration file. Clients can select only configured aliases, never an arbitrary working directory.
+Configuration is strict. A profile has exactly `default`, `permissionProfile`, `provider`, `model`, and `thinkingLevel`, plus the optional `mcpServers`, `extensions` and `skills` described in [Installation](installation.md) and [Pi skills](skills.md); aliases follow the configured alias naming rules. At least one profile and exactly one default are required, and that default must be `read-only`. `thinkingLevel` is one of `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. Workspace paths resolve relative to the configuration file. Clients can select only configured aliases, never an arbitrary working directory.
 
 Use placeholders until a locally available provider/model pair is known. Do not put keys, tokens, credential objects, headers, base URLs, or authentication paths in this file.
 
@@ -190,7 +261,7 @@ Claude Code enforces each tool's declared JSON Schema (`additionalProperties: fa
 ## Expected flow and lifecycle deadlines
 
 1. Call `pi_capabilities_get` with `{}` and select explicit workspace and read-only execution-profile aliases from the returned config-derived lists.
-2. Call `pi_session_start` with those aliases. The server resolves the configured provider/model through its one `ModelRuntime`, checks existing local Pi authentication and availability, creates with explicit model/thinking/tools, and verifies the effective SDK result.
+2. Call `pi_session_start` with those aliases. The server resolves the configured provider/model through its shared `ModelRuntime` (a profile with extensions gets a fresh runtime for each session), loads and validates the profile's selected skills, checks existing local Pi authentication and availability, creates with explicit model/thinking/tools, and verifies the effective SDK result.
 3. Call `pi_session_prompt` with the returned `sessionId` and a read-only prompt. It returns after accepted preflight with a `turnId` in `running` state.
 4. Poll `pi_turn_get` with that `sessionId` and `turnId` until `completed`, `failed`, or `aborted`, with a deadline no longer than three minutes. There is no `pi_turn_wait` tool.
 5. Call `pi_session_close` when the session is no longer needed.
@@ -246,7 +317,7 @@ Poll `pi_turn_get` for at most three minutes. If it does not become terminal, re
 
 ### A prompt fails immediately after a provider config or credential change
 
-`pi_session_prompt` reads the configured provider/model through one `ModelRuntime` that is created once and cached for the lifetime of the Pi Session MCP server process; the underlying SDK reads `~/.pi/agent/models.json` only at that creation. Editing that file (for example adding or fixing a provider API key) does not take effect in an already-running server process, and a resulting turn typically fails (`turn_failed`) within milliseconds rather than after a real provider round trip. Restart or reconnect the MCP server (which restarts the process) after any provider config or credential change, then retry.
+For profiles without extensions, `pi_session_prompt` reads the configured provider/model through one `ModelRuntime` that is created once and cached for the lifetime of the Pi Session MCP server process (a profile with extensions creates a fresh runtime when each session starts); the underlying SDK reads `~/.pi/agent/models.json` only at that creation. Editing that file (for example adding or fixing a provider API key) does not take effect in an already-running server process, and a resulting turn typically fails (`turn_failed`) within milliseconds rather than after a real provider round trip. Restart or reconnect the MCP server (which restarts the process) after any provider config or credential change, then retry.
 
 ### Session cleanup
 

package/docs/doctor-design.md

@@ -10,7 +10,7 @@ directory: an npm executable can run from any directory.
 sanitized semver `packageVersion` when metadata is available, ordered `checks`,
 and `exitCode`). Human and JSON output are projections of that same model.
 Subjects are only fixed component names, validated workspace aliases, or
-validated `<profile>:<package>` pairs; paths, configuration values, errors,
+validated `<profile>:<package>`, `<profile>:<skill-alias>` or `skill:<name>` pairs; paths, configuration values, errors,
 credentials, and provider data are never output.
 
 Each check is `{ id, severity, subject, remediation? }`. Severity is `ok`,
@@ -34,9 +34,17 @@ and owners are:
 | `workspace_not_writable` | A workspace is not writable while a coding profile can target it | validated workspace alias |
 | `extension_missing` | Pi has no user install of a package that a profile's `extensions` names | `<profile>:<package>` |
 | `extension_version_mismatch` | The installed manifest's version differs from the pinned version, or the manifest or its `pi.extensions` entries are invalid | `<profile>:<package>` |
+| `skill_missing` | The `SKILL.md` file that a profile's selected skill alias names does not exist; a `builtin:<name>` value that matches no override and no shipped skill resolves to the shipped location and is reported here | `<profile>:<skill-alias>` |
+| `skill_unreadable` | A selected skill path is not a regular file, is larger than 256 KiB, or cannot be read | `<profile>:<skill-alias>` |
+| `skill_duplicate` | Two selected skill aliases of one profile resolve to the same canonical file | `<profile>:<skill-alias>` |
+| `skill_override_outdated` | Warning. The current fingerprint of a shipped skill differs from the base recorded in the skill bases file next to the configuration file, or the bases file is corrupt | `skill:<name>`, or `skill:bases` for a corrupt file |
 
 Doctor reads extension manifests from Pi's user install location only; it never installs packages and never imports extension code.
 
+The skill checks run after the extension checks. They look only at file availability: Doctor never reads a skill's frontmatter, never parses or executes it, and the subject carries the catalog alias, never a path. Frontmatter, skill-name rules, name collisions and explicit-only flags (`disable-model-invocation`) are checked only at session start by the Pi SDK contract, so a clean Doctor run does not promise that a skill loads. Unknown or duplicate aliases and two selected aliases with one path are configuration errors and surface as `config_invalid`. See [Pi skills](skills.md).
+
+`skill_override_outdated` concerns the operator's skill overrides, not a profile. It is `ok` for a recorded base that still matches the shipped skill, and a warning (exit status 1, never blocking `setup`) when the shipped skill changed after the operator ran `pi-session-mcp-setup --customize-skill <name>`; its remediation names `pi-session-mcp-setup --apply --customize-skill <name>` to acknowledge a reviewed change. Only skills with a recorded base are compared, and a recorded name that is no longer shipped is skipped. A corrupt bases file yields a warning with the subject `skill:bases`. Doctor reads the bases file and the shipped skill files only; nothing is executed and the subject is a validated skill name, never a path. The check sorts after `skill_duplicate`.
+
 The Doctor reuses `loadConfig`; it does not duplicate alias, profile, thinking
 level, or read-only-default rules. Workspace values are used only for local
 filesystem checks and are never copied into the result.

package/docs/installation.md

@@ -14,12 +14,14 @@ Pi Session MCP is a local, stdio-only MCP server. An MCP client starts
 Nothing listens on a network port, no daemon runs between client sessions, and
 session state exists only in the memory of that child process.
 
-An installation consists of three locations:
+An installation consists of these locations:
 
 | What | Location | Notes |
 | --- | --- | --- |
 | Package | the npm global prefix, or a dedicated directory per release such as `~/.local/share/pi-session-mcp/releases/<tag>` | The built server, `setup` and Doctor. |
 | Configuration | a file outside the package, for example `~/.config/pi-session-mcp/pi-session-mcp.json` | Operator-owned, mode `0600`, never committed. |
+| Skill overrides (optional) | the `skills/` directory next to the configuration file, for example `~/.config/pi-session-mcp/skills/` | Your own or customized skills, plus `.pi-session-mcp-bases.json`. Created by you or by `setup --customize-skill`. See [Pi skills](#pi-skills). |
+| Controller skill | `~/.agents/skills/pi-session-orchestration` (Codex), `~/.claude/skills/pi-session-orchestration` or `<project>/.claude/skills/pi-session-orchestration` (Claude Code) | Written by `setup --apply`; see [Register a client](#4-register-a-client). |
 | Setup ownership state | `~/.local/state/pi-session-mcp/ownership.json` | Written by `setup` only. Path-free and secret-free. |
 
 Never register a development checkout. A registered client launches
@@ -155,7 +157,14 @@ Rules:
 - A profile may load Pi extensions that Pi has installed, through
   `extensions`: a list of at most 8 entries of the form
   `npm:<name>@<exact version>`, each package once. Ranges, tags, `git:`
-  sources and paths are rejected. See [Pi extensions](#pi-extensions).
+  sources, paths and build metadata (`+build`) are rejected. See [Pi extensions](#pi-extensions).
+- A profile may select Pi skills through `skills`: a list of at most 16 aliases
+  from the top-level `skillCatalog`, which maps an alias to `builtin:<name>`
+  (a skill of the package or of your override directory) or to the path of one
+  `SKILL.md` file (at most 64 entries). A relative path resolves against the
+  configuration file's directory; `~` is not expanded. The example already uses
+  `builtin:` for the two worker skills, so you need not change its skill
+  entries. See [Pi skills](#pi-skills).
 - Never put keys, tokens, credential objects, headers, base URLs or
   authentication paths into this file.
 
@@ -217,6 +226,10 @@ pi-session-mcp-setup --apply --target claude-code:user:pi-session-mcp
 pi-session-mcp-setup --verify --target claude-code:user:pi-session-mcp
 ```
 
+`--apply` also installs the controller skill `pi-session-orchestration` for the
+target, after the registration, so the client knows how to drive Pi worker
+sessions. See [Controller skill](#controller-skill).
+
 `setup` changes a Codex registration only through `codex mcp add` and
 `codex mcp remove`, and Codex rewrites `config.toml` on each of them. Codex CLI
 `0.162.0` groups all `[mcp_servers.*]` tables together and drops a comment
@@ -224,12 +237,14 @@ directly above such a table; settings are preserved. If your `config.toml`
 contains comments worth keeping, copy it before `--apply`, `--rollback` or
 `--remove` on `codex:user:pi-session-mcp`.
 
-Each report has one line for the operation with its overall status, and one line
-per target with a finding in the form `status (code)`:
+Each report has one line for the operation with its overall status, and per
+target two lines with a finding in the form `status (code)`: the registration
+and the controller skill, whose alias is `pi-session-orchestration`:
 
 ```text
 dry-run: planned
 claude-code/user/pi-session-mcp: absent (absent)
+claude-code/user/pi-session-orchestration: absent (skill_absent)
 ```
 
 Expected results:
@@ -237,8 +252,11 @@ Expected results:
 | Operation | Overall | Finding | Meaning |
 | --- | --- | --- | --- |
 | `--dry-run` | `planned` | `absent (absent)` | No registration exists. Apply will add one. |
+| `--dry-run` | `planned` | `absent (skill_absent)` | The controller skill is not installed. Apply will install it. |
 | `--apply` | `ok` | `ok (applied)` | The registration was added and is now owned by `setup`. |
+| `--apply` | `ok` | `ok (skill_installed)` | The controller skill was copied into the client's skill directory and is owned by `setup`. |
 | `--verify` | `ok` | `ok (mcp_verified)` | Doctor passed, the registration equals the intended one, and a direct MCP handshake listed the eight tools and answered `pi_capabilities_get`. |
+| `--verify` | `ok` | `ok (skill_verified)` | The installed skill equals the effective skill. |
 
 Verify never starts a session and never contacts a provider. Add `--json` to
 any operation for the sanitized JSON report. Exit status `0` is success, `1` an
@@ -255,6 +273,39 @@ If a registration already exists, `setup` never replaces it:
 Start a new client session after registering. The client launches the server on
 demand; there is nothing to start by hand.
 
+### Controller skill
+
+`--apply` copies the effective `pi-session-orchestration` skill (your override
+if you have one, else the shipped skill) as a real copy to the client's skill
+directory, where the client discovers it without further steps:
+
+| Target | Skill directory |
+| --- | --- |
+| `codex:user:pi-session-mcp` | `~/.agents/skills/pi-session-orchestration` |
+| `claude-code:user:pi-session-mcp`, `claude-code:local:pi-session-mcp` | `~/.claude/skills/pi-session-orchestration` (one shared directory) |
+| `claude-code:project:pi-session-mcp` | `<project>/.claude/skills/pi-session-orchestration`, where `<project>` is the directory in which you run `setup` |
+
+- `setup` never replaces or deletes a modified installed copy, hidden files
+  inside it (macOS Finder's `.DS_Store` counts too), a skill of the same name
+  that it did not install, or a link or non-directory entry. It reports
+  `skill_divergent`; the registration is still made, but the overall status is
+  `failed`. A link to exactly the effective skill is accepted as your own
+  (`skill_linked`). Inside a project, any link below the project root counts as
+  divergent.
+- A package update or a changed override replaces setup's own unmodified copy on
+  the next `--apply` (`skill_updated`). `--remove` and `--rollback` delete it
+  again (`skill_removed`), except while the other Claude Code registration of
+  the shared directory still uses it (`skill_kept_shared`).
+- To change the skill, do not edit the installed copy. Run
+  `pi-session-mcp-setup --apply --customize-skill pi-session-orchestration`,
+  edit the override it creates, and run `--apply` for the target again.
+- Setup installs only this one skill into clients. Worker skills are for Pi
+  profiles; additional controller skills of your own belong in the clients'
+  native skill directories.
+
+The codes and the rules are in [Pi skills](skills.md#install-the-orchestration-skill-into-codex-and-claude-code)
+and the [setup lifecycle design](client-setup-design.md#skill-installation).
+
 ### Register without setup
 
 `setup` runs on Linux and macOS. On every other platform, Windows included, it
@@ -277,7 +328,11 @@ acceptance level covers this path.
    directory: in an npm installation `echo "$(npm root -g)/pi-session-mcp"`
    prints that directory, in a release checkout it is the checkout. Write the
    resulting absolute path into the command; a substitution inside the single
-   quotes of the Codex example would not be expanded.
+   quotes of the Codex example would not be expanded. A manual registration
+   installs no skill. To use the controller skill, copy (do not link) the
+   directory `skills/pi-session-orchestration` of the package to the client's
+   skill directory listed under [Controller skill](#controller-skill), and
+   repeat the copy after an upgrade.
 3. Check the registration. These checks are not a replacement for
    `setup --verify`: it also performs a bounded direct MCP handshake, and
    outside `setup` nothing does that yet. The last check below depends on the
@@ -374,13 +429,16 @@ pin the installed version in the profile:
   and system-prompt changes. In `read-only` profiles the model still gets only
   `read`, `grep`, `find` and `ls`; in `coding` profiles every extension tool
   may be active. Extension commands never run from client prompts, but
-  extension input hooks can still see, rewrite or consume a client prompt.
+  extension input hooks can still see, rewrite or consume a client prompt;
+  they receive it with `source: "rpc"`, never `interactive`.
 - **Fail-closed start.** A session start fails with `extension_load_failed` if
   an extension reports a hook error while binding. It fails the same way if an
   extension registers an MCP server while loading or starting, because Pi's
   built-in MCP extension is not loaded. An extension tool whose name collides
-  with another tool, or whose name is not a plain identifier, fails with
-  `extension_tool_conflict`.
+  with another tool, or whose name is not 1 to 64 letters, digits, `_` or `-`
+  (not starting with `-`), or whose name Pi treats as an MCP tool (starting
+  with `mcp__`, or `list_mcp_resources`, `list_mcp_resource_templates`,
+  `read_mcp_resource`), fails with `extension_tool_conflict`.
 - **Cursor runtime.** `pi-cursor-sdk` runs Cursor's local agent runtime. That
   runtime starts its own processes (for example git and the MCP servers
   configured for Cursor) and may act through Cursor's own tooling, so a
@@ -391,6 +449,57 @@ pin the installed version in the profile:
   reports a placeholder key. Session start succeeds and the first prompt fails
   with `turn_failed`. Store the key with Pi first.
 
+## Pi skills
+
+An execution profile can give its sessions Pi skills. The package ships two
+worker skills, `pi-session-implementation` and `pi-session-review`, and the
+controller skill `pi-session-orchestration`, in its `skills/` directory. The
+catalog maps an alias to a skill; the profile selects aliases. MCP callers never
+choose skills.
+
+```json
+"skillCatalog": {
+  "pi-session-review": "builtin:pi-session-review"
+},
+"executionProfiles": {
+  "safe-readonly": {
+    "default": true,
+    "permissionProfile": "read-only",
+    "provider": "your-configured-provider",
+    "model": "your-configured-model",
+    "thinkingLevel": "medium",
+    "skills": ["pi-session-review"]
+  }
+}
+```
+
+- `builtin:<name>` resolves to your override
+  `<directory of the configuration file>/skills/<name>/SKILL.md` if it exists,
+  else to the shipped skill. The shipped example configuration already uses
+  `builtin:pi-session-implementation` and `builtin:pi-session-review`, so the
+  copied example needs no path edits for skills. Adding or removing an override
+  needs a server restart, like any configuration change.
+- To adjust a shipped skill, run `pi-session-mcp-setup --customize-skill <name>`
+  (a dry-run) and then `pi-session-mcp-setup --apply --customize-skill <name>`
+  with `PI_SESSION_MCP_CONFIG` set. It copies the shipped skill into the
+  override directory as a starting point and never overwrites an existing
+  override. Edit the copy, then restart the server. To add a skill of your own,
+  create `<override dir>/<new-name>/SKILL.md` and reference it as
+  `builtin:<new-name>`; no command is needed. After a package update, Doctor
+  warns with `skill_override_outdated` when a shipped skill changed since you
+  copied it.
+- A `builtin:` name with no override and no shipped skill makes Doctor report
+  `skill_missing` and the session start fail with `skill_load_failed`.
+- An extension allowlist alone makes none of a package's skills available. If a
+  profile relied on them, add a catalog entry with the absolute path of the
+  package's `SKILL.md` and select it; see the migration section of [Pi
+  skills](skills.md).
+- A skill file is read by the SDK at session start and later by the model.
+  Do not change skill files while sessions that use them are active; close
+  those sessions first.
+
+The complete rules, errors, Doctor checks and limits are in [Pi skills](skills.md).
+
 ## Upgrade
 
 `setup` binds each owned registration to the package manifests and to every
@@ -398,6 +507,12 @@ built runtime file, so the old version must remove its registration before the
 new one applies. Read the [changelog](../CHANGELOG.md) before upgrading; it
 records changes that affect operators, such as renamed provider keys.
 
+Removing the registration also removes the controller skill that setup
+installed, unless you modified it, and `--apply` for the new version installs
+the new text. A package update that changes a shipped skill does not touch an
+override of yours; Doctor warns with `skill_override_outdated` so that you can
+review the change.
+
 ### npm installation
 
 An npm upgrade replaces the package in place. Close the client sessions that
@@ -462,7 +577,12 @@ npm uninstall -g pi-session-mcp
 same owned removal and reports `rolled_back`; use it to undo an apply. After
 every target reports `removed`, uninstall the package or delete the release
 directory, and delete the configuration file and
-`~/.local/state/pi-session-mcp/`.
+`~/.local/state/pi-session-mcp/`. The same call removes the controller skill
+that `setup` installed (`skill_removed`). It keeps a copy that you modified
+(`skill_divergent`) and the shared Claude Code directory while the other
+Claude Code registration is still owned (`skill_kept_shared`). Your override
+directory `skills/` next to the configuration file is yours: delete it with the
+configuration file if you no longer need it.
 
 ## When something fails