@unbrained/pm-cli 2026.8.26 → 2026.8.27

package/.agents/skills/pm-user/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: pm-user
+description: Guides user- and operator-facing pm-cli workflows for intake, triage, prioritization, planning, and reporting under a bounded token budget. Use when routing requests into pm items, organizing a backlog, or reporting on state without implementing code changes.
+license: MIT
+compatibility: Works in terminal-based agent harnesses that execute pm CLI commands.
+metadata:
+  owner: unbrained
+  domain: pm-cli
+  scope: operator-workflow
+---
+
+# pm User Skill
+
+Planning and coordination work where the output is clean tracker state, not
+code. The tracker is the project's context: an item is well-formed when another
+agent can rebuild the full situation from it alone.
+
+## Load Order
+
+| Tier | Load                                  | Cost      | When                           |
+| ---- | ------------------------------------- | --------- | ------------------------------ |
+| 0    | This file                             | ~650 tok  | Always.                        |
+| 1    | `pm context --limit 10`               | ~2.1k     | Orient in an existing project. |
+| 1    | `pm search "<terms>" --limit 10`      | ~0.5-1k   | Before creating anything.      |
+| 2    | `pm guide <topic> --depth brief`      | ~0.6-1k   | An unfamiliar family.          |
+| 3    | `references/*.md` below               | ~0.3-1k   | Procedure detail.              |
+
+Optional deep routing that never goes stale:
+
+```bash
+pm install guide-shell --project
+pm guide quickstart
+pm guide commands --depth brief
+```
+
+## Non-Negotiables
+
+- Author identity is detected automatically. **Never pass `--author`, never set
+  `PM_AUTHOR`.**
+- Search before creating; record the duplicate check as a create-time comment.
+- Never delete items by search match — only by exact id.
+- Prefer appending (`pm comments`, `pm notes`) over rewriting item content.
+- Never assert an item's state from memory. Read it live first.
+
+## Intake Loop
+
+```bash
+pm context --limit 10
+pm search "<request keywords>" --limit 10
+pm list-open --limit 20 --output-include id,title,type,priority
+# reuse if it exists; otherwise create with lineage
+pm create --create-mode progressive \
+  --title "..." --description "..." --type Task --status open \
+  --parent <epic-or-feature-id> \
+  --dep "id=<origin-item>,kind=discovered_from" \
+  --ac "..." --priority 1 --risk medium --confidence medium
+pm comments <ID> "Duplicate check: searched <terms>; nearest existing is <id> which covers <scope>."
+```
+
+## What Makes An Item Well-Formed
+
+Use the metadata the tracker actually has. An item carrying only a title is a
+placeholder, not a tracked unit of work.
+
+| Field                                    | Why it matters                                     |
+| ---------------------------------------- | -------------------------------------------------- |
+| `--type`                                 | Routes into the right lifecycle and changelog bucket|
+| `--parent`                               | Places the item in the ladder                       |
+| `--dep "id=..,kind=.."`                  | Makes lineage machine-readable                      |
+| `--ac`                                   | Defines done without argument                       |
+| `--expected-result` / `--actual-result`  | Turns a defect into a reproducible claim            |
+| `--priority`, `--risk`, `--confidence`   | Lets selection rank without a human                 |
+| `--estimate`, `--deadline`               | Feeds scheduling and forecasting                    |
+| `--resolution`, `--close-reason`         | Makes the closed record answerable later            |
+
+`--risk` is an enum: `low`, `medium`, `high`, `critical`. `--ac` **replaces**
+the criteria; `--dep` **appends**.
+
+## Capability Map
+
+| Need                        | Entry                                    | Guide topic  |
+| --------------------------- | ---------------------------------------- | ------------ |
+| What should I do next       | `pm next`                                | `quickstart` |
+| Where does this project stand | `pm context`, `pm stats`               | `quickstart` |
+| Find existing work          | `pm search`, `pm list`, `pm duplicates`  | `commands`   |
+| Group and count             | `pm aggregate --group-by <field>`        | `commands`   |
+| Lineage and ordering        | `pm deps`, `pm graph <verb>`             | `graph`      |
+| Recent movement             | `pm activity`, `pm events`, `pm history` | `assurance`  |
+| Data quality                | `pm validate`, `pm health`               | `assurance`  |
+| Plan a multi-step change    | `pm plan`                                | `workflows`  |
+| Custom types and statuses   | `pm schema`, `pm config`                 | `commands`   |
+| Keep reads cheap            | `--output-*`, `--token-accounting`       | `tokens`     |
+
+## Reporting Without Loading Rows
+
+```bash
+pm stats
+pm aggregate --group-by status --json | jq '.groups'
+pm list --status open --output-include id,title,priority --output-limit 20
+```
+
+`--group-by tags` groups by the whole tag **tuple**, not by individual tag.
+Aggregate on a scalar field when a per-value count is what you want.
+
+## References
+
+| Need                              | Load                                          | Cost     |
+| --------------------------------- | --------------------------------------------- | -------- |
+| Triage and planning procedures     | [Workflows](references/WORKFLOWS.md)          | ~350 tok |
+| Prompt templates                   | [Prompts](references/PROMPTS.md)              | ~250 tok |
+| Backlog structure and item quality | [Backlog shaping](references/BACKLOG_SHAPING.md) | ~900 tok |

package/.agents/skills/pm-user/references/BACKLOG_SHAPING.md

@@ -0,0 +1,105 @@
+# Backlog Shaping
+
+How to keep a tracker readable by both people and graph algorithms as it grows
+from a handful of items to hundreds of thousands.
+
+## The Ladder
+
+Work resolves upward through typed edges to a declared outcome. A healthy
+workspace has no active item that reaches nothing.
+
+```
+Milestone (declared outcome)
+  ^ implements
+Epic / capability area
+  ^ parent
+Feature / Story / Decision
+  ^ parent
+Task / Issue / Chore
+```
+
+- `Story` states what an agent or an organization needs, in their words.
+- `Decision` records an architecture choice; open means proposed, closed means
+  accepted or rejected with rationale.
+- `Milestone` declares an outcome, not a date bucket.
+- `Plan` holds a multi-step change with durable steps and discoveries.
+
+Check the ladder:
+
+```bash
+pm graph audit --json | jq '{
+  isolated: .profile.isolated_active_nodes,
+  unreachable: .profile.outcome_unreachable_nodes,
+  outcomes: .profile.outcome_nodes
+}'
+```
+
+## Never Create A Duplicate
+
+```bash
+pm search "<distinctive phrase from the request>" --limit 10
+pm search "<second phrasing>" --limit 10
+pm list --type <likely-type> --status all --output-include id,title --output-limit 30
+pm duplicates --limit 20        # scored candidate pairs, where the corpus allows it
+```
+
+Record what you searched in a create-time comment. A duplicate check that is
+not written down cannot be audited later, and the next agent repeats it.
+
+When the request extends existing scope, extend the existing item — add
+acceptance criteria, add a child, add a typed edge. Filing a near-identical
+sibling is the most expensive mistake in a large tracker.
+
+## Prioritization That Selection Can Use
+
+`pm next` ranks from recorded metadata. Metadata you never set cannot rank.
+
+```bash
+pm update <ID> --priority 1 --risk high --confidence medium --estimate 120
+pm update <ID> --deadline 2026-09-30
+pm comments <ID> "Decision log: raised to P1 because <evidence>."
+```
+
+Ordering belongs in edges, not in priority numbers:
+
+```bash
+pm update <ID> --dep "id=<prerequisite>,kind=blocked_by"
+```
+
+Do not record the inverse `blocks` edge as well — the pair is one relationship
+and recording both creates a cycle.
+
+## Closing Well
+
+A closed item is the project's memory. Closed badly, it is a dead end.
+
+```bash
+pm close <ID> "<what shipped and what proved it>" \
+  --resolution "<how it was resolved>" \
+  --validate-close warn
+pm release <ID>
+```
+
+Fill `resolution`, `expected_result`, and `actual_result` for defects.
+`pm validate --check-resolution` reports which terminal items are missing them.
+
+Record evolution explicitly rather than letting it be inferred:
+
+```bash
+pm update <NEW> --dep "id=<OLD>,kind=supersedes"
+pm update <FIX> --dep "id=<INCIDENT>,kind=incident_from"
+pm update <TEST> --dep "id=<FEATURE>,kind=verifies"
+```
+
+## Periodic Hygiene
+
+```bash
+pm validate --check-resolution --check-history-drift
+pm health --summary
+pm graph audit
+pm list --status in_progress          # stale claims
+pm aggregate --group-by type --json
+```
+
+Fix what a diagnostic prescribes rather than only recording that it warned.
+A warning that has been carried for months is a decision that was never made.

package/.agents/skills/pm-user/references/PROMPTS.md

@@ -0,0 +1,17 @@
+# Operator Prompt Templates
+
+## Triage
+
+`Find the canonical pm item for this request. Show duplicate-check commands, then either reuse and update the item or create parent lineage + child item with explicit rationale.`
+
+## Schedule
+
+`Apply deterministic scheduling metadata (status, priority, estimate, deadline) to <ID> and leave a comment explaining the prioritization decision.`
+
+## Handoff
+
+`Prepare <ID> for handoff: append current state, blockers, and next actions; release the claim when handoff is complete.`
+
+## Closure Readiness
+
+`Validate whether <ID> is close-ready by checking acceptance criteria, linked files/tests/docs, and latest verification evidence.`

package/.agents/skills/pm-user/references/WORKFLOWS.md

@@ -0,0 +1,35 @@
+# User and Operator Workflows
+
+## Intake Workflow
+
+1. Query current context:
+
+```bash
+pm context --limit 10
+pm search "<keywords>" --limit 10
+pm list-open --limit 20
+pm list-in-progress --limit 20
+```
+
+2. If existing item matches, reuse and update it.
+3. If no match exists, create parent lineage then child item.
+4. Add duplicate-check evidence in comments at creation time.
+
+## Claim and Ownership Workflow
+
+```bash
+pm claim <ID>
+pm update <ID> --status in_progress --message "Start work"
+pm comments <ID> "Owner update: <state>"
+pm release <ID>
+```
+
+## Audit-Friendly Collaboration
+
+For non-owner append-only collaboration:
+
+```bash
+pm comments <ID> --add "audit comment" --allow-audit-comment
+pm notes <ID> --add "audit note" --allow-audit-comment
+pm update <ID> --dep "id=<id>,kind=related,author=<author>,created_at=now" --allow-audit-dep-update
+```

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Official marketplace for pm CLI — native git-based project management for Claude Code and AI coding agents.",
-    "version": "2026.8.26"
+    "version": "2026.8.27"
   },
   "plugins": [
     {
       "name": "pm-claude",
       "source": "./plugins/pm-claude",
       "description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents, hybrid TUI task tracking, session context injection, and coordination subagents for git-based project management without leaving Claude Code.",
-      "version": "2026.8.26",
+      "version": "2026.8.27",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 2026.8.27 - 2026-08-27
+
+### Added
+
+- Tiered contract-driven help: one-screen core help, full surface via pm help --all, generated from the contract table ([pm-e2bq](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-e2bq.toon))
+- Skills over MCP: discoverable version-coherent pm workflows with progressive disclosure, capability requirements, and token budgets ([pm-8nzivt](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-8nzivt.toon))
+- MCP Apps for pm: interactive graph, context, plan, assurance, and long-operation views with consent-safe action boundaries ([pm-pznhee](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-pznhee.toon))
+
+### Fixed
+
+- GH-859: pm-beads source export can omit Beads comment bodies and events ([pm-tpwde6](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-tpwde6.toon))
+- pm get silently discards --output-include field names because entity reads bind the flag to sections while collection reads bind it to fields, and the omission receipt reports no omissions either way ([pm-0k19l7](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-0k19l7.toon))
+- GH-860: pm-beads --preserve-source-ids changes source ID casing ([pm-f7jj9b](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-f7jj9b.toon))
+- GH-862: pm-beads must map Beads close reasons into native resolution metadata ([pm-gus5ft](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gus5ft.toon))
+- GH-1118: natural-language word-number titles trigger duplicate issue-code false positives ([pm-blvfye](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-blvfye.toon))
+- Published-artifact verification rejects the new pm-mcp-http bin before executing its healthy published entrypoint ([pm-fpdne3](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-fpdne3.toon))
+
+### Other
+
+- Consolidate package lifecycle: extension/package/install/upgrade under a single pm package namespace ([pm-tnud](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-tnud.toon))
+- Refresh compatible ESLint 10.9.1 and Node type 26.3 patches ([pm-crkmmr](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-crkmmr.toon))
+- MCP 2026-07-28 conformance and release gate: official schema matrix, protocol-era adapters, real transports, adversarial cases, and published consumers ([pm-55yf1t](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-55yf1t.toon))
+
 ## 2026.8.26 - 2026-08-26
 
 ### Added
@@ -442,7 +465,6 @@
 - Sentry PM-CLI-2Q: expected snapshot-name validation is captured as a high production error ([pm-qyg51h](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-qyg51h.toon))
 - The release gate classifies production errors by message prose and reads none of the 236 error codes the product declares, so every waiver is a latent re-block and a broad substring is a silent waiver ([pm-dqtzva](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-dqtzva.toon))
 - The mandatory command-wiring replication set is enforced only by a prose checklist, and the census shows partial application is the single largest recurring defect class in the record ([pm-7rrqsk](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-7rrqsk.toon))
-- pm get silently discards --output-include field names because entity reads bind the flag to sections while collection reads bind it to fields, and the omission receipt reports no omissions either way ([pm-0k19l7](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-0k19l7.toon))
 - GH-919: \_workspace author-attribution coordinates cannot be acknowledged ([pm-ety1qc](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ety1qc.toon))
 - pm comments write response replays the entire accumulated history, so one append can emit hundreds of comments ([pm-9stazf](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-9stazf.toon))
 - GH-457: pm health hangs during vectorization check with no output (never-block violation) ([pm-tu71](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-tu71.toon))
@@ -991,12 +1013,12 @@
 
 ### Fixed
 
+- GH-576: unknown-command help probes return structured non-zero errors ([pm-bu1m](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-bu1m.toon))
 - Sentry PM-CLI-2G: make merge-driver installation permission failures actionable ([pm-bnmlsc](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-bnmlsc.toon))
 - Sentry PM-CLI-2F: classify manifest-proven torn bundle call-time TypeError ([pm-pz7xtx](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-pz7xtx.toon))
 - Compatibility gate rejects compact legacy create envelopes after release promotion ([pm-pkdpyz](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-pkdpyz.toon))
 - Sentry PM-CLI-2E: directory-shaped settings.json crashes CLI bootstrap ([pm-k0nl2w](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-k0nl2w.toon))
 - Sentry PM-CLI-2D: storage-integrity history scan reads .jsonl directories as files ([pm-o1c53b](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-o1c53b.toon))
-- GH-576: unknown-command help probes return structured non-zero errors ([pm-bu1m](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-bu1m.toon))
 - GH-551: dependency seeds accept global source_kind and preserve cross-workspace IDs ([pm-topu](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-topu.toon))
 - GH-595: list JSON always emits total/has_more/truncated/next_cursor and omits unset filters ([pm-wrss](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-wrss.toon))
 - GH-623: opt-in post-merge history reconciliation hook and one-command verify repair ([pm-mfkv92](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-mfkv92.toon))
@@ -1462,6 +1484,7 @@
 
 ### Added
 
+- pm package/extension init --capability profile: scaffold a project-profile starter package ([pm-h2hk](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-h2hk.toon))
 - Describe --markdown writes reference docs to a file ([pm-u2tm](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-u2tm.toon))
 - Complete scaffold capability matrix: --capability renderers/parser/preflight/services starters ([pm-i5p5](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-i5p5.toon))
 - Scaffolded & authored command-bearing extensions reliably activate for their own commands ([pm-yxb5](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-yxb5.toon))
@@ -1469,7 +1492,6 @@
 - pm next: recommend the next actionable (unblocked, ready) work item with rationale + blocked companion ([pm-nj90](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-nj90.toon))
 - Add pm package / pm packages shell completion (bash/zsh/fish), including the package-only --declarative flag ([pm-mthy](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-mthy.toon))
 - Project profile author-time validation: lintProjectProfile + assertProjectProfile + pm profile lint ([pm-j1fj](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-j1fj.toon))
-- pm package/extension init --capability profile: scaffold a project-profile starter package ([pm-h2hk](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-h2hk.toon))
 - SDK + CLI: render extension/package surfaces to Markdown reference docs (renderExtensionSurfaceMarkdown + describe --markdown) ([pm-dmum](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-dmum.toon))
 - pm package/extension init --capability schema: scaffold custom item type/field/migration starter ([pm-d1ig](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-d1ig.toon))
 - First-party baseline profile package built on public SDK primitives ([pm-a7o4](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-a7o4.toon))

package/README.md

@@ -60,14 +60,17 @@ npx --yes @unbrained/pm-cli@latest --help
 `pm` packages use the same package-first vocabulary:
 
 ```bash
-pm install '*'
-pm install ./my-package
+pm package install '*'
+pm package install ./my-package
 pm package manage --project
 pm package doctor --detail summary
-pm upgrade --dry-run
+pm package upgrade --dry-run
 ```
 
-The legacy `pm extension ...` command remains available for existing automation.
+The hidden legacy `pm extension ...`, `pm install ...`, and `pm upgrade ...`
+aliases remain available for existing automation. They preserve canonical output
+and emit one migration hint on stderr unless `ux.deprecation_hints` is disabled;
+for example, `pm install guide-shell --project` maps to the canonical command.
 
 ## 60 Second Example
 
@@ -108,7 +111,7 @@ pm list --status in_progress --limit 20
 
 If no relevant item exists, create a parent lineage before child work, claim the child item, link changed files/docs/tests, and leave evidence comments before closing. The full workflow is in the [Agent Guide](docs/AGENT_GUIDE.md).
 
-For token-aware local routing, install `guide-shell` with `pm install guide-shell --project`, then use `pm guide workflows` and drill into related topics (`commands`, `skills`, `release`) only when needed.
+For token-aware local routing, install `guide-shell` with `pm package install guide-shell --project`, then use `pm guide workflows` and drill into related topics (`commands`, `skills`, `release`) only when needed.
 
 ## Core Model
 

package/dist/cli/commander-usage.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="48877bbb-17bf-5a78-91fa-19a2f2f4c2be")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="8879d491-9158-548c-bfbd-8ab57d8eb936")}catch(e){}}();
 import { pathExists, resolveItemTypeRegistry, EXIT_CODE, getSettingsPath, resolvePmRoot, readSettings, getActiveExtensionRegistrations, locateItem, runActiveServiceOverride, levenshteinDistanceWithinLimit, } from "../sdk/runtime-primitives.js";
 import { BUILTIN_ITEM_TYPE_VALUES } from "../types/index.js";
 import { PM_CORE_COMMAND_NAMES, resolveSubcommandFlagContractsForCommand, } from "../sdk/cli-contracts.js";
@@ -525,16 +525,20 @@ export function isKnownHelpCommandPath(root, commandPathTokens) {
         return true;
     }
     let current = root;
-    let matchedAny = false;
-    for (const token of commandPathTokens) {
+    for (const [tokenIndex, token] of commandPathTokens.entries()) {
         const next = resolveChildCommandByToken(current, token);
         if (!next) {
-            return matchedAny;
+            if (current.commands.some((candidate) => candidate.name() !== "help")) {
+                return false;
+            }
+            const declaredArguments = current.registeredArguments;
+            return (declaredArguments.length > 0 &&
+                (declaredArguments.at(-1)?.variadic === true ||
+                    commandPathTokens.length - tokenIndex <= declaredArguments.length));
         }
-        matchedAny = true;
         current = next;
     }
-    return matchedAny;
+    return true;
 }
 async function resolveWorkspaceUsageContext(bootstrapGlobal, message, invocationArgv, commandName) {
     try {
@@ -763,4 +767,4 @@ export const _testOnly = {
     suggestNearestLongFlags,
 };
 //# sourceMappingURL=commander-usage.js.map
-//# debugId=48877bbb-17bf-5a78-91fa-19a2f2f4c2be
+//# debugId=8879d491-9158-548c-bfbd-8ab57d8eb936

package/dist/cli/error-guidance.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="4bdb7fcf-dd74-57bc-8a0e-07539095462e")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="bb31fb1f-bf61-5eab-aa63-5d04fbac282f")}catch(e){}}();
 import { resolveRecoveryCommandName } from "../sdk/agent/command-recovery.js";
 import { projectPmDiagnosticOutput, projectPmDiagnosticText, } from "../sdk/cli-contracts/agent-output-contracts.js";
 import { renderPmCommand } from "./argv-utils.js";
@@ -207,6 +207,7 @@ function renderRecoveryBundle(recovery) {
         return [];
     }
     const lines = ["Recovery bundle:"];
+    appendRecoveryTextLine(lines, "suggested_retry", normalized.suggested_retry);
     appendRecoveryTextLine(lines, "attempted_command", normalized.attempted_command);
     appendRecoveryListLine(lines, "normalized_args", normalized.normalized_args, " ");
     if (normalized.parsed_positionals &&
@@ -231,7 +232,6 @@ function renderRecoveryBundle(recovery) {
     if (normalized.option_scope !== undefined) {
         lines.push(`  option_scope: ${normalized.option_scope}`);
     }
-    appendRecoveryTextLine(lines, "suggested_retry", normalized.suggested_retry);
     if (typeof normalized.retry_after_ms === "number") {
         lines.push(`  retry_after_ms: ${normalized.retry_after_ms}`);
     }
@@ -1297,4 +1297,4 @@ export const _testOnly = {
     resolveKnownPackageCommandHint,
 };
 //# sourceMappingURL=error-guidance.js.map
-//# debugId=4bdb7fcf-dd74-57bc-8a0e-07539095462e
+//# debugId=bb31fb1f-bf61-5eab-aa63-5d04fbac282f

package/dist/cli/help-content.d.ts

@@ -39,6 +39,8 @@ declare function renderDetailedHelpBundle(bundle: HelpBundle): string;
 export declare function normalizeHelpCommandPath(commandPath: string): string;
 /** Implements resolve help detail mode for the public runtime surface of this module. */
 export declare function resolveHelpDetailMode(argv: string[]): HelpDetailMode;
+/** Whether an invocation requests the complete public command discovery tier. */
+export declare function isFullHelpDiscovery(argv: readonly string[]): boolean;
 /** Public contract for root help bundle, shared by SDK and presentation-layer consumers. */
 export declare const ROOT_HELP_BUNDLE: HelpBundle;
 /** Implements resolve help bundle for path for the public runtime surface of this module. */

package/dist/cli/help-content.js

@@ -1,8 +1,9 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="5ea35d21-cfe6-5138-9fdb-413083719924")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="1399e88f-710a-5e5c-b4b3-70e35ec401cf")}catch(e){}}();
 import { parseBootstrapHelpRequest } from "./bootstrap-args.js";
 import { formatPmPositionalActionFlagTip, PM_POSITIONAL_ACTION_CONTRACTS, resolvePmPositionalActionContract, } from "../sdk/cli-contracts/grammar-contracts.js";
-import { listPmCommandsForTier, measurePmCoreHelp, PM_CORE_HELP_OPTION_FLAGS, } from "../sdk/agent-capability-contracts.js";
+import { listPmCommandsForTier, measurePmCoreHelp, PM_CORE_HELP_OPTION_FLAGS, resolvePmCommandVisibilityTier, } from "../sdk/agent-capability-contracts.js";
+import { PM_COMMAND_ALIAS_CONTRACTS, renderPmCommandAliasMigrationHint, } from "../sdk/cli-contracts.js";
 const COMMAND_HELP_VISIBILITY_TIERS = new WeakMap();
 /** Attach a package command's declared tier to its Commander presentation node. */
 export function setPmCommandHelpVisibilityTier(command, tier) {
@@ -92,6 +93,10 @@ export function resolveHelpDetailMode(argv) {
     }
     return "compact";
 }
+/** Whether an invocation requests the complete public command discovery tier. */
+export function isFullHelpDiscovery(argv) {
+    return argv.includes("--all") || argv.includes("--explain");
+}
 const HELP_BY_COMMAND_PATH = {
     init: {
         why: "Bootstraps tracker storage and settings so all other commands can run safely.",
@@ -883,30 +888,47 @@ export function resolveHelpNarrative(commandPath, detailMode) {
         detail_mode: detailMode,
     };
 }
-/** Implements attach rich help text for the public runtime surface of this module. */
-export function attachRichHelpText(program, argv = process.argv.slice(2)) {
-    const baselineHelp = program.createHelp();
-    const coreCommands = new Set(listPmCommandsForTier("core"));
+/** Render the complete permanent and deprecated command-alias discovery appendix. */
+function renderFullCommandAliasHelp() {
+    const permanentAliases = PM_COMMAND_ALIAS_CONTRACTS.filter(({ lifecycle }) => lifecycle === "permanent");
+    const deprecatedAliases = PM_COMMAND_ALIAS_CONTRACTS.filter(({ lifecycle }) => lifecycle === "deprecated");
+    return [
+        "",
+        "Command aliases:",
+        ...permanentAliases.map(({ alias, canonical_argv: canonicalArgv }) => `  ${alias} -> pm ${canonicalArgv.join(" ")}`),
+        "",
+        "Deprecated aliases:",
+        ...deprecatedAliases.map((contract) => `  ${contract.alias} -> pm ${contract.canonical_argv.join(" ")} (${renderPmCommandAliasMigrationHint(contract)})`),
+    ].join("\n");
+}
+/** Configure Commander visibility without changing the registered command graph. */
+function configureTieredHelpVisibility(program, baselineHelp, fullDiscovery, selectedRootCommands) {
     const coreOptions = new Set(PM_CORE_HELP_OPTION_FLAGS);
-    const selectedRootCommands = new Set();
     program.configureHelp({
         visibleCommands(command) {
             const visible = baselineHelp.visibleCommands(command);
-            if (command !== program) {
-                return visible;
+            if (!fullDiscovery) {
+                if (command !== program)
+                    return visible;
+                return visible.filter((candidate) => selectedRootCommands.has(candidate));
             }
-            return visible.filter((candidate) => selectedRootCommands.has(candidate));
+            return visible.filter((candidate) => {
+                const declaredTier = getPmCommandHelpVisibilityTier(candidate);
+                return ((declaredTier ?? resolvePmCommandVisibilityTier(candidate.name())) !==
+                    "internal");
+            });
         },
         visibleOptions(command) {
             const visible = baselineHelp.visibleOptions(command);
-            return command === program
-                ? visible.filter((option) => coreOptions.has(option.flags))
-                : visible;
+            if (command !== program || fullDiscovery)
+                return visible;
+            return visible.filter((option) => coreOptions.has(option.flags));
         },
     });
-    const detailMode = resolveHelpDetailMode(argv);
-    const rootHelpText = renderHelpBundle(ROOT_HELP_BUNDLE, detailMode);
-    program.addHelpText("after", rootHelpText);
+}
+/** Populate the root core tier while enforcing the public help-size budget. */
+function selectBudgetedRootCommands(program, baselineHelp, selectedRootCommands, rootHelpText) {
+    const coreCommands = new Set(listPmCommandsForTier("core"));
     const budgetHelp = program.createHelp();
     budgetHelp.prepareContext({
         error: false,
@@ -930,6 +952,20 @@ export function attachRichHelpText(program, argv = process.argv.slice(2)) {
             selectedRootCommands.delete(candidate);
         }
     }
+}
+/** Implements attach rich help text for the public runtime surface of this module. */
+export function attachRichHelpText(program, argv = process.argv.slice(2)) {
+    const baselineHelp = program.createHelp();
+    const fullDiscovery = isFullHelpDiscovery(argv);
+    const selectedRootCommands = new Set();
+    configureTieredHelpVisibility(program, baselineHelp, fullDiscovery, selectedRootCommands);
+    const detailMode = resolveHelpDetailMode(argv);
+    const rootHelpText = renderHelpBundle(ROOT_HELP_BUNDLE, detailMode);
+    program.addHelpText("after", rootHelpText);
+    if (fullDiscovery) {
+        program.addHelpText("after", renderFullCommandAliasHelp());
+    }
+    selectBudgetedRootCommands(program, baselineHelp, selectedRootCommands, rootHelpText);
     for (const [commandPath, bundle] of Object.entries(HELP_BY_COMMAND_PATH)) {
         attachBundleByPath(program, commandPath, bundle, detailMode);
     }
@@ -963,4 +999,4 @@ export const _testOnly = {
     renderDetailedHelpBundle,
 };
 //# sourceMappingURL=help-content.js.map
-//# debugId=5ea35d21-cfe6-5138-9fdb-413083719924
+//# debugId=1399e88f-710a-5e5c-b4b3-70e35ec401cf

package/dist/cli/help-json-payload.d.ts

@@ -31,6 +31,12 @@ export interface HelpSubcommandSummary {
     tier: PmCommandVisibilityTier;
     /** Shared command capability family. */
     family: PmCommandCapabilityFamily;
+    /** Canonical command path when this row is an executable alias. */
+    alias_for?: string;
+    /** Compatibility lifecycle declared by the canonical alias contract. */
+    alias_lifecycle?: "permanent" | "deprecated";
+    /** True when callers should migrate from this executable spelling. */
+    deprecated?: true;
 }
 type ExtensionCommandSurface = Pick<ExtensionCommandHelpDescriptor, "tier" | "family">;
 declare function resolveExtensionCommandSurface(commandPath: string, descriptors: ReadonlyMap<string, ExtensionCommandHelpDescriptor>, allowDescendants?: boolean): ExtensionCommandSurface | undefined;
@@ -40,7 +46,7 @@ declare function buildOptionAliasMap(options: unknown[]): Map<string, string[]>;
 declare function buildHelpOptionSummaries(command: Command): HelpOptionSummary[];
 declare function compactHelpOptionAliases(options: HelpOptionSummary[]): HelpOptionSummary[];
 declare function buildHelpArgumentSummaries(command: Command): HelpArgumentSummary[];
-declare function buildHelpSubcommandSummaries(command: Command, extensionDescriptors?: ReadonlyMap<string, ExtensionCommandHelpDescriptor>): HelpSubcommandSummary[];
+declare function buildHelpSubcommandSummaries(command: Command, extensionDescriptors?: ReadonlyMap<string, ExtensionCommandHelpDescriptor>, includeAll?: boolean): HelpSubcommandSummary[];
 interface PositionalActionHelpProjection {
     arguments: HelpArgumentSummary[];
     options: HelpOptionSummary[];
@@ -48,7 +54,7 @@ interface PositionalActionHelpProjection {
     usage: string;
 }
 /** Build the command/action structural view shared by every JSON help field. */
-declare function buildPositionalActionHelpProjection(action: PmPositionalActionContract | undefined, targetCommand: Command, resolvedPath: string, allOptions: HelpOptionSummary[], extensionDescriptors?: ReadonlyMap<string, ExtensionCommandHelpDescriptor>): PositionalActionHelpProjection;
+declare function buildPositionalActionHelpProjection(action: PmPositionalActionContract | undefined, targetCommand: Command, resolvedPath: string, allOptions: HelpOptionSummary[], extensionDescriptors?: ReadonlyMap<string, ExtensionCommandHelpDescriptor>, includeAll?: boolean): PositionalActionHelpProjection;
 declare function buildJsonHelpPayload(rootProgram: Command, targetCommand: Command, argv: string[], requestedPath: string[], extensionDescriptors: ReadonlyMap<string, ExtensionCommandHelpDescriptor>): Record<string, unknown>;
 /** Implements maybe render bootstrap json help for the public runtime surface of this module. */
 export declare function maybeRenderBootstrapJsonHelp(rootProgram: Command, argv: string[], extensionDescriptors: ReadonlyMap<string, ExtensionCommandHelpDescriptor>): Promise<boolean>;