@unbrained/pm-cli 2026.5.31 → 2026.6.6

package/docs/COMMANDS.md

@@ -16,13 +16,13 @@ pm contracts --command <command> --flags-only --json
 - Use `pm contracts` for machine clients.
 - Every mutation writes history.
 
-Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
+Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon).
 
 ## Command Families
 
 | Family | Commands | Purpose |
 |--------|----------|---------|
-| Bootstrap | `init`, `config`, `health` | create and inspect tracker setup |
+| Bootstrap | `init`, `config`, `health`, `telemetry` | create and inspect tracker setup |
 | Triage | `context`, `search`, `list*`, `aggregate`, `dedupe-audit` | find work and audit decomposition |
 | Lifecycle | `create`, `claim`, `update`, `append`, `close`, `release`, `delete`, `start-task`, `pause-task`, `close-task` | mutate item state |
 | Planning | `plan create`, `plan add-step`, `plan update-step`, `plan complete-step`, `plan link`, `plan approve`, `plan materialize` | agent-optimized living plans with ordered steps, evidence, decisions, validation, and materialization |
@@ -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 |
@@ -44,6 +44,7 @@ pm init --agent-guidance status
 pm init --agent-guidance add
 pm config project list
 pm health --check-only --summary --json
+pm telemetry status
 ```
 
 `pm init` creates `.agents/pm`. `pm health --check-only --summary --json` gives the smallest machine-readable health gate without refreshing optional search artifacts.
@@ -86,6 +87,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 +140,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,16 +301,53 @@ 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
+pm gc --scope locks --dry-run
 ```
 
 Use dry-run modes before broad lifecycle or cleanup changes.
 
+`pm gc` accepts `--scope` values `index`, `embeddings`, `runtime`, and `locks` (comma-separated or repeatable); with no `--scope` it sweeps all of them. The `locks` scope removes only **expired** lock files in `locks/` — those whose own embedded `created_at + ttl_seconds` has elapsed (debris left by crashed processes). Active locks and any lock file that cannot be parsed are always retained (never deleted when staleness cannot be proven), and the result includes a `locks` summary (`scanned`/`removed`/`retained`).
+
+`--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.
+
+### Telemetry Local Analytics
+
+`pm telemetry` surfaces local queue/runtime telemetry state without running full health checks:
+
+```bash
+pm telemetry status
+pm telemetry stats --limit 10
+pm telemetry flush
+pm telemetry clear
+```
+
+- `status` reports queue depth, endpoint, and latest flush metadata.
+- `stats` groups queued local telemetry events by command name.
+- `flush` runs an immediate local queue flush attempt.
+- `clear` disables telemetry and deletes local queue/runtime telemetry artifacts.
+
+### 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
 pm history <id> --limit 20
+pm history <id> --diff
+pm history <id> --diff --field status
 pm history <id> --full --diff --verify
 pm history-redact <id> --literal "[redacted_path_prefix]/private" --replacement "[redacted_path]"
 pm history-redact <id> --regex "/192\\.168\\.[0-9.]+/g" --dry-run
@@ -277,24 +359,53 @@ pm restore <id> <timestamp-or-version>
 ```
 
 History is append-only. Restore appends a new restore event instead of rewriting old history.
+
+`--diff` replays the history chain and emits, per entry, a `changes` array of `{ field, before, after }` field-level value transitions (alongside the `changed_fields` name list) — so you can see exactly what each field changed from and to without comparing snapshots. It is independent of the compact/full projection. `--field <name>` narrows the diff to a single field's transitions (implying `--diff`), answering "when did `<field>` change?" — e.g. `pm history <id> --diff --field status`.
+
+`pm stats` reports item and history totals plus per-type/per-status counts. Add `--storage` for aggregate history-stream metrics — `total_streams`, `total_lines`, `total_bytes`, the top streams by size (`largest_by_bytes`) and by depth (`deepest_by_lines`), and the global `oldest_entry`/`newest_entry` — to decide when to compact or redact streams and to plan storage:
+
+```bash
+pm stats
+pm stats --storage --json
+```
 `history-redact` rewrites matching history payloads deterministically, recomputes hash chains, and appends an auditable `history_redact` marker entry when changes are applied.
 `history-repair` re-anchors a drifted history chain when `pm health`/`pm validate --check-history-drift` report stale hashes: it replays the stream, recomputes every before/after hash, repairs legacy patch ops that no longer strictly apply, reconciles the latest hash with the on-disk item, and appends an auditable `history_repair` marker. It never modifies item content and is a safe no-op on a clean stream.
 
 ## 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-u9d0](../.agents/pm/epics/pm-u9d0.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:
@@ -130,6 +177,14 @@ Keyword search is always available:
 pm search "release docs" --mode keyword --limit 10
 ```
 
+`search.tuning` controls deterministic lexical weighting in keyword mode and the lexical component of hybrid mode. Default runtime weights:
+
+- `title_exact_bonus=10`
+- `title_weight=8`, `description_weight=5`, `tags_weight=6`, `status_weight=2`
+- `body_weight=1`, `comments_weight=1`, `notes_weight=1`, `learnings_weight=1`
+- `reminders_weight=2`, `events_weight=2`
+- `dependencies_weight=3`, `linked_content_weight=1`
+
 Semantic and hybrid search can use built-in OpenAI-compatible or Ollama providers plus vector stores such as Qdrant or LanceDB. If local Ollama is available and semantic settings are unset, `pm` can resolve local defaults automatically.
 
 For local Ollama or slower embedding providers, tune `search.embedding_batch_size`, `search.embedding_timeout_ms`, and `search.scanner_max_batch_retries` in project config before assuming semantic search is broken. Keyword search remains the fast baseline while semantic indexing catches up.

package/docs/EXTENSIONS.md

@@ -18,6 +18,7 @@ Related docs:
 - [Configuration](CONFIGURATION.md)
 - [Testing](TESTING.md)
 - [Command Reference](COMMANDS.md)
+- [Extension Author Contracts](EXTENSION_AUTHOR_CONTRACTS.md)
 
 ## Package Sources
 
@@ -45,6 +46,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 +82,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 +108,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 +128,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 +187,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 +212,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 +256,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,20 +282,41 @@ 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
 ```
 
+Detailed package-author runtime contracts live in
+[Extension Author Contracts](EXTENSION_AUTHOR_CONTRACTS.md), including
+`telemetry.capture_level`, create-path vs `mutateItem` write behavior, and hook
+surface guarantees.
+
+
 ## Lifecycle Commands
 
 Explore installed runtime entries:
@@ -296,6 +395,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/EXTENSION_AUTHOR_CONTRACTS.md

@@ -0,0 +1,73 @@
+# Extension Author Contracts
+
+Tracker: pm-at83
+
+This page records runtime contracts package authors need when they build on the public SDK. For the install, manifest, lifecycle, and troubleshooting overview, see [Packages and Extensions](EXTENSIONS.md).
+
+## Telemetry Capture Level
+
+Every `pm` command records a telemetry event. Extension commands use the same telemetry pipeline as core commands and inherit `telemetry.capture_level` from the active settings.
+
+Allowed values:
+
+| Value | Meaning |
+|-------|---------|
+| `redacted` | Default. Records sanitized command args, options, result summary, and runtime environment. |
+| `minimal` | Records structural metadata and one-way digests only. No readable command text, args, options, result summary, or runtime environment is kept. |
+| `max` | Same as `redacted`, but raises the per-string truncation cap from 512 to 2048 characters. Redaction still applies. |
+
+All levels redact inline secrets, bearer tokens, private paths, emails, private IPv4 addresses, and object keys whose names look sensitive. `minimal` additionally digests arg and option values with HMAC-SHA-256 so extension authors cannot reconstruct user input.
+
+Inspect and change the level:
+
+```bash
+pm health --json | jq '.details.capture_level'
+pm config set telemetry.capture_level minimal
+pm config set telemetry.capture_level redacted
+pm config set telemetry.capture_level max
+```
+
+The setting lives in the global pm settings file (`~/.pm-cli/settings.json` by default), not in the project tracker.
+
+## Item Write Paths
+
+`pm` has two item write paths. Hook, service, and migration authors should treat them as different contracts.
+
+Create path:
+
+- Used by `pm create` and importer-created items.
+- Acquires the item lock, writes the item file atomically, appends the create history entry, fires `onWrite` for the item file and history stream, records the after-command affected-item snapshot, then releases the lock.
+- Does not fire `onRead`, because there is no existing item.
+- Does not call the `item_store_write` service override. Use `onWrite` with `op="create"` if a package needs to observe new items.
+
+`mutateItem` path:
+
+- Used by `pm update`, `pm close`, `pm claim`, `pm release`, `pm restore`, `pm delete`, and other mutations of existing items.
+- Locates the item, acquires the lock, reads the item through the `onRead` hook, enforces ownership and history policy, applies the mutation, consults `item_store_write`, writes the item atomically, appends history, fires `onWrite` for the item and history stream, records the after-command affected-item snapshot, then releases the lock.
+- `item_store_write` handlers can redirect the target path, replace serialized contents, or skip the physical item write.
+
+Both paths guarantee:
+
+- Atomic item writes.
+- Lock coverage across item write and history append.
+- History append after the item write, with rollback if history append fails.
+- `onWrite` hooks only after item and history commits.
+- Non-fatal hook failures reported as `extension_hook_failed:<layer>:<name>:onWrite`.
+
+`changed_fields` sentinel values:
+
+| Value | Meaning |
+|-------|---------|
+| `["imported"]` | Item came from an importer. |
+| `["restored"]` | Item was restored from a previous state. |
+| `["deleted"]` | Item was deleted. |
+
+Surface matrix:
+
+| Surface | Create path | `mutateItem` path |
+|---------|-------------|-------------------|
+| `onRead` hook | No | Yes |
+| `item_store_write` service override | No | Yes |
+| `history_append` service override | Yes | Yes |
+| `onWrite` item hook | Yes, `op="create"` | Yes, `op=<mutation op>` |
+| `onWrite` history hook | Yes, `op="create:history"` | Yes, `op="<mutation op>:history"` |