@unbrained/pm-cli 2026.8.25 → 2026.8.27

package/docs/CLAUDE_CODE_PLUGIN.md

@@ -73,9 +73,10 @@ Add to the project's `.mcp.json`:
 ```
 
 The repo root `.mcp.json` uses this approach and activates automatically when
-Claude Code opens this repository. The MCP initialize handshake supplies the
-client name/version to pm's bounded identity detector, so normal agent
-mutations do not need a hard-wired `PM_AUTHOR`.
+Claude Code opens this repository. Under MCP `2026-07-28`, every request carries
+the protocol version, client capabilities, and client identity in `_meta`, so
+pm's bounded identity detector does not depend on session state and normal
+agent mutations do not need a hard-wired `PM_AUTHOR`.
 
 ## MCP Server Launcher
 
@@ -115,7 +116,10 @@ node scripts/smoke-claude-plugin.mjs
 pnpm smoke:claude-plugin
 ```
 
-Verifies: plugin file structure, manifest name consistency, MCP initialize, 31 tools present, full workflow (init → create → claim → update → link files/docs/tests → get → context → search → validate → health), and session-start hook.
+Verifies: plugin file structure, manifest name consistency, stateless MCP
+discovery for `2026-07-28`, 31 tools present, full workflow (init → create →
+claim → update → link files/docs/tests → get → context → search → validate →
+health), and session-start hook.
 
 ### MCP server smoke test
 
@@ -182,7 +186,10 @@ After installing the plugin:
 
 The authoritative plugin version is `plugins/pm-claude/.claude-plugin/plugin.json`; this row stays on the `1.x` major line so it does not drift with each plugin release.
 
-The MCP server uses JSON-RPC 2.0 over stdio with protocol version `2025-06-18`.
+The MCP server uses JSON-RPC 2.0 over stdio with canonical protocol version
+`2026-07-28`. A bounded legacy path remains for unversioned older hosts, with
+`2025-06-18` initialize available to enrich client identity; current hosts
+discover the server and send metadata on every request.
 
 ## Extension Policy Diagnostics
 

package/docs/CLI_GRAMMAR.md

@@ -1,11 +1,17 @@
 # Noun–Verb CLI Grammar and Compatibility Policy
 
-Tracked by [pm-pbyu](../.agents/pm/decisions/pm-pbyu.toon), implemented through [pm-0z7n](../.agents/pm/features/pm-0z7n.toon), [pm-pfqi](../.agents/pm/tasks/pm-pfqi.toon), [pm-yy8rmx](../.agents/pm/tasks/pm-yy8rmx.toon), and [pm-wt43zj](../.agents/pm/tasks/pm-wt43zj.toon).
+Tracked by [pm-pbyu](../.agents/pm/decisions/pm-pbyu.toon), implemented through [pm-0z7n](../.agents/pm/features/pm-0z7n.toon), [pm-pfqi](../.agents/pm/tasks/pm-pfqi.toon), [pm-yy8rmx](../.agents/pm/tasks/pm-yy8rmx.toon), [pm-wt43zj](../.agents/pm/tasks/pm-wt43zj.toon), [pm-e2bq](../.agents/pm/features/pm-e2bq.toon), and [pm-yql1](../.agents/pm/tasks/pm-yql1.toon).
 
 ## Agent Quick Context
 
 Use the canonical noun-first form when generating commands. Existing spellings remain executable, but deprecated compatibility aliases are absent from default help and completion discovery and emit one migration hint on stderr. Machine clients can read alias lifecycle and replacement tokens from `pm contracts --full --json`.
 
+Default `pm --help` stays within the core one-screen budget. Use
+`pm help --all` for every public command or `pm help --all --json` for the same
+surface with per-command visibility/family metadata and the complete alias
+lifecycle table. `--explain` also expands command discovery while adding the
+detailed narrative.
+
 The first completed consolidation is the list family:
 
 ```bash

package/docs/COMMANDS.md

@@ -178,7 +178,7 @@ As a read-only structured surface, `duplicates` accepts the universal output
 controls, including `--output-format json`, `--lean`, projection/amount
 controls, and token accounting, while its default TOON output remains bounded.
 Tracked by [pm-gh1076](../.agents/pm/issues/pm-gh1076.toon).
-Use `pm get <id>` to read a single item by ID — the single-item read primitive used throughout the agent loop. It accepts `--fields <list>` and `--depth brief|standard|deep|full` for token-minimal projections, and `--tree`/`--tree-depth <n>` to include descendants. Standard/deep reads expose a normalized `schedule` facet (`deadline`, `start_at`, `end_at`, `location`, reminders, and events) when scheduling metadata exists. Container-oriented built-ins (Epic, Feature, Milestone, and Plan) plus custom types automatically expose type-agnostic child counts and continuation metadata. Standard depth keeps that rollup counts-only; `--depth deep|full` or an explicit `--fields id,children` request adds the deterministic bounded child sample. Built-in leaf reads avoid a workspace scan unless children are explicitly requested. `pm get <id> --json` returns the `body` inside the `item` object (`.item.body`); see [Full results, totals, and bodies](#full-results-totals-and-bodies). To duplicate an existing item as a starting point, `pm copy <id> --title "New title"` clones it into a fresh id with lifecycle fields reset.
+Use `pm get <id>` to read a single item by ID — the single-item read primitive used throughout the agent loop. It accepts `--fields <list>` and `--depth brief|standard|deep|full` for token-minimal projections, and `--tree`/`--tree-depth <n>` to include descendants. The universal `--output-include` selector can request stored collections directly, for example `pm get <id> --output-include comments,learnings,tests`; the same bare and `item.<field>` grammar works through CLI, SDK, and MCP transports. Standard/deep reads expose a normalized `schedule` facet (`deadline`, `start_at`, `end_at`, `location`, reminders, and events) when scheduling metadata exists. Container-oriented built-ins (Epic, Feature, Milestone, and Plan) plus custom types automatically expose type-agnostic child counts and continuation metadata. Standard depth keeps that rollup counts-only; `--depth deep|full` or an explicit `--fields id,children` request adds the deterministic bounded child sample. Built-in leaf reads avoid a workspace scan unless children are explicitly requested. `pm get <id> --json` returns the `body` inside the `item` object (`.item.body`); see [Full results, totals, and bodies](#full-results-totals-and-bodies). To duplicate an existing item as a starting point, `pm copy <id> --title "New title"` clones it into a fresh id with lifecycle fields reset.
 
 When the strongest duplicate match is terminal because the same work recurred,
 reuse its lineage instead of creating or copying another item:
@@ -743,7 +743,7 @@ pm notes <id> --add "Keep renderer changes isolated to TOON output."
 pm learnings <id> --add "Use runtime contracts instead of duplicating flag lists."
 ```
 
-Use comments for progress and evidence, notes for implementation context, and learnings for durable future guidance. `--body` is a hidden compatibility alias for comments `--add`; choose exactly one input source (`[text]`, `--add`/`--body`, `--stdin`, or `--file`) per invocation. To clean up obsolete orchestration notes, `--edit <index>` rewrites the comment at a 1-based index and `--delete <index>` removes it; both record history and honor ownership rules.
+Use comments for progress and evidence, notes for implementation context, and learnings for durable future guidance. All three accept `--text` as a hidden compatibility alias for canonical `--add`; comments also retain `--body`/`--comment`, and notes retain `--note`. Choose exactly one input source (`[text]`, an add alias, `--stdin`, or `--file`) per invocation. Conflicting alias values fail before mutation. To clean up obsolete orchestration notes, `--edit <index>` rewrites the comment at a 1-based index and `--delete <index>` removes it; both record history and honor ownership rules.
 
 ## Linked Artifacts
 

package/docs/DIAGNOSTIC_OUTPUT_CONTRACTS.md

@@ -103,6 +103,14 @@ refusal; schema, items, history, settings, and package state must not change.
 Ephemeral runtime lock/cache directories are excluded from that semantic
 snapshot.
 
+The complete error-code census currently retains executable evidence for 18
+catalog rows across 17 canonical groups. Two of those rows are author-manifest
+schema findings reached through a real `pm health --full --strict-exit --json`
+process: an unknown top-level key and omitted canonical pm version bounds. The
+remaining rows stay explicit `uncovered` obligations in
+[the generated census](generated/REFUSAL_CLOSURE_CENSUS.md); the ratchet does not
+turn partial catalog closure into an approval claim.
+
 Run the focused proof with:
 
 ```bash

package/docs/EXTENSIONS.md

@@ -1,48 +1,48 @@
 # Packages and Extensions
 
-Extension flags declared with `list: true` accumulate repeated long/short alias occurrences and comma-separated values into one array. Dynamic commands preserve flag-like variadic content after `--`, and package handlers can use the public `suppressHostOutput()` protocol when they already emitted streaming, binary, or pre-rendered output. Declarative blueprints are also checked for reserved item-field collisions during SDK lint/preflight and harness activation, so a package cannot pass author-time validation and then fail only when users create or update items. Local archive installation, command ownership, and MCP custom-field diagnostics are tracked by [pm-lw6acw](../.agents/pm/issues/pm-lw6acw.toon), [pm-6z0wzf](../.agents/pm/issues/pm-6z0wzf.toon), and [pm-yfdav2](../.agents/pm/issues/pm-yfdav2.toon). Transactional mutation guards, host-bound command test SDKs, and installed custom-type lifecycle parity are tracked by [pm-hx23u5](../.agents/pm/issues/pm-hx23u5.toon), [pm-wx2lr5](../.agents/pm/issues/pm-wx2lr5.toon), and [pm-scga6k](../.agents/pm/issues/pm-scga6k.toon). Durable migration application, explicit source resolution, and composable preflight ownership are covered in [Extension Lifecycle Contracts](EXTENSION_LIFECYCLE.md).
+Extension flags declared with `list: true` accumulate repeated long/short alias occurrences and comma-separated values into one array. Dynamic commands preserve flag-like variadic content after `--`, and package handlers can use the public `suppressHostOutput()` protocol when they already emitted streaming, binary, or pre-rendered output. Declarative blueprints are also checked for reserved item-field collisions during SDK lint/preflight and harness activation, so a package cannot pass author-time validation and then fail only when users create or update items. Local archive installation, command ownership, MCP custom-field diagnostics, and author-manifest schema diagnostics are tracked by [pm-lw6acw](../.agents/pm/issues/pm-lw6acw.toon), [pm-6z0wzf](../.agents/pm/issues/pm-6z0wzf.toon), [pm-yfdav2](../.agents/pm/issues/pm-yfdav2.toon), and [pm-gh1091](../.agents/pm/issues/pm-gh1091.toon). Transactional mutation guards, host-bound command test SDKs, and installed custom-type lifecycle parity are tracked by [pm-hx23u5](../.agents/pm/issues/pm-hx23u5.toon), [pm-wx2lr5](../.agents/pm/issues/pm-wx2lr5.toon), and [pm-scga6k](../.agents/pm/issues/pm-scga6k.toon). Durable migration application, explicit source resolution, and composable preflight ownership are covered in [Extension Lifecycle Contracts](EXTENSION_LIFECYCLE.md).
 
 Packages add optional `pm` workflows without changing the core CLI. A package can ship one or more runtime extensions plus metadata such as docs and examples. Prefer the package-first commands in new docs and automation:
 
 ```bash
 pm package init ./my-package
 pm package init ./my-hook-package --capability hooks
-pm install ./my-package --project
+pm package install ./my-package --project
 pm package doctor --project --detail summary
 pm package reload --project
-pm upgrade --dry-run
+pm package upgrade --dry-run
 ```
 
-`pm extension ...` remains supported for compatibility and low-level runtime debugging. Related docs: [SDK](SDK.md), [Configuration](CONFIGURATION.md), [Testing](TESTING.md), [Command Reference](COMMANDS.md), [Extension Author Contracts](EXTENSION_AUTHOR_CONTRACTS.md).
+Hidden `pm extension ...`, `pm install ...`, and `pm upgrade ...` aliases remain supported for compatibility. They execute the canonical package handlers, keep stdout machine-compatible, and emit one migration hint on stderr unless the public config key `ux_deprecation_hints` (stored at `ux.deprecation_hints`) is disabled. Related docs: [SDK](SDK.md), [Configuration](CONFIGURATION.md), [Testing](TESTING.md), [Command Reference](COMMANDS.md), [Extension Author Contracts](EXTENSION_AUTHOR_CONTRACTS.md).
 
 ## Package Sources
 
-`pm install` accepts local, registry, and GitHub sources:
+`pm package install` accepts local, registry, and GitHub sources:
 
 ```bash
-pm install ./local-package --project
-pm install /absolute/path/to/package --project
-pm install ./my-package-1.2.3.tgz --project
-pm install npm:./my-package-1.2.3.tar.gz --project
-pm install npm:@scope/package --project
-pm install npm:package@1.2.3 --project
-pm install https://github.com/org/repo --project
-pm install --github org/repo/path --ref main --project
+pm package install ./local-package --project
+pm package install /absolute/path/to/package --project
+pm package install ./my-package-1.2.3.tgz --project
+pm package install npm:./my-package-1.2.3.tar.gz --project
+pm package install npm:@scope/package --project
+pm package install npm:package@1.2.3 --project
+pm package install https://github.com/org/repo --project
+pm package install --github org/repo/path --ref main --project
 ```
 
 Bundled first-party packages live under `packages/pm-*`:
 
 ```bash
 pm package catalog --project
-pm install all --project
-pm install calendar --project
-pm install search-advanced --project
-pm install kanban --project
+pm package install all --project
+pm package install calendar --project
+pm package install search-advanced --project
+pm package install kanban --project
 ```
 
-`pm install '*'`, `pm install all`, and shell-expanded `pm install *` are normalized to the same bundled install-all request. First-party package aliases come from each package manifest, with a fallback derived from the `packages/pm-*` directory name. A bare bundled alias that also names an installed npm package reports both explicit choices in `source_resolution`; see [Extension Lifecycle Contracts](EXTENSION_LIFECYCLE.md).
+`pm package install '*'` and `pm package install all` are normalized to the same bundled install-all request. First-party package aliases come from each package manifest, with a fallback derived from the `packages/pm-*` directory name. A bare bundled alias that also names an installed npm package reports both explicit choices in `source_resolution`; see [Extension Lifecycle Contracts](EXTENSION_LIFECYCLE.md).
 
-External registry packages are installed by exact package name. If `npm:<name>` returns a registry 404, JSON error output includes `fallback_candidates` and `next_best_command`; unpublished first-party packages fall back to `pm install --project github.com/unbraind/<name>`. Install results include package-owned `command_paths`, `action_paths`, `contributions`, `command_discovery`, and a light `verification` block covering the target tracker, activation status, registered commands/actions/item types, and health verdict. Agents should consume those fields instead of guessing from the package name or immediately spending another invocation on doctor. A successful activation persists the versioned contribution inventory in `.managed-extensions.json`; subsequent discovery can enumerate command handlers, hooks, parser/renderer targets, schema names, and the other registered surfaces without importing the package module. A failed runtime activation returns `ok: false`, `activated: false`, a non-zero CLI exit, and actionable diagnostics; missing SDK resolution adds an explicit dependency recovery step. Local installs are containment-safe when the extension destination is nested inside the source checkout: pm stages the package outside the source and prunes the destination, `.agents`, `node_modules`, and install-backup directories before copying, so reinstalling cannot recursively copy tracker history, host dependencies, or prior backups.
+External registry packages are installed by exact package name. If `npm:<name>` returns a registry 404, JSON error output includes `fallback_candidates` and `next_best_command`; unpublished first-party packages fall back to `pm package install --project github.com/unbraind/<name>`. Install results include package-owned `command_paths`, `action_paths`, `contributions`, `command_discovery`, and a light `verification` block covering the target tracker, activation status, registered commands/actions/item types, and health verdict. Agents should consume those fields instead of guessing from the package name or immediately spending another invocation on doctor. A successful activation persists the versioned contribution inventory in `.managed-extensions.json`; subsequent discovery can enumerate command handlers, hooks, parser/renderer targets, schema names, and the other registered surfaces without importing the package module. A failed runtime activation returns `ok: false`, `activated: false`, a non-zero CLI exit, and actionable diagnostics; missing SDK resolution adds an explicit dependency recovery step. Local installs are containment-safe when the extension destination is nested inside the source checkout: pm stages the package outside the source and prunes the destination, `.agents`, `node_modules`, and install-backup directories before copying, so reinstalling cannot recursively copy tracker history, host dependencies, or prior backups.
 Local `.tgz` and `.tar.gz` npm archives are inspected and extracted in an isolated temporary directory without invoking a shell. Archives must contain one `package/package.json` root, regular files/directories only, and bounded entry and expanded-byte totals. Absolute paths, traversal, alternate roots, links, device entries, oversized entries, and decompression-ratio abuse fail before installation. The managed source remains the original archive path, so reload and upgrade provenance do not point at a temporary extraction directory.
 Registry dependency names and versions are parsed as npm package specs before the install subprocess starts. Leading-option names and shell control syntax are rejected. npm reads those validated dependencies from an isolated runtime-only manifest; no caller-controlled spec is forwarded through the Windows command shell, and the fixed invocation still ends option parsing with `--`. Runtime verification then activates a temporary snapshot of the complete installed extension directory, so an upgrade cannot silently reuse stale transitive ESM dependencies from the current process. Successful install details expose `module_graph_verification: "fresh_snapshot"` for this check.
 pm-owned npm subprocesses clear any inherited, case-insensitive `npm_config_allow_scripts` value while retaining registry, auth, proxy, and executable-path environment; `--ignore-scripts` remains authoritative. Tracked by [pm-gh1072](../.agents/pm/issues/pm-gh1072.toon).
@@ -50,8 +50,8 @@ An explicit `--pm-path` scopes project installs to that tracker root, including
 
 ```bash
 npm search "pm-cli pm-package"
-pm install npm:pm-changelog --project
-pm install npm:pm-github --project
+pm package install npm:pm-changelog --project
+pm package install npm:pm-github --project
 pm package doctor --project --detail deep --trace
 pm github validate --repo owner/repo
 ```
@@ -91,7 +91,7 @@ Package roots declare resources in `package.json` under `pm`:
 ```
 
 Installation activates `pm.extensions`. `pm.docs`, `pm.examples`, `pm.assets`, and `pm.prompts` are catalog metadata (metadata-only — they are discovered and surfaced in the catalog but not executed). Declare agent-facing prompt/slash-command markdown under `pm.prompts` and non-code assets (images, skills, fixtures) under `pm.assets`; their conventional roots are `prompts/` (also `.agents/pm/prompts/`) and `assets/` (also `.agents/pm/assets/`).
-`pm package init` and its compatibility spelling `pm extension init` emit the same publishable root-extension artifact (`"extensions": ["."]`): package metadata, a typed `index.ts`, a colocated `node:test` suite, a strict type-check-only `tsconfig.json`, and `typecheck`/`test` scripts. Both results report the canonical `package_name` and exact `invocation_command`; an already prefixed target such as `pm-my-workflow` stays `pm-my-workflow` instead of becoming `pm-pm-my-workflow`. The manifest `entry` points at `./index.ts` itself (ADR [pm-2c28](../.agents/pm/decisions/pm-2c28.toon) / [pm-m1uz](../.agents/pm/decisions/pm-m1uz.toon)). pm loads that `.ts` entry directly via Node's native type stripping (Node >=22.18), so there is no build step — run `npm install` (for the peer SDK and type-checking) before `pm install`. The generated README shows how to author exported command/hook definitions with the SDK [define\* builders](../.agents/pm/decisions/pm-3mph.toon). `--capability` selects one of ten starters — one per SDK registration surface (`commands`, `hooks`, `search`, `importers`, `schema`, `profile`, `renderers`, `parser`, `preflight`, `services`) — each keeping a runnable starter command and adding the surface's registration plus a colocated `node:test` suite built on the matching SDK `assertRegistered*`/`runRegistered*ForTest` helpers. The option is repeatable for shell and config composition: repeating the same capability is idempotent, while combining distinct starter shapes fails with a usage error that asks the author to select one explicit scaffold capability. The full per-capability matrix (what each starter registers, which starters also declare `schema` because flag metadata is schema-governed, and why `schema`/`profile` omit `activation.commands` so their global contributions activate conservatively for every command) lives in [SDK.md — Minimal Command Extension](./SDK.md#minimal-command-extension). Starter manifests use the same least-privilege policy metadata as pure first-party command packages: `trusted: true`, `sandbox_profile: "strict"`, and explicit `false` permissions for `fs_read`, `fs_write`, `network`, `env_read`, `env_write`, and `process_spawn`. Declarative starters import `manifest.json` in their generated test and call `assertExtensionManifestMatchesBlueprint`, so capability drift fails locally before publication. Larger packages may point at nested extension directories after declaring runtime dependencies, relaxing only the permissions they actually need, and validating with `pm package doctor`, which additionally emits the advisory `extension_schema_narrow_activation` warning when a package registers custom item types/fields yet declares narrow `activation.commands` (the schema footgun above), recommending the field be dropped so the type stays globally available.
+`pm package init` and its compatibility spelling `pm extension init` emit the same publishable root-extension artifact (`"extensions": ["."]`): package metadata, a typed `index.ts`, a colocated `node:test` suite, a strict type-check-only `tsconfig.json`, and `typecheck`/`test` scripts. Both results report the canonical `package_name` and exact `invocation_command`; an already prefixed target such as `pm-my-workflow` stays `pm-my-workflow` instead of becoming `pm-pm-my-workflow`. The manifest `entry` points at `./index.ts` itself (ADR [pm-2c28](../.agents/pm/decisions/pm-2c28.toon) / [pm-m1uz](../.agents/pm/decisions/pm-m1uz.toon)). pm loads that `.ts` entry directly via Node's native type stripping (Node >=22.18), so there is no build step — run `npm install` (for the peer SDK and type-checking) before `pm package install`. The generated README shows how to author exported command/hook definitions with the SDK [define\* builders](../.agents/pm/decisions/pm-3mph.toon). `--capability` selects one of ten scaffold starters (`commands`, `hooks`, `search`, `importers`, `schema`, `profile`, `renderers`, `parser`, `preflight`, `services`), each keeping a runnable starter command and adding the selected registration pattern plus a colocated `node:test` suite built on the matching SDK `assertRegistered*`/`runRegistered*ForTest` helpers. These are authoring selectors, not a one-to-one manifest-capability vocabulary: the `profile` starter registers a profile but declares the supported `schema` manifest capability because `api.registerProfile` is schema-governed. The option is repeatable for shell and config composition: repeating the same capability is idempotent, while combining distinct starter shapes fails with a usage error that asks the author to select one explicit scaffold capability. The full per-capability matrix (what each starter registers, which starters also declare `schema` because flag metadata is schema-governed, and why `schema`/`profile` omit `activation.commands` so their global contributions activate conservatively for every command) lives in [SDK.md — Minimal Command Extension](./SDK.md#minimal-command-extension). Starter manifests use the same least-privilege policy metadata as pure first-party command packages: `trusted: true`, `sandbox_profile: "strict"`, and explicit `false` permissions for `fs_read`, `fs_write`, `network`, `env_read`, `env_write`, and `process_spawn`. Declarative starters import `manifest.json` in their generated test and call `assertExtensionManifestMatchesBlueprint`, so capability drift fails locally before publication. Larger packages may point at nested extension directories after declaring runtime dependencies, relaxing only the permissions they actually need, and validating with `pm package doctor`, which additionally emits the advisory `extension_schema_narrow_activation` warning when a package registers custom item types/fields yet declares narrow `activation.commands` (the schema footgun above), recommending the field be dropped so the type stays globally available.
 Package tests can pair `readPmPackageManifest(packageRoot)` with
 `assertPackageManifest(manifest, { resources: ... })` from
 `@unbrained/pm-cli/sdk` to prove aliases and resource paths without duplicating
@@ -191,10 +191,9 @@ useful for agents without inflating context or leaking private item content.
 
 Runnable manifest examples are the source of truth: [starter extension manifest](examples/starter-extension/manifest.json) and [policy-restricted manifest](examples/policy-restricted-extension/manifest.json).
 
-Use [extension-manifest.schema.json](schemas/extension-manifest.schema.json) as the `$schema` value for inline editor validation. The loader ignores `$schema` and tolerates future manifest fields, but the schema documents the fields pm reads.
-
-Rules:
+Use [extension-manifest.schema.json](schemas/extension-manifest.schema.json) as the `$schema` value for inline editor validation. The loader ignores `$schema` and tolerates future manifest fields, but the schema documents the fields pm reads. Rules:
 
+- `manifest.json` is the runtime declaration; package catalog metadata belongs in `package.json#pm`, and a top-level `compatibility` object is ignored. Use the public `inspectExtensionManifestSchema` / `lintExtensionManifestSchema` helpers for schema-only checks. In author workspaces, `pm health --full`, `pm package doctor`, and `pm extension --doctor` expose the same read-only `author_manifest` findings without activating the extension.
 - `entry` must resolve inside the extension directory.
 - `manifest_version` is an optional integer identifying the manifest schema generation. Runtime contracts currently support manifest versions `1` and `2`, and first-party runnable examples use `2`. First-party packages declare it; the manifest governance test requires it on every first-party package.
 - `pm_min_version` is an inclusive minimum pm CLI version. If the running CLI is older, discovery emits `extension_pm_min_version_unmet:<layer>:<name>:required=<version>:current=<version>` and skips the extension before import.
@@ -203,11 +202,11 @@ Rules:
 - An empty-string or non-string `pm_min_version`/`pm_max_version` makes the whole manifest malformed (`extension_manifest_invalid:<layer>:<name>`). Omit the field instead of leaving it blank.
 - Optional `engines.pm` and `engines.node` metadata is accepted for tooling, but `pm_min_version`/`pm_max_version` are the loader-enforced compatibility fields.
 - Declare only capabilities the extension actually uses. Declaring a capability it never registers against is over-broad: `pm package doctor` emits an advisory `extension_capability_unused:<layer>:<name>:<capability>` warning (never blocking) so you can trim the manifest, while the inverse — registering a surface whose capability is undeclared — is the blocking `extension_capability_missing` activation failure. Catch over-declaration earlier with the `assertExtensionCapabilityUsage` SDK testing helper.
-- `contributions` is the versioned, serializable surface inventory. `schema_version: 1` supports command definitions/handlers/overrides, hook phases, flag/parser targets, item types and fields, relationship kinds, migrations, profiles, importers/exporters, search/vector providers, service/renderer targets, renderer command ownership, and the preflight count. `pm install` derives and persists this block mechanically from the real activation result; authors may also declare it in `manifest.json` for build-time/static discovery.
+- `contributions` is the versioned, serializable surface inventory. `schema_version: 1` supports command definitions/handlers/overrides, hook phases, flag/parser targets, item types and fields, relationship kinds, migrations, profiles, importers/exporters, search/vector providers, service/renderer targets, renderer command ownership, and the preflight count. `pm package install` derives and persists this block mechanically from the real activation result; authors may also declare it in `manifest.json` for build-time/static discovery.
 - `activation.commands` is an optional array of the command paths on which the extension may activate (e.g. `["hello", "tickets import"]`). An explicit list is authoritative for every capability, including hooks and parser/preflight/renderer packages: when no declared path matches, pm does not import the module. Omit it and pm first uses the static contribution inventory, then falls back to conservative capability heuristics for legacy packages whose contributions are unknown.
 - Unknown capabilities emit deterministic warnings; legacy aliases such as `migration` and `validation` are normalized to `schema` with warnings.
 
-Supported capabilities:
+Supported manifest capabilities (the `profile` scaffold selector emits a profile registration under `schema`; it is not a manifest capability):
 
 - `commands`
 - `parser`
@@ -294,9 +293,11 @@ Doctor JSON also includes `triage.collision_plan` with grouped surfaces, ranked
 ## Runtime APIs
 
 Use the public SDK barrel. Do not deep-import from `src/core` or `dist/core`.
+
 ```ts
 import { defineExtension } from "@unbrained/pm-cli/sdk";
 ```
+
 Common APIs:
 
 - `api.extension` is a read-only identity (`name`, `layer`, `version`, `capabilities`, `pm_min_version?`, `pm_max_version?`, `source_package?`) for self-identifying logs and version gating without re-reading the manifest.
@@ -384,14 +385,14 @@ Compatibility equivalents remain available through `pm extension ...` for existi
 
 ## Upgrade Workflow
 
-`pm upgrade` is the package-first update entrypoint:
+`pm package upgrade` is the package-first update entrypoint:
 
 ```bash
-pm upgrade --dry-run
-pm upgrade
-pm upgrade --packages-only
-pm upgrade todos --dry-run
-pm upgrade --cli-only --repair
+pm package upgrade --dry-run
+pm package upgrade
+pm package upgrade --packages-only
+pm package upgrade todos --dry-run
+pm package upgrade --cli-only --repair
 ```
 
 CLI/SDK upgrades use `npm install -g @unbrained/pm-cli@<tag>`. Managed package upgrades reuse the source recorded at install time, including registry, GitHub, local, and first-party package sources.
@@ -402,7 +403,7 @@ Use non-interactive commands with explicit project scope:
 
 ```bash
 pm init --defaults --author codex-agent
-pm install '*' --project
+pm package install '*' --project
 pm package doctor --project --detail summary --json
 pm contracts --flags-only --json
 pm health --check-only --json
@@ -422,8 +423,7 @@ import { createExtensionTestHarness } from "@unbrained/pm-cli/sdk/testing";
 import { activateExtensionForTest } from "@unbrained/pm-cli/sdk/testing";
 ```
 
-Runtime modules use static SDK imports; installed copies receive a host SDK link. Use `createPmCliExpectedError(message, { exitCode, context })` for expected user/action failures from package commands. It creates an `Error` named `PmCliError` with a structural `exitCode`, so separately installed package code still gets expected-error handling and Sentry filtering.
-Commands that need to render a structured gate report and still fail CI may instead return an object with `exit_code` from `1` through `255`; optional string `code` and `remediation` fields are preserved by the host. The result is rendered normally, and the CLI exits with the declared status. Thrown plain objects also preserve bounded `code` and `remediation` fields in the host error contract.
+Runtime modules use static SDK imports; installed copies receive a host SDK link. Use `createPmCliExpectedError(message, { exitCode, context })` for expected user/action failures from package commands. It creates an `Error` named `PmCliError` with a structural `exitCode`, so separately installed package code still gets expected-error handling and Sentry filtering. Commands that need to render a structured gate report and still fail CI may instead return an object with `exit_code` from `1` through `255`; optional string `code` and `remediation` fields are preserved by the host. The result is rendered normally, and the CLI exits with the declared status. Thrown plain objects also preserve bounded `code` and `remediation` fields in the host error contract.
 Prefer the `define*` builders for exported registration definitions (`defineCommand`, `defineFlag`, `defineSearchProvider`, `defineAfterCommandHook`, and the matching override/import/export/hook helpers; see ADR [pm-3mph](../.agents/pm/decisions/pm-3mph.toon)). They are zero-cost identity functions that preserve object literal types and contextually type function parameters before the definitions reach `api.register*`; runtime validation remains in the loader, and behavior validation remains in `sdk/testing`.
 Packages that extend core list or search behavior should import `LIST_FILTER_EXTENSION_FLAG_DEFINITIONS`, `SEARCH_EXTENSION_FLAG_DEFINITIONS`, or `toExtensionFlagDefinitions` from `@unbrained/pm-cli/sdk/authoring` instead of copying CLI option tables. For example: `api.registerFlags("my search", SEARCH_EXTENSION_FLAG_DEFINITIONS)`.
 The adapter expands aliases into registration-ready definitions and preserves string/boolean behavior, list accumulation, repeatability, requiredness, descriptions, and value names from the canonical CLI contracts. Use `toExtensionFlagDefinitions` with another exported CLI flag contract for a narrower baseline.

package/docs/MCP_2026_07_28.md

@@ -0,0 +1,160 @@
+# MCP 2026-07-28 Protocol and Compatibility Decision
+
+Tracker references: [pm-sqvshj](../.agents/pm/decisions/pm-sqvshj.toon),
+[pm-vae5ec](../.agents/pm/features/pm-vae5ec.toon), and
+[pm-55yf1t](../.agents/pm/tasks/pm-55yf1t.toon). MRTR, durable tasks,
+and the cache/schema surface are tracked by
+[pm-rz9gep](../.agents/pm/features/pm-rz9gep.toon),
+[pm-rzs24j](../.agents/pm/features/pm-rzs24j.toon), and
+[pm-hv1x1x](../.agents/pm/features/pm-hv1x1x.toon). Subscriptions,
+Streamable HTTP, remote authorization, and the deprecation ratchet are tracked
+by [pm-v7e337](../.agents/pm/features/pm-v7e337.toon),
+[pm-3zh9s4](../.agents/pm/features/pm-3zh9s4.toon), and
+[pm-vzcisw](../.agents/pm/chores/pm-vzcisw.toon). Skills and Apps are tracked
+by [pm-8nzivt](../.agents/pm/features/pm-8nzivt.toon) and
+[pm-pznhee](../.agents/pm/features/pm-pznhee.toon).
+
+Status: accepted. MCP `2026-07-28` is pm's canonical protocol revision.
+
+## Decision
+
+The public pm SDK owns protocol versions, request metadata validation,
+capability checks, discovery, result envelopes, error codes, HTTP header
+parity, subscriptions, authorization boundaries, trace isolation, and legacy
+result interpretation. `pm-mcp` is a JSON-RPC/stdio adapter over those
+contracts; `pm-mcp-http` binds the same dispatcher to sessionless Streamable
+HTTP POST.
+
+Modern requests are stateless. Every request carries:
+
+- `io.modelcontextprotocol/protocolVersion` = `2026-07-28`;
+- `io.modelcontextprotocol/clientCapabilities` as an object, including `{}`;
+- optional `io.modelcontextprotocol/clientInfo` with `name` and `version`.
+
+Every modern result carries an explicit `resultType` (`complete`,
+`input_required`, or `task`) and `io.modelcontextprotocol/serverInfo` in
+result `_meta`. The mandatory
+`server/discover` method returns the supported modern revisions, deterministic
+capabilities, public cache policy, server identity, and bounded instructions.
+No modern request reads identity, capabilities, or version from a previous
+request.
+
+## Legacy boundary
+
+The sole supported legacy revision is `2025-06-18`, accepted through the
+existing stdio adapter. Unversioned requests stay on this legacy path because
+they cannot claim the current revision; `initialize` enriches their client
+identity but is not required for compatibility with older pm hosts. The
+adapter has no session id, does not affect modern requests, and is excluded
+from `server/discover`'s `supportedVersions` because it cannot be selected
+through modern per-request metadata.
+
+The adapter is scheduled for removal only after published-client telemetry and
+release probes show no required legacy consumers for two consecutive release
+windows. Removal is a reviewed compatibility change, never a history rewrite.
+
+## Transport behavior
+
+- Stdio modern clients call `server/discover` with current request metadata,
+  then send the same version and capability keys on every request.
+- Stdio legacy clients retain their existing response shapes and may use
+  `initialize` with `2025-06-18` to supply client identity.
+- Streamable HTTP requires `MCP-Protocol-Version` and `Mcp-Method` on every
+  request. `Mcp-Name` is required only for `prompts/get`, `resources/read`, and
+  `tools/call`; other methods omit it. Schema-declared `x-mcp-header` values are
+  encoded, decoded, and compared with tool arguments before dispatch.
+  Header/version mismatch uses code `-32020` and HTTP 400.
+- `subscriptions/listen` is a request-scoped stdio or SSE stream. The first
+  message acknowledges the supported filter; later messages carry its request
+  id as `io.modelcontextprotocol/subscriptionId`. Disconnect deletes the
+  subscription and a caller retries lost work with a new request id.
+- The remote adapter defaults to loopback, enforces exact browser origins,
+  bounds bodies, maps parse/invalid requests to HTTP 400, and can require an
+  issuer-, audience-, and scope-bound bearer token.
+- Unsupported modern versions return `-32022` plus the exact supported modern
+  list. Missing required capabilities return `-32021` with a structured
+  capability map. Malformed metadata uses JSON-RPC Invalid Params `-32602`.
+
+## Removed, migrated, and deprecated behavior
+
+| Prior behavior                                                    | Disposition                                                                                                 |
+| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `initialize` and `notifications/initialized`                      | Legacy stdio adapter only; absent from modern behavior.                                                     |
+| `Mcp-Session-Id` and protocol sessions                            | Removed; explicit application handles are ordinary arguments.                                               |
+| `ping`                                                            | Legacy adapter only; modern calls return Method Not Found.                                                  |
+| `resources/subscribe` and `resources/unsubscribe`                 | Replaced by the implemented `subscriptions/listen` filter.                                                  |
+| SSE event ids and `Last-Event-ID` replay                          | Removed; callers retry with a new request id.                                                               |
+| Reverse `roots/list`, sampling, and elicitation requests          | Migrate to MRTR `input_required` under `pm-rz9gep`.                                                         |
+| Core tasks                                                        | Migrate to `io.modelcontextprotocol/tasks` under `pm-rzs24j`.                                               |
+| `logging/setLevel`                                                | Removed; optional request-local log metadata is never shared, and remote operations use host OpenTelemetry. |
+| Roots, Sampling, Logging, HTTP+SSE, and non-none `includeContext` | Retain only in bounded legacy compatibility while `pm-vzcisw` drives deprecation removal.                   |
+| Dynamic Client Registration                                       | Legacy authorization fallback; Client ID Metadata Documents are canonical under `pm-3zh9s4`.                |
+
+## Rollout, rollback, and proof
+
+Local and hosted gates must prove SDK primitives, direct server calls, real
+stdio, packed artifacts, npx, bunx, and published artifacts agree on discovery
+and the canonical revision. Negative controls cover unsupported versions,
+missing/malformed metadata, missing capabilities, header mismatch, removed
+methods, and omitted modern `resultType`.
+
+Rollback preserves the SDK contract and re-enables only the reviewed legacy
+adapter. It must never reintroduce session ids or make modern behavior depend
+on initialization. Release evidence records exact source, package, tag, and
+consumer revisions separately.
+
+## MRTR, tasks, and cache behavior
+
+An SDK handler that cannot finish without host input throws
+`PmMcpInputRequiredError`. The modern adapter validates the requested
+`elicitation/create`, `roots/list`, or `sampling/createMessage` capability and
+returns `resultType: "input_required"`. Continuation state can be bounded,
+HMAC-sealed, expiry-bound, method-bound, parameter-bound, principal-bound, and
+protected from in-process replay with the public interaction helpers. Retry
+payloads arrive as request-local `inputResponses`; they never depend on a
+protocol session.
+
+Clients negotiate `io.modelcontextprotocol/tasks` in request capabilities.
+Eligible long-running `tools/call` operations can then return a durable task
+handle. `tasks/get`, `tasks/update`, and `tasks/cancel` are principal-scoped,
+persist records atomically under the ignored tracker runtime area, enforce
+immutable terminal states, expire abandoned work deterministically, and turn
+a disappeared worker into an actionable terminal failure. Task state remains
+retrieved through the task methods. Change subscriptions do not become
+task-progress channels, and pm's current handlers do not emit request progress
+or deprecated log-message notifications.
+
+Modern tool, resource, resource-template, and prompt list/read results carry
+explicit `ttlMs` and `cacheScope`. Tool schemas are validated as bounded JSON
+Schema 2020-12 documents before advertisement. Tool and resource data stay
+private; public metadata lists may be cached for their advertised lifetime.
+
+## Skills and Apps extensions
+
+Discovery advertises the stable `io.modelcontextprotocol/ui` MCP Apps
+extension and the revision-pinned draft `io.modelcontextprotocol/skills`
+extension. They remain optional and request-local. Apps require the stable
+`2026-01-26` MIME capability; Skills require the exact SEP-2640 commit and
+explicit directory-read support for bulk reads. An incompatible Apps
+declaration is treated as absent by `tools/list` and `resources/list`, so those
+discovery methods degrade to the non-UI surface; direct `ui://` reads remain
+strict and return the allocated missing-capability error. Skills methods fail
+closed on an incompatible draft declaration because their entire method family
+depends on that exact negotiated revision.
+
+The public SDK owns skill parsing, digesting, pagination, origin provenance,
+resource bounds, App contracts, tool metadata, sandbox policy, and accessible
+self-contained HTML. The server only applies negotiation and dispatch. See
+[MCP Skills and Apps](MCP_SKILLS_AND_APPS.md) for the wire examples and trust
+model.
+
+## Public SDK
+
+Use `PM_MCP_PROTOCOL_VERSION`, `resolveMcpRequestContext()`,
+`buildMcpDiscoverResult()`, `buildMcpCompleteResult()`,
+`PmMcpSubscriptionRegistry`, `buildMcpHttpRequestHeaders()`,
+`validateMcpHttpRequestHeaders()`, `buildMcpProtectedResourceMetadata()`, and
+the issuer/trace authorization helpers from `@unbrained/pm-cli/sdk`. See
+[MCP interaction and task SDK](SDK_MCP_INTERACTIONS.md) and
+[remote transport, authorization, and migration](MCP_REMOTE_TRANSPORT_SECURITY.md),
+plus [MCP Skills and Apps](MCP_SKILLS_AND_APPS.md).

package/docs/MCP_2026_07_28_CONFORMANCE.md

@@ -0,0 +1,30 @@
+# MCP 2026-07-28 Conformance Matrix
+
+Tracker: [pm-55yf1t](../.agents/pm/tasks/pm-55yf1t.toon). The official
+2026-07-28 schema and key-changes document are normative; this matrix assigns
+every revision-level change to one canonical pm owner and records executable
+evidence or an explicit open obligation.
+
+| Requirement family                                                                                 | Canonical owner                                     | Current disposition                                                                                                      | Executable evidence                                                                       |
+| -------------------------------------------------------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
+| Stateless per-request version, client capabilities, and identity                                   | [pm-vae5ec](../.agents/pm/features/pm-vae5ec.toon)  | Implemented                                                                                                              | `tests/unit/sdk/mcp/protocol.spec.ts`, `tests/integration/mcp-stateless-protocol.spec.ts` |
+| Mandatory `server/discover`, deterministic capabilities and identity                               | [pm-vae5ec](../.agents/pm/features/pm-vae5ec.toon)  | Implemented                                                                                                              | direct SDK/server tests plus plugin and release real-process probes                       |
+| Unsupported version `-32022`                                                                       | [pm-vae5ec](../.agents/pm/features/pm-vae5ec.toon)  | Implemented                                                                                                              | SDK and server negative controls                                                          |
+| Header mismatch `-32020` and missing capability `-32021`                                           | [pm-vae5ec](../.agents/pm/features/pm-vae5ec.toon)  | Implemented in SDK, stdio, and Streamable HTTP                                                                            | SDK negative controls and `tests/integration/mcp-streamable-http.spec.ts`                 |
+| Required result `resultType`; legacy omission means complete only at compatibility boundary        | [pm-vae5ec](../.agents/pm/features/pm-vae5ec.toon)  | Implemented for modern pm results                                                                                        | SDK unit and modern direct-server tests                                                   |
+| No modern initialize, initialized notification, ping, or protocol session                          | [pm-sqvshj](../.agents/pm/decisions/pm-sqvshj.toon) | Implemented with bounded legacy stdio adapter                                                                            | modern removed-method and legacy handshake tests                                          |
+| MRTR `input_required`, retry state, and reverse-request removal                                    | [pm-rz9gep](../.agents/pm/features/pm-rz9gep.toon)  | Implemented for SDK and stateless stdio adapter                                                                          | `tests/unit/sdk/mcp/interactions.spec.ts`; direct server negative controls                |
+| `subscriptions/listen`, request-scoped streams, no SSE resumability                                | [pm-v7e337](../.agents/pm/features/pm-v7e337.toon)  | Implemented locally; packed and published proof follows merge                                                            | subscription SDK, stdio, HTTP, backpressure, disconnect, and retry tests                  |
+| Official `io.modelcontextprotocol/tasks` extension                                                 | [pm-rzs24j](../.agents/pm/features/pm-rzs24j.toon)  | Implemented for eligible tool calls, durable lifecycle, and stdio methods; notifications remain with subscriptions owner | `tests/unit/sdk/mcp/tasks.spec.ts`, `tests/integration/mcp-stateless-protocol.spec.ts`    |
+| Cacheable list/read results, deterministic tools, JSON Schema 2020-12, any JSON structured content | [pm-hv1x1x](../.agents/pm/features/pm-hv1x1x.toon)  | Implemented for current pm tool/resource/prompt surfaces                                                                 | SDK schema/cache tests and direct modern server surface suite                             |
+| Issuer-bound authorization, client metadata documents, consent, headers, OpenTelemetry             | [pm-3zh9s4](../.agents/pm/features/pm-3zh9s4.toon)  | Implemented locally; deployment verifier integration remains host-owned                                                   | authorization SDK adversarial tests, real HTTP bearer suite, and threat model             |
+| Stable MCP Apps negotiation, tool/resource metadata, fallback, sandboxing, and accessible views    | [pm-pznhee](../.agents/pm/features/pm-pznhee.toon)  | Implemented in the public SDK and stateless server; packed/published proof follows merge                                 | `tests/unit/sdk/mcp/apps.spec.ts`, `tests/integration/mcp-stateless-protocol.spec.ts`      |
+| Draft Skills over MCP list/get/read, compatibility, provenance, digests, bounds, and pagination    | [pm-8nzivt](../.agents/pm/features/pm-8nzivt.toon)  | Implemented against exact SEP-2640 draft revision; packed/published proof follows merge                                  | `tests/unit/sdk/mcp/skills.spec.ts`, `tests/integration/mcp-stateless-protocol.spec.ts`    |
+| Deprecated Roots, Sampling, Logging, HTTP+SSE, `includeContext`, dynamic registration              | [pm-vzcisw](../.agents/pm/chores/pm-vzcisw.toon)    | Canonical source ratcheted; bounded stdio adapter and dated migration policy remain                                      | generated inventory, negative controls, adapter tests, and migration guide                |
+| Official schema, real stdio/HTTP, packed/published, npx/bunx, negative controls                    | [pm-55yf1t](../.agents/pm/tasks/pm-55yf1t.toon)     | Foundation implemented; remains open until every owner above closes                                                      | SDK/server suites, plugin smokes, published-release verifier                              |
+
+The programme gate remains intentionally incomplete while local-only rows
+lack their packed and published evidence. Provider
+silence, a successful legacy initialize, or source-only unit coverage cannot
+promote such a row. Completion requires the owner's positive and negative
+tests plus exact packed and published consumer proof.