@unbrained/pm-cli 2026.5.6 → 2026.5.11

package/dist/cli/commands/comments.js

@@ -1,3 +1,4 @@
+import { readFile } from "node:fs/promises";
 import { pathExists } from "../../core/fs/fs-utils.js";
 import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
 import { resolveItemTypeRegistry } from "../../core/item/type-registry.js";
@@ -43,6 +44,53 @@ function parseCommentTextInput(raw) {
         return trimmed;
     }
 }
+function isErrnoError(error) {
+    return typeof error === "object" && error !== null && "code" in error;
+}
+async function resolveCommentInput(options, stdinResolver) {
+    const hasAdd = options.add !== undefined;
+    const hasStdin = options.stdin === true;
+    const hasFile = typeof options.file === "string";
+    const sourceCount = Number(hasAdd) + Number(hasStdin) + Number(hasFile);
+    if (sourceCount === 0) {
+        return { mode: "list" };
+    }
+    if (sourceCount > 1) {
+        throw new PmCliError("Specify comment text using only one input source: --add, --stdin, or --file", EXIT_CODE.USAGE);
+    }
+    if (hasAdd) {
+        const addInput = await stdinResolver.resolveValue(options.add, "--add");
+        return {
+            mode: "add",
+            value: addInput ?? "",
+        };
+    }
+    if (hasStdin) {
+        const stdinInput = await stdinResolver.resolveValue("-", "--stdin");
+        return {
+            mode: "stdin",
+            value: stdinInput ?? "",
+        };
+    }
+    const filePath = options.file?.trim() ?? "";
+    if (!filePath) {
+        throw new PmCliError("--file path cannot be empty", EXIT_CODE.USAGE);
+    }
+    try {
+        const fileInput = await readFile(filePath, "utf8");
+        return {
+            mode: "file",
+            value: fileInput,
+        };
+    }
+    catch (error) {
+        if (isErrnoError(error) && error.code === "ENOENT") {
+            throw new PmCliError(`--file path not found: ${filePath}`, EXIT_CODE.USAGE);
+        }
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new PmCliError(`Failed to read --file path "${filePath}": ${detail}`, EXIT_CODE.USAGE);
+    }
+}
 export async function runComments(id, options, global) {
     const stdinResolver = createStdinTokenResolver();
     const pmRoot = resolvePmRoot(process.cwd(), global.path);
@@ -52,13 +100,14 @@ export async function runComments(id, options, global) {
     const settings = await readSettings(pmRoot);
     const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
     const limit = parseLimit(options.limit);
-    if (options.add === undefined) {
+    const commentInput = await resolveCommentInput(options, stdinResolver);
+    if (commentInput.mode === "list") {
         const located = await locateItem(pmRoot, id, settings.id_prefix, settings.item_format, typeRegistry.type_to_folder);
         if (!located) {
             throw new PmCliError(`Item ${id} not found`, EXIT_CODE.NOT_FOUND);
         }
         const loaded = await readLocatedItem(located, { schema: settings.schema });
-        const comments = limitComments(loaded.document.front_matter.comments ?? [], limit);
+        const comments = limitComments(loaded.document.metadata.comments ?? [], limit);
         return {
             id: located.id,
             comments,
@@ -66,10 +115,10 @@ export async function runComments(id, options, global) {
         };
     }
     const author = resolveAuthor(options.author, settings.author_default);
-    const addInput = await stdinResolver.resolveValue(options.add, "--add");
-    const text = parseCommentTextInput(addInput ?? "");
-    if (!text) {
-        throw new PmCliError("--add text cannot be empty", EXIT_CODE.USAGE);
+    const text = commentInput.mode === "add" ? parseCommentTextInput(commentInput.value ?? "") : (commentInput.value ?? "");
+    if (!text.trim()) {
+        const inputFlag = commentInput.mode === "add" ? "--add" : commentInput.mode === "stdin" ? "--stdin" : "--file";
+        throw new PmCliError(`${inputFlag} text cannot be empty`, EXIT_CODE.USAGE);
     }
     let result;
     try {
@@ -83,13 +132,13 @@ export async function runComments(id, options, global) {
             force: options.force,
             bypassAssigneeConflict: Boolean(options.allowAuditComment),
             mutate(document) {
-                const comments = document.front_matter.comments ?? [];
+                const comments = document.metadata.comments ?? [];
                 comments.push({
                     created_at: nowIso(),
                     author,
                     text,
                 });
-                document.front_matter.comments = comments;
+                document.metadata.comments = comments;
                 return { changedFields: ["comments"] };
             },
         });

package/dist/cli/commands/comments.js.map

@@ -1 +1 @@
-{"version":3,"file":"comments.js","sourceRoot":"/","sources":["cli/commands/comments.ts"],"names":[],"mappings":"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","sourcesContent":["import { pathExists } from \"../../core/fs/fs-utils.js\";\nimport { getActiveExtensionRegistrations } from \"../../core/extensions/index.js\";\nimport { resolveItemTypeRegistry } from \"../../core/item/type-registry.js\";\nimport { EXIT_CODE } from \"../../core/shared/constants.js\";\nimport type { GlobalOptions } from \"../../core/shared/command-types.js\";\nimport { PmCliError } from \"../../core/shared/errors.js\";\nimport { nowIso } from \"../../core/shared/time.js\";\nimport { createStdinTokenResolver, parseCsvKv } from \"../../core/item/parse.js\";\nimport { locateItem, mutateItem, readLocatedItem } from \"../../core/store/item-store.js\";\nimport { getSettingsPath, resolvePmRoot } from \"../../core/store/paths.js\";\nimport { readSettings } from \"../../core/store/settings.js\";\nimport { parseLimit } from \"../shared-parsers.js\";\nimport type { Comment } from \"../../types/index.js\";\n\nexport interface CommentsCommandOptions {\n  add?: string;\n  limit?: string;\n  author?: string;\n  message?: string;\n  force?: boolean;\n  allowAuditComment?: boolean;\n}\n\nexport interface CommentsResult {\n  id: string;\n  comments: Comment[];\n  count: number;\n}\n\nfunction resolveAuthor(candidate: string | undefined, fallback: string): string {\n  const resolved = candidate ?? process.env.PM_AUTHOR ?? fallback;\n  const trimmed = resolved.trim();\n  return trimmed || \"unknown\";\n}\n\nfunction limitComments(values: Comment[], limit: number | undefined): Comment[] {\n  if (limit === undefined) return values;\n  if (limit === 0) return [];\n  return values.slice(Math.max(0, values.length - limit));\n}\n\nfunction parseCommentTextInput(raw: string): string {\n  const trimmed = raw.trim();\n  if (!trimmed) {\n    return \"\";\n  }\n  const looksStructured = /^(?:[-*+]\\s*)?text\\s*[:=]/im.test(trimmed) || trimmed.startsWith(\"```\");\n  if (!looksStructured) {\n    return trimmed;\n  }\n  try {\n    const kv = parseCsvKv(trimmed, \"--add\");\n    const keys = Object.keys(kv).map((key) => key.trim().toLowerCase());\n    if (keys.some((key) => key !== \"text\")) {\n      return trimmed;\n    }\n    const text = kv.text?.trim();\n    return text || trimmed;\n  } catch {\n    return trimmed;\n  }\n}\n\nexport async function runComments(id: string, options: CommentsCommandOptions, global: GlobalOptions): Promise<CommentsResult> {\n  const stdinResolver = createStdinTokenResolver();\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  if (!(await pathExists(getSettingsPath(pmRoot)))) {\n    throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);\n  }\n  const settings = await readSettings(pmRoot);\n  const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());\n  const limit = parseLimit(options.limit);\n\n  if (options.add === undefined) {\n    const located = await locateItem(pmRoot, id, settings.id_prefix, settings.item_format, typeRegistry.type_to_folder);\n    if (!located) {\n      throw new PmCliError(`Item ${id} not found`, EXIT_CODE.NOT_FOUND);\n    }\n    const loaded = await readLocatedItem(located, { schema: settings.schema });\n    const comments = limitComments(loaded.document.front_matter.comments ?? [], limit);\n    return {\n      id: located.id,\n      comments,\n      count: comments.length,\n    };\n  }\n\n  const author = resolveAuthor(options.author, settings.author_default);\n  const addInput = await stdinResolver.resolveValue(options.add, \"--add\");\n  const text = parseCommentTextInput(addInput ?? \"\");\n  if (!text) {\n    throw new PmCliError(\"--add text cannot be empty\", EXIT_CODE.USAGE);\n  }\n\n  let result: Awaited<ReturnType<typeof mutateItem>>;\n  try {\n    result = await mutateItem({\n      pmRoot,\n      settings,\n      id,\n      op: \"comment_add\",\n      author,\n      message: options.message,\n      force: options.force,\n      bypassAssigneeConflict: Boolean(options.allowAuditComment),\n      mutate(document) {\n        const comments = document.front_matter.comments ?? [];\n        comments.push({\n          created_at: nowIso(),\n          author,\n          text,\n        });\n        document.front_matter.comments = comments;\n        return { changedFields: [\"comments\"] };\n      },\n    });\n  } catch (error: unknown) {\n    if (\n      error instanceof PmCliError &&\n      error.exitCode === EXIT_CODE.CONFLICT &&\n      error.message.includes(\"is assigned to\") &&\n      error.message.includes(\"Use --force to override\")\n    ) {\n      throw new PmCliError(error.message, error.exitCode, {\n        code: \"ownership_conflict\",\n        required:\n          \"For append-only comment audits on another owner's item, prefer --allow-audit-comment before considering --force.\",\n        examples: ['pm comments pm-a1b2 --add \"audit note\" --author \"reviewer\" --allow-audit-comment'],\n        nextSteps: [\n          \"Retry with --allow-audit-comment for append-only audits that do not mutate item metadata beyond comments.\",\n          \"Use --force only when an ownership override is explicitly approved.\",\n        ],\n      });\n    }\n    throw error;\n  }\n\n  const comments = limitComments(result.item.comments as Comment[], limit);\n  return {\n    id: result.item.id,\n    comments,\n    count: comments.length,\n  };\n}\n"]}
+{"version":3,"file":"comments.js","sourceRoot":"/","sources":["cli/commands/comments.ts"],"names":[],"mappings":"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","sourcesContent":["import { readFile } from \"node:fs/promises\";\nimport { pathExists } from \"../../core/fs/fs-utils.js\";\nimport { getActiveExtensionRegistrations } from \"../../core/extensions/index.js\";\nimport { resolveItemTypeRegistry } from \"../../core/item/type-registry.js\";\nimport { EXIT_CODE } from \"../../core/shared/constants.js\";\nimport type { GlobalOptions } from \"../../core/shared/command-types.js\";\nimport { PmCliError } from \"../../core/shared/errors.js\";\nimport { nowIso } from \"../../core/shared/time.js\";\nimport { createStdinTokenResolver, parseCsvKv } from \"../../core/item/parse.js\";\nimport { locateItem, mutateItem, readLocatedItem } from \"../../core/store/item-store.js\";\nimport { getSettingsPath, resolvePmRoot } from \"../../core/store/paths.js\";\nimport { readSettings } from \"../../core/store/settings.js\";\nimport { parseLimit } from \"../shared-parsers.js\";\nimport type { Comment } from \"../../types/index.js\";\n\nexport interface CommentsCommandOptions {\n  add?: string;\n  stdin?: boolean;\n  file?: string;\n  limit?: string;\n  author?: string;\n  message?: string;\n  force?: boolean;\n  allowAuditComment?: boolean;\n}\n\nexport interface CommentsResult {\n  id: string;\n  comments: Comment[];\n  count: number;\n}\n\nfunction resolveAuthor(candidate: string | undefined, fallback: string): string {\n  const resolved = candidate ?? process.env.PM_AUTHOR ?? fallback;\n  const trimmed = resolved.trim();\n  return trimmed || \"unknown\";\n}\n\nfunction limitComments(values: Comment[], limit: number | undefined): Comment[] {\n  if (limit === undefined) return values;\n  if (limit === 0) return [];\n  return values.slice(Math.max(0, values.length - limit));\n}\n\nfunction parseCommentTextInput(raw: string): string {\n  const trimmed = raw.trim();\n  if (!trimmed) {\n    return \"\";\n  }\n  const looksStructured = /^(?:[-*+]\\s*)?text\\s*[:=]/im.test(trimmed) || trimmed.startsWith(\"```\");\n  if (!looksStructured) {\n    return trimmed;\n  }\n  try {\n    const kv = parseCsvKv(trimmed, \"--add\");\n    const keys = Object.keys(kv).map((key) => key.trim().toLowerCase());\n    if (keys.some((key) => key !== \"text\")) {\n      return trimmed;\n    }\n    const text = kv.text?.trim();\n    return text || trimmed;\n  } catch {\n    return trimmed;\n  }\n}\n\ninterface ResolvedCommentInput {\n  mode: \"list\" | \"add\" | \"stdin\" | \"file\";\n  value?: string;\n}\n\nfunction isErrnoError(error: unknown): error is NodeJS.ErrnoException {\n  return typeof error === \"object\" && error !== null && \"code\" in error;\n}\n\nasync function resolveCommentInput(\n  options: CommentsCommandOptions,\n  stdinResolver: ReturnType<typeof createStdinTokenResolver>,\n): Promise<ResolvedCommentInput> {\n  const hasAdd = options.add !== undefined;\n  const hasStdin = options.stdin === true;\n  const hasFile = typeof options.file === \"string\";\n  const sourceCount = Number(hasAdd) + Number(hasStdin) + Number(hasFile);\n  if (sourceCount === 0) {\n    return { mode: \"list\" };\n  }\n  if (sourceCount > 1) {\n    throw new PmCliError(\"Specify comment text using only one input source: --add, --stdin, or --file\", EXIT_CODE.USAGE);\n  }\n  if (hasAdd) {\n    const addInput = await stdinResolver.resolveValue(options.add, \"--add\");\n    return {\n      mode: \"add\",\n      value: addInput ?? \"\",\n    };\n  }\n  if (hasStdin) {\n    const stdinInput = await stdinResolver.resolveValue(\"-\", \"--stdin\");\n    return {\n      mode: \"stdin\",\n      value: stdinInput ?? \"\",\n    };\n  }\n  const filePath = options.file?.trim() ?? \"\";\n  if (!filePath) {\n    throw new PmCliError(\"--file path cannot be empty\", EXIT_CODE.USAGE);\n  }\n  try {\n    const fileInput = await readFile(filePath, \"utf8\");\n    return {\n      mode: \"file\",\n      value: fileInput,\n    };\n  } catch (error: unknown) {\n    if (isErrnoError(error) && error.code === \"ENOENT\") {\n      throw new PmCliError(`--file path not found: ${filePath}`, EXIT_CODE.USAGE);\n    }\n    const detail = error instanceof Error ? error.message : String(error);\n    throw new PmCliError(`Failed to read --file path \"${filePath}\": ${detail}`, EXIT_CODE.USAGE);\n  }\n}\n\nexport async function runComments(id: string, options: CommentsCommandOptions, global: GlobalOptions): Promise<CommentsResult> {\n  const stdinResolver = createStdinTokenResolver();\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  if (!(await pathExists(getSettingsPath(pmRoot)))) {\n    throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);\n  }\n  const settings = await readSettings(pmRoot);\n  const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());\n  const limit = parseLimit(options.limit);\n  const commentInput = await resolveCommentInput(options, stdinResolver);\n\n  if (commentInput.mode === \"list\") {\n    const located = await locateItem(pmRoot, id, settings.id_prefix, settings.item_format, typeRegistry.type_to_folder);\n    if (!located) {\n      throw new PmCliError(`Item ${id} not found`, EXIT_CODE.NOT_FOUND);\n    }\n    const loaded = await readLocatedItem(located, { schema: settings.schema });\n    const comments = limitComments(loaded.document.metadata.comments ?? [], limit);\n    return {\n      id: located.id,\n      comments,\n      count: comments.length,\n    };\n  }\n\n  const author = resolveAuthor(options.author, settings.author_default);\n  const text = commentInput.mode === \"add\" ? parseCommentTextInput(commentInput.value ?? \"\") : (commentInput.value ?? \"\");\n  if (!text.trim()) {\n    const inputFlag = commentInput.mode === \"add\" ? \"--add\" : commentInput.mode === \"stdin\" ? \"--stdin\" : \"--file\";\n    throw new PmCliError(`${inputFlag} text cannot be empty`, EXIT_CODE.USAGE);\n  }\n\n  let result: Awaited<ReturnType<typeof mutateItem>>;\n  try {\n    result = await mutateItem({\n      pmRoot,\n      settings,\n      id,\n      op: \"comment_add\",\n      author,\n      message: options.message,\n      force: options.force,\n      bypassAssigneeConflict: Boolean(options.allowAuditComment),\n      mutate(document) {\n        const comments = document.metadata.comments ?? [];\n        comments.push({\n          created_at: nowIso(),\n          author,\n          text,\n        });\n        document.metadata.comments = comments;\n        return { changedFields: [\"comments\"] };\n      },\n    });\n  } catch (error: unknown) {\n    if (\n      error instanceof PmCliError &&\n      error.exitCode === EXIT_CODE.CONFLICT &&\n      error.message.includes(\"is assigned to\") &&\n      error.message.includes(\"Use --force to override\")\n    ) {\n      throw new PmCliError(error.message, error.exitCode, {\n        code: \"ownership_conflict\",\n        required:\n          \"For append-only comment audits on another owner's item, prefer --allow-audit-comment before considering --force.\",\n        examples: ['pm comments pm-a1b2 --add \"audit note\" --author \"reviewer\" --allow-audit-comment'],\n        nextSteps: [\n          \"Retry with --allow-audit-comment for append-only audits that do not mutate item metadata beyond comments.\",\n          \"Use --force only when an ownership override is explicitly approved.\",\n        ],\n      });\n    }\n    throw error;\n  }\n\n  const comments = limitComments(result.item.comments as Comment[], limit);\n  return {\n    id: result.item.id,\n    comments,\n    count: comments.length,\n  };\n}\n"]}

package/dist/cli/commands/completion.js

@@ -1,7 +1,8 @@
 import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
-import { ACTIVITY_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, CONTEXT_FLAG_CONTRACTS, CREATE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, NORMALIZE_FLAG_CONTRACTS, PM_CORE_COMMAND_NAMES, SEARCH_FLAG_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, toCompletionFlagString, } from "../../sdk/cli-contracts.js";
+import { ACTIVITY_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, CONTEXT_FLAG_CONTRACTS, CREATE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, NORMALIZE_FLAG_CONTRACTS, PM_CORE_COMMAND_NAMES, SEARCH_FLAG_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, toCompletionFlagString, } from "../../sdk/cli-contracts.js";
 import { BUILTIN_ITEM_TYPE_VALUES } from "../../types/index.js";
+import { listGuideTopicIds } from "../guide-topics.js";
 const VALID_SHELLS = ["bash", "zsh", "fish"];
 const DEFAULT_ITEM_TYPES = [...BUILTIN_ITEM_TYPE_VALUES];
 const DEFAULT_STATUS_VALUES = ["draft", "open", "in_progress", "blocked", "closed", "canceled"];
@@ -16,12 +17,14 @@ const ACTIVITY_FLAGS = toCompletionFlagString(ACTIVITY_FLAG_CONTRACTS);
 const CALENDAR_FLAGS = toCompletionFlagString(CALENDAR_FLAG_CONTRACTS);
 const CONTEXT_FLAGS = toCompletionFlagString(CONTEXT_FLAG_CONTRACTS);
 const DEPS_FLAGS = toCompletionFlagString(DEPS_FLAG_CONTRACTS);
+const GUIDE_FLAGS = toCompletionFlagString(GUIDE_FLAG_CONTRACTS);
 const SEARCH_FLAGS = toCompletionFlagString(SEARCH_FLAG_CONTRACTS);
 const HEALTH_FLAGS = toCompletionFlagString(HEALTH_FLAG_CONTRACTS);
 const INIT_FLAGS = toCompletionFlagString(INIT_FLAG_CONTRACTS);
 const CONTRACTS_FLAGS = toCompletionFlagString(CONTRACTS_FLAG_CONTRACTS);
 const COMPLETION_FLAGS = toCompletionFlagString(COMPLETION_FLAG_CONTRACTS);
 const COMPLETION_SHELL_CHOICES = `${COMPLETION_FLAGS} bash zsh fish`;
+const GUIDE_TOPIC_CHOICES = joinCompletionValues(listGuideTopicIds());
 const MUTATION_FLAGS = "--author --message --force --json --quiet --path --no-extensions --no-pager --profile --help";
 const CLOSE_MUTATION_FLAGS = "--author --message --validate-close --force --json --quiet --path --no-extensions --no-pager --profile --help";
 const RELEASE_MUTATION_FLAGS = "--allow-audit-release --author --message --force --json --quiet --path --no-extensions --no-pager --profile --help";
@@ -135,6 +138,9 @@ export function generateBashScript(itemTypes = DEFAULT_ITEM_TYPES, tags = [], ea
         "    context|ctx)",
         `      COMPREPLY=(${compgen(contextFlags)})`,
         "      ;;",
+        "    guide)",
+        `      COMPREPLY=(${compgen(`${GUIDE_FLAGS} ${GUIDE_TOPIC_CHOICES}`)})`,
+        "      ;;",
         "    search)",
         `      COMPREPLY=(${compgen(searchFlags)})`,
         "      ;;",
@@ -148,10 +154,10 @@ export function generateBashScript(itemTypes = DEFAULT_ITEM_TYPES, tags = [], ea
         `      COMPREPLY=(${compgen("--criterion --clear-criteria --format --policy --json --quiet --path --no-extensions --no-pager --profile --help")})`,
         "      ;;",
         "    extension)",
-        `      COMPREPLY=(${compgen("init scaffold install uninstall explore manage doctor adopt adopt-all activate deactivate --init --scaffold --install --uninstall --explore --manage --doctor --adopt --adopt-all --activate --deactivate --project --local --global --gh --github --ref --detail --trace --runtime-probe --fix-managed-state --strict-exit --fail-on-warn --json --quiet --path --no-extensions --no-pager --profile --help")})`,
+        `      COMPREPLY=(${compgen("init scaffold install uninstall explore manage reload doctor adopt adopt-all activate deactivate --init --scaffold --install --uninstall --explore --manage --reload --watch --doctor --adopt --adopt-all --activate --deactivate --project --local --global --gh --github --ref --detail --trace --runtime-probe --fix-managed-state --strict-exit --fail-on-warn --json --quiet --path --no-extensions --no-pager --profile --help")})`,
         "      ;;",
         "    comments)",
-        `      COMPREPLY=(${compgen("--add --limit --author --message --allow-audit-comment --force --json --quiet --path --no-extensions --no-pager --profile --help")})`,
+        `      COMPREPLY=(${compgen("--add --stdin --file --limit --author --message --allow-audit-comment --force --json --quiet --path --no-extensions --no-pager --profile --help")})`,
         "      ;;",
         "    comments-audit)",
         `      COMPREPLY=(${compgen("--status --type --tag --priority --parent --sprint --release --assignee --assignee-filter --limit-items --limit --full-history --latest --json --quiet --path --no-extensions --no-pager --profile --help")})`,
@@ -229,6 +235,7 @@ export function generateBashScript(itemTypes = DEFAULT_ITEM_TYPES, tags = [], ea
 export function generateZshScript(itemTypes = DEFAULT_ITEM_TYPES, tags = [], eagerTagExpansion = false) {
     const cmds = ALL_COMMANDS.map((c) => `'${c}'`).join(" ");
     const typeChoices = itemTypes.join(" ");
+    const guideTopicChoices = GUIDE_TOPIC_CHOICES;
     const tagChoices = joinCompletionValues(tags);
     const useEagerTagExpansion = eagerTagExpansion || tags.length > 0;
     const zshTagChoices = useEagerTagExpansion ? tagChoices : '${(f)"$(_pm_tag_choices)"}';
@@ -270,6 +277,7 @@ _pm_commands() {
     'list-canceled:List canceled items with optional filters'
     'aggregate:Aggregate grouped item counts for governance queries'
     'dedupe-audit:Audit potential duplicate items and emit merge suggestions'
+    'guide:Browse local progressive-disclosure guides'
     'calendar:Show calendar views for deadlines and reminders'
     'cal:Alias for calendar'
     'context:Show a token-efficient project context snapshot'
@@ -615,6 +623,15 @@ _pm() {
             '--json[Output JSON]' \\
             '--quiet[Suppress stdout]'
           ;;
+        guide)
+          _arguments \\
+            '1:topic:(${guideTopicChoices})' \\
+            '--list[Show guide topic index]' \\
+            '--format[Output override]:(markdown toon json)' \\
+            '--depth[Guide detail depth]:(brief standard deep)' \\
+            '--json[Output JSON]' \\
+            '--quiet[Suppress stdout]'
+          ;;
         search)
           _arguments \\
             '--mode[Search mode]:(keyword semantic hybrid)' \\
@@ -675,6 +692,8 @@ _pm() {
         comments)
           _arguments \\
             '--add[Add one entry (plain text, text=<value>, markdown pairs, or - for stdin)]:text' \\
+            '--stdin[Read comment text from stdin (supports multiline markdown)]' \\
+            '--file[Read comment text from file (supports multiline markdown)]:path' \\
             '--limit[Return only latest n entries]:number' \\
             '--author[Entry author (falls back to PM_AUTHOR/settings)]:author' \\
             '--message[History message]:message' \\
@@ -791,7 +810,7 @@ _pm() {
           _arguments \\
             '--criterion[Criteria value for definition-of-done metadata-required-fields or lifecycle pattern keys (repeatable for set)]:criterion' \\
             '--clear-criteria[Clear config criteria-list key values]' \\
-            '--format[Item format for item-format key]:format:(toon json_markdown)' \\
+            '--format[Item format for item-format key]:format:(toon)' \\
             '--policy[Policy value for supported policy keys]:policy' \\
             '--json[Output JSON]' \\
             '--quiet[Suppress stdout]'
@@ -890,13 +909,15 @@ _pm() {
           ;;
         extension)
           _arguments \\
-            '1:extension_action:(init scaffold install uninstall explore manage doctor adopt adopt-all activate deactivate)' \\
+            '1:extension_action:(init scaffold install uninstall explore manage reload doctor adopt adopt-all activate deactivate)' \\
             '--init[Generate a starter extension scaffold at target path]' \\
             '--scaffold[Alias for --init]' \\
             '--install[Install extension from local path or GitHub source]' \\
             '--uninstall[Uninstall extension by name]' \\
             '--explore[List discovered extensions for selected scope]' \\
             '--manage[List managed extensions with update metadata]' \\
+            '--reload[Reload extensions with cache-busted module imports]' \\
+            '--watch[Enable watch mode with --reload]' \\
             '--doctor[Run consolidated extension diagnostics (summary/deep)]' \\
             '--adopt[Adopt an unmanaged extension into managed metadata]' \\
             '--adopt-all[Adopt all unmanaged extensions into managed metadata]' \\
@@ -939,6 +960,7 @@ export function generateFishScript(itemTypes = DEFAULT_ITEM_TYPES, tags = [], ea
     const listCmds = ALL_COMMANDS.filter((command) => command === "list" || command.startsWith("list-")).join(" ");
     const noSubcommandList = ALL_COMMANDS.join(" ");
     const typeChoices = itemTypes.join(" ");
+    const guideTopicChoices = GUIDE_TOPIC_CHOICES;
     const tagChoices = joinCompletionValues(tags);
     const useEagerTagExpansion = eagerTagExpansion || tags.length > 0;
     const fishTagChoices = useEagerTagExpansion ? `'${tagChoices}'` : "'(__pm_tag_choices)'";
@@ -1004,6 +1026,7 @@ complete -c pm -n __pm_no_subcommand -a list-closed   -d 'List closed items with
 complete -c pm -n __pm_no_subcommand -a list-canceled -d 'List canceled items with optional filters'
 complete -c pm -n __pm_no_subcommand -a aggregate     -d 'Aggregate grouped item counts for governance queries'
 complete -c pm -n __pm_no_subcommand -a dedupe-audit  -d 'Audit potential duplicate items and emit merge suggestions'
+complete -c pm -n __pm_no_subcommand -a guide         -d 'Browse local progressive-disclosure guides'
 complete -c pm -n __pm_no_subcommand -a calendar      -d 'Show deadline/reminder calendar views'
 complete -c pm -n __pm_no_subcommand -a cal           -d 'Alias for calendar'
 complete -c pm -n __pm_no_subcommand -a context       -d 'Show a token-efficient project context snapshot'
@@ -1308,6 +1331,12 @@ complete -c pm -n '__fish_seen_subcommand_from context ctx' -l release   -d 'Fil
 complete -c pm -n '__fish_seen_subcommand_from context ctx' -l limit     -d 'Limit focus and agenda rows per section' -r
 complete -c pm -n '__fish_seen_subcommand_from context ctx' -l format    -d 'Output override' -r -a 'markdown toon json'
 
+# guide flags
+complete -c pm -n '__fish_seen_subcommand_from guide' -l list      -d 'Show guide topic index'
+complete -c pm -n '__fish_seen_subcommand_from guide' -l format    -d 'Output override' -r -a 'markdown toon json'
+complete -c pm -n '__fish_seen_subcommand_from guide' -l depth     -d 'Guide detail depth' -r -a 'brief standard deep'
+complete -c pm -n '__fish_seen_subcommand_from guide' -a '${guideTopicChoices}' -d 'Guide topic'
+
 # reindex flags
 complete -c pm -n '__fish_seen_subcommand_from reindex' -l mode -d 'Reindex mode' -r -a 'keyword semantic hybrid'
 complete -c pm -n '__fish_seen_subcommand_from reindex' -l progress -d 'Emit progress updates to stderr'
@@ -1337,6 +1366,8 @@ complete -c pm -n '__fish_seen_subcommand_from deps' -l summary -d 'Return count
 
 # comments / notes / learnings flags
 complete -c pm -n '__fish_seen_subcommand_from comments notes learnings' -l add -d 'Add one entry (text=<value> or plain text)' -r
+complete -c pm -n '__fish_seen_subcommand_from comments' -l stdin -d 'Read comment text from stdin (supports multiline markdown)'
+complete -c pm -n '__fish_seen_subcommand_from comments' -l file -d 'Read comment text from file (supports multiline markdown)' -r
 complete -c pm -n '__fish_seen_subcommand_from comments notes learnings' -l limit -d 'Return only latest n entries' -r
 complete -c pm -n '__fish_seen_subcommand_from comments notes learnings' -l author -d 'Entry author' -r
 complete -c pm -n '__fish_seen_subcommand_from comments notes learnings' -l message -d 'History message' -r
@@ -1430,7 +1461,7 @@ complete -c pm -n '__fish_seen_subcommand_from validate' -l check-command-refere
 complete -c pm -n '__fish_seen_subcommand_from init' -l preset -d 'Governance preset for new setups' -r -a 'minimal default strict'
 complete -c pm -n '__fish_seen_subcommand_from config' -l criterion -d 'Criteria value for definition-of-done metadata-required-fields or lifecycle pattern keys (repeatable for set)' -r
 complete -c pm -n '__fish_seen_subcommand_from config' -l clear-criteria -d 'Clear config criteria-list key values'
-complete -c pm -n '__fish_seen_subcommand_from config' -l format -d 'Item format for item-format key' -r -a 'toon json_markdown'
+complete -c pm -n '__fish_seen_subcommand_from config' -l format -d 'Item format for item-format key' -r -a 'toon'
 complete -c pm -n '__fish_seen_subcommand_from config' -l policy -d 'Policy value for supported policy keys' -r
 complete -c pm -n '__fish_seen_subcommand_from health' -l strict-directories -d 'Treat optional item-type directories as required failures'
 complete -c pm -n '__fish_seen_subcommand_from health' -l check-only -d 'Run read-only health diagnostics without refreshing vectors'
@@ -1461,13 +1492,15 @@ complete -c pm -n '__fish_seen_subcommand_from completion' -a 'bash zsh fish' -d
 complete -c pm -n '__fish_seen_subcommand_from templates' -a 'save list show' -d 'Templates command'
 
 # extension lifecycle flags
-complete -c pm -n '__fish_seen_subcommand_from extension' -a 'init scaffold install uninstall explore manage doctor adopt adopt-all activate deactivate' -d 'Extension action subcommand'
+complete -c pm -n '__fish_seen_subcommand_from extension' -a 'init scaffold install uninstall explore manage reload doctor adopt adopt-all activate deactivate' -d 'Extension action subcommand'
 complete -c pm -n '__fish_seen_subcommand_from extension' -l init -d 'Generate starter extension scaffold'
 complete -c pm -n '__fish_seen_subcommand_from extension' -l scaffold -d 'Alias for --init'
 complete -c pm -n '__fish_seen_subcommand_from extension' -l install -d 'Install extension from local path or GitHub source'
 complete -c pm -n '__fish_seen_subcommand_from extension' -l uninstall -d 'Uninstall extension by name'
 complete -c pm -n '__fish_seen_subcommand_from extension' -l explore -d 'List discovered extensions for selected scope'
 complete -c pm -n '__fish_seen_subcommand_from extension' -l manage -d 'List managed extensions with update metadata'
+complete -c pm -n '__fish_seen_subcommand_from extension' -l reload -d 'Reload extensions with cache-busted module imports'
+complete -c pm -n '__fish_seen_subcommand_from extension' -l watch -d 'Enable watch mode with --reload'
 complete -c pm -n '__fish_seen_subcommand_from extension' -l doctor -d 'Run consolidated extension diagnostics'
 complete -c pm -n '__fish_seen_subcommand_from extension' -l adopt -d 'Adopt an unmanaged extension into managed metadata'
 complete -c pm -n '__fish_seen_subcommand_from extension' -l adopt-all -d 'Adopt all unmanaged extensions into managed metadata'