@unbrained/pm-cli 2026.5.11 → 2026.5.14

package/docs/RELEASING.md

@@ -40,7 +40,7 @@ pnpm version:check
 - Keep any `release` environment compatible with free GitHub features. This repository is public, so environment secrets and tag/branch deployment rules are compatible with the free GitHub path; do not add paid-only release gates.
 - Ensure `GITHUB_TOKEN` has `contents: write` for GitHub Release creation.
 - Keep `package.json` repository, homepage, and bugs URLs aligned with `https://github.com/unbraind/pm-cli`.
-- Keep npm automation token settings compatible with provenance publishing. The release workflow must keep `id-token: write`, a GitHub-hosted runner, and `npm publish --access public --provenance`.
+- Keep npm automation token settings compatible with provenance publishing. The release workflow must keep `id-token: write`, a GitHub-hosted runner, and `npm publish --access public --provenance`. npm Trusted Publishing is preferred because it uses OIDC short-lived credentials; if the npm package is configured for Trusted Publishing, restrict traditional token publishing after verifying the workflow.
 
 ## Automated Daily Driver
 
@@ -134,8 +134,9 @@ git push origin v<version>
 - generated release notes from changelog plus sanitized tracker metadata
 - artifact uploads
 - `npm publish --access public --provenance`, skipped on retry when the exact version is already present on npm
-- post-publish npm/npx/bunx verification
+- post-publish npm/npx/bunx verification through `scripts/release/verify-published-release.mjs`
 - GitHub Release creation
+- GitHub Release metadata verification through the same local verification script
 
 Monitor:
 
@@ -151,6 +152,7 @@ npm view @unbrained/pm-cli@<version> version dist.integrity dist.unpackedSize --
 npx --yes --package @unbrained/pm-cli@<version> -- pm --version
 bunx --bun @unbrained/pm-cli@<version> pm --version
 gh release view v<version> --json tagName,name,isDraft,isPrerelease,url
+pnpm release:verify-published -- --version <version>
 ```
 
 The executable remains `pm` even though the npm package is scoped.

package/docs/SDK.md

@@ -2,7 +2,7 @@
 
 The supported programmatic surface is `@unbrained/pm-cli/sdk`.
 
-Use this package for extension authoring, command/action contract discovery, and deterministic app or CI automation. Do not import private `src/core/...` modules from external integrations.
+Use it for extension authoring, package authoring, command/action contract discovery, and deterministic app or CI automation. Do not import private `src/core/...` modules from external integrations or packages.
 
 ## Install
 
@@ -10,461 +10,78 @@ Use this package for extension authoring, command/action contract discovery, and
 npm install @unbrained/pm-cli
 ```
 
-## Core Exports
-
-### Extension authoring
-
-- `defineExtension`
-- `EXTENSION_CAPABILITIES`
-- `EXTENSION_CAPABILITY_CONTRACT`
-- `EXTENSION_CAPABILITY_CONTRACT_VERSION`
-- `EXTENSION_CAPABILITY_LEGACY_ALIASES`
-- `EXTENSION_POLICY_MODES`
-- `EXTENSION_POLICY_SURFACES`
-- `EXTENSION_TRUST_MODES`
-- `EXTENSION_SANDBOX_PROFILES`
-
-### Command and action contracts
-
-- `PM_CORE_COMMAND_NAMES`
-- `PM_TOOL_ACTIONS`
-- `PM_TOOL_PARAMETERS_SCHEMA`
-- `PM_PI_TOOL_PARAMETERS_SCHEMA`
-- `PM_TOOL_ACTION_PARAMETER_CONTRACTS`
-
-### Runtime contract constants
-
-- `PM_EXTENSION_CAPABILITY_CONTRACTS`
-- `PM_EXTENSION_SERVICE_NAME_CONTRACTS`
-- `PM_EXTENSION_POLICY_MODE_CONTRACTS`
-- `PM_EXTENSION_POLICY_SURFACE_CONTRACTS`
-- `PM_EXTENSION_TRUST_MODE_CONTRACTS`
-- `PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS`
-
-### Type guards
-
-- `isPmToolAction`
-- `isPmExtensionCapabilityContract`
-- `isPmExtensionServiceNameContract`
-- `isPmExtensionPolicyModeContract`
-- `isPmExtensionPolicySurfaceContract`
-
-## Capability Mapping
-
-- `commands` -> `registerCommand`
-- `schema` -> `registerFlags`, `registerItemFields`, `registerItemTypes`, `registerMigration`
-- `importers` -> `registerImporter`, `registerExporter`
-- `search` -> `registerSearchProvider`, `registerVectorStoreAdapter`
-- `hooks` -> `api.hooks.*`
-- `parser` -> `registerParser`
-- `preflight` -> `registerPreflight`
-- `services` -> `registerService`
-- `renderers` -> `registerRenderer`
-
-## Extension Example
+## Import Surfaces
 
 ```ts
 import { defineExtension } from "@unbrained/pm-cli/sdk";
-
-export default defineExtension({
-  activate(api) {
-    api.registerCommand({
-      name: "release audit",
-      action: "release-audit",
-      description: "Collect release-readiness diagnostics.",
-      intent: "Produce deterministic gate payloads for CI.",
-      flags: [{ long: "--strict", description: "Enable strict gate mode." }],
-      run: async (context) => ({
-        ok: true,
-        command: context.command,
-        strict: context.options.strict === true,
-      }),
-    });
-  },
-});
-```
-
-## Contracts-First Automation
-
-Use runtime contracts for extension-aware schemas:
-
-```bash
-pm contracts --json
-pm contracts --schema-only --json
-pm contracts --command extension --flags-only --json
-pm contracts --action create --schema-only --json
-```
-
-Minimal script pattern:
-
-```ts
-import { PM_TOOL_ACTION_PARAMETER_CONTRACTS, isPmToolAction } from "@unbrained/pm-cli/sdk";
-import { spawnSync } from "node:child_process";
-
-const action = "extension-reload";
-if (!isPmToolAction(action)) throw new Error("Unsupported action");
-const contract = PM_TOOL_ACTION_PARAMETER_CONTRACTS[action];
-console.log(contract.required, contract.optional);
-
-const result = spawnSync("pm", ["contracts", "--json"], { encoding: "utf8" });
-if (result.status !== 0) throw new Error(result.stderr);
 ```
 
-## Compatibility Metadata
-
-`pm contracts --json` includes compatibility metadata for extension integrations:
-
-- `extension_contracts.trust_modes`
-- `extension_contracts.sandbox_profiles`
-- `extension_contracts.manifest_versions`
-- `extension_contracts.compatibility`
-- `action_availability[].policy_state`
-
-Current compatibility model:
-
-- manifest current: `v2`
-- supported previous: `v1`
-- strategy: `versioned_breaking`
-
-## Runnable Examples
-
-- `docs/examples/sdk-contract-consumer/`
-- `docs/examples/sdk-app-embedding/`
-- `docs/examples/ci/`
-
-## Related Docs
-
-- `docs/EXTENSIONS.md`
-- `docs/CLAUDE_CODE_PLUGIN.md`
-# SDK
-
-The supported programmatic surface is `@unbrained/pm-cli/sdk`.
-
-Use this for:
-
-- extension authoring (`defineExtension`)
-- command/action schema discovery (`PM_TOOL_PARAMETERS_SCHEMA`)
-- runtime action contracts (`PM_TOOL_ACTION_PARAMETER_CONTRACTS`)
-- capability/policy/trust/sandbox contract constants
+Supported package exports:
 
-Do not import private `src/core/...` modules from external integrations.
+- `@unbrained/pm-cli/sdk` - stable extension and package authoring API plus CLI contract exports.
+- `@unbrained/pm-cli/cli` - runtime CLI module entrypoint for package resolution, not a typed library API.
 
-## Install
+## Public Exports
 
-```bash
-npm install @unbrained/pm-cli
-```
+Source of truth:
 
-## Key Exports
+- [`src/sdk/index.ts`](../src/sdk/index.ts)
+- [`src/sdk/runtime.ts`](../src/sdk/runtime.ts)
+- [`src/sdk/cli-contracts.ts`](../src/sdk/cli-contracts.ts)
+- [`src/sdk/cli-contracts/commander-types.ts`](../src/sdk/cli-contracts/commander-types.ts)
+- [`src/sdk/cli-contracts/commander-mutation-options.ts`](../src/sdk/cli-contracts/commander-mutation-options.ts)
 
-### Extension Authoring
+Common authoring exports:
 
 - `defineExtension`
 - `EXTENSION_CAPABILITIES`
+- `EXTENSION_CAPABILITY_CONTRACT`
+- `EXTENSION_CAPABILITY_CONTRACT_VERSION`
+- `EXTENSION_CAPABILITY_LEGACY_ALIASES`
 - `EXTENSION_POLICY_MODES`
 - `EXTENSION_POLICY_SURFACES`
 - `EXTENSION_TRUST_MODES`
 - `EXTENSION_SANDBOX_PROFILES`
-- `EXTENSION_CAPABILITY_CONTRACT`
-- `EXTENSION_CAPABILITY_CONTRACT_VERSION`
-- `EXTENSION_CAPABILITY_LEGACY_ALIASES`
-
-### Command/Action Contracts
-
-- `PM_CORE_COMMAND_NAMES`
-- `PM_TOOL_ACTIONS`
-- `PM_TOOL_PARAMETERS_SCHEMA`
-- `PM_PI_TOOL_PARAMETERS_SCHEMA`
-- `PM_TOOL_ACTION_PARAMETER_CONTRACTS`
-
-### Extension Runtime Contract Constants
-
-- `PM_EXTENSION_CAPABILITY_CONTRACTS`
-- `PM_EXTENSION_SERVICE_NAME_CONTRACTS`
-- `PM_EXTENSION_POLICY_MODE_CONTRACTS`
-- `PM_EXTENSION_POLICY_SURFACE_CONTRACTS`
-- `PM_EXTENSION_TRUST_MODE_CONTRACTS`
-- `PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS`
-
-### Type Guards
-
-- `isPmToolAction`
-- `isPmExtensionCapabilityContract`
-- `isPmExtensionServiceNameContract`
-- `isPmExtensionPolicyModeContract`
-- `isPmExtensionPolicySurfaceContract`
-
-## Extension Example
-
-```ts
-import { defineExtension } from "@unbrained/pm-cli/sdk";
-
-export default defineExtension({
-  activate(api) {
-    api.registerCommand({
-      name: "release audit",
-      action: "release-audit",
-      description: "Collect release-readiness diagnostics.",
-      intent: "Produce deterministic gate payloads for CI.",
-      run: async (context) => ({
-        ok: true,
-        command: context.command,
-      }),
-    });
-  },
-});
-```
-
-## Contracts-First Automation Pattern
-
-```ts
-import { PM_TOOL_ACTION_PARAMETER_CONTRACTS, isPmToolAction } from "@unbrained/pm-cli/sdk";
-import { spawnSync } from "node:child_process";
-
-const action = "extension-reload";
-if (!isPmToolAction(action)) throw new Error("Unsupported action");
-const contract = PM_TOOL_ACTION_PARAMETER_CONTRACTS[action];
-console.log(contract.required, contract.optional);
-
-const contracts = spawnSync("pm", ["contracts", "--json"], { encoding: "utf8" });
-if (contracts.status !== 0) throw new Error(contracts.stderr);
-```
-
-## Runtime Metadata Added For v2
-
-`pm contracts --json` now includes richer extension metadata:
-
-- `extension_contracts.trust_modes`
-- `extension_contracts.sandbox_profiles`
-- `extension_contracts.manifest_versions`
-- `extension_contracts.compatibility`
-- `action_availability[].policy_state` for extension-backed actions
-
-Use these fields to gate CI and to route compatibility behavior in embedded runtimes.
-
-## Versioned-Breaking Compatibility
 
-Current contract compatibility model:
+Package manifest exports:
 
-- `manifest` current: `v2`
-- supported previous: `v1`
-- strategy: `versioned_breaking`
-
-Recommended migration flow:
-
-1. read runtime contracts (`pm contracts --json`)
-2. branch behavior by compatibility metadata
-3. migrate manifests/policy to v2
-4. enforce trust/sandbox policy gates in CI
-
-## Runnable Examples
-
-- contracts consumer: `docs/examples/sdk-contract-consumer/`
-- app embedding runner: `docs/examples/sdk-app-embedding/`
-- CI gates: `docs/examples/ci/`
-
-## Related Docs
-
-- `docs/EXTENSIONS.md`
-- `docs/CLAUDE_CODE_PLUGIN.md`
-# SDK
-
-The stable integration surface is `@unbrained/pm-cli/sdk`. Use it for extension authoring, action/flag contract discovery, and deterministic app/CI automation.
-
-## Install
-
-```bash
-npm install @unbrained/pm-cli
-```
-
-```ts
-import {
-  defineExtension,
-  EXTENSION_CAPABILITIES,
-  EXTENSION_POLICY_MODES,
-  EXTENSION_POLICY_SURFACES,
-  PM_TOOL_ACTIONS,
-  PM_TOOL_PARAMETERS_SCHEMA,
-  PM_TOOL_ACTION_PARAMETER_CONTRACTS,
-  PM_EXTENSION_CAPABILITY_CONTRACTS,
-  PM_EXTENSION_SERVICE_NAME_CONTRACTS,
-  PM_EXTENSION_POLICY_MODE_CONTRACTS,
-  PM_EXTENSION_POLICY_SURFACE_CONTRACTS,
-  isPmToolAction,
-  isPmExtensionCapabilityContract,
-} from "@unbrained/pm-cli/sdk";
-```
-
-## What Is Exported
-
-Core authoring exports:
-
-- `defineExtension`
-- `EXTENSION_CAPABILITIES`
-- `EXTENSION_CAPABILITY_CONTRACT`
-- `EXTENSION_POLICY_MODES`
-- `EXTENSION_POLICY_SURFACES`
+- `PM_PACKAGE_RESOURCE_KINDS` (`extensions`, `docs`, `examples`)
+- `PM_PACKAGE_CONVENTIONAL_RESOURCE_ROOTS`
+- `readPmPackageManifest`
+- `collectPackageExtensionDirectories`
 
 Command/action contract exports:
 
 - `PM_CORE_COMMAND_NAMES`
 - `PM_TOOL_ACTIONS`
 - `PM_TOOL_PARAMETERS_SCHEMA`
-- `PM_PI_TOOL_PARAMETERS_SCHEMA`
+- `PM_PROVIDER_TOOL_PARAMETERS_SCHEMA`
 - `PM_TOOL_ACTION_PARAMETER_CONTRACTS`
 
+Commander option contract exports:
+
+- `CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS`
+- `UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS`
+- `CREATE_COMMANDER_STRING_OPTION_CONTRACTS`
+- `CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS`
+- `UPDATE_COMMANDER_STRING_OPTION_CONTRACTS`
+- `UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS`
+- `LIST_COMMANDER_STRING_OPTION_CONTRACTS`
+- `SEARCH_COMMANDER_STRING_OPTION_CONTRACTS`
+- `CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS`
+- `CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS`
+- `ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS`
+- `readFirstStringFromCommanderOptions`
+- `readStringArrayFromCommanderOptions`
+
 Extension runtime contract exports:
 
 - `PM_EXTENSION_CAPABILITY_CONTRACTS`
 - `PM_EXTENSION_SERVICE_NAME_CONTRACTS`
 - `PM_EXTENSION_POLICY_MODE_CONTRACTS`
 - `PM_EXTENSION_POLICY_SURFACE_CONTRACTS`
-
-Type guards:
-
-- `isPmToolAction(value)`
-- `isPmExtensionCapabilityContract(value)`
-- `isPmExtensionServiceNameContract(value)`
-- `isPmExtensionPolicyModeContract(value)`
-- `isPmExtensionPolicySurfaceContract(value)`
-
-## Capability Mapping
-
-- `commands` -> `registerCommand`
-- `schema` -> `registerFlags`, `registerItemFields`, `registerItemTypes`, `registerMigration`
-- `importers` -> `registerImporter`, `registerExporter`
-- `search` -> `registerSearchProvider`, `registerVectorStoreAdapter`
-- `hooks` -> `api.hooks.*`
-- `parser` -> `registerParser`
-- `preflight` -> `registerPreflight`
-- `services` -> `registerService`
-- `renderers` -> `registerRenderer`
-
-## Extension Authoring Example
-
-```ts
-import { defineExtension } from "@unbrained/pm-cli/sdk";
-
-export default defineExtension({
-  activate(api) {
-    api.registerCommand({
-      name: "release audit",
-      action: "release-audit",
-      description: "Collect release readiness diagnostics.",
-      intent: "provide deterministic audit payloads for CI gates",
-      examples: ["pm release audit --strict"],
-      failure_hints: ["Run pm extension --doctor --detail deep --trace on activation failures."],
-      flags: [{ long: "--strict", description: "Enable strict gate mode." }],
-      run: async (context) => ({
-        ok: true,
-        command: context.command,
-        strict: context.options.strict === true,
-      }),
-    });
-  },
-});
-```
-
-## Programmatic Contracts (App/Script)
-
-Use runtime `pm contracts` for extension-aware schemas:
-
-```bash
-pm contracts --json
-pm contracts --schema-only --json
-pm contracts --command extension --flags-only --json
-pm contracts --action create --schema-only --json
-```
-
-The result includes:
-
-- `actions`: runtime-invocable action list
-- `action_availability`: invocable/disabled reasons
-- `schema`: strict action-scoped JSON schema
-- `command_flags`: merged core + extension + runtime field flags
-- `extension_contracts`: capabilities/services/policy mode/surface contract metadata
-
-## Robust Script Pattern
-
-See runnable example: `docs/examples/sdk-contract-consumer/inspect-contracts.mjs`.
-
-Minimal pattern:
-
-1. Read contracts JSON.
-2. Validate action exists in `actions`.
-3. Validate required fields with `PM_TOOL_ACTION_PARAMETER_CONTRACTS`.
-4. Execute the action only after preflight passes.
-
-## CI/CD Pattern
-
-Recommended gate sequence:
-
-```bash
-pnpm build
-pm contracts --schema-only --json > /tmp/pm-contracts.json
-pm extension --doctor --project --detail summary --strict-exit
-node scripts/run-tests.mjs test -- tests/unit/contracts-command.spec.ts
-node scripts/run-tests.mjs coverage
-```
-
-Reference workflow file:
-
-- `docs/examples/ci/github-actions-pm-extension-gate.yml`
-
-## Pi / Tooling Compatibility
-
-For provider-safe schemas, use `PM_PI_TOOL_PARAMETERS_SCHEMA`. It is flat, non-`oneOf`, and designed for tool providers that reject advanced schema constructs.
-
-The bundled Pi wrapper (`.pi/extensions/pm-cli/index.js`) consumes this schema directly to reduce contract drift.
-
-## Related Docs
-
-- `docs/EXTENSIONS.md`
-- `docs/examples/starter-extension/README.md`
-- `docs/examples/sdk-contract-consumer/README.md`
-# SDK
-
-The public SDK is exported from `@unbrained/pm-cli/sdk`. Use it for extension authoring and command-contract introspection. Do not import internal `src/core/...` modules from extensions.
-
-## Agent Quick Context
-
-- Primary import: `@unbrained/pm-cli/sdk`.
-- Runtime extension lifecycle is documented in [Extensions](EXTENSIONS.md).
-- Exact command/action contracts are available through `pm contracts`.
-- Local deep-dive routing is available through `pm guide sdk --depth deep`.
-
-Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
-
-## Import Surfaces
-
-```ts
-import { defineExtension } from "@unbrained/pm-cli/sdk";
-```
-
-Supported package exports:
-
-- `@unbrained/pm-cli/sdk` - stable extension authoring API and CLI contract exports.
-- `@unbrained/pm-cli/cli` - runtime CLI module entrypoint for package resolution, not a typed library API.
-
-## Public Exports
-
-Source of truth:
-
-- [`src/sdk/index.ts`](../src/sdk/index.ts)
-- [`src/sdk/cli-contracts.ts`](../src/sdk/cli-contracts.ts)
-
-Common authoring exports:
-
-- `defineExtension`
-- `EXTENSION_CAPABILITIES`
-- `EXTENSION_CAPABILITY_CONTRACT`
-- `EXTENSION_CAPABILITY_CONTRACT_VERSION`
-- `EXTENSION_CAPABILITY_LEGACY_ALIASES`
-- `PM_CORE_COMMAND_NAMES`
-- `PM_TOOL_ACTIONS`
-- `PM_TOOL_PARAMETERS_SCHEMA`
-- `PM_EXTENSION_CAPABILITY_CONTRACTS`
-- `PM_EXTENSION_SERVICE_NAME_CONTRACTS`
+- `PM_EXTENSION_TRUST_MODE_CONTRACTS`
+- `PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS`
 
 Common types:
 
@@ -472,13 +89,35 @@ Common types:
 - `ExtensionManifest`
 - `CommandDefinition`
 - `FlagDefinition`
+- `ServiceOverrideContext`
 - `SchemaFieldDefinition`
 - `SchemaItemTypeDefinition`
 - `SearchProviderDefinition`
 - `VectorStoreAdapterDefinition`
 - `GlobalOptions`
+- `ItemDocument`
 - `PmSettings`
 
+## Static And Runtime Contracts
+
+`PM_TOOL_ACTIONS` and `PM_TOOL_PARAMETERS_SCHEMA` describe the always-on static core action surface. They include core project-management primitives, package lifecycle actions, and `upgrade`.
+
+Package-owned actions such as `beads-import`, `todos-export`, `calendar`, and `templates-save` are intentionally not advertised as static core actions. Discover installed package actions with runtime contracts:
+
+```bash
+pm contracts --runtime-only --json
+pm contracts --action calendar --runtime-only --schema-only --json
+pm contracts --command templates --runtime-only --flags-only --json
+```
+
+Use static SDK contracts for baseline validation, then use `pm contracts --runtime-only` in the target project before invoking package-provided commands or actions.
+
+When a package-owned command is missing at runtime, CLI usage guidance now includes a deterministic install hint (for example `pm install calendar` or `pm install search-advanced`) so agents can recover in one retry.
+
+Package installs currently activate only extension resources. Additional package resource kinds (`docs`, `examples`) are metadata-first and available through package manifest/catalog inspection.
+
+For provider-safe schemas, use `PM_PROVIDER_TOOL_PARAMETERS_SCHEMA`. It is flat and avoids advanced schema constructs such as root `oneOf`.
+
 ## Capability Requirements
 
 | Registration | Manifest capability |
@@ -508,9 +147,11 @@ export default defineExtension({
   activate(api) {
     api.registerCommand({
       name: "hello",
+      action: "hello",
       description: "Return a deterministic hello payload.",
       intent: "verify SDK extension activation",
       examples: ["pm hello"],
+      failure_hints: ["Run pm package doctor --detail deep --trace on activation failures."],
       run: async () => ({ ok: true, message: "hello" }),
     });
   },
@@ -579,23 +220,23 @@ export default defineExtension({
 
 Manifest capability: `search`.
 
-## Command Contracts
+## Robust Automation Pattern
 
-For machine clients:
+1. Read `PM_TOOL_ACTIONS` or `PM_TOOL_PARAMETERS_SCHEMA` for baseline static validation.
+2. Run `pm contracts --runtime-only --json` inside the target project.
+3. Verify the action appears in `actions` and has `action_availability[].invocable: true`.
+4. Validate required fields with `PM_TOOL_ACTION_PARAMETER_CONTRACTS` for static actions or the runtime schema for package actions.
+5. Execute only after preflight passes.
 
-```bash
-pm contracts --json
-pm contracts --command create --flags-only --json
-pm contracts --action create --schema-only --json
-```
+Runnable examples:
 
-Use the runtime command because active extensions can add command/action metadata.
+- [SDK contract consumer](examples/sdk-contract-consumer/README.md)
+- [SDK app embedding](examples/sdk-app-embedding/README.md)
+- [CI examples](examples/ci/)
 
 ## CLI Simplification Migration
 
-The conservative full-surface simplification pass updated invocation parsing and error envelopes. Integration details are documented in:
-
-- [CLI Simplification Migration](MIGRATION_CLI_SIMPLIFICATION.md)
+The conservative full-surface simplification pass updated invocation parsing and error envelopes. Integration details are documented in [CLI Simplification Migration](MIGRATION_CLI_SIMPLIFICATION.md).
 
 For SDK and automation consumers, the key runtime change is the optional `recovery` object in CLI usage/error JSON payloads:
 
@@ -610,15 +251,15 @@ Treat `recovery.suggested_retry` as the first-choice deterministic replay comman
 ## Authoring Pattern
 
 - Keep handlers deterministic and JSON-like.
-- Return data, not pre-rendered terminal text, unless implementing a renderer.
+- Return data, not pre-rendered terminal text, unless implementing a renderer or output service.
 - Keep service and preflight overrides narrow.
 - Declare only capabilities in use.
 - Include examples and failure hints in dynamic commands.
-- Add `pm extension doctor` diagnostics to testing instructions.
+- Add `pm package doctor` diagnostics to testing instructions.
 
 ## Related Docs
 
-- [Extensions](EXTENSIONS.md)
+- [Extensions And Packages](EXTENSIONS.md)
 - [CLI Simplification Migration](MIGRATION_CLI_SIMPLIFICATION.md)
 - [Architecture](ARCHITECTURE.md)
-- [starter extension](examples/starter-extension/README.md)
+- [Starter Extension](examples/starter-extension/README.md)