docs/CLI.md says every `forge` command with one example each, and a test fails when `forge help` lists one it does not #7410

The new docs/CLI.md explains how to drive the forge from a shell on one page, and a new test fails whenever forge help lists a command the page has no section for. The test passes on this branch. With two headings removed, it failed and named exactly those two.

• docs/CLI.md covers installing (bun build --compile), where the config, token and clones live, the variables that override each, and the exit codes 0–4. Then there is one ## forge <command> section per command forge help prints: bare forge, login, logout, whoami, sync, status, ls, pin, unpin and open. It also covers help, ui, --version and --help, which the code accepts but the help text does not list. Each section says what the command does, its flags and one example with its output. The help text and error lines are copied from real runs. The sync and ls tables were drawn by the real printReport and out.table with sample rows, so the column alignment is exact. The other example outputs are the strings src/cli/main.ts prints, with a made-up user and host filled in.
• test/cli-docs.test.ts runs bun src/cli/main.ts help as a separate process, because main writes to the real stdout and a test can't hand it a writer. It reads the commands off the usage lines: a command is one space after forge, so the description on the bare forge line isn't taken for a command. On failure it lists the exact headings to add, e.g. ## forge unpin, which is what other pulls that add commands will see.
• Links: docs/DEVELOP.md links the page in one line. README.md also gets one line in its "Where the rest is" index, because test/readme-front-door.test.ts fails when a top-level doc isn't listed there.

Not done: I left forge help as it is, so it still doesn't print ui, and the test only checks what help lists. The test also checks only that each heading exists, not whether a section's flags or examples are still right.

To try it: bun test test/cli-docs.test.ts, then rename ## forge unpin in docs/CLI.md and run it again. The type check passes, and the 13 test files scripts/fast.ts named for this change pass (165 tests).

🤖 Generated with Claude Code

Closes #7372

The new docs/CLI.md explains how to drive the forge from a shell on one page, and a new test fails whenever forge help lists a command the page has no section for. The test passes on this branch. With two headings removed, it failed and named exactly those two.

• docs/CLI.md covers installing (bun build --compile), where the config, token and clones live, the variables that override each, and the exit codes 0–4. Then there is one ## forge <command> section per command forge help prints: bare forge, login, logout, whoami, sync, status, ls, pin, unpin and open. It also covers help, ui, --version and --help, which the code accepts but the help text does not list. Each section says what the command does, its flags and one example with its output. The help text and error lines are copied from real runs. The sync and ls tables were drawn by the real printReport and out.table with sample rows, so the column alignment is exact. The other example outputs are the strings src/cli/main.ts prints, with a made-up user and host filled in.
• test/cli-docs.test.ts runs bun src/cli/main.ts help as a separate process, because main writes to the real stdout and a test can't hand it a writer. It reads the commands off the usage lines: a command is one space after forge, so the description on the bare forge line isn't taken for a command. On failure it lists the exact headings to add, e.g. ## forge unpin, which is what other pulls that add commands will see.
• Links: docs/DEVELOP.md links the page in one line. README.md also gets one line in its "Where the rest is" index, because test/readme-front-door.test.ts fails when a top-level doc isn't listed there.

Not done: I left forge help as it is, so it still doesn't print ui, and the test only checks what help lists. The test also checks only that each heading exists, not whether a section's flags or examples are still right.

To try it: bun test test/cli-docs.test.ts, then rename ## forge unpin in docs/CLI.md and run it again. The type check passes, and the 13 test files scripts/fast.ts named for this change pass (165 tests).

🤖 Generated with Claude Code

The full gate on land was red; the pull is open again. Red tests:

• every command forge help lists has a heading in docs/CLI.md

The gate's log: /api/v1/repos/trevato/forge/gates/1793136615202-3c2901a4bc79/log

Steward tick: this pull is red on its own merge with current main (gated alone, failed) and was held out of the landing queue so the others can land. Rebase on main, fix the failing test, push - then the hold comes off.

Adds docs/CLI.md, one page on driving the forge from a shell, and a test that fails when forge help lists a command the page has no section for.

docs/CLI.md covers:

• How to install (bun build --compile) and sign in.
• Where the config, token and clones live, and the environment variables that override each.
• The exit codes 0–4.
• One ## forge <command> section per command forge help prints: bare forge, login, logout, whoami, sync, status, ls, pin, unpin, open and asks. Each says what the command does, its flags and one example with its output. help, ui, --version and --help are documented too; the CLI accepts them but forge help doesn't list them.

The help block and error lines are copied from real runs. The sync, ls and asks examples were printed by the CLI's own printReport, out.table and askLines on sample rows, so the columns line up as they do in a terminal. docs/DEVELOP.md links the page in one line. README.md also gets one line in its "Where the rest is" index, because test/readme-front-door.test.ts fails when a top-level doc isn't listed there.

test/cli-docs.test.ts runs bun src/cli/main.ts help as a separate process, because main writes to the real stdout and can't be handed a capturing writer. A command is read from a usage line only when it follows forge after a single space, so the bare forge line's description is not taken for a command. On failure the test lists each heading to add, e.g. ## forge unpin.

After the red gate: main had gained forge asks and forge login --insecure. The gate failed on ## forge asks, which is the failure this test exists for. I merged main into the branch rather than rebasing, because a rebase needs a force push and those are refused here; the gate sees the same tree either way. I then added the ## forge asks section, updated the help block, and described the plain-http refusal and --insecure under login.

Left out: the test checks one direction only, so a section for a removed command still passes. I also didn't add ui to forge help. Both would be a follow-up that changes usage(), as @sentinel noted.

Try it: run bun test test/cli-docs.test.ts. Then rename ## forge asks in docs/CLI.md and run it again: it fails and names that heading. The type check passes, and the 13 test files scripts/fast.ts named for this change pass.

🤖 Generated with Claude Code

This pull adds docs/CLI.md, one section per forge command with what it does, its flags and one example. It also adds test/cli-docs.test.ts, which fails when a command in forge help has no ## forge <command> heading in the doc.

This push merges main again. The README conflict was two lines added in the same spot, the docs/CLI.md entry and main's new docs/features/csv-view.md entry, and both are kept. After the merge the docs test failed, because main had added CLI features the doc didn't cover yet. Those are now documented:

• forge pulls: what each row shows, and that the repository comes from --repo or else the folder's origin when it points at this workbench. Flags: --closed, --json.
• forge ship: shows the pull, asks y/N, then merges. Anything but y prints not shipped. --yes skips the question and is required when there is no terminal to ask on.
• Exit code 5: "refused", added to the exit-code table.
• forge sync: it only sends the token when origin is this workbench over https, or plain http to loopback. Any other origin is fetched without it, and the row says no token sent.

The forge help block in the doc now matches what the command prints. bun x tsc --noEmit is clean, and the 13 test files scripts/fast.ts names pass (165 tests), including test/cli-docs.test.ts.

🤖 Generated with Claude Code