@pknx/waterfall-cli 0.1.0

package/lib/cli/core/cli-help-spec.ts

@@ -0,0 +1,833 @@
+import { CLI_JSON_DOT_WATERFALL } from "../config/dot-waterfall.js";
+import {
+  OPERATOR_HINT_JSON,
+  OPERATOR_HINT_POSITIONAL_DESCRIPTION,
+} from "../commands/resolve-operator-hint";
+
+export const CLI_HELP_SCHEMA_VERSION = 1;
+
+export type CliGlobalOptionSpec = {
+  long: string;
+  short?: string;
+  metavar?: string;
+  type: "string" | "boolean" | "enum";
+  enumValues?: string[];
+  description: string;
+  default?: string;
+  env?: string;
+  dotWaterfallKey?: string;
+  notes?: string;
+};
+
+export type CliPositionalSpec = {
+  name: string;
+  required: boolean;
+  description: string;
+};
+
+export type CliCommandOptionSpec = {
+  long: string;
+  short?: string;
+  type: "boolean" | "string";
+  description: string;
+};
+
+export type CliCommandSpec = {
+  id: string;
+  /** Fixed argv prefix after global options, e.g. \`["cr", "to", "rq"]\`. */
+  argvPrefix: string[];
+  usage: string;
+  /**
+   * Example one-liner with \`waterfall\` prefix (realistic args; global flags optional).
+   * Emitted as \`example\` in \`help -o json\`; \`cliForm\` there matches \`usage\` (typed argv, no dotted id).
+   */
+  example: string;
+  summary: string;
+  kind:
+    | "meta"
+    | "scaffold"
+    | "git-branch"
+    | "git-mutate"
+    | "agent-prompt"
+    | "orchestrate"
+    | "export"
+    | "sync";
+  requiresSpecRoot: boolean;
+  positionals?: CliPositionalSpec[];
+  commandOptions?: CliCommandOptionSpec[];
+  /** Shipped workflow markdown under the CLI \`prompts/\` tree (agent-prompt / orchestrate). */
+  promptFile?: string;
+  orchestrationSteps?: string[];
+  /**
+   * Required git branch in the resolved spec repo when `requiresSpecRoot` is true,
+   * or N/A wording for meta/scaffold commands (see `git-branch-guards.ts`).
+   */
+  branchRequirement: string;
+};
+
+/** No spec checkout — \`help\`, etc. */
+export const CLI_HELP_BRANCH_NONE =
+  "No spec-root git branch check (this command does not resolve a waterfall-spec checkout).";
+
+/** \`spec init\` — works on a target directory, not an existing resolved spec root. */
+export const CLI_HELP_BRANCH_SCAFFOLD =
+  "No spec-root resolution; initializes DIR (may create git there on develop). After that, follow CURSOR.md branch rules in the new tree.";
+
+/** \`cr start\`, \`story close\` — \`assertBranchDevelop\`. */
+export const CLI_HELP_BRANCH_DEVELOP =
+  'Spec repo: current git branch must be "develop".';
+
+/** Lifecycle agents, orchestration, \`sys start\`, \`bug start\`, horizontals, \`cr finish\` — \`assertBranchForCrScopedCommand\`. */
+export const CLI_HELP_BRANCH_FEATURE_CR =
+  "Spec repo: current git branch must match feature/CR-<digits>-… (change-request branch; use waterfall cr start from develop).";
+
+export const GLOBAL_OPTIONS: CliGlobalOptionSpec[] = [
+  {
+    long: "spec-root",
+    metavar: "PATH",
+    type: "string",
+    description:
+      "Override waterfall-spec repository root (absolute or relative to cwd).",
+    env: "WATERFALL_SPEC_ROOT",
+    dotWaterfallKey: "spec_root",
+  },
+  {
+    long: "backend",
+    metavar: "ID",
+    type: "enum",
+    enumValues: ["cline-ollama", "cursor", "claude-code"],
+    description: "Agent backend for prompt commands.",
+    default: "cline-ollama",
+    env: "WATERFALL_BACKEND",
+    dotWaterfallKey: "backend",
+  },
+  {
+    long: "dry-run",
+    type: "boolean",
+    description:
+      "Print planned agent invocation only (default for lifecycle prompt commands unless overridden).",
+    dotWaterfallKey: "dry_run",
+  },
+  {
+    long: "execute-agent",
+    type: "boolean",
+    description:
+      "Invoke the real backend (cline / agent|cursor / claude); implies not dry-run.",
+    dotWaterfallKey: "execute_agent",
+  },
+  {
+    long: "log-level",
+    metavar: "L",
+    type: "enum",
+    enumValues: ["silent", "normal", "verbose"],
+    description: "CLI tracing verbosity for agent planning / invoke.",
+    env: "WATERFALL_LOG_LEVEL",
+    dotWaterfallKey: "level",
+  },
+  {
+    long: "quiet",
+    type: "boolean",
+    description: "Same as --log-level silent (subprocess output unchanged).",
+  },
+  {
+    long: "prompt-delivery",
+    metavar: "M",
+    type: "enum",
+    enumValues: ["embed", "reference"],
+    description:
+      "embed: inline workflow markdown in the agent message; reference: filesystem paths only.",
+    default: "embed",
+    dotWaterfallKey: "prompt_delivery",
+  },
+];
+
+/** Commands and special forms handled by \`main.ts\` / registry (order matches dispatch). */
+export const COMMAND_SPECS: CliCommandSpec[] = [
+  {
+    id: "help",
+    argvPrefix: ["help"],
+    usage: "help [-o json | --output json]",
+    example: "waterfall help -o json",
+    summary: "Print usage text or machine-readable CLI spec as JSON.",
+    kind: "meta",
+    requiresSpecRoot: false,
+    branchRequirement: CLI_HELP_BRANCH_NONE,
+    commandOptions: [
+      {
+        long: "output",
+        short: "o",
+        type: "string",
+        description: 'Output format; use "json" for the CLI command/options spec.',
+      },
+    ],
+  },
+  {
+    id: "spec.init",
+    argvPrefix: ["spec", "init"],
+    usage: 'spec init --title TITLE [--full] [DIR]',
+    example: 'waterfall spec init --title "My product" --full ./my-waterfall-spec',
+    summary:
+      "Create a new spec directory: pom.json (project title + future metadata), layout, number.json, CURSOR.md, git on develop.",
+    kind: "scaffold",
+    requiresSpecRoot: false,
+    branchRequirement: CLI_HELP_BRANCH_SCAFFOLD,
+    commandOptions: [
+      {
+        long: "title",
+        metavar: "TITLE",
+        type: "string",
+        description:
+          "Required. Project name written to pom.json at the init root (also used as export pdf document title when that tree is the spec).",
+      },
+      {
+        long: "full",
+        type: "boolean",
+        description:
+          "Copy regeneratable prompts/ + doc/ from spec-template/full and extend CURSOR.md.",
+      },
+    ],
+    positionals: [
+      {
+        name: "DIR",
+        required: false,
+        description: "Target directory (default: .).",
+      },
+    ],
+  },
+  {
+    id: "sync.stories",
+    argvPrefix: ["sync", "stories"],
+    usage: "sync stories [--dump-spec] [<hint…>]",
+    example: "waterfall sync stories --dump-spec",
+    summary:
+      "Load STORY-* from technical/ into canonical work-item JSON (comments from `STORY-NNN.comments.json` + tracker; compared by author `email` + `createdAt` + display `user` + body). Spec-side attachments are **other files in the same folder** as STORY-NNN.md (not the .md itself). Configure via .waterfall `sync_story_*` (`sync_story_leading=waterfall|remote`, default waterfall). On mismatches the leading side is canonical for state/title/comments/attachments for **reporting**. **Comments on disk** are always overwritten from the remote snapshot for each id present in both spec and remote (`{STORY}-NNN.comments.json`). --dump-spec prints spec-side meta only (ignores hint). Optional hint after flags: same resolution as operator hints (inline argv, `-` stdin, `@PATH`); provider `direct` requires JSON in the `--dump-spec` shape for the remote side. With `direct`, stdout ends with pretty-printed JSON (`source`: `waterfall-direct-out`) after every run (pipe to seed the next `@PATH` hint).",
+    kind: "sync",
+    requiresSpecRoot: true,
+    branchRequirement: CLI_HELP_BRANCH_NONE,
+    commandOptions: [
+      {
+        long: "dump-spec",
+        type: "boolean",
+        description:
+          "Emit waterfall-spec work-item meta JSON to stdout (no .waterfall sync_story_* required).",
+      },
+    ],
+    positionals: [
+      {
+        name: "hint",
+        required: false,
+        description: OPERATOR_HINT_POSITIONAL_DESCRIPTION,
+      },
+    ],
+  },
+  {
+    id: "sync.bugs",
+    argvPrefix: ["sync", "bugs"],
+    usage: "sync bugs [--dump-spec] [<hint…>]",
+    example: "waterfall sync bugs --dump-spec",
+    summary:
+      "Same as sync stories for BUG-* (`BUG-NNN.comments.json` + tracker comments; folder file attachments) using sync_bug_* keys (`sync_bug_leading` defaults to remote). With `sync_bug_leading=remote`, remote-only bug ids are created under `technical/SYS-NNN-*/BUG-NNN-slug/` with **Draft steering (remote import)** for the agent; **SYS** comes from remote `sysId` when set, else the only `SYS-*` folder, else keyword overlap vs SYS/STORY folder names (ties → set `sysId` in the hint). After materialize + comments, runs `prompts/commands/sync-bugs-refine-imports.md` (dry-run or `--execute-agent`). Optional hint, `direct` provider, and `waterfall-direct-out` stdout after each run behave like sync stories.",
+    kind: "sync",
+    requiresSpecRoot: true,
+    branchRequirement: CLI_HELP_BRANCH_NONE,
+    commandOptions: [
+      {
+        long: "dump-spec",
+        type: "boolean",
+        description:
+          "Emit waterfall-spec BUG work-item meta JSON to stdout (no sync_bug_* required).",
+      },
+    ],
+    positionals: [
+      {
+        name: "hint",
+        required: false,
+        description: OPERATOR_HINT_POSITIONAL_DESCRIPTION,
+      },
+    ],
+  },
+  {
+    id: "export.pdf",
+    argvPrefix: ["export", "pdf"],
+    usage:
+      "export pdf [--items LIST | --items=LIST] [-o PATH | --output PATH]",
+    example: "waterfall export pdf --items CR,RQ,UC,HOR,TST",
+    summary:
+      "Merge selected spec markdown into one document, render fenced Mermaid diagrams to PNG via bundled @mermaid-js/mermaid-cli (mmdc), then produce PDF with pandoc-wasm (Markdown→HTML) and puppeteer (HTML→PDF, Chromium bundled). Requires a clean git working tree at the spec root. --items is a comma-separated list of artifact codes (CR,RQ,UC,SYS,STORY,BUG,HOR,TST,CURSOR); default CR,RQ,UC,HOR,TST excludes CURSOR.md, prompts/, doc/, docs/, SYS/STORY/BUG bodies, etc. Document title (PDF metadata and top heading): non-empty string \"title\" from pom.json, found by walking up from the spec root until pom.json exists (see spec init --title). Default output: <spec-root>/docs/<basename>-<tag|short-hash>.pdf. Optional -o overrides the output file path. use_native_pandoc=true in .waterfall uses system pandoc (WATERFALL_PANDOC_ARGS).",
+    kind: "export",
+    requiresSpecRoot: true,
+    branchRequirement: CLI_HELP_BRANCH_NONE,
+    commandOptions: [
+      {
+        long: "items",
+        type: "string",
+        description:
+          "Comma-separated codes: CR,RQ,UC,SYS,STORY,BUG,HOR,TST,CURSOR. Default CR,RQ,UC,HOR,TST. Forms: --items LIST, --items=LIST, -items=LIST.",
+      },
+      {
+        long: "output",
+        short: "o",
+        type: "string",
+        description:
+          "Output PDF path (default: <spec-root>/docs/<basename>-<tag|hash>.pdf). Relative to cwd.",
+      },
+    ],
+  },
+  {
+    id: "cr.start",
+    argvPrefix: ["cr", "start"],
+    usage: "cr start <description>",
+    example: 'waterfall cr start "Payment retry handling"',
+    summary:
+      "On develop: new feature/CR-* branch, scaffold CR-NNN.md + bump number.json (commit), then agent prompt cr-start.md to synthesize Summary/Proposed change (--execute-agent or dry-run).",
+    kind: "git-branch",
+    requiresSpecRoot: true,
+    branchRequirement: CLI_HELP_BRANCH_DEVELOP,
+    promptFile: "prompts/commands/cr-start.md",
+    positionals: [
+      {
+        name: "description",
+        required: true,
+        description: `CR title / slug source. ${OPERATOR_HINT_POSITIONAL_DESCRIPTION}`,
+      },
+    ],
+  },
+  {
+    id: "sys.start",
+    argvPrefix: ["sys", "start"],
+    usage: "sys start <description>",
+    example: 'waterfall sys start "Authentication subsystem"',
+    summary:
+      "On a CR branch: scaffold SYS-NNN.md + bump number.json (commit), then agent prompt sys-start.md to synthesize Purpose (--execute-agent or dry-run).",
+    kind: "git-mutate",
+    requiresSpecRoot: true,
+    branchRequirement: CLI_HELP_BRANCH_FEATURE_CR,
+    promptFile: "prompts/commands/sys-start.md",
+    positionals: [
+      {
+        name: "description",
+        required: true,
+        description: `Subsystem title / slug source. ${OPERATOR_HINT_POSITIONAL_DESCRIPTION}`,
+      },
+    ],
+  },
+  {
+    id: "bug.start",
+    argvPrefix: ["bug", "start"],
+    usage: "bug start SYS-NNN <hint>",
+    example: 'waterfall bug start SYS-001 "Cart total rounds incorrectly"',
+    summary:
+      "On a CR branch: scaffold BUG-NNN.md under the matching SYS folder + bump number.json (commit), then agent prompt bug-start.md to synthesize Summary (--execute-agent or dry-run).",
+    kind: "git-mutate",
+    requiresSpecRoot: true,
+    branchRequirement: CLI_HELP_BRANCH_FEATURE_CR,
+    promptFile: "prompts/commands/bug-start.md",
+    positionals: [
+      {
+        name: "sysId",
+        required: true,
+        description: "Parent subsystem id (SYS-NNN); must match an existing technical/SYS-NNN-* folder.",
+      },
+      {
+        name: "hint",
+        required: true,
+        description: OPERATOR_HINT_POSITIONAL_DESCRIPTION,
+      },
+    ],
+  },
+  {
+    id: "horizontal.create",
+    argvPrefix: ["horizontal", "create"],
+    usage: "horizontal create story <name-slug> <purpose>",
+    example:
+      'waterfall horizontal create story database-model "Shared schema for orders"',
+    summary:
+      "On a CR branch: scaffold HOR-NNN.md + bump next.HOR (commit), then agent prompt horizontal-create.md to synthesize Purpose (--execute-agent or dry-run).",
+    kind: "git-mutate",
+    requiresSpecRoot: true,
+    branchRequirement: CLI_HELP_BRANCH_FEATURE_CR,
+    promptFile: "prompts/commands/horizontal-create.md",
+    positionals: [
+      {
+        name: "anchor",
+        required: true,
+        description: "Anchor item type (e.g. story).",
+      },
+      {
+        name: "name-slug",
+        required: true,
+        description: "Horizontal name slug (e.g. database-model).",
+      },
+      {
+        name: "purpose",
+        required: true,
+        description: `Purpose text. ${OPERATOR_HINT_POSITIONAL_DESCRIPTION}`,
+      },
+    ],
+  },
+  {
+    id: "horizontal.update",
+    argvPrefix: ["horizontal", "update"],
+    usage: "horizontal update HOR-NNN [<hint>]",
+    example: "waterfall horizontal update HOR-001",
+    summary:
+      "On a CR branch: run git diff develop...HEAD for scope; agent prompt horizontal-update (does not edit HOR file mechanically).",
+    kind: "agent-prompt",
+    requiresSpecRoot: true,
+    branchRequirement: CLI_HELP_BRANCH_FEATURE_CR,
+    promptFile: "prompts/commands/horizontal-update.md",
+    positionals: [
+      {
+        name: "HOR-NNN",
+        required: true,
+        description: "Horizontal id (HOR-001 or 001).",
+      },
+      {
+        name: "hint",
+        required: false,
+        description: `Optional operator hint. ${OPERATOR_HINT_POSITIONAL_DESCRIPTION}`,
+      },
+    ],
+  },
+  {
+    id: "cr.finish",
+    argvPrefix: ["cr", "finish"],
+    usage: "cr finish",
+    example: "waterfall cr finish",
+    summary:
+      "On CR branch: validate diff vs develop, merge into develop, checkout develop.",
+    kind: "git-mutate",
+    requiresSpecRoot: true,
+    branchRequirement: CLI_HELP_BRANCH_FEATURE_CR,
+    promptFile: "prompts/commands/cr-finish.md",
+  },
+  {
+    id: "cr.to-rq",
+    argvPrefix: ["cr", "to", "rq"],
+    usage: "cr to rq <hint>",
+    example: 'waterfall cr to rq "Triage scope for API errors"',
+    summary: "Agent: CR → RQ triage (cr-to-rq).",
+    kind: "agent-prompt",
+    requiresSpecRoot: true,
+    branchRequirement: CLI_HELP_BRANCH_FEATURE_CR,
+    promptFile: "prompts/commands/cr-to-rq.md",
+    positionals: [
+      {
+        name: "hint",
+        required: true,
+        description: OPERATOR_HINT_POSITIONAL_DESCRIPTION,
+      },
+    ],
+  },
+  {
+    id: "rq.to-uc",
+    argvPrefix: ["rq", "to", "uc"],
+    usage: "rq to uc <hint>",
+    example: 'waterfall rq to uc "Split admin vs customer flows"',
+    summary: "Agent: RQ → UC (rq-to-uc).",
+    kind: "agent-prompt",
+    requiresSpecRoot: true,
+    branchRequirement: CLI_HELP_BRANCH_FEATURE_CR,
+    promptFile: "prompts/commands/rq-to-uc.md",
+    positionals: [
+      {
+        name: "hint",
+        required: true,
+        description: OPERATOR_HINT_POSITIONAL_DESCRIPTION,
+      },
+    ],
+  },
+  {
+    id: "uc.to-story",
+    argvPrefix: ["uc", "to", "story"],
+    usage: "uc to story <hint>",
+    example: 'waterfall uc to story "Checkout happy path"',
+    summary: "Agent: UC → story (uc-to-story).",
+    kind: "agent-prompt",
+    requiresSpecRoot: true,
+    branchRequirement: CLI_HELP_BRANCH_FEATURE_CR,
+    promptFile: "prompts/commands/uc-to-story.md",
+    positionals: [
+      {
+        name: "hint",
+        required: true,
+        description: OPERATOR_HINT_POSITIONAL_DESCRIPTION,
+      },
+    ],
+  },
+  {
+    id: "uc.to-test",
+    argvPrefix: ["uc", "to", "test"],
+    usage: "uc to test <hint>",
+    example: 'waterfall uc to test "Gherkin for returns and refunds"',
+    summary: "Agent: UC → test (uc-to-test).",
+    kind: "agent-prompt",
+    requiresSpecRoot: true,
+    branchRequirement: CLI_HELP_BRANCH_FEATURE_CR,
+    promptFile: "prompts/commands/uc-to-test.md",
+    positionals: [
+      {
+        name: "hint",
+        required: true,
+        description: OPERATOR_HINT_POSITIONAL_DESCRIPTION,
+      },
+    ],
+  },
+  {
+    id: "test.to-story",
+    argvPrefix: ["test", "to", "story"],
+    usage: "test to story <hint>",
+    example: 'waterfall test to story "Align tests with STORY-002"',
+    summary: "Agent: test → story (test-to-story).",
+    kind: "agent-prompt",
+    requiresSpecRoot: true,
+    branchRequirement: CLI_HELP_BRANCH_FEATURE_CR,
+    promptFile: "prompts/commands/test-to-story.md",
+    positionals: [
+      {
+        name: "hint",
+        required: true,
+        description: OPERATOR_HINT_POSITIONAL_DESCRIPTION,
+      },
+    ],
+  },
+  {
+    id: "cr.all",
+    argvPrefix: ["cr", "all"],
+    usage: "cr all [<hint>]",
+    example: 'waterfall cr all "Run full chain from new CR"',
+    summary: "Orchestrate cr → rq → rq→uc → uc→story → uc→test → test→story.",
+    kind: "orchestrate",
+    requiresSpecRoot: true,
+    branchRequirement: CLI_HELP_BRANCH_FEATURE_CR,
+    positionals: [
+      {
+        name: "hint",
+        required: false,
+        description: OPERATOR_HINT_POSITIONAL_DESCRIPTION,
+      },
+    ],
+    orchestrationSteps: [
+      "cr-to-rq",
+      "rq-to-uc",
+      "uc-to-story",
+      "uc-to-test",
+      "test-to-story",
+    ],
+  },
+  {
+    id: "rq.all",
+    argvPrefix: ["rq", "all"],
+    usage: "rq all [<hint>]",
+    example: 'waterfall rq all "Continue from requirements"',
+    summary: "Orchestrate rq→uc → uc→story → uc→test → test→story.",
+    kind: "orchestrate",
+    requiresSpecRoot: true,
+    branchRequirement: CLI_HELP_BRANCH_FEATURE_CR,
+    positionals: [
+      {
+        name: "hint",
+        required: false,
+        description: OPERATOR_HINT_POSITIONAL_DESCRIPTION,
+      },
+    ],
+    orchestrationSteps: [
+      "rq-to-uc",
+      "uc-to-story",
+      "uc-to-test",
+      "test-to-story",
+    ],
+  },
+  {
+    id: "uc.all",
+    argvPrefix: ["uc", "all"],
+    usage: "uc all [<hint>]",
+    example: 'waterfall uc all "Stories and tests from use cases"',
+    summary: "Orchestrate uc→story → uc→test → test→story.",
+    kind: "orchestrate",
+    requiresSpecRoot: true,
+    branchRequirement: CLI_HELP_BRANCH_FEATURE_CR,
+    positionals: [
+      {
+        name: "hint",
+        required: false,
+        description: OPERATOR_HINT_POSITIONAL_DESCRIPTION,
+      },
+    ],
+    orchestrationSteps: ["uc-to-story", "uc-to-test", "test-to-story"],
+  },
+  {
+    id: "test.all",
+    argvPrefix: ["test", "all"],
+    usage: "test all [<hint>]",
+    example: 'waterfall test all "Propagate test specs to stories"',
+    summary: "Orchestrate test→story only.",
+    kind: "orchestrate",
+    requiresSpecRoot: true,
+    branchRequirement: CLI_HELP_BRANCH_FEATURE_CR,
+    positionals: [
+      {
+        name: "hint",
+        required: false,
+        description: OPERATOR_HINT_POSITIONAL_DESCRIPTION,
+      },
+    ],
+    orchestrationSteps: ["test-to-story"],
+  },
+  {
+    id: "comment.add",
+    argvPrefix: ["comment", "add"],
+    usage: "comment add <ITEM-ID> <email> <display-name> <hint…>",
+    example:
+      'waterfall comment add STORY-001 dev@acme.com Reviewer "Align with API review notes"',
+    summary:
+      "On develop: append a remark for any spec item with a canonical `{ITEM-ID}.md` (CR,RQ,UC,SYS,STORY,BUG,HOR,TST + NNN). Stored as `{ITEM-ID}.comments.json` beside that markdown; author identity is `email`, display name is `from`. State OPEN + ISO timestamps; RESOLVED|REJECTED by editing the file.",
+    kind: "git-mutate",
+    requiresSpecRoot: true,
+    branchRequirement: CLI_HELP_BRANCH_DEVELOP,
+    positionals: [
+      {
+        name: "item",
+        required: true,
+        description:
+          "CR|RQ|UC|SYS|STORY|BUG|HOR|TST-NNN — must match exactly one `{ITEM}.md` under the spec root.",
+      },
+      {
+        name: "email",
+        required: true,
+        description: "Author identifier for sync (same person as display name).",
+      },
+      {
+        name: "display-name",
+        required: true,
+        description: "Short display label stored as `from`.",
+      },
+      {
+        name: "hint",
+        required: true,
+        description: "Remark text (remaining argv joined with spaces).",
+      },
+    ],
+  },
+  {
+    id: "story.close",
+    argvPrefix: ["story", "close"],
+    usage: "story close STORY-NNN | story close all",
+    example: "waterfall story close STORY-001",
+    summary:
+      "On develop: close one story folder (rename with _) or note for close all.",
+    kind: "git-mutate",
+    requiresSpecRoot: true,
+    branchRequirement: CLI_HELP_BRANCH_DEVELOP,
+    positionals: [
+      {
+        name: "STORY-NNN|all",
+        required: true,
+        description: "Story id or all (all may be restricted in implementation).",
+      },
+    ],
+  },
+];
+
+export type CliEnvironmentVariableSpec = {
+  name: string;
+  description: string;
+  /** Typical values or format (when not obvious from description). */
+  valueDescription?: string;
+  cliFlag?: string;
+  dotWaterfallKey?: string;
+};
+
+export type CliEnvironmentCategorySpec = {
+  id: string;
+  title: string;
+  description?: string;
+  variables: CliEnvironmentVariableSpec[];
+};
+
+export type CliHelpJsonEnvironment = {
+  description: string;
+  precedenceNote: string;
+  categories: CliEnvironmentCategorySpec[];
+};
+
+/**
+ * All env vars referenced by waterfall-cli (read in code or documented for operators).
+ * WATERFALL_* settings mirror {@link GLOBAL_OPTIONS} where \`env\` is set.
+ */
+export function buildCliHelpEnvironment(): CliHelpJsonEnvironment {
+  const fromGlobals: CliEnvironmentVariableSpec[] = GLOBAL_OPTIONS.filter(
+    (o): o is CliGlobalOptionSpec & { env: string } => Boolean(o.env),
+  ).map((o) => ({
+    name: o.env,
+    description: o.description,
+    valueDescription: o.enumValues?.join(" | "),
+    cliFlag: `--${o.long}`,
+    dotWaterfallKey: o.dotWaterfallKey,
+  }));
+
+  return {
+    description:
+      "Environment variables read by waterfall-cli or inherited by agent backend processes.",
+    precedenceNote:
+      "For CLI settings mirrored by flags, precedence is: argv > WATERFALL_* env > .waterfall > defaults (see config.precedence).",
+    categories: [
+      {
+        id: "waterfall-cli",
+        title: "Waterfall CLI (WATERFALL_*)",
+        variables: [
+          ...fromGlobals,
+          {
+            name: "WATERFALL_MMDC",
+            description:
+              "Absolute path to the Mermaid CLI binary (`mmdc`) for `waterfall export pdf`; overrides PATH and npx fallback.",
+          },
+          {
+            name: "WATERFALL_PANDOC",
+            description:
+              "Absolute path to the `pandoc` binary when `use_native_pandoc=true`; overrides PATH and built-in Homebrew guesses.",
+          },
+          {
+            name: "WATERFALL_PANDOC_PDF_ENGINE",
+            description:
+              "When `use_native_pandoc=true`: LaTeX engine for Pandoc (default `xelatex`, for Unicode in specs). Override e.g. `pdflatex` or `lualatex` if needed.",
+          },
+          {
+            name: "WATERFALL_PANDOC_ARGS",
+            description:
+              "When `use_native_pandoc=true` in .waterfall: extra arguments (space-separated) after input markdown, `-o` PDF path, TOC, and `--pdf-engine` (so you can append another `--pdf-engine` to override).",
+          },
+        ],
+      },
+      {
+        id: "cline",
+        title: "Cline backend",
+        description:
+          "Read when invoking the cline-ollama backend (--backend cline-ollama).",
+        variables: [
+          {
+            name: "WATERFALL_CLINE_MODEL",
+            description:
+              "Optional model id passed to the Cline CLI as -m when set.",
+            valueDescription: "e.g. llama3.2:latest",
+          },
+        ],
+      },
+      {
+        id: "agent-inherit",
+        title: "Agent subprocess environment",
+        description:
+          "Cursor, Claude Code, and Cline run with the current process environment. Set provider keys and endpoints per each tool’s docs. UPPER_SNAKE keys from ~/.waterfall / .waterfall are merged into process.env when unset; see dotWaterfall.environmentPassthrough (examples: ANTHROPIC_API_KEY, CURSOR_API_KEY, OLLAMA_HOST).",
+        variables: [],
+      },
+      {
+        id: "testing",
+        title: "Testing / internal",
+        description:
+          "Used by the waterfall-cli Vitest suite; operators do not need these.",
+        variables: [
+          {
+            name: "WATERFALL_TEST_HOME",
+            description:
+              "When set, used as the home directory for resolving ~/.waterfall.",
+          },
+          {
+            name: "VITEST",
+            description:
+              'When "true", skips auto-creating ~/.waterfall during tests and adjusts git helpers.',
+          },
+        ],
+      },
+    ],
+  };
+}
+
+export type CliHelpJsonCommand = CliCommandSpec & {
+  /** Typed argv after global options (spaces, not dotted \`id\`). Same text as \`usage\`. */
+  cliForm: string;
+};
+
+export type CliHelpJson = {
+  schemaVersion: number;
+  name: string;
+  title: string;
+  globalOptions: CliGlobalOptionSpec[];
+  config: {
+    files: string[];
+    precedence: string;
+    notes: string[];
+  };
+  /** Detailed \`.waterfall\` / \`~/.waterfall\` syntax and keys (see \`parseDotWaterfallContent\`). */
+  dotWaterfall: typeof CLI_JSON_DOT_WATERFALL;
+  /** Env vars read by the CLI or relevant to agent subprocesses (see \`buildCliHelpEnvironment\`). */
+  environment: CliHelpJsonEnvironment;
+  /** How operator hints are resolved (inline, stdin, file); see \`resolveOperatorHint\`. */
+  operatorHint: typeof OPERATOR_HINT_JSON;
+  specResolution: string[];
+  commands: CliHelpJsonCommand[];
+};
+
+export function buildCliHelpJson(): CliHelpJson {
+  return {
+    schemaVersion: CLI_HELP_SCHEMA_VERSION,
+    name: "waterfall",
+    title: "Waterfall CLI — waterfall-spec workflows",
+    globalOptions: GLOBAL_OPTIONS,
+    config: {
+      files: [".waterfall (cwd)", "~/.waterfall"],
+      precedence:
+        "flags > WATERFALL_* env > ./.waterfall > ~/.waterfall > defaults",
+      notes: [
+        "~/.waterfall is created on first run when missing (commented examples).",
+        "Log/tracing: WATERFALL_LOG_LEVEL or level= in .waterfall.",
+      ],
+    },
+    dotWaterfall: CLI_JSON_DOT_WATERFALL,
+    environment: buildCliHelpEnvironment(),
+    operatorHint: OPERATOR_HINT_JSON,
+    specResolution: [
+      "--spec-root",
+      "WATERFALL_SPEC_ROOT",
+      "./.waterfall and ~/.waterfall spec_root",
+      "waterfall.json waterfallSpecRelativePath (walk up from cwd)",
+      "walk up to directory containing CURSOR.md",
+    ],
+    commands: COMMAND_SPECS.map((c) => ({
+      ...c,
+      cliForm: c.usage,
+    })),
+  };
+}
+
+export function formatCliHelpJson(): string {
+  return `${JSON.stringify(buildCliHelpJson(), null, 2)}\n`;
+}
+
+/**
+ * Parse \`help\` argv after the \`help\` token: \`help\`, \`help -o json\`, etc.
+ */
+export function parseHelpFormat(rest: string[]): {
+  format: "text" | "json";
+} {
+  if (rest.length <= 1) return { format: "text" };
+  let format: "text" | "json" = "text";
+  for (let i = 1; i < rest.length; i++) {
+    const a = rest[i]!;
+    if (a === "-o" || a === "--output") {
+      const v = rest[++i];
+      if (!v) {
+        throw new Error(`${a} requires an argument (use json)`);
+      }
+      if (v.toLowerCase() === "json") {
+        format = "json";
+      } else {
+        throw new Error(
+          `Invalid output format "${v}" (use: waterfall help -o json)`,
+        );
+      }
+      continue;
+    }
+    throw new Error(`Unknown help option: ${a} (try: waterfall help -o json)`);
+  }
+  return { format };
+}