@unbrained/pm-cli 2026.5.10 → 2026.5.12

package/dist/cli/error-guidance.js.map

@@ -1 +1 @@
-{"version":3,"file":"error-guidance.js","sourceRoot":"/","sources":["cli/error-guidance.ts"],"names":[],"mappings":"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","sourcesContent":["import type { PmCliErrorContext } from \"../core/shared/errors.js\";\n\ninterface GuidanceMessage {\n  code: string;\n  type: string;\n  title: string;\n  happened: string;\n  required: string;\n  why?: string;\n  examples?: string[];\n  nextSteps?: string[];\n}\n\nexport interface JsonErrorEnvelope {\n  type: string;\n  code: string;\n  title: string;\n  detail: string;\n  required: string;\n  exit_code: number;\n  why?: string;\n  examples?: string[];\n  next_steps?: string[];\n}\n\nexport interface ErrorClassification {\n  type: string;\n  code: string;\n  title: string;\n  detail: string;\n  required: string;\n  why?: string;\n  examples?: string[];\n  next_steps?: string[];\n}\n\nexport interface CommanderGuidanceContext {\n  unknownCommandExamples?: string[];\n  unknownCommandNextSteps?: string[];\n}\n\nfunction errorType(code: string): string {\n  return `urn:pm-cli:error:${code}`;\n}\n\nfunction makeGuidanceMessage(params: Omit<GuidanceMessage, \"type\">): GuidanceMessage {\n  return {\n    ...params,\n    type: errorType(params.code),\n  };\n}\n\nfunction renderList(title: string, entries: string[]): string[] {\n  if (entries.length === 0) {\n    return [];\n  }\n  return [title, ...entries.map((entry) => `  - ${entry}`)];\n}\n\nexport function renderGuidanceMessage(message: GuidanceMessage): string {\n  const lines: string[] = [\n    `Error: ${message.title}`,\n    \"\",\n    \"What happened:\",\n    `  ${message.happened}`,\n    \"\",\n    \"What is required:\",\n    `  ${message.required}`,\n  ];\n  if (message.why) {\n    lines.push(\"\", \"Why:\");\n    lines.push(`  ${message.why}`);\n  }\n  if (message.examples && message.examples.length > 0) {\n    lines.push(\"\");\n    lines.push(...renderList(\"Examples:\", message.examples));\n  }\n  if (message.nextSteps && message.nextSteps.length > 0) {\n    lines.push(\"\");\n    lines.push(...renderList(\"Next steps:\", message.nextSteps));\n  }\n  return lines.join(\"\\n\");\n}\n\nfunction guidanceToJsonEnvelope(message: GuidanceMessage, exitCode: number): JsonErrorEnvelope {\n  const payload: JsonErrorEnvelope = {\n    type: message.type,\n    code: message.code,\n    title: message.title,\n    detail: message.happened,\n    required: message.required,\n    exit_code: exitCode,\n  };\n  if (message.why) {\n    payload.why = message.why;\n  }\n  if (message.examples && message.examples.length > 0) {\n    payload.examples = message.examples;\n  }\n  if (message.nextSteps && message.nextSteps.length > 0) {\n    payload.next_steps = message.nextSteps;\n  }\n  return payload;\n}\n\nfunction guidanceToClassification(message: GuidanceMessage): ErrorClassification {\n  const payload: ErrorClassification = {\n    type: message.type,\n    code: message.code,\n    title: message.title,\n    detail: message.happened,\n    required: message.required,\n  };\n  if (message.why) {\n    payload.why = message.why;\n  }\n  if (message.examples && message.examples.length > 0) {\n    payload.examples = message.examples;\n  }\n  if (message.nextSteps && message.nextSteps.length > 0) {\n    payload.next_steps = message.nextSteps;\n  }\n  return payload;\n}\n\nfunction normalizeMessage(message: string): string {\n  return message.replace(/\\(outputHelp\\)/g, \"\").trim();\n}\n\nfunction normalizeContextList(values: string[] | undefined): string[] | undefined {\n  if (!Array.isArray(values)) {\n    return undefined;\n  }\n  const normalized = values.map((value) => value.trim()).filter((value) => value.length > 0);\n  return normalized.length > 0 ? normalized : undefined;\n}\n\nfunction buildFallbackTitleFromMessage(message: string): string | undefined {\n  const firstLine = message.split(/\\r?\\n/)[0]?.trim() ?? \"\";\n  if (firstLine.length === 0) {\n    return undefined;\n  }\n  if (firstLine.length <= 120) {\n    return firstLine;\n  }\n  return `${firstLine.slice(0, 117)}...`;\n}\n\nfunction applyPmCliErrorContext(\n  guidance: GuidanceMessage,\n  rawMessage: string,\n  context: PmCliErrorContext | undefined,\n): GuidanceMessage {\n  if (!context) {\n    return guidance;\n  }\n  const normalizedRawMessage = normalizeMessage(rawMessage);\n  const code = typeof context.code === \"string\" && context.code.trim().length > 0 ? context.code.trim() : guidance.code;\n  const type = typeof context.type === \"string\" && context.type.trim().length > 0 ? context.type.trim() : errorType(code);\n  const examples = normalizeContextList(context.examples) ?? guidance.examples;\n  const nextSteps = normalizeContextList(context.nextSteps) ?? guidance.nextSteps;\n  const fallbackTitle = guidance.code === \"command_failed\" && context.code ? buildFallbackTitleFromMessage(normalizedRawMessage) : undefined;\n  return {\n    ...guidance,\n    code,\n    type,\n    title: fallbackTitle ?? guidance.title,\n    happened: normalizedRawMessage.length > 0 ? normalizedRawMessage : guidance.happened,\n    required: typeof context.required === \"string\" && context.required.trim().length > 0 ? context.required.trim() : guidance.required,\n    why: typeof context.why === \"string\" && context.why.trim().length > 0 ? context.why.trim() : guidance.why,\n    examples,\n    nextSteps,\n  };\n}\n\nfunction buildPmCliErrorGuidance(rawMessage: string, context?: PmCliErrorContext): GuidanceMessage {\n  const message = normalizeMessage(rawMessage);\n\n  const trackerNotInitialized = message.match(/^Tracker is not initialized at (.+)\\. Run pm init first\\.$/);\n  if (trackerNotInitialized) {\n    return applyPmCliErrorContext(\n      makeGuidanceMessage({\n        code: \"tracker_not_initialized\",\n        title: \"Tracker is not initialized\",\n        happened: `pm data path does not contain initialized tracker metadata (${trackerNotInitialized[1]}).`,\n        required: \"Initialize tracker storage before running this command.\",\n        why: \"Most commands require settings and tracker directories created by pm init.\",\n        examples: [\"pm init\", \"pm init acme\"],\n        nextSteps: ['Run \"pm init\", then rerun your original command.'],\n      }),\n      rawMessage,\n      context,\n    );\n  }\n\n  const itemNotFound = message.match(/^Item ([^ ]+) not found$/);\n  if (itemNotFound) {\n    const badId = itemNotFound[1];\n    const isPlaceholder = /^(undefined|null|<.*>|\\[.*\\]|{.*}|)$/.test(badId);\n    const happened = isPlaceholder\n      ? `The item ID \"${badId}\" looks like a placeholder or unresolved variable. Ensure the ID argument is resolved before calling pm.`\n      : `No item with id \"${badId}\" exists in the active tracker scope.`;\n    const nextSteps = isPlaceholder\n      ? [\n          \"Check that the variable holding the item ID is defined before passing it to pm.\",\n          'Use \"pm list-open --limit 20\" to find valid IDs.',\n        ]\n      : [\"Confirm the active --path/PM_PATH scope, then retry with a valid id.\"];\n    return applyPmCliErrorContext(\n      makeGuidanceMessage({\n        code: \"item_not_found\",\n        title: \"Item ID not found\",\n        happened,\n        required: \"Use an existing item ID from current tracker data.\",\n        why: \"Mutation and read commands operate only on known IDs.\",\n        examples: ['pm list-open --limit 20', 'pm search \"<keyword>\" --limit 10'],\n        nextSteps,\n      }),\n      rawMessage,\n      context,\n    );\n  }\n\n  if (message.includes(\"is assigned to\") && message.includes(\"Use --force to override\")) {\n    return applyPmCliErrorContext(\n      makeGuidanceMessage({\n        code: \"ownership_conflict\",\n        title: \"Ownership conflict\",\n        happened: message,\n        required:\n          \"Run as assigned owner, use audit flags for safe non-owner updates, or use --force only for approved override scenarios.\",\n        why: \"Ownership checks prevent accidental concurrent mutations on claimed items and protect against conflicting writes.\",\n        examples: [\n          'pm update pm-a1b2 --allow-audit-update --description \"...\" --author \"audit-agent\"',\n          'pm update pm-a1b2 --allow-audit-dep-update --dep \"...\" --author \"audit-agent\"',\n          'pm comments pm-a1b2 \"...\" --allow-audit-comment --author \"audit-agent\"',\n          'pm claim pm-a1b2 --author \"codex-agent\"',\n          'pm release pm-a1b2 --allow-audit-release --author \"reviewer\"',\n          'pm update pm-a1b2 --status in_progress --force',\n        ],\n        nextSteps: [\n          \"Use --allow-audit-update for metadata-only non-owner updates (excludes lifecycle/ownership fields).\",\n          \"Use --allow-audit-dep-update for dependency-only non-owner additions.\",\n          \"Use --allow-audit-comment on comments/notes/learnings for append-only audit entries.\",\n          \"Use --force for PM audits and systematic metadata updates performed by leads/maintainers.\",\n          \"Use --force when correcting known stale metadata after coordinating ownership changes.\",\n          'For non-terminal reassignment, prefer \"pm claim <ID> --author <you>\" before running other mutations.',\n          'For assignee handoff release workflows, prefer \"pm release <ID> --allow-audit-release --author <you>\" before using --force.',\n        ],\n      }),\n      rawMessage,\n      context,\n    );\n  }\n\n  if (message.includes(\"is locked\")) {\n    return applyPmCliErrorContext(\n      makeGuidanceMessage({\n        code: \"lock_conflict\",\n        title: \"Lock conflict\",\n        happened: message,\n        required: \"Wait for lock release, or use --force where supported if lock is stale and safe to override.\",\n        why: \"Locking protects item files from concurrent write races.\",\n        examples: ['pm update pm-a1b2 --status in_progress --force --author \"codex-agent\"'],\n      }),\n      rawMessage,\n      context,\n    );\n  }\n\n  const missingRequiredOption = message.match(/^Missing required option /);\n  const missingRequiredOptions = message.match(/^Missing required options /);\n  if (missingRequiredOption || missingRequiredOptions) {\n    const plural = Boolean(missingRequiredOptions);\n    const missingOptionFlag = !plural ? message.replace(/^Missing required option\\s+/, \"\").trim() : null;\n    const missingOptionRequired = missingOptionFlag\n      ? `Pass ${missingOptionFlag} with a valid value before running the command.`\n      : \"Provide the required option for this command invocation.\";\n    return applyPmCliErrorContext(\n      makeGuidanceMessage({\n        code: \"missing_required_option\",\n        title: plural ? \"Missing required options\" : missingOptionFlag ? `Missing required option ${missingOptionFlag}` : \"Missing required option\",\n        happened: message,\n        required: plural\n          ? \"Provide every required option for this command invocation.\"\n          : missingOptionRequired,\n        why: \"Required options define command intent and enforce deterministic write contracts.\",\n        examples: [\n          'pm create --title \"Task title\" --description \"Task details\" --type Task --create-mode progressive',\n          'pm create --title \"Task title\" --description \"Task details\" --type Task --status open --priority 1 --message \"Create task\" --dep \"id=pm-epic01,kind=parent,author=codex-agent,created_at=now\" --comment \"author=codex-agent,created_at=now,text=Why this task exists.\" --note \"author=codex-agent,created_at=now,text=Initial implementation note.\" --learning \"author=codex-agent,created_at=now,text=Durable lesson placeholder.\" --file \"path=src/example.ts,scope=project\" --test \"command=node scripts/run-tests.mjs test,scope=project,timeout_seconds=240\" --doc \"path=README.md,scope=project\"',\n        ],\n        nextSteps: [\n          'Run \"pm <command> --help\" to view required and recommended flags.',\n          \"For staged triage without placeholder linkage values, use --create-mode progressive.\",\n        ],\n      }),\n      rawMessage,\n      context,\n    );\n  }\n\n  if (message.startsWith(\"No update flags provided\")) {\n    return applyPmCliErrorContext(\n      makeGuidanceMessage({\n        code: \"no_update_fields\",\n        title: \"No update fields supplied\",\n        happened: \"The update command was called without any field-changing flags.\",\n        required:\n          \"Provide at least one field-changing flag such as --status, --priority, --title, --tags, --description, or --body. Use --message only to label a real mutation.\",\n        why: \"pm update mutates existing item fields; no-op invocations are rejected to avoid ambiguous history.\",\n        examples: [\n          'pm update pm-a1b2 --status in_progress --message \"Start implementation\"',\n          'pm update pm-a1b2 --description \"Clarified implementation scope\" --message \"Clarify task intent\"',\n          'pm append pm-a1b2 --body \"Detailed progress notes\" --message \"Append progress notes\"',\n        ],\n        nextSteps: [\n          \"Choose the item field you intend to change, then pair that change with --message for history context.\",\n          \"Use pm comments, pm notes, pm learnings, or pm append when you only need to add narrative context.\",\n        ],\n      }),\n      rawMessage,\n      context,\n    );\n  }\n\n  if (message.startsWith(\"Invalid \") || message.includes(\" must be \")) {\n    return applyPmCliErrorContext(\n      makeGuidanceMessage({\n        code: \"invalid_argument_value\",\n        title: \"Invalid argument value\",\n        happened: message,\n        required: \"Use values that match documented command constraints.\",\n        why: \"Validation protects data consistency and deterministic behavior across commands.\",\n        examples: [\"pm create --help\", \"pm update --help\", \"pm calendar --help\"],\n        nextSteps: [\"Check allowed values in command help, then rerun with corrected input.\"],\n      }),\n      rawMessage,\n      context,\n    );\n  }\n\n  return applyPmCliErrorContext(\n    makeGuidanceMessage({\n      code: \"command_failed\",\n      title: \"Command failed\",\n      happened: message,\n      required: \"Adjust command input or tracker state and retry.\",\n      why: \"pm enforces explicit, deterministic contracts for data and command semantics.\",\n      examples: [\"pm --help\", \"pm <command> --help\"],\n    }),\n    rawMessage,\n    context,\n  );\n}\n\nfunction commandExampleForRequiredOption(commandName: string | undefined, optionFlag: string, allowedTypes: string): string[] {\n  if (commandName === \"create\" && optionFlag.startsWith(\"--type\")) {\n    const firstAllowed = allowedTypes.split(\"|\")[0] || \"Task\";\n    return [\n      `pm create --title \"Example title\" --description \"Example description\" --type ${firstAllowed} --status open --priority 1 --message \"Create item\" --create-mode progressive`,\n    ];\n  }\n  if (commandName === \"update\") {\n    return ['pm update pm-a1b2 --status in_progress --message \"Start implementation\"'];\n  }\n  return [`pm ${commandName ?? \"<command>\"} --help`];\n}\n\nfunction buildCommanderErrorGuidance(\n  rawMessage: string,\n  commandName: string | undefined,\n  allowedTypes: string,\n  context?: CommanderGuidanceContext,\n): GuidanceMessage {\n  const message = normalizeMessage(rawMessage);\n\n  const requiredOption = message.match(/required option '([^']+)' not specified/);\n  if (requiredOption) {\n    const optionFlag = requiredOption[1];\n    const isType = optionFlag.startsWith(\"--type\");\n    return makeGuidanceMessage({\n      code: \"missing_required_option\",\n      title: `Missing required option ${optionFlag}`,\n      happened: `Commander rejected the command because ${optionFlag} was not provided.`,\n      required: `Pass ${optionFlag} with a valid value before running the command.`,\n      why: isType\n        ? \"--type selects item contract and policy routing, including required/disabled option rules.\"\n        : \"Required flags define mandatory command intent and prevent ambiguous execution.\",\n      examples: commandExampleForRequiredOption(commandName, optionFlag, allowedTypes),\n      nextSteps: isType\n        ? [`Allowed type values: ${allowedTypes}`, `Run \"pm ${commandName ?? \"create\"} --help --type <value>\" for type-aware policy details.`]\n        : [`Run \"pm ${commandName ?? \"<command>\"} --help\" for required option guidance.`],\n    });\n  }\n\n  const missingArgument = message.match(/missing required argument '([^']+)'/);\n  if (missingArgument) {\n    const argumentName = missingArgument[1];\n    return makeGuidanceMessage({\n      code: \"missing_required_argument\",\n      title: `Missing required argument ${argumentName}`,\n      happened: `Command invocation omitted positional argument ${argumentName}.`,\n      required: `Provide ${argumentName} in the expected command position.`,\n      why: \"Positional arguments identify the target entity or action context for the command.\",\n      examples: [`pm ${commandName ?? \"<command>\"} --help`],\n    });\n  }\n\n  const unknownOption = message.match(/unknown option '([^']+)'/);\n  if (unknownOption) {\n    const optionName = unknownOption[1];\n    if (commandName === \"update\" && (optionName === \"--file\" || optionName === \"--doc\")) {\n      return makeGuidanceMessage({\n        code: \"unsupported_update_option\",\n        title: `Unsupported option ${optionName} for update`,\n        happened: `pm update does not accept ${optionName} for linked artifact mutations.`,\n        required: \"Use dedicated linked-artifact commands instead of pm update for files/docs changes.\",\n        why: \"pm update manages scalar item metadata, while linked files/docs are managed by pm files and pm docs.\",\n        examples: [\n          'pm files pm-a1b2 --add \"path=src/cli/main.ts,scope=project,note=implementation surface\"',\n          'pm docs pm-a1b2 --add \"path=README.md,scope=project,note=user-facing contract\"',\n        ],\n        nextSteps: ['Run \"pm files --help\" and \"pm docs --help\" for add/remove payload formats.'],\n      });\n    }\n    return makeGuidanceMessage({\n      code: \"unknown_option\",\n      title: `Unknown option ${optionName}`,\n      happened: `Commander does not recognize option ${optionName} for this command path.`,\n      required: \"Use supported options only, or move option to the correct subcommand.\",\n      why: \"Option contracts are command-specific and intentionally validated.\",\n      examples: [`pm ${commandName ?? \"<command>\"} --help`],\n    });\n  }\n\n  const unknownCommand = message.match(/unknown command '([^']+)'/);\n  if (unknownCommand) {\n    const commandToken = unknownCommand[1];\n    const runtimeExamples = normalizeContextList(context?.unknownCommandExamples);\n    const runtimeNextSteps = normalizeContextList(context?.unknownCommandNextSteps);\n    return makeGuidanceMessage({\n      code: \"unknown_command\",\n      title: `Unknown command ${commandToken}`,\n      happened: `pm does not expose command path \"${commandToken}\" in current runtime configuration.`,\n      required: \"Use a valid command name or subcommand path.\",\n      why: \"Command registry includes core commands plus active extension command handlers.\",\n      examples: runtimeExamples ?? [\"pm --help\"],\n      nextSteps: runtimeNextSteps ?? [\"Verify spelling and active extensions, then rerun.\"],\n    });\n  }\n\n  return makeGuidanceMessage({\n    code: \"invalid_command_usage\",\n    title: \"Invalid command usage\",\n    happened: message,\n    required: \"Use the command with valid arguments and options.\",\n    why: \"Commander validates CLI contracts before execution.\",\n    examples: [\"pm --help\", `pm ${commandName ?? \"<command>\"} --help`],\n  });\n}\n\nexport function formatPmCliErrorForDisplay(rawMessage: string, context?: PmCliErrorContext): string {\n  return renderGuidanceMessage(buildPmCliErrorGuidance(rawMessage, context));\n}\n\nexport function classifyPmCliError(rawMessage: string, context?: PmCliErrorContext): ErrorClassification {\n  return guidanceToClassification(buildPmCliErrorGuidance(rawMessage, context));\n}\n\nexport function formatPmCliErrorForJson(rawMessage: string, exitCode: number, context?: PmCliErrorContext): JsonErrorEnvelope {\n  return guidanceToJsonEnvelope(buildPmCliErrorGuidance(rawMessage, context), exitCode);\n}\n\nexport function formatCommanderErrorForDisplay(\n  rawMessage: string,\n  commandName: string | undefined,\n  allowedTypes: string,\n  context?: CommanderGuidanceContext,\n): string {\n  return renderGuidanceMessage(buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, context));\n}\n\nexport function classifyCommanderError(\n  rawMessage: string,\n  commandName: string | undefined,\n  allowedTypes: string,\n  context?: CommanderGuidanceContext,\n): ErrorClassification {\n  return guidanceToClassification(buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, context));\n}\n\nexport function formatCommanderErrorForJson(\n  rawMessage: string,\n  commandName: string | undefined,\n  allowedTypes: string,\n  exitCode: number,\n  context?: CommanderGuidanceContext,\n): JsonErrorEnvelope {\n  return guidanceToJsonEnvelope(buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, context), exitCode);\n}\n\nexport function formatUnknownErrorForJson(rawMessage: string, exitCode: number): JsonErrorEnvelope {\n  const guidance = buildUnknownErrorGuidance(rawMessage);\n  return guidanceToJsonEnvelope(guidance, exitCode);\n}\n\nfunction buildUnknownErrorGuidance(rawMessage: string): GuidanceMessage {\n  return makeGuidanceMessage({\n    code: \"unknown_error\",\n    title: \"Unhandled error\",\n    happened: normalizeMessage(rawMessage),\n    required: \"Inspect command input and runtime state, then retry.\",\n    why: \"Unexpected runtime failures can occur from environment or extension-level issues.\",\n    examples: [\"pm --help\", \"pm health --json\"],\n  });\n}\n\nexport function classifyUnknownError(rawMessage: string): ErrorClassification {\n  return guidanceToClassification(buildUnknownErrorGuidance(rawMessage));\n}\n"]}
+{"version":3,"file":"error-guidance.js","sourceRoot":"/","sources":["cli/error-guidance.ts"],"names":[],"mappings":"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","sourcesContent":["import type { PmCliErrorContext, PmCliErrorRecoveryPayload } from \"../core/shared/errors.js\";\nimport { renderPmCommand } from \"./argv-utils.js\";\n\ninterface GuidanceMessage {\n  code: string;\n  type: string;\n  title: string;\n  happened: string;\n  required: string;\n  why?: string;\n  examples?: string[];\n  nextSteps?: string[];\n  recovery?: PmCliErrorRecoveryPayload;\n}\n\nexport interface JsonErrorEnvelope {\n  type: string;\n  code: string;\n  title: string;\n  detail: string;\n  required: string;\n  exit_code: number;\n  why?: string;\n  examples?: string[];\n  next_steps?: string[];\n  recovery?: PmCliErrorRecoveryPayload;\n}\n\nexport interface ErrorClassification {\n  type: string;\n  code: string;\n  title: string;\n  detail: string;\n  required: string;\n  why?: string;\n  examples?: string[];\n  next_steps?: string[];\n  recovery?: PmCliErrorRecoveryPayload;\n}\n\nexport interface CommanderGuidanceContext {\n  unknownCommandExamples?: string[];\n  unknownCommandNextSteps?: string[];\n  attemptedCommand?: string;\n  normalizedInvocationArgs?: string[];\n  providedOptionFlags?: string[];\n  unknownOptionSuggestions?: string[];\n  suggestedRetryCommand?: string;\n}\n\nfunction errorType(code: string): string {\n  return `urn:pm-cli:error:${code}`;\n}\n\nfunction makeGuidanceMessage(params: Omit<GuidanceMessage, \"type\">): GuidanceMessage {\n  return {\n    ...params,\n    type: errorType(params.code),\n  };\n}\n\nfunction renderList(title: string, entries: string[]): string[] {\n  if (entries.length === 0) {\n    return [];\n  }\n  return [title, ...entries.map((entry) => `  - ${entry}`)];\n}\n\nfunction normalizeRecoveryPayload(payload: PmCliErrorRecoveryPayload | undefined): PmCliErrorRecoveryPayload | undefined {\n  if (!payload || typeof payload !== \"object\") {\n    return undefined;\n  }\n  const normalized: PmCliErrorRecoveryPayload = {};\n  if (typeof payload.attempted_command === \"string\" && payload.attempted_command.trim().length > 0) {\n    normalized.attempted_command = payload.attempted_command.trim();\n  }\n  if (Array.isArray(payload.normalized_args)) {\n    const args = payload.normalized_args.map((entry) => entry.trim()).filter((entry) => entry.length > 0);\n    if (args.length > 0) {\n      normalized.normalized_args = args;\n    }\n  }\n  if (Array.isArray(payload.provided_fields)) {\n    const fields = payload.provided_fields.map((entry) => entry.trim()).filter((entry) => entry.length > 0);\n    if (fields.length > 0) {\n      normalized.provided_fields = fields;\n    }\n  }\n  if (Array.isArray(payload.missing)) {\n    const missing = payload.missing.map((entry) => entry.trim()).filter((entry) => entry.length > 0);\n    if (missing.length > 0) {\n      normalized.missing = missing;\n    }\n  }\n  if (typeof payload.suggested_retry === \"string\" && payload.suggested_retry.trim().length > 0) {\n    normalized.suggested_retry = payload.suggested_retry.trim();\n  }\n  return Object.keys(normalized).length > 0 ? normalized : undefined;\n}\n\nfunction renderRecoveryBundle(recovery: PmCliErrorRecoveryPayload | undefined): string[] {\n  const normalized = normalizeRecoveryPayload(recovery);\n  if (!normalized) {\n    return [];\n  }\n  const lines = [\"Recovery bundle:\"];\n  if (normalized.attempted_command) {\n    lines.push(`  attempted_command: ${normalized.attempted_command}`);\n  }\n  if (normalized.normalized_args && normalized.normalized_args.length > 0) {\n    lines.push(`  normalized_args: ${normalized.normalized_args.join(\" \")}`);\n  }\n  if (normalized.provided_fields && normalized.provided_fields.length > 0) {\n    lines.push(`  provided_fields: ${normalized.provided_fields.join(\", \")}`);\n  }\n  if (normalized.missing && normalized.missing.length > 0) {\n    lines.push(`  missing: ${normalized.missing.join(\", \")}`);\n  }\n  if (normalized.suggested_retry) {\n    lines.push(`  suggested_retry: ${normalized.suggested_retry}`);\n  }\n  return lines;\n}\n\nexport function renderGuidanceMessage(message: GuidanceMessage): string {\n  const lines: string[] = [\n    `Error: ${message.title}`,\n    \"\",\n    \"What happened:\",\n    `  ${message.happened}`,\n    \"\",\n    \"What is required:\",\n    `  ${message.required}`,\n  ];\n  if (message.why) {\n    lines.push(\"\", \"Why:\");\n    lines.push(`  ${message.why}`);\n  }\n  if (message.examples && message.examples.length > 0) {\n    lines.push(\"\");\n    lines.push(...renderList(\"Examples:\", message.examples));\n  }\n  if (message.nextSteps && message.nextSteps.length > 0) {\n    lines.push(\"\");\n    lines.push(...renderList(\"Next steps:\", message.nextSteps));\n  }\n  const recoveryLines = renderRecoveryBundle(message.recovery);\n  if (recoveryLines.length > 0) {\n    lines.push(\"\");\n    lines.push(...recoveryLines);\n  }\n  return lines.join(\"\\n\");\n}\n\nfunction guidanceToJsonEnvelope(message: GuidanceMessage, exitCode: number): JsonErrorEnvelope {\n  const payload: JsonErrorEnvelope = {\n    type: message.type,\n    code: message.code,\n    title: message.title,\n    detail: message.happened,\n    required: message.required,\n    exit_code: exitCode,\n  };\n  if (message.why) {\n    payload.why = message.why;\n  }\n  if (message.examples && message.examples.length > 0) {\n    payload.examples = message.examples;\n  }\n  if (message.nextSteps && message.nextSteps.length > 0) {\n    payload.next_steps = message.nextSteps;\n  }\n  if (message.recovery) {\n    payload.recovery = message.recovery;\n  }\n  return payload;\n}\n\nfunction guidanceToClassification(message: GuidanceMessage): ErrorClassification {\n  const payload: ErrorClassification = {\n    type: message.type,\n    code: message.code,\n    title: message.title,\n    detail: message.happened,\n    required: message.required,\n  };\n  if (message.why) {\n    payload.why = message.why;\n  }\n  if (message.examples && message.examples.length > 0) {\n    payload.examples = message.examples;\n  }\n  if (message.nextSteps && message.nextSteps.length > 0) {\n    payload.next_steps = message.nextSteps;\n  }\n  if (message.recovery) {\n    payload.recovery = message.recovery;\n  }\n  return payload;\n}\n\nfunction normalizeMessage(message: string): string {\n  return message.replace(/\\(outputHelp\\)/g, \"\").trim();\n}\n\nfunction normalizeContextList(values: string[] | undefined): string[] | undefined {\n  if (!Array.isArray(values)) {\n    return undefined;\n  }\n  const normalized = values.map((value) => value.trim()).filter((value) => value.length > 0);\n  return normalized.length > 0 ? normalized : undefined;\n}\n\nfunction buildFallbackTitleFromMessage(message: string): string | undefined {\n  const firstLine = message.split(/\\r?\\n/)[0]?.trim() ?? \"\";\n  if (firstLine.length === 0) {\n    return undefined;\n  }\n  if (firstLine.length <= 120) {\n    return firstLine;\n  }\n  return `${firstLine.slice(0, 117)}...`;\n}\n\nfunction applyPmCliErrorContext(\n  guidance: GuidanceMessage,\n  rawMessage: string,\n  context: PmCliErrorContext | undefined,\n): GuidanceMessage {\n  if (!context) {\n    return guidance;\n  }\n  const normalizedRawMessage = normalizeMessage(rawMessage);\n  const code = typeof context.code === \"string\" && context.code.trim().length > 0 ? context.code.trim() : guidance.code;\n  const type = typeof context.type === \"string\" && context.type.trim().length > 0 ? context.type.trim() : errorType(code);\n  const examples = normalizeContextList(context.examples) ?? guidance.examples;\n  const nextSteps = normalizeContextList(context.nextSteps) ?? guidance.nextSteps;\n  const fallbackTitle = guidance.code === \"command_failed\" && context.code ? buildFallbackTitleFromMessage(normalizedRawMessage) : undefined;\n  const recovery = normalizeRecoveryPayload(context.recovery) ?? guidance.recovery;\n  return {\n    ...guidance,\n    code,\n    type,\n    title: fallbackTitle ?? guidance.title,\n    happened: normalizedRawMessage.length > 0 ? normalizedRawMessage : guidance.happened,\n    required: typeof context.required === \"string\" && context.required.trim().length > 0 ? context.required.trim() : guidance.required,\n    why: typeof context.why === \"string\" && context.why.trim().length > 0 ? context.why.trim() : guidance.why,\n    examples,\n    nextSteps,\n    recovery,\n  };\n}\n\nfunction buildPmCliErrorGuidance(rawMessage: string, context?: PmCliErrorContext): GuidanceMessage {\n  const message = normalizeMessage(rawMessage);\n\n  const trackerNotInitialized = message.match(/^Tracker is not initialized at (.+)\\. Run pm init first\\.$/);\n  if (trackerNotInitialized) {\n    return applyPmCliErrorContext(\n      makeGuidanceMessage({\n        code: \"tracker_not_initialized\",\n        title: \"Tracker is not initialized\",\n        happened: `pm data path does not contain initialized tracker metadata (${trackerNotInitialized[1]}).`,\n        required: \"Initialize tracker storage before running this command.\",\n        why: \"Most commands require settings and tracker directories created by pm init.\",\n        examples: [\"pm init\", \"pm init acme\"],\n        nextSteps: ['Run \"pm init\", then rerun your original command.'],\n      }),\n      rawMessage,\n      context,\n    );\n  }\n\n  const itemNotFound = message.match(/^Item ([^ ]+) not found$/);\n  if (itemNotFound) {\n    const badId = itemNotFound[1];\n    const isPlaceholder = /^(undefined|null|<.*>|\\[.*\\]|{.*}|)$/.test(badId);\n    const happened = isPlaceholder\n      ? `The item ID \"${badId}\" looks like a placeholder or unresolved variable. Ensure the ID argument is resolved before calling pm.`\n      : `No item with id \"${badId}\" exists in the active tracker scope.`;\n    const nextSteps = isPlaceholder\n      ? [\n          \"Check that the variable holding the item ID is defined before passing it to pm.\",\n          'Use \"pm list-open --limit 20\" to find valid IDs.',\n        ]\n      : [\"Confirm the active --path/PM_PATH scope, then retry with a valid id.\"];\n    return applyPmCliErrorContext(\n      makeGuidanceMessage({\n        code: \"item_not_found\",\n        title: \"Item ID not found\",\n        happened,\n        required: \"Use an existing item ID from current tracker data.\",\n        why: \"Mutation and read commands operate only on known IDs.\",\n        examples: ['pm list-open --limit 20', 'pm search \"<keyword>\" --limit 10'],\n        nextSteps,\n      }),\n      rawMessage,\n      context,\n    );\n  }\n\n  if (message.includes(\"is assigned to\") && message.includes(\"Use --force to override\")) {\n    return applyPmCliErrorContext(\n      makeGuidanceMessage({\n        code: \"ownership_conflict\",\n        title: \"Ownership conflict\",\n        happened: message,\n        required:\n          \"Run as assigned owner, use audit flags for safe non-owner updates, or use --force only for approved override scenarios.\",\n        why: \"Ownership checks prevent accidental concurrent mutations on claimed items and protect against conflicting writes.\",\n        examples: [\n          'pm update pm-a1b2 --allow-audit-update --description \"...\" --author \"audit-agent\"',\n          'pm update pm-a1b2 --allow-audit-dep-update --dep \"...\" --author \"audit-agent\"',\n          'pm comments pm-a1b2 \"...\" --allow-audit-comment --author \"audit-agent\"',\n          'pm claim pm-a1b2 --author \"codex-agent\"',\n          'pm release pm-a1b2 --allow-audit-release --author \"reviewer\"',\n          'pm update pm-a1b2 --status in_progress --force',\n        ],\n        nextSteps: [\n          \"Use --allow-audit-update for metadata-only non-owner updates (excludes lifecycle/ownership fields).\",\n          \"Use --allow-audit-dep-update for dependency-only non-owner additions.\",\n          \"Use --allow-audit-comment on comments/notes/learnings for append-only audit entries.\",\n          \"Use --force for PM audits and systematic metadata updates performed by leads/maintainers.\",\n          \"Use --force when correcting known stale metadata after coordinating ownership changes.\",\n          'For non-terminal reassignment, prefer \"pm claim <ID> --author <you>\" before running other mutations.',\n          'For assignee handoff release workflows, prefer \"pm release <ID> --allow-audit-release --author <you>\" before using --force.',\n        ],\n      }),\n      rawMessage,\n      context,\n    );\n  }\n\n  if (message.includes(\"is locked\")) {\n    return applyPmCliErrorContext(\n      makeGuidanceMessage({\n        code: \"lock_conflict\",\n        title: \"Lock conflict\",\n        happened: message,\n        required: \"Wait for lock release, or use --force where supported if lock is stale and safe to override.\",\n        why: \"Locking protects item files from concurrent write races.\",\n        examples: ['pm update pm-a1b2 --status in_progress --force --author \"codex-agent\"'],\n      }),\n      rawMessage,\n      context,\n    );\n  }\n\n  const missingRequiredOption = message.match(/^Missing required option /);\n  const missingRequiredOptions = message.match(/^Missing required options /);\n  if (missingRequiredOption || missingRequiredOptions) {\n    const plural = Boolean(missingRequiredOptions);\n    const missingOptionFlag = !plural ? message.replace(/^Missing required option\\s+/, \"\").trim() : null;\n    const missingOptionRequired = missingOptionFlag\n      ? `Pass ${missingOptionFlag} with a valid value before running the command.`\n      : \"Provide the required option for this command invocation.\";\n    return applyPmCliErrorContext(\n      makeGuidanceMessage({\n        code: \"missing_required_option\",\n        title: plural ? \"Missing required options\" : missingOptionFlag ? `Missing required option ${missingOptionFlag}` : \"Missing required option\",\n        happened: message,\n        required: plural\n          ? \"Provide every required option for this command invocation.\"\n          : missingOptionRequired,\n        why: \"Required options define command intent and enforce deterministic write contracts.\",\n        examples: [\n          'pm create --title \"Task title\" --description \"Task details\" --type Task --create-mode progressive',\n          'pm create --title \"Task title\" --description \"Task details\" --type Task --status open --priority 1 --message \"Create task\" --dep \"id=pm-epic01,kind=parent,author=codex-agent,created_at=now\" --comment \"author=codex-agent,created_at=now,text=Why this task exists.\" --note \"author=codex-agent,created_at=now,text=Initial implementation note.\" --learning \"author=codex-agent,created_at=now,text=Durable lesson placeholder.\" --file \"path=src/example.ts,scope=project\" --test \"command=node scripts/run-tests.mjs test,scope=project,timeout_seconds=240\" --doc \"path=README.md,scope=project\"',\n        ],\n        nextSteps: [\n          'Run \"pm <command> --help\" to view required and recommended flags.',\n          \"For staged triage without placeholder linkage values, use --create-mode progressive.\",\n        ],\n      }),\n      rawMessage,\n      context,\n    );\n  }\n\n  if (message.startsWith(\"No update flags provided\")) {\n    return applyPmCliErrorContext(\n      makeGuidanceMessage({\n        code: \"no_update_fields\",\n        title: \"No update fields supplied\",\n        happened: \"The update command was called without any field-changing flags.\",\n        required:\n          \"Provide at least one field-changing flag such as --status, --priority, --title, --tags, --description, or --body. Use --message only to label a real mutation.\",\n        why: \"pm update mutates existing item fields; no-op invocations are rejected to avoid ambiguous history.\",\n        examples: [\n          'pm update pm-a1b2 --status in_progress --message \"Start implementation\"',\n          'pm update pm-a1b2 --description \"Clarified implementation scope\" --message \"Clarify task intent\"',\n          'pm append pm-a1b2 --body \"Detailed progress notes\" --message \"Append progress notes\"',\n        ],\n        nextSteps: [\n          \"Choose the item field you intend to change, then pair that change with --message for history context.\",\n          \"Use pm comments, pm notes, pm learnings, or pm append when you only need to add narrative context.\",\n        ],\n      }),\n      rawMessage,\n      context,\n    );\n  }\n\n  if (message.startsWith(\"Invalid \") || message.includes(\" must be \")) {\n    return applyPmCliErrorContext(\n      makeGuidanceMessage({\n        code: \"invalid_argument_value\",\n        title: \"Invalid argument value\",\n        happened: message,\n        required: \"Use values that match documented command constraints.\",\n        why: \"Validation protects data consistency and deterministic behavior across commands.\",\n        examples: [\"pm create --help\", \"pm update --help\", \"pm calendar --help\"],\n        nextSteps: [\"Check allowed values in command help, then rerun with corrected input.\"],\n      }),\n      rawMessage,\n      context,\n    );\n  }\n\n  return applyPmCliErrorContext(\n    makeGuidanceMessage({\n      code: \"command_failed\",\n      title: \"Command failed\",\n      happened: message,\n      required: \"Adjust command input or tracker state and retry.\",\n      why: \"pm enforces explicit, deterministic contracts for data and command semantics.\",\n      examples: [\"pm --help\", \"pm <command> --help\"],\n    }),\n    rawMessage,\n    context,\n  );\n}\n\nfunction commandExampleForRequiredOption(commandName: string | undefined, optionFlag: string, allowedTypes: string): string[] {\n  if (commandName === \"create\" && optionFlag.startsWith(\"--type\")) {\n    const firstAllowed = allowedTypes.split(\"|\")[0] || \"Task\";\n    return [\n      `pm create --title \"Example title\" --description \"Example description\" --type ${firstAllowed} --status open --priority 1 --message \"Create item\" --create-mode progressive`,\n    ];\n  }\n  if (commandName === \"update\") {\n    return ['pm update pm-a1b2 --status in_progress --message \"Start implementation\"'];\n  }\n  return [`pm ${commandName ?? \"<command>\"} --help`];\n}\n\nfunction normalizeRequiredOptionLabel(rawValue: string): string {\n  const normalized = rawValue.trim();\n  const firstLongFlag = normalized.match(/--[A-Za-z0-9][A-Za-z0-9_-]*/)?.[0];\n  return firstLongFlag ?? normalized;\n}\n\nfunction renderPmCommandFromArgs(argv: string[] | undefined): string | undefined {\n  if (!Array.isArray(argv) || argv.length === 0) {\n    return undefined;\n  }\n  return renderPmCommand(argv);\n}\n\nfunction normalizeOptionFlags(values: string[] | undefined): string[] | undefined {\n  if (!Array.isArray(values)) {\n    return undefined;\n  }\n  const normalized = values.map((value) => value.trim()).filter((value) => value.length > 0);\n  return normalized.length > 0 ? normalized : undefined;\n}\n\nfunction buildCommanderRecoveryPayload(\n  context: CommanderGuidanceContext | undefined,\n  overrides: Partial<PmCliErrorRecoveryPayload> = {},\n): PmCliErrorRecoveryPayload | undefined {\n  const providedFields = normalizeOptionFlags(context?.providedOptionFlags);\n  const normalizedArgs =\n    Array.isArray(context?.normalizedInvocationArgs) && context?.normalizedInvocationArgs.length > 0\n      ? context.normalizedInvocationArgs\n      : undefined;\n  const attemptedCommand = typeof context?.attemptedCommand === \"string\" ? context.attemptedCommand : renderPmCommandFromArgs(normalizedArgs);\n  const retryCommand = typeof context?.suggestedRetryCommand === \"string\" ? context.suggestedRetryCommand : undefined;\n  return normalizeRecoveryPayload({\n    attempted_command: attemptedCommand,\n    normalized_args: normalizedArgs,\n    provided_fields: providedFields,\n    suggested_retry: retryCommand,\n    ...overrides,\n  });\n}\n\nfunction appendIfMissing(entries: string[], value: string | undefined): string[] {\n  if (!value || entries.includes(value)) {\n    return entries;\n  }\n  return [...entries, value];\n}\n\nfunction buildCommanderErrorGuidance(\n  rawMessage: string,\n  commandName: string | undefined,\n  allowedTypes: string,\n  context?: CommanderGuidanceContext,\n): GuidanceMessage {\n  const message = normalizeMessage(rawMessage);\n\n  const requiredOption = message.match(/required option '([^']+)' not specified/);\n  if (requiredOption) {\n    const optionFlag = normalizeRequiredOptionLabel(requiredOption[1]);\n    const isType = optionFlag.startsWith(\"--type\");\n    const retryCommand = context?.suggestedRetryCommand;\n    const providedFlags = normalizeOptionFlags(context?.providedOptionFlags);\n    const missing = [optionFlag];\n    const examples = commandExampleForRequiredOption(commandName, optionFlag, allowedTypes);\n    const examplesWithRetry = retryCommand ? appendIfMissing(examples, retryCommand) : examples;\n    const nextStepsBase = isType\n      ? [`Allowed type values: ${allowedTypes}`, `Run \"pm ${commandName ?? \"create\"} --help --type <value>\" for type-aware policy details.`]\n      : [`Run \"pm ${commandName ?? \"<command>\"} --help\" for required option guidance.`];\n    const nextStepsWithRetry = retryCommand\n      ? appendIfMissing(nextStepsBase, `Replay with preserved arguments: ${retryCommand}`)\n      : nextStepsBase;\n    const nextSteps =\n      providedFlags && providedFlags.length > 0\n        ? appendIfMissing(nextStepsWithRetry, `Already provided options: ${providedFlags.join(\", \")}`)\n        : nextStepsWithRetry;\n    return makeGuidanceMessage({\n      code: \"missing_required_option\",\n      title: `Missing required option ${optionFlag}`,\n      happened: `Commander rejected the command because ${optionFlag} was not provided.`,\n      required: `Pass ${optionFlag} with a valid value before running the command.`,\n      why: isType\n        ? \"--type selects item contract and policy routing, including required/disabled option rules.\"\n        : \"Required flags define mandatory command intent and prevent ambiguous execution.\",\n      examples: examplesWithRetry,\n      nextSteps,\n      recovery: buildCommanderRecoveryPayload(context, { missing }),\n    });\n  }\n\n  const missingArgument = message.match(/missing required argument '([^']+)'/);\n  if (missingArgument) {\n    const argumentName = missingArgument[1];\n    return makeGuidanceMessage({\n      code: \"missing_required_argument\",\n      title: `Missing required argument ${argumentName}`,\n      happened: `Command invocation omitted positional argument ${argumentName}.`,\n      required: `Provide ${argumentName} in the expected command position.`,\n      why: \"Positional arguments identify the target entity or action context for the command.\",\n      examples: [`pm ${commandName ?? \"<command>\"} --help`],\n      recovery: buildCommanderRecoveryPayload(context, { missing: [argumentName] }),\n    });\n  }\n\n  const unknownOption = message.match(/unknown option '([^']+)'/);\n  if (unknownOption) {\n    const optionName = unknownOption[1];\n    const suggestions = normalizeOptionFlags(context?.unknownOptionSuggestions);\n    const retryCommand = context?.suggestedRetryCommand;\n    if (commandName === \"update\" && (optionName === \"--file\" || optionName === \"--doc\")) {\n      return makeGuidanceMessage({\n        code: \"unsupported_update_option\",\n        title: `Unsupported option ${optionName} for update`,\n        happened: `pm update does not accept ${optionName} for linked artifact mutations.`,\n        required: \"Use dedicated linked-artifact commands instead of pm update for files/docs changes.\",\n        why: \"pm update manages scalar item metadata, while linked files/docs are managed by pm files and pm docs.\",\n        examples: [\n          'pm files pm-a1b2 --add \"path=src/cli/main.ts,scope=project,note=implementation surface\"',\n          'pm docs pm-a1b2 --add \"path=README.md,scope=project,note=user-facing contract\"',\n        ],\n        nextSteps: ['Run \"pm files --help\" and \"pm docs --help\" for add/remove payload formats.'],\n        recovery: buildCommanderRecoveryPayload(context, {\n          missing: suggestions,\n        }),\n      });\n    }\n    const nextSteps = [\n      \"Run command help to confirm the exact option contracts for this command path.\",\n      ...(suggestions && suggestions.length > 0 ? [`Nearest supported options: ${suggestions.join(\", \")}`] : []),\n      ...(retryCommand ? [`Replay with suggested correction: ${retryCommand}`] : []),\n    ];\n    const examples = [\n      ...(retryCommand ? [retryCommand] : []),\n      `pm ${commandName ?? \"<command>\"} --help`,\n    ];\n    return makeGuidanceMessage({\n      code: \"unknown_option\",\n      title: `Unknown option ${optionName}`,\n      happened: `Commander does not recognize option ${optionName} for this command path.`,\n      required: \"Use supported options only, or move option to the correct subcommand.\",\n      why: \"Option contracts are command-specific and intentionally validated.\",\n      examples,\n      nextSteps,\n      recovery: buildCommanderRecoveryPayload(context, {\n        missing: suggestions,\n      }),\n    });\n  }\n\n  const unknownCommand = message.match(/unknown command '([^']+)'/);\n  if (unknownCommand) {\n    const commandToken = unknownCommand[1];\n    const runtimeExamples = normalizeContextList(context?.unknownCommandExamples);\n    const runtimeNextSteps = normalizeContextList(context?.unknownCommandNextSteps);\n    return makeGuidanceMessage({\n      code: \"unknown_command\",\n      title: `Unknown command ${commandToken}`,\n      happened: `pm does not expose command path \"${commandToken}\" in current runtime configuration.`,\n      required: \"Use a valid command name or subcommand path.\",\n      why: \"Command registry includes core commands plus active extension command handlers.\",\n      examples: runtimeExamples ?? [\"pm --help\"],\n      nextSteps: runtimeNextSteps ?? [\"Verify spelling and active extensions, then rerun.\"],\n      recovery: buildCommanderRecoveryPayload(context),\n    });\n  }\n\n  return makeGuidanceMessage({\n    code: \"invalid_command_usage\",\n    title: \"Invalid command usage\",\n    happened: message,\n    required: \"Use the command with valid arguments and options.\",\n    why: \"Commander validates CLI contracts before execution.\",\n    examples: [\"pm --help\", `pm ${commandName ?? \"<command>\"} --help`],\n    recovery: buildCommanderRecoveryPayload(context),\n  });\n}\n\nexport function formatPmCliErrorForDisplay(rawMessage: string, context?: PmCliErrorContext): string {\n  return renderGuidanceMessage(buildPmCliErrorGuidance(rawMessage, context));\n}\n\nexport function classifyPmCliError(rawMessage: string, context?: PmCliErrorContext): ErrorClassification {\n  return guidanceToClassification(buildPmCliErrorGuidance(rawMessage, context));\n}\n\nexport function formatPmCliErrorForJson(rawMessage: string, exitCode: number, context?: PmCliErrorContext): JsonErrorEnvelope {\n  return guidanceToJsonEnvelope(buildPmCliErrorGuidance(rawMessage, context), exitCode);\n}\n\nexport function formatCommanderErrorForDisplay(\n  rawMessage: string,\n  commandName: string | undefined,\n  allowedTypes: string,\n  context?: CommanderGuidanceContext,\n): string {\n  return renderGuidanceMessage(buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, context));\n}\n\nexport function classifyCommanderError(\n  rawMessage: string,\n  commandName: string | undefined,\n  allowedTypes: string,\n  context?: CommanderGuidanceContext,\n): ErrorClassification {\n  return guidanceToClassification(buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, context));\n}\n\nexport function formatCommanderErrorForJson(\n  rawMessage: string,\n  commandName: string | undefined,\n  allowedTypes: string,\n  exitCode: number,\n  context?: CommanderGuidanceContext,\n): JsonErrorEnvelope {\n  return guidanceToJsonEnvelope(buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, context), exitCode);\n}\n\nexport function formatUnknownErrorForJson(rawMessage: string, exitCode: number): JsonErrorEnvelope {\n  const guidance = buildUnknownErrorGuidance(rawMessage);\n  return guidanceToJsonEnvelope(guidance, exitCode);\n}\n\nfunction buildUnknownErrorGuidance(rawMessage: string): GuidanceMessage {\n  return makeGuidanceMessage({\n    code: \"unknown_error\",\n    title: \"Unhandled error\",\n    happened: normalizeMessage(rawMessage),\n    required: \"Inspect command input and runtime state, then retry.\",\n    why: \"Unexpected runtime failures can occur from environment or extension-level issues.\",\n    examples: [\"pm --help\", \"pm health --json\"],\n  });\n}\n\nexport function classifyUnknownError(rawMessage: string): ErrorClassification {\n  return guidanceToClassification(buildUnknownErrorGuidance(rawMessage));\n}\n"]}

package/dist/cli/guide-topics.js

@@ -128,27 +128,29 @@ const GUIDE_TOPICS = [
     },
     {
         id: "extensions",
-        aliases: ["plugins", "extension-authoring"],
-        title: "Extensions",
-        summary: "Install, author, and diagnose extensions with deterministic lifecycle controls.",
-        intent: "Use this for extension management, capability registration, and runtime diagnostics.",
+        aliases: ["plugins", "extension-authoring", "packages", "package-authoring"],
+        title: "Packages and Extensions",
+        summary: "Install, author, and diagnose packages/extensions with deterministic lifecycle controls.",
+        intent: "Use this for package management, extension capability registration, and runtime diagnostics.",
         commands: [
-            "pm extension explore --project",
-            "pm extension install <target> --project",
-            "pm extension manage --detail summary",
-            "pm extension doctor --detail deep",
-            "pm extension activate <target> --project",
-            "pm extension deactivate <target> --project",
+            "pm install <target> --project",
+            "pm upgrade --dry-run",
+            "pm package explore --project",
+            "pm package manage --detail summary",
+            "pm package doctor --detail deep",
+            "pm package activate <target> --project",
+            "pm package deactivate <target> --project",
         ],
         workflows: [
             {
                 name: "Lifecycle Triage",
                 goal: "Diagnose extension state before forceful lifecycle actions.",
-                prompt: "You are debugging extension behavior. Inspect managed state first, then run doctor diagnostics, then apply install/adopt/activate actions.",
+                prompt: "You are debugging package behavior. Inspect managed state first, then run doctor diagnostics, then apply install/adopt/activate actions.",
                 commands: [
-                    "pm extension explore --project",
-                    "pm extension manage --detail summary",
-                    "pm extension doctor --detail deep",
+                    "pm package explore --project",
+                    "pm package manage --detail summary",
+                    "pm package doctor --detail deep",
+                    "pm upgrade --packages-only --dry-run",
                 ],
             },
         ],
@@ -196,8 +198,8 @@ const GUIDE_TOPICS = [
         id: "harnesses",
         aliases: ["compatibility", "agent-compatibility"],
         title: "Agent Harness Compatibility",
-        summary: "Cross-harness compatibility guidance for skill discovery, prompts, and docs routing.",
-        intent: "Use this when adapting pm skills/docs usage for Pi, OpenClaw, Claude Code, Codex CLI, OpenCode, Amp, Droid, Hermes, or Gemini CLI.",
+        summary: "Cross-harness compatibility guidance for docs routing.",
+        intent: "Use this when adapting pm docs and SDK contracts for an external automation harness.",
         commands: ["pm guide skills", "pm guide commands", "pm contracts --runtime-only --availability-only"],
         workflows: [
             {

package/dist/cli/guide-topics.js.map

@@ -1 +1 @@
-{"version":3,"file":"guide-topics.js","sourceRoot":"/","sources":["cli/guide-topics.ts"],"names":[],"mappings":"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","sourcesContent":["export interface GuideDocReference {\n  path: string;\n  purpose: string;\n  optional?: boolean;\n}\n\nexport interface GuideWorkflowTemplate {\n  name: string;\n  goal: string;\n  prompt: string;\n  commands: string[];\n}\n\nexport interface GuideTopicDefinition {\n  id: string;\n  aliases: string[];\n  title: string;\n  summary: string;\n  intent: string;\n  commands: string[];\n  workflows: GuideWorkflowTemplate[];\n  docs: GuideDocReference[];\n  related: string[];\n}\n\nfunction normalizeTopicToken(value: string): string {\n  return value.trim().toLowerCase().replaceAll(\"_\", \"-\");\n}\n\nconst GUIDE_TOPICS: GuideTopicDefinition[] = [\n  {\n    id: \"quickstart\",\n    aliases: [\"start\", \"getting-started\", \"bootstrap\"],\n    title: \"Quickstart\",\n    summary: \"Initialize a tracker and run the shortest safe plan -> execute -> close loop.\",\n    intent: \"Use this when a human or agent needs to start productive work quickly with minimal context load.\",\n    commands: [\n      \"pm init\",\n      \"pm context --limit 10\",\n      \"pm list-open --limit 20\",\n      \"pm create --create-mode progressive --title \\\"...\\\" --description \\\"...\\\" --type Task\",\n      \"pm claim <ID>\",\n      \"pm update <ID> --status in_progress\",\n      \"pm close <ID> \\\"<reason with evidence>\\\" --validate-close warn\",\n    ],\n    workflows: [\n      {\n        name: \"Start Session Safely\",\n        goal: \"Bootstrap without mutating unrelated state.\",\n        prompt:\n          \"You are bootstrapping pm work. Use a token-efficient context snapshot first, then select one open item, claim it, and only then mutate.\",\n        commands: [\"pm context --limit 10\", \"pm list-open --limit 20\", \"pm claim <ID>\"],\n      },\n    ],\n    docs: [\n      { path: \"README.md\", purpose: \"High-level project and install entrypoint.\" },\n      { path: \"docs/QUICKSTART.md\", purpose: \"Short setup and first-command walkthrough.\" },\n      { path: \"docs/COMMANDS.md\", purpose: \"Task-oriented command recipes.\" },\n    ],\n    related: [\"commands\", \"workflows\", \"release\"],\n  },\n  {\n    id: \"commands\",\n    aliases: [\"cli\", \"operations\", \"reference\"],\n    title: \"CLI Command Routing\",\n    summary: \"Find the right command family quickly and use command-scoped help/contracts output.\",\n    intent: \"Use this when selecting command paths, flags, and output formats for implementation or automation.\",\n    commands: [\n      \"pm --help\",\n      \"pm <command> --help\",\n      \"pm <command> --help --explain\",\n      \"pm contracts --command <command> --flags-only\",\n      \"pm contracts --command <command> --availability-only --runtime-only\",\n      \"pm completion <bash|zsh|fish>\",\n    ],\n    workflows: [\n      {\n        name: \"Flag Discovery\",\n        goal: \"Resolve command flags deterministically before mutations.\",\n        prompt:\n          \"You are preparing to run a command. Use help and contracts surfaces to verify required/optional flags before execution.\",\n        commands: [\"pm <command> --help --explain\", \"pm contracts --command <command> --flags-only\"],\n      },\n    ],\n    docs: [\n      { path: \"docs/COMMANDS.md\", purpose: \"Command grouping and examples.\" },\n      { path: \"docs/CONFIGURATION.md\", purpose: \"Project/global settings and policy controls.\" },\n      { path: \"docs/TESTING.md\", purpose: \"Linked-test orchestration and safety guidance.\" },\n    ],\n    related: [\"quickstart\", \"workflows\", \"sdk\", \"extensions\"],\n  },\n  {\n    id: \"workflows\",\n    aliases: [\"developer\", \"maintainer\", \"agent\"],\n    title: \"Developer and Agent Workflows\",\n    summary: \"Apply canonical claim -> execute -> verify -> close workflows with append-only evidence.\",\n    intent: \"Use this for day-to-day coding-agent execution loops and handoff-safe updates.\",\n    commands: [\n      \"pm claim <ID>\",\n      \"pm update <ID> --status in_progress\",\n      \"pm files <ID> --add ...\",\n      \"pm test <ID> --add ...\",\n      \"pm comments <ID> \\\"...\\\"\",\n      \"pm validate --check-resolution --check-history-drift\",\n      \"pm release <ID>\",\n    ],\n    workflows: [\n      {\n        name: \"Execution Loop\",\n        goal: \"Keep code, tests, and tracker evidence synchronized.\",\n        prompt:\n          \"You are implementing a scoped change. Claim first, link files/tests/docs as you go, append evidence comments, and close only after validation.\",\n        commands: [\n          \"pm claim <ID>\",\n          \"pm update <ID> --status in_progress\",\n          \"pm files <ID> --add path=<file>,scope=project\",\n          \"pm test <ID> --run --progress\",\n          \"pm close <ID> \\\"<evidence>\\\" --validate-close warn\",\n        ],\n      },\n    ],\n    docs: [\n      { path: \"AGENTS.md\", purpose: \"Repository operating rules and required workflow.\" },\n      { path: \"docs/AGENT_GUIDE.md\", purpose: \"Agent-oriented usage and context strategy.\" },\n      { path: \"docs/TESTING.md\", purpose: \"Sandbox-safe test execution rules.\" },\n    ],\n    related: [\"quickstart\", \"commands\", \"skills\"],\n  },\n  {\n    id: \"sdk\",\n    aliases: [\"api\", \"typescript-sdk\"],\n    title: \"SDK and Integrations\",\n    summary: \"Use the published SDK surface for extension authoring and contract-safe integrations.\",\n    intent: \"Use this when building or reviewing programmatic integrations against @unbrained/pm-cli/sdk.\",\n    commands: [\n      \"pm contracts --schema-only\",\n      \"pm contracts --command extension --flags-only\",\n      \"pm contracts --runtime-only --availability-only\",\n    ],\n    workflows: [\n      {\n        name: \"Integration Contract Check\",\n        goal: \"Confirm action schemas and runtime availability before coding.\",\n        prompt:\n          \"You are wiring an integration. Capture schema + runtime availability first, then map your adapter payload fields to contract keys.\",\n        commands: [\n          \"pm contracts --schema-only\",\n          \"pm contracts --availability-only --runtime-only\",\n          \"pm contracts --command <command> --flags-only\",\n        ],\n      },\n    ],\n    docs: [\n      { path: \"docs/SDK.md\", purpose: \"Public SDK exports and extension authoring references.\" },\n      { path: \"docs/ARCHITECTURE.md\", purpose: \"Core runtime composition and extension load flow.\" },\n    ],\n    related: [\"extensions\", \"commands\"],\n  },\n  {\n    id: \"extensions\",\n    aliases: [\"plugins\", \"extension-authoring\"],\n    title: \"Extensions\",\n    summary: \"Install, author, and diagnose extensions with deterministic lifecycle controls.\",\n    intent: \"Use this for extension management, capability registration, and runtime diagnostics.\",\n    commands: [\n      \"pm extension explore --project\",\n      \"pm extension install <target> --project\",\n      \"pm extension manage --detail summary\",\n      \"pm extension doctor --detail deep\",\n      \"pm extension activate <target> --project\",\n      \"pm extension deactivate <target> --project\",\n    ],\n    workflows: [\n      {\n        name: \"Lifecycle Triage\",\n        goal: \"Diagnose extension state before forceful lifecycle actions.\",\n        prompt:\n          \"You are debugging extension behavior. Inspect managed state first, then run doctor diagnostics, then apply install/adopt/activate actions.\",\n        commands: [\n          \"pm extension explore --project\",\n          \"pm extension manage --detail summary\",\n          \"pm extension doctor --detail deep\",\n        ],\n      },\n    ],\n    docs: [\n      { path: \"docs/EXTENSIONS.md\", purpose: \"Capability model and lifecycle command usage.\" },\n      {\n        path: \"docs/examples/starter-extension/README.md\",\n        purpose: \"Starter extension scaffold and local development path.\",\n      },\n      { path: \"docs/SDK.md\", purpose: \"SDK contracts used by extension implementations.\" },\n    ],\n    related: [\"sdk\", \"commands\", \"skills\"],\n  },\n  {\n    id: \"skills\",\n    aliases: [\"agent-skills\", \"agentskills\"],\n    title: \"Agent Skills\",\n    summary: \"Skill bundles for developer, user, extensions, and sdk workflows aligned to the current CLI.\",\n    intent: \"Use this when an agent needs reproducible prompts/workflows with strict compatibility metadata.\",\n    commands: [\n      \"pm guide skills --depth deep\",\n      \"pm contracts --command guide --flags-only\",\n      \"pm validate --check-command-references\",\n    ],\n    workflows: [\n      {\n        name: \"Skill Selection\",\n        goal: \"Pick the narrowest compatible skill first to minimize context usage.\",\n        prompt:\n          \"Select a pm skill based on the task intent, then execute only the workflow section needed for the current change.\",\n        commands: [\"pm guide skills\", \"pm guide skills --depth deep\"],\n      },\n    ],\n    docs: [\n      { path: \"docs/AGENT_GUIDE.md\", purpose: \"Agent-first usage and context model.\" },\n      { path: \"docs/README.md\", purpose: \"Documentation routing with progressive disclosure.\" },\n      { path: \".agents/skills/README.md\", purpose: \"Agent skills index and routing overview.\" },\n      { path: \".agents/skills/pm-developer/SKILL.md\", purpose: \"Developer-oriented pm skill workflow.\" },\n      { path: \".agents/skills/pm-user/SKILL.md\", purpose: \"User/operator pm skill workflow.\" },\n      { path: \".agents/skills/pm-extensions/SKILL.md\", purpose: \"Extension-focused pm skill workflow.\" },\n      { path: \".agents/skills/pm-sdk/SKILL.md\", purpose: \"SDK integration pm skill workflow.\" },\n    ],\n    related: [\"workflows\", \"harnesses\", \"commands\"],\n  },\n  {\n    id: \"harnesses\",\n    aliases: [\"compatibility\", \"agent-compatibility\"],\n    title: \"Agent Harness Compatibility\",\n    summary: \"Cross-harness compatibility guidance for skill discovery, prompts, and docs routing.\",\n    intent: \"Use this when adapting pm skills/docs usage for Pi, OpenClaw, Claude Code, Codex CLI, OpenCode, Amp, Droid, Hermes, or Gemini CLI.\",\n    commands: [\"pm guide skills\", \"pm guide commands\", \"pm contracts --runtime-only --availability-only\"],\n    workflows: [\n      {\n        name: \"Harness Mapping\",\n        goal: \"Route each harness to the same canonical skill/docs sources.\",\n        prompt:\n          \"Map harness-specific entrypoints to the same pm guide topics and .agents/skills workflows without adding runtime harness-specific code.\",\n        commands: [\"pm guide harnesses --depth standard\", \"pm guide skills --depth deep\"],\n      },\n    ],\n    docs: [\n      { path: \"docs/AGENT_GUIDE.md\", purpose: \"Agent context and output-mode conventions.\" },\n      { path: \"docs/README.md\", purpose: \"Single-source documentation routing entrypoint.\" },\n      { path: \".agents/skills/HARNESS_COMPATIBILITY.md\", purpose: \"Harness compatibility matrix and usage notes.\" },\n    ],\n    related: [\"skills\", \"workflows\"],\n  },\n  {\n    id: \"release\",\n    aliases: [\"gates\", \"ship\", \"release-readiness\"],\n    title: \"Release and Staleness Gates\",\n    summary: \"Run release gates and docs/skills freshness checks before publishing.\",\n    intent: \"Use this when validating release readiness and preventing docs/skills drift.\",\n    commands: [\n      \"pnpm build\",\n      \"pnpm test:coverage\",\n      \"pnpm quality:static\",\n      \"node scripts/release/run-gates.mjs --telemetry-mode best-effort\",\n      \"pnpm security:scan\",\n    ],\n    workflows: [\n      {\n        name: \"Pre-Release Gate Sweep\",\n        goal: \"Ensure code, docs, and skills are all green before publish.\",\n        prompt:\n          \"Run release gates in deterministic order and treat docs/skills freshness failures as release blockers.\",\n        commands: [\n          \"pnpm build\",\n          \"pnpm test:coverage\",\n          \"node scripts/release/run-gates.mjs --telemetry-mode best-effort\",\n        ],\n      },\n    ],\n    docs: [\n      { path: \"docs/RELEASING.md\", purpose: \"Release flow and safety checks.\" },\n      { path: \"CHANGELOG.md\", purpose: \"Versioned release history and unreleased notes.\" },\n      { path: \"scripts/release/run-gates.mjs\", purpose: \"Source of truth for release gate ordering.\" },\n    ],\n    related: [\"commands\", \"skills\", \"workflows\"],\n  },\n];\n\nconst TOPIC_BY_TOKEN = new Map<string, GuideTopicDefinition>();\nfor (const topic of GUIDE_TOPICS) {\n  TOPIC_BY_TOKEN.set(topic.id, topic);\n  for (const alias of topic.aliases) {\n    TOPIC_BY_TOKEN.set(alias, topic);\n  }\n}\n\nexport function listGuideTopics(): GuideTopicDefinition[] {\n  return GUIDE_TOPICS.map((topic) => ({\n    ...topic,\n    aliases: [...topic.aliases],\n    commands: [...topic.commands],\n    workflows: topic.workflows.map((workflow) => ({\n      ...workflow,\n      commands: [...workflow.commands],\n    })),\n    docs: topic.docs.map((doc) => ({ ...doc })),\n    related: [...topic.related],\n  }));\n}\n\nexport function listGuideTopicIds(): string[] {\n  return GUIDE_TOPICS.map((topic) => topic.id);\n}\n\nexport function resolveGuideTopic(rawTopic: string | undefined): GuideTopicDefinition | null {\n  if (!rawTopic) {\n    return null;\n  }\n  const normalized = normalizeTopicToken(rawTopic);\n  if (!normalized) {\n    return null;\n  }\n  return TOPIC_BY_TOKEN.get(normalized) ?? null;\n}\n\n"]}
+{"version":3,"file":"guide-topics.js","sourceRoot":"/","sources":["cli/guide-topics.ts"],"names":[],"mappings":"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","sourcesContent":["export interface GuideDocReference {\n  path: string;\n  purpose: string;\n  optional?: boolean;\n}\n\nexport interface GuideWorkflowTemplate {\n  name: string;\n  goal: string;\n  prompt: string;\n  commands: string[];\n}\n\nexport interface GuideTopicDefinition {\n  id: string;\n  aliases: string[];\n  title: string;\n  summary: string;\n  intent: string;\n  commands: string[];\n  workflows: GuideWorkflowTemplate[];\n  docs: GuideDocReference[];\n  related: string[];\n}\n\nfunction normalizeTopicToken(value: string): string {\n  return value.trim().toLowerCase().replaceAll(\"_\", \"-\");\n}\n\nconst GUIDE_TOPICS: GuideTopicDefinition[] = [\n  {\n    id: \"quickstart\",\n    aliases: [\"start\", \"getting-started\", \"bootstrap\"],\n    title: \"Quickstart\",\n    summary: \"Initialize a tracker and run the shortest safe plan -> execute -> close loop.\",\n    intent: \"Use this when a human or agent needs to start productive work quickly with minimal context load.\",\n    commands: [\n      \"pm init\",\n      \"pm context --limit 10\",\n      \"pm list-open --limit 20\",\n      \"pm create --create-mode progressive --title \\\"...\\\" --description \\\"...\\\" --type Task\",\n      \"pm claim <ID>\",\n      \"pm update <ID> --status in_progress\",\n      \"pm close <ID> \\\"<reason with evidence>\\\" --validate-close warn\",\n    ],\n    workflows: [\n      {\n        name: \"Start Session Safely\",\n        goal: \"Bootstrap without mutating unrelated state.\",\n        prompt:\n          \"You are bootstrapping pm work. Use a token-efficient context snapshot first, then select one open item, claim it, and only then mutate.\",\n        commands: [\"pm context --limit 10\", \"pm list-open --limit 20\", \"pm claim <ID>\"],\n      },\n    ],\n    docs: [\n      { path: \"README.md\", purpose: \"High-level project and install entrypoint.\" },\n      { path: \"docs/QUICKSTART.md\", purpose: \"Short setup and first-command walkthrough.\" },\n      { path: \"docs/COMMANDS.md\", purpose: \"Task-oriented command recipes.\" },\n    ],\n    related: [\"commands\", \"workflows\", \"release\"],\n  },\n  {\n    id: \"commands\",\n    aliases: [\"cli\", \"operations\", \"reference\"],\n    title: \"CLI Command Routing\",\n    summary: \"Find the right command family quickly and use command-scoped help/contracts output.\",\n    intent: \"Use this when selecting command paths, flags, and output formats for implementation or automation.\",\n    commands: [\n      \"pm --help\",\n      \"pm <command> --help\",\n      \"pm <command> --help --explain\",\n      \"pm contracts --command <command> --flags-only\",\n      \"pm contracts --command <command> --availability-only --runtime-only\",\n      \"pm completion <bash|zsh|fish>\",\n    ],\n    workflows: [\n      {\n        name: \"Flag Discovery\",\n        goal: \"Resolve command flags deterministically before mutations.\",\n        prompt:\n          \"You are preparing to run a command. Use help and contracts surfaces to verify required/optional flags before execution.\",\n        commands: [\"pm <command> --help --explain\", \"pm contracts --command <command> --flags-only\"],\n      },\n    ],\n    docs: [\n      { path: \"docs/COMMANDS.md\", purpose: \"Command grouping and examples.\" },\n      { path: \"docs/CONFIGURATION.md\", purpose: \"Project/global settings and policy controls.\" },\n      { path: \"docs/TESTING.md\", purpose: \"Linked-test orchestration and safety guidance.\" },\n    ],\n    related: [\"quickstart\", \"workflows\", \"sdk\", \"extensions\"],\n  },\n  {\n    id: \"workflows\",\n    aliases: [\"developer\", \"maintainer\", \"agent\"],\n    title: \"Developer and Agent Workflows\",\n    summary: \"Apply canonical claim -> execute -> verify -> close workflows with append-only evidence.\",\n    intent: \"Use this for day-to-day coding-agent execution loops and handoff-safe updates.\",\n    commands: [\n      \"pm claim <ID>\",\n      \"pm update <ID> --status in_progress\",\n      \"pm files <ID> --add ...\",\n      \"pm test <ID> --add ...\",\n      \"pm comments <ID> \\\"...\\\"\",\n      \"pm validate --check-resolution --check-history-drift\",\n      \"pm release <ID>\",\n    ],\n    workflows: [\n      {\n        name: \"Execution Loop\",\n        goal: \"Keep code, tests, and tracker evidence synchronized.\",\n        prompt:\n          \"You are implementing a scoped change. Claim first, link files/tests/docs as you go, append evidence comments, and close only after validation.\",\n        commands: [\n          \"pm claim <ID>\",\n          \"pm update <ID> --status in_progress\",\n          \"pm files <ID> --add path=<file>,scope=project\",\n          \"pm test <ID> --run --progress\",\n          \"pm close <ID> \\\"<evidence>\\\" --validate-close warn\",\n        ],\n      },\n    ],\n    docs: [\n      { path: \"AGENTS.md\", purpose: \"Repository operating rules and required workflow.\" },\n      { path: \"docs/AGENT_GUIDE.md\", purpose: \"Agent-oriented usage and context strategy.\" },\n      { path: \"docs/TESTING.md\", purpose: \"Sandbox-safe test execution rules.\" },\n    ],\n    related: [\"quickstart\", \"commands\", \"skills\"],\n  },\n  {\n    id: \"sdk\",\n    aliases: [\"api\", \"typescript-sdk\"],\n    title: \"SDK and Integrations\",\n    summary: \"Use the published SDK surface for extension authoring and contract-safe integrations.\",\n    intent: \"Use this when building or reviewing programmatic integrations against @unbrained/pm-cli/sdk.\",\n    commands: [\n      \"pm contracts --schema-only\",\n      \"pm contracts --command extension --flags-only\",\n      \"pm contracts --runtime-only --availability-only\",\n    ],\n    workflows: [\n      {\n        name: \"Integration Contract Check\",\n        goal: \"Confirm action schemas and runtime availability before coding.\",\n        prompt:\n          \"You are wiring an integration. Capture schema + runtime availability first, then map your adapter payload fields to contract keys.\",\n        commands: [\n          \"pm contracts --schema-only\",\n          \"pm contracts --availability-only --runtime-only\",\n          \"pm contracts --command <command> --flags-only\",\n        ],\n      },\n    ],\n    docs: [\n      { path: \"docs/SDK.md\", purpose: \"Public SDK exports and extension authoring references.\" },\n      { path: \"docs/ARCHITECTURE.md\", purpose: \"Core runtime composition and extension load flow.\" },\n    ],\n    related: [\"extensions\", \"commands\"],\n  },\n  {\n    id: \"extensions\",\n    aliases: [\"plugins\", \"extension-authoring\", \"packages\", \"package-authoring\"],\n    title: \"Packages and Extensions\",\n    summary: \"Install, author, and diagnose packages/extensions with deterministic lifecycle controls.\",\n    intent: \"Use this for package management, extension capability registration, and runtime diagnostics.\",\n    commands: [\n      \"pm install <target> --project\",\n      \"pm upgrade --dry-run\",\n      \"pm package explore --project\",\n      \"pm package manage --detail summary\",\n      \"pm package doctor --detail deep\",\n      \"pm package activate <target> --project\",\n      \"pm package deactivate <target> --project\",\n    ],\n    workflows: [\n      {\n        name: \"Lifecycle Triage\",\n        goal: \"Diagnose extension state before forceful lifecycle actions.\",\n        prompt:\n          \"You are debugging package behavior. Inspect managed state first, then run doctor diagnostics, then apply install/adopt/activate actions.\",\n        commands: [\n          \"pm package explore --project\",\n          \"pm package manage --detail summary\",\n          \"pm package doctor --detail deep\",\n          \"pm upgrade --packages-only --dry-run\",\n        ],\n      },\n    ],\n    docs: [\n      { path: \"docs/EXTENSIONS.md\", purpose: \"Capability model and lifecycle command usage.\" },\n      {\n        path: \"docs/examples/starter-extension/README.md\",\n        purpose: \"Starter extension scaffold and local development path.\",\n      },\n      { path: \"docs/SDK.md\", purpose: \"SDK contracts used by extension implementations.\" },\n    ],\n    related: [\"sdk\", \"commands\", \"skills\"],\n  },\n  {\n    id: \"skills\",\n    aliases: [\"agent-skills\", \"agentskills\"],\n    title: \"Agent Skills\",\n    summary: \"Skill bundles for developer, user, extensions, and sdk workflows aligned to the current CLI.\",\n    intent: \"Use this when an agent needs reproducible prompts/workflows with strict compatibility metadata.\",\n    commands: [\n      \"pm guide skills --depth deep\",\n      \"pm contracts --command guide --flags-only\",\n      \"pm validate --check-command-references\",\n    ],\n    workflows: [\n      {\n        name: \"Skill Selection\",\n        goal: \"Pick the narrowest compatible skill first to minimize context usage.\",\n        prompt:\n          \"Select a pm skill based on the task intent, then execute only the workflow section needed for the current change.\",\n        commands: [\"pm guide skills\", \"pm guide skills --depth deep\"],\n      },\n    ],\n    docs: [\n      { path: \"docs/AGENT_GUIDE.md\", purpose: \"Agent-first usage and context model.\" },\n      { path: \"docs/README.md\", purpose: \"Documentation routing with progressive disclosure.\" },\n      { path: \".agents/skills/README.md\", purpose: \"Agent skills index and routing overview.\" },\n      { path: \".agents/skills/pm-developer/SKILL.md\", purpose: \"Developer-oriented pm skill workflow.\" },\n      { path: \".agents/skills/pm-user/SKILL.md\", purpose: \"User/operator pm skill workflow.\" },\n      { path: \".agents/skills/pm-extensions/SKILL.md\", purpose: \"Extension-focused pm skill workflow.\" },\n      { path: \".agents/skills/pm-sdk/SKILL.md\", purpose: \"SDK integration pm skill workflow.\" },\n    ],\n    related: [\"workflows\", \"harnesses\", \"commands\"],\n  },\n  {\n    id: \"harnesses\",\n    aliases: [\"compatibility\", \"agent-compatibility\"],\n    title: \"Agent Harness Compatibility\",\n    summary: \"Cross-harness compatibility guidance for docs routing.\",\n    intent: \"Use this when adapting pm docs and SDK contracts for an external automation harness.\",\n    commands: [\"pm guide skills\", \"pm guide commands\", \"pm contracts --runtime-only --availability-only\"],\n    workflows: [\n      {\n        name: \"Harness Mapping\",\n        goal: \"Route each harness to the same canonical skill/docs sources.\",\n        prompt:\n          \"Map harness-specific entrypoints to the same pm guide topics and .agents/skills workflows without adding runtime harness-specific code.\",\n        commands: [\"pm guide harnesses --depth standard\", \"pm guide skills --depth deep\"],\n      },\n    ],\n    docs: [\n      { path: \"docs/AGENT_GUIDE.md\", purpose: \"Agent context and output-mode conventions.\" },\n      { path: \"docs/README.md\", purpose: \"Single-source documentation routing entrypoint.\" },\n      { path: \".agents/skills/HARNESS_COMPATIBILITY.md\", purpose: \"Harness compatibility matrix and usage notes.\" },\n    ],\n    related: [\"skills\", \"workflows\"],\n  },\n  {\n    id: \"release\",\n    aliases: [\"gates\", \"ship\", \"release-readiness\"],\n    title: \"Release and Staleness Gates\",\n    summary: \"Run release gates and docs/skills freshness checks before publishing.\",\n    intent: \"Use this when validating release readiness and preventing docs/skills drift.\",\n    commands: [\n      \"pnpm build\",\n      \"pnpm test:coverage\",\n      \"pnpm quality:static\",\n      \"node scripts/release/run-gates.mjs --telemetry-mode best-effort\",\n      \"pnpm security:scan\",\n    ],\n    workflows: [\n      {\n        name: \"Pre-Release Gate Sweep\",\n        goal: \"Ensure code, docs, and skills are all green before publish.\",\n        prompt:\n          \"Run release gates in deterministic order and treat docs/skills freshness failures as release blockers.\",\n        commands: [\n          \"pnpm build\",\n          \"pnpm test:coverage\",\n          \"node scripts/release/run-gates.mjs --telemetry-mode best-effort\",\n        ],\n      },\n    ],\n    docs: [\n      { path: \"docs/RELEASING.md\", purpose: \"Release flow and safety checks.\" },\n      { path: \"CHANGELOG.md\", purpose: \"Versioned release history and unreleased notes.\" },\n      { path: \"scripts/release/run-gates.mjs\", purpose: \"Source of truth for release gate ordering.\" },\n    ],\n    related: [\"commands\", \"skills\", \"workflows\"],\n  },\n];\n\nconst TOPIC_BY_TOKEN = new Map<string, GuideTopicDefinition>();\nfor (const topic of GUIDE_TOPICS) {\n  TOPIC_BY_TOKEN.set(topic.id, topic);\n  for (const alias of topic.aliases) {\n    TOPIC_BY_TOKEN.set(alias, topic);\n  }\n}\n\nexport function listGuideTopics(): GuideTopicDefinition[] {\n  return GUIDE_TOPICS.map((topic) => ({\n    ...topic,\n    aliases: [...topic.aliases],\n    commands: [...topic.commands],\n    workflows: topic.workflows.map((workflow) => ({\n      ...workflow,\n      commands: [...workflow.commands],\n    })),\n    docs: topic.docs.map((doc) => ({ ...doc })),\n    related: [...topic.related],\n  }));\n}\n\nexport function listGuideTopicIds(): string[] {\n  return GUIDE_TOPICS.map((topic) => topic.id);\n}\n\nexport function resolveGuideTopic(rawTopic: string | undefined): GuideTopicDefinition | null {\n  if (!rawTopic) {\n    return null;\n  }\n  const normalized = normalizeTopicToken(rawTopic);\n  if (!normalized) {\n    return null;\n  }\n  return TOPIC_BY_TOKEN.get(normalized) ?? null;\n}\n"]}

package/dist/cli/help-content.js

@@ -101,8 +101,8 @@ const HELP_BY_COMMAND_PATH = {
             "pm extension install beads --project",
             "pm extension install todos --global",
             "pm extension install .agents/pm/extensions/sample --project",
-            "pm extension install https://github.com/unbraind/pm-cli/tree/main/.agents/pm/extensions/pi --global",
-            "pm extension install --gh unbraind/pm-cli/pi --project",
+            "pm extension install https://github.com/org/repo/tree/main/extensions/sample --global",
+            "pm extension install --gh org/repo/extensions/sample --project",
             "pm extension explore --project",
             "pm extension manage --global",
             "pm extension doctor --detail deep",
@@ -125,6 +125,46 @@ const HELP_BY_COMMAND_PATH = {
             "Use --doctor for consolidated diagnostics with warning codes, remediation hints, and optional deep detail payloads.",
         ],
     },
+    package: {
+        why: "Installs, explores, manages, diagnoses, adopts, activates, deactivates, and refreshes package-backed pm runtime extensions.",
+        examples: [
+            "pm install npm:@scope/pm-package --project",
+            "pm package install ./my-package --project",
+            "pm package doctor --project --detail deep",
+            "pm package manage --project --runtime-probe",
+            "pm package activate sample-ext --project",
+            "pm upgrade --packages-only --dry-run",
+        ],
+        tips: [
+            "Prefer package vocabulary for user-facing workflows; extension vocabulary remains available for compatibility.",
+            "Use pm upgrade to refresh the CLI/SDK and managed packages from their recorded sources.",
+            "Use --dry-run before upgrade when automation needs a deterministic plan.",
+        ],
+    },
+    install: {
+        why: "Installs a pm package into project scope by default, using local, npm, GitHub, or bundled alias sources.",
+        examples: [
+            "pm install ./packages/pm-todos --project",
+            "pm install npm:@scope/pm-package --global",
+            "pm install --github org/repo/packages/my-pm-package --ref main",
+        ],
+        tips: ["Installed packages are recorded in managed state and can be inspected with pm package manage."],
+    },
+    upgrade: {
+        why: "Updates the global pm CLI/SDK and refreshes managed pm packages from recorded install sources.",
+        examples: [
+            "pm upgrade --dry-run",
+            "pm upgrade --packages-only --project",
+            "pm upgrade todos --dry-run",
+            "pm upgrade --cli-only --repair",
+            "pm upgrade --tag next --dry-run",
+        ],
+        tips: [
+            "Omit target to include the CLI/SDK plus all managed packages in the selected scope.",
+            "Pass a target to refresh one managed package by name, directory, package name, or source.",
+            "Use --packages-only in repository automation when the global CLI should not be changed.",
+        ],
+    },
     create: {
         why: "Creates a new planning item with deterministic metadata and history.",
         examples: [