@unbrained/pm-cli 2026.5.30 → 2026.6.5

package/docs/SDK.md

@@ -19,6 +19,8 @@ import { defineExtension } from "@unbrained/pm-cli/sdk";
 Supported package exports:
 
 - `@unbrained/pm-cli/sdk` - stable extension and package authoring API plus CLI contract exports.
+- `@unbrained/pm-cli/sdk/runtime` - runtime helpers for packages that need command implementations without private imports.
+- `@unbrained/pm-cli/sdk/testing` - lightweight assertion helpers for package/extension tests.
 - `@unbrained/pm-cli/cli` - runtime CLI module entrypoint for package resolution, not a typed library API.
 
 ## Public Exports
@@ -42,6 +44,9 @@ Common authoring exports:
 - `EXTENSION_POLICY_SURFACES`
 - `EXTENSION_TRUST_MODES`
 - `EXTENSION_SANDBOX_PROFILES`
+- `PM_CLI_EXPECTED_ERROR_NAME`
+- `createPmCliExpectedError`
+- `isPmCliExpectedError`
 
 Package manifest exports:
 
@@ -58,6 +63,15 @@ Command/action contract exports:
 - `PM_PROVIDER_TOOL_PARAMETERS_SCHEMA`
 - `PM_TOOL_ACTION_PARAMETER_CONTRACTS`
 
+Testing helper exports (also under `@unbrained/pm-cli/sdk/testing`):
+
+- `activateExtensionForTest`
+- `assertRegisteredCommandContract`
+- `assertRegisteredHook`
+- `assertRegisteredSearchProvider`
+- `assertRegisteredImporter`
+- `assertRegisteredExporter`
+
 Commander option contract exports:
 
 - `CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS`
@@ -87,9 +101,13 @@ Common types:
 
 - `ExtensionApi`
 - `ExtensionManifest`
+- `ExtensionManifestEngines`
 - `CommandDefinition`
 - `FlagDefinition`
+- `ImportExportRegistrationOptions`
 - `ServiceOverrideContext`
+- `PmCliExpectedError`
+- `CreatePmCliExpectedErrorOptions`
 - `SchemaFieldDefinition`
 - `SchemaItemTypeDefinition`
 - `SearchProviderDefinition`
@@ -121,6 +139,15 @@ const contracts = await getContracts("/path/to/project/.agents/pm", {
 });
 ```
 
+For item-type context, use the CLI inspection primitives before issuing custom-domain mutations:
+
+```bash
+pm schema list --json
+pm schema show Experiment --json
+```
+
+`schema list/show` include built-in, persisted custom, and extension-provided item types. Extension-provided types include provenance (`layer` and package/extension name) in `show --json`, which helps agents decide whether a missing type should be registered persistently with `pm schema add-type`, added through `pm init --type-preset`, or provided by an installed package.
+
 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.
@@ -147,6 +174,20 @@ For provider-safe schemas, use `PM_PROVIDER_TOOL_PARAMETERS_SCHEMA`. It is flat
 | `registerSearchProvider` | `search` |
 | `registerVectorStoreAdapter` | `search` |
 
+Some override surfaces are single-winner: command overrides, parser overrides, preflight overrides, and output renderers. Keep those handlers narrowly scoped and verify package combinations with:
+
+```bash
+pm package doctor --project --detail deep --trace
+pm health --check-only --brief
+```
+
+Collision warnings are deterministic and include package names plus deactivation guidance.
+If extension code calls a `register*` API without declaring the matching
+manifest capability, activation fails with
+`extension_capability_missing:<name>:<capability>` in doctor triage. Run doctor
+with `--trace` to see the exact method, `missing_capability`, and manifest
+capability entry to add before publishing.
+
 ## Minimal Command Extension
 
 ```ts
@@ -174,10 +215,167 @@ Manifest:
   "name": "hello",
   "version": "0.1.0",
   "entry": "./index.js",
+  "pm_min_version": "2026.5.31",
   "capabilities": ["commands"]
 }
 ```
 
+`pm_min_version` is an inclusive minimum pm CLI version. When the installed CLI is older than the manifest requires, discovery emits `extension_pm_min_version_unmet:<layer>:<name>:required=<version>:current=<version>` and does not load the extension. Use a plain numeric version such as `2026.5.31`; `>=2026.5.31` is accepted for compatibility with `engines.pm`, but ranges beyond an inclusive minimum are not interpreted.
+
+Manifest typing also accepts optional `engines` metadata:
+
+```json
+{
+  "engines": {
+    "pm": ">=2026.5.31",
+    "node": ">=20"
+  }
+}
+```
+
+Use `pm_min_version` for the loader gate. Keep `engines` as package-manager and tooling metadata.
+
+## Expected CLI Errors
+
+Package commands should throw expected user/action errors with the public SDK shape so the CLI can preserve exit codes and Sentry can filter expected retry failures:
+
+```ts
+import { EXIT_CODE, createPmCliExpectedError } from "@unbrained/pm-cli/sdk";
+
+throw createPmCliExpectedError("hello requires --name", {
+  exitCode: EXIT_CODE.USAGE,
+  context: {
+    code: "missing_name",
+    why: "The command needs a target name.",
+  },
+});
+```
+
+The helper returns an `Error` whose public name is `PmCliError` and whose `exitCode` is structural. That makes it safe for bundled, linked, and separately installed package code even when class identity is not shared with the running CLI.
+
+## Package Runtime Imports
+
+Third-party packages should import from stable public SDK subpaths:
+
+```ts
+import { defineExtension } from "@unbrained/pm-cli/sdk";
+import { createPmCliExpectedError } from "@unbrained/pm-cli/sdk/runtime";
+```
+
+`PM_CLI_PACKAGE_ROOT` is reserved for first-party packages bundled inside this repository. Those packages use it to locate the running CLI's `dist/sdk/runtime.js` before they are installed as independent npm packages. External packages must not depend on `PM_CLI_PACKAGE_ROOT`, `dist/` paths, or `src/core/...`; declare `@unbrained/pm-cli` as a dependency or peer dependency and import the public SDK subpaths instead.
+
+## Testing Helpers
+
+Package tests can assert registration contracts without depending on Vitest-specific
+helpers. Every assertion normalizes the expected name, returns the matched registration
+entry, and throws an `Error` that lists what _is_ available when the expectation is
+missing. They are exported from both `@unbrained/pm-cli/sdk/testing` and the main
+`@unbrained/pm-cli/sdk` barrel.
+
+Activate an in-memory extension module without private loader imports:
+
+```ts
+import {
+  activateExtensionForTest,
+  assertRegisteredCommandContract,
+} from "@unbrained/pm-cli/sdk/testing";
+
+const activation = await activateExtensionForTest({
+  manifest: {
+    name: "hello-ext",
+    version: "0.1.0",
+    entry: "./index.js",
+    priority: 0,
+    capabilities: ["commands", "schema"],
+  },
+  activate(api) {
+    api.registerCommand({
+      name: "hello",
+      action: "hello",
+      description: "Return a deterministic hello payload.",
+      flags: [{ long: "--name", value_type: "string" }],
+      run: async () => ({ ok: true }),
+    });
+  },
+});
+
+assertRegisteredCommandContract(activation.registrations, {
+  command: "hello",
+  action: "hello",
+  flags: ["--name"],
+});
+```
+
+`activateExtensionForTest` uses the real pm activation engine and capability
+guardrails, but it does not discover files or install packages. Use it for unit
+tests of extension registration shape; keep `pm package doctor` and runtime
+contracts in integration tests.
+
+Assert a command registration contract:
+
+```ts
+import { assertRegisteredCommandContract } from "@unbrained/pm-cli/sdk/testing";
+
+assertRegisteredCommandContract(activation.registrations, {
+  command: "hello",
+  action: "hello",
+  flags: ["--name"],
+});
+```
+
+Assert importer, exporter, and search-provider registrations against an
+`ExtensionRegistrationRegistry` (from `activation.registrations`). The optional
+`extensionName` narrows the match to a single extension:
+
+```ts
+import {
+  assertRegisteredExporter,
+  assertRegisteredImporter,
+  assertRegisteredSearchProvider,
+} from "@unbrained/pm-cli/sdk/testing";
+
+assertRegisteredImporter(activation.registrations, { importer: "jsonl" });
+assertRegisteredExporter(activation.registrations, {
+  exporter: "jsonl",
+  extensionName: "my-ext",
+});
+assertRegisteredSearchProvider(activation.registrations, { provider: "semantic-local" });
+```
+
+Hooks are surfaced via `activation.hooks` (an `ExtensionHookRegistry`), not the command
+registry, so `assertRegisteredHook` takes the hook registry and a lifecycle `kind`
+(`before_command` | `after_command` | `on_read` | `on_write` | `on_index`):
+
+```ts
+import { assertRegisteredHook } from "@unbrained/pm-cli/sdk/testing";
+
+const hook = assertRegisteredHook(activation.hooks, {
+  kind: "on_write",
+  extensionName: "my-ext",
+});
+// hook.run is the registered OnWriteHook handler
+```
+
+The bundled `pm-lifecycle-hooks` package is the first-party hooks exemplar. It
+declares only the `hooks` capability and registers a default-inert `afterCommand`
+hook, so package authors can copy a lifecycle pattern that does not write files,
+produce output, or alter command behavior.
+
+`afterCommand` receives the command outcome plus an optional `affected` array for
+item mutations. Each affected entry is a compact command context:
+`id`, `op`, `item_type`, `previous_status`, `status`, `changed_fields`, and
+partial `previous`/`current` front matter snapshots. Use this for
+transition-aware packages such as notifications; do not parse the untyped
+`result` payload when the transition fields are available.
+
+`onWrite` receives `{ path, scope, op }` for every observed write. When the write
+is tied to an item mutation, the context also includes `item_id`, `item_type`,
+`before`, `after`, and `changed_fields`, so sync packages can mirror the exact
+item change without reparsing files. Non-item writes omit those item fields.
+`changed_fields` lists mutated fields for updates and uses lifecycle sentinels
+for item lifecycle writes: `["imported"]` for package imports, `["restored"]`
+for restores, and `["deleted"]` for deletes.
+
 ## Custom Item Type
 
 ```ts
@@ -208,6 +406,70 @@ export default defineExtension({
 
 Manifest capability: `schema`.
 
+Declared item fields are first-class create/update inputs. Agents and importers can persist extension provenance without description markers:
+
+```bash
+pm create "Import issue" --type Incident --field service=api --field severity=critical
+pm update pm-1234 --field service=worker
+```
+
+`--field` accepts only fields declared by active `registerItemFields` registrations and coerces values using the declared field type.
+
+## Importer / Exporter
+
+`registerImporter(name, importer)` and `registerExporter(name, exporter)` register
+a data adapter and automatically create a `<name> import` / `<name> export` command
+path that invokes it. The handler receives an `ImportExportContext`
+(`registration`, `action`, `command`, `args`, `options`, `global`, `pm_root`).
+
+By default the auto-created command only has a handler. Pass an optional third
+`ImportExportRegistrationOptions` argument to make it a first-class command with a
+description, flags, intent, examples, failure hints, and positional arguments —
+surfaced in `--help` and runtime contracts exactly like `registerCommand`:
+
+```ts
+import { defineExtension } from "@unbrained/pm-cli/sdk";
+
+export default defineExtension({
+  activate(api) {
+    api.registerImporter(
+      "jsonl",
+      async (context) => {
+        // context.options.file, context.global, context.pm_root, ...
+        return { ok: true, imported: 0 };
+      },
+      {
+        action: "jsonl-import",
+        description: "Import JSONL records into pm items.",
+        intent: "ingest external task records",
+        examples: ["pm jsonl import --file source.jsonl"],
+        failure_hints: ["Verify the JSONL source path exists."],
+        flags: [
+          {
+            long: "--file",
+            value_name: "path",
+            value_type: "string",
+            description: "Path to the JSONL source file.",
+          },
+        ],
+      },
+    );
+
+    api.registerExporter("jsonl", async () => ({ ok: true }), {
+      description: "Export pm items to JSONL.",
+    });
+  },
+});
+```
+
+Manifest capability: `importers` (and `schema` when supplying `flags`). The two-argument
+form remains supported; supplying the options object never produces a command-handler
+collision because the definition and handler share the same command path and extension.
+
+The bundled `pm-beads` and `pm-todos` packages are first-party importer/exporter
+exemplars that use this registration path and expose runtime contracts for their
+generated commands.
+
 ## Search Provider
 
 ```ts
@@ -229,6 +491,15 @@ export default defineExtension({
 
 Manifest capability: `search`.
 
+Core search invokes the registered `query` when `settings.search.provider` matches
+the provider `name`. The bundled `pm-search-advanced` package ships a working
+first-party exemplar: `searchAdvancedLocalProvider()` registers a deterministic,
+dependency-free local lexical ranker named `search-advanced-local` (enable with
+`pm config set search.provider search-advanced-local`). Authors building
+embedding-backed providers (for example Ollama or a hosted model) implement
+`embed`/`embedBatch` on the same `SearchProviderDefinition` shape, and may also
+`registerVectorStoreAdapter` for a custom vector store.
+
 ## Robust Automation Pattern
 
 1. Read `PM_TOOL_ACTIONS` or `PM_TOOL_PARAMETERS_SCHEMA` for baseline static validation.
@@ -261,8 +532,9 @@ Treat `recovery.suggested_retry` as the first-choice deterministic replay comman
 
 - Keep handlers deterministic and JSON-like.
 - Return data, not pre-rendered terminal text, unless implementing a renderer or output service.
-- Keep service and preflight overrides narrow.
+- Keep service, renderer, and preflight overrides narrow. For `output_format`, return `context.payload`, `null`, or `undefined` for unrelated commands; for renderers, return `null` when the payload should fall back to native rendering.
 - Declare only capabilities in use.
+- Set `pm_min_version` when the package requires SDK or runtime behavior added after older pm releases.
 - Include examples and failure hints in dynamic commands.
 - Add `pm package doctor` diagnostics to testing instructions.
 

package/docs/TESTING.md

@@ -48,6 +48,23 @@ pm test-all --status in_progress --progress
 
 Do not link `pm test-all` itself as an item-level test command. It creates recursive orchestration.
 
+## Package Ecosystem Smoke
+
+After `pnpm build`, external package compatibility can be checked without
+touching the repository tracker:
+
+```bash
+pnpm smoke:external-packages -- --limit 10
+pnpm smoke:external-packages -- --package pm-changelog
+```
+
+The harness creates one temporary project per package, sets sandboxed `PM_PATH`
+and `PM_GLOBAL_PATH`, installs the package with `pm install npm:<name>
+--project`, runs `pm package doctor --project --detail deep --trace`, and probes
+runtime contracts with `pm contracts --runtime-only --availability-only`. Use
+`--discover-only` for the npm package list and `--keep-temp` only when debugging
+a failing package root.
+
 ## PM Context Modes
 
 Linked PM commands default to schema context: settings and extensions are seeded, but tracker item data stays isolated.

package/docs/examples/policy-restricted-extension/manifest.json

@@ -3,6 +3,7 @@
   "version": "0.1.0",
   "entry": "./index.js",
   "manifest_version": 2,
+  "pm_min_version": "2026.5.0",
   "trusted": true,
   "provenance": {
     "source": "docs/examples/policy-restricted-extension",

package/docs/examples/starter-extension/index.js

@@ -94,8 +94,16 @@ export default defineExtension({
     });
 
     // renderers
-    api.registerRenderer("json", (context) => stableJson(context.result));
+    api.registerRenderer("json", (context) => {
+      if (context.command !== "starter ping") {
+        return null;
+      }
+      return stableJson(context.result);
+    });
     api.registerRenderer("toon", (context) => {
+      if (context.command !== "starter ping") {
+        return null;
+      }
       const result = asRecord(context.result);
       const hooks = asRecord(result.hook_counts);
       return [

package/docs/examples/starter-extension/manifest.json

@@ -4,6 +4,7 @@
   "description": "SDK-first starter extension demonstrating all pm extension capabilities.",
   "entry": "./index.js",
   "manifest_version": 2,
+  "pm_min_version": "2026.5.0",
   "trusted": true,
   "provenance": {
     "source": "docs/examples/starter-extension",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.5.30",
+  "version": "2026.6.5",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "author": "unbrained",
@@ -33,6 +33,11 @@
       "import": "./dist/sdk/runtime.js",
       "default": "./dist/sdk/runtime.js"
     },
+    "./sdk/testing": {
+      "types": "./dist/sdk/testing.d.ts",
+      "import": "./dist/sdk/testing.js",
+      "default": "./dist/sdk/testing.js"
+    },
     "./cli": {
       "types": "./dist/cli/main.d.ts",
       "import": "./dist/cli/main.js",
@@ -70,6 +75,7 @@
     "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:external-packages": "node scripts/smoke-external-packages.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",
@@ -115,21 +121,20 @@
     }
   },
   "dependencies": {
-    "@sentry/node": "^10.55.0",
+    "@sentry/node": "^10.56.0",
     "@toon-format/toon": "^2.3.0",
     "commander": "^14.0.3",
     "fast-glob": "^3.3.3",
     "fast-json-patch": "^3.1.1"
   },
   "devDependencies": {
-    "@sentry/cli": "^3.4.3",
+    "@sentry/cli": "^3.5.0",
     "@types/node": "^25.9.1",
-    "@vitest/coverage-v8": "^4.1.7",
-    "c8": "^11.0.0",
+    "@vitest/coverage-v8": "^4.1.8",
     "esbuild": "0.28.0",
-    "tsx": "^4.22.3",
+    "tsx": "^4.22.4",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.7"
+    "vitest": "^4.1.8"
   },
   "pnpm": {
     "onlyBuiltDependencies": [

package/packages/pm-beads/extensions/beads/index.js

@@ -4,7 +4,7 @@ export const manifest = {
     version: "0.1.0",
     entry: "./index.js",
     priority: 0,
-    capabilities: ["commands", "schema"],
+    capabilities: ["commands", "schema", "importers"],
 };
 function asOptionalString(value) {
     return typeof value === "string" ? value : undefined;
@@ -28,8 +28,7 @@ async function runBeadsImportFromRuntime(options, global) {
     return runtime.runBeadsImport(options, global);
 }
 export function activate(api) {
-    api.registerCommand({
-        name: "beads import",
+    api.registerImporter("beads", async (context) => runBeadsImportFromRuntime(toBeadsImportOptions(context.options), context.global), {
         action: "beads-import",
         description: "Import Beads JSONL records into pm items.",
         flags: [
@@ -57,7 +56,6 @@ export function activate(api) {
                 description: "Preserve source IDs from Beads payload records when possible.",
             },
         ],
-        run: async (context) => runBeadsImportFromRuntime(toBeadsImportOptions(context.options), context.global),
     });
 }
 export default {

package/packages/pm-beads/extensions/beads/index.ts

@@ -1,4 +1,9 @@
-import type { CommandDefinition, ExtensionApi, GlobalOptions } from "../../../../src/sdk/index.js";
+import type {
+  ExtensionApi,
+  GlobalOptions,
+  ImportExportContext,
+  ImportExportRegistrationOptions,
+} from "../../../../src/sdk/index.js";
 import type { BeadsImportOptions, BeadsImportResult } from "./runtime.js";
 import { loadPackageRuntimeModule } from "./runtime-loader.js";
 
@@ -7,7 +12,7 @@ export const manifest = {
   version: "0.1.0",
   entry: "./index.js",
   priority: 0,
-  capabilities: ["commands", "schema"],
+  capabilities: ["commands", "schema", "importers"],
 };
 
 type RuntimeModule = {
@@ -40,37 +45,42 @@ async function runBeadsImportFromRuntime(options: BeadsImportOptions, global: Gl
 }
 
 export function activate(api: ExtensionApi): void {
-  api.registerCommand({
-    name: "beads import",
-    action: "beads-import",
-    description: "Import Beads JSONL records into pm items.",
-    flags: [
-      {
-        long: "--file",
-        value_name: "path",
-        value_type: "string",
-        description: "Path to the Beads JSONL source file.",
-      },
-      {
-        long: "--author",
-        value_name: "author",
-        value_type: "string",
-        description: "Override import mutation author.",
-      },
-      {
-        long: "--message",
-        value_name: "text",
-        value_type: "string",
-        description: "Override import history message.",
-      },
-      {
-        long: "--preserve-source-ids",
-        value_type: "boolean",
-        description: "Preserve source IDs from Beads payload records when possible.",
-      },
-    ],
-    run: async (context) => runBeadsImportFromRuntime(toBeadsImportOptions(context.options), context.global),
-  } satisfies CommandDefinition);
+  // First-party exemplar for the importers capability: registerImporter creates
+  // the `beads import` command path, and the options object keeps the command
+  // description + flags discoverable in help and runtime contracts.
+  api.registerImporter(
+    "beads",
+    async (context: ImportExportContext) => runBeadsImportFromRuntime(toBeadsImportOptions(context.options), context.global),
+    {
+      action: "beads-import",
+      description: "Import Beads JSONL records into pm items.",
+      flags: [
+        {
+          long: "--file",
+          value_name: "path",
+          value_type: "string",
+          description: "Path to the Beads JSONL source file.",
+        },
+        {
+          long: "--author",
+          value_name: "author",
+          value_type: "string",
+          description: "Override import mutation author.",
+        },
+        {
+          long: "--message",
+          value_name: "text",
+          value_type: "string",
+          description: "Override import history message.",
+        },
+        {
+          long: "--preserve-source-ids",
+          value_type: "boolean",
+          description: "Preserve source IDs from Beads payload records when possible.",
+        },
+      ],
+    } satisfies ImportExportRegistrationOptions,
+  );
 }
 
 export default {

package/packages/pm-beads/extensions/beads/manifest.json

@@ -3,5 +3,16 @@
   "version": "0.1.0",
   "entry": "./index.js",
   "priority": 0,
-  "capabilities": ["commands", "schema"]
+  "capabilities": [
+    "commands",
+    "schema",
+    "importers"
+  ],
+  "manifest_version": 1,
+  "pm_min_version": "2026.5.0",
+  "activation": {
+    "commands": [
+      "beads import"
+    ]
+  }
 }

package/packages/pm-calendar/README.md

@@ -13,3 +13,9 @@ pm cal --json --view agenda --include reminders,events
 The package owns presentation commands for deadline, reminder, and scheduled event views. Core pm still owns item metadata such as `deadline`, `reminders`, and `events`, plus create/update parsing for those fields.
 
 Runtime sources are authored in TypeScript and use only the public `@unbrained/pm-cli/sdk` surface.
+
+## Recurrence Notes
+
+Recurring event `recur_count` values are counted from the event series `start`, not from the query window. For example, a daily event starting April 1 with `recur_count=3` has its counted occurrences on April 1, 2, and 3; querying April 10 does not restart the count.
+
+`recur_exdates` exclude occurrences by instant. Equivalent timestamp spellings such as `2026-04-02T09:00:00Z`, `2026-04-02T09:00:00.000Z`, and `2026-04-02T09:00:00.000+00:00` match the same generated occurrence.

package/packages/pm-calendar/extensions/calendar/index.js

@@ -40,7 +40,12 @@ const calendarFlags = [
   { long: "--include", value_name: "value", value_type: "string", description: "Include sources: deadlines|reminders|events|scheduled|all." },
   { long: "--recurrence-lookahead-days", value_name: "n", value_type: "string", description: "Bound open-ended recurrence lookahead days." },
   { long: "--recurrence-lookback-days", value_name: "n", value_type: "string", description: "Bound open-ended recurrence lookback days." },
-  { long: "--occurrence-limit", value_name: "n", value_type: "string", description: "Cap generated occurrences per recurring event." },
+  {
+    long: "--occurrence-limit",
+    value_name: "n",
+    value_type: "string",
+    description: "Cap generated occurrences per recurring event; stored recur_count starts at series start, not the query window.",
+  },
   { long: "--limit", value_name: "n", value_type: "string", description: "Limit returned event count." },
   { long: "--format", value_name: "value", value_type: "string", description: "Calendar output override: markdown|toon|json." },
 ];

package/packages/pm-calendar/extensions/calendar/index.ts

@@ -47,7 +47,12 @@ const calendarFlags = [
   { long: "--include", value_name: "value", value_type: "string", description: "Include sources: deadlines|reminders|events|scheduled|all." },
   { long: "--recurrence-lookahead-days", value_name: "n", value_type: "string", description: "Bound open-ended recurrence lookahead days." },
   { long: "--recurrence-lookback-days", value_name: "n", value_type: "string", description: "Bound open-ended recurrence lookback days." },
-  { long: "--occurrence-limit", value_name: "n", value_type: "string", description: "Cap generated occurrences per recurring event." },
+  {
+    long: "--occurrence-limit",
+    value_name: "n",
+    value_type: "string",
+    description: "Cap generated occurrences per recurring event; stored recur_count starts at series start, not the query window.",
+  },
   { long: "--limit", value_name: "n", value_type: "string", description: "Limit returned event count." },
   { long: "--format", value_name: "value", value_type: "string", description: "Calendar output override: markdown|toon|json." },
 ] as const;

package/packages/pm-calendar/extensions/calendar/manifest.json

@@ -3,5 +3,10 @@
   "version": "0.1.0",
   "entry": "./index.js",
   "priority": 0,
-  "capabilities": ["commands", "schema", "services"]
+  "capabilities": ["commands", "schema", "services"],
+  "manifest_version": 1,
+  "pm_min_version": "2026.5.0",
+  "activation": {
+    "commands": ["cal", "calendar"]
+  }
 }

package/packages/pm-governance-audit/extensions/governance-audit/manifest.json

@@ -3,5 +3,10 @@
   "version": "0.1.0",
   "entry": "./index.js",
   "priority": 0,
-  "capabilities": ["commands", "schema"]
+  "capabilities": ["commands", "schema"],
+  "manifest_version": 1,
+  "pm_min_version": "2026.5.0",
+  "activation": {
+    "commands": ["comments-audit", "dedupe-audit", "normalize"]
+  }
 }