@unbrained/pm-cli 2026.8.26 → 2026.8.28

package/dist/sdk/notes.d.ts

@@ -30,6 +30,8 @@ export interface NotesCommandOptions {
     includeMeta?: boolean;
     /** Return complete note history after a mutation instead of a bounded receipt. */
     fullHistory?: boolean;
+    /** Append only when no note has the same resolved author and text. */
+    ifAbsent?: boolean;
     /** Value that configures or reports author for this contract. */
     author?: string;
     /** Human-readable explanation suitable for logs and agent-facing output. */
@@ -59,6 +61,8 @@ export interface NotesResult {
     mutation_receipt?: AnnotationMutationReceipt;
     /** Declares whether older notes were withheld from a mutation response. */
     omission_receipt?: AnnotationOmissionReceipt;
+    /** Whether a requested mutation changed persisted state. */
+    changed?: boolean;
 }
 /** Implements run notes for the public runtime surface of this module. */
 export declare function runNotes(id: string, options: NotesCommandOptions, global: GlobalOptions): Promise<NotesResult>;

package/dist/sdk/notes.js

@@ -4,7 +4,7 @@
  * Implements the pm notes command surface and its agent-facing runtime behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="ebd9f151-593f-5081-97da-d78f83de4914")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="216389a2-fb85-56a0-8ef2-9f41f1321c16")}catch(e){}}();
 import { EXIT_CODE, PmCliError, parseLimit, stableStringify, } from "./runtime-primitives.js";
 import { limitAnnotationEntries, parseAnnotationTextInput, resolveAnnotationInput, runAnnotationCommand, } from "./annotations.js";
 function parseStructuredEventPayload(raw) {
@@ -137,4 +137,4 @@ export async function runNotes(id, options, global) {
     };
 }
 //# sourceMappingURL=notes.js.map
-//# debugId=ebd9f151-593f-5081-97da-d78f83de4914
+//# debugId=216389a2-fb85-56a0-8ef2-9f41f1321c16

package/dist/sdk/read-output-contracts.js

@@ -5,7 +5,7 @@
  * surface without coupling package authors to command-specific option names.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="d084da05-c967-58f1-afe4-069f09838e6f")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="2103a4dc-3037-5768-b2c7-5964de4ac86b")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { compactReadOutputToBudget, estimateReadOutputTokens, resolveReadOutputRecoveryBudget, updateReadOutputReceiptEstimate, } from "./read-output-budget.js";
@@ -388,7 +388,20 @@ export function applyReadOutputIncludeModes(command, includeValue, commandOption
         modes.push(token);
         canonicalModes.add(token);
     }
-    if (modes.length > 0) {
+    const forwardedGetFieldSelectors = resolveReadOutputSurface(command) === "get"
+        ? selectors.filter((selector) => selector !== "item")
+        : [];
+    const forwardedGetFields = forwardedGetFieldSelectors.length > 0;
+    if (forwardedGetFields) {
+        commandOptions.fields = [
+            ...new Set([
+                ...(stringList(commandOptions.fields) ?? []),
+                ...forwardedGetFieldSelectors,
+            ]),
+        ].join(",");
+        canonicalModes.add("fields");
+    }
+    if (modes.length > 0 || forwardedGetFields) {
         optionsWithProvenance[READ_OUTPUT_INVOCATION_PROVENANCE] = {
             canonical_include_modes: [...canonicalModes],
             explicit_legacy_aliases: [...explicitLegacyAliases],
@@ -1210,4 +1223,4 @@ export function resolveReadOutputEncoding(command, options) {
         : undefined;
 }
 //# sourceMappingURL=read-output-contracts.js.map
-//# debugId=d084da05-c967-58f1-afe4-069f09838e6f
+//# debugId=2103a4dc-3037-5768-b2c7-5964de4ac86b

package/dist/sdk/runtime-action-aliases.js

@@ -4,8 +4,8 @@
  * Declares canonical native-action routes for public SDK aliases.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="6f62939a-7b99-5687-93ae-834e0032f1d5")}catch(e){}}();
-import { PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS } from "./cli-contracts/enum-contracts.js";
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="1ff4005f-be23-5dcf-9834-dbd7d083b76d")}catch(e){}}();
+import { PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS, PM_PACKAGE_ONLY_ACTION_SUBCOMMANDS, } from "./cli-contracts/enum-contracts.js";
 const LIST_ACTION_ALIASES = {
     "list-all": { action: "list", options: { excludeTerminal: false } },
     "list-draft": {
@@ -51,6 +51,10 @@ export const SDK_ACTION_ALIASES = {
     ...LIST_ACTION_ALIASES,
     ...buildExtensionPackageActionAliases("extension"),
     ...buildExtensionPackageActionAliases("package"),
+    ...Object.fromEntries(PM_PACKAGE_ONLY_ACTION_SUBCOMMANDS.map((subcommand) => [
+        `package-${subcommand}`,
+        { action: subcommand },
+    ])),
 };
 //# sourceMappingURL=runtime-action-aliases.js.map
-//# debugId=6f62939a-7b99-5687-93ae-834e0032f1d5
+//# debugId=1ff4005f-be23-5dcf-9834-dbd7d083b76d

package/dist/sdk/runtime-input.js

@@ -5,7 +5,7 @@
  * primitives are shared by native action dispatchers and MCP-specific adapters.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="2a1e986f-304d-50f6-a405-6afc221bdad5")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="fde4fea5-94d6-53e2-bfbc-bff71d828c01")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { asRecordClone } from "../core/shared/primitives.js";
@@ -202,6 +202,18 @@ const HOISTED_ACTION_OPTION_KEYS = {
     update: ["parent", "allowMissingParent", "completedAt"],
     copy: ["allowDuplicate"],
     close: ["duplicateOf", "completedAt"],
+    comments: ["ifAbsent"],
+    notes: ["ifAbsent"],
+    learnings: ["ifAbsent"],
+    upgrade: [
+        "scope",
+        "dryRun",
+        "cliOnly",
+        "packagesOnly",
+        "repair",
+        "tag",
+        "packageName",
+    ],
     // pm-7u9j: the narrow pm_append tool declares `body` top-level; runAppend
     // reads it from options, while schema/config consume their top-level values
     // directly in runAction and therefore need no hoisting.
@@ -232,8 +244,7 @@ export function normalizeMcpOptionsArrays(options, action = "") {
             result[key] = value;
             continue;
         }
-        if (typeof value === "string" &&
-            scalarToArrayFields.has(key)) {
+        if (typeof value === "string" && scalarToArrayFields.has(key)) {
             result[key] = [value];
             continue;
         }
@@ -578,4 +589,4 @@ export function updateManyOptionsFromFlat(options) {
     };
 }
 //# sourceMappingURL=runtime-input.js.map
-//# debugId=2a1e986f-304d-50f6-a405-6afc221bdad5
+//# debugId=fde4fea5-94d6-53e2-bfbc-bff71d828c01

package/dist/sdk/runtime-primitives.d.ts

@@ -75,7 +75,7 @@ export { migrateItemFilesToFormat } from "../core/store/item-format-migration.js
 export { type CachedDocumentCandidate, listAllDocumentCandidatesCached, } from "../core/store/item-metadata-cache.js";
 export { buildItemNotFoundError, createMutationGuardSdk, deleteItem, listAllItemMetadata, listAllItemMetadataLight, locateItem, mutateItem, mutateItemWithHistoryContext, readLocatedItem, } from "../core/store/item-store.js";
 export { isTerminalPlanMode, shouldCompletePlanOnClose, } from "../core/item/plan-lifecycle.js";
-export { getHistoryPath, getItemPath, getSettingsPath, resolveImplicitPmRoot, resolvePmRoot, } from "../core/store/paths.js";
+export { getHistoryPath, getItemPath, getSettingsPath, resolveImplicitPmRoot, resolvePmRoot, resolveWorkspaceRoot, } from "../core/store/paths.js";
 export { persistSelectedItemFormat, readSettings, readSettingsWithMetadata, writeSettings, } from "../core/store/settings.js";
 export { maybeRunFirstUseTelemetryPrompt } from "../core/telemetry/consent.js";
 export { type TelemetryCommandResolution, type TelemetryResolutionStage, deriveTelemetryCommandResolution, } from "../core/telemetry/observability.js";

package/dist/sdk/runtime-primitives.js

@@ -7,7 +7,7 @@
  * prefer the typed operations exported by the main SDK barrel.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="4be36c51-a9fc-507d-8f13-d764b5668ab9")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="d45775e5-6826-521b-80b3-429ed22947d9")}catch(e){}}();
 export { createCheckpointId, loadMutationCheckpoint, restoreCheckpointItems, writeMutationCheckpoint, } from "../core/checkpoint/mutation-checkpoint.js";
 export { flattenFlagListValue, resolveFlagValueKind, } from "../core/extensions/flag-value-types.js";
 export { createUnknownSubcommandError, } from "./agent/subcommand-recovery.js";
@@ -76,10 +76,10 @@ export { migrateItemFilesToFormat } from "../core/store/item-format-migration.js
 export { listAllDocumentCandidatesCached, } from "../core/store/item-metadata-cache.js";
 export { buildItemNotFoundError, createMutationGuardSdk, deleteItem, listAllItemMetadata, listAllItemMetadataLight, locateItem, mutateItem, mutateItemWithHistoryContext, readLocatedItem, } from "../core/store/item-store.js";
 export { isTerminalPlanMode, shouldCompletePlanOnClose, } from "../core/item/plan-lifecycle.js";
-export { getHistoryPath, getItemPath, getSettingsPath, resolveImplicitPmRoot, resolvePmRoot, } from "../core/store/paths.js";
+export { getHistoryPath, getItemPath, getSettingsPath, resolveImplicitPmRoot, resolvePmRoot, resolveWorkspaceRoot, } from "../core/store/paths.js";
 export { persistSelectedItemFormat, readSettings, readSettingsWithMetadata, writeSettings, } from "../core/store/settings.js";
 export { maybeRunFirstUseTelemetryPrompt } from "../core/telemetry/consent.js";
 export { deriveTelemetryCommandResolution, } from "../core/telemetry/observability.js";
 export { emitTelemetryErrorEvent, finishTelemetryCommand, startTelemetryCommand, } from "../core/telemetry/runtime.js";
 //# sourceMappingURL=runtime-primitives.js.map
-//# debugId=4be36c51-a9fc-507d-8f13-d764b5668ab9
+//# debugId=d45775e5-6826-521b-80b3-429ed22947d9

package/dist/sdk/runtime.d.ts

@@ -157,11 +157,11 @@ export declare class PmClient {
     stats<Options extends ReadOptions<StatsCommandOptions> = StatsCommandOptions>(options?: Options): ReadPromise<StatsResult, Options>;
     /** Discover existing duplicate clusters without mutating tracker state. */
     duplicates<Options extends ReadOptions<DuplicatesCommandOptions> = DuplicatesCommandOptions>(options?: Options): ReadPromise<DuplicatesResult, Options>;
-    /** List, add, edit, or delete item comments. */
+    /** List or mutate comments, including lock-scoped idempotent appends. */
     comments<Options extends ReadOptions<CommentsCommandOptions> = CommentsCommandOptions>(id: string, options?: Options): ReadPromise<CommentsResult, Options>;
-    /** List or append private item notes. */
+    /** List or mutate private notes, including lock-scoped idempotent appends. */
     notes<Options extends ReadOptions<NotesCommandOptions> = NotesCommandOptions>(id: string, options?: Options): ReadPromise<NotesResult, Options>;
-    /** List or append durable item learnings. */
+    /** List or mutate durable learnings, including lock-scoped idempotent appends. */
     learnings(id: string, options?: LearningsCommandOptions): Promise<LearningsResult>;
     /** Add, remove, clear, or list linked project files for an item. */
     files<Options extends ReadOptions<FilesCommandOptions> = FilesCommandOptions>(id: string, options?: Options): ReadPromise<FilesResult, Options>;
@@ -373,11 +373,11 @@ export declare function aggregate<Options extends ReadOptions<AggregateOptions>
 export declare function stats<Options extends ReadOptions<StatsCommandOptions> = StatsCommandOptions>(options?: Options, clientOptions?: PmClientOptions): ReadPromise<StatsResult, Options>;
 /** Discover duplicate clusters without constructing a reusable client. */
 export declare function duplicates<Options extends ReadOptions<DuplicatesCommandOptions> = DuplicatesCommandOptions>(options?: Options, clientOptions?: PmClientOptions): ReadPromise<DuplicatesResult, Options>;
-/** List, add, edit, or delete item comments without constructing a reusable client. */
+/** List or mutate comments with optional idempotency without constructing a client. */
 export declare function comments<Options extends ReadOptions<CommentsCommandOptions> = CommentsCommandOptions>(id: string, options?: Options, clientOptions?: PmClientOptions): ReadPromise<CommentsResult, Options>;
-/** List or append private item notes without constructing a reusable client. */
+/** List or mutate private notes with optional idempotency without constructing a client. */
 export declare function notes<Options extends ReadOptions<NotesCommandOptions> = NotesCommandOptions>(id: string, options?: Options, clientOptions?: PmClientOptions): ReadPromise<NotesResult, Options>;
-/** List or append durable item learnings without constructing a reusable client. */
+/** List or mutate durable learnings with optional idempotency without constructing a client. */
 export declare function learnings(id: string, options?: LearningsCommandOptions, clientOptions?: PmClientOptions): Promise<LearningsResult>;
 /** Manage linked item files without constructing a reusable client. */
 export declare function files<Options extends ReadOptions<FilesCommandOptions> = FilesCommandOptions>(id: string, options?: Options, clientOptions?: PmClientOptions): ReadPromise<FilesResult, Options>;

package/dist/sdk/runtime.js

@@ -4,7 +4,7 @@
  * Defines public SDK APIs and package-author helpers for Runtime.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="72111aa2-52b2-53da-a1c8-07ba53a74944")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="b67ba0fe-bbca-57ab-b3be-a4a028f21de4")}catch(e){}}();
 export { PM_GITIGNORE_END, PM_GITIGNORE_START, ensurePmGitignore, getPmGitignoreBlock, } from "./workspace.js";
 export { SEARCH_EXTENSION_FLAG_DEFINITIONS } from "./extension-contracts.js";
 export * from "./cli-contracts/agent-output-contracts.js";
@@ -212,15 +212,15 @@ export class PmClient {
     duplicates(options = {}) {
         return this.runTyped("duplicates", { options });
     }
-    /** List, add, edit, or delete item comments. */
+    /** List or mutate comments, including lock-scoped idempotent appends. */
     comments(id, options = {}) {
         return this.runTyped("comments", { id, options });
     }
-    /** List or append private item notes. */
+    /** List or mutate private notes, including lock-scoped idempotent appends. */
     notes(id, options = {}) {
         return this.runTyped("notes", { id, options });
     }
-    /** List or append durable item learnings. */
+    /** List or mutate durable learnings, including lock-scoped idempotent appends. */
     learnings(id, options = {}) {
         return this.runTyped("learnings", { id, options });
     }
@@ -744,15 +744,15 @@ export function stats(options = {}, clientOptions = {}) {
 export function duplicates(options = {}, clientOptions = {}) {
     return new PmClient(clientOptions).duplicates(options);
 }
-/** List, add, edit, or delete item comments without constructing a reusable client. */
+/** List or mutate comments with optional idempotency without constructing a client. */
 export function comments(id, options = {}, clientOptions = {}) {
     return new PmClient(clientOptions).comments(id, options);
 }
-/** List or append private item notes without constructing a reusable client. */
+/** List or mutate private notes with optional idempotency without constructing a client. */
 export function notes(id, options = {}, clientOptions = {}) {
     return new PmClient(clientOptions).notes(id, options);
 }
-/** List or append durable item learnings without constructing a reusable client. */
+/** List or mutate durable learnings with optional idempotency without constructing a client. */
 export function learnings(id, options = {}, clientOptions = {}) {
     return new PmClient(clientOptions).learnings(id, options);
 }
@@ -1933,4 +1933,4 @@ async function loadWorkspaceExtensionRegistrations(pmRoot, settings, cwd) {
     }
 }
 //# sourceMappingURL=runtime.js.map
-//# debugId=72111aa2-52b2-53da-a1c8-07ba53a74944
+//# debugId=b67ba0fe-bbca-57ab-b3be-a4a028f21de4

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:
@@ -735,15 +735,16 @@ explicitly overriding terminal-state or lock conflicts.
 
 ```bash
 pm comments <id> "Implemented command parsing fix."
+pm comments <id> "Implemented command parsing fix." --author agent-a --if-absent
 printf '%s\n' '## Verification summary' '- Linux pass' '- macOS pass' | pm comments <id> --stdin
 pm comments <id> --file docs/release-evidence.md
 pm comments <id> --edit 2 "Corrected: the regression was in the parser, not the renderer."
 pm comments <id> --delete 3
-pm notes <id> --add "Keep renderer changes isolated to TOON output."
-pm learnings <id> --add "Use runtime contracts instead of duplicating flag lists."
+pm notes <id> --add "Keep renderer changes isolated to TOON output." --if-absent
+pm learnings <id> --add "Use runtime contracts instead of duplicating flag lists." --if-absent
 ```
 
-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. For retrying agents, `--if-absent` makes any annotation append idempotent by the resolved author plus exact normalized stored text: the first call returns `changed: true` and `mutation_receipt.changed_count: 1`; an exact retry returns `changed: false`, the existing entry position, and `changed_count: 0` without writing item or history state. Different authors remain distinct, and omitting `--if-absent` deliberately preserves duplicate-appending compatibility. The flag is append-only and is rejected for list, edit, and delete operations. 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.