@unbrained/pm-cli 2026.5.31 → 2026.6.6

package/docs/ONBOARDING.md

@@ -0,0 +1,165 @@
+# Onboarding
+
+Use this guide to become productive in your first two hours without breaking release flow or tracker integrity.
+
+## Agent Quick Context
+
+- Bootstrap with `npm install -g .`, verify toolchain versions, then run `pnpm build`.
+- Use `pm context` + `pm search` before creating any new item.
+- Claim before substantial edits and link files/docs/tests as you go.
+- Run sandbox-safe tests before closing items.
+- Never hand-edit tracker records or generated changelog output.
+
+Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon), [pm-oh5h](../.agents/pm/tasks/pm-oh5h.toon), [pm-10ml](../.agents/pm/stories/pm-10ml.toon).
+
+## Prerequisites
+
+- Node.js 20 or newer
+- pnpm 10 or newer
+- Git + GitHub CLI (`gh`) authenticated for this repository
+
+## First-Time Bootstrap (Real Repository Work)
+
+Run from the repository root:
+
+```bash
+npm install -g .
+pm --version
+node -v
+pnpm -v
+pnpm build
+export PM_AUTHOR="<stable-agent-id>"
+```
+
+For real repository tracking, do not set `PM_PATH`.
+
+## First Read Path
+
+Use progressive disclosure:
+
+```bash
+pm context --limit 10
+pm search "<request keywords>" --limit 10
+pm list-open --limit 20
+pm list-in-progress --limit 20
+pm install guide-shell --project
+pm guide workflows
+```
+
+Then use:
+
+- [Agent Guide](AGENT_GUIDE.md)
+- [Command Reference](COMMANDS.md)
+- [Testing](TESTING.md)
+- [Releasing](RELEASING.md)
+
+## Safe Local Verification
+
+Use sandbox-safe wrappers for test execution:
+
+```bash
+node scripts/run-tests.mjs test
+node scripts/run-tests.mjs coverage
+```
+
+Standard local gate set:
+
+```bash
+pnpm build
+pnpm typecheck
+node scripts/run-tests.mjs coverage
+pnpm quality:docs-skills
+pm validate --check-resolution --check-history-drift
+```
+
+## Real Tracker Workflow (Canonical Loop)
+
+1) Orient and dedupe
+
+```bash
+pm context --limit 10
+pm search "<keywords>" --limit 10
+pm list-open --limit 20
+pm list-in-progress --limit 20
+```
+
+2) Claim and start
+
+```bash
+pm claim <id>
+pm update <id> --status in_progress --message "Start implementation"
+```
+
+3) Link execution context while editing
+
+```bash
+pm files <id> --add path=src/...,scope=project,note="implementation scope"
+pm docs <id> --add path=docs/...,scope=project,note="user-facing behavior"
+pm test <id> --add command="node scripts/run-tests.mjs test -- tests/unit/...",scope=project,timeout_seconds=240
+```
+
+4) Record progress
+
+```bash
+pm comments <id> "Progress update and rationale."
+pm notes <id> --add "Design tradeoff."
+pm learnings <id> --add "Durable lesson."
+```
+
+5) Verify, close, and release
+
+```bash
+pm test <id> --run --progress
+pm comments <id> "Evidence: linked tests and gates passed."
+pm close <id> "Acceptance criteria met; verification passed." --validate-close warn
+pm release <id>
+```
+
+## Release Overview
+
+- Daily release prep runs via `.github/workflows/auto-release.yml`.
+- Tag-triggered publish runs via `.github/workflows/release.yml`.
+- `CHANGELOG.md` is generated by `pm-changelog` and must stay package-generated.
+
+Local parity:
+
+```bash
+pnpm release:pipeline:dry-run
+pnpm release:pipeline
+```
+
+## Hard Never-Do List
+
+- Do not hand-edit `CHANGELOG.md` (use `pnpm changelog:pm` only).
+- Do not run manual `npm publish` for this project.
+- Do not set `PM_PATH` for real repository mutations.
+- Do not edit `.agents/pm/**` files directly; mutate through `pm` commands.
+- Do not bypass governance with destructive git commands unless explicitly approved.
+
+## Diagnostics and Recovery
+
+```bash
+pm health --check-only
+pm validate --check-resolution --check-history-drift
+pm normalize --dry-run --json
+pm package doctor --project --detail summary
+pm contracts --command <command> --flags-only --json
+```
+
+If history drift is reported:
+
+```bash
+pm history-repair <id> --dry-run
+pm history-repair <id>
+```
+
+If sensitive content is found in history:
+
+```bash
+pm history-redact <id> --literal "<secret>" --replacement "[redacted]" --dry-run
+pm history-redact <id> --literal "<secret>" --replacement "[redacted]"
+```
+
+## Private Operations Boundary
+
+Keep credentials, host-specific runbooks, internal topology, and raw private reliability logs out of tracked docs and package output. Keep those details in local, ignored operations notes.

package/docs/QUICKSTART.md

@@ -11,7 +11,7 @@ Use this page to get from a clean repository to a tracked, verified item.
 - Close only after evidence is recorded.
 - Use `pm install guide-shell --project` before `pm guide quickstart` or `pm guide workflows` when you need local docs routing.
 
-Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
+Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon).
 
 ## Install
 
@@ -48,6 +48,7 @@ pm package doctor --project --detail summary
 
 ```bash
 pm init
+pm init --defaults --type-preset agile
 pm health --check-only
 pm init --agent-guidance status
 pm init --agent-guidance add
@@ -57,6 +58,7 @@ pm init --agent-guidance add
 When AGENTS/CLAUDE guidance is missing, default `pm init` uses `--agent-guidance ask`: it prompts only in TTY, never blocks non-interactive runs, and records declined prompts.
 Use `pm init --agent-guidance add` to write the compact workflow block later, or `pm init --agent-guidance status` to inspect guidance state without changing files.
 Use `pm init --defaults --with-packages` when agents should get bundled commands such as calendar, templates, advanced search, and governance helpers in one non-interactive setup step.
+Use `pm init --type-preset agile|ops|research` when a fresh project should start with domain item types such as Story/Spike, Incident/Runbook, or Experiment/Hypothesis.
 
 ## Create Your First Item
 

package/docs/README.md

@@ -20,15 +20,18 @@ pm guide release --json
 | Reader | First page | Then read |
 |--------|------------|-----------|
 | New user | [Quickstart](QUICKSTART.md) | [Command Reference](COMMANDS.md) |
+| New maintainer | [Onboarding](ONBOARDING.md) | [Agent Guide](AGENT_GUIDE.md), [Testing](TESTING.md), [Releasing](RELEASING.md) |
 | Coding agent | [Agent Guide](AGENT_GUIDE.md) | [Configuration](CONFIGURATION.md), then command help |
 | Maintainer | [Contributing](../CONTRIBUTING.md) | [Testing](TESTING.md), [Releasing](RELEASING.md), [Architecture](ARCHITECTURE.md) |
 | Package author | [Packages and Extensions](EXTENSIONS.md) | [SDK](SDK.md), [starter extension](examples/starter-extension/README.md) |
 | Codex user | [Codex Plugin](CODEX_PLUGIN.md) | [Agent Guide](AGENT_GUIDE.md), then [Command Reference](COMMANDS.md) |
+| Claude Code user | [Claude Code Plugin](CLAUDE_CODE_PLUGIN.md) | [Agent Guide](AGENT_GUIDE.md), then [Command Reference](COMMANDS.md) |
 | Machine client | `pm contracts --json` | [Command Reference](COMMANDS.md#machine-contracts), optionally `pm install guide-shell --project && pm guide commands` |
 
 ## Documentation Map
 
 - [Quickstart](QUICKSTART.md) - install, initialize, create, claim, link, test, close.
+- [Onboarding](ONBOARDING.md) - first-two-hours maintainer and contributor setup.
 - [Agent Guide](AGENT_GUIDE.md) - canonical agent loop, tracker linking, and token-minimal command choices.
 - [Command Reference](COMMANDS.md) - command families with examples and when to use each family.
 - [Configuration](CONFIGURATION.md) - settings, storage formats, output, search, validation, and environment variables.
@@ -37,6 +40,7 @@ pm guide release --json
 - [Packages and Extensions](EXTENSIONS.md) - package install workflows, runtime extension lifecycle, and API reference.
 - [SDK](SDK.md) - public import surfaces and typed authoring examples.
 - [Codex Plugin](CODEX_PLUGIN.md) - native MCP plugin install, tools, skills, and safety notes.
+- [Claude Code Plugin](CLAUDE_CODE_PLUGIN.md) - native Claude Code plugin architecture and install flow.
 - [Releasing](RELEASING.md) - maintainer release checklist and failure handling.
 - [starter extension](examples/starter-extension/README.md) - compact extension scaffold reference.
 
@@ -71,11 +75,15 @@ Community files:
 
 ## Tracker References
 
-This documentation structure is tracked through:
+Current documentation structure work is tracked through:
 
-- [pm-3042](../.agents/pm/epics/pm-3042.toon)
-- [pm-r9gu](../.agents/pm/features/pm-r9gu.toon)
-- [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon)
+- [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon)
+
+Legacy documentation baseline references (closed):
+
+- [pm-3042](../.agents/pm/epics/pm-3042.toon) (closed)
+- [pm-r9gu](../.agents/pm/features/pm-r9gu.toon) (closed)
+- [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon) (closed)
 
 When changing docs, link files back to the active item:
 

package/docs/RELEASING.md

@@ -12,7 +12,7 @@ For local progressive-disclosure routing, install `guide-shell` with `pm install
 - Run local parity gates before pushing release tags.
 - Use `pm guide release --json` for machine-readable release docs routing after `guide-shell` is installed.
 
-Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
+Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon).
 
 ## Version Policy
 
@@ -36,7 +36,7 @@ pnpm version:check
 ## One-Time Setup
 
 - Use npm provenance publishing for `.github/workflows/release.yml` so GitHub-hosted release jobs publish signed packages. Keep `id-token: write`, Node 24 or newer, npm 11.5.1 or newer, `NODE_AUTH_TOKEN` from the `release` environment `NPM_TOKEN` secret, and `npm publish --access public --provenance`. The token must authenticate as a maintainer with read-write access to `@unbrained/pm-cli`.
-- Add `SENTRY_AUTH_TOKEN` as an optional GitHub Environment or repository secret when Sentry release creation and sourcemap upload should run. Add `SENTRY_PERSONAL_ADMIN_TOKEN` only when the GitHub-hosted Sentry issue-threshold gate should read unresolved issues; CI-scoped release tokens may not have issue-read scope. The release workflow skips Sentry upload cleanly when `SENTRY_AUTH_TOKEN` is absent and skips the GitHub-hosted issue-threshold gate when `SENTRY_PERSONAL_ADMIN_TOKEN` is absent; local maintainers should still run the token-backed Sentry gate before release.
+- Add `SENTRY_AUTH_TOKEN` as an optional GitHub Environment or repository secret when Sentry release creation and sourcemap upload should run. Add `SENTRY_PERSONAL_ADMIN_TOKEN` for the GitHub-hosted Sentry issue-threshold gate; CI-scoped release tokens may not have issue-read scope. The release workflow skips Sentry upload cleanly when `SENTRY_AUTH_TOKEN` is absent, but fails the reliability threshold gate when `SENTRY_PERSONAL_ADMIN_TOKEN` is absent; local maintainers should still run the token-backed Sentry gate before release.
 - 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`.
@@ -54,7 +54,7 @@ Policy:
 - same-day follow-up release (`YYYY.M.D-N`) is manual-only via `allow_same_day_release=true`
 - release preparation must pass all quality and compatibility gates before commit+tag push
 - `CHANGELOG.md` is generated by the latest npm `pm-changelog` package (`pm install npm:pm-changelog --project`, then `pm changelog generate --mode replace --all-release-tags`) from closed tracker items across git release tag windows and checked in CI; do not edit it by hand
-- external Sentry checks run when a Sentry token is configured; local maintainers should run private reliability checks separately and keep raw operational details in ignored local notes
+- release reliability gating requires `SENTRY_PERSONAL_ADMIN_TOKEN` for issue-threshold checks; Auto Release fails before creating the version commit/tag when the token is missing and `push=true`, while sourcemap upload remains optional through `SENTRY_AUTH_TOKEN`
 - after creating and pushing a new tag, auto-release dispatches `.github/workflows/release.yml` with that tag and waits for the publish workflow to finish, because GitHub does not start normal push/tag workflows from `GITHUB_TOKEN` pushes
 
 Pipeline entrypoint:
@@ -74,6 +74,41 @@ The pipeline performs:
 
 The generated changelog includes clickable pm item links to the tracked `.toon` files. Missing release evidence should be fixed in pm item history, not by hand-editing `CHANGELOG.md`.
 
+## Changelog Classification (Contributor-Facing)
+
+`pnpm changelog:pm` routes closed pm items into keep-a-changelog sections using `pm-changelog` classification logic. Use explicit type/tag metadata when you want deterministic section routing.
+
+Signal tiers:
+
+- **Strong signals**: item `type` + `tags`
+- **Weak signal**: item `title` (after stripping CLI-flag-like tokens such as `--add`)
+
+Category precedence (first matching bucket wins):
+
+| Priority | Category | Trigger terms (from strong + weak signals unless noted) |
+|---|---|---|
+| 1 | `Security` | `security`, `cve`, `vulnerability` |
+| 2 | `Deprecated` | `deprecated`, `deprecation` |
+| 3 | `Removed` | `removed`, `remove`, `deleted`, `delete` |
+| 4 | `Fixed` | `fix`, `fixed`, `bug`, `bugfix`, `hotfix`, `regression` |
+| 5 | `Added` | `feature`, `feat`, `added`, `add`, `new` |
+| 6 | `Changed` | strong-signal `change`, `changed`, `refactor`, `update`, `updated`, `improve`; for non-bug-like types only, title fallback is also used |
+| 7 | `Other` | no classifier match |
+
+Bug-like default:
+
+- Items with type `Issue`, `Bug`, `Bugfix`, or `Defect` default to `Fixed` unless a higher-priority category already matched.
+- This bug-like default runs before title-only `Changed` fallback to avoid misrouting command-name issue titles (for example "`pm update ...`" issue reports).
+
+Practical examples:
+
+- `Issue` + title `pm update --add-tags fails` -> `Fixed`
+- `Task` + tag `refactor` -> `Changed`
+- `Feature` + tag `security` -> `Security`
+- `Issue` + tag `feature` -> `Added` (explicit stronger signal beats default)
+
+If a changelog routing rule appears incorrect, fix classifier behavior in the `pm-changelog` package/repo and then consume the updated package here. Do not patch generator internals in this repository.
+
 ## Local Release Parity Checklist
 
 1. Confirm or compute the version.

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.