Refine top-level CLI help text (#129)

Author: benvinegar

src/core/cli.ts

@@ -119,22 +119,27 @@ function renderCliHelp() {
     "  hunk session <subcommand>               inspect or control a live Hunk session",
     "  hunk mcp serve                          run the local Hunk session daemon",
     "",
-    "Options:",
+    "Global options:",
     "  -h, --help                              show help",
     "  -v, --version                           show version",
     "",
-    "Examples:",
-    "  hunk diff",
-    "  hunk diff main",
-    "  hunk diff main...feature",
-    "  hunk diff --staged -- src/ui/App.tsx",
-    "  hunk show",
-    "  hunk show HEAD~1",
-    "  hunk show abc123 -- README.md",
-    "  hunk patch -",
-    "  hunk pager",
-    "  hunk session list",
-    "  hunk mcp serve",
+    "Common review options:",
+    "  --mode <mode>                           layout mode: auto, split, stack",
+    "  --watch                                 auto-reload when the current diff input changes",
+    "  --agent-context <path>                  JSON sidecar with agent rationale",
+    "  --pager                                 use pager-style chrome and controls",
+    "  --line-numbers / --no-line-numbers      show or hide line numbers",
+    "  --wrap / --no-wrap                      wrap or truncate long diff lines",
+    "  --hunk-headers / --no-hunk-headers      show or hide hunk metadata rows",
+    "  --agent-notes / --no-agent-notes        show or hide agent notes by default",
+    "  --theme <theme>                         named theme override",
+    "",
+    "Git diff options:",
+    "  --staged, --cached                      review staged changes",
+    "  --exclude-untracked                     hide untracked files in working tree reviews",
+    "",
+    "Notes:",
+    "  Run `hunk <command> --help` for command-specific syntax and options.",
     "",
   ].join("\n");
 }

test/cli.test.ts

@@ -33,7 +33,16 @@ describe("parseCli", () => {
     expect(parsed.text).toContain("Usage:");
     expect(parsed.text).toContain("hunk diff");
     expect(parsed.text).toContain("hunk show");
-    expect(parsed.text).toContain("hunk patch -");
+    expect(parsed.text).toContain("Global options:");
+    expect(parsed.text).toContain("Common review options:");
+    expect(parsed.text).toContain("auto-reload when the current diff input changes");
+    expect(parsed.text).toContain("Git diff options:");
+    expect(parsed.text).toContain("Notes:");
+    expect(parsed.text).toContain(
+      "Run `hunk <command> --help` for command-specific syntax and options.",
+    );
+    expect(parsed.text).not.toContain("Config:");
+    expect(parsed.text).not.toContain("Examples:");
   });
 
   test("prints the same top-level help for --help", async () => {

test/help-output.test.ts

@@ -35,6 +35,16 @@ describe("CLI help output", () => {
     expect(stdout).toContain("Usage:");
     expect(stdout).toContain("hunk diff");
     expect(stdout).toContain("hunk show");
+    expect(stdout).toContain("Global options:");
+    expect(stdout).toContain("Common review options:");
+    expect(stdout).toContain("auto-reload when the current diff input changes");
+    expect(stdout).toContain("Git diff options:");
+    expect(stdout).toContain("Notes:");
+    expect(stdout).toContain(
+      "Run `hunk <command> --help` for command-specific syntax and options.",
+    );
+    expect(stdout).not.toContain("Config:");
+    expect(stdout).not.toContain("Examples:");
     expect(stdout).toContain("hunk pager");
     expect(stdout).toContain("hunk session <subcommand>");
     expect(stdout).toContain("hunk mcp serve");