@unbrained/pm-cli 2026.8.10 → 2026.8.12

package/dist/cli/commander-usage.js

@@ -1,12 +1,12 @@
 
-!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]="a327ea76-ca7d-5f8f-aa2d-2f6f43052913")}catch(e){}}();
-import { pathExists, resolveItemTypeRegistry, EXIT_CODE, getSettingsPath, resolvePmRoot, readSettings, getActiveExtensionRegistrations, runActiveServiceOverride, levenshteinDistanceWithinLimit, } from "../sdk/runtime-primitives.js";
+!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]="05cf369c-7529-57ab-984a-f5505cc9c0c9")}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";
 import { formatCommanderErrorForDisplay, formatCommanderErrorForJson, projectLeanErrorEnvelope, } from "./error-guidance.js";
 import { normalizeHelpCommandPath } from "./help-content.js";
 import { getCommandPath } from "./registration-helpers.js";
-import { EXECUTABLE_COMMAND_ALIASES, normalizeBootstrapInvocation, parseBootstrapHelpRequest, parseBootstrapGlobalOptions, parseBootstrapCommandName, } from "./bootstrap-args.js";
+import { EXECUTABLE_COMMAND_ALIASES, findBootstrapCommandTokenIndex, normalizeBootstrapInvocation, parseBootstrapHelpRequest, parseBootstrapGlobalOptions, parseBootstrapCommandName, } from "./bootstrap-args.js";
 import { extractProvidedOptionFlags, normalizeLongFlag, renderPmCommand, } from "./argv-utils.js";
 import { normalizeExtensionNameForMatch } from "./commands/extension/shared.js";
 import { rankCommandPaths } from "../sdk/agent/command-suggestions.js";
@@ -54,6 +54,23 @@ const SEMANTIC_UNKNOWN_OPTION_SUGGESTIONS = {
         "--tag": ["--tags"],
     },
 };
+const SCHEMA_SUBCOMMAND_VALUES = [
+    "add-field",
+    "add-status",
+    "add-type",
+    "apply-preset",
+    "list",
+    "list-fields",
+    "remap-status",
+    "remove-field",
+    "remove-status",
+    "remove-type",
+    "rename-field",
+    "rename-type",
+    "show",
+    "show-field",
+    "show-status",
+];
 function getSemanticUnknownOptionSuggestions(commandName, unknownOption) {
     const commandSuggestions = SEMANTIC_UNKNOWN_OPTION_SUGGESTIONS[commandName];
     if (!commandSuggestions) {
@@ -335,9 +352,17 @@ function findOtherCommandsForFlag(unknownOption, currentCommand) {
         return [];
     }
     const normalizedCurrent = currentCommand?.trim().toLowerCase();
+    const currentFlags = new Set(collectKnownLongFlags(normalizedCurrent));
     return commands
         .filter((command) => command !== normalizedCurrent)
-        .slice(0, 3);
+        .map((command) => ({
+        command,
+        sharedFlagCount: collectKnownLongFlags(command).filter((flag) => currentFlags.has(flag)).length,
+    }))
+        .sort((left, right) => left.sharedFlagCount !== right.sharedFlagCount
+        ? right.sharedFlagCount - left.sharedFlagCount
+        : left.command.localeCompare(right.command))
+        .map(({ command }) => command);
 }
 function rewriteUnknownOptionArgv(argv, unknownOption, replacementFlag) {
     for (let index = 0; index < argv.length; index += 1) {
@@ -511,24 +536,46 @@ export function isKnownHelpCommandPath(root, commandPathTokens) {
     }
     return matchedAny;
 }
-async function resolveAllowedTypesForUsage(bootstrapGlobal) {
+async function resolveWorkspaceUsageContext(bootstrapGlobal, message, invocationArgv, commandName) {
     try {
         const pmRoot = resolvePmRoot(process.cwd(), bootstrapGlobal.path);
         if (!(await pathExists(getSettingsPath(pmRoot)))) {
-            return BUILTIN_TYPE_HELP_VALUES;
+            return { allowedTypes: BUILTIN_TYPE_HELP_VALUES };
         }
         const settings = await readSettings(pmRoot);
         const extensionRegistrations = bootstrapGlobal.noExtensions
             ? undefined
             : getActiveExtensionRegistrations();
         const typeRegistry = resolveItemTypeRegistry(settings, extensionRegistrations);
-        return typeRegistry.types.length > 0
-            ? typeRegistry.types.join("|")
-            : BUILTIN_TYPE_HELP_VALUES;
+        let verifiedCollectionItemId;
+        if (/too many arguments/i.test(message) &&
+            ["comments", "docs", "files", "learnings", "notes", "test"].includes(commandName ?? "")) {
+            const commandIndex = invocationArgv.findIndex((token) => token === commandName);
+            const candidate = invocationArgv[commandIndex + 2];
+            if (invocationArgv[commandIndex + 1]?.toLowerCase() === "add" &&
+                candidate !== undefined &&
+                !candidate.startsWith("-")) {
+                try {
+                    verifiedCollectionItemId = (await locateItem(pmRoot, candidate, settings.id_prefix, settings.item_format, typeRegistry.type_to_folder))?.id;
+                }
+                catch {
+                    // Usage rendering remains available when tracker storage is unreadable.
+                }
+            }
+        }
+        return {
+            allowedTypes: typeRegistry.types.length > 0
+                ? typeRegistry.types.join("|")
+                : BUILTIN_TYPE_HELP_VALUES,
+            pmRoot,
+            settings,
+            typeToFolder: typeRegistry.type_to_folder,
+            verifiedCollectionItemId,
+        };
     }
     catch {
         /* v8 ignore start -- defensive fallback for corrupted settings during usage-error rendering; command behavior is covered through normal settings paths */
-        return BUILTIN_TYPE_HELP_VALUES;
+        return { allowedTypes: BUILTIN_TYPE_HELP_VALUES };
         /* v8 ignore stop */
     }
 }
@@ -571,6 +618,35 @@ function resolveSuggestedRetryForMissingOption(message, invocationArgv) {
         requiredOptionToken,
     ]);
 }
+function resolveSplitSchemaSubcommand(message, invocationArgv) {
+    if (!/too many arguments/i.test(message)) {
+        return undefined;
+    }
+    if (parseBootstrapCommandName(invocationArgv) !== "schema") {
+        return undefined;
+    }
+    const schemaIndex = findBootstrapCommandTokenIndex(invocationArgv);
+    const verb = invocationArgv[schemaIndex + 1]?.trim().toLowerCase();
+    const noun = invocationArgv[schemaIndex + 2]?.trim().toLowerCase();
+    if (!verb || !noun) {
+        return undefined;
+    }
+    const joined = `${verb}-${noun}`;
+    if (!SCHEMA_SUBCOMMAND_VALUES.includes(joined)) {
+        return undefined;
+    }
+    const rewritten = [
+        ...invocationArgv.slice(0, schemaIndex + 1),
+        joined,
+        ...invocationArgv.slice(schemaIndex + 3),
+    ];
+    return {
+        unknownSubcommandPath: "schema",
+        unknownSubcommandToken: `${verb} ${noun}`,
+        unknownSubcommandAllowedValues: [...SCHEMA_SUBCOMMAND_VALUES],
+        suggestedRetryCommand: renderAttemptedCommand(rewritten),
+    };
+}
 /** Implements resolve commander usage context for the public runtime surface of this module. */
 export async function resolveCommanderUsageContext(error, rootProgram, extensionDescriptors, guidanceOverrides = {}) {
     const rawMessage = typeof error === "object" && error !== null
@@ -582,10 +658,14 @@ export async function resolveCommanderUsageContext(error, rootProgram, extension
     const commandName = parseBootstrapCommandName(invocationArgv);
     const attemptedCommand = renderAttemptedCommand(invocationArgv);
     const providedOptionFlags = extractProvidedOptionFlags(invocationArgv);
-    const allowedTypes = await resolveAllowedTypesForUsage(bootstrapGlobal);
+    const workspaceUsage = await resolveWorkspaceUsageContext(bootstrapGlobal, message, invocationArgv, commandName);
+    const allowedTypes = workspaceUsage.allowedTypes;
     const unknownCommandGuidance = buildUnknownCommandGuidanceFromRuntime(message, rootProgram, extensionDescriptors);
     const unknownOption = resolveUnknownOptionSuggestions(message, commandName);
-    const suggestedRetryCommand = resolveSuggestedRetryForUnknownOption(invocationArgv, unknownOption.match, unknownOption.suggestions) ?? resolveSuggestedRetryForMissingOption(message, invocationArgv);
+    const splitSchemaSubcommand = resolveSplitSchemaSubcommand(message, invocationArgv);
+    const suggestedRetryCommand = splitSchemaSubcommand?.suggestedRetryCommand ??
+        resolveSuggestedRetryForUnknownOption(invocationArgv, unknownOption.match, unknownOption.suggestions) ??
+        resolveSuggestedRetryForMissingOption(message, invocationArgv);
     return {
         message,
         commandName,
@@ -595,9 +675,15 @@ export async function resolveCommanderUsageContext(error, rootProgram, extension
         providedOptionFlags,
         unknownOptionSuggestions: unknownOption.suggestions,
         unknownOptionOtherCommands: unknownOption.otherCommands.length > 0
-            ? unknownOption.otherCommands
+            ? unknownOption.otherCommands.slice(0, 12)
+            : undefined,
+        unknownOptionOtherCommandsTotal: unknownOption.otherCommands.length > 0
+            ? unknownOption.otherCommands.length
             : undefined,
+        unknownOptionOtherCommandsTruncated: unknownOption.otherCommands.length > 12 || undefined,
         suggestedRetryCommand,
+        verifiedCollectionItemId: workspaceUsage.verifiedCollectionItemId,
+        ...splitSchemaSubcommand,
         ...unknownCommandGuidance,
         ...guidanceOverrides,
     };
@@ -605,7 +691,7 @@ export async function resolveCommanderUsageContext(error, rootProgram, extension
 /** Implements format commander usage message for the public runtime surface of this module. */
 export async function formatCommanderUsageMessage(error, rootProgram, extensionDescriptors, guidanceOverrides = {}) {
     const usageContext = await resolveCommanderUsageContext(error, rootProgram, extensionDescriptors, guidanceOverrides);
-    const { message, commandName, allowedTypes, unknownCommandExamples, unknownCommandNextSteps, attemptedCommand, normalizedInvocationArgs, providedOptionFlags, unknownOptionSuggestions, unknownOptionOtherCommands, suggestedRetryCommand, failedExtensions, } = usageContext;
+    const { message, commandName, allowedTypes, unknownCommandExamples, unknownCommandNextSteps, attemptedCommand, normalizedInvocationArgs, providedOptionFlags, unknownOptionSuggestions, unknownOptionOtherCommands, unknownOptionOtherCommandsTotal, unknownOptionOtherCommandsTruncated, unknownSubcommandPath, unknownSubcommandToken, unknownSubcommandAllowedValues, suggestedRetryCommand, verifiedCollectionItemId, failedExtensions, } = usageContext;
     const formatted = formatCommanderErrorForDisplay(message, commandName, allowedTypes, {
         unknownCommandExamples,
         unknownCommandNextSteps,
@@ -614,7 +700,13 @@ export async function formatCommanderUsageMessage(error, rootProgram, extensionD
         providedOptionFlags,
         unknownOptionSuggestions,
         unknownOptionOtherCommands,
+        unknownOptionOtherCommandsTotal,
+        unknownOptionOtherCommandsTruncated,
+        unknownSubcommandPath,
+        unknownSubcommandToken,
+        unknownSubcommandAllowedValues,
         suggestedRetryCommand,
+        verifiedCollectionItemId,
         failedExtensions,
     });
     const serviceOverride = await runActiveServiceOverride("help_format", {
@@ -638,7 +730,13 @@ export async function formatCommanderUsageJson(error, rootProgram, extensionDesc
         providedOptionFlags: usageContext.providedOptionFlags,
         unknownOptionSuggestions: usageContext.unknownOptionSuggestions,
         unknownOptionOtherCommands: usageContext.unknownOptionOtherCommands,
+        unknownOptionOtherCommandsTotal: usageContext.unknownOptionOtherCommandsTotal,
+        unknownOptionOtherCommandsTruncated: usageContext.unknownOptionOtherCommandsTruncated,
+        unknownSubcommandPath: usageContext.unknownSubcommandPath,
+        unknownSubcommandToken: usageContext.unknownSubcommandToken,
+        unknownSubcommandAllowedValues: usageContext.unknownSubcommandAllowedValues,
         suggestedRetryCommand: usageContext.suggestedRetryCommand,
+        verifiedCollectionItemId: usageContext.verifiedCollectionItemId,
         failedExtensions: usageContext.failedExtensions,
     });
     return JSON.stringify(lean ? projectLeanErrorEnvelope(envelope) : envelope, null, 2);
@@ -652,4 +750,4 @@ export const _testOnly = {
     suggestNearestLongFlags,
 };
 //# sourceMappingURL=commander-usage.js.map
-//# debugId=a327ea76-ca7d-5f8f-aa2d-2f6f43052913
+//# debugId=05cf369c-7529-57ab-984a-f5505cc9c0c9

package/dist/cli/error-guidance.d.ts

@@ -77,8 +77,20 @@ export interface CommanderGuidanceContext {
     unknownOptionSuggestions?: string[];
     /** Value that configures or reports unknown option other commands for this contract. */
     unknownOptionOtherCommands?: string[];
+    /** Complete number of commands accepting the unknown option. */
+    unknownOptionOtherCommandsTotal?: number;
+    /** Whether the structured command candidates reached their own ceiling. */
+    unknownOptionOtherCommandsTruncated?: boolean;
+    /** Command family whose positional subcommand was split into invalid tokens. */
+    unknownSubcommandPath?: string;
+    /** Rejected positional subcommand token or token sequence. */
+    unknownSubcommandToken?: string;
+    /** Complete declared subcommand vocabulary for the command family. */
+    unknownSubcommandAllowedValues?: string[];
     /** Value that configures or reports suggested retry command for this contract. */
     suggestedRetryCommand?: string;
+    /** Existing item id verified against the selected tracker for collection recovery. */
+    verifiedCollectionItemId?: string;
     /** Installed extensions whose activation failed for this invocation. */
     failedExtensions?: Array<{
         name: string;

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]="d9d3d041-587b-5660-a909-d0759998248d")}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]="0203943b-16ea-5c3a-a2d3-56a0c4d2848f")}catch(e){}}();
 import { renderPmCommand } from "./argv-utils.js";
 import { discoverNearbyPmRoot } from "../sdk/tracker-root-discovery.js";
 /** Compact an error envelope to fields that change the caller's next action. */
@@ -125,7 +125,21 @@ function assignRecoveryString(normalized, key, value) {
         normalized[key] = value.trim();
     }
 }
-function assignRecoveryStringArray(normalized, key, value) {
+function assignRecoveryCollection(normalized, key, value) {
+    if (key === "parsed_positionals") {
+        if (!Array.isArray(value))
+            return;
+        const parsedPositionals = value
+            .map((entry) => ({
+            role: typeof entry?.role === "string" ? entry.role.trim() : "",
+            value: typeof entry?.value === "string" ? entry.value.trim() : "",
+        }))
+            .filter((entry) => entry.role.length > 0 && entry.value.length > 0);
+        if (parsedPositionals.length > 0) {
+            normalized.parsed_positionals = parsedPositionals;
+        }
+        return;
+    }
     const values = normalizeStringArray(value);
     if (values) {
         normalized[key] = values;
@@ -140,11 +154,22 @@ function normalizeRecoveryPayload(payload) {
         normalized.recovery_mode = "compact";
     }
     assignRecoveryString(normalized, "attempted_command", payload.attempted_command);
-    assignRecoveryStringArray(normalized, "normalized_args", payload.normalized_args);
-    assignRecoveryStringArray(normalized, "provided_fields", payload.provided_fields);
-    assignRecoveryStringArray(normalized, "missing", payload.missing);
-    assignRecoveryStringArray(normalized, "missing_required_fields", payload.missing_required_fields);
-    assignRecoveryStringArray(normalized, "suggested_flags", payload.suggested_flags);
+    assignRecoveryCollection(normalized, "normalized_args", payload.normalized_args);
+    assignRecoveryCollection(normalized, "parsed_positionals", payload.parsed_positionals);
+    assignRecoveryCollection(normalized, "provided_fields", payload.provided_fields);
+    assignRecoveryCollection(normalized, "missing", payload.missing);
+    assignRecoveryCollection(normalized, "missing_required_fields", payload.missing_required_fields);
+    assignRecoveryCollection(normalized, "suggested_flags", payload.suggested_flags);
+    assignRecoveryCollection(normalized, "allowed_values", payload.allowed_values);
+    assignRecoveryCollection(normalized, "candidate_commands", payload.candidate_commands);
+    if (typeof payload.candidate_commands_total === "number" &&
+        Number.isSafeInteger(payload.candidate_commands_total) &&
+        payload.candidate_commands_total >= 0) {
+        normalized.candidate_commands_total = payload.candidate_commands_total;
+    }
+    if (payload.candidate_commands_truncated === true) {
+        normalized.candidate_commands_truncated = true;
+    }
     assignRecoveryString(normalized, "suggested_retry", payload.suggested_retry);
     if (typeof payload.retry_after_ms === "number" &&
         Number.isSafeInteger(payload.retry_after_ms) &&
@@ -176,10 +201,25 @@ function renderRecoveryBundle(recovery) {
     const lines = ["Recovery bundle:"];
     appendRecoveryTextLine(lines, "attempted_command", normalized.attempted_command);
     appendRecoveryListLine(lines, "normalized_args", normalized.normalized_args, " ");
+    if (normalized.parsed_positionals &&
+        normalized.parsed_positionals.length > 0) {
+        lines.push("  parsed_positionals:");
+        for (const positional of normalized.parsed_positionals) {
+            lines.push(`    - ${positional.role}: ${positional.value}`);
+        }
+    }
     appendRecoveryListLine(lines, "provided_fields", normalized.provided_fields, ", ");
     appendRecoveryListLine(lines, "missing", normalized.missing, ", ");
     appendRecoveryListLine(lines, "missing_required_fields", normalized.missing_required_fields, ", ");
     appendRecoveryListLine(lines, "suggested_flags", normalized.suggested_flags, ", ");
+    appendRecoveryListLine(lines, "allowed_values", normalized.allowed_values, ", ");
+    appendRecoveryListLine(lines, "candidate_commands", normalized.candidate_commands, ", ");
+    if (typeof normalized.candidate_commands_total === "number") {
+        lines.push(`  candidate_commands_total: ${String(normalized.candidate_commands_total)}`);
+    }
+    if (normalized.candidate_commands_truncated === true) {
+        lines.push("  candidate_commands_truncated: true");
+    }
     appendRecoveryTextLine(lines, "suggested_retry", normalized.suggested_retry);
     if (typeof normalized.retry_after_ms === "number") {
         lines.push(`  retry_after_ms: ${normalized.retry_after_ms}`);
@@ -471,9 +511,7 @@ function buildLockConflictGuidance(rawMessage, message, context) {
         happened: message,
         required: "Wait for lock release, or use --force where supported if lock is stale and safe to override.",
         why: "Locking protects item files from concurrent write races.",
-        examples: [
-            "pm update pm-a1b2 --status in_progress --force",
-        ],
+        examples: ["pm update pm-a1b2 --status in_progress --force"],
     }), rawMessage, context);
 }
 function buildPmMissingRequiredOptionGuidance(rawMessage, message, context) {
@@ -797,32 +835,38 @@ function buildUnknownOptionGuidance(message, commandName, context) {
     if (!unknownOption) {
         return null;
     }
+    const guidanceContext = context ?? {};
     const optionName = unknownOption[1];
-    const suggestions = normalizeOptionFlags(context?.unknownOptionSuggestions);
-    const retryCommand = context?.suggestedRetryCommand;
+    const suggestions = normalizeOptionFlags(guidanceContext.unknownOptionSuggestions) ?? [];
+    const retryCommand = guidanceContext.suggestedRetryCommand;
     if (commandName === "update" &&
         (optionName === "--file" || optionName === "--doc")) {
         return buildUnsupportedUpdateOptionGuidance(optionName, context, suggestions);
     }
-    const otherCommands = normalizeContextList(context?.unknownOptionOtherCommands);
+    const otherCommands = normalizeContextList(guidanceContext.unknownOptionOtherCommands) ?? [];
+    const candidateTotal = guidanceContext.unknownOptionOtherCommandsTotal ?? otherCommands.length;
+    const proseCommands = otherCommands.slice(0, 3);
+    const proseRemainder = candidateTotal - proseCommands.length;
+    let proseRemainderText = "";
+    if (proseRemainder > 0) {
+        proseRemainderText = ` and ${String(proseRemainder)} more command path(s)`;
+    }
     const nextSteps = [
         "Run command help to confirm the exact option contracts for this command path.",
-        ...(suggestions && suggestions.length > 0
-            ? [`Nearest supported options: ${suggestions.join(", ")}`]
-            : []),
-        ...(otherCommands && otherCommands.length > 0
-            ? [
-                `${optionName} is a valid option on: ${otherCommands.join(", ")}. If you meant one of those, run that command instead.`,
-            ]
-            : []),
-        ...(retryCommand
-            ? [`Replay with suggested correction: ${retryCommand}`]
-            : []),
-    ];
+        suggestions.length
+            ? `Nearest supported options: ${suggestions.join(", ")}`
+            : undefined,
+        proseCommands.length
+            ? `${optionName} is accepted by ${proseCommands.join(", ")}${proseRemainderText}. Inspect those command contracts only if you intended a different operation.`
+            : undefined,
+        retryCommand
+            ? `Replay with suggested correction: ${retryCommand}`
+            : undefined,
+    ].filter((entry) => typeof entry === "string");
     const examples = [
-        ...(retryCommand ? [retryCommand] : []),
+        retryCommand,
         `pm ${commandName ?? "<command>"} --help`,
-    ];
+    ].filter((entry) => typeof entry === "string");
     return makeGuidanceMessage({
         code: "unknown_option",
         title: `Unknown option ${optionName}`,
@@ -832,7 +876,10 @@ function buildUnknownOptionGuidance(message, commandName, context) {
         examples,
         nextSteps,
         recovery: buildCommanderRecoveryPayload(context, {
-            suggested_flags: suggestions,
+            suggested_flags: suggestions.length > 0 ? suggestions : undefined,
+            candidate_commands: otherCommands,
+            candidate_commands_total: candidateTotal || undefined,
+            candidate_commands_truncated: guidanceContext.unknownOptionOtherCommandsTruncated,
         }),
     });
 }
@@ -884,6 +931,33 @@ function buildUnknownCommandGuidance(message, context) {
         recovery: buildCommanderRecoveryPayload(context),
     });
 }
+function buildUnknownSubcommandGuidance(context) {
+    const commandPath = context?.unknownSubcommandPath?.trim();
+    const token = context?.unknownSubcommandToken?.trim();
+    const allowed = normalizeContextList(context?.unknownSubcommandAllowedValues);
+    if (!commandPath || !token || !allowed) {
+        return null;
+    }
+    const retryCommand = context?.suggestedRetryCommand;
+    return makeGuidanceMessage({
+        code: "unknown_subcommand",
+        title: `Unknown ${commandPath} subcommand ${token}`,
+        happened: `The positional token sequence "${token}" is not a declared ${commandPath} subcommand.`,
+        required: `Use one of: ${allowed.join(", ")}.`,
+        why: "Subcommands are single positional tokens; multi-word action names use hyphens.",
+        examples: [
+            ...(retryCommand ? [retryCommand] : []),
+            `pm ${commandPath} --help`,
+        ],
+        nextSteps: retryCommand
+            ? [`Retry with the declared hyphenated action: ${retryCommand}`]
+            : ["Choose one value from recovery.allowed_values."],
+        recovery: buildCommanderRecoveryPayload(context, {
+            allowed_values: allowed,
+            suggested_retry: retryCommand,
+        }),
+    });
+}
 function buildLinkedTestValueNotQuotedGuidance(message, commandName, context) {
     if (!/too many arguments/i.test(message) || commandName !== "test") {
         return null;
@@ -916,6 +990,48 @@ function buildLinkedTestValueNotQuotedGuidance(message, commandName, context) {
         recovery: buildCommanderRecoveryPayload(context, retryCommand ? { suggested_retry: retryCommand } : {}),
     });
 }
+const TRANSPOSED_COLLECTION_COMMANDS = new Set([
+    "comments",
+    "docs",
+    "files",
+    "learnings",
+    "notes",
+    "test",
+]);
+function buildTransposedCollectionActionGuidance(message, commandName, context) {
+    if (!/too many arguments/i.test(message) ||
+        !TRANSPOSED_COLLECTION_COMMANDS.has(commandName ?? "")) {
+        return null;
+    }
+    const argv = context?.normalizedInvocationArgs ?? [];
+    const commandIndex = argv.findIndex((token) => token === commandName);
+    const action = argv[commandIndex + 1];
+    const parsedItemId = argv[commandIndex + 2];
+    const itemId = context?.verifiedCollectionItemId?.trim();
+    if (action?.toLowerCase() !== "add" ||
+        !parsedItemId ||
+        parsedItemId.startsWith("-") ||
+        !itemId ||
+        itemId.toLowerCase() !== parsedItemId.toLowerCase()) {
+        return null;
+    }
+    const suggestedRetry = `pm ${commandName} ${itemId} --add <value>`;
+    return makeGuidanceMessage({
+        code: "collection_transposed_subcommand",
+        title: `Transposed ${commandName} add syntax`,
+        happened: `The positional token "add" occupied the item-id role and "${itemId}" occupied the next positional role. pm ${commandName} does not use an add subcommand.`,
+        required: `Place the item id immediately after ${commandName}, then use --add for the value.`,
+        why: "Collection mutations use object-first grammar: pm <collection> <item-id> --add <value>.",
+        examples: [suggestedRetry, `pm ${commandName} --help`],
+        recovery: buildCommanderRecoveryPayload(context, {
+            parsed_positionals: [
+                { role: "transposed_subcommand", value: action },
+                { role: "item_id", value: itemId },
+            ],
+            suggested_retry: suggestedRetry,
+        }),
+    });
+}
 const CONTEXT_GUIDANCE_VALUE_FLAGS = new Set([
     "--activity-limit",
     "--assignee",
@@ -990,6 +1106,8 @@ function buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, cont
         buildMissingRequiredArgumentGuidance(message, commandName, context) ??
         buildUnknownOptionGuidance(message, commandName, context) ??
         buildUnknownCommandGuidance(message, context) ??
+        buildUnknownSubcommandGuidance(context) ??
+        buildTransposedCollectionActionGuidance(message, commandName, context) ??
         buildLinkedTestValueNotQuotedGuidance(message, commandName, context) ??
         buildContextItemArgumentGuidance(message, commandName, context);
     if (guidance) {
@@ -1083,4 +1201,4 @@ export const _testOnly = {
     resolveKnownPackageCommandHint,
 };
 //# sourceMappingURL=error-guidance.js.map
-//# debugId=d9d3d041-587b-5660-a909-d0759998248d
+//# debugId=0203943b-16ea-5c3a-a2d3-56a0c4d2848f

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]="555e37d0-385a-5748-b0a5-760f48c94e90")}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]="6eb8f2a6-6096-54af-a3dc-eb15fdbe5999")}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 { resolveSubcommandFlagContractsForCommand } from "../sdk/cli-contracts.js";
@@ -138,6 +138,10 @@ function projectExistingRecoveryOptionalFields(existingRecovery) {
         "recovery_mode",
         "missing_required_fields",
         "suggested_flags",
+        "allowed_values",
+        "candidate_commands",
+        "candidate_commands_total",
+        "candidate_commands_truncated",
         "fallback_candidates",
         "next_best_command",
     ];
@@ -842,15 +846,29 @@ function activationCommandMatchesProbe(command, probe) {
     return false;
 }
 function extensionActivationCommands(extension) {
-    return (extension.activation?.commands ??
-        [
-            ...(extension.contributions?.commands ?? []),
-            ...(extension.contributions?.command_handlers ?? []),
-            ...(extension.contributions?.command_overrides ?? []),
-            ...(extension.contributions?.flag_commands ?? []),
-            ...(extension.contributions?.parser_overrides ?? []),
-            ...(extension.contributions?.renderer_ownership?.flatMap((entry) => entry.commands) ?? []),
-        ]);
+    const explicitCommands = extension.activation?.commands;
+    if (explicitCommands) {
+        return explicitCommands;
+    }
+    const contributions = extension.contributions;
+    if (!contributions) {
+        return [];
+    }
+    return [
+        ...entriesOrEmpty(contributions.commands),
+        ...entriesOrEmpty(contributions.command_handlers),
+        ...entriesOrEmpty(contributions.command_overrides),
+        ...entriesOrEmpty(contributions.flag_commands),
+        ...entriesOrEmpty(contributions.parser_overrides),
+        ...ownershipCommands(contributions.preflight_ownership),
+        ...ownershipCommands(contributions.renderer_ownership),
+    ];
+}
+function entriesOrEmpty(entries) {
+    return entries ?? [];
+}
+function ownershipCommands(entries) {
+    return entriesOrEmpty(entries).flatMap((entry) => entry.commands);
 }
 function extensionCapabilities(extension) {
     /* c8 ignore next */
@@ -913,14 +931,15 @@ function matchesStaticExtensionCommand(commands, probe) {
 /** Identify contribution surfaces that participate in global runtime behavior. */
 function hasGlobalExtensionContributions(contributions) {
     const contributionCounts = [
-        contributions.hooks?.length ?? 0,
-        contributions.preflight_overrides ?? 0,
-        contributions.item_types?.length ?? 0,
-        contributions.item_fields?.length ?? 0,
-        contributions.relationship_kinds?.length ?? 0,
-        contributions.service_overrides?.length ?? 0,
-        (contributions.renderer_overrides?.length ?? 0) -
-            (contributions.renderer_ownership?.length ?? 0),
+        entriesOrEmpty(contributions.hooks).length,
+        (contributions.preflight_overrides ?? 0) -
+            entriesOrEmpty(contributions.preflight_ownership).length,
+        entriesOrEmpty(contributions.item_types).length,
+        entriesOrEmpty(contributions.item_fields).length,
+        entriesOrEmpty(contributions.relationship_kinds).length,
+        entriesOrEmpty(contributions.service_overrides).length,
+        entriesOrEmpty(contributions.renderer_overrides).length -
+            entriesOrEmpty(contributions.renderer_ownership).length,
     ];
     return contributionCounts.some((count) => count > 0);
 }
@@ -2455,4 +2474,4 @@ export const _testOnly = {
     wrapThrownErrorForSentry,
 };
 //# sourceMappingURL=main.js.map
-//# debugId=555e37d0-385a-5748-b0a5-760f48c94e90
+//# debugId=6eb8f2a6-6096-54af-a3dc-eb15fdbe5999