@akagilnc/pi-workflow-roles 0.1.2114 → 0.1.2118

package/README.md

@@ -82,33 +82,9 @@ ak-role merger --project /path/to/worktree "Reconcile the active merge."
 
 Roles are named after Tang/Song offices; the full roster and naming rule live in [README.zh-CN.md](https://github.com/Akagilnc/ak-pi-workflow-roles/blob/main/README.zh-CN.md).
 
-## Developer seam: raw session invocation (advanced)
+## Codex fast tier
 
-Most callers never need this. The source tree retains an explicitly loadable raw-Pi seam for package development and low-level diagnosis; it is not a supported invocation recipe—external callers use `ak-role`.
-
-A raw run loads the role runtime explicitly and selects the role through the internal flag. This is the real argv shape, taken from the CLI’s own builders and recorded runs under the ledger book:
-
-```bash
-run=~/.ak-roles/books/<book>/issues/<issue>/runs/<invocation>@<source-tree>
-pi --no-extensions \
-  -e <packageRoot>/extensions/role-runtime.ts \
-  --no-skills --no-prompt-templates --no-themes --no-context-files \
-  --session "$run/session/session.jsonl" \
-  --session-dir "$run/session" \
-  --ak-role judge --mode json \
-  "Adjudicate the attached materials." \
-  </dev/null >/dev/null 2>"$run/stderr.log"
-```
-
-`--session` names the exact session file principal (never directory-latest); `--session-dir` is its directory. Judge takes the instruction as the prompt; other roles pass durable payload files through their own internal flags (`--ak-coder-task`, `--ak-fix-packet`, and siblings), assembled by each role’s builder in `src/public-cli/*-run.ts` through the load boundary in `src/public-cli/explicit-internal.ts`. Derive flags from that source—and from recorded runs under the ledger book—never from prose.
-
-Discipline:
-
-- seal stdin with `</dev/null`—Pi reads a non-TTY stdin to EOF before starting, so an open background pipe parks the run forever;
-- send stdout to `/dev/null`—the session file is the authoritative record and stdout is an unbounded copy surface; attach dashboards to `stderr.log` and the session file;
-- keep `stderr.log` and `invocation.json` in the same `runs/` directory, as in the example above.
-
-Codex fast tier: enable fast tier with `echo "fast_mode = on" > ~/.pi-codex-fast`; disable it with `echo "fast_mode = off" > ~/.pi-codex-fast` (or delete the file). The change takes effect on the next request without a restart. Fast tier costs more than the default tier.
+Enable fast tier with `echo "fast_mode = on" > ~/.pi-codex-fast`; disable it with `echo "fast_mode = off" > ~/.pi-codex-fast` (or delete the file). The change takes effect on the next request without a restart. Fast tier costs more than the default tier.
 
 <!-- BEGIN GENERATED: public-cli-options -->
 ## Public CLI options (generated)

package/README.zh-CN.md

@@ -111,33 +111,9 @@ ak-role merger --project /path/to/worktree "Reconcile the active merge."
 
 `拾遗补阙` 成对留档，待将来出现第二个进言席再启用。
 
-## 开发者接缝：手拼 session（高级）
+## Codex fast 档
 
-多数调用者不需要本节。源码树保留一条可显式装载的 raw-Pi 接缝，供包开发与底层诊断；它不是受支持的调用配方——外部调用者用 `ak-role`。
-
-原始运行显式装载角色运行时，经内部旗标选角色。以下 argv 全形取自 CLI 自身 builder 与卷宗实记：
-
-```bash
-run=~/.ak-roles/books/<book>/issues/<issue>/runs/<invocation>@<源树>
-pi --no-extensions \
-  -e <packageRoot>/extensions/role-runtime.ts \
-  --no-skills --no-prompt-templates --no-themes --no-context-files \
-  --session "$run/session/session.jsonl" \
-  --session-dir "$run/session" \
-  --ak-role judge --mode json \
-  "Adjudicate the attached materials." \
-  </dev/null >/dev/null 2>"$run/stderr.log"
-```
-
-`--session` 指精确 session 文件正本（非 directory-latest）；`--session-dir` 为其目录。大理寺的指令走 prompt；其余角色经各自内部旗标传持久 payload 文件（`--ak-coder-task`、`--ak-fix-packet` 等），由各角色 builder（`src/public-cli/*-run.ts`）经装载边界 `src/public-cli/explicit-internal.ts` 装配。旗标从源码与卷宗实记推导，勿从散文推导。
-
-纪律：
-
-- stdin 须以 `</dev/null` 封死——Pi 会将非 TTY stdin 读到 EOF 才开工，未封死的后台管道＝永久停车；
-- stdout 丢 `/dev/null`——session 文件才是正本，stdout 是无上限副本面；仪表挂 `stderr.log` 与 session 文件；
-- `stderr.log` 与 `invocation.json` 落在同次 `runs/` 目录，如上例。
-
-Codex fast 档：开启：`echo "fast_mode = on" > ~/.pi-codex-fast`；关闭：`echo "fast_mode = off" > ~/.pi-codex-fast`（或删文件）。修改后无需重启，下一个请求即生效。Fast 档价格高于默认档。
+开启：`echo "fast_mode = on" > ~/.pi-codex-fast`；关闭：`echo "fast_mode = off" > ~/.pi-codex-fast`（或删文件）。修改后无需重启，下一个请求即生效。Fast 档价格高于默认档。
 
 <!-- BEGIN GENERATED: public-cli-options -->
 ## 公开 CLI 选项（生成）

package/dist/public-cli/main.js

@@ -15806,44 +15806,46 @@ function projectOwnerOptions(owner) {
     description: def.description
   }));
 }
-function renderOwnerOptionHelpLines(owner, locale2 = "en") {
+function projectCommandHelp(topic) {
+  if (!(topic in PUBLIC_COMMAND_HELP)) return void 0;
+  const facts = PUBLIC_COMMAND_HELP[topic];
+  return {
+    command: facts.command,
+    summary: facts.summary,
+    usage: [...facts.usage],
+    examples: [...facts.examples]
+  };
+}
+function renderHumanOwnerOptionLines(owner, locale2 = "en") {
   const lines = [];
   for (const opt of projectOwnerOptions(owner)) {
-    const aliasText = opt.aliases.length === 0 ? "-" : opt.aliases.join(",");
-    const metavar = opt.valueMetavar ?? "-";
-    const required = opt.required ? "required" : "optional";
-    const repeatable = opt.repeatable ? "repeatable" : "single";
-    const form = opt.form;
-    const phases = opt.phases === void 0 ? "-" : opt.phases.join("|");
-    const modes = opt.modes === void 0 ? "-" : opt.modes.join("|");
-    const requiredInModes = opt.requiredInModes === void 0 ? "-" : opt.requiredInModes.join("|");
-    const exclusiveWith = opt.exclusiveWith === void 0 ? "-" : opt.exclusiveWith.join("|");
-    const maxCount = opt.maxCountByMode === void 0 ? "-" : Object.entries(opt.maxCountByMode).map(([mode, n]) => `${mode}:${n}`).join(",");
-    const defaultValue = opt.defaultValue ?? "-";
+    let spelling = opt.canonical;
+    if (opt.valueMetavar !== null) {
+      spelling = `${spelling} <${opt.valueMetavar}>`;
+    }
+    if (opt.aliases.length > 0) {
+      const aliasHint = opt.aliases.join(", ");
+      if (opt.form === "positional") {
+        spelling = opt.aliases.length > 0 ? opt.aliases.join("|") : spelling;
+      } else {
+        spelling = `${spelling} (${aliasHint})`;
+      }
+    }
+    const tags = [];
+    if (opt.required) tags.push("required");
+    if (opt.requiredInModes !== void 0) {
+      tags.push(`required:${opt.requiredInModes.join("|")}`);
+    }
+    if (opt.repeatable) tags.push("repeatable");
+    if (opt.defaultValue !== void 0) tags.push(`default=${opt.defaultValue}`);
+    if (opt.form === "positional") tags.push("positional");
+    const tagText = tags.length === 0 ? "" : ` [${tags.join(", ")}]`;
     const desc = locale2 === "zh" ? opt.description.zh : opt.description.en;
-    lines.push(
-      [
-        "option",
-        opt.id,
-        opt.canonical,
-        `aliases=${aliasText}`,
-        `metavar=${metavar}`,
-        required,
-        repeatable,
-        `form=${form}`,
-        `phases=${phases}`,
-        `modes=${modes}`,
-        `requiredInModes=${requiredInModes}`,
-        `exclusiveWith=${exclusiveWith}`,
-        `maxCountByMode=${maxCount}`,
-        `default=${defaultValue}`,
-        desc
-      ].join("	")
-    );
+    lines.push(`  ${spelling}${tagText}  ${desc}`);
   }
   return lines;
 }
-var TAISHI_REQUIRE_ANY_OF, TAISHI_DEFAULT_MODE, REJECTED_PUBLIC_SPELLINGS, GLOBAL_OPTIONS, SHARED_PROJECT_SEMANTICS, SHARED_ATTACH_SEMANTICS, JUDGE_OPTIONS, CODER_OPTIONS, FIXER_OPTIONS, REVIEWER_OPTIONS, COLLECTOR_OPTIONS, DOCTOR_OPTIONS, MERGER_OPTIONS, TAISHI_OPTIONS, PUBLIC_OPTION_TABLE;
+var TAISHI_REQUIRE_ANY_OF, TAISHI_DEFAULT_MODE, REJECTED_PUBLIC_SPELLINGS, GLOBAL_OPTIONS, SHARED_PROJECT_SEMANTICS, SHARED_ATTACH_SEMANTICS, JUDGE_OPTIONS, CODER_OPTIONS, FIXER_OPTIONS, REVIEWER_OPTIONS, COLLECTOR_OPTIONS, DOCTOR_OPTIONS, MERGER_OPTIONS, TAISHI_OPTIONS, PUBLIC_OPTION_TABLE, PUBLIC_NAVIGATOR_HELP_NOTE, TOP_LEVEL_HELP, ROLE_COMMAND_HELP, SUPPORT_COMMAND_HELP, PUBLIC_COMMAND_HELP;
 var init_option_definitions = __esm({
   "src/public-cli/option-definitions.ts"() {
     "use strict";
@@ -16317,6 +16319,133 @@ var init_option_definitions = __esm({
       merger: MERGER_OPTIONS,
       taishi: TAISHI_OPTIONS
     };
+    PUBLIC_NAVIGATOR_HELP_NOTE = "Navigator attends automatically on every run; configure with `ak-role config set navigator <provider/model[:thinking]>` (not a caller command).";
+    TOP_LEVEL_HELP = {
+      command: "top",
+      summary: "public role CLI",
+      usage: [
+        "ak-role <command> [options]",
+        "ak-role help <command>"
+      ],
+      examples: [
+        'ak-role judge --attach ./plan.md "Review this plan."',
+        'ak-role coder plan "Propose the first implementation plan."'
+      ]
+    };
+    ROLE_COMMAND_HELP = {
+      judge: {
+        command: "judge",
+        summary: "Adjudicate the supplied materials; infers its own burden.",
+        usage: ["ak-role judge [options] [instruction]"],
+        examples: [
+          'ak-role judge --attach ./plan.md "Review this plan."',
+          'ak-role judge --attach ./findings.md --attach ./adr.md "Adjudicate every finding."'
+        ]
+      },
+      coder: {
+        command: "coder",
+        summary: "First implementation; phase defaults to apply.",
+        usage: ["ak-role coder [plan|apply] [options] <instruction>"],
+        examples: [
+          'ak-role coder plan "Propose the first implementation plan."',
+          'ak-role coder apply --attach ./plan.md "Implement the approved slice."'
+        ]
+      },
+      fixer: {
+        command: "fixer",
+        summary: "Repair the assigned findings; phase defaults to apply.",
+        usage: ["ak-role fixer [plan|apply] [options] <instruction>"],
+        examples: [
+          'ak-role fixer --attach ./findings.md --prerequisites ./prereqs.json "Repair the findings."',
+          'ak-role fixer plan --attach ./findings.md "Propose the repair plan."'
+        ]
+      },
+      reviewer: {
+        command: "reviewer",
+        summary: "Fixed-target two-axis review (Standards + Spec).",
+        usage: ["ak-role reviewer --base <revision> [options] <instruction>"],
+        examples: [
+          'ak-role reviewer --base main "Review the branch against the governing issue and repository authority."'
+        ]
+      },
+      collector: {
+        command: "collector",
+        summary: "Collect GitHub PR review evidence (one-shot).",
+        usage: ["ak-role collector --pr <number> [options] [instruction]"],
+        examples: [
+          "ak-role collector --pr 42 --repo owner/repository",
+          "ak-role collector --pr 42 --request-manifest ./requests.json"
+        ]
+      },
+      doctor: {
+        command: "doctor",
+        summary: "Diagnose one retained case (one-shot).",
+        usage: ["ak-role doctor --issue <number> [options] [instruction]"],
+        examples: [
+          'ak-role doctor --issue 115 "Diagnose this retained case."'
+        ]
+      },
+      merger: {
+        command: "merger",
+        summary: "Resolve one ordinary merge already in conflict.",
+        usage: ["ak-role merger [options] <instruction>"],
+        examples: [
+          'ak-role merger --project /path/to/worktree "Reconcile the active merge."'
+        ]
+      },
+      taishi: {
+        command: "taishi",
+        summary: "Deterministic analysis seat (issue / sweep / cohort / model-groups).",
+        usage: [
+          "ak-role taishi (--ticket <N> | --project-root <P>) [options]",
+          "ak-role taishi [sweep] --attach <path>",
+          "ak-role taishi --cohort --group-a-label <L> --group-a-issues <N[,N...]> --group-b-label <L> --group-b-issues <N[,N...]>",
+          "ak-role taishi --model-groups --project-root <P> [--project-root <P> ...]"
+        ],
+        examples: [
+          "ak-role taishi --ticket 125",
+          "ak-role taishi sweep --attach ./sweep.json"
+        ]
+      }
+    };
+    SUPPORT_COMMAND_HELP = {
+      roles: {
+        command: "roles",
+        summary: "List effective seats and models.",
+        usage: ["ak-role roles"],
+        examples: ["ak-role roles"]
+      },
+      config: {
+        command: "config",
+        summary: "Persistent seat model and labor-engine defaults.",
+        usage: [
+          "ak-role config set <seat> <provider/model[:thinking]> [<seat> <spec> ...]",
+          "ak-role config set-engine <seat> <name>",
+          "ak-role config unset-engine <seat>"
+        ],
+        examples: [
+          "ak-role config set judge openai-codex/gpt-5.6-sol:high",
+          "ak-role config set-engine judge opus"
+        ]
+      },
+      help: {
+        command: "help",
+        summary: "Show public CLI help.",
+        usage: ["ak-role help [command]", "ak-role --help"],
+        examples: ["ak-role help coder", "ak-role help judge"]
+      },
+      resume: {
+        command: "resume",
+        summary: "Reopen an exact role run after a typed HTTP 429.",
+        usage: ["ak-role resume <runId>"],
+        examples: ["ak-role resume 01abc\u2026"]
+      }
+    };
+    PUBLIC_COMMAND_HELP = {
+      top: TOP_LEVEL_HELP,
+      ...ROLE_COMMAND_HELP,
+      ...SUPPORT_COMMAND_HELP
+    };
   }
 });
 
@@ -27130,13 +27259,29 @@ function helpDocumentForCommand(command) {
   }
   return void 0;
 }
+function appendUsageAndExamples(lines, topic) {
+  const facts = projectCommandHelp(topic);
+  if (facts === void 0) return;
+  lines.push("", "USAGE");
+  for (const line2 of facts.usage) {
+    lines.push(`  ${line2}`);
+  }
+  if (facts.examples.length > 0) {
+    lines.push("", "EXAMPLES");
+    for (const example of facts.examples) {
+      lines.push(`  ${example}`);
+    }
+  }
+}
 function renderHelp() {
   const doc = helpDocument();
+  const top = projectCommandHelp("top");
   const lines = [
-    "ak-role \u2014 public role CLI",
-    "",
-    "Support commands:"
+    `ak-role \u2014 ${top?.summary ?? "public role CLI"}`
   ];
+  appendUsageAndExamples(lines, "top");
+  lines.push("", PUBLIC_NAVIGATOR_HELP_NOTE);
+  lines.push("", "Support commands:");
   for (const cap of doc.capabilities) {
     if (cap.kind === "support") {
       lines.push(`  ${cap.name}`);
@@ -27155,8 +27300,8 @@ function renderHelp() {
       lines.push(`  ${cap.name}`);
     }
   }
-  lines.push("", "Global options:");
-  lines.push(...renderOwnerOptionHelpLines("global"));
+  lines.push("", "OPTIONS");
+  lines.push(...renderHumanOwnerOptionLines("global"));
   lines.push(
     "",
     "Role options: ak-role help <command>",
@@ -27171,22 +27316,22 @@ function renderCommandHelp(command) {
   const caps = listHelpCapabilities();
   const match = caps.find((cap) => cap.name === command);
   if (match === void 0) return void 0;
+  const facts = projectCommandHelp(command);
   const lines = [];
-  if (match.kind === "support") {
-    lines.push(`command	${match.name}	kind	support`);
+  if (facts !== void 0) {
+    lines.push(`ak-role ${facts.command} \u2014 ${facts.summary}`);
+  } else if (match.kind === "support") {
+    lines.push(`ak-role ${match.name}`);
   } else if (match.kind === "deterministic") {
-    lines.push(`command	${match.name}	kind	deterministic`);
+    lines.push(`ak-role ${match.name}`);
   } else {
-    lines.push(
-      `command	${match.name}	kind	role	phases	${match.phases.map((p) => p === null ? "none" : p).join(",")}	default	${match.defaultPhase ?? "none"}`
-    );
+    lines.push(`ak-role ${match.name}`);
   }
-  if (command in PUBLIC_ROLE_ARGV) {
-    lines.push(
-      ...renderOwnerOptionHelpLines(
-        command
-      )
-    );
+  appendUsageAndExamples(lines, command);
+  if (command in PUBLIC_ROLE_ARGV || command === "global") {
+    const owner = command === "global" ? "global" : command;
+    lines.push("", "OPTIONS");
+    lines.push(...renderHumanOwnerOptionLines(owner));
   }
   return `${lines.join("\n")}
 `;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akagilnc/pi-workflow-roles",
-  "version": "0.1.2114",
+  "version": "0.1.2118",
   "description": "Soul-bound workflow roles for Pi",
   "type": "module",
   "license": "Apache-2.0",

package/src/public-cli/cli.ts

@@ -43,8 +43,10 @@ import {
 import {
   createTypedOptionConsumer,
   optionsForOwner,
+  projectCommandHelp,
   projectOwnerOptions,
-  renderOwnerOptionHelpLines,
+  PUBLIC_NAVIGATOR_HELP_NOTE,
+  renderHumanOwnerOptionLines,
   type PublicOptionDefinition,
   type TypedOptionConsumer,
 } from "./option-definitions.ts";
@@ -412,13 +414,34 @@ export function helpDocumentForCommand(command: string) {
   return undefined;
 }
 
+/** Append USAGE + EXAMPLES blocks from the sole public help-copy owner. */
+function appendUsageAndExamples(
+  lines: string[],
+  topic: string,
+): void {
+  const facts = projectCommandHelp(topic);
+  if (facts === undefined) return;
+  lines.push("", "USAGE");
+  for (const line of facts.usage) {
+    lines.push(`  ${line}`);
+  }
+  if (facts.examples.length > 0) {
+    lines.push("", "EXAMPLES");
+    for (const example of facts.examples) {
+      lines.push(`  ${example}`);
+    }
+  }
+}
+
 function renderHelp(): string {
   const doc = helpDocument();
+  const top = projectCommandHelp("top");
   const lines: string[] = [
-    "ak-role — public role CLI",
-    "",
-    "Support commands:",
+    `ak-role — ${top?.summary ?? "public role CLI"}`,
   ];
+  appendUsageAndExamples(lines, "top");
+  lines.push("", PUBLIC_NAVIGATOR_HELP_NOTE);
+  lines.push("", "Support commands:");
   for (const cap of doc.capabilities) {
     if (cap.kind === "support") {
       lines.push(`  ${cap.name}`);
@@ -441,8 +464,8 @@ function renderHelp(): string {
       lines.push(`  ${cap.name}`);
     }
   }
-  lines.push("", "Global options:");
-  lines.push(...renderOwnerOptionHelpLines("global"));
+  lines.push("", "OPTIONS");
+  lines.push(...renderHumanOwnerOptionLines("global"));
   lines.push(
     "",
     "Role options: ak-role help <command>",
@@ -457,24 +480,25 @@ function renderCommandHelp(command: string): string | undefined {
   const caps = listHelpCapabilities();
   const match = caps.find((cap) => cap.name === command);
   if (match === undefined) return undefined;
+  const facts = projectCommandHelp(command);
   const lines: string[] = [];
-  if (match.kind === "support") {
-    lines.push(`command\t${match.name}\tkind\tsupport`);
+  if (facts !== undefined) {
+    lines.push(`ak-role ${facts.command} — ${facts.summary}`);
+  } else if (match.kind === "support") {
+    lines.push(`ak-role ${match.name}`);
   } else if (match.kind === "deterministic") {
-    lines.push(`command\t${match.name}\tkind\tdeterministic`);
+    lines.push(`ak-role ${match.name}`);
   } else {
-    lines.push(
-      `command\t${match.name}\tkind\trole\tphases\t${match.phases
-        .map((p) => (p === null ? "none" : p))
-        .join(",")}\tdefault\t${match.defaultPhase ?? "none"}`,
-    );
+    lines.push(`ak-role ${match.name}`);
   }
-  if (command in PUBLIC_ROLE_ARGV) {
-    lines.push(
-      ...renderOwnerOptionHelpLines(
-        command as keyof typeof PUBLIC_ROLE_ARGV,
-      ),
-    );
+  appendUsageAndExamples(lines, command);
+  if (command in PUBLIC_ROLE_ARGV || command === "global") {
+    const owner =
+      command === "global"
+        ? "global"
+        : (command as keyof typeof PUBLIC_ROLE_ARGV);
+    lines.push("", "OPTIONS");
+    lines.push(...renderHumanOwnerOptionLines(owner));
   }
   return `${lines.join("\n")}\n`;
 }

package/src/public-cli/option-definitions.ts

@@ -998,57 +998,214 @@ export function allRejectedSpellingTokens(): readonly string[] {
 }
 
 /**
- * Render one owner’s options as stable TSV lines for help.
- * Layout is presentation; identity columns are the structured contract.
+ * #125 — public command help facts on the sole option-owner module.
+ * Presentation inputs only (USAGE synopsis + public `ak-role` examples).
+ * Option identity/requiredness remain on PUBLIC_OPTION_TABLE rows.
+ * Free text is not a test contract (机器只咬契约，不咬呈现).
  */
-export function renderOwnerOptionHelpLines(
+export type PublicCommandHelpFacts = {
+  /** Command / topic id (role owner, support command, or "top"). */
+  readonly command: string;
+  /** One-line what-it-does (presentation). */
+  readonly summary: string;
+  /** USAGE synopsis line(s), each a full public `ak-role …` sketch. */
+  readonly usage: readonly string[];
+  /** 1–2 public invocation examples using only public spellings. */
+  readonly examples: readonly string[];
+};
+
+/**
+ * Top-level public help short note for automatic Navigator attendance.
+ * Not a caller command; configure via `ak-role config set navigator …`.
+ */
+export const PUBLIC_NAVIGATOR_HELP_NOTE =
+  "Navigator attends automatically on every run; configure with `ak-role config set navigator <provider/model[:thinking]>` (not a caller command)." as const;
+
+const TOP_LEVEL_HELP = {
+  command: "top",
+  summary: "public role CLI",
+  usage: [
+    "ak-role <command> [options]",
+    "ak-role help <command>",
+  ],
+  examples: [
+    'ak-role judge --attach ./plan.md "Review this plan."',
+    'ak-role coder plan "Propose the first implementation plan."',
+  ],
+} as const satisfies PublicCommandHelpFacts;
+
+const ROLE_COMMAND_HELP = {
+  judge: {
+    command: "judge",
+    summary: "Adjudicate the supplied materials; infers its own burden.",
+    usage: ["ak-role judge [options] [instruction]"],
+    examples: [
+      'ak-role judge --attach ./plan.md "Review this plan."',
+      'ak-role judge --attach ./findings.md --attach ./adr.md "Adjudicate every finding."',
+    ],
+  },
+  coder: {
+    command: "coder",
+    summary: "First implementation; phase defaults to apply.",
+    usage: ["ak-role coder [plan|apply] [options] <instruction>"],
+    examples: [
+      'ak-role coder plan "Propose the first implementation plan."',
+      'ak-role coder apply --attach ./plan.md "Implement the approved slice."',
+    ],
+  },
+  fixer: {
+    command: "fixer",
+    summary: "Repair the assigned findings; phase defaults to apply.",
+    usage: ["ak-role fixer [plan|apply] [options] <instruction>"],
+    examples: [
+      'ak-role fixer --attach ./findings.md --prerequisites ./prereqs.json "Repair the findings."',
+      'ak-role fixer plan --attach ./findings.md "Propose the repair plan."',
+    ],
+  },
+  reviewer: {
+    command: "reviewer",
+    summary: "Fixed-target two-axis review (Standards + Spec).",
+    usage: ["ak-role reviewer --base <revision> [options] <instruction>"],
+    examples: [
+      'ak-role reviewer --base main "Review the branch against the governing issue and repository authority."',
+    ],
+  },
+  collector: {
+    command: "collector",
+    summary: "Collect GitHub PR review evidence (one-shot).",
+    usage: ["ak-role collector --pr <number> [options] [instruction]"],
+    examples: [
+      "ak-role collector --pr 42 --repo owner/repository",
+      "ak-role collector --pr 42 --request-manifest ./requests.json",
+    ],
+  },
+  doctor: {
+    command: "doctor",
+    summary: "Diagnose one retained case (one-shot).",
+    usage: ["ak-role doctor --issue <number> [options] [instruction]"],
+    examples: [
+      'ak-role doctor --issue 115 "Diagnose this retained case."',
+    ],
+  },
+  merger: {
+    command: "merger",
+    summary: "Resolve one ordinary merge already in conflict.",
+    usage: ["ak-role merger [options] <instruction>"],
+    examples: [
+      'ak-role merger --project /path/to/worktree "Reconcile the active merge."',
+    ],
+  },
+  taishi: {
+    command: "taishi",
+    summary: "Deterministic analysis seat (issue / sweep / cohort / model-groups).",
+    usage: [
+      "ak-role taishi (--ticket <N> | --project-root <P>) [options]",
+      "ak-role taishi [sweep] --attach <path>",
+      "ak-role taishi --cohort --group-a-label <L> --group-a-issues <N[,N...]> --group-b-label <L> --group-b-issues <N[,N...]>",
+      "ak-role taishi --model-groups --project-root <P> [--project-root <P> ...]",
+    ],
+    examples: [
+      "ak-role taishi --ticket 125",
+      "ak-role taishi sweep --attach ./sweep.json",
+    ],
+  },
+} as const satisfies Record<PublicRoleOptionOwner, PublicCommandHelpFacts>;
+
+const SUPPORT_COMMAND_HELP = {
+  roles: {
+    command: "roles",
+    summary: "List effective seats and models.",
+    usage: ["ak-role roles"],
+    examples: ["ak-role roles"],
+  },
+  config: {
+    command: "config",
+    summary: "Persistent seat model and labor-engine defaults.",
+    usage: [
+      "ak-role config set <seat> <provider/model[:thinking]> [<seat> <spec> ...]",
+      "ak-role config set-engine <seat> <name>",
+      "ak-role config unset-engine <seat>",
+    ],
+    examples: [
+      "ak-role config set judge openai-codex/gpt-5.6-sol:high",
+      "ak-role config set-engine judge opus",
+    ],
+  },
+  help: {
+    command: "help",
+    summary: "Show public CLI help.",
+    usage: ["ak-role help [command]", "ak-role --help"],
+    examples: ["ak-role help coder", "ak-role help judge"],
+  },
+  resume: {
+    command: "resume",
+    summary: "Reopen an exact role run after a typed HTTP 429.",
+    usage: ["ak-role resume <runId>"],
+    examples: ["ak-role resume 01abc…"],
+  },
+} as const satisfies Record<string, PublicCommandHelpFacts>;
+
+/**
+ * Sole public help-copy owner keyed by command/topic id.
+ * Role topics share identity with PUBLIC_ROLE_OPTION_OWNERS; options still
+ * project from PUBLIC_OPTION_TABLE. Support topics cover non-option commands.
+ */
+export const PUBLIC_COMMAND_HELP = {
+  top: TOP_LEVEL_HELP,
+  ...ROLE_COMMAND_HELP,
+  ...SUPPORT_COMMAND_HELP,
+} as const;
+
+export type PublicCommandHelpTopic = keyof typeof PUBLIC_COMMAND_HELP;
+
+/** Structured projector — identity + presence; free text is presentation. */
+export function projectCommandHelp(
+  topic: string,
+): PublicCommandHelpFacts | undefined {
+  if (!(topic in PUBLIC_COMMAND_HELP)) return undefined;
+  const facts = PUBLIC_COMMAND_HELP[topic as PublicCommandHelpTopic];
+  return {
+    command: facts.command,
+    summary: facts.summary,
+    usage: [...facts.usage],
+    examples: [...facts.examples],
+  };
+}
+
+/**
+ * Human OPTIONS lines from the sole option table.
+ * Layout is presentation; structured identity stays on projectOwnerOptions.
+ */
+export function renderHumanOwnerOptionLines(
   owner: OptionOwner,
   locale: "en" | "zh" = "en",
 ): string[] {
   const lines: string[] = [];
   for (const opt of projectOwnerOptions(owner)) {
-    const aliasText =
-      opt.aliases.length === 0 ? "-" : opt.aliases.join(",");
-    const metavar = opt.valueMetavar ?? "-";
-    const required = opt.required ? "required" : "optional";
-    const repeatable = opt.repeatable ? "repeatable" : "single";
-    const form = opt.form;
-    const phases =
-      opt.phases === undefined ? "-" : opt.phases.join("|");
-    const modes = opt.modes === undefined ? "-" : opt.modes.join("|");
-    const requiredInModes =
-      opt.requiredInModes === undefined
-        ? "-"
-        : opt.requiredInModes.join("|");
-    const exclusiveWith =
-      opt.exclusiveWith === undefined ? "-" : opt.exclusiveWith.join("|");
-    const maxCount =
-      opt.maxCountByMode === undefined
-        ? "-"
-        : Object.entries(opt.maxCountByMode)
-            .map(([mode, n]) => `${mode}:${n}`)
-            .join(",");
-    const defaultValue = opt.defaultValue ?? "-";
+    let spelling = opt.canonical;
+    if (opt.valueMetavar !== null) {
+      spelling = `${spelling} <${opt.valueMetavar}>`;
+    }
+    if (opt.aliases.length > 0) {
+      // Prefer single-token aliases in the spelling hint (plan/apply, -h).
+      const aliasHint = opt.aliases.join(", ");
+      if (opt.form === "positional") {
+        spelling = opt.aliases.length > 0 ? opt.aliases.join("|") : spelling;
+      } else {
+        spelling = `${spelling} (${aliasHint})`;
+      }
+    }
+    const tags: string[] = [];
+    if (opt.required) tags.push("required");
+    if (opt.requiredInModes !== undefined) {
+      tags.push(`required:${opt.requiredInModes.join("|")}`);
+    }
+    if (opt.repeatable) tags.push("repeatable");
+    if (opt.defaultValue !== undefined) tags.push(`default=${opt.defaultValue}`);
+    if (opt.form === "positional") tags.push("positional");
+    const tagText = tags.length === 0 ? "" : ` [${tags.join(", ")}]`;
     const desc = locale === "zh" ? opt.description.zh : opt.description.en;
-    lines.push(
-      [
-        "option",
-        opt.id,
-        opt.canonical,
-        `aliases=${aliasText}`,
-        `metavar=${metavar}`,
-        required,
-        repeatable,
-        `form=${form}`,
-        `phases=${phases}`,
-        `modes=${modes}`,
-        `requiredInModes=${requiredInModes}`,
-        `exclusiveWith=${exclusiveWith}`,
-        `maxCountByMode=${maxCount}`,
-        `default=${defaultValue}`,
-        desc,
-      ].join("\t"),
-    );
+    lines.push(`  ${spelling}${tagText}  ${desc}`);
   }
   return lines;
 }