Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
Eliminate HTML from skill reference files (#1825)
Maximilian Roosdc6a88b541ac
diff --git a/skills/worktrunk/reference/config.md b/skills/worktrunk/reference/config.mdindex a910ef2ac..e48157447 100644--- a/skills/worktrunk/reference/config.md+++ b/skills/worktrunk/reference/config.md@@ -230,9 +230,7 @@ For context:Entries are keyed by project identifier (e.g., `github.com/user/repo`).-#### Setting overrides--[experimental]+#### Setting overrides [experimental]Override global user config for a specific project. Scalar values (like `worktree-path`) replace the global value; everything else (hooks, aliases, etc.) appends, global first.@@ -430,32 +428,34 @@ $ WORKTRUNK_COMMIT__GENERATION__COMMAND="echo 'test: automated commit'" wt merge## Command reference-wt config - Manage user & project configs+```+wt config - Manage user & project configsIncludes shell integration, hooks, and saved state.-Usage: <b><span class=c>wt config</span></b> <span class=c>[OPTIONS]</span> <span class=c><COMMAND></span>+Usage: wt config [OPTIONS] <COMMAND>-<b><span class=g>Commands:</span></b>- <b><span class=c>shell</span></b> Shell integration setup- <b><span class=c>create</span></b> Create configuration file- <b><span class=c>show</span></b> Show configuration files & locations- <b><span class=c>update</span></b> Update deprecated config settings- <b><span class=c>state</span></b> Manage internal data and cache+Commands:+ shell Shell integration setup+ create Create configuration file+ show Show configuration files & locations+ update Update deprecated config settings+ state Manage internal data and cache-<b><span class=g>Options:</span></b>- <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>- Print help (see a summary with '-h')+Options:+ -h, --help+ Print help (see a summary with '-h')-<b><span class=g>Global Options:</span></b>- <b><span class=c>-C</span></b><span class=c> <path></span>+Global Options:+ -C <path>Working directory for this command- <b><span class=c>--config</span></b><span class=c> <path></span>+ --config <path>User config file path- <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>+ -v, --verbose...Verbose output (-v: hooks, templates; -vv: debug report)+```# Subcommands@@ -483,26 +483,28 @@ This tests:### Command reference-wt config show - Show configuration files & locations+```+wt config show - Show configuration files & locations-Usage: <b><span class=c>wt config show</span></b> <span class=c>[OPTIONS]</span>+Usage: wt config show [OPTIONS]-<b><span class=g>Options:</span></b>- <b><span class=c>--full</span></b>+Options:+ --fullRun diagnostic checks (CI tools, commit generation, version)- <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>- Print help (see a summary with '-h')+ -h, --help+ Print help (see a summary with '-h')-<b><span class=g>Global Options:</span></b>- <b><span class=c>-C</span></b><span class=c> <path></span>+Global Options:+ -C <path>Working directory for this command- <b><span class=c>--config</span></b><span class=c> <path></span>+ --config <path>User config file path- <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>+ -v, --verbose...Verbose output (-v: hooks, templates; -vv: debug report)+```## wt config state@@ -559,34 +561,36 @@ $ wt config state clear### Command reference+```wt config state - Manage internal data and cache-Usage: <b><span class=c>wt config state</span></b> <span class=c>[OPTIONS]</span> <span class=c><COMMAND></span>--<b><span class=g>Commands:</span></b>- <b><span class=c>default-branch</span></b> Default branch detection and override- <b><span class=c>previous-branch</span></b> Previous branch (for <b>wt switch -</b>)- <b><span class=c>ci-status</span></b> CI status cache- <b><span class=c>marker</span></b> Branch markers- <b><span class=c>logs</span></b> Background operation logs- <b><span class=c>hints</span></b> One-time hints shown in this repo- <b><span class=c>vars</span></b> [experimental] Custom variables per branch- <b><span class=c>get</span></b> Get all stored state- <b><span class=c>clear</span></b> Clear all stored state--<b><span class=g>Options:</span></b>- <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>- Print help (see a summary with '-h')--<b><span class=g>Global Options:</span></b>- <b><span class=c>-C</span></b><span class=c> <path></span>+Usage: wt config state [OPTIONS] <COMMAND>++Commands:+ default-branch Default branch detection and override+ previous-branch Previous branch (for wt switch -)+ ci-status CI status cache+ marker Branch markers+ logs Background operation logs+ hints One-time hints shown in this repo+ vars [experimental] Custom variables per branch+ get Get all stored state+ clear Clear all stored state++Options:+ -h, --help+ Print help (see a summary with '-h')++Global Options:+ -C <path>Working directory for this command- <b><span class=c>--config</span></b><span class=c> <path></span>+ --config <path>User config file path- <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>+ -v, --verbose...Verbose output (-v: hooks, templates; -vv: debug report)+```## wt config state default-branch@@ -619,28 +623,30 @@ The local inference fallback uses these heuristics in order:### Command reference+```wt config state default-branch - Default branch detection and override-Usage: <b><span class=c>wt config state default-branch</span></b> <span class=c>[OPTIONS]</span> <span class=c>[COMMAND]</span>+Usage: wt config state default-branch [OPTIONS] [COMMAND]-<b><span class=g>Commands:</span></b>- <b><span class=c>get</span></b> Get the default branch- <b><span class=c>set</span></b> Set the default branch- <b><span class=c>clear</span></b> Clear the default branch cache+Commands:+ get Get the default branch+ set Set the default branch+ clear Clear the default branch cache-<b><span class=g>Options:</span></b>- <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>- Print help (see a summary with '-h')+Options:+ -h, --help+ Print help (see a summary with '-h')-<b><span class=g>Global Options:</span></b>- <b><span class=c>-C</span></b><span class=c> <path></span>+Global Options:+ -C <path>Working directory for this command- <b><span class=c>--config</span></b><span class=c> <path></span>+ --config <path>User config file path- <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>+ -v, --verbose...Verbose output (-v: hooks, templates; -vv: debug report)+```## wt config state ci-status@@ -671,27 +677,29 @@ Without a subcommand, runs `get` for the current branch. Use `clear` to reset ca### Command reference+```wt config state ci-status - CI status cache-Usage: <b><span class=c>wt config state ci-status</span></b> <span class=c>[OPTIONS]</span> <span class=c>[COMMAND]</span>+Usage: wt config state ci-status [OPTIONS] [COMMAND]-<b><span class=g>Commands:</span></b>- <b><span class=c>get</span></b> Get CI status for a branch- <b><span class=c>clear</span></b> Clear CI status cache+Commands:+ get Get CI status for a branch+ clear Clear CI status cache-<b><span class=g>Options:</span></b>- <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>- Print help (see a summary with '-h')+Options:+ -h, --help+ Print help (see a summary with '-h')-<b><span class=g>Global Options:</span></b>- <b><span class=c>-C</span></b><span class=c> <path></span>+Global Options:+ -C <path>Working directory for this command- <b><span class=c>--config</span></b><span class=c> <path></span>+ --config <path>User config file path- <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>+ -v, --verbose...Verbose output (-v: hooks, templates; -vv: debug report)+```## wt config state marker@@ -728,28 +736,30 @@ Without a subcommand, runs `get` for the current branch. For `--branch`, use `ge### Command reference+```wt config state marker - Branch markers-Usage: <b><span class=c>wt config state marker</span></b> <span class=c>[OPTIONS]</span> <span class=c>[COMMAND]</span>+Usage: wt config state marker [OPTIONS] [COMMAND]-<b><span class=g>Commands:</span></b>- <b><span class=c>get</span></b> Get marker for a branch- <b><span class=c>set</span></b> Set marker for a branch- <b><span class=c>clear</span></b> Clear marker for a branch+Commands:+ get Get marker for a branch+ set Set marker for a branch+ clear Clear marker for a branch-<b><span class=g>Options:</span></b>- <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>- Print help (see a summary with '-h')+Options:+ -h, --help+ Print help (see a summary with '-h')-<b><span class=g>Global Options:</span></b>- <b><span class=c>-C</span></b><span class=c> <path></span>+Global Options:+ -C <path>Working directory for this command- <b><span class=c>--config</span></b><span class=c> <path></span>+ --config <path>User config file path- <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>+ -v, --verbose...Verbose output (-v: hooks, templates; -vv: debug report)+```## wt config state vars@@ -807,29 +817,31 @@ Stored in git config as `worktrunk.state.<branch>.vars.<key>`. Keys must contain### Command reference+```wt config state vars - [experimental] Custom variables per branch-Usage: <b><span class=c>wt config state vars</span></b> <span class=c>[OPTIONS]</span> <span class=c><COMMAND></span>+Usage: wt config state vars [OPTIONS] <COMMAND>-<b><span class=g>Commands:</span></b>- <b><span class=c>get</span></b> Get a value- <b><span class=c>set</span></b> Set a value- <b><span class=c>list</span></b> List all keys- <b><span class=c>clear</span></b> Clear a key or all keys+Commands:+ get Get a value+ set Set a value+ list List all keys+ clear Clear a key or all keys-<b><span class=g>Options:</span></b>- <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>- Print help (see a summary with '-h')+Options:+ -h, --help+ Print help (see a summary with '-h')-<b><span class=g>Global Options:</span></b>- <b><span class=c>-C</span></b><span class=c> <path></span>+Global Options:+ -C <path>Working directory for this command- <b><span class=c>--config</span></b><span class=c> <path></span>+ --config <path>User config file path- <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>+ -v, --verbose...Verbose output (-v: hooks, templates; -vv: debug report)+```## wt config state logs@@ -888,24 +900,26 @@ $ wt config state logs clear### Command reference+```wt config state logs - Background operation logs-Usage: <b><span class=c>wt config state logs</span></b> <span class=c>[OPTIONS]</span> <span class=c>[COMMAND]</span>+Usage: wt config state logs [OPTIONS] [COMMAND]-<b><span class=g>Commands:</span></b>- <b><span class=c>get</span></b> Get log file paths- <b><span class=c>clear</span></b> Clear background operation logs+Commands:+ get Get log file paths+ clear Clear background operation logs-<b><span class=g>Options:</span></b>- <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>- Print help (see a summary with '-h')+Options:+ -h, --help+ Print help (see a summary with '-h')-<b><span class=g>Global Options:</span></b>- <b><span class=c>-C</span></b><span class=c> <path></span>+Global Options:+ -C <path>Working directory for this command- <b><span class=c>--config</span></b><span class=c> <path></span>+ --config <path>User config file path- <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>+ -v, --verbose...Verbose output (-v: hooks, templates; -vv: debug report)+```diff --git a/skills/worktrunk/reference/faq.md b/skills/worktrunk/reference/faq.mdindex 17f9933f0..652beeb73 100644--- a/skills/worktrunk/reference/faq.md+++ b/skills/worktrunk/reference/faq.md@@ -164,16 +164,16 @@ User hooks don't require approval (you defined them). Commands from project hook### Example approval prompt-<span class="y">▲ <b>repo</b> needs approval to execute <b>3</b> commands:</span>+▲ repo needs approval to execute 3 commands:-<span class="d">○</span> pre-start <b>install</b>:-<span style='background:var(--bright-white,#fff)'> </span> <span class="d"><span class="b">npm</span> ci</span>-<span class="d">○</span> pre-start <b>build</b>:-<span style='background:var(--bright-white,#fff)'> </span> <span class="d"><span class="b">cargo</span> build <span class="c">--release</span></span>-<span class="d">○</span> pre-start <b>env</b>:-<span style='background:var(--bright-white,#fff)'> </span> <span class="d"><span class="b">echo</span> <span class="g">'PORT={{ branch | hash_port }}'</span> <span class="c">></span> .env.local</span>+○ pre-start install:+ npm ci+○ pre-start build:+ cargo build --release+○ pre-start env:+ echo 'PORT={{ branch | hash_port }}' > .env.local-<span class="c">❯</span> Allow and remember? <b>[y/N]</b>+❯ Allow and remember? [y/N]Use `--yes` to bypass prompts (useful for CI/automation).diff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.mdindex e44d10d71..7f4e2f816 100644--- a/skills/worktrunk/reference/hook.md+++ b/skills/worktrunk/reference/hook.md@@ -37,16 +37,18 @@ During `wt merge`, hooks run in this order: pre-commit → post-commit → pre-mProject commands require approval on first run:-<span class="y">▲ <b>repo</b> needs approval to execute <b>3</b> commands:</span>+```+▲ repo needs approval to execute 3 commands:-<span class="d">○</span> pre-start <b>install</b>:-<span style='background:var(--bright-white,#fff)'> </span> <span class="d"><span class="b">npm</span> ci</span>-<span class="d">○</span> pre-start <b>build</b>:-<span style='background:var(--bright-white,#fff)'> </span> <span class="d"><span class="b">cargo</span> build <span class="c">--release</span></span>-<span class="d">○</span> pre-start <b>env</b>:-<span style='background:var(--bright-white,#fff)'> </span> <span class="d"><span class="b">echo</span> <span class="g">'PORT={{ branch | hash_port }}'</span> <span class="c">></span> .env.local</span>+○ pre-start install:+ npm ci+○ pre-start build:+ cargo build --release+○ pre-start env:+ echo 'PORT={{ branch | hash_port }}' > .env.local-<span class="c">❯</span> Allow and remember? <b>[y/N]</b>+❯ Allow and remember? [y/N]+```- Approvals are saved to `~/.config/worktrunk/approvals.toml`- If a command changes, new approval is required@@ -211,9 +213,7 @@ The `user:` and `project:` prefixes filter by source. Use `user:` or `project:`The `--var KEY=VALUE` flag overrides built-in template variables — useful for testing hooks with different contexts without switching to that context.-# Pipeline Ordering--[experimental]+# Pipeline Ordering [experimental]By default, all commands in a `post-*` hook run concurrently in the background. The TOML type determines execution order. In the simplest case, a string runs one command:@@ -443,37 +443,39 @@ remove-db = "docker stop {{ repo }}-{{ branch | sanitize }}-postgres 2>/dev/null## Command reference+```wt hook - Run configured hooks-Usage: <b><span class=c>wt hook</span></b> <span class=c>[OPTIONS]</span> <span class=c><COMMAND></span>--<b><span class=g>Commands:</span></b>- <b><span class=c>show</span></b> Show configured hooks- <b><span class=c>pre-switch</span></b> Run pre-switch hooks- <b><span class=c>post-switch</span></b> Run post-switch hooks- <b><span class=c>pre-start</span></b> Run pre-start hooks- <b><span class=c>post-start</span></b> Run post-start hooks- <b><span class=c>pre-commit</span></b> Run pre-commit hooks- <b><span class=c>post-commit</span></b> Run post-commit hooks- <b><span class=c>pre-merge</span></b> Run pre-merge hooks- <b><span class=c>post-merge</span></b> Run post-merge hooks- <b><span class=c>pre-remove</span></b> Run pre-remove hooks- <b><span class=c>post-remove</span></b> Run post-remove hooks- <b><span class=c>approvals</span></b> Manage command approvals--<b><span class=g>Options:</span></b>- <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>- Print help (see a summary with '-h')--<b><span class=g>Global Options:</span></b>- <b><span class=c>-C</span></b><span class=c> <path></span>+Usage: wt hook [OPTIONS] <COMMAND>++Commands:+ show Show configured hooks+ pre-switch Run pre-switch hooks+ post-switch Run post-switch hooks+ pre-start Run pre-start hooks+ post-start Run post-start hooks+ pre-commit Run pre-commit hooks+ post-commit Run post-commit hooks+ pre-merge Run pre-merge hooks+ post-merge Run post-merge hooks+ pre-remove Run pre-remove hooks+ post-remove Run post-remove hooks+ approvals Manage command approvals++Options:+ -h, --help+ Print help (see a summary with '-h')++Global Options:+ -C <path>Working directory for this command- <b><span class=c>--config</span></b><span class=c> <path></span>+ --config <path>User config file path- <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>+ -v, --verbose...Verbose output (-v: hooks, templates; -vv: debug report)+```# Subcommands@@ -506,24 +508,26 @@ Approved commands are saved to `~/.config/worktrunk/approvals.toml`. Re-approval### Command reference+```wt hook approvals - Manage command approvals-Usage: <b><span class=c>wt hook approvals</span></b> <span class=c>[OPTIONS]</span> <span class=c><COMMAND></span>+Usage: wt hook approvals [OPTIONS] <COMMAND>-<b><span class=g>Commands:</span></b>- <b><span class=c>add</span></b> Store approvals in approvals.toml- <b><span class=c>clear</span></b> Clear approved commands from approvals.toml+Commands:+ add Store approvals in approvals.toml+ clear Clear approved commands from approvals.toml-<b><span class=g>Options:</span></b>- <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>- Print help (see a summary with '-h')+Options:+ -h, --help+ Print help (see a summary with '-h')-<b><span class=g>Global Options:</span></b>- <b><span class=c>-C</span></b><span class=c> <path></span>+Global Options:+ -C <path>Working directory for this command- <b><span class=c>--config</span></b><span class=c> <path></span>+ --config <path>User config file path- <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>+ -v, --verbose...Verbose output (-v: hooks, templates; -vv: debug report)+```diff --git a/skills/worktrunk/reference/list.md b/skills/worktrunk/reference/list.mdindex 0e9757331..8c3e31468 100644--- a/skills/worktrunk/reference/list.md+++ b/skills/worktrunk/reference/list.md@@ -65,19 +65,17 @@ The CI column shows GitHub/GitLab pipeline status:| Indicator | Meaning ||-----------|---------|-| <span style='color:#0a0'>●</span> green | All checks passed |-| <span style='color:#00a'>●</span> blue | Checks running |-| <span style='color:#a00'>●</span> red | Checks failed |-| <span style='color:#a60'>●</span> yellow | Merge conflicts with base |-| <span style='color:#888'>●</span> gray | No checks configured |-| <span style='color:#a60'>⚠</span> yellow | Fetch error (rate limit, network) |+| `●` green | All checks passed |+| `●` blue | Checks running |+| `●` red | Checks failed |+| `●` yellow | Merge conflicts with base |+| `●` gray | No checks configured |+| `⚠` yellow | Fetch error (rate limit, network) || (blank) | No upstream or no PR/MR |CI indicators are clickable links to the PR or pipeline page. Any CI dot appears dimmed when unpushed local changes make the status stale. PRs/MRs are checked first, then branch workflows/pipelines for branches with an upstream. Local-only branches show blank; remote-only branches — visible with `--remotes` — get CI status detection. Results are cached for 30-60 seconds; use `wt config state` to view or clear.-### LLM summaries--[experimental]+### LLM summaries [experimental]Reuses the [`commit.generation`](https://worktrunk.dev/config/#commit) command — the same LLM that generates commit messages. Enable with `summary = true` in `[list]` config; requires `--full`. Results are cached until the branch's diff changes.@@ -248,49 +246,51 @@ When `main_state == "integrated"`: `"ancestor"` `"trees_match"` `"no_added_chang`"passed"` `"running"` `"failed"` `"conflicts"` `"no-ci"` `"error"`-Missing a field that would be generally useful? [Open an issue](https://github.com/max-sixty/worktrunk/issues).+Missing a field that would be generally useful? Open an issue at https://github.com/max-sixty/worktrunk.## Command reference+```wt list - List worktrees and their status-Usage: <b><span class=c>wt list</span></b> <span class=c>[OPTIONS]</span>- <b><span class=c>wt list</span></b> <span class=c><COMMAND></span>+Usage: wt list [OPTIONS]+ wt list <COMMAND>-<b><span class=g>Commands:</span></b>- <b><span class=c>statusline</span></b> Single-line status for shell prompts+Commands:+ statusline Single-line status for shell prompts-<b><span class=g>Options:</span></b>- <b><span class=c>--format</span></b><span class=c> <FORMAT></span>+Options:+ --format <FORMAT>Output format (table, json)[default: table]- <b><span class=c>--branches</span></b>+ --branchesInclude branches without worktrees- <b><span class=c>--remotes</span></b>+ --remotesInclude remote branches- <b><span class=c>--full</span></b>+ --fullShow CI, diff analysis, and LLM summaries- <b><span class=c>--progressive</span></b>+ --progressiveShow fast info immediately, update with slow infoDisplays local data (branches, paths, status) first, then updates with remote data (CI,upstream) as it arrives. Use --no-progressive to force buffered rendering. Auto-enabledfor TTY.- <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>- Print help (see a summary with '-h')+ -h, --help+ Print help (see a summary with '-h')-<b><span class=g>Global Options:</span></b>- <b><span class=c>-C</span></b><span class=c> <path></span>+Global Options:+ -C <path>Working directory for this command- <b><span class=c>--config</span></b><span class=c> <path></span>+ --config <path>User config file path- <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>+ -v, --verbose...Verbose output (-v: hooks, templates; -vv: debug report)+```diff --git a/skills/worktrunk/reference/merge.md b/skills/worktrunk/reference/merge.mdindex 270f3e3b0..ee2e4d137 100644--- a/skills/worktrunk/reference/merge.md+++ b/skills/worktrunk/reference/merge.md@@ -73,58 +73,60 @@ lint = "cargo clippy"## Command reference+```wt merge - Merge current branch into the target branch-Squash & rebase, fast-forward the target branch, remove the worktree.+Squash & rebase, fast-forward the target branch, remove the worktree.-Usage: <b><span class=c>wt merge</span></b> <span class=c>[OPTIONS]</span> <span class=c>[TARGET]</span>+Usage: wt merge [OPTIONS] [TARGET]-<b><span class=g>Arguments:</span></b>- <span class=c>[TARGET]</span>+Arguments:+ [TARGET]Target branchDefaults to default branch.-<b><span class=g>Options:</span></b>- <b><span class=c>--no-squash</span></b>+Options:+ --no-squashSkip commit squashing- <b><span class=c>--no-commit</span></b>+ --no-commitSkip commit and squash- <b><span class=c>--no-rebase</span></b>+ --no-rebaseSkip rebase (fail if not already rebased)- <b><span class=c>--no-remove</span></b>+ --no-removeKeep worktree after merge- <b><span class=c>--no-ff</span></b>+ --no-ffCreate a merge commit (no fast-forward)- <b><span class=c>--stage</span></b><span class=c> <STAGE></span>+ --stage <STAGE>What to stage before committing [default: all]Possible values:- - <b><span class=c>all</span></b>: Stage everything: untracked files + unstaged tracked changes- - <b><span class=c>tracked</span></b>: Stage tracked changes only (like <b>git add -u</b>)- - <b><span class=c>none</span></b>: Stage nothing, commit only what's already in the index+ - all: Stage everything: untracked files + unstaged tracked changes+ - tracked: Stage tracked changes only (like git add -u)+ - none: Stage nothing, commit only what's already in the index- <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>- Print help (see a summary with '-h')+ -h, --help+ Print help (see a summary with '-h')-<b><span class=g>Automation:</span></b>- <b><span class=c>-y</span></b>, <b><span class=c>--yes</span></b>+Automation:+ -y, --yesSkip approval prompts- <b><span class=c>--no-verify</span></b>+ --no-verifySkip hooks-<b><span class=g>Global Options:</span></b>- <b><span class=c>-C</span></b><span class=c> <path></span>+Global Options:+ -C <path>Working directory for this command- <b><span class=c>--config</span></b><span class=c> <path></span>+ --config <path>User config file path- <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>+ -v, --verbose...Verbose output (-v: hooks, templates; -vv: debug report)+```diff --git a/skills/worktrunk/reference/remove.md b/skills/worktrunk/reference/remove.mdindex 1e3748edd..ba419f59f 100644--- a/skills/worktrunk/reference/remove.md+++ b/skills/worktrunk/reference/remove.md@@ -76,48 +76,50 @@ Detached worktrees have no branch name. Pass the worktree path instead: `wt remo## Command reference+```wt remove - Remove worktree; delete branch if mergedDefaults to the current worktree.-Usage: <b><span class=c>wt remove</span></b> <span class=c>[OPTIONS]</span> <span class=c>[BRANCHES]...</span>+Usage: wt remove [OPTIONS] [BRANCHES]...-<b><span class=g>Arguments:</span></b>- <span class=c>[BRANCHES]...</span>+Arguments:+ [BRANCHES]...Branch name [default: current]-<b><span class=g>Options:</span></b>- <b><span class=c>--no-delete-branch</span></b>+Options:+ --no-delete-branchKeep branch after removal- <b><span class=c>-D</span></b>, <b><span class=c>--force-delete</span></b>+ -D, --force-deleteDelete unmerged branches- <b><span class=c>--foreground</span></b>+ --foregroundRun removal in foreground (block until complete)- <b><span class=c>-f</span></b>, <b><span class=c>--force</span></b>+ -f, --forceForce worktree removalRemove worktrees even if they contain untracked files (like build artifacts). Without thisflag, removal fails if untracked files exist.- <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>- Print help (see a summary with '-h')+ -h, --help+ Print help (see a summary with '-h')-<b><span class=g>Automation:</span></b>- <b><span class=c>-y</span></b>, <b><span class=c>--yes</span></b>+Automation:+ -y, --yesSkip approval prompts- <b><span class=c>--no-verify</span></b>+ --no-verifySkip hooks-<b><span class=g>Global Options:</span></b>- <b><span class=c>-C</span></b><span class=c> <path></span>+Global Options:+ -C <path>Working directory for this command- <b><span class=c>--config</span></b><span class=c> <path></span>+ --config <path>User config file path- <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>+ -v, --verbose...Verbose output (-v: hooks, templates; -vv: debug report)+```diff --git a/skills/worktrunk/reference/step.md b/skills/worktrunk/reference/step.mdindex e339ce397..4def81fc8 100644--- a/skills/worktrunk/reference/step.md+++ b/skills/worktrunk/reference/step.md@@ -36,38 +36,40 @@ $ wt step push## Command reference+```wt step - Run individual operations-The building blocks of <b>wt merge</b> — commit, squash, rebase, push — plus standalone utilities.--Usage: <b><span class=c>wt step</span></b> <span class=c>[OPTIONS]</span> <span class=c><COMMAND></span>--<b><span class=g>Commands:</span></b>- <b><span class=c>commit</span></b> Stage and commit with LLM-generated message- <b><span class=c>squash</span></b> Squash commits since branching- <b><span class=c>push</span></b> Fast-forward target to current branch- <b><span class=c>rebase</span></b> Rebase onto target- <b><span class=c>diff</span></b> Show all changes since branching- <b><span class=c>copy-ignored</span></b> Copy gitignored files to another worktree- <b><span class=c>eval</span></b> [experimental] Evaluate a template expression- <b><span class=c>for-each</span></b> [experimental] Run command in each worktree- <b><span class=c>promote</span></b> [experimental] Swap a branch into the main worktree- <b><span class=c>prune</span></b> [experimental] Remove worktrees merged into the default branch- <b><span class=c>relocate</span></b> [experimental] Move worktrees to expected paths--<b><span class=g>Options:</span></b>- <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>- Print help (see a summary with '-h')--<b><span class=g>Global Options:</span></b>- <b><span class=c>-C</span></b><span class=c> <path></span>+The building blocks of wt merge — commit, squash, rebase, push — plus standalone utilities.++Usage: wt step [OPTIONS] <COMMAND>++Commands:+ commit Stage and commit with LLM-generated message+ squash Squash commits since branching+ push Fast-forward target to current branch+ rebase Rebase onto target+ diff Show all changes since branching+ copy-ignored Copy gitignored files to another worktree+ eval [experimental] Evaluate a template expression+ for-each [experimental] Run command in each worktree+ promote [experimental] Swap a branch into the main worktree+ prune [experimental] Remove worktrees merged into the default branch+ relocate [experimental] Move worktrees to expected paths++Options:+ -h, --help+ Print help (see a summary with '-h')++Global Options:+ -C <path>Working directory for this command- <b><span class=c>--config</span></b><span class=c> <path></span>+ --config <path>User config file path- <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>+ -v, --verbose...Verbose output (-v: hooks, templates; -vv: debug report)+```# Subcommands@@ -114,46 +116,48 @@ $ wt step commit --show-prompt | llm -m gpt-5-nano### Command reference+```wt step commit - Stage and commit with LLM-generated message-Usage: <b><span class=c>wt step commit</span></b> <span class=c>[OPTIONS]</span>+Usage: wt step commit [OPTIONS]-<b><span class=g>Options:</span></b>- <b><span class=c>-b</span></b>, <b><span class=c>--branch</span></b><span class=c> <BRANCH></span>+Options:+ -b, --branch <BRANCH>Branch to operate on (defaults to current worktree)- <b><span class=c>--stage</span></b><span class=c> <STAGE></span>+ --stage <STAGE>What to stage before committing [default: all]Possible values:- - <b><span class=c>all</span></b>: Stage everything: untracked files + unstaged tracked changes- - <b><span class=c>tracked</span></b>: Stage tracked changes only (like <b>git add -u</b>)- - <b><span class=c>none</span></b>: Stage nothing, commit only what's already in the index+ - all: Stage everything: untracked files + unstaged tracked changes+ - tracked: Stage tracked changes only (like git add -u)+ - none: Stage nothing, commit only what's already in the index- <b><span class=c>--show-prompt</span></b>+ --show-promptShow prompt without running LLMOutputs the rendered prompt to stdout for debugging or manual piping.- <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>- Print help (see a summary with '-h')+ -h, --help+ Print help (see a summary with '-h')-<b><span class=g>Automation:</span></b>- <b><span class=c>-y</span></b>, <b><span class=c>--yes</span></b>+Automation:+ -y, --yesSkip approval prompts- <b><span class=c>--no-verify</span></b>+ --no-verifySkip hooks-<b><span class=g>Global Options:</span></b>- <b><span class=c>-C</span></b><span class=c> <path></span>+Global Options:+ -C <path>Working directory for this command- <b><span class=c>--config</span></b><span class=c> <path></span>+ --config <path>User config file path- <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>+ -v, --verbose...Verbose output (-v: hooks, templates; -vv: debug report)+```## wt step squash@@ -194,51 +198,53 @@ $ wt step squash --show-prompt | less### Command reference+```wt step squash - Squash commits since branchingStages changes and generates message with LLM.-Usage: <b><span class=c>wt step squash</span></b> <span class=c>[OPTIONS]</span> <span class=c>[TARGET]</span>+Usage: wt step squash [OPTIONS] [TARGET]-<b><span class=g>Arguments:</span></b>- <span class=c>[TARGET]</span>+Arguments:+ [TARGET]Target branchDefaults to default branch.-<b><span class=g>Options:</span></b>- <b><span class=c>--stage</span></b><span class=c> <STAGE></span>+Options:+ --stage <STAGE>What to stage before committing [default: all]Possible values:- - <b><span class=c>all</span></b>: Stage everything: untracked files + unstaged tracked changes- - <b><span class=c>tracked</span></b>: Stage tracked changes only (like <b>git add -u</b>)- - <b><span class=c>none</span></b>: Stage nothing, commit only what's already in the index+ - all: Stage everything: untracked files + unstaged tracked changes+ - tracked: Stage tracked changes only (like git add -u)+ - none: Stage nothing, commit only what's already in the index- <b><span class=c>--show-prompt</span></b>+ --show-promptShow prompt without running LLMOutputs the rendered prompt to stdout for debugging or manual piping.- <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>- Print help (see a summary with '-h')+ -h, --help+ Print help (see a summary with '-h')-<b><span class=g>Automation:</span></b>- <b><span class=c>-y</span></b>, <b><span class=c>--yes</span></b>+Automation:+ -y, --yesSkip approval prompts- <b><span class=c>--no-verify</span></b>+ --no-verifySkip hooks-<b><span class=g>Global Options:</span></b>- <b><span class=c>-C</span></b><span class=c> <path></span>+Global Options:+ -C <path>Working directory for this command- <b><span class=c>--config</span></b><span class=c> <path></span>+ --config <path>User config file path- <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>+ -v, --verbose...Verbose output (-v: hooks, templates; -vv: debug report)+```## wt step diff@@ -276,34 +282,36 @@ $ GIT_INDEX_FILE=/tmp/idx git diff $(git merge-base HEAD $(wt config state defau### Command reference+```wt step diff - Show all changes since branchingIncludes committed, staged, unstaged, and untracked files.-Usage: <b><span class=c>wt step diff</span></b> <span class=c>[OPTIONS]</span> <span class=c>[TARGET]</span> <b><span class=c>[--</span></b> <span class=c><EXTRA_ARGS>...</span><b><span class=c>]</span></b>+Usage: wt step diff [OPTIONS] [TARGET] [-- <EXTRA_ARGS>...]-<b><span class=g>Arguments:</span></b>- <span class=c>[TARGET]</span>+Arguments:+ [TARGET]Target branchDefaults to default branch.- <span class=c>[EXTRA_ARGS]...</span>- Extra arguments forwarded to <b>git diff</b>+ [EXTRA_ARGS]...+ Extra arguments forwarded to git diff-<b><span class=g>Options:</span></b>- <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>- Print help (see a summary with '-h')+Options:+ -h, --help+ Print help (see a summary with '-h')-<b><span class=g>Global Options:</span></b>- <b><span class=c>-C</span></b><span class=c> <path></span>+Global Options:+ -C <path>Working directory for this command- <b><span class=c>--config</span></b><span class=c> <path></span>+ --config <path>User config file path- <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>+ -v, --verbose...Verbose output (-v: hooks, templates; -vv: debug report)+```## wt step copy-ignored@@ -398,41 +406,43 @@ The `.worktreeinclude` pattern is shared with [Claude Code on desktop](https://c### Command reference+```wt step copy-ignored - Copy gitignored files to another worktreeEliminates cold starts by copying build caches and dependencies.-Usage: <b><span class=c>wt step copy-ignored</span></b> <span class=c>[OPTIONS]</span>+Usage: wt step copy-ignored [OPTIONS]-<b><span class=g>Options:</span></b>- <b><span class=c>--from</span></b><span class=c> <FROM></span>+Options:+ --from <FROM>Source worktree branchDefaults to main worktree.- <b><span class=c>--to</span></b><span class=c> <TO></span>+ --to <TO>Destination worktree branchDefaults to current worktree.- <b><span class=c>--dry-run</span></b>+ --dry-runShow what would be copied- <b><span class=c>--force</span></b>+ --forceOverwrite existing files in destination- <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>- Print help (see a summary with '-h')+ -h, --help+ Print help (see a summary with '-h')-<b><span class=g>Global Options:</span></b>- <b><span class=c>-C</span></b><span class=c> <path></span>+Global Options:+ -C <path>Working directory for this command- <b><span class=c>--config</span></b><span class=c> <path></span>+ --config <path>User config file path- <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>+ -v, --verbose...Verbose output (-v: hooks, templates; -vv: debug report)+```## wt step eval@@ -485,32 +495,34 @@ Note: This command is experimental and may change in future versions.### Command reference+```wt step eval - [experimental] Evaluate a template expressionPrints the result to stdout for use in scripts and shell substitutions.-Usage: <b><span class=c>wt step eval</span></b> <span class=c>[OPTIONS]</span> <span class=c><TEMPLATE></span>+Usage: wt step eval [OPTIONS] <TEMPLATE>-<b><span class=g>Arguments:</span></b>- <span class=c><TEMPLATE></span>+Arguments:+ <TEMPLATE>Template expression to evaluate-<b><span class=g>Options:</span></b>- <b><span class=c>--dry-run</span></b>+Options:+ --dry-runShow template variables and expanded result- <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>- Print help (see a summary with '-h')+ -h, --help+ Print help (see a summary with '-h')-<b><span class=g>Global Options:</span></b>- <b><span class=c>-C</span></b><span class=c> <path></span>+Global Options:+ -C <path>Working directory for this command- <b><span class=c>--config</span></b><span class=c> <path></span>+ --config <path>User config file path- <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>+ -v, --verbose...Verbose output (-v: hooks, templates; -vv: debug report)+```## wt step for-each@@ -554,29 +566,31 @@ Note: This command is experimental and may change in future versions.### Command reference+```wt step for-each - [experimental] Run command in each worktreeExecutes sequentially with real-time output; continues on failure.-Usage: <b><span class=c>wt step for-each</span></b> <span class=c>[OPTIONS]</span> <b><span class=c>--</span></b> <span class=c><ARGS>...</span>+Usage: wt step for-each [OPTIONS] -- <ARGS>...-<b><span class=g>Arguments:</span></b>- <span class=c><ARGS>...</span>+Arguments:+ <ARGS>...Command template (see --help for all variables)-<b><span class=g>Options:</span></b>- <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>- Print help (see a summary with '-h')+Options:+ -h, --help+ Print help (see a summary with '-h')-<b><span class=g>Global Options:</span></b>- <b><span class=c>-C</span></b><span class=c> <path></span>+Global Options:+ -C <path>Working directory for this command- <b><span class=c>--config</span></b><span class=c> <path></span>+ --config <path>User config file path- <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>+ -v, --verbose...Verbose output (-v: hooks, templates; -vv: debug report)+```## wt step promote@@ -626,31 +640,33 @@ The swap uses `rename()` for each entry — fast regardless of entry size, since### Command reference+```wt step promote - [experimental] Swap a branch into the main worktreeExchanges branches and gitignored files between two worktrees.-Usage: <b><span class=c>wt step promote</span></b> <span class=c>[OPTIONS]</span> <span class=c>[BRANCH]</span>+Usage: wt step promote [OPTIONS] [BRANCH]-<b><span class=g>Arguments:</span></b>- <span class=c>[BRANCH]</span>+Arguments:+ [BRANCH]Branch to promote to main worktreeDefaults to current branch, or default branch from main worktree.-<b><span class=g>Options:</span></b>- <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>- Print help (see a summary with '-h')+Options:+ -h, --help+ Print help (see a summary with '-h')-<b><span class=g>Global Options:</span></b>- <b><span class=c>-C</span></b><span class=c> <path></span>+Global Options:+ -C <path>Working directory for this command- <b><span class=c>--config</span></b><span class=c> <path></span>+ --config <path>User config file path- <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>+ -v, --verbose...Verbose output (-v: hooks, templates; -vv: debug report)+```## wt step prune@@ -689,38 +705,40 @@ $ wt step prune### Command reference+```wt step prune - [experimental] Remove worktrees merged into the default branch-Usage: <b><span class=c>wt step prune</span></b> <span class=c>[OPTIONS]</span>+Usage: wt step prune [OPTIONS]-<b><span class=g>Options:</span></b>- <b><span class=c>--dry-run</span></b>+Options:+ --dry-runShow what would be removed- <b><span class=c>--min-age</span></b><span class=c> <MIN_AGE></span>+ --min-age <MIN_AGE>Skip worktrees younger than this[default: 1h]- <b><span class=c>--foreground</span></b>+ --foregroundRun removal in foreground (block until complete)- <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>- Print help (see a summary with '-h')+ -h, --help+ Print help (see a summary with '-h')-<b><span class=g>Automation:</span></b>- <b><span class=c>-y</span></b>, <b><span class=c>--yes</span></b>+Automation:+ -y, --yesSkip approval prompts-<b><span class=g>Global Options:</span></b>- <b><span class=c>-C</span></b><span class=c> <path></span>+Global Options:+ -C <path>Working directory for this command- <b><span class=c>--config</span></b><span class=c> <path></span>+ --config <path>User config file path- <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>+ -v, --verbose...Verbose output (-v: hooks, templates; -vv: debug report)+```## wt step relocate@@ -782,44 +800,44 @@ Note: This command is experimental and may change in future versions.### Command reference+```wt step relocate - [experimental] Move worktrees to expected paths-Relocates worktrees whose path doesn't match the <b>worktree-path</b> template.+Relocates worktrees whose path doesn't match the worktree-path template.-Usage: <b><span class=c>wt step relocate</span></b> <span class=c>[OPTIONS]</span> <span class=c>[BRANCHES]...</span>+Usage: wt step relocate [OPTIONS] [BRANCHES]...-<b><span class=g>Arguments:</span></b>- <span class=c>[BRANCHES]...</span>+Arguments:+ [BRANCHES]...Worktrees to relocate (defaults to all mismatched)-<b><span class=g>Options:</span></b>- <b><span class=c>--dry-run</span></b>+Options:+ --dry-runShow what would be moved- <b><span class=c>--commit</span></b>+ --commitCommit uncommitted changes before relocating- <b><span class=c>--clobber</span></b>+ --clobberBackup non-worktree paths at target locations- Moves blocking paths to <b><path>.bak-<timestamp></b>.+ Moves blocking paths to <path>.bak-<timestamp>.- <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>- Print help (see a summary with '-h')+ -h, --help+ Print help (see a summary with '-h')-<b><span class=g>Global Options:</span></b>- <b><span class=c>-C</span></b><span class=c> <path></span>+Global Options:+ -C <path>Working directory for this command- <b><span class=c>--config</span></b><span class=c> <path></span>+ --config <path>User config file path- <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>+ -v, --verbose...Verbose output (-v: hooks, templates; -vv: debug report)+```-## Aliases--[experimental]+## Aliases [experimental]Custom command templates configured in user config (`~/.config/worktrunk/config.toml`) or project config (`.config/wt.toml`). Aliases support the same [template variables](https://worktrunk.dev/hook/#template-variables) as hooks.diff --git a/skills/worktrunk/reference/switch.md b/skills/worktrunk/reference/switch.mdindex d358d2544..1f2bfb991 100644--- a/skills/worktrunk/reference/switch.md+++ b/skills/worktrunk/reference/switch.md@@ -110,57 +110,58 @@ To change which branch a worktree is on, use `git switch` inside that worktree.## Command reference+```wt switch - Switch to a worktree; create if needed-Usage: <b><span class=c>wt switch</span></b> <span class=c>[OPTIONS]</span> <span class=c>[BRANCH]</span> <b><span class=c>[--</span></b> <span class=c><EXECUTE_ARGS>...</span><b><span class=c>]</span></b>+Usage: wt switch [OPTIONS] [BRANCH] [-- <EXECUTE_ARGS>...]-<b><span class=g>Arguments:</span></b>- <span class=c>[BRANCH]</span>+Arguments:+ [BRANCH]Branch name or shortcut- Opens interactive picker if omitted. Shortcuts: '^' (default branch), '-' (previous), '@'- (current), 'pr:{N}' (GitHub PR), 'mr:{N}' (GitLab MR)+ Opens interactive picker if omitted. Shortcuts: '^' (default branch), '-' (previous), '@'+ (current), 'pr:{N}' (GitHub PR), 'mr:{N}' (GitLab MR)- <span class=c>[EXECUTE_ARGS]...</span>+ [EXECUTE_ARGS]...Additional arguments for --execute command (after --)- Arguments after <b>--</b> are appended to the execute command. Each argument is expanded for+ Arguments after -- are appended to the execute command. Each argument is expanded fortemplates, then POSIX shell-escaped.-<b><span class=g>Options:</span></b>- <b><span class=c>-c</span></b>, <b><span class=c>--create</span></b>+Options:+ -c, --createCreate a new branch- <b><span class=c>-b</span></b>, <b><span class=c>--base</span></b><span class=c> <BASE></span>+ -b, --base <BASE>Base branchDefaults to default branch.- <b><span class=c>-x</span></b>, <b><span class=c>--execute</span></b><span class=c> <EXECUTE></span>+ -x, --execute <EXECUTE>Command to run after switchReplaces the wt process with the command after switching, giving it full terminal control.Useful for launching editors, AI agents, or other interactive tools.- Supports <u>hook template variables</u> (<b>{{ branch }}</b>, <b>{{ worktree_path }}</b>, etc.) and filters. <b>{{</b>-<b> base }}</b> and <b>{{ base_worktree_path }}</b> require <b>--create</b>.+ Supports hook template variables ({{ branch }}, {{ worktree_path }}, etc.) and filters. {{+ base }} and {{ base_worktree_path }} require --create.Especially useful with shell aliases:- <b>alias wsc='wt switch --create -x claude'</b>- <b>wsc feature-branch -- 'Fix GH #322'</b>+ alias wsc='wt switch --create -x claude'+ wsc feature-branch -- 'Fix GH #322'- Then <b>wsc feature-branch</b> creates the worktree and launches Claude Code. Arguments after <b>--</b>- are passed to the command, so <b>wsc feature -- 'Fix GH #322'</b> runs <b>claude 'Fix GH #322'</b>,+ Then wsc feature-branch creates the worktree and launches Claude Code. Arguments after --+ are passed to the command, so wsc feature -- 'Fix GH #322' runs claude 'Fix GH #322',starting Claude with a prompt.- Template example: <b>-x 'code {{ worktree_path }}'</b> opens VS Code at the worktree, <b>-x 'tmux</b>-<b> new -s {{ branch | sanitize }}'</b> starts a tmux session named after the branch.+ Template example: -x 'code {{ worktree_path }}' opens VS Code at the worktree, -x 'tmux+ new -s {{ branch | sanitize }}' starts a tmux session named after the branch.- <b><span class=c>--clobber</span></b>+ --clobberRemove stale paths at target- <b><span class=c>--no-cd</span></b>+ --no-cdSkip directory change after switchingHooks still run normally. Useful when hooks handle navigation (e.g., tmux workflows) or@@ -169,29 +170,30 @@ Usage: <b><span class=c>wt switch</span></b> <span class=c>[OPTIONS]</span> <spaIn picker mode (no branch argument), prints the selected branch name and exits withoutswitching. Useful for scripting.- <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>- Print help (see a summary with '-h')+ -h, --help+ Print help (see a summary with '-h')-<b><span class=g>Picker Options:</span></b>- <b><span class=c>--branches</span></b>+Picker Options:+ --branchesInclude branches without worktrees- <b><span class=c>--remotes</span></b>+ --remotesInclude remote branches-<b><span class=g>Automation:</span></b>- <b><span class=c>-y</span></b>, <b><span class=c>--yes</span></b>+Automation:+ -y, --yesSkip approval prompts- <b><span class=c>--no-verify</span></b>+ --no-verifySkip hooks-<b><span class=g>Global Options:</span></b>- <b><span class=c>-C</span></b><span class=c> <path></span>+Global Options:+ -C <path>Working directory for this command- <b><span class=c>--config</span></b><span class=c> <path></span>+ --config <path>User config file path- <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>+ -v, --verbose...Verbose output (-v: hooks, templates; -vv: debug report)+```diff --git a/skills/worktrunk/reference/worktrunk.md b/skills/worktrunk/reference/worktrunk.mdindex 817ad0b54..e717caff1 100644--- a/skills/worktrunk/reference/worktrunk.md+++ b/skills/worktrunk/reference/worktrunk.md@@ -39,27 +39,27 @@ Worktrees are addressed by branch name; paths are computed from a configurable t<tbody><tr><td>Switch worktrees</td>- <td>{% rawcode() %}wt switch feat{% end %}</td>- <td>{% rawcode() %}cd ../repo.feat{% end %}</td>+ <td>wt switch feat</td>+ <td>cd ../repo.feat</td></tr><tr><td>Create + start Claude</td>- <td>{% rawcode() %}wt switch -c -x claude feat{% end %}</td>- <td>{% rawcode() %}git worktree add -b feat ../repo.feat && \+ <td>wt switch -c -x claude feat</td>+ <td>git worktree add -b feat ../repo.feat && \cd ../repo.feat && \-claude{% end %}</td>+claude</td></tr><tr><td>Clean up</td>- <td>{% rawcode() %}wt remove{% end %}</td>- <td>{% rawcode() %}cd ../repo && \+ <td>wt remove</td>+ <td>cd ../repo && \git worktree remove ../repo.feat && \-git branch -d feat{% end %}</td>+git branch -d feat</td></tr><tr><td>List with status</td>- <td>{% rawcode() %}wt list{% end %}</td>- <td>{% rawcode() %}git worktree list{% end %} (paths only)</td>+ <td>wt list</td>+ <td>git worktree list (paths only)</td></tr></tbody></table>diff --git a/src/help.rs b/src/help.rsindex fbe078b10..2809ae81f 100644--- a/src/help.rs+++ b/src/help.rs@@ -77,7 +77,8 @@ pub fn maybe_handle_help_with_pager() -> bool {// Check for --help-page flag (output full doc page with frontmatter)if args.iter().any(|a| a == "--help-page") {- handle_help_page(&args);+ let plain = args.iter().any(|a| a == "--plain");+ handle_help_page(&args, plain);process::exit(0);}@@ -168,27 +169,34 @@ pub fn maybe_handle_help_with_pager() -> bool {}}-/// Get the help reference block for a command by invoking clap's help system.-///-/// Returns the usage/options/subcommands section without the after_long_help content.-/// If `width` is provided, wraps text at that width (for web docs); otherwise uses default.-/// Always preserves ANSI color codes for HTML conversion.-fn help_reference(command_path: &[&str], width: Option<usize>) -> String {- let output = help_reference_inner(command_path, width);- // Strip OSC 8 hyperlinks. Clap generates these from markdown links like [text](url),- // but web docs convert ANSI to HTML via ansi_to_html which only handles SGR codes- // (colors), not OSC sequences - hyperlinks leak through as garbage.- worktrunk::styling::strip_osc8_hyperlinks(&output)+/// Get the help reference block with configurable color output.+///+/// `ColorChoice::Always` produces ANSI codes for HTML conversion (web docs).+/// `ColorChoice::Never` produces plain text (skill reference files).+fn help_reference_with_color(+ command_path: &[&str],+ width: Option<usize>,+ color: ColorChoice,+) -> String {+ let output = help_reference_inner(command_path, width, color);+ if matches!(color, ColorChoice::Always) {+ // Strip OSC 8 hyperlinks. Clap generates these from markdown links like [text](url),+ // but web docs convert ANSI to HTML via ansi_to_html which only handles SGR codes+ // (colors), not OSC sequences - hyperlinks leak through as garbage.+ worktrunk::styling::strip_osc8_hyperlinks(&output)+ } else {+ output+ }}-fn help_reference_inner(command_path: &[&str], width: Option<usize>) -> String {+fn help_reference_inner(command_path: &[&str], width: Option<usize>, color: ColorChoice) -> String {// Build args: ["wt", "config", "create", "--help"]let mut args: Vec<String> = vec!["wt".to_string()];args.extend(command_path.iter().map(|s| s.to_string()));args.push("--help".to_string());let mut cmd = cli::build_command();- cmd = cmd.color(ColorChoice::Always);+ cmd = cmd.color(color);if let Some(w) = width {cmd = cmd.term_width(w);}@@ -199,7 +207,13 @@ fn help_reference_inner(command_path: &[&str], width: Option<usize>) -> String {ErrorKind::DisplayHelp | ErrorKind::DisplayHelpOnMissingArgumentOrSubcommand) {let rendered = err.render();- let text = rendered.ansi().to_string();+ // .ansi() preserves ANSI codes; .to_string() strips them.+ // Use .ansi() only when colors are enabled (for web HTML conversion).+ let text = if matches!(color, ColorChoice::Always) {+ rendered.ansi().to_string()+ } else {+ rendered.to_string()+ };text.replace("```text\n", "```\n").replace("```console\n", "```bash\n")} else {@@ -336,7 +350,7 @@ fn handle_help_description(args: &[String]) {/// ```////// This is used to generate docs/content/merge.md etc from the source.-fn handle_help_page(args: &[String]) {+fn handle_help_page(args: &[String], plain: bool) {let mut cmd = cli::build_command();cmd = cmd.color(ColorChoice::Never);@@ -369,7 +383,13 @@ Commands with pages: merge, switch, remove, list"// Subdocs are expanded separately so main Command reference comes firstlet parent_name = format!("wt {}", subcommand);let raw_help = combine_command_docs(sub);- let raw_help = convert_dollar_console_to_terminal(&raw_help);+ // Web mode: convert $ code blocks to Zola terminal shortcodes+ // Plain mode: skip shortcode conversion (skills consume plain markdown)+ let raw_help = if plain {+ raw_help+ } else {+ convert_dollar_console_to_terminal(&raw_help)+ };let raw_help = raw_help.replace("```console\n", "```bash\n");// Split content at first subdoc placeholder@@ -381,22 +401,38 @@ Commands with pages: merge, switch, remove, list"};// Process main content (before subdocs)- let main_help = {+ // Web mode: expand demo GIFs and convert CLI markers to HTML+ // Plain mode: skip HTML transforms (skills consume plain markdown)+ let main_help = if plain {+ strip_demo_placeholders(main_content)+ } else {let text = expand_demo_placeholders(main_content);post_process_for_html(&text)};- // Get the help reference block (wrap at 100 chars for web docs, with colors for HTML)- let reference_block = help_reference(&[subcommand], Some(100));+ // Get the help reference block (wrap at 100 chars, with colors for HTML in web mode)+ let reference_block = help_reference_with_color(+ &[subcommand],+ Some(100),+ if plain {+ ColorChoice::Never+ } else {+ ColorChoice::Always+ },+ );- // Output the generated content (frontmatter is in skeleton files)- // Uses region markers so sync can replace just this content- // END tag mirrors the ID for unambiguous matching with nested markers// Use std::println! to preserve ANSI codes in output (the styling::println strips them)- std::println!(- "<!-- ⚠️ AUTO-GENERATED from `wt {subcommand} --help-page` — edit cli.rs to update -->"- );- std::println!();+ if plain {+ // Plain mode: H1 title, no AUTO-GENERATED markers+ std::println!("# wt {subcommand}");+ std::println!();+ } else {+ // Web mode: region markers for sync replacement (frontmatter is in skeleton files)+ std::println!(+ "<!-- ⚠️ AUTO-GENERATED from `wt {subcommand} --help-page` — edit cli.rs to update -->"+ );+ std::println!();+ }std::println!("{}", main_help.trim());std::println!();@@ -410,20 +446,26 @@ Commands with pages: merge, switch, remove, list"// Subdocs follow, each with their own command reference at the end.if let Some(subdocs) = subdoc_content {- // Apply post-processing to non-marker text (e.g., the Aliases section after- // the last subdoc marker). Must happen before expansion — after expansion,- // post_process_for_html has already run on each subcommand section internally- // (in format_subcommand_section), so re-running it would double-convert.- let subdocs = post_process_for_html(subdocs);- let subdocs_expanded = expand_subdoc_placeholders(&subdocs, sub, &parent_name);+ let subdocs = if plain {+ subdocs.to_string()+ } else {+ // Apply post-processing to non-marker text (e.g., the Aliases section after+ // the last subdoc marker). Must happen before expansion — after expansion,+ // post_process_for_html has already run on each subcommand section internally+ // (in format_subcommand_section), so re-running it would double-convert.+ post_process_for_html(subdocs)+ };+ let subdocs_expanded = expand_subdoc_placeholders(&subdocs, sub, &parent_name, plain);std::println!();std::println!("# Subcommands");std::println!();std::println!("{}", subdocs_expanded.trim());}- std::println!();- std::println!("<!-- END AUTO-GENERATED from `wt {subcommand} --help-page` -->");+ if !plain {+ std::println!();+ std::println!("<!-- END AUTO-GENERATED from `wt {subcommand} --help-page` -->");+ }}/// Post-process CLI help content for web docs rendering.@@ -587,7 +629,12 @@ fn increase_heading_levels(content: &str) -> String {/// ```////// This allows including subcommand documentation inline in the parent command's docs page.-fn expand_subdoc_placeholders(text: &str, parent_cmd: &clap::Command, parent_name: &str) -> String {+fn expand_subdoc_placeholders(+ text: &str,+ parent_cmd: &clap::Command,+ parent_name: &str,+ plain: bool,+) -> String {const PREFIX: &str = "<!-- subdoc: ";const SUFFIX: &str = " -->";@@ -603,7 +650,7 @@ fn expand_subdoc_placeholders(text: &str, parent_cmd: &clap::Command, parent_nam.get_subcommands().find(|s| s.get_name() == subcommand_name){- format_subcommand_section(sub, parent_name, subcommand_name)+ format_subcommand_section(sub, parent_name, subcommand_name, plain)} else {format!("<!-- subdoc error: subcommand '{}' not found -->",@@ -651,6 +698,7 @@ fn format_subcommand_section(sub: &clap::Command,parent_name: &str,subcommand_name: &str,+ plain: bool,) -> String {// parent_name is "wt config", subcommand_name is "create"// full_command is "wt config create"@@ -658,12 +706,16 @@ fn format_subcommand_section(// Get combined docs: about + subtitle + after_long_helplet raw_help = combine_command_docs(sub);- let raw_help = convert_dollar_console_to_terminal(&raw_help);+ let raw_help = if plain {+ raw_help+ } else {+ convert_dollar_console_to_terminal(&raw_help)+ };let raw_help = raw_help.replace("```console\n", "```bash\n");// Extract [experimental] marker from content start → badge after heading.- // Placed after the heading (not inside it) so Zola's anchor link doesn't- // wrap the badge. CSS positions it inline with the heading text.+ // Web mode: placed after heading as HTML badge so Zola's anchor link doesn't wrap it.+ // Plain mode: kept as [experimental] text.let (has_experimental, raw_help) = if let Some(rest) = raw_help.strip_prefix("[experimental] "){(true, rest.to_string())@@ -680,7 +732,10 @@ fn format_subcommand_section(};// Process main content (before any nested subdocs)- let main_help = {+ let main_help = if plain {+ let text = increase_heading_levels(main_content);+ strip_demo_placeholders(&text)+ } else {let text = increase_heading_levels(main_content);post_process_for_html(&text)};@@ -693,13 +748,25 @@ fn format_subcommand_section(.chain(std::iter::once(subcommand_name)).collect();- // Get help reference (wrap at 100 chars for web docs, with colors for HTML)- let reference_block = help_reference(&command_path, Some(100));+ // Get help reference with colors for web HTML conversion, plain text for skills+ let reference_block = help_reference_with_color(+ &command_path,+ Some(100),+ if plain {+ ColorChoice::Never+ } else {+ ColorChoice::Always+ },+ );// Format the section: heading, badge (outside heading), main content, command referencelet mut section = format!("## {full_command}\n\n");if has_experimental {- section.push_str("<span class=\"badge-experimental\"></span>\n\n");+ if plain {+ section.push_str("[experimental]\n\n");+ } else {+ section.push_str("<span class=\"badge-experimental\"></span>\n\n");+ }}if !main_help.is_empty() {@@ -714,8 +781,12 @@ fn format_subcommand_section(// Expand nested subdocs after the command reference.if let Some(subdocs) = subdoc_content {- let subdocs = post_process_for_html(subdocs);- let subdocs_expanded = expand_subdoc_placeholders(&subdocs, sub, &full_command);+ let subdocs = if plain {+ subdocs.to_string()+ } else {+ post_process_for_html(subdocs)+ };+ let subdocs_expanded = expand_subdoc_placeholders(&subdocs, sub, &full_command, plain);section.push('\n');section.push_str(subdocs_expanded.trim());section.push('\n');@@ -772,3 +843,30 @@ fn expand_demo_placeholders(text: &str) -> String {}result}++/// Strip demo GIF placeholders from content (for plain/skill output).+///+/// Removes `<!-- demo: filename.gif -->` lines entirely. These are invisible in+/// terminal --help but would leak as HTML comments in skill reference files.+fn strip_demo_placeholders(text: &str) -> String {+ const PREFIX: &str = "<!-- demo: ";+ const SUFFIX: &str = " -->";++ let mut result = text.to_string();+ while let Some(start) = result.find(PREFIX) {+ let after_prefix = start + PREFIX.len();+ if let Some(end_offset) = result[after_prefix..].find(SUFFIX) {+ let end = after_prefix + end_offset + SUFFIX.len();+ // Also strip trailing newline if present+ let end = if result[end..].starts_with('\n') {+ end + 1+ } else {+ end+ };+ result.replace_range(start..end, "");+ } else {+ break;+ }+ }+ result+}diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rsindex 49cd1cfcb..23121e062 100644--- a/tests/integration_tests/readme_sync.rs+++ b/tests/integration_tests/readme_sync.rs@@ -1787,7 +1787,9 @@ fn transform_docs_for_skill(content: &str) -> String {let converted = SPAN_CMD_TO_DOLLAR.replace_all(body, "$$ $1");format!("```bash\n{converted}```")}- None => body.to_string(),+ // Terminal bodies without cmd are styled CLI output demos (colored+ // spans, bold text). Strip HTML to plain text for skill files.+ None => strip_html(body),}});let content = ZOLA_TERMINAL_SELF_CLOSING_PATTERN@@ -1795,6 +1797,9 @@ fn transform_docs_for_skill(content: &str) -> String {cmd_to_bash_block(caps.get(1).map_or("", |m| m.as_str()), "")});+ // Strip rawcode shortcodes (keep content)+ let content = ZOLA_RAWCODE_PATTERN.replace_all(&content, "$1");+// Replace placeholders used to escape Tera template syntax in cmd parameterslet content = content.replace("__WT_OPEN2__", "{{")@@ -1814,38 +1819,15 @@ fn transform_docs_for_skill(content: &str) -> String {"[experimental]",);- // Transform Zola internal links to full URLs- let content = ZOLA_LINK_PATTERN- .replace_all(&content, |caps: ®ex::Captures| {- let text = caps.get(1).unwrap().as_str();- let page = caps.get(2).unwrap().as_str();- let anchor = caps.get(3).map_or("", |m| m.as_str());- format!("[{text}](https://worktrunk.dev/{page}/{anchor})")- })- .into_owned();-- // Remove "See also" section (just contains links to other pages)- let content = remove_section(&content, "## See also");-- // Clean up multiple consecutive blank lines- let content = content- .lines()- .fold((Vec::new(), false), |(mut acc, prev_blank), line| {- let is_blank = line.trim().is_empty();- if !(is_blank && prev_blank) {- acc.push(line);- }- (acc, is_blank)- })- .0- .join("\n");-// Prepend title as H1 if extracted- if let Some(title) = title {+ let content = if let Some(title) = title {format!("# {}\n\n{}", title, content.trim())} else {content.trim().to_string()- }+ };++ // Apply shared finalization: Zola links, See also removal, blank line cleanup+ finalize_skill_content(&content)}/// Remove a section from markdown content (from heading to next same-level heading)@@ -1924,19 +1906,29 @@ fn sync_skill_files(project_root: &Path) -> (Vec<String>, Vec<String>) {entries.sort();for name in &entries {- let docs_file = docs_dir.join(name);let skill_file = skill_dir.join(name);-- if !docs_file.exists() {- errors.push(format!("Missing docs file: {}", docs_file.display()));- continue;- }-- let docs_content = fs::read_to_string(&docs_file)- .unwrap_or_else(|e| panic!("Failed to read {}: {}", docs_file.display(), e));-- // Transform and use content directly (docs already have proper H1 titles)- let expected = transform_docs_for_skill(&docs_content);+ let cmd_name = name.trim_end_matches(".md");++ let expected = if COMMAND_PAGES.contains(&cmd_name) {+ // Command pages: generate directly from --help-page --plain (no HTML)+ match generate_skill_from_help(cmd_name, project_root) {+ Ok(content) => content,+ Err(e) => {+ errors.push(e);+ continue;+ }+ }+ } else {+ // Non-command pages: read from docs, transform Zola syntax, strip residual HTML+ let docs_file = docs_dir.join(name);+ if !docs_file.exists() {+ errors.push(format!("Missing docs file: {}", docs_file.display()));+ continue;+ }+ let docs_content = fs::read_to_string(&docs_file)+ .unwrap_or_else(|e| panic!("Failed to read {}: {}", docs_file.display(), e));+ transform_docs_for_skill(&docs_content)+ };let expected = trim_lines(&expected);let current = if skill_file.exists() {@@ -1963,6 +1955,68 @@ fn sync_skill_files(project_root: &Path) -> (Vec<String>, Vec<String>) {(errors, updated_files)}+/// Generate a skill reference file directly from `--help-page --plain` output.+///+/// For command pages, this produces clean markdown without HTML. The only+/// post-processing needed is Zola link transformation and section cleanup.+fn generate_skill_from_help(cmd: &str, project_root: &Path) -> Result<String, String> {+ let output = wt_command()+ .args([cmd, "--help-page", "--plain"])+ .current_dir(project_root)+ .output()+ .expect("Failed to run wt --help-page --plain");++ if !output.status.success() {+ return Err(format!(+ "'wt {} --help-page --plain' failed (exit {}): {}",+ cmd,+ output.status.code().unwrap_or(-1),+ String::from_utf8_lossy(&output.stderr)+ ));+ }++ let content = String::from_utf8_lossy(&output.stdout).to_string();+ if content.trim().is_empty() {+ return Err(format!(+ "Empty output from 'wt {} --help-page --plain': {}",+ cmd,+ String::from_utf8_lossy(&output.stderr)+ ));+ }++ Ok(finalize_skill_content(&content))+}++/// Apply final transforms shared between command and non-command skill files:+/// Zola internal links → full URLs, remove "See also" section, collapse blank lines.+fn finalize_skill_content(content: &str) -> String {+ // Transform Zola internal links to full URLs+ let content = ZOLA_LINK_PATTERN+ .replace_all(content, |caps: ®ex::Captures| {+ let text = caps.get(1).unwrap().as_str();+ let page = caps.get(2).unwrap().as_str();+ let anchor = caps.get(3).map_or("", |m| m.as_str());+ format!("[{text}](https://worktrunk.dev/{page}/{anchor})")+ })+ .into_owned();++ // Remove "See also" section (just contains links to other pages)+ let content = remove_section(&content, "## See also");++ // Clean up multiple consecutive blank lines+ content+ .lines()+ .fold((Vec::new(), false), |(mut acc, prev_blank), line| {+ let is_blank = line.trim().is_empty();+ if !(is_blank && prev_blank) {+ acc.push(line);+ }+ (acc, is_blank)+ })+ .0+ .join("\n")+}+/// Sync .well-known/agent-skills/ index.json and verify symlink.////// The skill files are served via a symlink: