fix(cli): document the shipped commands and drop a stray backslash

[drawmeanelephant]

Agent Completion Report

• Status: complete
• Branch and Worktree:
  • Branch: t3code/cli-reference-current
  • Worktree: t3code/cli-reference-current (the shared checkout; no separate worktree)
• Commit and PR:
  • Commits: 2061faa3 (the reference and help fixes), 750ec1df (the formatter's output on src/cli.zig)
  • Target PR / Branch: main
• Linked Issues (auto-close convention):
  • None, and deliberately so: this is not a filed card. Both defects were found while reviewing the published GitHub Pages site against the shipped binary rather than from an issue, so nothing is declared kept open and nothing is orphaned by this merge.
• Changed Files:
  • content/reference/commands.md — the published CLI reference
  • src/cli.zig — the usage text and its new test
  • docs/changelog.d/995-cli-reference-current.md — changelog fragment, already named for this PR
• Preserved Unrelated Files:
  • Staged by explicit path only, never git add -A. The separate Author-surface work is committed on t3code/editor-residual-flat-993 and opened as its own PR; this branch carries only the three paths above, and the working tree is clean.
• Implementation Summary: two defects, both confirmed against the shipped binary before being changed.
  • The published CLI reference omitted three shipped commands. content/reference/commands.md opened by describing "six core commands plus the standard-site and nostr families", while boris --help also ships graph, proof verify, and init. proof verify was absent from the page entirely, and every one of the page's nine graph hits was incidental (graph.json, "content, graph, renderer") — the command itself was never documented. That is a bad omission specifically because proof verify is the gate the Pages deploy workflow runs on every publish, so the page documenting the surface was the page missing the check that guards it. Fixed by adding graph, proof verify, and init to the commands-at-a-glance table, replacing the "six core commands" framing with the actual set, adding three sections (Graph renders with --format mermaid|dot; Publication-check policy with --max-errors, --max-warnings, --block-code, noting it is the same gate the Pages workflow runs; and Starter site with init [DIR]), and correcting the exit-code 1 row to include a proof verify policy failure per docs/contracts/cli.md.
  • Every flag documented was verified to exist in src/cli.zig before it was written, rather than taken from the contract prose. The contract already listed all three commands, so the contract was right and the published page was the stale artefact.
  • --help printed a stray backslash. src/cli.zig had a doubled multiline marker on the recipe-scale line where every sibling line has one, so --help literally printed \ recipe-scale in the Modes list. The deeper problem was that nothing read the help text, so no test could ever catch it. The usage string is now a named pub const usage_text, with a test asserting the two properties that would have caught the typo: the text contains no backslash at all, and every shipped command appears in the Modes list.
• Known Gaps:
  • boris graph --help and boris proof verify --help do not print command-specific help; both fall back to the general list, while init --help has its own. That is an inconsistency in the help surface, not drift, so it is left as a design decision rather than folded into this change.
  • docs/STATUS.md still lists "Migration-guide review findings — … four generated-site missing routes" as a live item. The current link audit is clean (exit 0, checks 3/3 passed), so that line looks like stale bookkeeping, but project policy moves STATUS.md only when phase, integration line, or the "what's next" list moves, so it is left for a maintainer rather than changed as a drive-by.
  • The reference page was checked command-by-command against the binary's help output; the other published pages were not re-audited line by line in this change.
• Exact Commands Run:
  1. zig build test
  2. ./zig-out/bin/boris build
  3. ./zig-out/bin/boris --help | grep -c '\\'
  4. zig fmt --check .
  5. git diff --check
  6. ./scripts/check-pr-issue-close.sh --body-file <this body>
• Exact Gate Results:
  • zig build test: pass — including the documentation link walk (1068 links) and the new usage-text test
  • ./zig-out/bin/boris build: pass — 1 target written, checks 3/3 passed, no missing routes
  • ./zig-out/bin/boris --help | grep -c '\\': 0 — the doubled marker is gone
  • dist/reference/commands.html: proof verify now appears 6 times (it appeared 0 times before), and all three new sections are present
  • zig fmt --check .: pass after 750ec1df — this caught a real miss. zig build test does not run the formatter, so my first push failed CI's Format check before it reached Build or Test. Extracting the usage string into a const moved its continuation lines one indent level out and I did not re-run zig fmt. The follow-up commit is the formatter's own output, verified to change no behaviour: boris --help output is byte-identical before and after (14329 bytes).
  • git diff --check: pass — no whitespace errors
  • ./scripts/check-pr-issue-close.sh --body-file: pass
• Determinism Result:
  • The reference page is authored Markdown, so it does not affect compiler output determinism. boris init and proof verify behaviour is unchanged: this change documents them and fixes a help string.
• Generated Artifacts:
  • dist/ and .zig-cache/ (both git-ignored, built for verification)
  • No generated output is staged or committed.
• Blockers and Next Card:
  • Blockers: None.
  • Next Card: boris graph --help and boris proof verify --help fall back to the general usage list. Giving every shipped command its own --help — and a test that asserts each one answers with its own text rather than the fallback — would close the remaining inconsistency in the help surface.

[itoqa]

Commit: 750ec1d: 9 test cases ran, 9 passed ✅.

Summary

Coverage spans product help and documentation behavior, including clean command discovery, rendered reference pages, working links, and publication boundaries. It also exercises happy-path initialization and compilation alongside edge cases such as occupied targets, policy-limit failures, argument-order variations, preserved files, and no unwanted artifacts.

Safe to merge — the exercised behaviors all passed, with no regressions, new failures, or previously flagged PR-attributable failures identified. The change presents low merge risk based on this run.

Tests run by Ito

Result	Severity	Type	Description
✅	—	General	Proof verification succeeds when findings stay within the configured cap. One error over the zero-error cap returns exit 1, prints the policy verdict to stderr, and creates no output artifact.
✅	—	General	Init refuses a non-empty target with status 2 and keeps its existing sentinel file. A missing target creates the starter site and verifies that three pages compile successfully.
✅	—	General	The production command exits successfully from an empty directory and prints the rewritten help text with graph, proof verify, init, standard-site, and nostr commands. The output is clean and does not create publication files.
✅	—	General	The generated Command Reference page shows the graph, proof verify, and init sections with their examples and boundary notes. All checked guide and reference links open successfully.
✅	—	General	Both boris build --help and boris --help build showed the same help text, returned success, and left the empty folder unchanged.
✅	—	General	An empty target receives the starter site and passes the compile check. A non-empty target is refused first, and its existing file stays unchanged.
✅	—	Help	The help command exits successfully and clearly lists all shipped command families, including graph, proof verify, init, standard-site, and nostr. It has no stray backslash and does not require a content tree or create publication artifacts.
✅	—	Help	Running boris --help from an empty directory returned exit code 0 and printed the complete general help document. It did not compile content or create any files.
✅	—	Reference	The published Command Reference shows graph, proof verify, and init with working examples, clear behavior limits, and links to related guides.

Tip

Reply with @itoqa to send us feedback on this test run.

[itoqa]

Ito Diff Report — 750ec1d → a365a6e: 14 test cases ran, 13 passing ✅, 1 additional finding ⚠️.

Diff Summary

Coverage spans core editor flows, connection-state handling, recovery of unsaved work, author/review navigation, responsive layout and design-scale rules, plus command-line help, initialization, and published references. It includes normal use, failure and recovery paths, boundary conditions, rapid state changes, and adversarial checks of documented behavior.

Safe to merge — the only failing behavior is a pre-existing medium-severity connection-recovery issue and is explicitly not attributable to this PR. No PR-related regression or newly introduced failure is indicated; the unrelated issue is a flag for later.

Tests run by Ito

Result	State	Severity	Type	Description
✅	Passing	—	General	When the local host became unavailable, the editor showed the matching warning and full details while keeping the unsaved file content and dirty state intact.
✅	Passing	—	General	Verified acceptable by independent adversarial review: the observed behavior is intended and documented in this codebase. Review notes: The finding treats retained focus and the Graph URL fragment as requiring Graph to remain the scrollspy marker after the user scrolls to the document bottom, but this repository deliberately separates focus hand-off from viewport currency. Its written and tested contract releases the jump marker when Graph no longer covers the reading line and selects the last present pane at maximum scroll, exact…
✅	Passing	—	General	Verified acceptable by independent adversarial review: the scenario cannot be reached through any real application path. Review notes: The finding's forced 503-to-200 health sequence is not a state the production application can produce. A live authenticated host's health route always returns 200, and after an actual host restart the old page points to the prior ephemeral port and carries the prior random token; the repository expressly directs the user to open the new launch URL. The one-way watcher therefore matches the documen…
✅	Passing	—	General	After several quick switches between Author and Review, the editor stayed in Review with the Graph pane open. Reloading kept Review selected, preserved the Graph section in the URL, and kept the source buffer available.
✅	Passing	—	Connection	The header announces a short Connected status and opens the matching full connection sentence when the disclosure is activated with the keyboard.
✅	Passing	—	Connection	Token-missing, host-unavailable, and connected states each showed the right short status and matching full message. Reloading cleared the old detail before the next state was opened.
✅	Passing	—	Density	The editor starts in Author mode with Project and Source emphasized and Review links still available. Switching to Review restores the full working surface and active Review destinations.
✅	Passing	—	Navigation	Verified acceptable by independent adversarial review: the observed behavior is intended and documented in this codebase. Review notes: The finding conflates activation destination with scrollspy currency. The repository explicitly separates focus hand-off from aria-current and states that a clamped Graph jump keeps currency only while Graph covers the reading line; the finding itself says that coverage check is false, at which point selecting Watch under the documented max-scroll rule is intended. The PR did alter surrounding pre…
✅	Passing	—	Navigation	Verified acceptable by independent adversarial review: the observed behavior is intended and documented in this codebase. Review notes: The scenario is reachable, but the claimed inconsistency treats focus/activation state as the contract for aria-current. This repository expressly separates those concepts: Graph may retain focus and the URL after activation, while settled scrollspy currency becomes Watch if a clamped jump leaves Graph off the reading line. The finding never establishes the decisive geometric precondition that Gra…
✅	Passing	—	Recovery	The editor reported that the host was unavailable while keeping the unsaved content and dirty state in place. The expanded connection message matched the warning shown in the editor.
✅	Passing	—	Recovery	A recovery snapshot error was shown while the changed editor content and Unsaved changes state stayed in place.
✅	Passing	—	Rev	The package check passes with the current editor tokens and fails when a new spacing token is added without listing it. Removing the test mutation restores a clean pass, and the repository remains unchanged.
✅	Passing	—	Scale	The editor's type, spacing, corner, and layer scales passed the static gate and six responsive browser checks. The local editor also showed the expected Author mode and section structure.
⏸️	Skipped	—	General	Proof verification succeeds when findings stay within the configured cap. One error over the zero-error cap returns exit 1, prints the policy verdict to stderr, and creates no output artifact.
⏸️	Skipped	—	General	Init refuses a non-empty target with status 2 and keeps its existing sentinel file. A missing target creates the starter site and verifies that three pages compile successfully.
⏸️	Skipped	—	General	The production command exits successfully from an empty directory and prints the rewritten help text with graph, proof verify, init, standard-site, and nostr commands. The output is clean and does not create publication files.
⏸️	Skipped	—	General	The generated Command Reference page shows the graph, proof verify, and init sections with their examples and boundary notes. All checked guide and reference links open successfully.
⏸️	Skipped	—	General	Both boris build --help and boris --help build showed the same help text, returned success, and left the empty folder unchanged.
⏸️	Skipped	—	General	An empty target receives the starter site and passes the compile check. A non-empty target is refused first, and its existing file stays unchanged.
⏸️	Skipped	—	Help	The help command exits successfully and clearly lists all shipped command families, including graph, proof verify, init, standard-site, and nostr. It has no stray backslash and does not require a content tree or create publication artifacts.
⏸️	Skipped	—	Help	Running boris --help from an empty directory returned exit code 0 and printed the complete general help document. It did not compile content or create any files.
⏸️	Skipped	—	Reference	The published Command Reference shows graph, proof verify, and init with working examples, clear behavior limits, and links to related guides.
⚠️	Additional Finding		General	The editor showed Host unavailable after the health check returned HTTP 503. The dirty content and the separate recovery snapshot failed message were preserved, but after the failing routes were removed and a healthy HTTP 200 health response was supplied, the connection stayed Host unavailable instead of changing back to Connected.

Additional Findings Details

These findings are unrelated to the current changes but were observed during testing.

🟡 Editor stays offline after host recovery

• Severity: Medium
• Description: The editor showed Host unavailable after the health check returned HTTP 503. The dirty content and the separate recovery snapshot failed message were preserved, but after the failing routes were removed and a healthy HTTP 200 health response was supplied, the connection stayed Host unavailable instead of changing back to Connected.
• Impact: After the editor host recovers, users may still see it as unavailable and be unable to use the normal connected workflow. Reloading the editor restores access, and unsaved edits remain safe.
• Steps to Reproduce:
  1. Open the editor with content/index.md and change the file without saving it.
  2. Make the health check return host_unavailable and make the recovery snapshot request return snapshot_failed.
  3. Confirm that Host unavailable, the recovery snapshot failure, and the unsaved marker are visible.
  4. Restore healthy health responses and wait for the periodic host check.
  5. Observe that the connection remains Host unavailable instead of returning to Connected.
• Stub / mock content: The test used browser-level local responses for the health and recovery endpoints, plus a local editor session token. No production systems or customer data were used.
• Code Analysis: The production path confirms the retry defect. In editor/ui/src/App.svelte:328-341, startHostWatch schedules watchHost every five seconds, and watchHost only calls noteHostUnavailable when the /api/health response is not OK. For an OK response it returns without calling markConnected, applyHealth, or any equivalent recovery transition. noteHostUnavailable at editor/ui/src/App.svelte:343-348 writes the Host unavailable state, but there is no inverse operation in the watcher, so connection.status remains the detail-backed unavailable state after health is restored. The initial connect path at editor/ui/src/App.svelte:102-163 can call markConnected, but it runs only during initial startup and is not reused by the periodic watcher. The state writer in editor/ui/src/lib/state/connection.svelte.ts:26-38 already provides the correct Connected summary/detail pair, so the targeted fix is to have a successful watch response update that pair, ideally using the response editor_id and a short watch-start timestamp or a dedicated connected transition, while preserving the dirty buffer. The current recovery failure branch in editor/ui/src/lib/state/buffer.svelte.ts:209-229 correctly leaves the buffer untouched and is not the cause of the retry failure. The PR diff changes the status-pair writer and the unavailable-state guard in App.svelte and buffer.svelte.ts, but it does not add or remove the missing successful branch in watchHost; the defective retry behavior is therefore not directly introduced by this PR.

Evidence Package

• text/BF-FAIL-1/BF-FAIL-1-retry-evidence.md — 5 KB

Tip

Reply with @itoqa to send us feedback on this test run.