pi-session-mcp 0.7.1 → 0.8.1

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 recorded base of 0.8.0 (a version 1 fingerprint) is compared through the version 2 value of the released 0.8.0 skill it names; a version 1 base that names no released skill cannot be confirmed and yields a warning that says so, with the same remediation. 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` and its lock file `.pi-session-mcp-bases.lock`. 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
@@ -156,6 +158,13 @@ Rules:
   `extensions`: a list of at most 8 entries of the form
   `npm:<name>@<exact version>`, each package once. Ranges, tags, `git:`
   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
@@ -394,6 +449,58 @@ 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. `--apply --customize-skill` takes a kernel lock on the override
+  directory, so concurrent runs cannot lose a recorded base.
+- 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
@@ -401,6 +508,17 @@ 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.
+
+After an upgrade from 0.8.0, run `setup` as a dry-run and then with `--apply`
+for your targets. Copies and records of 0.8.0 are proven before setup acts on
+them; one that cannot be proven is reported as `skill_legacy_unverified` and
+stays untouched. See [Upgrade from 0.8.0](skills.md#upgrade-from-080).
+
 ### npm installation
 
 An npm upgrade replaces the package in place. Close the client sessions that
@@ -465,7 +583,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
 

package/docs/pi-extensions-design.md

@@ -3,6 +3,14 @@
 Status: approved by the owner on 2026-10-11 for implementation. Tracking issue:
 [#34](https://github.com/plagor44-ux/pi-session-mcp/issues/34).
 
+> **Amended by [ADR 0007](adr/0007-profile-skill-selection.md).** This design
+> assumed that `noSkills` and the other `no*` options keep skills, prompt
+> templates and themes out of every session. With Pi SDK 1.1.0 that did not hold
+> for resources that an allowlisted extension package ships. An extension
+> allowlist now makes none of them available; a skill reaches a session only
+> through the operator's `skillCatalog` and the profile's `skills`. See
+> [Pi skills](skills.md).
+
 ## Goal
 
 An operator can allowlist Pi extensions per execution profile. A profile that
@@ -53,8 +61,10 @@ Success means:
 `DefaultResourceLoader` with `noExtensions: true`, no skills, templates or
 themes, and a disabled system prompt. `SdkPiSessionAdapter.create` resolves
 provider, model, authentication and availability against one `ModelRuntime`
-shared by all sessions, and only then builds the resource loader and calls
-`createAgentSession`.
+shared by the sessions of profiles without extensions (a profile with
+`extensions` gets a runtime of its own, see *Session creation*), and only then
+builds the resource loader and calls `createAgentSession`. This describes the
+state before this feature; ADR 0007 later added the skill selection.
 
 Facts about Pi SDK 1.1.0 that shape this design, verified against the
 installed package:
@@ -85,8 +95,11 @@ installed package:
    mismatched npm packages, and `getInstalledPath(source, "user")` falls back
    to a synchronous `npm root -g` on a miss and accepts legacy global
    installs; neither is side-effect free.
-9. `pi-cursor-sdk` and `@cursor/sdk` call `console.log`. In a stdio MCP server
-   such output corrupts the protocol stream.
+9. Skills, prompt templates and themes that an allowlisted extension package
+   ships reached the session although `noSkills` was set (ADR 0007).
+   `loadSkills` removes duplicate skill names before `skillsOverride` runs.
+10. `pi-cursor-sdk` and `@cursor/sdk` call `console.log`. In a stdio MCP server
+    such output corrupts the protocol stream.
 
 The relevant SDK functions are root exports of
 `@earendil-works/pi-coding-agent`: `createAgentSessionServices`,
@@ -250,6 +263,17 @@ and step 6 leaves no session to dispose.
 - **UI and flags.** No UI context is bound; extension UI calls return the
   SDK's no-op results. `extensionFlagValues` is empty, so extension flags keep
   their defaults.
+- **Turn liveness.** The `updatedAt` of a running turn follows the public SDK
+  events of the prompt: assistant message start, update and end, and tool
+  execution start, update and end. An extension provider with its own agent
+  loop, such as `pi-cursor-sdk`, therefore advances `updatedAt` whenever it
+  publishes streaming updates. Its internal steps that publish no public
+  event stay invisible, so an unchanged `updatedAt` is no proof of a hang, and
+  streaming is no evidence of finished or useful work. Only the event type and
+  the message role are inspected; no delta, thinking block, tool argument or
+  partial result is stored or projected, and the answer still comes only from
+  the final assistant message. See [Tool
+  contracts](tool-contracts.md).
 
 ### Lifecycle and close
 

package/docs/releasing.md

@@ -131,9 +131,15 @@ Patch transitive advisories in the lockfile only:
 
 ## Prepare a release
 
+A release travels in the pull request of the change it ships. That pull
+request also carries the version, the changelog heading and the pre-release
+acceptance record; there is no separate release pull request. Records that can
+only be made after publishing go into the pull request of the next change.
+
 Preconditions:
 
-- `main` contains every change of the release, and Level 1 is green on `main`.
+- The change pull request contains every change of the release, and Level 1
+  is green on its head.
 - `npm audit` reports 0 vulnerabilities.
 - The public contract is unchanged, or a minor release has been decided.
 - The acceptance that this release requires is recorded, or its absence is
@@ -141,8 +147,9 @@ Preconditions:
 
 Steps:
 
-1. Create a release branch from the current `main`. Never reuse a release branch
-   that predates later merges: its lockfile would undo later dependency patches.
+1. Bring the change branch up to date with `main` if `main` moved. Never reuse
+   a branch that predates later merges without that: its lockfile would undo
+   later dependency patches.
 2. Set the version:
 
    ```bash
@@ -159,11 +166,13 @@ Steps:
 5. Run the working-tree
    [Level 2 acceptance](acceptance.md#tooling) on the release candidate with
    `scripts/setup-acceptance.mjs`, unless the release notes state its absence.
-6. Open one pull request named `chore: prepare v<x.y.z> release`.
+6. Record the pre-release acceptance in the status section of
+   [Acceptance](acceptance.md) and push it to the change pull request. Name the
+   release in the pull request's title and description.
 
 ## Publish a release
 
-After the release pull request is merged and CI is green on the merge commit:
+After the change pull request is merged and CI is green on the merge commit:
 
 ```bash
 git switch main
@@ -217,9 +226,9 @@ After publishing:
 
 1. Run the published-release
    [Level 2 acceptance](acceptance.md#working-tree-and-published-release-variants)
-   from a fresh clone of the tag and from the published npm package, and
-   record it. `scripts/setup-acceptance.mjs` runs both
-   ([Tooling](acceptance.md#tooling)).
+   from a fresh clone of the tag and from the published npm package.
+   `scripts/setup-acceptance.mjs` runs both ([Tooling](acceptance.md#tooling)).
 2. Upgrade the installation as described in
    [Installation](installation.md#upgrade).
-3. Update the status section in [Acceptance](acceptance.md).
+3. Record both in the status section of [Acceptance](acceptance.md) with the
+   pull request of the next change, not in a pull request of their own.

package/docs/session-mcp.md

@@ -7,8 +7,13 @@ the Pi session, supplies their definitions as `customTools`, and includes the
 names in Pi's explicit active `tools` list. The selected tools are verified again
 before the session is returned.
 
-Global/project extensions remain disabled (`noExtensions: true`). Installing
-`pi-mcp-adapter` globally is neither required nor sufficient for this integration.
+Global and project extensions are never auto-discovered; only the extensions
+that a profile allowlists load (see [Pi extensions](installation.md#pi-extensions)).
+Installing `pi-mcp-adapter` globally is neither required nor sufficient for this
+integration. Skills are likewise never auto-discovered; a profile gets only the
+skills it selects from the operator's catalog (see [Pi skills](skills.md)).
+Granting an external MCP tool through `mcpServers` and selecting a skill are
+independent: a skill grants no tool.
 There is no automatic import of global MCP configuration or ambient credentials.
 Profiles without `mcpServers` keep their existing built-in tool sets and launch
 no MCP child process. The public `pi_session_start` input remains unchanged: callers