@unbrained/pm-cli 2026.8.26 → 2026.8.27

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/EXTENSIONS.md

@@ -7,42 +7,42 @@ Packages add optional `pm` workflows without changing the core CLI. A package ca
 ```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
@@ -202,11 +202,11 @@ Use [extension-manifest.schema.json](schemas/extension-manifest.schema.json) as
 - 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`
@@ -293,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.
@@ -383,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.
@@ -401,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
@@ -421,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

@@ -10,7 +10,9 @@ and the cache/schema surface are tracked by
 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).
+[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.
 
@@ -127,6 +129,25 @@ 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()`,
@@ -135,4 +156,5 @@ Use `PM_MCP_PROTOCOL_VERSION`, `resolveMcpRequestContext()`,
 `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).
+[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

@@ -18,13 +18,13 @@ evidence or an explicit open obligation.
 | 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             |
-| Core extension negotiation and official extension fallback                                         | [pm-pznhee](../.agents/pm/features/pm-pznhee.toon)  | Open                                                                                                                     | owner acceptance criteria and release matrix                                              |
-| Skills over MCP                                                                                    | [pm-8nzivt](../.agents/pm/features/pm-8nzivt.toon)  | Open                                                                                                                     | owner acceptance criteria define capability and token-budget proof                        |
+| 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 any row says `Open`
-or while local-only rows lack their packed and published evidence. Provider
+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.

package/docs/MCP_SKILLS_AND_APPS.md

@@ -0,0 +1,107 @@
+# MCP Skills and Apps
+
+Tracker references: [pm-8nzivt](../.agents/pm/features/pm-8nzivt.toon),
+[pm-pznhee](../.agents/pm/features/pm-pznhee.toon), and
+[pm-55yf1t](../.agents/pm/tasks/pm-55yf1t.toon).
+
+pm exposes optional workflow guidance and interactive context views without
+moving authority out of the public SDK or the tracker. Both extensions require
+explicit request-local negotiation. Clients that do not negotiate them retain
+the complete CLI, SDK, tool, prompt, and ordinary resource behavior.
+
+## Skills over MCP
+
+Skills support follows the current SEP-2640 draft at the exact revision
+`a3e147ca2710f68214247aecc729731ee1ae8d03`. Because the proposal is not a
+stable MCP extension, discovery advertises both `status: draft` and that exact
+revision. Every `skills/list`, `skills/get`, skill `resources/read`, and
+`resources/directory/read` request must independently declare:
+
+```json
+{
+  "extensions": {
+    "io.modelcontextprotocol/skills": {
+      "revision": "SEP-2640@a3e147ca2710f68214247aecc729731ee1ae8d03",
+      "directoryRead": true
+    }
+  }
+}
+```
+
+`skills/list` is lexically ordered and cursor-paginated. Descriptors contain
+the parsed SKILL.md frontmatter, every file URI, byte size, SHA-256 digest,
+estimated token cost, package/MCP compatibility, origin, and an explicit
+`untrusted` trust marker. `skills/get` returns one descriptor without loading
+file bodies. Digests use the draft's `sha256:<hex>` representation.
+`resources/read` fetches one digest-bound file; the optional, cursor-paginated
+directory read returns one directory's direct child resource metadata only.
+Clients read selected file bodies through ordinary `resources/read` calls.
+
+The published package carries the four canonical pm skills. A repository may
+override a package skill by placing the same validated name below
+`.agents/skills`, and the returned origin changes to `workspace`. Overrides do
+not inherit trust: skill text is guidance, never implicit permission to execute
+commands or mutate the tracker.
+
+Security limits reject symbolic links, malformed or aliased YAML, mismatched
+directory/frontmatter names, stale cursors, oversized files, excessive file
+counts, and aggregate skill bodies above the declared bound. In accordance with
+the draft, pm accepts at most 512 resources and 16 MiB of total content per
+skill; the same 16 MiB ceiling applies to an individual resource. An origin is
+limited to 100 candidate skill directories and 32 MiB across all retained
+bodies. File counts and both byte budgets are reserved from filesystem metadata
+before a body is read, so an untrusted workspace cannot exceed the declared
+memory envelope before rejection. Each read is resolved from the immutable
+in-memory registry used to compute its digest.
+
+## MCP Apps
+
+pm implements the stable MCP Apps `2026-01-26` extension through the official
+`@modelcontextprotocol/ext-apps` metadata contracts. A client opts in with:
+
+```json
+{
+  "extensions": {
+    "io.modelcontextprotocol/ui": {
+      "specVersion": "2026-01-26",
+      "mimeTypes": ["text/html;profile=mcp-app"]
+    }
+  }
+}
+```
+
+Negotiated `tools/list` attaches `_meta.ui.resourceUri` to five existing,
+SDK-backed tools. `resources/list` and `resources/read` expose the corresponding
+`ui://` documents:
+
+| View | Authoritative tool | Purpose |
+| --- | --- | --- |
+| Context explorer | `pm_context` | Context, provenance, omissions, and token cost |
+| Relationship graph | `pm_graph` | Typed edges, explaining paths, and governance |
+| Plan and milestone | `pm_plan` | Steps, dependencies, decisions, and validation |
+| Assurance dashboard | `pm_validate` | Verdicts, evidence, and recovery paths |
+| Long-operation view | `pm_test` | Durable test and operation results |
+
+Every view is self-contained and requests no network, storage, camera,
+microphone, or location permission. It performs the MCP Apps initialization
+handshake, listens for tool input/result/cancellation and host-context events,
+bounds large renderings with an explicit truncation message, and retains the
+tool result's text fallback. Layout is responsive, keyboard focus is visible,
+and reduced-motion preferences are honored.
+
+Apps keep no durable project state and expose no hidden mutation path. The
+tracker, task store, mutation guards, consent, idempotency, and immutable
+receipts remain owned by existing SDK-backed MCP tools. A host that cannot or
+does not render Apps still receives meaningful tool text and structured data.
+Missing or incompatible optional Apps declarations therefore leave core tool
+and resource discovery undecorated; an explicit read of a `ui://` resource
+continues to fail closed unless the stable capability was negotiated.
+
+## Public SDK
+
+Use `PmMcpSkillRegistry`, `assertPmMcpSkillsCapability()`,
+`PM_MCP_SKILLS_SERVER_CAPABILITY`, `PM_MCP_APP_CONTRACTS`,
+`hasPmMcpAppsCapability()`, `decoratePmMcpToolsWithApps()`, and
+`renderPmMcpAppHtml()` from `@unbrained/pm-cli/sdk`. The server is a thin
+adapter over these contracts; custom hosts can project the same resources and
+security policy without importing pm server internals.

package/docs/QUICKSTART.md

@@ -9,7 +9,7 @@ Use this page to get from a clean repository to a tracked, verified item.
 - Claim before implementation.
 - Link changed files, docs, and tests to the item.
 - Close only after evidence is recorded.
-- Use `pm install guide-shell --project` before `pm guide quickstart` or `pm guide workflows` when you need local docs routing.
+- Use `pm package install guide-shell --project` before `pm guide quickstart` or `pm guide workflows` when you need local docs routing.
 
 Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon).
 
@@ -23,10 +23,10 @@ pm --version
 For updates, use the registry package again:
 
 ```bash
-pm upgrade --cli-only
+pm package upgrade --cli-only
 ```
 
-`pm upgrade` uses `npm install -g @unbrained/pm-cli@latest` for the CLI/SDK and can also refresh installed pm packages. Do not use the GitHub git URL as the normal global update path. If a previous git-sourced install left a stale `pm` shim, run `pm upgrade --cli-only --repair`, run `bash scripts/install.sh --repair` from a checkout, or uninstall the package before reinstalling from npm.
+`pm package upgrade` uses `npm install -g @unbrained/pm-cli@latest` for the CLI/SDK and can also refresh installed pm packages. Do not use the GitHub git URL as the normal global update path. If a previous git-sourced install left a stale `pm` shim, run `pm package upgrade --cli-only --repair`, run `bash scripts/install.sh --repair` from a checkout, or uninstall the package before reinstalling from npm. The hidden `pm upgrade` alias remains compatible with existing automation and emits a migration hint on stderr.
 
 For one-off use:
 
@@ -39,8 +39,8 @@ Optional first-party packages are installable during init or on demand:
 ```bash
 pm init --defaults --with-packages
 pm package catalog --project
-pm install '*' --project
-pm install all --project
+pm package install '*' --project
+pm package install all --project
 pm package doctor --project --detail summary
 ```
 
@@ -78,16 +78,16 @@ pm create \
 
 Useful item types:
 
-| Type | Use |
-|------|-----|
-| `Epic` | broad outcome or initiative |
-| `Feature` | user-facing capability or major slice |
-| `Task` | implementation work |
-| `Chore` | maintenance, refactoring, or housekeeping work |
-| `Issue` | bug or defect |
-| `Decision` | recorded choice and rationale |
-| `Plan` | agent-optimized living plan with ordered steps and evidence |
-| `Event`, `Reminder`, `Milestone`, `Meeting` | calendar-aware planning |
+| Type                                        | Use                                                         |
+| ------------------------------------------- | ----------------------------------------------------------- |
+| `Epic`                                      | broad outcome or initiative                                 |
+| `Feature`                                   | user-facing capability or major slice                       |
+| `Task`                                      | implementation work                                         |
+| `Chore`                                     | maintenance, refactoring, or housekeeping work              |
+| `Issue`                                     | bug or defect                                               |
+| `Decision`                                  | recorded choice and rationale                               |
+| `Plan`                                      | agent-optimized living plan with ordered steps and evidence |
+| `Event`, `Reminder`, `Milestone`, `Meeting` | calendar-aware planning                                     |
 
 ## Find and Claim Work
 

package/docs/README.md

@@ -47,6 +47,7 @@ pm guide release --json
 - [MCP 2026-07-28 Protocol Decision](MCP_2026_07_28.md) - stateless request metadata, discovery, result envelopes, explicit legacy boundary, and migration policy.
 - [MCP 2026-07-28 Conformance Matrix](MCP_2026_07_28_CONFORMANCE.md) - official revision changes mapped to canonical owners and executable evidence.
 - [MCP Interaction and Task SDK](SDK_MCP_INTERACTIONS.md) - public MRTR continuation, cache/schema validation, and durable task-store contracts.
+- [MCP Skills and Apps](MCP_SKILLS_AND_APPS.md) - negotiated draft workflow discovery, stable interactive views, digests, provenance, accessibility, and trust boundaries.
 - [MCP Remote Transport, Authorization, and Migration](MCP_REMOTE_TRANSPORT_SECURITY.md) - Streamable HTTP operation, subscriptions, OAuth and trace boundaries, threat model, and deprecated-feature ratchet.
 - [SDK Artifact Output Contracts](SDK_ARTIFACT_OUTPUT.md) - clean stdout/file exporter channels, bounded receipts, binary-safe delivery, and shared NDJSON terminal framing.
 - [Context Relevance and Packing](CONTEXT_RELEVANCE.md) - shared CLI/SDK signals, derived-store provenance, ranking explanations, and token budgets.

package/docs/RELEASING.md

@@ -387,9 +387,17 @@ git push origin v<version>
   metadata cannot mask a public-registry outage. The verifier dispatches a real
   `pm contracts` command through both explicit-bin and package-default
   invocations, performs stateless JSON-RPC `server/discover` against the
-  symlink-resolved `pm-mcp` bin under both npx and bunx, requires canonical
-  `2026-07-28` metadata/result envelopes, derives bin coverage
-  from `package.json`, and proves missing-bin and missing-command controls fail.
+  symlink-resolved `pm-mcp` bin under both npx and bunx, and launches the exact
+  public `pm-mcp-http` bin under both executors on an isolated loopback port for
+  a real Streamable HTTP `server/discover` exchange. Both transports require
+  canonical `2026-07-28` metadata/result envelopes. HTTP startup is bounded to
+  two 20-second attempts per executor so the complete retry budget remains below
+  the hosted step timeout. Signal-aware process-group cleanup escalates from
+  `SIGTERM` to `SIGKILL` after a bounded grace period, including when the outer
+  evaluator times out or an intermediate executor exits before its server
+  descendant. Direct executor exit is not treated as process-group cleanup. The
+  verifier derives bin coverage from `package.json`, and proves missing-bin and
+  missing-command controls fail.
 - exact-package installed acceptance through
   `scripts/release/verify-installed-agent-session.mjs`. Separate npm and Bun
   install roots must contain the resolved executable, then each drives the

package/docs/SDK_CONTEXT_INTEGRITY.md

@@ -16,10 +16,16 @@ These contracts keep project management equal to context management: reads say w
 pm get pm-a1b2 --output-include id,title
 pm get pm-a1b2 --output-include item.id,item.title,linked
 pm get pm-a1b2 --output-include item,claim_state
+pm get pm-a1b2 --output-include comments,learnings,tests
 ```
 
 An unknown selector is a usage refusal that lists the valid vocabulary. Selecting the complete `item` object together with an item field is also refused because the two selectors express conflicting projection depths. Every successful projection carries an `omission_receipt` with the exact selectors needed to restore withheld item fields or sections.
 
+Collection selectors participate in the same pre-execution projection on CLI,
+SDK, and MCP transports. Requesting `comments`, `notes`, `learnings`, `files`,
+`tests`, `docs`, `reminders`, or `events` therefore loads only the named item
+collections before the universal output layer removes unrequested fields.
+
 Automatic receipts cover every heavy item collection (`comments`, `notes`,
 `learnings`, `files`, `tests`, `docs`, `reminders`, and `events`) plus `body`,
 `children`, `claim_state`, `linked`, and `schedule`. Empty included collections

package/docs/SDK_EVIDENCE_TRACEABILITY.md

@@ -1,6 +1,6 @@
 # SDK Evidence Traceability and Integrity
 
-Tracker references: [pm-f86lth](../.agents/pm/features/pm-f86lth.toon), [pm-cstuys](../.agents/pm/issues/pm-cstuys.toon), [pm-jb1ron](../.agents/pm/issues/pm-jb1ron.toon), [pm-2irc1p](../.agents/pm/issues/pm-2irc1p.toon), and [pm-u5c27w](../.agents/pm/issues/pm-u5c27w.toon).
+Tracker references: [pm-f86lth](../.agents/pm/features/pm-f86lth.toon), [pm-cstuys](../.agents/pm/issues/pm-cstuys.toon), [pm-jb1ron](../.agents/pm/issues/pm-jb1ron.toon), [pm-2irc1p](../.agents/pm/issues/pm-2irc1p.toon), [pm-u5c27w](../.agents/pm/issues/pm-u5c27w.toon), and [pm-blvfye](../.agents/pm/issues/pm-blvfye.toon).
 
 This contract turns linked evidence into a bidirectional context primitive. Items can continue to declare the files that explain their implementation, while agents and packages can resolve a source path back to its owning work without scanning tracker files at indexed scale.
 
@@ -127,3 +127,11 @@ such as `BD-30-A` and `BD-30-B` are distinct sibling work and receive only their
 ordinary title-token similarity; exact repetitions of the full code retain the
 strong `issue_code` signal. This keeps duplicate-close guidance from collapsing
 decomposed work that shares a numeric family prefix.
+
+Metadata validation applies a separate, evidence-backed title classifier.
+Upper-case prefixes remain conventional issue codes. Mixed-case prefixes must
+have a code delimiter, an explicit body marker/backtick reference, or match the
+configured item-id prefix. Natural-language compounds such as `Match-3`,
+`Covid-19`, and `Wi-Fi-6` therefore do not produce dishonest rename-or-merge
+warnings, while `GH-1118`, `Bug-12: ...`, and configured formats remain
+detectable without an ever-growing word dictionary.

package/docs/generated/AGENT_CAPABILITY_ROUTING.md

@@ -14,4 +14,4 @@ This file is generated from `PM_COMMAND_CAPABILITY_CONTRACTS`. Do not edit it ma
 | graph | `graph`, `deps`, `plan` |
 | quality | `test`, `test-all`, `validate`, `assurance`, `contracts` |
 | automation | `meet`, `event`, `remind` |
-| extensions | `extension`, `package`, `packages`, `install`, `upgrade` |
+| extensions | `package` |

package/docs/generated/REFUSAL_CLOSURE_CENSUS.md

@@ -4,14 +4,14 @@ Tracker: `pm-f05lsg`.
 
 Every catalog code is listed. An `uncovered` row is an explicit closure obligation, never an omission or implied approval.
 
-- Catalog error codes: 343
-- Executable error codes: 18
+- Catalog error codes: 344
+- Executable error codes: 19
 - Executable-code ratchet floor: 18
 - Required executable canonical codes: `bulk_ids_input_empty`, `bulk_ids_input_missing_path`, `bulk_ids_input_unreadable`, `invalid_argument_value`, `manifest_unknown_key`, `missing_lifecycle_target`, `missing_required_argument`, `no_version_bounds_declared`, `projection_options_mutually_exclusive`, `tracker_not_initialized`, `tracker_root_missing`, `tracker_root_not_directory`, `tracker_root_unreadable`, `unknown_context_intent`, `unknown_field_projection`, `unknown_option`, `unknown_subcommand`
 - Uncovered error codes: 325
-- Coverage fraction: 0.052478
-- Closed-domain probes: 18
-- Grammar probes: 95
+- Coverage fraction: 0.055233
+- Closed-domain probes: 19
+- Grammar probes: 94
 
 | Error code | Canonical code | Disposition | Evidence kinds | Probe count |
 | --- | --- | --- | --- | --- |
@@ -198,7 +198,7 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 | `missing_observed_signature` | `missing_observed_signature` | uncovered | none | 0 |
 | `missing_parameter_alias` | `missing_parameter_alias` | uncovered | none | 0 |
 | `missing_probe` | `missing_probe` | uncovered | none | 0 |
-| `missing_required_argument` | `missing_required_argument` | executable | grammar | 58 |
+| `missing_required_argument` | `missing_required_argument` | executable | grammar | 57 |
 | `missing_required_option` | `missing_required_option` | uncovered | none | 0 |
 | `missing_suggested_retry` | `missing_suggested_retry` | uncovered | none | 0 |
 | `missing_suggested_retry_args` | `missing_suggested_retry_args` | uncovered | none | 0 |
@@ -218,6 +218,7 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 | `ownership_dependency_bypass_restricted_options` | `ownership_dependency_bypass_restricted_options` | uncovered | none | 0 |
 | `ownership_metadata_bypass_restricted_options` | `ownership_metadata_bypass_restricted_options` | uncovered | none | 0 |
 | `package_spec_empty` | `package_spec_empty` | uncovered | none | 0 |
+| `package_upgrade_modes_mutually_exclusive` | `package_upgrade_modes_mutually_exclusive` | executable | closed_domain | 1 |
 | `positional_shape_budget_exceeded` | `positional_shape_budget_exceeded` | uncovered | none | 0 |
 | `positional_signature_mismatch` | `positional_signature_mismatch` | uncovered | none | 0 |
 | `profile_name_empty` | `profile_name_empty` | uncovered | none | 0 |

package/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Official marketplace for pm CLI — native git-based project management for Claude Code and AI coding agents.",
-    "version": "2026.8.26"
+    "version": "2026.8.27"
   },
   "plugins": [
     {
       "name": "pm-claude",
       "source": "./plugins/pm-claude",
       "description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents, hybrid TUI task tracking, session context injection, and coordination subagents for git-based project management without leaving Claude Code.",
-      "version": "2026.8.26",
+      "version": "2026.8.27",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"