@unbrained/pm-cli 2026.5.12 → 2026.5.18

package/docs/QUICKSTART.md

@@ -9,7 +9,7 @@ Use this page to get from a clean repository to a tracked, verified item.
 - Claim before implementation.
 - Link changed files, docs, and tests to the item.
 - Close only after evidence is recorded.
-- Use `pm guide quickstart` or `pm guide workflows` when you need local docs routing.
+- Use `pm install guide-shell --project` before `pm guide quickstart` or `pm guide workflows` when you need local docs routing.
 
 Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
 
@@ -34,9 +34,11 @@ For one-off use:
 npx @unbrained/pm-cli --help
 ```
 
-Optional first-party packages are installable on demand:
+Optional first-party packages are installable during init or on demand:
 
 ```bash
+pm init --defaults --with-packages
+pm package catalog --project
 pm install '*' --project
 pm install all --project
 pm package doctor --project --detail summary
@@ -47,9 +49,14 @@ pm package doctor --project --detail summary
 ```bash
 pm init
 pm health --check-only
+pm init --agent-guidance status
+pm init --agent-guidance add
 ```
 
 `pm init` creates `.agents/pm/` with settings, item folders, history, locks, search cache directories, and project extension storage.
+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.
 
 ## Create Your First Item
 
@@ -93,9 +100,9 @@ Do not create a duplicate item until `context`, `search`, and list commands show
 ## 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
+pm files <item-id> --add path=src/core/lock/lock.ts,note="implementation"
+pm docs <item-id> --add path=docs/ARCHITECTURE.md,note="design context"
+pm test <item-id> --add command="node scripts/run-tests.mjs test -- tests/unit/lock.spec.ts",timeout_seconds=240
 ```
 
 Use `node scripts/run-tests.mjs ...` for linked tests so tracker data is sandboxed.

package/docs/README.md

@@ -2,11 +2,12 @@
 
 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.
 
-## CLI Guide Router
+## Optional CLI Guide Router
 
-`pm guide` exposes the same documentation routes from inside the CLI:
+`pm guide` is provided by the optional `guide-shell` package. Install it when local in-CLI documentation routing is useful:
 
 ```bash
+pm install guide-shell --project
 pm guide
 pm guide quickstart
 pm guide commands --depth standard
@@ -23,7 +24,7 @@ pm guide release --json
 | Maintainer | [Contributing](../CONTRIBUTING.md) | [Testing](TESTING.md), [Releasing](RELEASING.md), [Architecture](ARCHITECTURE.md) |
 | Package author | [Packages and Extensions](EXTENSIONS.md) | [SDK](SDK.md), [starter extension](examples/starter-extension/README.md) |
 | Codex user | [Codex Plugin](CODEX_PLUGIN.md) | [Agent Guide](AGENT_GUIDE.md), then [Command Reference](COMMANDS.md) |
-| Machine client | `pm guide commands` | [Command Reference](COMMANDS.md#machine-contracts), then `pm contracts --json` |
+| Machine client | `pm contracts --json` | [Command Reference](COMMANDS.md#machine-contracts), optionally `pm install guide-shell --project && pm guide commands` |
 
 ## Documentation Map
 
@@ -41,8 +42,8 @@ pm guide release --json
 
 ## Guide Topic Map
 
-| `pm guide` topic | Primary docs |
-|------------------|--------------|
+| Optional `pm guide` topic | Primary docs |
+|-----------------------------|--------------|
 | `quickstart` | [Quickstart](QUICKSTART.md), [Command Reference](COMMANDS.md) |
 | `commands` | [Command Reference](COMMANDS.md), [Configuration](CONFIGURATION.md) |
 | `workflows` | [Agent Guide](AGENT_GUIDE.md), [Testing](TESTING.md) |
@@ -79,7 +80,7 @@ This documentation structure is tracked through:
 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 docs <item-id> --add path=docs/README.md,note="documentation index"
 pm comments <item-id> "Docs updated; links and build verified."
 ```
 

package/docs/RELEASING.md

@@ -1,7 +1,7 @@
 # Releasing `@unbrained/pm-cli`
 
 This page is for maintainers cutting npm and GitHub releases. It assumes release work is tracked with `pm`.
-For local progressive-disclosure routing, use `pm guide release`.
+For local progressive-disclosure routing, install `guide-shell` with `pm install guide-shell --project`, then use `pm guide release`.
 
 ## Agent Quick Context
 
@@ -10,7 +10,7 @@ For local progressive-disclosure routing, use `pm guide release`.
 - Publishing is owned by the tag-driven GitHub Actions release workflow.
 - Do not run manual `npm publish`.
 - Run local parity gates before pushing release tags.
-- Use `pm guide release --json` for machine-readable release docs routing.
+- Use `pm guide release --json` for machine-readable release docs routing after `guide-shell` is installed.
 
 Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
 
@@ -40,7 +40,7 @@ pnpm version:check
 - 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`.
-- Keep npm automation token settings compatible with provenance publishing. The release workflow must keep `id-token: write`, a GitHub-hosted runner, and `npm publish --access public --provenance`.
+- Keep npm automation token settings compatible with provenance publishing. The release workflow must keep `id-token: write`, a GitHub-hosted runner, and `npm publish --access public --provenance`. npm Trusted Publishing is preferred because it uses OIDC short-lived credentials; if the npm package is configured for Trusted Publishing, restrict traditional token publishing after verifying the workflow.
 
 ## Automated Daily Driver
 
@@ -134,8 +134,9 @@ git push origin v<version>
 - generated release notes from changelog plus sanitized tracker metadata
 - artifact uploads
 - `npm publish --access public --provenance`, skipped on retry when the exact version is already present on npm
-- post-publish npm/npx/bunx verification
+- post-publish npm/npx/bunx verification through `scripts/release/verify-published-release.mjs`
 - GitHub Release creation
+- GitHub Release metadata verification through the same local verification script
 
 Monitor:
 
@@ -151,6 +152,7 @@ npm view @unbrained/pm-cli@<version> version dist.integrity dist.unpackedSize --
 npx --yes --package @unbrained/pm-cli@<version> -- pm --version
 bunx --bun @unbrained/pm-cli@<version> pm --version
 gh release view v<version> --json tagName,name,isDraft,isPrerelease,url
+pnpm release:verify-published -- --version <version>
 ```
 
 The executable remains `pm` even though the npm package is scoped.