Skip to content

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.md
index 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 configs
Includes shell integration, hooks, and saved state.
-Usage: <b><span class=c>wt config</span></b> <span class=c>[OPTIONS]</span> <span class=c>&lt;COMMAND&gt;</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 &amp; 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 &#39;-h&#39;)
+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> &lt;path&gt;</span>
+Global Options:
+ -C <path>
Working directory for this command
- <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</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 &amp; 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:
+ --full
Run 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 &#39;-h&#39;)
+ -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> &lt;path&gt;</span>
+Global Options:
+ -C <path>
Working directory for this command
- <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</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>&lt;COMMAND&gt;</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 &#39;-h&#39;)
-
-<b><span class=g>Global Options:</span></b>
- <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</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> &lt;path&gt;</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 &#39;-h&#39;)
+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> &lt;path&gt;</span>
+Global Options:
+ -C <path>
Working directory for this command
- <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</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 &#39;-h&#39;)
+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> &lt;path&gt;</span>
+Global Options:
+ -C <path>
Working directory for this command
- <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</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 &#39;-h&#39;)
+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> &lt;path&gt;</span>
+Global Options:
+ -C <path>
Working directory for this command
- <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</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>&lt;COMMAND&gt;</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 &#39;-h&#39;)
+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> &lt;path&gt;</span>
+Global Options:
+ -C <path>
Working directory for this command
- <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</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 &#39;-h&#39;)
+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> &lt;path&gt;</span>
+Global Options:
+ -C <path>
Working directory for this command
- <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</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.md
index 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.md
index 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-m
Project 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>&lt;COMMAND&gt;</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 &#39;-h&#39;)
-
-<b><span class=g>Global Options:</span></b>
- <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</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> &lt;path&gt;</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>&lt;COMMAND&gt;</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 &#39;-h&#39;)
+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> &lt;path&gt;</span>
+Global Options:
+ -C <path>
Working directory for this command
- <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</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.md
index 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>&lt;COMMAND&gt;</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> &lt;FORMAT&gt;</span>
+Options:
+ --format <FORMAT>
Output format (table, json)
[default: table]
- <b><span class=c>--branches</span></b>
+ --branches
Include branches without worktrees
- <b><span class=c>--remotes</span></b>
+ --remotes
Include remote branches
- <b><span class=c>--full</span></b>
+ --full
Show CI, diff analysis, and LLM summaries
- <b><span class=c>--progressive</span></b>
+ --progressive
Show fast info immediately, update with slow info
Displays local data (branches, paths, status) first, then updates with remote data (CI,
upstream) as it arrives. Use --no-progressive to force buffered rendering. Auto-enabled
for TTY.
- <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>
- Print help (see a summary with &#39;-h&#39;)
+ -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> &lt;path&gt;</span>
+Global Options:
+ -C <path>
Working directory for this command
- <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</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.md
index 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 &amp; 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 branch
Defaults to default branch.
-<b><span class=g>Options:</span></b>
- <b><span class=c>--no-squash</span></b>
+Options:
+ --no-squash
Skip commit squashing
- <b><span class=c>--no-commit</span></b>
+ --no-commit
Skip commit and squash
- <b><span class=c>--no-rebase</span></b>
+ --no-rebase
Skip rebase (fail if not already rebased)
- <b><span class=c>--no-remove</span></b>
+ --no-remove
Keep worktree after merge
- <b><span class=c>--no-ff</span></b>
+ --no-ff
Create a merge commit (no fast-forward)
- <b><span class=c>--stage</span></b><span class=c> &lt;STAGE&gt;</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&#39;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 &#39;-h&#39;)
+ -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, --yes
Skip approval prompts
- <b><span class=c>--no-verify</span></b>
+ --no-verify
Skip hooks
-<b><span class=g>Global Options:</span></b>
- <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
+Global Options:
+ -C <path>
Working directory for this command
- <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</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.md
index 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 merged
Defaults 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-branch
Keep branch after removal
- <b><span class=c>-D</span></b>, <b><span class=c>--force-delete</span></b>
+ -D, --force-delete
Delete unmerged branches
- <b><span class=c>--foreground</span></b>
+ --foreground
Run removal in foreground (block until complete)
- <b><span class=c>-f</span></b>, <b><span class=c>--force</span></b>
+ -f, --force
Force worktree removal
Remove worktrees even if they contain untracked files (like build artifacts). Without this
flag, 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 &#39;-h&#39;)
+ -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, --yes
Skip approval prompts
- <b><span class=c>--no-verify</span></b>
+ --no-verify
Skip hooks
-<b><span class=g>Global Options:</span></b>
- <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
+Global Options:
+ -C <path>
Working directory for this command
- <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</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.md
index 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>&lt;COMMAND&gt;</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 &#39;-h&#39;)
-
-<b><span class=g>Global Options:</span></b>
- <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</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> &lt;path&gt;</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> &lt;BRANCH&gt;</span>
+Options:
+ -b, --branch <BRANCH>
Branch to operate on (defaults to current worktree)
- <b><span class=c>--stage</span></b><span class=c> &lt;STAGE&gt;</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&#39;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-prompt
Show prompt without running LLM
Outputs 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 &#39;-h&#39;)
+ -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, --yes
Skip approval prompts
- <b><span class=c>--no-verify</span></b>
+ --no-verify
Skip hooks
-<b><span class=g>Global Options:</span></b>
- <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
+Global Options:
+ -C <path>
Working directory for this command
- <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</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 branching
Stages 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 branch
Defaults to default branch.
-<b><span class=g>Options:</span></b>
- <b><span class=c>--stage</span></b><span class=c> &lt;STAGE&gt;</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&#39;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-prompt
Show prompt without running LLM
Outputs 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 &#39;-h&#39;)
+ -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, --yes
Skip approval prompts
- <b><span class=c>--no-verify</span></b>
+ --no-verify
Skip hooks
-<b><span class=g>Global Options:</span></b>
- <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
+Global Options:
+ -C <path>
Working directory for this command
- <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</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 branching
Includes 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>&lt;EXTRA_ARGS&gt;...</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 branch
Defaults 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 &#39;-h&#39;)
+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> &lt;path&gt;</span>
+Global Options:
+ -C <path>
Working directory for this command
- <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</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 worktree
Eliminates 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> &lt;FROM&gt;</span>
+Options:
+ --from <FROM>
Source worktree branch
Defaults to main worktree.
- <b><span class=c>--to</span></b><span class=c> &lt;TO&gt;</span>
+ --to <TO>
Destination worktree branch
Defaults to current worktree.
- <b><span class=c>--dry-run</span></b>
+ --dry-run
Show what would be copied
- <b><span class=c>--force</span></b>
+ --force
Overwrite existing files in destination
- <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>
- Print help (see a summary with &#39;-h&#39;)
+ -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> &lt;path&gt;</span>
+Global Options:
+ -C <path>
Working directory for this command
- <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</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 expression
Prints 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>&lt;TEMPLATE&gt;</span>
+Usage: wt step eval [OPTIONS] <TEMPLATE>
-<b><span class=g>Arguments:</span></b>
- <span class=c>&lt;TEMPLATE&gt;</span>
+Arguments:
+ <TEMPLATE>
Template expression to evaluate
-<b><span class=g>Options:</span></b>
- <b><span class=c>--dry-run</span></b>
+Options:
+ --dry-run
Show 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 &#39;-h&#39;)
+ -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> &lt;path&gt;</span>
+Global Options:
+ -C <path>
Working directory for this command
- <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</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 worktree
Executes 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>&lt;ARGS&gt;...</span>
+Usage: wt step for-each [OPTIONS] -- <ARGS>...
-<b><span class=g>Arguments:</span></b>
- <span class=c>&lt;ARGS&gt;...</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 &#39;-h&#39;)
+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> &lt;path&gt;</span>
+Global Options:
+ -C <path>
Working directory for this command
- <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</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 worktree
Exchanges 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 worktree
Defaults 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 &#39;-h&#39;)
+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> &lt;path&gt;</span>
+Global Options:
+ -C <path>
Working directory for this command
- <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</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-run
Show what would be removed
- <b><span class=c>--min-age</span></b><span class=c> &lt;MIN_AGE&gt;</span>
+ --min-age <MIN_AGE>
Skip worktrees younger than this
[default: 1h]
- <b><span class=c>--foreground</span></b>
+ --foreground
Run 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 &#39;-h&#39;)
+ -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, --yes
Skip approval prompts
-<b><span class=g>Global Options:</span></b>
- <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
+Global Options:
+ -C <path>
Working directory for this command
- <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</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&#39;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-run
Show what would be moved
- <b><span class=c>--commit</span></b>
+ --commit
Commit uncommitted changes before relocating
- <b><span class=c>--clobber</span></b>
+ --clobber
Backup non-worktree paths at target locations
- Moves blocking paths to <b>&lt;path&gt;.bak-&lt;timestamp&gt;</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 &#39;-h&#39;)
+ -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> &lt;path&gt;</span>
+Global Options:
+ -C <path>
Working directory for this command
- <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</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.md
index 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>&lt;EXECUTE_ARGS&gt;...</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: &#39;^&#39; (default branch), &#39;-&#39; (previous), &#39;@&#39;
- (current), &#39;pr:{N}&#39; (GitHub PR), &#39;mr:{N}&#39; (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 for
templates, 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, --create
Create a new branch
- <b><span class=c>-b</span></b>, <b><span class=c>--base</span></b><span class=c> &lt;BASE&gt;</span>
+ -b, --base <BASE>
Base branch
Defaults to default branch.
- <b><span class=c>-x</span></b>, <b><span class=c>--execute</span></b><span class=c> &lt;EXECUTE&gt;</span>
+ -x, --execute <EXECUTE>
Command to run after switch
Replaces 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=&#39;wt switch --create -x claude&#39;</b>
- <b>wsc feature-branch -- &#39;Fix GH #322&#39;</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 -- &#39;Fix GH #322&#39;</b> runs <b>claude &#39;Fix GH #322&#39;</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 &#39;code {{ worktree_path }}&#39;</b> opens VS Code at the worktree, <b>-x &#39;tmux</b>
-<b> new -s {{ branch | sanitize }}&#39;</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>
+ --clobber
Remove stale paths at target
- <b><span class=c>--no-cd</span></b>
+ --no-cd
Skip directory change after switching
Hooks 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> <spa
In picker mode (no branch argument), prints the selected branch name and exits without
switching. Useful for scripting.
- <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>
- Print help (see a summary with &#39;-h&#39;)
+ -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:
+ --branches
Include branches without worktrees
- <b><span class=c>--remotes</span></b>
+ --remotes
Include 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, --yes
Skip approval prompts
- <b><span class=c>--no-verify</span></b>
+ --no-verify
Skip hooks
-<b><span class=g>Global Options:</span></b>
- <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
+Global Options:
+ -C <path>
Working directory for this command
- <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</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.md
index 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.rs
index 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 first
let 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_help
let 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 reference
let 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.rs
index 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 parameters
let 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: &regex::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: &regex::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: