Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
Standardize doc headings to sentence case (#89)
Maximilian Roosb4d026822f0d
diff --git a/README.md b/README.mdindex 867c41584..7443d681a 100644--- a/README.md+++ b/README.md@@ -521,7 +521,7 @@ wt switch --create hotfix --base productionFor interactive selection, use [`wt select`](@/select.md).-### Creating Worktrees+### Creating worktreesWith `--create`, worktrunk:@@ -552,7 +552,7 @@ wt switch ^ # Main worktreewt switch --create fix --base=@ # Branch from current HEAD```-### Path-First Lookup+### Path-first lookupArguments resolve by checking the filesystem before git branches:@@ -564,7 +564,7 @@ Arguments resolve by checking the filesystem before git branches:- `wt switch foo` → switches to `repo.foo/` (the `bar` worktree)- `wt switch bar` → also works (branch lookup finds same worktree)-### See Also+### See also- [wt select](@/select.md) — Interactive worktree selection- [wt list](@/list.md) — View all worktrees@@ -679,7 +679,7 @@ wt merge --no-commitUse `--no-commit` to skip steps 1-3 and only run hooks and push. Requires a clean working tree and `--no-remove`.-### See Also+### See also- [wt step](@/step.md) — Run individual merge steps (commit, squash, rebase, push)- [wt remove](@/remove.md) — Remove worktrees without merging@@ -756,19 +756,19 @@ Force-delete an unmerged branch:wt remove -D experimental```-### Branch Cleanup+### Branch cleanupBranches delete automatically when their content is already in the target branch (typically main). This works with squash-merge and rebase workflows where commit history differs but file changes match.Use `-D` to force-delete unmerged branches. Use `--no-delete-branch` to keep the branch.-### Background Removal+### Background removalRemoval runs in the background by default (returns immediately). Logs are written to `.git/wt-logs/{branch}-remove.log`. Use `--no-background` to run in the foreground.Arguments resolve by path first, then branch name—see [wt switch](@/switch.md#path-first-lookup). Shortcuts: `@` (current), `-` (previous), `^` (main worktree).-### See Also+### See also- [wt merge](@/merge.md) — Remove worktree after merging- [wt list](@/list.md) — View all worktrees@@ -887,7 +887,7 @@ The CI column shows GitHub/GitLab pipeline status:Any CI dot appears dimmed when there are unpushed local changes (stale status).-### Status Symbols+### Status symbolsSymbols appear in the Status column in this order:@@ -914,7 +914,7 @@ Symbols appear in the Status column in this order:Rows are dimmed when the branch has no marginal contribution (`≡` matches main or `_` no commits).-### JSON Output+### JSON outputQuery structured data with `--format=json`:@@ -944,7 +944,7 @@ wt list --format=json | jq '.[] | select(.status.main_divergence == "Ahead")'- `is_current` — Current directory- `is_previous` — Previous worktree from [wt switch](@/switch.md)-### See Also+### See also- [wt select](@/select.md) — Interactive worktree picker with live preview@@ -1007,7 +1007,7 @@ Show current configuration and file locations:wt config show```-### Shell Integration+### Shell integrationShell integration allows Worktrunk to change the shell's working directory after `wt switch`. Without it, commands run in a subprocess and directory changes don't persist.@@ -1024,7 +1024,7 @@ eval "$(wt config shell init zsh)"wt config shell init fish | source```-### Configuration Files+### Configuration files**User config** — `~/.config/worktrunk/config.toml` (or `$WORKTRUNK_CONFIG_PATH`):@@ -1034,7 +1034,7 @@ Personal settings like LLM commit generation, path templates, and default behaviProject-specific hooks: post-create, post-start, pre-commit, pre-merge, post-merge. See [Hooks](@/hooks.md) for details.-### LLM Commit Messages+### LLM commit messagesWorktrunk can generate commit messages using an LLM. Enable in user config:@@ -1128,7 +1128,7 @@ wt step push- `pre-merge` — Before pushing to target- `post-merge` — After merge cleanup-### See Also+### See also- [wt merge](@/merge.md) — Runs commit → squash → rebase → hooks → push → cleanup automaticallydiff --git a/docs/CLAUDE.md b/docs/CLAUDE.mdindex 9e3fb4be6..a9a602128 100644--- a/docs/CLAUDE.md+++ b/docs/CLAUDE.md@@ -1,6 +1,6 @@# Docs Site-## Demo GIF Workflow+## Demo GIF workflowSee `dev/wt-demo/CLAUDE.md` for the full workflow. Quick reference:@@ -23,7 +23,7 @@ This is an initial scaffolding of the documentation site. The content was auto-gThis is being merged to enable iteration, not as finished documentation.-## Development Workflow+## Development workflowWhen making changes to the docs, **ensure the dev server is running before returning to the user** so they can review changes in their browser.@@ -34,7 +34,7 @@ cd docs && zola serveIf the server isn't already running, start it as a background process or in a separate terminal session before completing work. The user should be able to immediately see rendered changes without needing to manually start the server.-### Visual Review Requirement+### Visual review requirement**Always verify changes visually before returning to the user.** Use Playwright MCP (or similar browser automation) to:@@ -57,7 +57,7 @@ Common issues to check:View changes: http://127.0.0.1:1111```-## Theme Architecture+## Theme architectureThe docs use a "warm workbench" theme built on top of the Juice Zola theme. Key files:@@ -69,7 +69,7 @@ The docs use a "warm workbench" theme built on top of the Juice Zola theme. Key| `templates/index.html` | Homepage hero and animations || `templates/page.html` | Doc page TOC rendering |-### Layout System+### Layout systemThe sticky header and TOC use **definitional CSS variables** so positions are always in sync:@@ -83,7 +83,7 @@ Anchor scroll-margin: same calculationWhen either variable changes (including via media queries), all dependent values update automatically. This prevents the TOC from "jumping" when transitioning to sticky mode.-### Key Technical Decisions+### Key technical decisions1. **`box-sizing: border-box` on header** - Border is included in height, simplifying calculations2. **`scrollbar-gutter: stable`** - Reserves scrollbar space to prevent layout shift on navigation@@ -91,25 +91,25 @@ When either variable changes (including via media queries), all dependent values4. **Logo preload** - Prevents flash when navigating between pages5. **WCAG AA colors** - `--wt-color-text-soft` is #78716a for 4.5:1 contrast-### Responsive Breakpoints+### Responsive breakpointsVariables are overridden in media queries to maintain definitional correctness:- **≤1024px**: `--wt-main-padding-top: 30px`- **≤768px**: `--wt-header-height: 50px`, `--wt-main-padding-top: 20px`, TOC hidden-### Extending the Theme+### Extending the themeWhen 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 documentationCommand pages (e.g., `switch.md`, `merge.md`, `list.md`) are **generated from the CLI source code**. The **entire file** is generated — manual edits will be overwritten.-### Generation Mechanism+### Generation mechanismEach command page is generated by running:@@ -122,7 +122,7 @@ The output combines:2. **Conceptual documentation** — from `after_long_help` in `src/cli.rs`3. **Command Reference section** — the standard `--help` output-### Editing Command Docs+### Editing command docs**To update command documentation, edit `src/cli.rs`**, not the markdown files directly.@@ -135,7 +135,7 @@ After editing, run the sync test (which auto-updates out-of-sync pages):cargo test --test integration test_command_pages_are_in_sync```-### Example Output Expansion (wt list)+### Example output expansion (wt list)The `wt list` examples use **HTML comments + code blocks** that expand to full snapshot output. In `cli.rs`, you write:@@ -178,7 +178,7 @@ This renders differently in each context:The examples in `cli.rs` are just command stubs — the actual output comes from snapshots generated by integration tests. This ensures docs always match real CLI behavior.-### CLI and Web Compatibility+### CLI and web compatibilityContent in `after_long_help` must work in **both** the terminal (`--help`) and the web docs:@@ -187,7 +187,7 @@ Content in `after_long_help` must work in **both** the terminal (`--help`) and t- **Code blocks** — Work in both- **Raw HTML** — Avoid. Renders as raw text in terminal help.-### Post-Processing for Web Docs+### Post-processing for web docsThe `--help-page` generator in `src/main.rs` applies post-processing to transform CLI-friendly content into web-friendly HTML:diff --git a/docs/content/advanced.md b/docs/content/advanced.mdindex ae39df48c..17b6238d3 100644--- a/docs/content/advanced.md+++ b/docs/content/advanced.md@@ -8,7 +8,7 @@ group = "Reference"Most Worktrunk users get everything they need from `wt switch`, `wt list`, `wt merge`, and `wt remove`. The features below are optional power-user capabilities.-## Claude Code Integration+## Claude Code integrationWorktrunk includes a Claude Code plugin for tracking agent status across worktrees.@@ -51,7 +51,7 @@ $ wt config var set marker "✅" --branch feature # Specific branch$ git config worktrunk.marker.feature "💬" # Direct git config```-## Statusline Integration+## Statusline integration`wt list statusline` outputs a single-line status for shell prompts, starship, or editor integrations.[^1]@@ -76,7 +76,7 @@ Add to `~/.claude/settings.json`:}```-## Interactive Worktree Picker+## Interactive worktree picker`wt select` opens a fuzzy-search worktree picker with diff preview (Unix only).diff --git a/docs/content/config.md b/docs/content/config.mdindex 4f754d2b1..217a4f6f8 100644--- a/docs/content/config.md+++ b/docs/content/config.md@@ -30,7 +30,7 @@ Show current configuration and file locations:wt config show```-## Shell Integration+## Shell integrationShell integration allows Worktrunk to change the shell's working directory after `wt switch`. Without it, commands run in a subprocess and directory changes don't persist.@@ -47,7 +47,7 @@ eval "$(wt config shell init zsh)"wt config shell init fish | source```-## Configuration Files+## Configuration files**User config** — `~/.config/worktrunk/config.toml` (or `$WORKTRUNK_CONFIG_PATH`):@@ -57,7 +57,7 @@ Personal settings like LLM commit generation, path templates, and default behaviProject-specific hooks: post-create, post-start, pre-commit, pre-merge, post-merge. See [Hooks](@/hooks.md) for details.-## LLM Commit Messages+## LLM commit messagesWorktrunk can generate commit messages using an LLM. Enable in user config:@@ -70,7 +70,7 @@ See [LLM Commits](@/llm-commits.md) for installation, provider setup, and custom----## Command Reference+## Command reference<!-- ⚠️ AUTO-GENERATED from `wt config --help-page` — edit cli.rs to update -->diff --git a/docs/content/configuration.md b/docs/content/configuration.mdindex 890e3bc65..0c5cc3339 100644--- a/docs/content/configuration.md+++ b/docs/content/configuration.md@@ -13,7 +13,7 @@ Worktrunk uses two configuration files:| **User config** | `~/.config/worktrunk/config.toml` | Personal settings, command defaults, approved project commands || **Project config** | `.config/wt.toml` | Lifecycle hooks, checked into version control |-## User Config+## User configThe user config stores personal preferences that apply across all repositories. Create it with:@@ -23,7 +23,7 @@ wt config createThis creates `~/.config/worktrunk/config.toml` with documented examples. View the current configuration with `wt config show`.-### Worktree Path Template+### Worktree path templateControls where new worktrees are created. The template is relative to the repository root:@@ -42,7 +42,7 @@ worktree-path = "../worktrees/{{ main_worktree }}/{{ branch }}"- `{{ main_worktree }}` — main worktree directory name- `{{ branch }}` — branch name (slashes replaced with dashes)-### Command Defaults+### Command defaultsOverride default flag behavior for commands. Settings here apply unless explicitly overridden on the command line.@@ -73,7 +73,7 @@ remove = false # --no-remove: keep worktree after mergeverify = false # --no-verify: skip project hooks```-### LLM Commit Messages+### LLM commit messagesConfigure automatic commit message generation. Requires an external tool like [llm](https://llm.datasette.io/):@@ -85,7 +85,7 @@ args = ["-m", "claude-haiku-4.5"]See [LLM Commit Messages](@/llm-commits.md) for setup details and template customization.-### Approved Commands+### Approved commandsWhen project hooks run for the first time, Worktrunk prompts for approval. Approved commands are saved here automatically:@@ -99,7 +99,7 @@ approved-commands = [Manage approvals with `wt config approvals list` and `wt config approvals clear <repo>`.-## Project Config+## Project configThe project config defines lifecycle hooks — commands that run at specific points during worktree operations. This file is checked into version control and shared across the team.@@ -116,7 +116,7 @@ lint = "npm run lint"See [Hooks](@/hooks.md) for complete documentation on hook types, execution order, and template variables.-## Shell Integration+## Shell integrationWorktrunk needs shell integration to change directories when switching worktrees. Install with:@@ -136,7 +136,7 @@ wt config shell init fish | sourceWithout shell integration, `wt switch` prints the target directory but cannot `cd` into it.-## Environment Variables+## Environment variablesAll user config options can be overridden with environment variables using the `WORKTRUNK_` prefix.diff --git a/docs/content/faq.md b/docs/content/faq.mdindex 6f83792d2..3be2fd952 100644--- a/docs/content/faq.md+++ b/docs/content/faq.md@@ -41,7 +41,7 @@ Use `--force` to bypass prompts (useful for CI/automation).## How does Worktrunk compare to alternatives?-### vs. Branch Switching+### vs. branch switchingBranch switching uses one directory, so only one agent can work at a time. Worktrees give each agent its own directory.diff --git a/docs/content/hooks.md b/docs/content/hooks.mdindex 3a1a97522..9c6c100b3 100644--- a/docs/content/hooks.md+++ b/docs/content/hooks.md@@ -8,7 +8,7 @@ group = "Reference"Hooks automate setup and validation at worktree lifecycle events. They're defined in `.config/wt.toml` (project config) and run automatically during `wt switch --create` and `wt merge`.-## Hook Types+## Hook types| Hook | When | Blocking? | Fail-Fast? | Execution ||------|------|-----------|------------|-----------|@@ -21,23 +21,23 @@ Hooks automate setup and validation at worktree lifecycle events. They're define**Blocking**: Command waits for hook to complete before continuing.**Fail-fast**: First failure aborts the operation.-## Configuration Formats+## Configuration formatsAll hooks support three formats in `.config/wt.toml`:-### Single Command (String)+### Single command (string)```tomlpost-create = "npm install"```-### Multiple Commands (Array)+### Multiple commands (array)```tomlpost-create = ["npm install", "npm run build"]```-### Named Commands (Table)+### Named commands (table)```toml[post-create]@@ -63,11 +63,11 @@ Named commands appear in output with their labels:<!-- END AUTO-GENERATED -->-## Template Variables+## Template variablesHooks can use template variables that expand at runtime:-### Basic Variables (All Hooks)+### Basic variables (all hooks)- `{{ repo }}` — Repository name (e.g., "my-project")- `{{ branch }}` — Branch name (slashes replaced with dashes)@@ -76,14 +76,14 @@ Hooks can use template variables that expand at runtime:- `{{ repo_root }}` — Absolute path to the repository root- `{{ default_branch }}` — Default branch name (e.g., "main")-### Git Variables (All Hooks)+### Git variables (all hooks)- `{{ commit }}` — Current HEAD commit SHA (full 40-character hash)- `{{ short_commit }}` — Current HEAD commit SHA (short 7-character hash)- `{{ remote }}` — Primary remote name (e.g., "origin")- `{{ upstream }}` — Upstream tracking branch (e.g., "origin/feature"), if configured-### Merge Variables (pre-commit, pre-merge, post-merge)+### Merge variables (pre-commit, pre-merge, post-merge)- `{{ target }}` — Target branch for the merge (e.g., "main")@@ -95,7 +95,7 @@ post-create = "echo '{{ short_commit }}' > .version"pre-merge = "echo 'Merging {{ branch }} into {{ target }}'"```-## Hook Details+## Hook details### post-create@@ -181,7 +181,7 @@ post-merge = "cargo install --path ."- Runs after push succeeds, before cleanup- Failures show errors but cleanup proceeds-## Execution Order During Merge+## Execution order during mergeThe complete sequence when running `wt merge`:@@ -196,7 +196,7 @@ The complete sequence when running `wt merge`:9. **Run `post-merge`** — best-effort, failures logged10. Clean up (delete branch, remove worktree)-## Security & Approval+## Security & approvalProject commands require approval on first run. When a project defines hooks, the first execution prompts for approval:@@ -231,7 +231,7 @@ wt config approvals list # Show all approvalswt config approvals clear <repo> # Remove approvals for a repo```-## Skipping Hooks+## Skipping hooksUse `--no-verify` to skip all project hooks:@@ -251,7 +251,7 @@ Background operations log to `.git/wt-logs/` in the main worktree:Logs overwrite on repeated runs for the same branch/operation. Stale logs from deleted branches persist but are bounded by branch count.-## Running Hooks Manually+## Running hooks manuallyUse `wt step` to run individual hooks:@@ -261,7 +261,7 @@ wt step pre-merge # Run pre-merge hookswt step post-merge # Run post-merge hooks```-## Example Configurations+## Example configurations### Node.js / TypeScript@@ -343,9 +343,9 @@ backend-tests = "cd backend && cargo test"integration = "./scripts/integration-tests.sh"```-## Common Patterns+## Common patterns-### Fast Dependencies + Slow Build+### Fast dependencies + slow buildInstall dependencies blocking (must complete before work), build in background:@@ -354,7 +354,7 @@ post-create = "npm install"post-start = "npm run build"```-### Progressive Validation+### Progressive validationQuick checks before commit, thorough validation before merge:@@ -368,7 +368,7 @@ test = "npm test"build = "npm run build"```-### Target-Specific Behavior+### Target-specific behaviorDifferent behavior based on merge target:@@ -382,7 +382,7 @@ fi"""```-### Symlinks and Caches+### Symlinks and cachesSet up shared resources that shouldn't be duplicated:diff --git a/docs/content/list.md b/docs/content/list.mdindex f46d18555..722ba69cd 100644--- a/docs/content/list.md+++ b/docs/content/list.md@@ -99,7 +99,7 @@ The CI column shows GitHub/GitLab pipeline status:Any CI dot appears dimmed when there are unpushed local changes (stale status).-## Status Symbols+## Status symbolsSymbols appear in the Status column in this order:@@ -126,7 +126,7 @@ Symbols appear in the Status column in this order:Rows are dimmed when the branch has no marginal contribution (`≡` matches main or `_` no commits).-## JSON Output+## JSON outputQuery structured data with `--format=json`:@@ -156,13 +156,13 @@ wt list --format=json | jq '.[] | select(.status.main_divergence == "Ahead")'- `is_current` — Current directory- `is_previous` — Previous worktree from [wt switch](@/switch.md)-## See Also+## See also- [wt select](@/select.md) — Interactive worktree picker with live preview----## Command Reference+## Command reference<!-- ⚠️ AUTO-GENERATED from `wt list --help-page` — edit cli.rs to update -->diff --git a/docs/content/merge.md b/docs/content/merge.mdindex b622de4bc..3b37cf63f 100644--- a/docs/content/merge.md+++ b/docs/content/merge.md@@ -58,7 +58,7 @@ wt merge --no-commitUse `--no-commit` to skip steps 1-3 and only run hooks and push. Requires a clean working tree and `--no-remove`.-## See Also+## See also- [wt step](@/step.md) — Run individual merge steps (commit, squash, rebase, push)- [wt remove](@/remove.md) — Remove worktrees without merging@@ -66,7 +66,7 @@ Use `--no-commit` to skip steps 1-3 and only run hooks and push. Requires a clea----## Command Reference+## Command reference<!-- ⚠️ AUTO-GENERATED from `wt merge --help-page` — edit cli.rs to update -->diff --git a/docs/content/remove.md b/docs/content/remove.mdindex fba963cf0..40bf3380f 100644--- a/docs/content/remove.md+++ b/docs/content/remove.md@@ -37,26 +37,26 @@ Force-delete an unmerged branch:wt remove -D experimental```-## Branch Cleanup+## Branch cleanupBranches delete automatically when their content is already in the target branch (typically main). This works with squash-merge and rebase workflows where commit history differs but file changes match.Use `-D` to force-delete unmerged branches. Use `--no-delete-branch` to keep the branch.-## Background Removal+## Background removalRemoval runs in the background by default (returns immediately). Logs are written to `.git/wt-logs/{branch}-remove.log`. Use `--no-background` to run in the foreground.Arguments resolve by path first, then branch name—see [wt switch](@/switch.md#path-first-lookup). Shortcuts: `@` (current), `-` (previous), `^` (main worktree).-## See Also+## See also- [wt merge](@/merge.md) — Remove worktree after merging- [wt list](@/list.md) — View all worktrees----## Command Reference+## Command reference<!-- ⚠️ AUTO-GENERATED from `wt remove --help-page` — edit cli.rs to update -->diff --git a/docs/content/select.md b/docs/content/select.mdindex 5d7466238..4bd94cba1 100644--- a/docs/content/select.md+++ b/docs/content/select.md@@ -18,7 +18,7 @@ Open the selector:wt select```-## Preview Tabs+## Preview tabsToggle between views with number keys:@@ -38,14 +38,14 @@ Toggle between views with number keys:| `Alt+p` | Toggle preview panel || `Ctrl-u`/`Ctrl-d` | Scroll preview up/down |-## See Also+## See also- [wt list](@/list.md) — Static table view with all worktree metadata- [wt switch](@/switch.md) — Direct switching when you know the target branch----## Command Reference+## Command reference<!-- ⚠️ AUTO-GENERATED from `wt select --help-page` — edit cli.rs to update -->diff --git a/docs/content/step.md b/docs/content/step.mdindex c782070fd..da449d636 100644--- a/docs/content/step.md+++ b/docs/content/step.md@@ -51,13 +51,13 @@ wt step push- `pre-merge` — Before pushing to target- `post-merge` — After merge cleanup-## See Also+## See also- [wt merge](@/merge.md) — Runs commit → squash → rebase → hooks → push → cleanup automatically----## Command Reference+## Command reference<!-- ⚠️ AUTO-GENERATED from `wt step --help-page` — edit cli.rs to update -->diff --git a/docs/content/switch.md b/docs/content/switch.mdindex d72a57216..fadfee168 100644--- a/docs/content/switch.md+++ b/docs/content/switch.md@@ -24,7 +24,7 @@ wt switch --create hotfix --base productionFor interactive selection, use [`wt select`](@/select.md).-## Creating Worktrees+## Creating worktreesWith `--create`, worktrunk:@@ -55,7 +55,7 @@ wt switch ^ # Main worktreewt switch --create fix --base=@ # Branch from current HEAD```-## Path-First Lookup+## Path-first lookupArguments resolve by checking the filesystem before git branches:@@ -67,7 +67,7 @@ Arguments resolve by checking the filesystem before git branches:- `wt switch foo` → switches to `repo.foo/` (the `bar` worktree)- `wt switch bar` → also works (branch lookup finds same worktree)-## See Also+## See also- [wt select](@/select.md) — Interactive worktree selection- [wt list](@/list.md) — View all worktrees@@ -76,7 +76,7 @@ Arguments resolve by checking the filesystem before git branches:----## Command Reference+## Command reference<!-- ⚠️ AUTO-GENERATED from `wt switch --help-page` — edit cli.rs to update -->diff --git a/src/cli.rs b/src/cli.rsindex ce0b83c98..9f464f8e6 100644--- a/src/cli.rs+++ b/src/cli.rs@@ -160,7 +160,7 @@ Zsh (~/.zshrc):eval "$(wt config shell init zsh)"```-## Auto Setup+## Auto setupUse `wt config shell install` to add to the shell config automatically."#)]Init {@@ -170,7 +170,7 @@ Use `wt config shell install` to add to the shell config automatically."#)]},/// Write shell integration to config files- #[command(after_long_help = r#"## Auto Setup+ #[command(after_long_help = r#"## Auto setupDetects existing shell config files and adds integration:```console@@ -212,7 +212,7 @@ Skip confirmation prompt:wt config shell uninstall --force```-## Version Tolerance+## Version toleranceDetects various forms of the integration pattern regardless of:- Command prefix (wt, worktree, etc.)@@ -286,7 +286,7 @@ and project config (`.config/wt.toml`).If a config file doesn't exist, shows defaults that would be used.-## Doctor Mode+## Doctor modeUse `--doctor` to test commit generation with a synthetic diff:@@ -314,7 +314,7 @@ commit messages."#after_long_help = r#"Variables are runtime values stored in git config, separate fromconfiguration files. Use `wt config show` to view file-based configuration.-## Available Variables+## Available variables- **default-branch**: The repository's default branch (read-only, cached)- **marker**: Custom status marker for a branch (shown in `wt list`)@@ -676,7 +676,7 @@ Show current configuration and file locations:wt config show```-## Shell Integration+## Shell integrationShell integration allows Worktrunk to change the shell's working directory after `wt switch`. Without it, commands run in a subprocess and directory changes don't persist.@@ -693,7 +693,7 @@ eval "$(wt config shell init zsh)"wt config shell init fish | source```-## Configuration Files+## Configuration files**User config** — `~/.config/worktrunk/config.toml` (or `$WORKTRUNK_CONFIG_PATH`):@@ -703,7 +703,7 @@ Personal settings like LLM commit generation, path templates, and default behaviProject-specific hooks: post-create, post-start, pre-commit, pre-merge, post-merge. See [Hooks](@/hooks.md) for details.-## LLM Commit Messages+## LLM commit messagesWorktrunk can generate commit messages using an LLM. Enable in user config:@@ -766,7 +766,7 @@ wt step push- `pre-merge` — Before pushing to target- `post-merge` — After merge cleanup-## See Also+## See also- [wt merge](@/merge.md) — Runs commit → squash → rebase → hooks → push → cleanup automatically"#@@ -791,7 +791,7 @@ Open the selector:wt select```-## Preview Tabs+## Preview tabsToggle between views with number keys:@@ -811,7 +811,7 @@ Toggle between views with number keys:| `Alt+p` | Toggle preview panel || `Ctrl-u`/`Ctrl-d` | Scroll preview up/down |-## See Also+## See also- [wt list](@/list.md) — Static table view with all worktree metadata- [wt switch](@/switch.md) — Direct switching when you know the target branch@@ -883,7 +883,7 @@ The CI column shows GitHub/GitLab pipeline status:Any CI dot appears dimmed when there are unpushed local changes (stale status).-## Status Symbols+## Status symbolsSymbols appear in the Status column in this order:@@ -910,7 +910,7 @@ Symbols appear in the Status column in this order:Rows are dimmed when the branch has no marginal contribution (`≡` matches main or `_` no commits).-## JSON Output+## JSON outputQuery structured data with `--format=json`:@@ -940,7 +940,7 @@ wt list --format=json | jq '.[] | select(.status.main_divergence == "Ahead")'- `is_current` — Current directory- `is_previous` — Previous worktree from [wt switch](@/switch.md)-## See Also+## See also- [wt select](@/select.md) — Interactive worktree picker with live preview"#@@ -995,7 +995,7 @@ wt switch --create hotfix --base productionFor interactive selection, use [`wt select`](@/select.md).-## Creating Worktrees+## Creating worktreesWith `--create`, worktrunk:@@ -1026,7 +1026,7 @@ wt switch ^ # Main worktreewt switch --create fix --base=@ # Branch from current HEAD```-## Path-First Lookup+## Path-first lookupArguments resolve by checking the filesystem before git branches:@@ -1038,7 +1038,7 @@ Arguments resolve by checking the filesystem before git branches:- `wt switch foo` → switches to `repo.foo/` (the `bar` worktree)- `wt switch bar` → also works (branch lookup finds same worktree)-## See Also+## See also- [wt select](@/select.md) — Interactive worktree selection- [wt list](@/list.md) — View all worktrees@@ -1106,19 +1106,19 @@ Force-delete an unmerged branch:wt remove -D experimental```-## Branch Cleanup+## Branch cleanupBranches delete automatically when their content is already in the target branch (typically main). This works with squash-merge and rebase workflows where commit history differs but file changes match.Use `-D` to force-delete unmerged branches. Use `--no-delete-branch` to keep the branch.-## Background Removal+## Background removalRemoval runs in the background by default (returns immediately). Logs are written to `.git/wt-logs/{branch}-remove.log`. Use `--no-background` to run in the foreground.Arguments resolve by path first, then branch name—see [wt switch](@/switch.md#path-first-lookup). Shortcuts: `@` (current), `-` (previous), `^` (main worktree).-## See Also+## See also- [wt merge](@/merge.md) — Remove worktree after merging- [wt list](@/list.md) — View all worktrees@@ -1194,7 +1194,7 @@ wt merge --no-commitUse `--no-commit` to skip steps 1-3 and only run hooks and push. Requires a clean working tree and `--no-remove`.-## See Also+## See also- [wt step](@/step.md) — Run individual merge steps (commit, squash, rebase, push)- [wt remove](@/remove.md) — Remove worktrees without mergingdiff --git a/src/commands/CLAUDE.md b/src/commands/CLAUDE.mdindex 3a9051bc3..749ace275 100644--- a/src/commands/CLAUDE.md+++ b/src/commands/CLAUDE.md@@ -103,10 +103,10 @@ Each command page should follow this order:1. **Intro paragraph** — One or two sentences: what the command does and when to use it. Integrate key behavioral distinctions (e.g., "Switching to an existing worktree is just a directory change. With `--create`, hooks run.")2. **Examples** — Common use cases with brief labels, immediately after intro-3. **Feature sections** — Deeper explanation of major features (e.g., "Creating Worktrees", "Shortcuts")+3. **Feature sections** — Deeper explanation of major features (e.g., "Creating worktrees", "Shortcuts")4. **Hooks** — Brief summary with link to `/hooks/` for details5. **Technical details** — Implementation details like argument resolution, pushed to the bottom-6. **Command Reference** — Auto-generated from `--help-page`, always last+6. **Command reference** — Auto-generated from `--help-page`, always last### Writing Stylediff --git a/src/main.rs b/src/main.rsindex fb1299076..fc49579cb 100644--- a/src/main.rs+++ b/src/main.rs@@ -146,7 +146,7 @@ fn maybe_handle_help_with_pager() -> bool {////// ---///-/// ## Command Reference+/// ## Command reference////// ```bash/// wt merge — ...@@ -270,7 +270,7 @@ fn handle_help_page(args: &[String]) {println!();println!("---");println!();- println!("## Command Reference");+ println!("## Command reference");println!();println!("<!-- ⚠️ AUTO-GENERATED from `wt {subcommand} --help-page` — edit cli.rs to update -->"diff --git a/tests/common/progressive_output.rs b/tests/common/progressive_output.rsindex 0bb17382b..8b608586f 100644--- a/tests/common/progressive_output.rs+++ b/tests/common/progressive_output.rs@@ -117,8 +117,8 @@ const STABLE_READ_THRESHOLD: u32 = 4;/// On slow CI systems (especially Ubuntu), the PTY may return spurious EOFs before/// all data has been flushed from the kernel buffer. This ensures we wait long enough/// for the kernel to complete its PTY buffer flush, regardless of how many EOFs we've seen.-/// 500ms provides enough margin for slow CI runners under load.-const MIN_DRAIN_WAIT_MS: u64 = 500;+/// 1000ms provides enough margin for slow CI runners under load with many worktrees.+const MIN_DRAIN_WAIT_MS: u64 = 1000;/// Strategy for capturing progressive output snapshots#[derive(Debug, Clone)]diff --git a/tests/snapshots/integration__integration_tests__help__help_config_long.snap b/tests/snapshots/integration__integration_tests__help__help_config_long.snapindex 5d7843401..2800d846f 100644--- a/tests/snapshots/integration__integration_tests__help__help_config_long.snap+++ b/tests/snapshots/integration__integration_tests__help__help_config_long.snap@@ -58,7 +58,7 @@ Show current configuration and file locations:[2mwt config show[0m-[32mShell Integration[0m+[32mShell integration[0mShell integration allows Worktrunk to change the shell's working directory after [2mwt switch[0m. Without it, commands run in a subprocess and directory changes don't persist.@@ -73,7 +73,7 @@ The [2mwt config shell install[0m command adds integration to the shell's conf[2m# For fish: add to ~/.config/fish/config.fish[0m[2mwt config shell init fish | source[0m-[32mConfiguration Files[0m+[32mConfiguration files[0m[1mUser config[0m — [2m~/.config/worktrunk/config.toml[0m (or [2m$WORKTRUNK_CONFIG_PATH[0m):@@ -83,7 +83,7 @@ Personal settings like LLM commit generation, path templates, and default behaviProject-specific hooks: post-create, post-start, pre-commit, pre-merge, post-merge. See Hooks for details.-[32mLLM Commit Messages[0m+[32mLLM commit messages[0mWorktrunk can generate commit messages using an LLM. Enable in user config:diff --git a/tests/snapshots/integration__integration_tests__help__help_config_show.snap b/tests/snapshots/integration__integration_tests__help__help_config_show.snapindex 1fc7f3a77..a0b58da41 100644--- a/tests/snapshots/integration__integration_tests__help__help_config_show.snap+++ b/tests/snapshots/integration__integration_tests__help__help_config_show.snap@@ -43,7 +43,7 @@ and project config ([2m.config/wt.toml[0m).If a config file doesn't exist, shows defaults that would be used.-[32mDoctor Mode[0m+[32mDoctor mode[0mUse [2m--doctor[0m to test commit generation with a synthetic diff:diff --git a/tests/snapshots/integration__integration_tests__help__help_config_var.snap b/tests/snapshots/integration__integration_tests__help__help_config_var.snapindex c69cf1c77..8dadaf9c4 100644--- a/tests/snapshots/integration__integration_tests__help__help_config_var.snap+++ b/tests/snapshots/integration__integration_tests__help__help_config_var.snap@@ -43,7 +43,7 @@ Usage: [1m[36mwt config var[0m [36m[OPTIONS][0m [36m<COMMAND>[0mVariables are runtime values stored in git config, separate fromconfiguration files. Use [2mwt config show[0m to view file-based configuration.-[32mAvailable Variables[0m+[32mAvailable variables[0m- [1mdefault-branch[0m: The repository's default branch (read-only, cached)- [1mmarker[0m: Custom status marker for a branch (shown in [2mwt list[0m)diff --git a/tests/snapshots/integration__integration_tests__help__help_list_long.snap b/tests/snapshots/integration__integration_tests__help__help_list_long.snapindex 07228cfe1..c302fa007 100644--- a/tests/snapshots/integration__integration_tests__help__help_list_long.snap+++ b/tests/snapshots/integration__integration_tests__help__help_list_long.snap@@ -108,7 +108,7 @@ The CI column shows GitHub/GitLab pipeline status:Any CI dot appears dimmed when there are unpushed local changes (stale status).-[32mStatus Symbols[0m+[32mStatus symbols[0mSymbols appear in the Status column in this order:@@ -135,7 +135,7 @@ Symbols appear in the Status column in this order:Rows are dimmed when the branch has no marginal contribution ([2m≡[0m matches main or [2m_[0m no commits).-[32mJSON Output[0m+[32mJSON output[0mQuery structured data with [2m--format=json[0m:@@ -163,6 +163,6 @@ Query structured data with [2m--format=json[0m:- [2mis_current[0m — Current directory- [2mis_previous[0m — Previous worktree from wt switch-[32mSee Also[0m+[32mSee also[0m- wt select — Interactive worktree picker with live previewdiff --git a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap b/tests/snapshots/integration__integration_tests__help__help_merge_long.snapindex a63697f82..b02dbf9e3 100644--- a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap+++ b/tests/snapshots/integration__integration_tests__help__help_merge_long.snap@@ -105,7 +105,7 @@ Skip git operations, only run hooks and push:Use [2m--no-commit[0m to skip steps 1-3 and only run hooks and push. Requires a clean working tree and [2m--no-remove[0m.-[32mSee Also[0m+[32mSee also[0m- wt step — Run individual merge steps (commit, squash, rebase, push)- wt remove — Remove worktrees without mergingdiff --git a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap b/tests/snapshots/integration__integration_tests__help__help_remove_long.snapindex db31576a6..9f26bed17 100644--- a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap+++ b/tests/snapshots/integration__integration_tests__help__help_remove_long.snap@@ -68,19 +68,19 @@ Force-delete an unmerged branch:[2mwt remove -D experimental[0m-[32mBranch Cleanup[0m+[32mBranch cleanup[0mBranches delete automatically when their content is already in the target branch (typically main). This works with squash-merge and rebase workflows where commit history differs but file changes match.Use [2m-D[0m to force-delete unmerged branches. Use [2m--no-delete-branch[0m to keep the branch.-[32mBackground Removal[0m+[32mBackground removal[0mRemoval runs in the background by default (returns immediately). Logs are written to [2m.git/wt-logs/{branch}-remove.log[0m. Use [2m--no-background[0m to run in the foreground.Arguments resolve by path first, then branch name—see wt switch. Shortcuts: [2m@[0m (current), [2m-[0m (previous), [2m^[0m (main worktree).-[32mSee Also[0m+[32mSee also[0m- wt merge — Remove worktree after merging- wt list — View all worktreesdiff --git a/tests/snapshots/integration__integration_tests__help__help_step_long.snap b/tests/snapshots/integration__integration_tests__help__help_step_long.snapindex 5b796018f..96cd3a990 100644--- a/tests/snapshots/integration__integration_tests__help__help_step_long.snap+++ b/tests/snapshots/integration__integration_tests__help__help_step_long.snap@@ -82,6 +82,6 @@ Manual merge workflow with review between steps:- [2mpre-merge[0m — Before pushing to target- [2mpost-merge[0m — After merge cleanup-[32mSee Also[0m+[32mSee also[0m- wt merge — Runs commit → squash → rebase → hooks → push → cleanup automaticallydiff --git a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap b/tests/snapshots/integration__integration_tests__help__help_switch_long.snapindex 7179e071a..37fa2dc94 100644--- a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap+++ b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap@@ -71,7 +71,7 @@ Two distinct operations:For interactive selection, use `wt select`.-[32mCreating Worktrees[0m+[32mCreating worktrees[0mWith [2m--create[0m, worktrunk:@@ -98,7 +98,7 @@ With [2m--create[0m, worktrunk:[2mwt switch ^ # Main worktree[0m[2mwt switch --create fix --base=@ # Branch from current HEAD[0m-[32mPath-First Lookup[0m+[32mPath-first lookup[0mArguments resolve by checking the filesystem before git branches:@@ -110,7 +110,7 @@ Arguments resolve by checking the filesystem before git branches:- [2mwt switch foo[0m → switches to [2mrepo.foo/[0m (the [2mbar[0m worktree)- [2mwt switch bar[0m → also works (branch lookup finds same worktree)-[32mSee Also[0m+[32mSee also[0m- wt select — Interactive worktree selection- wt list — View all worktrees