@unbrained/pm-cli 2026.5.12 → 2026.5.18

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,302 +10,45 @@ 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_PROVIDER_TOOL_PARAMETERS_SCHEMA`
-- `PM_TOOL_ACTION_PARAMETER_CONTRACTS`
-
-`PM_TOOL_ACTIONS` includes the package lifecycle actions and `upgrade`, so agents and apps can discover `pm upgrade` through `pm contracts` instead of hard-coding flags.
-
-### 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 package --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 = "package-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_PROVIDER_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:
-
-- `manifest` current: `v2`
-- supported previous: `v1`
-- strategy: `versioned_breaking`
 
-Recommended migration flow:
+Package manifest exports:
 
-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:
 
@@ -315,160 +58,30 @@ Command/action contract exports:
 - `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 package 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 package --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 package 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`
-
-## Tooling Compatibility
-
-For provider-safe schemas, use `PM_PROVIDER_TOOL_PARAMETERS_SCHEMA`. It is flat, non-`oneOf`, and designed for tool providers that reject advanced schema constructs. Agent-specific adapters should consume this SDK export from their own packages instead of adding agent runtime code to the main `pm` CLI.
-
-## 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_PACKAGE_RESOURCE_KINDS`
-- `PM_PACKAGE_CONVENTIONAL_RESOURCE_ROOTS`
-- `readPmPackageManifest`
-- `collectPackageExtensionDirectories`
-- `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:
 
@@ -476,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 |
@@ -512,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" }),
     });
   },
@@ -583,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:
 
@@ -614,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)

package/docs/TESTING.md

@@ -36,7 +36,7 @@ Use focused runs while iterating, then run coverage before closure when risk or
 Add tests to the item that owns the work:
 
 ```bash
-pm test <item-id> --add command="node scripts/run-tests.mjs test -- tests/unit/output.spec.ts",scope=project,timeout_seconds=240
+pm test <item-id> --add command="node scripts/run-tests.mjs test -- tests/unit/output.spec.ts",timeout_seconds=240
 pm test <item-id> --run --progress
 ```
 
@@ -76,7 +76,7 @@ Linked tests can include assertion metadata:
 
 ```bash
 pm test <item-id> --add \
-  command="pm list-open --json",scope=project,timeout_seconds=120,assert_json_field_gte=count:0
+  command="pm list-open --json",timeout_seconds=120,assert_json_field_gte=count:0
 ```
 
 Common assertion keys include:

package/marketplace.json

@@ -7,10 +7,10 @@
   },
   "plugins": [
     {
-      "name": "pm-cli",
+      "name": "pm-claude",
       "description": "Native pm CLI integration for Claude Code — 18 MCP tools, 5 workflow skills, 14 slash commands, 3 subagents, hybrid TUI task tracking, session context injection, and coordination subagents for git-based project management without leaving Claude Code.",
-      "version": "1.3.0",
-      "source": "./plugins/pm-cli-claude",
+      "version": "1.4.0",
+      "source": "./plugins/pm-claude",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.5.12",
+  "version": "2026.5.18",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "author": "unbrained",
@@ -48,14 +48,15 @@
     "docs/**",
     ".claude-plugin/**",
     "plugins/**",
-    "packages/pm-beads/**",
-    "packages/pm-todos/**",
+    "packages/pm-*/**",
+    "scripts/finalize-build.mjs",
     "scripts/install.sh",
     "scripts/install.ps1",
+    "scripts/prepare-build-cache.mjs",
     "marketplace.json"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "node scripts/prepare-build-cache.mjs && tsc -p tsconfig.json && node scripts/finalize-build.mjs",
     "typecheck": "tsc --noEmit -p tsconfig.json && tsc -p tsconfig.packages.json",
     "start": "node dist/cli.js",
     "dev": "tsx src/cli.ts",
@@ -63,6 +64,7 @@
     "test:coverage": "node scripts/run-tests.mjs coverage",
     "quality:static": "node scripts/release/static-quality-gate.mjs",
     "quality:docs-skills": "node scripts/release/docs-skills-gate.mjs",
+    "dogfood:package-first": "node scripts/dogfood-package-first.mjs",
     "smoke:codex-plugin": "node scripts/smoke-codex-plugin-mcp.mjs",
     "smoke:claude-plugin": "node scripts/smoke-claude-plugin.mjs",
     "version:check": "node scripts/release-version.mjs check",
@@ -72,6 +74,7 @@
     "release:gates": "node scripts/release/run-gates.mjs --telemetry-mode best-effort",
     "release:pipeline": "node scripts/release/run-release-pipeline.mjs",
     "release:pipeline:dry-run": "node scripts/release/run-release-pipeline.mjs --dry-run",
+    "release:verify-published": "node scripts/release/verify-published-release.mjs",
     "security:scan": "node scripts/check-secrets.mjs",
     "smoke:npx": "node scripts/smoke-npx-from-pack.mjs",
     "sentry:inject": "sentry-cli sourcemaps inject dist/",