@pmelab/gtd 59.0.0 → 60.0.0

package/src/cli/Cli.test.ts

@@ -35,8 +35,8 @@ const FLAG_NAMES = [
   "--dev",
   "--cost",
   "--model",
-  "--workflow",
   "--var",
+  "--threshold",
   "--open-questions",
   "--open-threads",
   "--verbose",
@@ -71,7 +71,8 @@ describe("parseArgv — unknown options", () => {
     expect(plan).toEqual({
       kind: "usage",
       stdout: "",
-      message: "gtd: unknown option '--jsn' — see `gtd --help`",
+      message:
+        "gtd: unknown option '--jsn' — did you mean `--json`? Run `gtd help <command>` for its options",
       json: false,
     })
   })
@@ -104,13 +105,18 @@ describe("parseArgv — scope", () => {
     if (plan.kind === "usage") expect(plan.message).toContain("only valid for `gtd land`")
   })
 
-  it("--json is in scope for next, land, judge and judge answer — every other command usage-errors on it", () => {
+  it("--json is in scope for next, land, the judge and script commands and the listings — every other command usage-errors on it", () => {
     for (const args of [
       ["next", "--json"],
       ["land", "--json"],
       ["judge", "--json"],
       ["judge", "answer", "--json"],
-      ["doors", "--json"],
+      ["validate", "--json"],
+      ["abandon", "--json"],
+      ["restore", "--json"],
+      ["start", "--json"],
+      ["start", "fix", "--json"],
+      ["history", "fetch", "--json"],
     ]) {
       const ok = parseArgv(["node", "gtd.js", ...args])
       expect(ok.kind).toBe("command")
@@ -119,18 +125,16 @@ describe("parseArgv — scope", () => {
 
     for (const args of [
       ["lsp", "--json"],
-      ["validate", "--json"],
       ["check", "qa", "TODO.md", "--json"],
-      ["install", "--json"],
-      ["abandon", "--json"],
-      ["restore", "--json"],
-      ["--workflow", "some-state", "--json"],
+      ["guide", "--json"],
+      ["summary", "--json"],
+      ["base", "--json"],
     ]) {
       const plan = parseArgv(["node", "gtd.js", ...args])
       expect(plan.kind).toBe("usage")
       if (plan.kind === "usage") {
         expect(plan.message).toContain("only valid for `gtd next`/`gtd land`")
-        expect(plan.message).toContain("gtd install")
+        expect(plan.message).toContain("gtd guide")
       }
     }
   })
@@ -166,38 +170,31 @@ describe("parseArgv — scope", () => {
     }
   })
 
-  it("--var without --workflow is rejected", () => {
-    const plan = parseArgv(["node", "gtd.js", "land", "--var", "a=1"])
-    expect(plan.kind).toBe("usage")
-    if (plan.kind === "usage")
-      expect(plan.message).toBe("gtd: --var requires --workflow (or `gtd history judges`)")
-  })
-
-  it("--cost with --workflow is rejected (landing and starting are different verbs)", () => {
-    const plan = parseArgv(["node", "gtd.js", "--workflow", "foo", "--cost=5"])
-    expect(plan.kind).toBe("usage")
-    if (plan.kind === "usage") expect(plan.message).toContain("only valid for `gtd land`")
+  it("--var outside `gtd start` is rejected", () => {
+    for (const args of [
+      ["land", "--var", "a=1"],
+      ["history", "judges", "--var", "qualityTriageMinP=0.9"],
+    ]) {
+      const plan = parseArgv(["node", "gtd.js", ...args])
+      expect(plan.kind).toBe("usage")
+      if (plan.kind === "usage")
+        expect(plan.message).toBe("gtd: --var is only valid for `gtd start <name>`")
+    }
   })
 
-  it("--model with --workflow is rejected the same way", () => {
-    const plan = parseArgv(["node", "gtd.js", "--workflow", "foo", "--model=gpt"])
-    expect(plan.kind).toBe("usage")
-    if (plan.kind === "usage") expect(plan.message).toContain("only valid for `gtd land`")
+  it("--cost and --model on `gtd start` are rejected (landing and starting are different verbs)", () => {
+    for (const flag of ["--cost=5", "--model=gpt"]) {
+      const plan = parseArgv(["node", "gtd.js", "start", "foo", flag])
+      expect(plan.kind).toBe("usage")
+      if (plan.kind === "usage") expect(plan.message).toContain("only valid for `gtd land`")
+    }
   })
 
-  it("--workflow on `gtd land` (or any other command) is rejected — landing and starting are different verbs", () => {
-    for (const args of [
-      ["validate", "--workflow", "e"],
-      ["land", "--workflow", "e"],
-    ]) {
+  it("--workflow is gone: an unknown option on its own and after any command", () => {
+    for (const args of [["--workflow", "e"], ["--workflow=e"], ["land", "--workflow", "e"]]) {
       const plan = parseArgv(["node", "gtd.js", ...args])
       expect(plan.kind).toBe("usage")
-      if (plan.kind === "usage") {
-        expect(plan.message).toBe(
-          "gtd: --workflow is only valid with no other command — use the bare `gtd --workflow <name>` " +
-            "form; landing and starting are different verbs",
-        )
-      }
+      if (plan.kind === "usage") expect(plan.message).toContain("unknown option '--workflow")
     }
   })
 
@@ -369,17 +366,52 @@ describe("parseArgv — bare/unknown command under --json", () => {
     }
   })
 
-  it("bare gtd's missing-command message (no --json) points at gtd install, not a bundled loop", () => {
+  it("bare gtd prints a short usage, not the overview, and points at gtd help and gtd guide", () => {
     const plan = parseArgv(["node", "gtd.js"])
     expect(plan.kind).toBe("usage")
     if (plan.kind === "usage") {
       expect(plan.message).toContain("missing command")
-      expect(plan.message).toContain("gtd decides and prints")
-      expect(plan.message).toContain("gtd install")
-      expect(plan.message).toContain("A complete minimal driver")
+      expect(plan.message).toContain("`gtd help`")
+      expect(plan.message).toContain("gtd guide")
+      expect(plan.stdout).toMatch(/^Usage: gtd <command>/)
+      expect(plan.stdout.split("\n").length).toBeLessThan(10)
     }
   })
 
+  it("an unknown command that looks like a typo names the nearest command", () => {
+    expect(parseArgv(["node", "gtd.js", "nxt"])).toEqual({
+      kind: "usage",
+      stdout: "",
+      message:
+        "gtd: unknown command 'nxt' — did you mean `gtd next`? Run `gtd help` for every command",
+      json: false,
+    })
+  })
+
+  it("an unknown command nothing resembles points at gtd help only", () => {
+    const plan = parseArgv(["node", "gtd.js", "frobnicate"])
+    expect(plan.kind === "usage" && plan.message).toBe(
+      "gtd: unknown command 'frobnicate' — run `gtd help` for every command",
+    )
+  })
+
+  it("a mistyped history subcommand names the nearest one", () => {
+    const plan = parseArgv(["node", "gtd.js", "history", "shwo"])
+    expect(plan.kind === "usage" && plan.message).toContain("did you mean `gtd history show`?")
+  })
+
+  it("a bare --json followed by a word suggests the = form", () => {
+    const plan = parseArgv(["node", "gtd.js", "next", "--json", "kind"])
+    expect(plan.kind === "usage" && plan.message).toBe(
+      "gtd next: too many arguments — expected none, got: kind — to print one field, write --json=kind",
+    )
+  })
+
+  it("an unknown single-dash option is an unknown option, not an extra argument", () => {
+    const plan = parseArgv(["node", "gtd.js", "-j", "next"])
+    expect(plan.kind === "usage" && plan.message).toContain("unknown option '-j'")
+  })
+
   it("an unknown command under --json carries json:true, naming --json's own scope error over the subcommand", () => {
     const plan = parseArgv(["node", "gtd.js", "bogus", "--json"])
     expect(plan.kind).toBe("usage")
@@ -399,43 +431,16 @@ describe("parseArgv — bare/unknown command under --json", () => {
   })
 })
 
-describe("parseArgv — entry/var flag details (formerly parseEntryFlags/takeFlagValues)", () => {
-  it("accepts --workflow=<state> (= form)", () => {
-    const plan = parseArgv(["node", "gtd.js", "--workflow=side-entry"])
-    expect(plan.kind).toBe("command")
-    if (plan.kind === "command") {
-      expect(plan.command).toEqual({
-        kind: "start",
-        actor: "human",
-        workflow: "side-entry",
-        vars: {},
-        label: "gtd --workflow side-entry",
-      })
-    }
-  })
-
-  it("a bare --workflow with no value is a usage error", () => {
-    const plan = parseArgv(["node", "gtd.js", "--workflow"])
-    expect(plan.kind).toBe("usage")
-    if (plan.kind === "usage") expect(plan.message).toContain("--workflow requires a value")
-  })
-
-  it("a second --workflow occurrence is a usage error (not last-wins)", () => {
-    const plan = parseArgv(["node", "gtd.js", "--workflow", "a", "--workflow", "b"])
-    expect(plan.kind).toBe("usage")
-    if (plan.kind === "usage")
-      expect(plan.message).toContain("--workflow may be given at most once")
-  })
-
-  it("a duplicate --var NAME is a usage error", () => {
-    const plan = parseArgv(["node", "gtd.js", "--workflow", "e", "--var", "a=1", "--var", "a=2"])
+describe("parseArgv — --var details", () => {
+  it("a second --var occurrence of one name is a usage error (not last-wins)", () => {
+    const plan = parseArgv(["node", "gtd.js", "start", "e", "--var", "a=1", "--var", "a=2"])
     expect(plan.kind).toBe("usage")
     if (plan.kind === "usage") expect(plan.message).toContain("--var a")
   })
 
   it("a --var name outside the setting-name rule is a usage error naming it", () => {
     for (const raw of ["a b=1", "a-b=1", "1a=1", "a\nb=1"]) {
-      const plan = parseArgv(["node", "gtd.js", "--workflow", "e", "--var", raw])
+      const plan = parseArgv(["node", "gtd.js", "start", "e", "--var", raw])
       expect(plan.kind).toBe("usage")
       if (plan.kind === "usage") {
         expect(plan.message).toContain(
@@ -446,36 +451,25 @@ describe("parseArgv — entry/var flag details (formerly parseEntryFlags/takeFla
   })
 
   it("a multiline --var value is a usage error", () => {
-    const plan = parseArgv(["node", "gtd.js", "--workflow", "e", "--var", "a=1\n2"])
+    const plan = parseArgv(["node", "gtd.js", "start", "e", "--var", "a=1\n2"])
     expect(plan.kind).toBe("usage")
   })
 })
 
 describe("parseArgv — --entry is removed", () => {
-  it("is an ordinary unknown option, with no hint at --workflow", () => {
+  it("is an ordinary unknown option", () => {
     const plan = parseArgv(["node", "gtd.js", "--entry", "fix-precheck"])
     expect(plan.kind).toBe("usage")
-    if (plan.kind === "usage") {
-      expect(plan.message).toContain("--entry")
-      expect(plan.message).not.toContain("--workflow")
-    }
+    if (plan.kind === "usage") expect(plan.message).toContain("--entry")
   })
 })
 
-describe("parseArgv — the --workflow selector", () => {
-  it("gtd --workflow version parses to { kind: start, workflow: version } — the regression this RFC fixes", () => {
-    const plan = parseArgv(["node", "gtd.js", "--workflow", "version"])
-    expect(plan.kind).toBe("command")
-    if (plan.kind === "command") {
-      expect(plan.command).toMatchObject({ kind: "start", workflow: "version" })
-    }
-  })
-
-  it("gtd --workflow help likewise parses to a start command, not the help text", () => {
-    const plan = parseArgv(["node", "gtd.js", "--workflow", "help"])
-    expect(plan.kind).toBe("command")
-    if (plan.kind === "command") {
-      expect(plan.command).toMatchObject({ kind: "start", workflow: "help" })
+describe("parseArgv — gtd start <name>", () => {
+  it("a workflow named like a command word still parses to a start command", () => {
+    for (const name of ["version", "help"]) {
+      const plan = parseArgv(["node", "gtd.js", "start", name])
+      expect(plan.kind).toBe("command")
+      if (plan.kind === "command") expect(plan.command).toMatchObject({ kind: "start", name })
     }
   })
 })
@@ -684,7 +678,7 @@ describe("parseArgv — --verbose / -v (the -v/-V swap)", () => {
       ["land", "--verbose"],
       ["next", "--verbose", "--json"],
       ["check", "qa", "TODO.md", "--verbose"],
-      ["--workflow", "some-state", "--verbose"],
+      ["start", "some-state", "--verbose"],
     ]) {
       const plan = parseArgv(["node", "gtd.js", ...args])
       expect(plan.kind).toBe("command")
@@ -693,30 +687,39 @@ describe("parseArgv — --verbose / -v (the -v/-V swap)", () => {
   })
 })
 
-describe("parseArgv — gtd install", () => {
-  it("parses to an install command", () => {
-    const plan = parseArgv(["node", "gtd.js", "install"])
+describe("parseArgv — gtd guide", () => {
+  it("parses to a guide command", () => {
+    const plan = parseArgv(["node", "gtd.js", "guide"])
     expect(plan.kind).toBe("command")
     if (plan.kind === "command") {
-      expect(plan.command).toEqual({ kind: "install" })
+      expect(plan.command).toEqual({ kind: "guide" })
       expect(plan.json).toEqual({ kind: "off" })
     }
   })
 
-  it("--json is out of scope for install — the briefing is plain text only", () => {
-    const plan = parseArgv(["node", "gtd.js", "install", "--json"])
-    expect(plan.kind).toBe("usage")
-    if (plan.kind === "usage") expect(plan.message).toContain("only valid for `gtd next`")
+  it("install, door and doors are gone: unknown commands", () => {
+    expect(parseArgv(["node", "gtd.js", "install"])).toMatchObject({
+      kind: "usage",
+      message: expect.stringContaining("unknown command 'install'"),
+    })
+    for (const word of ["door", "doors"]) {
+      expect(parseArgv(["node", "gtd.js", word, "fix"])).toMatchObject({
+        kind: "usage",
+        message: expect.stringContaining(`unknown command '${word}'`),
+      })
+    }
+    expect(parseArgv(["node", "gtd.js", "help", "install"]).kind).toBe("usage")
+    expect(renderHelp()).not.toMatch(/^ {2}(install|doors?)\b|--workflow|Older spellings/m)
   })
 
-  it("gtd install extra is a usage error (install takes no argument)", () => {
-    const plan = parseArgv(["node", "gtd.js", "install", "extra"])
+  it("gtd guide extra is a usage error (guide takes no argument)", () => {
+    const plan = parseArgv(["node", "gtd.js", "guide", "extra"])
     expect(plan.kind).toBe("usage")
     if (plan.kind === "usage") expect(plan.message).toContain("too many arguments")
   })
 
-  it("a scoped-out flag (e.g. --port) is rejected on install", () => {
-    const plan = parseArgv(["node", "gtd.js", "install", "--port=3"])
+  it("a scoped-out flag (e.g. --port) is rejected on guide", () => {
+    const plan = parseArgv(["node", "gtd.js", "guide", "--port=3"])
     expect(plan.kind).toBe("usage")
     if (plan.kind === "usage") expect(plan.message).toContain("only valid for `gtd ui`")
   })
@@ -859,7 +862,7 @@ describe("parseArgv — gtd judge run", () => {
     [["judge", "run", "--answers", "a.json"], "--answers is only valid with --provider fixed"],
     [["judge", "run", "--provider", "jev", "--model", "x"], "--model"],
     [["judge", "run", "--provider", "fixed", "--model", "x"], "--model"],
-    [["next", "--model", "x"], "`gtd land` (with --cost) or `gtd judge run`"],
+    [["next", "--model", "x"], "`gtd land` (with --cost: the model to record the cost against)"],
     [["judge", "run", "--provider", "fixed", "--json"], "--json is only valid"],
     [["judge", "run", "--provider", "fixed", "--answers="], "requires a value"],
     [["judge", "--provider", "fixed"], "only valid for `gtd judge run`"],
@@ -872,61 +875,6 @@ describe("parseArgv — gtd judge run", () => {
   })
 })
 
-describe("parseArgv — doors", () => {
-  const parse = (...args: string[]): CliPlan => parseArgv(["node", "gtd.js", ...args])
-
-  it("`gtd door <name>` carries the name and no args", () => {
-    const plan = parse("door", "fix")
-    expect(plan).toMatchObject({
-      kind: "command",
-      command: { kind: "door", name: "fix", args: [] },
-    })
-  })
-
-  it("`gtd door <name> a b` carries every positional after the name, in order", () => {
-    const plan = parse("door", "review", "v1.0", "extra")
-    expect(plan).toMatchObject({
-      kind: "command",
-      command: { kind: "door", name: "review", args: ["v1.0", "extra"] },
-    })
-  })
-
-  it("`gtd door` with no name is a usage error", () => {
-    const plan = parse("door")
-    expect(plan.kind).toBe("usage")
-    if (plan.kind === "usage") expect(plan.message).toContain("gtd door: missing name argument")
-  })
-
-  it("`gtd doors` parses with every --json shape", () => {
-    expect(parse("doors")).toMatchObject({
-      kind: "command",
-      command: { kind: "doors" },
-      json: { kind: "off" },
-    })
-    expect(parse("doors", "--json")).toMatchObject({ json: { kind: "document" } })
-    expect(parse("doors", "--json=0.name")).toMatchObject({
-      json: { kind: "select", path: "0.name" },
-    })
-  })
-
-  it("`gtd doors` takes no argument", () => {
-    const plan = parse("doors", "extra")
-    expect(plan.kind).toBe("usage")
-    if (plan.kind === "usage") expect(plan.message).toContain("too many arguments")
-  })
-
-  it("`gtd door` rejects --json and --var — a door's vars come from its args", () => {
-    expect(parse("door", "fix", "--json").kind).toBe("usage")
-    expect(parse("door", "fix", "--var", "a=1").kind).toBe("usage")
-  })
-
-  it("help lists both commands", () => {
-    const help = renderHelp()
-    expect(help).toContain("door <name> [args...]")
-    expect(help).toMatch(/^ {2}doors\b/m)
-  })
-})
-
 describe("parseArgv — gtd history", () => {
   const parse = (...args: string[]) => parseArgv(["node", "gtd.js", ...args])
   const usage = (plan: CliPlan): string => (plan.kind === "usage" ? plan.message : "")
@@ -953,7 +901,7 @@ describe("parseArgv — gtd history", () => {
     expect(parse("history", "metrics", "a", "feat/b")).toMatchObject({
       command: { kind: "historyMetrics", refs: ["a", "feat/b"] },
     })
-    expect(parse("history", "judges", "a", "--var", "qualityTriageMinP=0.9")).toMatchObject({
+    expect(parse("history", "judges", "a", "--threshold", "qualityTriageMinP=0.9")).toMatchObject({
       command: {
         kind: "historyJudges",
         refs: ["a"],
@@ -966,21 +914,40 @@ describe("parseArgv — gtd history", () => {
     })
   })
 
-  it("judges takes only judge thresholds as --var, and --jsonl alone", () => {
-    expect(usage(parse("history", "judges", "--var", "reviewBase=main"))).toContain(
-      "no judge threshold",
+  it("judges takes only judge thresholds as --threshold, and --jsonl alone", () => {
+    expect(
+      parse(
+        "history",
+        "judges",
+        "--threshold=qualityTriageMinP=0.9",
+        "--threshold",
+        "judgeIdenticalMinP=0.5",
+      ),
+    ).toMatchObject({
+      command: { vars: { qualityTriageMinP: "0.9", judgeIdenticalMinP: "0.5" } },
+    })
+    expect(usage(parse("history", "judges", "--threshold", "reviewBase=main"))).toBe(
+      "gtd history judges: --threshold reviewBase is no judge threshold — use judgeIdenticalMinP or qualityTriageMinP",
     )
-    expect(usage(parse("history", "judges", "--var", "toString=0.9"))).toContain(
+    expect(usage(parse("history", "judges", "--threshold", "toString=0.9"))).toContain(
       "no judge threshold",
     )
-    expect(usage(parse("history", "judges", "--var", "qualityTriageMinP=0,9"))).toContain(
-      "must be a number",
-    )
+    for (const value of ["x", "0,9"]) {
+      expect(usage(parse("history", "judges", "--threshold", `qualityTriageMinP=${value}`))).toBe(
+        `gtd history judges: --threshold qualityTriageMinP must be a number — got "${value}"`,
+      )
+    }
     expect(usage(parse("history", "judges", "--jsonl", "--json"))).toContain("mutually exclusive")
-    expect(usage(parse("history", "judges", "--jsonl", "--var", "qualityTriageMinP=1"))).toContain(
-      "mutually exclusive",
+    expect(
+      usage(parse("history", "judges", "--jsonl", "--threshold", "qualityTriageMinP=1")),
+    ).toContain("mutually exclusive")
+    expect(usage(parse("history", "metrics", "--threshold", "qualityTriageMinP=1"))).toContain(
+      "only valid for `gtd history judges`",
     )
     expect(usage(parse("history", "metrics", "--jsonl"))).toContain("only valid for")
+    const help = helpFor("help", "history", "judges")
+    expect(help).toContain("--threshold <name>=<value>")
+    expect(help).not.toContain("--var")
   })
 
   it("bare history and an unknown subcommand are usage errors naming list, show, metrics, fetch", () => {
@@ -1001,7 +968,7 @@ describe("parseArgv — gtd history", () => {
     expect(usage(parse("history", "fetch", "a", "b"))).toContain("too many arguments")
   })
 
-  it("--json is accepted for list, show and metrics, rejected for fetch", () => {
+  it("--json is accepted for list, show, metrics and fetch", () => {
     expect(parse("history", "list", "--json")).toMatchObject({ json: { kind: "document" } })
     expect(parse("history", "show", "x", "--json=ended")).toMatchObject({
       json: { kind: "select", path: "ended" },
@@ -1009,7 +976,9 @@ describe("parseArgv — gtd history", () => {
     expect(parse("history", "metrics", "--json=total.refactorFirstRate")).toMatchObject({
       json: { kind: "select", path: "total.refactorFirstRate" },
     })
-    expect(parse("history", "fetch", "--json").kind).toBe("usage")
+    expect(parse("history", "fetch", "--json=script")).toMatchObject({
+      json: { kind: "select", path: "script" },
+    })
   })
 
   it("help lists the four history rows", () => {
@@ -1022,6 +991,70 @@ describe("parseArgv — gtd history", () => {
   })
 })
 
+describe("parseArgv — gtd start", () => {
+  const parse = (...args: string[]): CliPlan => parseArgv(["node", "gtd.js", ...args])
+
+  it("bare `gtd start` parses with no name, so the loaded config can list what starts", () => {
+    expect(parse("start")).toEqual({
+      kind: "command",
+      command: { kind: "start", args: [], vars: {} },
+      json: { kind: "off" },
+      verbose: false,
+    })
+    expect(parse("start", "--json")).toMatchObject({ json: { kind: "document" } })
+  })
+
+  it("carries the name, every positional after it, and the --var pins", () => {
+    expect(parse("start", "review", "main", "--var", "a=1", "--var=b=2")).toMatchObject({
+      command: { kind: "start", name: "review", args: ["main"], vars: { a: "1", b: "2" } },
+    })
+  })
+
+  it("--var with no name is a usage error", () => {
+    const plan = parse("start", "--var", "a=1")
+    expect(plan.kind === "usage" && plan.message).toContain("--var needs a <name>")
+  })
+
+  it("its help names doors, workflows, --var and the --json=script idiom", () => {
+    const help = helpFor("help", "start")
+    expect(help).toMatch(/^Usage: gtd start \[name\] \[args\.\.\.\] \[options\]\n/)
+    expect(help).toMatch(/A door\s+shadows a workflow of the same name/)
+    expect(help).toContain("--var <name>=<value>")
+    expect(help).toContain('s=$(gtd start <name> --json=script) && sh -c "$s"')
+  })
+})
+
+describe("parseArgv — -- ends the options", () => {
+  const parse = (...args: string[]): CliPlan => parseArgv(["node", "gtd.js", ...args])
+
+  it("every word after -- is a positional, even one that looks like an option", () => {
+    expect(parse("strays", "a..b", "--", "--weird", "-x")).toMatchObject({
+      command: { kind: "strays", globs: ["--weird", "-x"] },
+    })
+    expect(parse("start", "fix", "--json=script", "--", "--var")).toMatchObject({
+      command: { kind: "start", name: "fix", args: ["--var"], vars: {} },
+      json: { kind: "select", path: "script" },
+    })
+  })
+
+  it("--help, -h, --version and -V after -- are arguments, not short-circuits", () => {
+    expect(parse("start", "fix", "--", "--help")).toMatchObject({
+      command: { kind: "start", args: ["--help"] },
+    })
+    expect(parse("start", "fix", "--", "-V").kind).toBe("command")
+    expect(parse("next", "--", "--version")).toMatchObject({ kind: "usage" })
+  })
+
+  it("a bare -- changes nothing", () => {
+    expect(parse("next", "--")).toEqual(parse("next"))
+  })
+
+  it("an option that needs a value never takes -- as it", () => {
+    const plan = parse("start", "fix", "--var", "--", "a=1")
+    expect(plan.kind === "usage" && plan.message).toContain("--var requires a value")
+  })
+})
+
 describe("parseArgv — gtd strays", () => {
   const strays = (...args: string[]): CliPlan => parseArgv(["node", "gtd.js", "strays", ...args])
 
@@ -1061,20 +1094,21 @@ describe("parseArgv — gtd strays", () => {
     const plan = parseArgv(["node", "gtd.js", "lsp", "--json"])
     if (plan.kind === "usage") expect(plan.message).toContain("`gtd strays`")
     expect(renderHelp()).toContain("strays <range> [glob...]")
-    expect(renderHelp()).toContain("gtd strays only")
+    const help = parseArgv(["node", "gtd.js", "help", "strays"])
+    expect(help.kind === "output" && help.stdout).toContain("--json[=<path>]")
   })
 })
 
 describe("standaloneKinds / needsOf", () => {
   it("pins the standalone kinds", () => {
-    expect(standaloneKinds()).toEqual(["lsp", "check", "uncheck", "install", "judgeRun", "strays"])
+    expect(standaloneKinds()).toEqual(["lsp", "check", "uncheck", "guide", "judgeRun", "strays"])
   })
 
   it("needsOf matches none/fs for the standalone kinds and state for everything else", () => {
     expect(needsOf("lsp")).toBe("none")
     expect(needsOf("check")).toBe("fs")
     expect(needsOf("uncheck")).toBe("fs")
-    expect(needsOf("install")).toBe("none")
+    expect(needsOf("guide")).toBe("none")
     expect(needsOf("judgeRun")).toBe("none")
     expect(needsOf("strays")).toBe("none")
     for (const kind of [
@@ -1087,8 +1121,6 @@ describe("standaloneKinds / needsOf", () => {
       "ui",
       "judge",
       "judgeAnswer",
-      "door",
-      "doors",
       "historyList",
       "historyShow",
       "historyMetrics",
@@ -1100,56 +1132,96 @@ describe("standaloneKinds / needsOf", () => {
   })
 })
 
+const helpFor = (...args: string[]): string => {
+  const plan = parseArgv(["node", "gtd.js", ...args])
+  if (plan.kind !== "output") throw new Error(`no help for ${args.join(" ")}`)
+  return plan.stdout
+}
+
+/** The command names the overview lists — `  name ` lines, as the docs pins read them. */
+const listedCommands = (): string[] =>
+  [...renderHelp().matchAll(/^ {2}([a-z]+(?:-[a-z]+)?(?: [a-z]+)?)(?= )/gm)].map(([, n]) => n!)
+
 describe("renderHelp", () => {
-  it("mentions every command and flag, and no removed surface", () => {
+  it("groups the commands and mentions no removed surface", () => {
     const help = renderHelp()
-    expect(help).toContain("Usage")
-    expect(help).toContain("land")
-    expect(help).toContain("--workflow <name>")
-    expect(help).toContain("--var")
-    expect(help).toContain("abandon")
-    expect(help).toContain("restore")
-    expect(help).toContain("next")
-    expect(help).toContain("validate")
-    expect(help).toContain("lsp")
-    expect(help).not.toContain("visualize")
-    expect(help).not.toMatch(/^ {2}init\b/m)
-    expect(help).not.toContain(".gtdrc")
-    expect(help).toMatch(/^ {2}ui\b/m)
+    for (const heading of ["Core loop:", "Start and stop:", "Inspect:", "Driver plumbing:"]) {
+      expect(help).toContain(`\n${heading}\n`)
+    }
+    expect(help).toContain("start [name] [args...]")
     expect(help).toContain("check <mode> <file>")
-    expect(help).toContain("install")
-    expect(help).toContain("base ")
-    expect(help).toMatch(/^ {2}judge\b/m)
-    expect(help).toContain("judge answer")
-    expect(help).toContain("version")
-    expect(help).toContain("help")
-    expect(help).toContain("--json")
-    expect(help).toContain("--port")
-    expect(help).not.toContain("--no-open")
-    expect(help).toContain("--host")
-    expect(help).toContain("--self-signed")
-    expect(help).toContain("--dev")
-    expect(help).toContain("--cost")
-    expect(help).toContain("--model")
-    expect(help).toContain("--open-questions")
-    expect(help).toContain("--verbose")
-    expect(help).toContain("--version, -V")
-    expect(help).toContain("--help, -h")
-    expect(help).not.toContain("review <commitish>")
-    expect(help).not.toContain("format <file>")
-    expect(help).not.toContain("--debug")
-    expect(help).not.toContain("bin/gtd")
-    expect(help).not.toContain("(no command), loop")
-    expect(help).not.toContain("--dispatch")
-    expect(help).not.toContain("--if-resting")
-    expect(help).not.toMatch(/^ {2}serve\b/m)
+    expect(help).toContain("-V, --version")
+    expect(help).toContain("-h, --help")
+    expect(help).toContain("Examples:")
+    for (const removed of [
+      "--workflow",
+      "Older spellings",
+      "visualize",
+      ".gtdrc",
+      "--no-open",
+      "--debug",
+      "--dispatch",
+      "bin/gtd",
+    ]) {
+      expect(help).not.toContain(removed)
+    }
+    expect(help).not.toMatch(/^ {2}(init|serve|install|door|doors)\b/m)
     expect(help).toMatch(/\n$/)
   })
 
-  it("every flag row's name appears in the Options: block and vice versa", () => {
-    const help = renderHelp()
-    const optionsBlock = help.slice(help.indexOf("Options:"))
-    for (const name of FLAG_NAMES) expect(optionsBlock).toContain(name)
+  it("keeps every line of every help text within 80 columns", () => {
+    for (const text of [renderHelp(), ...listedCommands().map((name) => helpFor("help", name))]) {
+      for (const line of text.split("\n")) expect(line.length, line).toBeLessThanOrEqual(80)
+    }
+  })
+
+  it("names no internals", () => {
+    const all = [renderHelp(), ...listedCommands().map((name) => helpFor("help", name))].join("")
+    for (const internal of ["it.processCost", "refs/worktree/gtd/history", "Effect Schema"]) {
+      expect(all).not.toContain(internal)
+    }
+  })
+
+  it("every flag is in the help of a command it is valid for", () => {
+    const all = [renderHelp(), ...listedCommands().map((name) => helpFor("help", name))].join("")
+    for (const name of FLAG_NAMES) expect(all).toContain(name)
+  })
+
+  it("gtd <cmd> --help, gtd <cmd> -h and gtd help <cmd> print that command's own help", () => {
+    const help = helpFor("help", "land")
+    expect(help).toMatch(/^Usage: gtd land \[options\]\n/)
+    expect(help).toContain("--cost=<n>")
+    expect(help).not.toContain("--port")
+    expect(helpFor("land", "--help")).toBe(help)
+    expect(helpFor("land", "-h")).toBe(help)
+  })
+
+  it("a two-word command's help is its own", () => {
+    expect(helpFor("judge", "run", "--help")).toMatch(/^Usage: gtd judge run \[options\]/)
+    expect(helpFor("help", "history", "show")).toMatch(/^Usage: gtd history show <ref>/)
+  })
+
+  it("a flag that means something else per command is described per command", () => {
+    expect(helpFor("help", "land")).toContain("With --cost: the model")
+    expect(helpFor("help", "land")).toContain("nothing runs on it")
+    expect(helpFor("help", "judge", "run")).toContain("The claude model")
+    expect(helpFor("help", "abandon")).toContain("Print { schema, script }")
+    expect(helpFor("help", "next")).not.toContain("Print { schema, script }")
+  })
+
+  it("--help after an unknown command still prints the overview", () => {
+    expect(helpFor("bogus", "--help")).toBe(renderHelp())
+  })
+
+  it("gtd help <unknown> is a usage error naming the nearest command", () => {
+    const plan = parseArgv(["node", "gtd.js", "help", "lnad"])
+    expect(plan).toEqual({
+      kind: "usage",
+      stdout: "",
+      message:
+        "gtd: help: no command 'lnad' — did you mean `gtd help land`? Run `gtd help` for every command",
+      json: false,
+    })
   })
 
   it("the docs/cli.md Commands fenced block equals renderHelp()", () => {
@@ -1159,6 +1231,15 @@ describe("renderHelp", () => {
     expect(match![1] + "\n").toBe(renderHelp())
   })
 
+  it("docs/cli.md's Every command section is every command's help, in the overview's order", () => {
+    const doc = readFileSync(resolve(import.meta.dirname, "../../docs/cli.md"), "utf8")
+    const section = doc.slice(doc.indexOf("\n## Every command\n"))
+    const documented = [...section.matchAll(/^### `gtd ([^`]+)`\n\n```\n([\s\S]*?)```\n/gm)].map(
+      ([, name, help]) => [name, help],
+    )
+    expect(documented).toEqual(listedCommands().map((name) => [name, helpFor("help", name)]))
+  })
+
   it("README.md and COMPATIBILITY.md list exactly the commands", () => {
     const commands = new Set(
       [...renderHelp().matchAll(/^ {2}([a-z]+(?:-[a-z]+)?(?: [a-z]+)?)(?= )/gm)].map(
@@ -1280,17 +1361,18 @@ describe("runCli — a garbled GTD_FLAG_* value", () => {
 })
 
 describe("runCli — StartFlags", () => {
-  const CONFIG = `import { agent, human } from "@pmelab/gtd/flows"
+  const CONFIG = `import { agent, human, workflow } from "@pmelab/gtd/flows"
 
 export default async () => {
   await human("idle")
 }
 
-export const side = async () => {
-  await agent("working", "w")
-}
-
-export const defaults = { flag_beta: "0" }
+export const side = workflow(
+  async () => {
+    await agent("working", "w")
+  },
+  { defaults: { flag_beta: "0" } },
+)
 `
   const BETA = { name: "beta", owner: "pmelab", expiry: "2099-01-01", kind: "release" } as const
   const start = async (
@@ -1302,7 +1384,7 @@ export const defaults = { flag_beta: "0" }
     repo.seedCommit("chore: add workflow")
     const { io, result } = makeCapturingCliIo(repo, env)
     await Effect.runPromise(
-      runCli(["node", "gtd.js", "--workflow", "side"], { ...io, ...(flags ? { flags } : {}) }),
+      runCli(["node", "gtd.js", "start", "side"], { ...io, ...(flags ? { flags } : {}) }),
     )
     return result().stdout
   }
@@ -1419,7 +1501,7 @@ describe("runCli — stdout stays byte-empty on every failing surface", () => {
     const { stdout, stderr, exitCode } = captured()
     expect(exitCode).toBe(EXIT_RUNTIME_ERROR)
     expect(stdout).toBe("")
-    expect(stderr).toContain("gtd requires a repository with at least one commit")
+    expect(stderr).toContain("gtd: the repository has no commits yet")
   })
 
   it("runtime error: a handler's own Effect.fail (not the shared repo-root/commit guard) leaves stdout byte-empty", async () => {