Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

Docs: Add explanation of command documentation generation

Maximilian Roosdb0e998e3d96
diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md
index 985ebbd15..1f9428e5d 100644
--- a/docs/CLAUDE.md
+++ b/docs/CLAUDE.md
@@ -92,3 +92,42 @@ When adding new positioned elements:
- Use the layout variables rather than hardcoding pixel values
- Test anchor navigation to verify no visual jumps
- Check both with and without page scroll
+
+## Command Documentation
+
+Command pages (e.g., `switch.md`, `merge.md`) are **generated from the CLI source code**.
+
+### Generation Mechanism
+
+Each command page is generated by running:
+
+```bash
+wt <command> --help-page > docs/content/<command>.md
+```
+
+The output combines:
+1. **Zola frontmatter** - title, weight, group metadata
+2. **Conceptual documentation** - from `after_long_help` in `src/cli.rs`
+3. **Command Reference section** - the standard `--help` output
+
+### Editing Command Docs
+
+**To update command documentation, edit `src/cli.rs`**, not the markdown files directly.
+
+- **Conceptual content** - Edit the `after_long_help` attribute on the command
+- **Usage/options/examples** - Edit the clap attributes (`about`, `long_about`, doc comments on args)
+
+After editing, regenerate the affected page(s):
+
+```bash
+wt switch --help-page > docs/content/switch.md
+wt merge --help-page > docs/content/merge.md
+# etc.
+```
+
+**Note:** Unlike inline `--help-md` snippets (which are auto-synced by `readme_sync.rs`), command pages require manual regeneration. There's no test that verifies they're in sync.
+
+The generated files contain this warning comment:
+```html
+<!-- ⚠️ AUTO-GENERATED from `wt <command> --help-page` — edit cli.rs to update -->
+```