docs: correct stale facts and fill gaps across hunk.dev docs

[benvinegar]

Problem

An audit of all 29 hunk.dev docs pages against the source turned up three kinds of problem:

• The first-run agent workflow doesn't work as written. Agent notes are hidden by default (showAgentNotes: false). Neither the "Review with an agent" page nor the bundled hunk-review skill says so. A user who follows the walkthrough, or an agent that adds a note without --focus, ends up with notes the user never sees.
• Shipped commands are missing from the reference. hunk log shipped in 0.22 but is still hidden by a leftover publicDocs: false. The generator never walks the bundled hunk gh extension command.
• Facts are stale or wrong, for example:
  • extension API version (28 vs 31)
  • extension trust-state path (pre-XDG)
  • Windows config paths
  • pager/difftool undo, which left a broken diff.tool
  • jj hunk diff <revset> semantics
  • the VCS adapter detect sample, which fails from subdirectories

Changes

Code and generated output

• packages/hunk/src/app/cli.ts:
  • hunk log is now public.
  • Its positional is [target] everywhere; the metadata said [revision-expression] and Commander said [revision].
  • Its summary no longer reads as marketing.
• packages/hunk-gh/src/help.ts: hunk gh help is now structured GITHUB_CLI_REFERENCE metadata. hunk gh --help, registerCliCommand, and the docs generator all read it.
• scripts/generate/generate-docs.ts renders a hunk gh section with:
  • usage for pr / commit / compare
  • the --repo option
  • the auth variables
  • the accepted argument forms
• A new test in generate-docs.test.ts parses the real hunk --help and fails if any listed command lacks a section in cli.md.
• hunk gh --help now lists its options and GH_TOKEN / GITHUB_TOKEN. gh commit --help and gh compare --help gain the token line.
• packages/hunk/src/hunk-review/skillDocument.ts: the skill tells agents that notes start hidden, to --focus their first note, and what each comment list --type value means. Skill output regenerated.
• The config reference's [pager] example now shows mode = "unified" instead of menu_bar = false, which is already the pager default. It also says that [pager] applies to --pager and that hunk pager matches [patch]. The configuration guide changes the same way, and the test that runs the guide's TOML examples is updated to match.

Docs pages

• Agents:
  • Skill setup is rewritten around npx skills add modem-dev/hunk -g --skill hunk-review, with hunk skill show as the fallback.
  • The pages now explain how to show notes (a, --agent-notes, --focus).
  • New content:
    • the sidecar JSON schema, with field tables
    • a glossary of note kinds
    • replies and the human-to-agent notes loop
    • the --type values
    • daemon security and environment variables
    • a step-by-step fix after upgrading Hunk
• Start:
  • Quick start covers the skill install and the hidden notes.
  • Keyboard: fixed ↑/↓ (they move the current line), the c anchor, and the / rebind consequence. Added selection, copy, and note keys plus the OSC 52 copy note.
• Workflows:
  • Pager/difftool undo now removes everything it added; Windows falls back to more.
  • Per-VCS show defaults, and the two-revision diff form.
  • jj semantics and repository-scoped vcs placement.
  • The watch requirements, plus where to put watch = true. A top-level watch = true also applies to hunk pager and hunk patch -, which then fail.
• Configure: the [pager] → [patch] relationship, the 0/1/2 layout key mapping, and corrected transparency wording.
• Extend:
  • API version 31, with the version history as a table instead of one run-on paragraph.
  • The trust state path.
  • A detect sample that walks up the tree and typechecks.
  • A note that hunk.log() output is not displayed yet.
• Help:
  • Windows paths table and the published platform/architecture matrix.
  • Troubleshooting for watch, daemon mismatch, and port conflicts.
• Install and README: the platform matrix, what HUNK_INSTALL_DIR holds, and the README's agent setup and config path. packages/hunk/README.md is kept identical to the root README.
• Moved: help/deployment.md (the Vercel runbook and hunk-web cutover) is out of the user sidebar and now lives at docs/website-deployment.md. Its contradictions are fixed and it now lists /install.sh, /changelog/, and /compare/.

Non-goals and follow-ups

This pass only corrects facts and fixes the broken agent flow. It is the first slice of the audit; follow-ups:

• New guide pages: hunk gh, hunk log, hunk status, hunk open, uninstall and shell completions.
• New generated references: the full keybinding table and an environment-variable reference.
• CLI reference restructuring: examples, arguments, and exit codes.
• Code issues to file separately:
  • A top-level watch = true breaks hunk pager. Documented here, behavior unchanged.
  • hunk.log() output is never displayed.
  • hunk extension list doesn't print npm extension ids.
  • Invalid enum/boolean config values and unknown keys are silently ignored.

Validation

• bun run check:docs, bun run typecheck, bun run lint, bun run deps:check: pass.
• bun run format:check: passes on the committed files.
• bun run website:check, bun run website:build, bun run website:links: pass (64 pages). Every new in-page anchor resolves in the built output.
• bun test scripts/generate packages/hunk-gh packages/hunk/src/app/cli.test.ts packages/hunk/src/hunk-review: 366 pass, 0 fail.
• The new detect sample typechecks against the real hunkdiff/extension types.
• Config claims checked against resolveConfiguredCliInput: a top-level watch = true reaches pager input, and a config-layer menu_bar overrides the pager's default.
• bun run test has 73 failures:
  • This change: one, scripts/generate/config-examples.test.ts, which still expected the old pager example. Fixed in this PR.
  • Already on main: every other failure also fails on a clean main checkout (ae34231) when the same files run on their own, file for file with identical counts. The files:
    • filesystemSource*.test.ts, controller.filesystem.test.ts, core/watch/observer.fs.test.ts
    • extensions/{hostRuntimeModules,installedPackageResolution,startup}.test.ts
    • AppHost.{extension-dialogs,extension-navigation,extension-sidebar,reload,workspace}.test.tsx
    • test/cli/log.test.ts
  • My machine: the log.test.ts failures come from a locally installed user extension (~/.config/hunk/extensions/installed/hunk-diff-context) whose load warning ends up on stderr.
  • observer.fs.test.ts is flaky: 8–9 failures on both branches.
• Not run: PTY/TTY smoke suites (no rendering changes) and Windows.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
hunk-web	Ready	Preview	Oct 14, 2026 12:05pm UTC

[greptile-apps]

Confidence Score: 4/5

[Low impact] Documentation and help text corrections across the site.

The PR appears safe to merge, with one non-blocking correction to the extension API guidance.

Findings

1.  Version check happens when loading ▶

Fix with agent prompt

### Issue 1
website/src/content/docs/docs/extend/extension-api.md:10
The new `apiVersion` guidance says older Hunk versions refuse to install the extension, but the check runs when Hunk loads it. Installation can succeed while the extension remains unavailable. Change “refuses to install it” to “refuses to load it” so authors know when the requirement takes effect.

```suggestion
The API generation this Hunk speaks (currently `31`). Branch on it if you want one file to support several Hunk versions, or declare `"hunk": {"apiVersion": N}` in a folder extension's `package.json` so an older Hunk refuses to load it.
```

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

This PR updates the docs and bundled agent guidance, adds hunk log and hunk gh to the CLI reference, and shares GitHub help metadata between the CLI and generator.

• Agent guides show how hidden notes fit into a live review.
• The CLI reference now covers hunk log and hunk gh.
• Workflow and config guides spell out pager, VCS, and watch behavior.
• Setup and keyboard guides give readers corrected platform and shortcut details.
• Extension guides describe the current API and where extensions find repository details.
• The website deployment runbook now lives outside the user docs sidebar.

Acknowledged by benvinegar: top-level watch = true breaking stdin reviews, undisplayed hunk.log() output, missing npm extension IDs in hunk extension list, and silently ignored invalid config values are known follow-ups. Moving the deployment runbook out of the public sidebar is intentional.

_{Reviews (1) · Last reviewed commit: "docs: correct stale facts and fill gaps ..." · Reviewed by Greptile}

[greptile-apps]

Version check happens when loading

The new apiVersion guidance says older Hunk versions refuse to install the extension, but the check runs when Hunk loads it. Installation can succeed while the extension remains unavailable. Change “refuses to install it” to “refuses to load it” so authors know when the requirement takes effect.

Suggested change

	The API generation this Hunk speaks (currently `31`). Branch on it if you want one file to support several Hunk versions, or declare `"hunk": {"apiVersion": N}` in a folder extension's `package.json` so an older Hunk refuses to install it.
	The API generation this Hunk speaks (currently `31`). Branch on it if you want one file to support several Hunk versions, or declare `"hunk": {"apiVersion": N}` in a folder extension's `package.json` so an older Hunk refuses to load it.

Prompt To Fix With AI

This is a comment left during a code review.
Path: website/src/content/docs/docs/extend/extension-api.md
Line: 10

Comment:
**Version check happens when loading**

The new `apiVersion` guidance says older Hunk versions refuse to install the extension, but the check runs when Hunk loads it. Installation can succeed while the extension remains unavailable. Change “refuses to install it” to “refuses to load it” so authors know when the requirement takes effect.

```suggestion
The API generation this Hunk speaks (currently `31`). Branch on it if you want one file to support several Hunk versions, or declare `"hunk": {"apiVersion": N}` in a folder extension's `package.json` so an older Hunk refuses to load it.
```

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[benvinegar]

Good catch — the check lives in host.ts (describeApiVersionRefusal) and runs at load time; install doesn't check the version. Changed this line to "refuses to load it with a clear message", and fixed the same claim in extensions.md's publishing steps (46c6b0c).

_{Responded by Claude Code using claude-opus-5-5.}

[benvinegar]

Rebased onto main (ab30039) and force-pushed.

• Conflict: one, in configure/layout-and-display.md. I kept main's auto_split_min_width wording from Auto width threshold #1170 instead of this branch's "120 columns" line. The PR description no longer mentions the 120-column threshold.
• New commit: 46c6b0c addresses Greptile's review: apiVersion is enforced when Hunk loads an extension, not when it installs one.
• Checks after rebase: check:docs, typecheck, lint, format:check, deps:check, website:build, and website:links all pass. The targeted tests pass too (366 pass).