@unbrained/pm-cli 2026.5.1-2 → 2026.5.2

package/docs/QUICKSTART.md

@@ -0,0 +1,108 @@
+# Quickstart
+
+Use this page to get from a clean repository to a tracked, verified item.
+
+## Agent Quick Context
+
+- Start with `pm init`.
+- Create items with enough metadata to route work, then enrich later.
+- Claim before implementation.
+- Link changed files, docs, and tests to the item.
+- Close only after evidence is recorded.
+
+Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
+
+## Install
+
+```bash
+npm install -g @unbrained/pm-cli
+pm --version
+```
+
+For one-off use:
+
+```bash
+npx @unbrained/pm-cli --help
+```
+
+## Initialize a Repository
+
+```bash
+pm init
+pm health --check-only
+```
+
+`pm init` creates `.agents/pm/` with settings, item folders, history, locks, search cache directories, and project extension storage.
+
+## Create Your First Item
+
+Use strict create mode when all required fields are ready. Use progressive mode for staged triage.
+
+```bash
+pm create \
+  --title "Add restore retry logging" \
+  --description "Restore should explain stale lock retry behavior." \
+  --type Task \
+  --status open \
+  --priority 1 \
+  --tags "restore,locks" \
+  --ac "Retry logs are visible and regression coverage passes." \
+  --create-mode progressive
+```
+
+Useful item types:
+
+| Type | Use |
+|------|-----|
+| `Epic` | broad outcome or initiative |
+| `Feature` | user-facing capability or major slice |
+| `Task` | implementation work |
+| `Issue` | bug or defect |
+| `Decision` | recorded choice and rationale |
+| `Event`, `Reminder`, `Milestone`, `Meeting` | calendar-aware planning |
+
+## Find and Claim Work
+
+```bash
+pm context --limit 10
+pm search "restore lock retry" --limit 10
+pm list-open --limit 20
+pm claim <item-id>
+pm update <item-id> --status in_progress --message "Start implementation"
+```
+
+Do not create a duplicate item until `context`, `search`, and list commands show no relevant active item.
+
+## Link Work Artifacts
+
+```bash
+pm files <item-id> --add path=src/core/lock/lock.ts,scope=project,note="implementation"
+pm docs <item-id> --add path=docs/ARCHITECTURE.md,scope=project,note="design context"
+pm test <item-id> --add command="node scripts/run-tests.mjs test -- tests/unit/lock.spec.ts",scope=project,timeout_seconds=240
+```
+
+Use `node scripts/run-tests.mjs ...` for linked tests so tracker data is sandboxed.
+
+## Record Evidence and Close
+
+```bash
+pm test <item-id> --run --progress
+pm comments <item-id> "Evidence: linked lock regression passed."
+pm close <item-id> "Acceptance criteria met; linked regression passed." --validate-close warn
+pm release <item-id>
+```
+
+For broad readiness checks:
+
+```bash
+pnpm build
+node scripts/run-tests.mjs coverage
+pm validate --check-resolution --check-history-drift
+```
+
+## Next Pages
+
+- [Agent Guide](AGENT_GUIDE.md) for the full canonical workflow.
+- [Command Reference](COMMANDS.md) for command families and examples.
+- [Configuration](CONFIGURATION.md) for output, storage, search, and validation settings.
+- [Testing](TESTING.md) for sandbox and linked-test details.

package/docs/README.md

@@ -0,0 +1,70 @@
+# pm-cli Documentation
+
+This directory is the public documentation home for `pm-cli`. It is organized for progressive disclosure: read the smallest page that answers the current question, then follow links only when more detail is needed.
+
+## Read Path
+
+| Reader | First page | Then read |
+|--------|------------|-----------|
+| New user | [Quickstart](QUICKSTART.md) | [Command Reference](COMMANDS.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) |
+| Extension author | [Extensions](EXTENSIONS.md) | [SDK](SDK.md), [starter extension](examples/starter-extension/README.md) |
+| Machine client | [Command Reference](COMMANDS.md#machine-contracts) | `pm contracts --json` |
+
+## Documentation Map
+
+- [Quickstart](QUICKSTART.md) - install, initialize, create, claim, link, test, close.
+- [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.
+- [Testing](TESTING.md) - sandbox-safe local tests and linked-test orchestration.
+- [Architecture](ARCHITECTURE.md) - contributor internals: storage, mutation flow, search, extensions, and command contracts.
+- [Extensions](EXTENSIONS.md) - runtime extension lifecycle and API reference.
+- [SDK](SDK.md) - public import surfaces and typed authoring examples.
+- [Releasing](RELEASING.md) - maintainer release checklist and failure handling.
+- [starter extension](examples/starter-extension/README.md) - compact extension scaffold reference.
+
+Community files:
+
+- [Contributing](../CONTRIBUTING.md)
+- [Security](../SECURITY.md)
+- [Code of Conduct](../CODE_OF_CONDUCT.md)
+- [Changelog](../CHANGELOG.md)
+- [License](../LICENSE)
+
+## Agent Routing Rules
+
+1. Start with [Agent Guide](AGENT_GUIDE.md) for workflow rules.
+2. Use [Command Reference](COMMANDS.md) for command families, not exhaustive flag memory.
+3. Use `pm <command> --help --json` or `pm contracts --command <name> --flags-only --json` for exact flags.
+4. Use [Architecture](ARCHITECTURE.md) only when changing internals or debugging behavior.
+5. Use [SDK](SDK.md) and [Extensions](EXTENSIONS.md) only when authoring or troubleshooting extensions.
+
+## Tracker References
+
+This documentation structure 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)
+
+When changing docs, link files back to the active item:
+
+```bash
+pm docs <item-id> --add path=docs/README.md,scope=project,note="documentation index"
+pm comments <item-id> "Docs updated; links and build verified."
+```
+
+## Public Boundary
+
+Public docs must not link to ignored local operations artifacts, unpublished evidence logs, credentials, host-specific runbooks, or private service details. Keep those materials local and out of packaged releases.
+
+## Maintenance Checklist
+
+- Keep links relative and GitHub-compatible.
+- Keep README short; move detail into focused pages.
+- Put a short "Agent Quick Context" near the top of deep docs.
+- Prefer commands that agents can copy exactly.
+- Use `pm` item IDs as durable references when docs explain tracked work.
+- Run link/search checks before closing documentation tasks.

package/docs/RELEASING.md

@@ -1,55 +1,66 @@
 # Releasing `@unbrained/pm-cli`
 
-This repository uses a tag-driven GitHub Actions pipeline that publishes to npm and creates a GitHub Release. The pipeline uses standard GitHub Actions, repository or environment secrets, artifacts, and npm provenance; it does not require paid GitHub features or paid-only environment protection rules.
+This page is for maintainers cutting npm and GitHub releases. It assumes release work is tracked with `pm`.
 
-## Version Policy
+## Agent Quick Context
+
+- Release versioning is calendar SemVer-compatible: `YYYY.M.D` or `YYYY.M.D-N`.
+- Publishing is owned by the GitHub Actions release workflow.
+- Do not run manual `npm publish`.
+- Run local gates before tagging.
 
-`pm-cli` uses a calendar SemVer-compatible scheme:
+Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
 
-- `YYYY.M.D` for the first release on a date
-- `YYYY.M.D-N` for additional releases on the same date (`N >= 2`)
+## Version Policy
 
 Examples:
 
-- First release on 2026-03-09: `2026.3.9`
-- Second release on 2026-03-09: `2026.3.9-2`
+- first release on 2026-05-01: `2026.5.1`
+- second release on 2026-05-01: `2026.5.1-2`
 
-Use this to compute the next expected release version from the npm registry:
+Check the next version:
 
 ```bash
 pnpm version:next
 ```
 
-The release workflow enforces the package version, tag name, calendar date, and npm registry sequencing before publishing.
+Validate the current package version:
+
+```bash
+pnpm version:check
+```
 
 ## One-Time Setup
 
-- Add `NPM_TOKEN` as a GitHub Environment or repository secret named `NPM_TOKEN`.
-- If using an Environment named `release`, keep it free-feature compatible: no paid-only reviewer or deployment-protection requirements.
-- Ensure `GITHUB_TOKEN` has the default workflow permission needed by `permissions: contents: write` for GitHub Release creation.
-- Keep npm two-factor settings compatible with automation tokens and provenance publishing.
-- Keep `package.json` repository, homepage, and bugs URLs aligned with the canonical GitHub source repository (`https://github.com/unbraind/pm-cli`); npm provenance validation rejects mismatched repository metadata.
+- Add `NPM_TOKEN` as a GitHub Environment or repository secret.
+- Add `SENTRY_AUTH_TOKEN` as an optional GitHub Environment or repository secret when Sentry release creation and sourcemap upload should run. The release workflow skips this step cleanly when the secret is absent.
+- Keep any `release` environment compatible with free GitHub features.
+- 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`.
+- Keep npm automation token settings compatible with provenance publishing.
 
 ## Local Release Checklist
 
-1. Confirm the next version:
+1. Confirm or compute the version.
 
 ```bash
 pnpm version:next
 ```
 
-2. Update `package.json`, `pnpm-lock.yaml`, and `CHANGELOG.md`.
+2. Update release files.
 
-   Keep direct dependency specifiers deterministic. Do not publish `latest` ranges; pin runtime and development dependencies to explicit SemVer ranges that resolve to the audited lockfile versions so Dependabot and downstream installs evaluate the same safe package line.
+- `package.json`
+- `pnpm-lock.yaml`
+- [CHANGELOG.md](../CHANGELOG.md)
 
-3. Generate release notes locally from changelog + pm tracker data:
+3. Generate release notes.
 
 ```bash
 pnpm build
 pnpm release:notes -- --version "$(node -p 'require("./package.json").version')" --output /tmp/pm-cli-release-notes.md
 ```
 
-4. Run local release gates:
+4. Run local gates.
 
 ```bash
 pnpm install
@@ -63,9 +74,11 @@ pnpm security:scan
 pnpm smoke:npx
 ```
 
-5. Verify previous-version tracker compatibility before tagging. Use a temporary project with the previously published package, create representative items, then run the current build against the same sandboxed `PM_PATH` and `PM_GLOBAL_PATH`. Confirm item count, fields, linked files/docs/tests, comments, close metadata, health, and history drift checks remain intact.
+5. Verify previous-version tracker compatibility in a temporary project.
 
-6. Commit, push, tag, and push the tag:
+Check representative items, linked files/docs/tests, comments, close metadata, health, and history drift across the previous package and current build.
+
+6. Commit, push, tag, and push the tag.
 
 ```bash
 git push origin main
@@ -73,22 +86,24 @@ git tag v<version>
 git push origin v<version>
 ```
 
-## Release Workflow
+## GitHub Workflow
 
-`.github/workflows/release.yml` runs on `v*.*.*` tags and performs:
+`.github/workflows/release.yml` runs on `v*.*.*` tags and handles:
 
-- full-history checkout for previous-tag and release-note generation
+- full-history checkout
 - pnpm install with frozen lockfile
 - version policy and tag guard
-- secret leak scan
-- build, typecheck, test coverage, and sandboxed pm coverage
+- secret scan
+- build, typecheck, test, and coverage
+- 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
-- generated release notes from `CHANGELOG.md` plus sanitized `pm` tracker metadata
-- coverage and release-note artifact uploads
+- generated release notes from changelog plus sanitized tracker metadata
+- artifact uploads
 - `npm publish --access public --provenance`
-- GitHub Release creation using the generated release-note body
+- GitHub Release creation
 
-Monitor with:
+Monitor:
 
 ```bash
 gh run list --workflow Release --limit 5
@@ -97,8 +112,6 @@ gh run watch <run-id> --exit-status
 
 ## Post-Release Verification
 
-After the workflow succeeds, verify all distribution paths:
-
 ```bash
 npm view @unbrained/pm-cli@<version> version dist.integrity dist.unpackedSize --json
 npx --yes @unbrained/pm-cli@<version> --version
@@ -106,11 +119,11 @@ bunx @unbrained/pm-cli@<version> --version
 gh release view v<version> --json tagName,name,isDraft,isPrerelease,url
 ```
 
-The `pm` executable name remains unchanged even though the npm package is scoped.
+The executable remains `pm` even though the npm package is scoped.
 
 ## Failure Handling
 
-- Do not run manual `npm publish`; publishing is owned by `.github/workflows/release.yml`.
-- If local gates fail, fix the code/docs/tests and rerun the checklist before tagging.
-- If the tag workflow fails before npm publish, fix the issue, move the tag only after confirming no package was published, and rerun the workflow.
-- If npm publish succeeds but GitHub Release creation fails, rerun only the release creation after confirming the tag and package are correct.
+- If local gates fail, fix and rerun before tagging.
+- If the tag workflow fails before npm publish, confirm no package was published before moving or replacing a tag.
+- If npm publish succeeds but GitHub Release creation fails, recreate only the GitHub Release after verifying the tag and package.
+- Record failure evidence and remediation in the release `pm` item.

package/docs/SDK.md

@@ -1,123 +1,182 @@
-# pm SDK Guide
+# SDK
 
-This guide documents the public SDK surface for extension authors.
+The public SDK is exported from `@unbrained/pm-cli/sdk`. Use it for extension authoring and command-contract introspection. Do not import internal `src/core/...` modules from extensions.
 
-Primary import:
+## Agent Quick Context
+
+- Primary import: `@unbrained/pm-cli/sdk`.
+- Runtime extension lifecycle is documented in [Extensions](EXTENSIONS.md).
+- Exact command/action contracts are available through `pm contracts`.
+
+Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
+
+## Import Surfaces
 
 ```ts
 import { defineExtension } from "@unbrained/pm-cli/sdk";
 ```
 
-Use this document for SDK/API contracts. Use `docs/EXTENSIONS.md` for full runtime lifecycle behavior and `pm extension --init ./my-extension` for starter scaffold generation.
-
-## Import Surfaces
+Supported package exports:
 
-- `@unbrained/pm-cli/sdk`: stable extension authoring API and CLI contract exports.
-- `@unbrained/pm-cli/cli`: runtime CLI module entrypoint. This path is for runtime module resolution, not a typed library API; its declaration file intentionally exports no symbols.
+- `@unbrained/pm-cli/sdk` - stable extension authoring API and CLI contract exports.
+- `@unbrained/pm-cli/cli` - runtime CLI module entrypoint for package resolution, not a typed library API.
 
-## Public SDK Exports
+## Public Exports
 
 Source of truth:
 
-- `src/sdk/index.ts`
-- `src/sdk/cli-contracts.ts`
+- [`src/sdk/index.ts`](../src/sdk/index.ts)
+- [`src/sdk/cli-contracts.ts`](../src/sdk/cli-contracts.ts)
 
-### Extension authoring values
+Common authoring exports:
 
-- `defineExtension(...)`
+- `defineExtension`
 - `EXTENSION_CAPABILITIES`
 - `EXTENSION_CAPABILITY_CONTRACT`
 - `EXTENSION_CAPABILITY_CONTRACT_VERSION`
 - `EXTENSION_CAPABILITY_LEGACY_ALIASES`
-
-### CLI/action contract values
-
 - `PM_CORE_COMMAND_NAMES`
 - `PM_TOOL_ACTIONS`
 - `PM_TOOL_PARAMETERS_SCHEMA`
 - `PM_EXTENSION_CAPABILITY_CONTRACTS`
 - `PM_EXTENSION_SERVICE_NAME_CONTRACTS`
-- all exported `...FLAG_CONTRACTS`, `...OPTION_CONTRACTS`, and `...COMMANDER_*_CONTRACTS` arrays from `src/sdk/cli-contracts.ts`
-
-### CLI/action contract helpers
-
-- `withFlagAliasMetadata(...)`
-- `toCompletionFlagString(...)`
-- `readFirstStringFromCommanderOptions(...)`
-- `readStringArrayFromCommanderOptions(...)`
 
-### Key type exports
+Common types:
 
-- extension capability/types: `ExtensionCapability`, `PmToolAction`, `PmExtensionCapabilityContract`, `PmExtensionServiceNameContract`
-- command/flag/type helpers: `CommandDefinition`, `ExtensionCommandArgumentDefinition`, `FlagDefinition`, `SchemaFieldDefinition`, `SchemaItemTypeDefinition`
-- runtime extension API types: `ExtensionApi`, `ExtensionManifest`, lifecycle hook context types, importer/exporter contexts, search provider types, vector adapter types
-- shared command/settings types: `GlobalOptions`, `PmSettings`
-
-## Capability Requirements (Quick Reference)
-
-Declare capabilities in `manifest.json`; runtime gating is strict.
+- `ExtensionApi`
+- `ExtensionManifest`
+- `CommandDefinition`
+- `FlagDefinition`
+- `SchemaFieldDefinition`
+- `SchemaItemTypeDefinition`
+- `SearchProviderDefinition`
+- `VectorStoreAdapterDefinition`
+- `GlobalOptions`
+- `PmSettings`
+
+## Capability Requirements
+
+| Registration | Manifest capability |
+|--------------|---------------------|
+| `registerCommand` | `commands` |
+| inline command flags | `schema` |
+| `registerFlags` | `schema` |
+| `registerItemFields` | `schema` |
+| `registerItemTypes` | `schema` |
+| `registerMigration` | `schema` |
+| `registerImporter` | `importers` |
+| `registerExporter` | `importers` |
+| `registerParser` | `parser` |
+| `registerPreflight` | `preflight` |
+| `registerService` | `services` |
+| `registerRenderer` | `renderers` |
+| lifecycle hooks | `hooks` |
+| `registerSearchProvider` | `search` |
+| `registerVectorStoreAdapter` | `search` |
+
+## Minimal Command Extension
 
-- `registerCommand(...)`: requires `commands`
-- `registerCommand({ flags: [...] })` and `registerFlags(...)`: require `schema`
-- `registerItemFields(...)`, `registerItemTypes(...)`, `registerMigration(...)`: require `schema`
-- `registerImporter(...)` and `registerExporter(...)`: require `importers`
-- `registerParser(...)`: requires `parser`
-- `registerPreflight(...)`: requires `preflight`
-- `registerService(...)`: requires `services`
-- `registerRenderer(...)`: requires `renderers`
-- lifecycle hooks (`beforeCommand`, `afterCommand`, `onWrite`, `onRead`, `onIndex`): require `hooks`
-- `registerSearchProvider(...)` and `registerVectorStoreAdapter(...)`: require `search`
+```ts
+import { defineExtension } from "@unbrained/pm-cli/sdk";
 
-## Minimal Extension
+export default defineExtension({
+  activate(api) {
+    api.registerCommand({
+      name: "hello",
+      description: "Return a deterministic hello payload.",
+      intent: "verify SDK extension activation",
+      examples: ["pm hello"],
+      run: async () => ({ ok: true, message: "hello" }),
+    });
+  },
+});
+```
 
-`manifest.json`:
+Manifest:
 
 ```json
 {
-  "name": "hello-extension",
+  "name": "hello",
   "version": "0.1.0",
   "entry": "./index.js",
   "capabilities": ["commands"]
 }
 ```
 
-`index.js`:
+## Custom Item Type
 
-```js
+```ts
 import { defineExtension } from "@unbrained/pm-cli/sdk";
 
 export default defineExtension({
   activate(api) {
-    api.registerCommand({
-      name: "hello",
-      run: async () => ({ ok: true, message: "hello from sdk extension" }),
+    api.registerItemTypes([
+      {
+        name: "Incident",
+        folder: "incidents",
+        aliases: ["incident"],
+        required_create_fields: ["title", "description", "severity"],
+        options: [
+          { key: "severity", values: ["critical", "major", "minor"], required: true },
+          { key: "service", values: ["api", "web", "worker"] },
+        ],
+      },
+    ]);
+
+    api.registerItemFields([
+      { name: "severity", type: "string" },
+      { name: "service", type: "string", optional: true },
+    ]);
+  },
+});
+```
+
+Manifest capability: `schema`.
+
+## Search Provider
+
+```ts
+import { defineExtension } from "@unbrained/pm-cli/sdk";
+
+export default defineExtension({
+  activate(api) {
+    api.registerSearchProvider({
+      name: "example-search",
+      async query(context) {
+        return context.documents
+          .filter((doc) => doc.front_matter.title?.toLowerCase().includes(context.query.toLowerCase()))
+          .map((doc) => ({ id: doc.front_matter.id, score: 0.5, matched_fields: ["title"] }));
+      },
     });
   },
 });
 ```
 
-## Typed Authoring Highlights
+Manifest capability: `search`.
 
-The SDK provides explicit interfaces for key surfaces including:
+## Command Contracts
 
-- `CommandDefinition` and `ExtensionCommandArgumentDefinition`
-- `FlagDefinition`
-- `SchemaFieldDefinition`, `SchemaItemTypeDefinition`, `SchemaMigrationDefinition`
-- `ImportExportContext`
-- `SearchProviderDefinition`, `SearchProviderQueryContext`, `SearchProviderHit`
-- `VectorStoreAdapterDefinition`, `VectorStoreQueryContext`, `VectorStoreUpsertContext`
+For machine clients:
+
+```bash
+pm contracts --json
+pm contracts --command create --flags-only --json
+pm contracts --action create --schema-only --json
+```
 
-These interfaces intentionally allow additive metadata (`[key: string]: unknown`) where extension-defined metadata is expected.
+Use the runtime command because active extensions can add command/action metadata.
 
-## Recommended Authoring Pattern
+## Authoring Pattern
 
-- keep command handlers deterministic and JSON-like
-- keep renderer/service overrides narrow to specific command paths
-- prefer additive hooks and schema fields over global behavior changes
-- ship one extension folder with `manifest.json`, an entry module, and package metadata/dependencies
+- Keep handlers deterministic and JSON-like.
+- Return data, not pre-rendered terminal text, unless implementing a renderer.
+- Keep service and preflight overrides narrow.
+- Declare only capabilities in use.
+- Include examples and failure hints in dynamic commands.
+- Add `pm extension doctor` diagnostics to testing instructions.
 
 ## Related Docs
 
-- full extension lifecycle/runtime reference: `docs/EXTENSIONS.md`
-- architecture internals: `docs/ARCHITECTURE.md`
-- complete starter scaffold: `docs/examples/starter-extension/`
+- [Extensions](EXTENSIONS.md)
+- [Architecture](ARCHITECTURE.md)
+- [starter extension](examples/starter-extension/README.md)