@unbrained/pm-cli 2026.8.23 → 2026.8.24

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.23"
+    "version": "2026.8.24"
   },
   "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.23",
+      "version": "2026.8.24",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 2026.8.24 - 2026-08-24
+
+### Fixed
+
+- Structured release-failure causes are preserved in blocked-release alerts ([pm-x63izf](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-x63izf.toon))
+- Bulk writes accept newline/comma IDs from argv, stdin, and @path with effect-aware exits ([pm-3oq022](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-3oq022.toon))
+- update-many --dry-run allows filter-only preview for review and bulk-selection workflows ([pm-kexu](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-kexu.toon))
+- Releases from the default branch are supported with analyzer evidence ([pm-u1baah](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-u1baah.toon))
+
+### Other
+
+- Uniform stdin convention: body-file and annotation --file flags accept '-' for stdin ([pm-iktj](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-iktj.toon))
+- Single source of surface tiering: one contract-declared tier per command drives CLI help, MCP tool profiles, completions, and docs together ([pm-kxci8x](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-kxci8x.toon))
+
 ## 2026.8.23 - 2026-08-23
 
 ### Added
@@ -109,7 +123,6 @@
 
 ### Fixed
 
-- A commit pushed directly to the default branch can never be released: both analyzer-evidence fallbacks presuppose a pull request, and nothing declares that precondition ([pm-u1baah](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-u1baah.toon))
 - GH-1052: typed fail-closed whole-list SDK primitive ([pm-y4aaol](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-y4aaol.toon))
 - Packed Bun SDK import fails on node:module stripTypeScriptTypes ([pm-ikj8ve](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ikj8ve.toon))
 - GH-1051: package catalog rejects universal output-budget controls ([pm-2firut](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-2firut.toon))

package/dist/cli/description-stdin.js

@@ -4,14 +4,15 @@
  * Resolves the shared create/update description stdin sentinel.
  */
 
-!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]="e6b32b75-4618-5270-a79a-8564e97c7f3b")}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]="c55461f3-15d7-51f4-9e41-f71ce693b7b8")}catch(e){}}();
 import { createStdinTokenResolver } from "../sdk/runtime-primitives.js";
 /** Replace a description stdin sentinel with the complete standard-input payload. */
 export async function resolveDescriptionStdin(options) {
-    if (options.description === "-") {
+    if (typeof options.description === "string" &&
+        options.description.trim() === "-") {
         options.description =
-            (await createStdinTokenResolver().resolveValue("-", "--description")) ?? "";
+            (await createStdinTokenResolver().resolveValue(options.description, "--description")) ?? "";
     }
 }
 //# sourceMappingURL=description-stdin.js.map
-//# debugId=e6b32b75-4618-5270-a79a-8564e97c7f3b
+//# debugId=c55461f3-15d7-51f4-9e41-f71ce693b7b8

package/dist/cli/extension-command-help.d.ts

@@ -5,6 +5,7 @@
  */
 import { Command } from "commander";
 import { type FlagDefinition, type RegisteredExtensionCommandDefinition, type RegisteredExtensionFlagDefinitions } from "../sdk/runtime-primitives.js";
+import type { PmCommandCapabilityFamily, PmCommandVisibilityTier } from "../sdk/agent-capability-contracts.js";
 /** Documents the extension command argument help descriptor payload exchanged by command, SDK, and package integrations. */
 export interface ExtensionCommandArgumentHelpDescriptor {
     /** Value that configures or reports name for this contract. */
@@ -34,6 +35,10 @@ export interface ExtensionCommandHelpDescriptor {
     arguments: ExtensionCommandArgumentHelpDescriptor[];
     /** Value that configures or reports flags for this contract. */
     flags: FlagDefinition[];
+    /** Minimum agent surface tier declared by the package. */
+    tier: PmCommandVisibilityTier;
+    /** Capability family declared by the package. */
+    family: PmCommandCapabilityFamily;
     /** Value that configures or reports source for this contract. */
     source?: {
         layer: "global" | "project";

package/dist/cli/extension-command-help.js

@@ -4,7 +4,7 @@
  * Provides CLI runtime support for Extension Command Help.
  */
 
-!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]="45f3bebb-c075-5573-97bc-b573ae4d2d76")}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]="99d39b7c-ec26-5c95-85c0-ac28112a6fe6")}catch(e){}}();
 import { Option } from "commander";
 /** Implements normalize extension command path for the public runtime surface of this module. */
 export function normalizeExtensionCommandPath(commandPath) {
@@ -227,6 +227,8 @@ function collectExtensionDefinitionsByCommand(commandDefinitions) {
             failure_hints: normalizeExtensionCommandStringList(definition.failure_hints),
             arguments: normalizeExtensionCommandArguments(definition.arguments),
             flags: [],
+            tier: definition.tier ?? "standard",
+            family: definition.family ?? "extensions",
             source: {
                 layer: definition.layer,
                 name: definition.name,
@@ -300,6 +302,8 @@ export function collectExtensionCommandHelpDescriptors(commandHandlers, commandD
             failure_hints: [],
             arguments: [],
             flags,
+            tier: "standard",
+            family: "extensions",
         });
     }
     return descriptors;
@@ -630,4 +634,4 @@ export function reportExtensionCommandCollision(activationWarnings, report, warn
     report(`[pm] warning: ${warning}; core command preserved. Rename or namespace the extension command alias.`);
 }
 //# sourceMappingURL=extension-command-help.js.map
-//# debugId=45f3bebb-c075-5573-97bc-b573ae4d2d76
+//# debugId=99d39b7c-ec26-5c95-85c0-ac28112a6fe6

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

@@ -4,6 +4,11 @@
  * Provides CLI runtime support for Help Content.
  */
 import { Command } from "commander";
+import { type PmCommandVisibilityTier } from "../sdk/agent-capability-contracts.js";
+/** Attach a package command's declared tier to its Commander presentation node. */
+export declare function setPmCommandHelpVisibilityTier(command: Command, tier: PmCommandVisibilityTier): void;
+/** Read presentation metadata attached to a package-created Commander node. */
+export declare function getPmCommandHelpVisibilityTier(command: Command): PmCommandVisibilityTier | undefined;
 /** Documents the help bundle payload exchanged by command, SDK, and package integrations. */
 export interface HelpBundle {
     /** Value that configures or reports why for this contract. */

package/dist/cli/help-content.js

@@ -1,7 +1,17 @@
 
-!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]="9cf83881-9464-5c18-b196-ee669057a873")}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]="5ea35d21-cfe6-5138-9fdb-413083719924")}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";
+const COMMAND_HELP_VISIBILITY_TIERS = new WeakMap();
+/** Attach a package command's declared tier to its Commander presentation node. */
+export function setPmCommandHelpVisibilityTier(command, tier) {
+    COMMAND_HELP_VISIBILITY_TIERS.set(command, tier);
+}
+/** Read presentation metadata attached to a package-created Commander node. */
+export function getPmCommandHelpVisibilityTier(command) {
+    return COMMAND_HELP_VISIBILITY_TIERS.get(command);
+}
 // Compact help/narrative surfaces show at most the first example. Centralizing this
 // keeps the empty-examples guard in one place for renderCompactHelpBundle and
 // resolveHelpNarrative (both must degrade to an empty list rather than [undefined]).
@@ -875,8 +885,51 @@ export function resolveHelpNarrative(commandPath, 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"));
+    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;
+            }
+            return visible.filter((candidate) => selectedRootCommands.has(candidate));
+        },
+        visibleOptions(command) {
+            const visible = baselineHelp.visibleOptions(command);
+            return command === program
+                ? visible.filter((option) => coreOptions.has(option.flags))
+                : visible;
+        },
+    });
     const detailMode = resolveHelpDetailMode(argv);
-    program.addHelpText("after", renderHelpBundle(ROOT_HELP_BUNDLE, detailMode));
+    const rootHelpText = renderHelpBundle(ROOT_HELP_BUNDLE, detailMode);
+    program.addHelpText("after", rootHelpText);
+    const budgetHelp = program.createHelp();
+    budgetHelp.prepareContext({
+        error: false,
+        helpWidth: 80,
+        outputHasColors: false,
+    });
+    const renderBudgetHelp = () => `${budgetHelp.formatHelp(program, budgetHelp)}${rootHelpText}\n`;
+    const rootCandidates = baselineHelp.visibleCommands(program);
+    for (const candidate of rootCandidates) {
+        const declaredTier = getPmCommandHelpVisibilityTier(candidate);
+        if (declaredTier === undefined &&
+            (candidate.name() === "help" || coreCommands.has(candidate.name()))) {
+            selectedRootCommands.add(candidate);
+        }
+    }
+    for (const candidate of rootCandidates) {
+        if (getPmCommandHelpVisibilityTier(candidate) !== "core")
+            continue;
+        selectedRootCommands.add(candidate);
+        if (!measurePmCoreHelp(renderBudgetHelp()).within_budget) {
+            selectedRootCommands.delete(candidate);
+        }
+    }
     for (const [commandPath, bundle] of Object.entries(HELP_BY_COMMAND_PATH)) {
         attachBundleByPath(program, commandPath, bundle, detailMode);
     }
@@ -910,4 +963,4 @@ export const _testOnly = {
     renderDetailedHelpBundle,
 };
 //# sourceMappingURL=help-content.js.map
-//# debugId=9cf83881-9464-5c18-b196-ee669057a873
+//# debugId=5ea35d21-cfe6-5138-9fdb-413083719924

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

@@ -32,13 +32,15 @@ export interface HelpSubcommandSummary {
     /** Shared command capability family. */
     family: PmCommandCapabilityFamily;
 }
+type ExtensionCommandSurface = Pick<ExtensionCommandHelpDescriptor, "tier" | "family">;
+declare function resolveExtensionCommandSurface(commandPath: string, descriptors: ReadonlyMap<string, ExtensionCommandHelpDescriptor>, allowDescendants?: boolean): ExtensionCommandSurface | undefined;
 declare function resolveCommandFromPathTokens(root: Command, pathTokens: string[]): Command | null;
 declare function readOptionAttributeName(option: unknown): string | null;
 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): HelpSubcommandSummary[];
+declare function buildHelpSubcommandSummaries(command: Command, extensionDescriptors?: ReadonlyMap<string, ExtensionCommandHelpDescriptor>): HelpSubcommandSummary[];
 interface PositionalActionHelpProjection {
     arguments: HelpArgumentSummary[];
     options: HelpOptionSummary[];
@@ -46,7 +48,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[]): PositionalActionHelpProjection;
+declare function buildPositionalActionHelpProjection(action: PmPositionalActionContract | undefined, targetCommand: Command, resolvedPath: string, allOptions: HelpOptionSummary[], extensionDescriptors?: ReadonlyMap<string, ExtensionCommandHelpDescriptor>): 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>;
@@ -66,5 +68,6 @@ export declare const _testOnly: {
     compactHelpOptionAliases: typeof compactHelpOptionAliases;
     readOptionAttributeName: typeof readOptionAttributeName;
     resolveCommandFromPathTokens: typeof resolveCommandFromPathTokens;
+    resolveExtensionCommandSurface: typeof resolveExtensionCommandSurface;
 };
 export {};

package/dist/cli/help-json-payload.js

@@ -1,9 +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]="abdb8d3e-8c1b-511e-b25b-220d5a40ae3f")}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]="26c3efa6-b820-5370-b0ab-65b08bc007ec")}catch(e){}}();
 import { hasSubcommandFlagContractsForCommand, PM_CORE_COMMAND_NAMES, } from "../sdk/cli-contracts.js";
 import { commandOptionFlagLabel, resolveCommandOptionPolicyState, resolveTypeDefinition, EXIT_CODE, printError, writeStdout, } from "../sdk/runtime-primitives.js";
 import { buildDynamicExtensionHelpOptionSummaries, mergeHelpOptionSummaries, findCommandByPath, findDirectChildCommand, commandAliases, } from "./extension-command-help.js";
-import { normalizeHelpCommandPath, resolveHelpDetailMode, resolveHelpNarrative, } from "./help-content.js";
+import { getPmCommandHelpVisibilityTier, normalizeHelpCommandPath, resolveHelpDetailMode, resolveHelpNarrative, } from "./help-content.js";
 import { getCommandPath } from "./registration-helpers.js";
 import { parseBootstrapGlobalOptions, parseBootstrapHelpRequest, parseBootstrapCommandName, parseBootstrapTypeValue, } from "./bootstrap-args.js";
 import { extractProvidedOptionFlags, renderPmCommand } from "./argv-utils.js";
@@ -12,6 +12,32 @@ import { BUILTIN_TYPE_HELP_VALUES, buildUnknownCommandGuidanceFromRuntime, } fro
 import { resolveCreateExplicitEmptyFlag } from "../sdk/agent/create-option-policy.js";
 import { formatPmPositionalActionFlagTip, PM_POSITIONAL_ACTION_CONTRACTS, resolvePmPositionalActionContract, } from "../sdk/cli-contracts/grammar-contracts.js";
 import { resolvePmCommandCapabilityFamily, resolvePmCommandVisibilityTier, } from "../sdk/agent-capability-contracts.js";
+const EXTENSION_TIER_ORDER = {
+    core: 0,
+    standard: 1,
+    full: 2,
+    internal: 3,
+};
+function resolveExtensionCommandSurface(commandPath, descriptors, allowDescendants = true) {
+    const exact = descriptors.get(commandPath);
+    if (exact)
+        return exact;
+    if (!allowDescendants)
+        return undefined;
+    const descendants = [...descriptors.entries()]
+        .filter(([path]) => path.startsWith(`${commandPath} `))
+        .map(([, descriptor]) => descriptor);
+    if (descendants.length === 0)
+        return undefined;
+    const tier = descendants.reduce((selected, descriptor) => EXTENSION_TIER_ORDER[descriptor.tier] < EXTENSION_TIER_ORDER[selected]
+        ? descriptor.tier
+        : selected, "internal");
+    const families = new Set(descendants.map(({ family }) => family));
+    return {
+        tier,
+        family: families.size === 1 ? descendants[0].family : "extensions",
+    };
+}
 function resolveCommandFromPathTokens(root, pathTokens) {
     if (pathTokens.length === 0) {
         return root;
@@ -180,20 +206,23 @@ function buildHelpArgumentSummaries(command) {
         };
     });
 }
-function buildHelpSubcommandSummaries(command) {
+function buildHelpSubcommandSummaries(command, extensionDescriptors = new Map()) {
     return command
         .createHelp()
         .visibleCommands(command)
         .filter((entry) => entry.name() !== "help" || command.parent === null)
         .map((entry) => {
-        const rootCommand = normalizeHelpCommandPath(getCommandPath(entry))
-            .split(" ")[0];
+        const commandPath = normalizeHelpCommandPath(getCommandPath(entry));
+        const rootCommand = commandPath.split(" ")[0];
+        const extensionDescriptor = resolveExtensionCommandSurface(commandPath, extensionDescriptors, getPmCommandHelpVisibilityTier(entry) !== undefined);
         return {
             name: entry.name().trim(),
             aliases: commandAliases(entry),
             description: entry.description().trim(),
-            tier: resolvePmCommandVisibilityTier(rootCommand),
-            family: resolvePmCommandCapabilityFamily(rootCommand),
+            tier: extensionDescriptor?.tier ??
+                resolvePmCommandVisibilityTier(rootCommand),
+            family: extensionDescriptor?.family ??
+                resolvePmCommandCapabilityFamily(rootCommand),
         };
     })
         .sort((left, right) => left.name.localeCompare(right.name));
@@ -223,11 +252,22 @@ function buildJsonHelpNarrative(detailMode, fallbackNarrative, extensionDescript
         detail_mode: detailMode,
     };
 }
+function resolveJsonHelpVisibilityTier(rootCommandPath, extensionDescriptor) {
+    if (rootCommandPath === undefined)
+        return null;
+    return (extensionDescriptor?.tier ?? resolvePmCommandVisibilityTier(rootCommandPath));
+}
+function resolveJsonHelpCapabilityFamily(rootCommandPath, extensionDescriptor) {
+    if (rootCommandPath === undefined)
+        return null;
+    return (extensionDescriptor?.family ??
+        resolvePmCommandCapabilityFamily(rootCommandPath));
+}
 /** Build the command/action structural view shared by every JSON help field. */
-function buildPositionalActionHelpProjection(action, targetCommand, resolvedPath, allOptions) {
+function buildPositionalActionHelpProjection(action, targetCommand, resolvedPath, allOptions, extensionDescriptors = new Map()) {
     if (!action) {
         const argumentsList = buildHelpArgumentSummaries(targetCommand);
-        const registeredSubcommands = buildHelpSubcommandSummaries(targetCommand);
+        const registeredSubcommands = buildHelpSubcommandSummaries(targetCommand, extensionDescriptors);
         const registeredSubcommandNames = new Set(registeredSubcommands.map(({ name }) => name));
         return {
             arguments: argumentsList,
@@ -289,21 +329,20 @@ function buildJsonHelpPayload(rootProgram, targetCommand, argv, requestedPath, e
     const extensionDescriptor = commandPath
         ? extensionDescriptors.get(commandPath)
         : undefined;
+    const extensionSurface = commandPath
+        ? resolveExtensionCommandSurface(commandPath, extensionDescriptors, getPmCommandHelpVisibilityTier(targetCommand) !== undefined)
+        : undefined;
     const narrative = buildJsonHelpNarrative(detailMode, fallbackNarrative, extensionDescriptor);
     const allOptionSummaries = compactHelpOptionAliases(mergeHelpOptionSummaries(buildHelpOptionSummaries(targetCommand), buildDynamicExtensionHelpOptionSummaries(extensionDescriptor)));
-    const projection = buildPositionalActionHelpProjection(positionalAction, targetCommand, projectedPath, allOptionSummaries);
+    const projection = buildPositionalActionHelpProjection(positionalAction, targetCommand, projectedPath, allOptionSummaries, extensionDescriptors);
     return {
         format: "pm_help_v1",
         detail_mode: detailMode,
         root_command: rootProgram.name(),
         requested_path: requestedPath,
         resolved_path: projectedPath.length > 0 ? projectedPath : rootProgram.name(),
-        visibility_tier: rootCommandPath === undefined
-            ? null
-            : resolvePmCommandVisibilityTier(rootCommandPath),
-        capability_family: rootCommandPath === undefined
-            ? null
-            : resolvePmCommandCapabilityFamily(rootCommandPath),
+        visibility_tier: resolveJsonHelpVisibilityTier(rootCommandPath, extensionSurface),
+        capability_family: resolveJsonHelpCapabilityFamily(rootCommandPath, extensionSurface),
         description: positionalAction?.description ?? targetCommand.description(),
         usage: projection.usage,
         intent: positionalAction?.description ?? narrative.intent,
@@ -487,6 +526,7 @@ export const _testOnly = {
     compactHelpOptionAliases,
     readOptionAttributeName,
     resolveCommandFromPathTokens,
+    resolveExtensionCommandSurface,
 };
 //# sourceMappingURL=help-json-payload.js.map
-//# debugId=abdb8d3e-8c1b-511e-b25b-220d5a40ae3f
+//# debugId=26c3efa6-b820-5370-b0ab-65b08bc007ec

package/dist/cli/main.d.ts

@@ -157,6 +157,8 @@ declare function loadRuntimeExtensionCommandDescriptorsForRecovery(pmRoot: strin
 declare function executeRegisteredRuntimeMigrations(migrations: RegisteredExtensionSchemaMigrationDefinition[], pmRoot: string): Promise<string[]>;
 declare function runRequiredExtensionCommand(command: Command, options: Record<string, unknown>, globalOptions: GlobalOptions, extensionFlagDefinitions?: LooseCommandFlagDefinition[]): Promise<unknown>;
 declare function wrapProgramActionsForExtensionHandlers(rootProgram: Command): void;
+/** Apply descendant-derived visibility to every generated extension namespace. */
+declare function applyDynamicExtensionRootHelpVisibility(rootProgram: Command, preexistingTopLevelCommands: ReadonlySet<string>, descriptors: ReadonlyMap<string, ExtensionCommandHelpDescriptor>): void;
 declare function registerDynamicExtensionCommandPaths(rootProgram: Command, invocationArgv: string[]): Promise<void>;
 interface CoreCommandRegistrationSelection {
     setup: boolean;
@@ -230,6 +232,7 @@ export declare function runPmCli(rawArgv?: string[]): Promise<void>;
 /** Public contract for test only, shared by SDK and presentation-layer consumers. */
 export declare const _testOnly: {
     activationCommandMatchesProbe: typeof activationCommandMatchesProbe;
+    applyDynamicExtensionRootHelpVisibility: typeof applyDynamicExtensionRootHelpVisibility;
     bootstrapProfileEnabled: typeof bootstrapProfileEnabled;
     buildBootstrapActivationProbe: typeof buildBootstrapActivationProbe;
     buildPostActionTelemetryOutcome: typeof buildPostActionTelemetryOutcome;

package/dist/cli/main.js

@@ -3,7 +3,7 @@
  * @module cli/main
  */
 
-!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]="7289d222-cf1f-5fa5-ac8a-d690b6012e39")}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]="ffd55bde-cc30-529f-a6f9-ec43abe4efba")}catch(e){}}();
 import { Command } from "commander";
 import { activateExtensions, clearActiveExtensionHooks, createCoreCommandHookContext, resetActiveExtensionRuntimeState, createEmptyExtensionRegistrationRegistry, discoverExtensions, getActiveCommandResult, getActiveExtensionRegistrations, loadExtensions, consumeAfterCommandAffectedItems, runActiveCommandHandler, runActiveParserOverride, runActivePreflightOverride, runAfterCommandHooks, runBeforeCommandHooks, setActiveCommandResult, setActiveCommandContext, setActiveExtensionCommands, setActiveExtensionHooks, setActiveExtensionParsers, setActiveExtensionPreflight, setActiveExtensionRegistrations, setActiveExtensionRenderers, setActiveExtensionServices, pathExists, resolvePmCliVersion, resolvePmPackageRootFromModule, resolveItemTypeRegistry, resolveRuntimeFieldRegistry, EXIT_CODE, resolveTelemetryErrorCategory, PmCliError, asRecordOrNull, printError, printResult, maybeRunFirstUseTelemetryPrompt, emitTelemetryErrorEvent, startTelemetryCommand, deriveTelemetryCommandResolution, sentryCaptureCliError, sentryFinishCommandSpan, sentryFlush, sentryLogCliUsageError, sentrySetCommandContext, sentryStartCommandSpan, ensureSentryInit, getSettingsPath, resolvePmRoot, readSettings, readSettingsWithMetadata, runWithWorkspaceHarnessSignalDescriptors, createLazyModule, } from "../sdk/runtime-primitives.js";
 import { runWithReproducibleProcessEnvironment } from "../sdk/reproducibility/process.js";
@@ -11,7 +11,7 @@ import { resolveSubcommandFlagContractsForCommand } from "../sdk/cli-contracts.j
 import { createExtensionCommandSdk } from "../sdk/extension-command-context.js";
 import { PmClient } from "../sdk/runtime.js";
 import { coerceLooseCommandOptionsWithFlagDefinitions, collectLooseCommandOptionKeysForDefinitions, collectLoosePositionalArgs, parseLooseCommandOptions, stripLooseCommandOptionTokens, validateLooseCommandOptionsWithFlagDefinitions, } from "./extension-command-options.js";
-import { attachRichHelpText } from "./help-content.js";
+import { attachRichHelpText, setPmCommandHelpVisibilityTier, } from "./help-content.js";
 import { finishActiveTelemetryCommand, recordAfterCommandContextUsage } from "./after-command-context-usage.js";
 import { extractProvidedOptionFlags, normalizeLongOptionFlag, redactSensitiveCommandArgs, renderPmCommand, } from "./argv-utils.js";
 import { classifyCommanderError, classifyPmCliError, classifyUnknownError, formatPmCliErrorForDisplay, formatPmCliErrorForJson, formatUnknownErrorForJson, projectLeanErrorEnvelope, } from "./error-guidance.js";
@@ -1508,6 +1508,28 @@ function attachDynamicExtensionHelp(command, descriptor, flagHelp, metadataHelp)
 }
 /* v8 ignore stop */
 /* c8 ignore start */
+/** Apply descendant-derived visibility to every generated extension namespace. */
+function applyDynamicExtensionRootHelpVisibility(rootProgram, preexistingTopLevelCommands, descriptors) {
+    const tierRank = { core: 0, standard: 1, full: 2, internal: 3 };
+    const applyVisibility = (command, pathParts) => {
+        const commandPath = pathParts.join(" ");
+        const matchingDescriptors = [...descriptors.entries()]
+            .filter(([path]) => path === commandPath || path.startsWith(`${commandPath} `))
+            .map(([, descriptor]) => descriptor);
+        const tier = matchingDescriptors.length === 0
+            ? "standard"
+            : matchingDescriptors.reduce((selected, descriptor) => tierRank[descriptor.tier] < tierRank[selected] ? descriptor.tier : selected, "internal");
+        setPmCommandHelpVisibilityTier(command, tier);
+        for (const child of command.commands) {
+            applyVisibility(child, [...pathParts, child.name()]);
+        }
+    };
+    for (const command of rootProgram.commands) {
+        if (!preexistingTopLevelCommands.has(command.name())) {
+            applyVisibility(command, [command.name()]);
+        }
+    }
+}
 async function registerDynamicExtensionCommandPaths(rootProgram, invocationArgv) {
     const bootstrapGlobalOptions = parseBootstrapGlobalOptions(invocationArgv);
     const pmRoot = resolvePmRoot(process.cwd(), bootstrapGlobalOptions.path);
@@ -1552,6 +1574,7 @@ async function registerDynamicExtensionCommandPaths(rootProgram, invocationArgv)
     activeRuntimeExtensionCommandDescriptors = new Map(snapshot.commandDescriptors);
     await maybeAttachCreateUpdatePolicyHelpText(rootProgram, pmRoot, invocationArgv, snapshot.registrations, snapshot.settings);
     const commandPaths = collectSafeExtensionCommandPaths(rootProgram, snapshot.commandHandlers, snapshot.commandDescriptors, snapshot.commandAliases, (warning) => reportExtensionCommandCollision(snapshot.activationWarnings, printError, warning));
+    const preexistingTopLevelCommands = new Set(rootProgram.commands.map((command) => command.name()));
     const registerCommandPath = (commandPath) => {
         const pathParts = commandPath.split(" ").filter((part) => part.length > 0);
         const descriptor = snapshot.commandDescriptors.get(commandPath);
@@ -1609,6 +1632,7 @@ async function registerDynamicExtensionCommandPaths(rootProgram, invocationArgv)
     for (const commandPath of commandPaths) {
         registerCommandPath(commandPath);
     }
+    applyDynamicExtensionRootHelpVisibility(rootProgram, preexistingTopLevelCommands, snapshot.commandDescriptors);
 }
 /* c8 ignore stop */
 /* c8 ignore start */
@@ -2470,6 +2494,7 @@ export async function runPmCli(rawArgv = process.argv.slice(2)) {
 /** Public contract for test only, shared by SDK and presentation-layer consumers. */
 export const _testOnly = {
     activationCommandMatchesProbe,
+    applyDynamicExtensionRootHelpVisibility,
     bootstrapProfileEnabled,
     buildBootstrapActivationProbe,
     buildPostActionTelemetryOutcome,
@@ -2558,4 +2583,4 @@ export const _testOnly = {
     wrapThrownErrorForSentry,
 };
 //# sourceMappingURL=main.js.map
-//# debugId=7289d222-cf1f-5fa5-ac8a-d690b6012e39
+//# debugId=ffd55bde-cc30-529f-a6f9-ec43abe4efba

package/dist/cli/register-annotations.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]="616fff4b-f86e-54e5-b569-0b9894da5221")}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]="79bf0b3f-ad63-5d9f-9911-d5a142214ac1")}catch(e){}}();
 import { EXIT_CODE, PmCliError, } from "../sdk/runtime-primitives.js";
 import { renderPmCommand } from "../sdk/command-line.js";
 import { runComments } from "./commands/comments.js";
@@ -194,7 +194,7 @@ export function registerAnnotationCommands(program, parsePositiveInteger) {
         .argument("[text]", "Optional comment text shorthand (equivalent to --add)")
         .option("--add <text>", "Add one comment entry (plain text fallback, text=<value>, markdown pairs, or - for stdin; CSV-like key fragments are preserved as plain text unless text is explicit)")
         .option("--stdin", "Read comment text from stdin (supports multiline markdown)")
-        .option("--file <path>", "Read comment text from file (supports multiline markdown)")
+        .option("--file <path>", "Read comment text from a file or stdin (-)")
         .option("--edit <index>", "Replace the comment at 1-based <index> (replacement text from positional [text], --add, --stdin, or --file)", parsePositiveInteger("--edit"))
         .option("--delete <index>", "Delete the comment at 1-based <index>", parsePositiveInteger("--delete"))
         .option("--limit <n>", "Return only latest n comments")
@@ -214,7 +214,7 @@ export function registerAnnotationCommands(program, parsePositiveInteger) {
         .option("--note <text>", "Alias for --add")
         .option("--add-json <json>", "Append a merge-safe JSON event")
         .option("--stdin", "Read note text from stdin")
-        .option("--file <path>", "Read note text from a UTF-8 file")
+        .option("--file <path>", "Read note from file or stdin (-)")
         .option("--edit <index>", "Replace a 1-based note using the selected text input", parsePositiveInteger("--edit"))
         .option("--delete <index>", "Delete the note at 1-based <index>", parsePositiveInteger("--delete"))
         .option("--limit <n>", "Return only latest n notes")
@@ -233,7 +233,7 @@ export function registerAnnotationCommands(program, parsePositiveInteger) {
         .argument("[text]", "Optional learning text shorthand (equivalent to --add; use - for stdin)")
         .option("--add <text>", "Add one learning entry (plain text fallback, text=<value>, markdown pairs, or - for stdin; CSV-like key fragments are preserved as plain text unless text is explicit)")
         .option("--stdin", "Read learning text from stdin (supports multiline markdown)")
-        .option("--file <path>", "Read learning text from file (supports multiline markdown)")
+        .option("--file <path>", "Read learning text from a file or stdin (-)")
         .option("--edit <index>", "Replace the learning at 1-based <index> (replacement text from positional [text], --add, --stdin, or --file)", parsePositiveInteger("--edit"))
         .option("--delete <index>", "Delete the learning at 1-based <index>", parsePositiveInteger("--delete"))
         .option("--limit <n>", "Return only latest n learnings")
@@ -245,4 +245,4 @@ export function registerAnnotationCommands(program, parsePositiveInteger) {
         .action(runLearningsAction);
 }
 //# sourceMappingURL=register-annotations.js.map
-//# debugId=616fff4b-f86e-54e5-b569-0b9894da5221
+//# debugId=79bf0b3f-ad63-5d9f-9911-d5a142214ac1