@unbrained/pm-cli 2026.5.30 → 2026.6.5

package/docs/COMMANDS.md

@@ -30,7 +30,7 @@ Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
 | Links | `files`, `docs`, `test`, `deps` | connect items to artifacts, tests, and relationships |
 | Verification | `test`, `test-all`, `test-runs`, `validate`, `gc` | run linked tests and repository checks |
 | History | `history`, `history-redact`, `history-repair`, `activity`, `restore`, `stats` | inspect, redact, re-anchor, and recover item state |
-| Schema | `schema add-type` | register config-driven custom item types into `.agents/pm/schema/types.json` |
+| Schema | `schema add-type` / `remove-type` / `add-status` / `remove-status` | manage config-driven custom item types (`.agents/pm/schema/types.json`) and statuses (`.agents/pm/schema/statuses.json`) |
 | Calendar | `calendar`, `cal` | project deadlines, reminders, and events |
 | Packages | `install`, `upgrade`, `package`, `packages`, `extension`, package/extension command groups | install, upgrade, manage, and run package-backed extension commands |
 | Machines | `contracts`, `help`, optional `guide`/`completion` | command contracts plus optional guide-shell docs routing and shell helpers |
@@ -86,6 +86,47 @@ Use `context` first for a compact active-work snapshot. Use `search` when the re
 pm list-all --sort updated --order desc
 ```
 
+### Incremental "what changed since" filters
+
+Every `list*` command accepts `--updated-after`/`--updated-before`/`--created-after`/`--created-before`, and `pm search` accepts `--status` for parity with `list`. These keep a long-running agent's context focused on the slice it cares about instead of re-scanning the whole tracker:
+
+```bash
+# Items touched since my last context window (feed back the previous run's `now`)
+pm list-all --updated-after 2026-06-04T15:18:32Z --brief
+
+# Relative offsets are SIGNED: -2h/-7d reach into the past, +1d into the future.
+# Units are h/d/w/m (m = months — there is no minutes unit).
+pm list-open --updated-after=-2h --brief
+pm list-all --created-after=-7d --status open
+
+# Search scoped to open work only (drops closed-history noise); statuses are
+# open/closed/canceled aliases or configured ids, comma-separated, with a
+# did-you-mean hint on typos.
+pm search "reminder validation" --status open --limit 10
+```
+
+Each filter echoes its raw input back in the result `filters` block so an agent can confirm exactly what window it queried.
+
+## Bulk Operations
+
+`update-many` and `close-many` apply one change across a matched set with a dry-run preview and a rollback checkpoint. Both share the `--filter-*` scoping family (`--filter-status/-type/-tag/-priority/-sprint/-release/-parent/-assignee/-deadline-before|after/-updated-after|before/-created-after|before`) plus `--ids` for an explicit comma-separated allowlist intersected with the other filters.
+
+```bash
+# Bulk metadata update by explicit id allowlist (compose with search --json | jq)
+pm update-many --ids pm-a,pm-b,pm-c --priority 1 --dry-run
+pm update-many --filter-tag wave:7 --reviewer maintainer-review
+
+# Audited bulk close: routes EACH match through full `pm close` semantics
+# (close validation, active-child orphan checks, blocked-edge cleanup) — unlike
+# `update-many --status closed`, which bypasses them. A shared --reason is required
+# and at least one filter is required so it never matches every item.
+pm close-many --filter-sprint S-12 --reason "Sprint S-12 acceptance criteria met" --dry-run
+pm close-many --filter-sprint S-12 --reason "Sprint S-12 acceptance criteria met"
+pm close-many --rollback close-many-20260604-abc123   # restore the batch
+```
+
+`close-many` skips already-terminal matches by default (pass `--force` to re-close), reports a per-item plan (`close`/`skip`, plus `active_child_ids` for parents that would be orphaned) under `--dry-run`, and writes a checkpoint by default (`--no-checkpoint` to disable). Checkpoints for both commands live under `.agents/pm/checkpoints/<command>/` and are restored with `--rollback <checkpoint-id>`.
+
 When a flag is rejected with `Unknown option`, the error guidance now suggests the nearest supported flag (including abbreviations like `--desc` → `--description`) and notes when the flag is valid on a different command (for example `--type` on `test-all` points to `create`/`list`).
 
 ## Create and Update
@@ -98,7 +139,10 @@ pm create "Fix login bug" --type Issue --priority high
 ```
 
 `pm create` defaults `--type` to `settings.governance.create_default_type` (falling back to `Task`).
+Set it with `pm config project set governance-create-default-type <Type>` (must resolve to a known item type).
 Pass `--create-mode strict` to require an explicit `--type` flag for governance-controlled flows.
+`pm update --status` can be constrained per item type via `schema.type_workflows` plus
+`pm config project set governance-workflow-enforcement <off|warn|strict>` (see CONFIGURATION.md → Per-Type Workflows).
 Priority accepts either `0..4` or the equivalent names `critical`, `high`, `medium`, `low`, and `minimal`.
 
 Minimal progressive create with explicit fields:
@@ -256,12 +300,28 @@ For `--include events` without explicit `--to`, `--recurrence-lookahead-days`, o
 ```bash
 pm validate --check-resolution --check-history-drift
 pm validate --check-files --scan-mode tracked-all
+pm validate --check-resolution --fix-hints --json
 pm normalize --dry-run --json
 pm gc --dry-run
 ```
 
 Use dry-run modes before broad lifecycle or cleanup changes.
 
+`--fix-hints` is a read-only flag: each failing check gains `details.fix_hints`, an array of `pm` command templates derived from the warning codes it raised (for example `pm history-repair <id>` for history drift, or `pm update <id> --reviewer "<name>"` for a missing reviewer). Generic hints may contain `<id>`/`<field>`/`<path>` placeholders the agent substitutes from the check's detail rows; the resolution check aliases concrete per-row commands and marks `fix_hints_truncated` when the list is summarized. It never mutates items. The mapping comes from the shared remediation registry that also backs `pm health --json` (see Self-Repair Remediation below), so agents gating on `pm validate` can auto-repair findings without hardcoding warning-code-to-command lookups.
+
+### Self-Repair Remediation
+
+`pm health --json` annotates every non-extension check whose warnings have a known code with `details.remediation_map`, an object mapping each warning-code prefix to the executable `pm` command that fixes it:
+
+```jsonc
+// history_drift check
+"remediation_map": { "history_drift_missing_stream": "pm history-repair <id>" }
+// vectorization check
+"remediation_map": { "vectorization_stale_items_remaining": "pm health --refresh-vectors" }
+```
+
+`remediation_map` appears in default and `--full` output and is omitted in `--brief`/`--summary` to stay token-efficient. Extension checks keep their existing richer `details.triage.remediation` instead.
+
 ## History and Recovery
 
 ```bash
@@ -282,19 +342,39 @@ History is append-only. Restore appends a new restore event instead of rewriting
 
 ## Custom Item Types
 
-`pm schema add-type` registers a config-driven custom item type so agents can use `pm create <Type> "..."` for project-specific work categories without editing settings by hand. The definition is merged into the runtime type registry from `.agents/pm/schema/types.json` (shape: `{ "definitions": [ItemTypeDefinition...] }`).
+Tracker references: [pm-qq69](../.agents/pm/features/pm-qq69.toon), [pm-1lkm](../.agents/pm/features/pm-1lkm.toon).
+
+`pm schema` inspects and manages the runtime item-type registry. `list` and `show` include built-in, custom, and extension-provided types so agents can confirm project context before creating work. `add-type` registers a config-driven custom item type so agents can use `pm create <Type> "..."` for project-specific work categories without editing settings by hand. Custom definitions are merged from `.agents/pm/schema/types.json` (shape: `{ "definitions": [ItemTypeDefinition...] }`). Custom statuses are managed with `add-status`/`remove-status` and persist in `.agents/pm/schema/statuses.json` (shape: `{ "statuses": [RuntimeStatusDefinition...] }`).
 
 ```bash
+pm schema list
+pm schema show Task
 pm schema add-type Spike --description "Time-boxed investigation" --default-status open
 pm schema add-type Spike --alias spike --alias research --folder spikes
+pm schema remove-type Spike
+pm schema add-status review --role active --alias in_review --description "Awaiting review" --order 25
+pm schema remove-status review
 pm create Spike "Investigate retry backoff"
 ```
 
-- The command is an idempotent UPSERT keyed on the type name (case-insensitive); re-running it merges aliases and overrides supplied fields while preserving everything else.
-- Built-in types (Chore, Decision, Epic, Event, Feature, Issue, Meeting, Milestone, Plan, Reminder, Task) are reserved and cannot be redefined.
-- Flags: `--description <text>`, `--default-status <status>`, `--folder <dir>`, `--alias <name>` (repeatable), plus `--author`/`--force` governance flags. Add `--json` for the machine envelope.
+- `pm schema list --json` returns `{ builtin, custom, extension, counts, statuses: { builtin, custom, counts } }` for compact machine parsing. Each status entry includes `id`, `source` (`builtin`/`custom`), `roles`, and `aliases`.
+- `pm schema show <Type> --json` returns the resolved definition, including folder, aliases, default status, required create options, type options, command-option policies, and extension provenance when applicable.
+- `add-type` is an idempotent UPSERT keyed on the type name (case-insensitive); re-running it merges aliases and overrides supplied fields while preserving everything else.
+- `remove-type <Name>` removes a custom type definition (case-insensitive). Built-in types are refused. It WARNS (non-blocking) with `items_using_type:<N>` when items of that type still exist, then removes the definition.
+- `add-status <id>` writes a custom lifecycle status (idempotent UPSERT keyed on the normalized id; re-adding sets `replaced: true`). Roles are validated against the runtime status roles: `draft`, `active`, `blocked`, `terminal`, `terminal_done`, `terminal_canceled`, `default_open`, `default_close`, `default_cancel`.
+- `remove-status <id>` removes a custom status. The five built-in default statuses (`open`, `in_progress`, `blocked`, `closed`, `canceled`, plus `draft`) are refused. It WARNS (non-blocking) with `items_using_status:<N>` when items currently use that status.
+- Built-in types (Chore, Decision, Epic, Event, Feature, Issue, Meeting, Milestone, Plan, Reminder, Task) are reserved and cannot be redefined or removed.
+- Flags: `--description <text>`, `--default-status <status>`, `--folder <dir>`, `--alias <name>` (repeatable), `--role <value>` (repeatable; add-status), `--order <n>` (add-status), plus `--author`/`--force` governance flags. Add `--json` for the machine envelope.
 - When `pm create`/`pm update` reject an unknown type, the error now points back here: `To register a custom type, run: pm schema add-type "X" (writes .agents/pm/schema/types.json).`
 
+`pm init --type-preset agile|ops|research` registers common domain types during initialization:
+
+- `agile`: Story, Spike
+- `ops`: Incident, Runbook
+- `research`: Experiment, Hypothesis
+
+The option composes with `--defaults`, `--preset`, `--author`, `--agent-guidance`, and `--with-packages`; re-running it is idempotent and reports `registered_type_preset` in JSON output.
+
 ## Plan Workflow
 
 `pm plan` is the agent-optimized planning loop built on the first-class `Plan` item type. Plans persist ordered steps, evidence, decisions, discoveries, validation, and resume context. Each mutation appends a history entry; full hash-chain replay is preserved.

package/docs/CONFIGURATION.md

@@ -9,7 +9,7 @@
 - Use `--json` only when strict parsing is needed.
 - Use `pm contracts` for current command/schema metadata.
 
-Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
+Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon), [pm-1lkm](../.agents/pm/features/pm-1lkm.toon), [pm-qq69](../.agents/pm/features/pm-qq69.toon).
 
 ## Configuration Commands
 
@@ -49,6 +49,8 @@ Precedence:
 4. global settings
 5. built-in defaults
 
+When `settings.json` cannot be loaded, `pm` falls back to built-in defaults and prints a one-time `settings_read_invalid_json` or `settings_read_invalid_schema` warning to stderr (stdout output is unchanged); run `pm health` for remediation.
+
 ## Common Settings
 
 | Setting | Purpose |
@@ -63,9 +65,13 @@ Precedence:
 | `validation.sprint_release_format` | `warn` or `strict_error` |
 | `validation.parent_reference` | `warn` or `strict_error` |
 | `item_types.definitions[]` | custom item types and type options |
-| `governance.create_default_type` | default `--type` used by the `pm create "title"` positional shortcut (defaults to `Task`) |
+| `governance.create_default_type` | default `--type` used by `pm create "title"` when `--type` is omitted (defaults to `Task`); must resolve to a known item type |
+| `governance.workflow_enforcement` | per-type transition enforcement mode for `pm update --status` (`off` default, `warn`, or `strict`) |
+| `schema.type_workflows[]` | per-type allowed status transitions (see Per-Type Workflows below) |
 | `search.*` | search mode, scoring, providers, embedding timeout, and vector settings |
 
+Runtime item types are context primitives. Use `pm schema list` to inspect the merged registry and `pm schema show <Type>` to inspect one type's folder, aliases, defaults, required options, and extension provenance. `pm init --type-preset agile|ops|research` writes reusable domain types into `.agents/pm/schema/types.json`; this is equivalent to persisted project schema, not an extension-only runtime overlay.
+
 ## Environment Variables
 
 | Variable | Use |
@@ -100,6 +106,7 @@ Use JSON for strict machine parsing:
 
 ```bash
 pm get <id> --json
+pm get <id> --full --json
 pm contracts --json
 ```
 
@@ -122,6 +129,46 @@ pm validate --check-files --scan-mode tracked-all
 pm health --check-only --summary --json
 ```
 
+## Per-Type Workflows
+
+Restrict which status transitions are allowed for a given item type. Rules live in
+`schema/workflows.json` alongside the lifecycle `workflow` block, and enforcement is
+gated by `governance.workflow_enforcement` (default `off`, so existing projects are
+unaffected until you opt in).
+
+```jsonc
+// .agents/pm/schema/workflows.json
+{
+  "workflow": { "open_status": "open", "close_status": "closed", "canceled_status": "canceled" },
+  "type_workflows": [
+    {
+      "type": "Story",
+      "allowed_transitions": [
+        ["open", "in_progress"],
+        ["in_progress", "closed"]
+      ]
+    }
+  ]
+}
+```
+
+```bash
+pm config project set governance-workflow-enforcement strict   # off | warn | strict
+pm config project set governance-create-default-type Issue     # default create type
+```
+
+Semantics:
+
+- A type with **no** `type_workflows` entry is unrestricted (every transition allowed).
+- A type **with** an entry allows only the listed `[from, to]` pairs. `from`/`to` are
+  matched case-insensitively and resolved through the status registry's aliases.
+- A same-status no-op (`from === to`) is always allowed.
+- `workflow_enforcement: strict` rejects a disallowed transition (including transitions
+  toward the close status, gated before close-routing) with the allowed-transition hint.
+- `workflow_enforcement: warn` still applies the change but adds a
+  `workflow_transition_not_allowed` warning to the update result.
+- `workflow_enforcement: off` (default) ignores all `type_workflows` rules.
+
 ## Search Configuration
 
 Keyword search is always available:

package/docs/EXTENSIONS.md

@@ -45,6 +45,32 @@ pm install governance-audit --project
 
 `pm install '*'`, `pm install all`, and shell-expanded `pm install *` are normalized to the same bundled install-all request. First-party package aliases come from each package manifest, with a fallback derived from the `packages/pm-*` directory name.
 
+External registry packages are installed by exact package name:
+
+```bash
+npm search "pm-cli pm-package"
+pm install npm:pm-changelog --project
+pm install npm:pm-github --project
+pm package doctor --project --detail deep --trace
+```
+
+For ecosystem maintenance, use the reusable external package smoke harness after
+building `dist/`:
+
+```bash
+pnpm build
+pnpm smoke:external-packages -- --limit 10
+pnpm smoke:external-packages -- --package pm-changelog
+```
+
+The harness discovers npm packages with the `keywords:pm-package` query unless
+explicit packages are provided. Each package is installed in a temporary project
+with isolated `PM_PATH` and `PM_GLOBAL_PATH`, then checked with `pm package
+doctor --project --detail deep --trace` and runtime availability contracts. The
+JSON output is compact enough for agents to attach as tracker evidence.
+
+Prefer package-specific docs before invoking commands that require service credentials, such as GitHub, Jira, Linear, or Slack sync packages.
+
 ## Package Manifest
 
 Package roots declare resources in `package.json` under `pm`:
@@ -55,7 +81,7 @@ Package roots declare resources in `package.json` under `pm`:
   "keywords": ["pm-package"],
   "pm": {
     "aliases": ["my-workflow"],
-    "extensions": ["extensions/my-extension"],
+    "extensions": ["."],
     "docs": ["README.md"],
     "examples": ["examples/basic.md"],
     "catalog": {
@@ -81,6 +107,8 @@ Current resource kinds are:
 
 Installation activates `pm.extensions`. `pm.docs` and `pm.examples` are catalog metadata. Agent-specific assets such as prompts, skills, or MCP servers should live in agent adapter packages, not in the core `pm` package contract.
 
+`pm package init` emits a root extension (`"extensions": ["."]`) so local package installs can activate without dependency bootstrapping. Larger packages may point at nested extension directories after declaring runtime dependencies and validating with `pm package doctor`.
+
 When no package manifest is present, `pm` discovers conventional extension directories:
 
 - `.agents/pm/extensions/`
@@ -99,17 +127,37 @@ Runtime path overrides:
 - `PM_PATH`: project tracker root
 - `PM_GLOBAL_PATH`: global profile root
 
-A minimal extension has a `manifest.json` and an entrypoint:
+A minimal standalone extension has a `manifest.json` and an import-free entrypoint. Standalone entries are loaded by file URL from the extension directory, so they should not import `@unbrained/pm-cli` unless the extension is installed as a package with its own dependencies.
 
 ```json
 {
   "name": "hello",
   "version": "0.1.0",
   "entry": "./index.js",
+  "manifest_version": 1,
+  "pm_min_version": "2026.5.0",
+  "pm_max_version": "2027.0.0",
   "capabilities": ["commands"]
 }
 ```
 
+```js
+/** @param {import("@unbrained/pm-cli/sdk").ExtensionApi} api */
+export function activate(api) {
+  api.registerCommand({
+    name: "hello",
+    description: "Print a deterministic hello payload.",
+    intent: "verify extension command activation",
+    examples: ["pm hello"],
+    run() {
+      return { ok: true, message: "hello" };
+    },
+  });
+}
+```
+
+Package-backed extensions can use the SDK helper after declaring `@unbrained/pm-cli` in `package.json` and installing dependencies. Use this shape for packages published to npm or installed from a package root:
+
 ```js
 import { defineExtension } from "@unbrained/pm-cli/sdk";
 
@@ -138,6 +186,15 @@ Runnable manifest examples are the source of truth:
 Rules:
 
 - `entry` must resolve inside the extension directory.
+- `manifest_version` is an optional integer identifying the manifest schema generation. Runtime contracts currently support manifest versions `1` and `2`, and first-party runnable examples use `2`. First-party packages declare it; the manifest governance test requires it on every first-party package.
+- `pm_min_version` is an inclusive minimum pm CLI version. If the running CLI is older, discovery emits `extension_pm_min_version_unmet:<layer>:<name>:required=<version>:current=<version>` and skips the extension before import.
+- `pm_max_version` is an optional inclusive maximum pm CLI version (the upper compatibility bound). If the running CLI is newer than this value, discovery emits `extension_pm_max_version_exceeded:<layer>:<name>:allowed=<version>:current=<version>` and skips the extension before import. Use it to stop a CLI major release from loading a stale package that would crash at activation.
+- Both bounds share the same blocking semantics and warning-code shapes:
+  - `*_invalid` (`required=`/`allowed=` only): the declared version is unparseable; the extension is **blocked**.
+  - `*_unchecked` (`...:current=unknown` or an uncomparable current version): the bound could not be compared against the running CLI; the extension is **allowed** but a warning is recorded.
+  - `extension_pm_min_version_unmet` / `extension_pm_max_version_exceeded`: the running CLI is outside the declared bound; the extension is **blocked**.
+- An empty-string or non-string `pm_min_version`/`pm_max_version` makes the whole manifest malformed (`extension_manifest_invalid:<layer>:<name>`). Omit the field instead of leaving it blank.
+- Optional `engines.pm` and `engines.node` metadata is accepted for tooling, but `pm_min_version`/`pm_max_version` are the loader-enforced compatibility fields.
 - Declare only capabilities the extension actually uses.
 - Unknown capabilities emit deterministic warnings.
 - Legacy aliases such as `migration` and `validation` are normalized to `schema` with warnings.
@@ -154,6 +211,12 @@ Supported capabilities:
 - `importers`
 - `search`
 
+First-party package exemplars:
+
+- `pm-beads` and `pm-todos`: importer/exporter registration and generated command contracts.
+- `pm-lifecycle-hooks`: default-inert lifecycle hook registration.
+- `pm-search-advanced`: deterministic local search provider registration.
+
 ## Governance Policy
 
 Governance policy is configured in `settings.json` under `extensions.policy`. The runnable [policy-restricted example](examples/policy-restricted-extension/README.md) owns the complete policy snippet and expected behavior.
@@ -192,6 +255,20 @@ Surface tokens include:
 
 Use `pm package doctor --project --detail deep --trace` to inspect active policy state and warning codes.
 
+## Registration Collisions
+
+Some extension surfaces are intentionally single-winner: command overrides, parser overrides, preflight overrides, and format renderers. If multiple packages register the same single-winner surface, the later-loaded registration wins and `pm package doctor` / `pm health` report deterministic `extension_*_collision` warnings.
+
+Use the warning details to resolve the overlap:
+
+```bash
+pm package doctor --project --detail deep --trace
+pm package deactivate <conflicting-package> --project
+pm package doctor --project --strict-exit
+```
+
+For production stacks, keep broad demo/starter packages separate from packages that own real workflow behavior, or constrain registration surfaces through `extensions.policy.extension_overrides`.
+
 ## Runtime APIs
 
 Use the public SDK barrel. Do not deep-import from `src/core` or `dist/core`.
@@ -204,16 +281,31 @@ Common APIs:
 
 - `api.registerCommand(definition)` adds package-owned commands.
 - `api.registerFlags(command, flags)` adds runtime command flags.
-- `api.registerItemFields(fields)` adds custom metadata fields.
+- `api.registerItemFields(fields)` adds custom metadata fields. Agents can set declared fields with repeatable `pm create --field name=value` and `pm update <id> --field name=value`; undeclared names are rejected.
 - `api.registerItemTypes(types)` adds custom item types.
 - `api.registerMigration(definition)` adds schema migrations.
-- `api.registerOutputService(definition)` customizes output rendering.
-- `api.registerRenderer(definition)` adds format-specific renderers.
-- `api.registerHook(name, handler)` adds lifecycle hooks.
+- `api.registerService("output_format", handler)` customizes output formatting through the service override API. Return `context.payload`, `null`, or `undefined` for commands the extension does not own.
+- `api.registerRenderer("toon" | "json", renderer)` adds format-specific renderers. Return `null` for unrelated payloads so pm falls back to native rendering.
+- `api.hooks.beforeCommand(handler)`, `api.hooks.afterCommand(handler)`, `api.hooks.onWrite(handler)`, `api.hooks.onRead(handler)`, and `api.hooks.onIndex(handler)` add lifecycle hooks.
+  `afterCommand` receives command outcome fields plus optional compact `affected`
+  item entries for mutations, including `previous_status`, `status`,
+  `changed_fields`, and partial `previous`/`current` front matter snapshots.
+  `onWrite` always includes `path`, `scope`, and `op`; item mutations also add optional `item_id`, `item_type`, `before`, `after`, and `changed_fields`.
+
+The bundled `pm-lifecycle-hooks` package is the hook exemplar: it declares only
+`hooks` and registers a default-inert `afterCommand` hook so authors can copy a
+safe lifecycle pattern without changing command output.
+
+If a package calls a `register*` API without declaring the required manifest
+capability, `pm package doctor --project --detail deep --trace` reports
+`extension_capability_missing:<name>:<capability>` and shows the exact capability
+to add before publishing.
 
 Inline command flags require both `commands` and `schema` capabilities. Runtime schema changes should be verified with:
 
 ```bash
+pm schema list
+pm schema show <Type>
 pm contracts --runtime-only --schema-only --json
 pm contracts --command <command> --flags-only --json
 ```
@@ -296,6 +388,26 @@ For package-owned commands, install the package before assuming the command is a
 
 If a package-owned command is invoked before installation, usage guidance includes the recovery install command when `pm` can map the command to a bundled package.
 
+## Package Authoring Notes
+
+Third-party packages should import only stable public SDK subpaths:
+
+```js
+import { defineExtension, createPmCliExpectedError } from "@unbrained/pm-cli/sdk";
+import { activateExtensionForTest, assertRegisteredCommandContract } from "@unbrained/pm-cli/sdk/testing";
+```
+
+Use `createPmCliExpectedError(message, { exitCode, context })` for expected user/action failures from package commands. It creates an `Error` named `PmCliError` with a structural `exitCode`, so separately installed package code still gets expected-error handling and Sentry filtering.
+
+Use `activateExtensionForTest(module)` in package unit tests when you need an
+`activation.registrations` or `activation.hooks` object for assertion helpers.
+It exercises the real activation and capability validation path without
+requiring private loader imports or a temporary `.agents/pm/extensions` tree.
+Keep `pm package doctor --project --detail deep --trace` and runtime contracts
+for integration tests against installed packages.
+
+`PM_CLI_PACKAGE_ROOT` is first-party only. Bundled packages in this repository use it to find the running CLI's `dist/sdk/runtime.js` before they are published or installed independently. External packages must not read this environment variable or import from `dist/` or `src/core`; use `@unbrained/pm-cli/sdk`, `@unbrained/pm-cli/sdk/runtime`, and `@unbrained/pm-cli/sdk/testing`.
+
 ## Troubleshooting
 
 - Manifest or entry failure: run `pm package explore --project`.

package/docs/QUICKSTART.md

@@ -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/RELEASING.md

@@ -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:
@@ -131,7 +131,7 @@ git push origin v<version>
 - build, typecheck, test, and coverage
 - static quality gate (complexity, duplication, dead/orphan module, file/folder hygiene)
 - temporary-project compatibility gate against latest published tracker data
-- reliability threshold gate (Sentry severity threshold, telemetry policy mode)
+- reliability threshold gate (Sentry severity threshold; `--telemetry-mode` gate policy: `off` | `best-effort` | `required`)
 - sandboxed `pm` coverage
 - optional Sentry release metadata and sourcemap upload when `SENTRY_AUTH_TOKEN` is configured
 - npm pack dry run and npx tarball smoke test