Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
Syntect highlighting for template expression blocks (#1792)
Maximilian Roosbd9b9fe29352
diff --git a/docs/CLAUDE.md b/docs/CLAUDE.mdindex e45717b03..fadbfef28 100644--- a/docs/CLAUDE.md+++ b/docs/CLAUDE.md@@ -226,11 +226,12 @@ All shell commands use `$ ` prefix in `` ```console `` blocks. `convert_dollar_c| Detected pattern | Web output | Highlighting ||------------------|------------|--------------|-| Any `$ ` commands, no `{{ }}` | `cmd` parameter with `\|\|\|` delimiter | Full Syntect |-| `{{ }}` in command | `{% terminal() %}` with `<span class="cmd">` body | Accent color only |+| `$ ` commands | `cmd` parameter with `\|\|\|` delimiter | Full Syntect || No `$ ` | `console` → `bash` conversion | Syntect (no `$ ` prompt) |-The `cmd` parameter supports multiple commands joined by `|||`. The template splits, highlights each through Syntect individually, and wraps commands in `<span class="cmd">` (CSS `::before` adds `$ `). Comment lines (`#`) are highlighted but not wrapped (no prompt).+All `$ ` commands go through the `cmd` parameter path for consistent Syntect highlighting. Multiple commands are joined by `|||`; the template splits and highlights each individually. Commands are wrapped in `<span class="cmd">` (CSS `::before` adds `$ `). Comment lines (`#`) are highlighted but not wrapped (no prompt).++**Placeholders in cmd values:** Tera (Zola's template engine) would interpret `{{ }}` in the `cmd` parameter as template expressions, and `"` would close the parameter string. Since Tera has no backslash-escape mechanism for string literals, these characters are replaced with text placeholders (`__WT_OPEN2__`, `__WT_CLOSE2__`, `__WT_QUOT__`) in the Rust conversion function. The terminal shortcode template replaces them back before Syntect highlighting. The sync test also strips them when generating skill reference files.Hand-written docs can use either `console` fences with `$ ` (auto-converted by the sync test) or shortcodes directly.@@ -249,7 +250,7 @@ The `--help-page` generator in `src/main.rs` applies post-processing to transfor| CLI Source | Web Output ||------------|------------|-| `` ```console `` with `$ ` | `{% terminal() %}` with `<span class="cmd">` |+| `` ```console `` with `$ ` | `terminal` shortcode with `cmd` parameter || `` ```console `` (no `$ `) | `` ```bash `` || `` `●` green `` | `<span style='color:#0a0'>●</span> green` || `` `●` blue `` | `<span style='color:#00a'>●</span> blue` |diff --git a/docs/content/config.md b/docs/content/config.mdindex bfcacf1c8..e07eaf69b 100644--- a/docs/content/config.md+++ b/docs/content/config.md@@ -409,7 +409,7 @@ Note the single underscore after `WORKTRUNK` and double underscores between nestOverride the LLM command in CI to use a mock:-{{ terminal(cmd="WORKTRUNK_COMMIT__GENERATION__COMMAND="echo 'test: automated commit'" wt merge") }}+{{ terminal(cmd="WORKTRUNK_COMMIT__GENERATION__COMMAND=__WT_QUOT__echo 'test: automated commit'__WT_QUOT__ wt merge") }}### Other environment variables@@ -527,7 +527,7 @@ Set the default branch manually:{{ terminal(cmd="wt config state default-branch set main") }}Set a marker for current branch:-{{ terminal(cmd="wt config state marker set "🚧 WIP"") }}+{{ terminal(cmd="wt config state marker set __WT_QUOT__🚧 WIP__WT_QUOT__") }}Clear all CI status cache:{{ terminal(cmd="wt config state ci-status clear --all") }}@@ -704,7 +704,7 @@ bugfix 🤖!↑⇡ ~/code/myproject.bugfixStored in git config as `worktrunk.state.<branch>.marker`. Set directly with:-{{ terminal(cmd="git config worktrunk.state.feature.marker '{"marker":"🚧","set_at":0}'") }}+{{ terminal(cmd="git config worktrunk.state.feature.marker '{__WT_QUOT__marker__WT_QUOT__:__WT_QUOT__🚧__WT_QUOT__,__WT_QUOT__set_at__WT_QUOT__:0}'") }}Without a subcommand, runs `get` for the current branch. For `--branch`, use `get --branch=NAME`.@@ -777,7 +777,7 @@ Query the command log:{{ terminal(cmd="tail -5 .git/wt/logs/commands.jsonl | jq .") }}View a specific hook log:-{{ terminal(cmd="cat "$(git rev-parse --git-dir)/wt/logs/feature-project-post-start-build.log"") }}+{{ terminal(cmd="cat __WT_QUOT__$(git rev-parse --git-dir)/wt/logs/feature-project-post-start-build.log__WT_QUOT__") }}Clear all logs:{{ terminal(cmd="wt config state logs clear") }}diff --git a/docs/content/hook.md b/docs/content/hook.mdindex bfce919d1..bf199a0fd 100644--- a/docs/content/hook.md+++ b/docs/content/hook.md@@ -199,7 +199,7 @@ if ctx['branch'].startswith('feature/') and 'backend' in ctx['repo']:`wt hook <type>` runs hooks on demand — useful for testing during development, running in CI pipelines, or re-running after a failure.-{{ terminal(cmd="wt hook pre-merge # Run all pre-merge hooks|||wt hook pre-merge test # Run hooks named "test" from both sources|||wt hook pre-merge user: # Run all user hooks|||wt hook pre-merge project: # Run all project hooks|||wt hook pre-merge user:test # Run only user's "test" hook|||wt hook pre-merge project:test # Run only project's "test" hook|||wt hook pre-merge --yes # Skip approval prompts (for CI)|||wt hook pre-start --var branch=feature/test # Override template variable") }}+{{ terminal(cmd="wt hook pre-merge # Run all pre-merge hooks|||wt hook pre-merge test # Run hooks named __WT_QUOT__test__WT_QUOT__ from both sources|||wt hook pre-merge user: # Run all user hooks|||wt hook pre-merge project: # Run all project hooks|||wt hook pre-merge user:test # Run only user's __WT_QUOT__test__WT_QUOT__ hook|||wt hook pre-merge project:test # Run only project's __WT_QUOT__test__WT_QUOT__ hook|||wt hook pre-merge --yes # Skip approval prompts (for CI)|||wt hook pre-start --var branch=feature/test # Override template variable") }}The `user:` and `project:` prefixes filter by source. Use `user:` or `project:` alone to run all hooks from that source, or `user:name` / `project:name` to run a specific hook.diff --git a/docs/content/list.md b/docs/content/list.mdindex be1e82c47..01febe9bb 100644--- a/docs/content/list.md+++ b/docs/content/list.md@@ -136,7 +136,7 @@ These appear across all columns while the table is loading:Query structured data with `--format=json`:-{{ terminal(cmd="# Current worktree path (for scripts)|||wt list --format=json | jq -r '.[] | select(.is_current) | .path'||||||# Branches with uncommitted changes|||wt list --format=json | jq '.[] | select(.working_tree.modified)'||||||# Worktrees with merge conflicts|||wt list --format=json | jq '.[] | select(.operation_state == "conflicts")'||||||# Branches ahead of main (needs merging)|||wt list --format=json | jq '.[] | select(.main.ahead > 0) | .branch'||||||# Integrated branches (safe to remove)|||wt list --format=json | jq '.[] | select(.main_state == "integrated" or .main_state == "empty") | .branch'||||||# Branches without worktrees|||wt list --format=json --branches | jq '.[] | select(.kind == "branch") | .branch'||||||# Worktrees ahead of remote (needs pushing)|||wt list --format=json | jq '.[] | select(.remote.ahead > 0) | {branch, ahead: .remote.ahead}'||||||# Stale CI (local changes not reflected in CI)|||wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'") }}+{{ terminal(cmd="# Current worktree path (for scripts)|||wt list --format=json | jq -r '.[] | select(.is_current) | .path'||||||# Branches with uncommitted changes|||wt list --format=json | jq '.[] | select(.working_tree.modified)'||||||# Worktrees with merge conflicts|||wt list --format=json | jq '.[] | select(.operation_state == __WT_QUOT__conflicts__WT_QUOT__)'||||||# Branches ahead of main (needs merging)|||wt list --format=json | jq '.[] | select(.main.ahead > 0) | .branch'||||||# Integrated branches (safe to remove)|||wt list --format=json | jq '.[] | select(.main_state == __WT_QUOT__integrated__WT_QUOT__ or .main_state == __WT_QUOT__empty__WT_QUOT__) | .branch'||||||# Branches without worktrees|||wt list --format=json --branches | jq '.[] | select(.kind == __WT_QUOT__branch__WT_QUOT__) | .branch'||||||# Worktrees ahead of remote (needs pushing)|||wt list --format=json | jq '.[] | select(.remote.ahead > 0) | {branch, ahead: .remote.ahead}'||||||# Stale CI (local changes not reflected in CI)|||wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'") }}**Fields:**diff --git a/docs/content/step.md b/docs/content/step.mdindex 10db87718..efec8fdff 100644--- a/docs/content/step.md+++ b/docs/content/step.md@@ -258,7 +258,7 @@ The diff is pipeable to tools like `delta`:Equivalent to:-{{ terminal(cmd="cp "$(git rev-parse --git-dir)/index" /tmp/idx|||GIT_INDEX_FILE=/tmp/idx git add --intent-to-add .|||GIT_INDEX_FILE=/tmp/idx git diff $(git merge-base HEAD $(wt config state default-branch))") }}+{{ terminal(cmd="cp __WT_QUOT__$(git rev-parse --git-dir)/index__WT_QUOT__ /tmp/idx|||GIT_INDEX_FILE=/tmp/idx git add --intent-to-add .|||GIT_INDEX_FILE=/tmp/idx git diff $(git merge-base HEAD $(wt config state default-branch))") }}`git diff` ignores untracked files. `git add --intent-to-add .` registers them in the index without staging their content, making them visible to `git diff`. This runs against a copy of the real index so the original is never modified.@@ -438,35 +438,29 @@ All [hook template variables and filters](@/hook.md#template-variables) are avaiGet the port for the current branch:-{% terminal() %}-<span class="cmd">wt step eval '{{ branch | hash_port }}'</span>+{% terminal(cmd="wt step eval '__WT_OPEN2__ branch | hash_port __WT_CLOSE2__'") %}16066{% end %}Use in shell substitution:-{% terminal() %}-<span class="cmd">curl http://localhost:$(wt step eval '{{ branch | hash_port }}')/health</span>-{% end %}+{{ terminal(cmd="curl http://localhost:$(wt step eval '__WT_OPEN2__ branch | hash_port __WT_CLOSE2__')/health") }}Combine multiple values:-{% terminal() %}-<span class="cmd">wt step eval '{{ branch | hash_port }},{{ ("supabase-api-" ~ branch) | hash_port }}'</span>+{% terminal(cmd="wt step eval '__WT_OPEN2__ branch | hash_port __WT_CLOSE2__,__WT_OPEN2__ (__WT_QUOT__supabase-api-__WT_QUOT__ ~ branch) | hash_port __WT_CLOSE2__'") %}16066,16739{% end %}Use conditionals and filters:-{% terminal() %}-<span class="cmd">wt step eval '{{ branch | sanitize_db }}'</span>+{% terminal(cmd="wt step eval '__WT_OPEN2__ branch | sanitize_db __WT_CLOSE2__'") %}feature_auth_oauth2_a1b{% end %}Show available template variables:-{% terminal() %}-<span class="cmd">wt step eval --dry-run '{{ branch }}'</span>+{% terminal(cmd="wt step eval --dry-run '__WT_OPEN2__ branch __WT_CLOSE2__'") %}branch=feature/auth-oauth2worktree_path=/home/user/projects/myapp-feature-auth-oauth2...@@ -530,13 +524,11 @@ Run npm install in all worktrees:Use branch name in command:-{% terminal() %}-<span class="cmd">wt step for-each -- "echo Branch: {{ branch }}"</span>-{% end %}+{{ terminal(cmd="wt step for-each -- __WT_QUOT__echo Branch: __WT_OPEN2__ branch __WT_CLOSE2____WT_QUOT__") }}Pull updates in worktrees with upstreams (skips others):-{{ terminal(cmd="git fetch --prune && wt step for-each -- '[ "$(git rev-parse @{u} 2>/dev/null)" ] || exit 0; git pull --autostash'") }}+{{ terminal(cmd="git fetch --prune && wt step for-each -- '[ __WT_QUOT__$(git rev-parse @{u} 2>/dev/null)__WT_QUOT__ ] || exit 0; git pull --autostash'") }}Note: This command is experimental and may change in future versions.diff --git a/docs/templates/shortcodes/terminal.html b/docs/templates/shortcodes/terminal.htmlindex c70593ffb..8f072b49e 100644--- a/docs/templates/shortcodes/terminal.html+++ b/docs/templates/shortcodes/terminal.html@@ -8,6 +8,7 @@{% endif %}<pre class="terminal"><code>{%- for cmd_line in cmd_lines -%}+{%- set cmd_line = cmd_line | replace(from="__WT_OPEN2__", to="{{") | replace(from="__WT_CLOSE2__", to="}}") | replace(from="__WT_QUOT__", to='"') -%}{%- set md = fence ~ "bash" ~ cmd_line ~ "" ~ fence -%}diff --git a/skills/worktrunk/reference/claude-code.md b/skills/worktrunk/reference/claude-code.mdindex 4255b4737..34d83adc5 100644--- a/skills/worktrunk/reference/claude-code.md+++ b/skills/worktrunk/reference/claude-code.md@@ -7,8 +7,10 @@ The worktrunk Claude Code plugin provides two features:## Installation-<span class="cmd">claude plugin marketplace add max-sixty/worktrunk</span>-<span class="cmd">claude plugin install worktrunk@worktrunk</span>+```bash+$ claude plugin marketplace add max-sixty/worktrunk+$ claude plugin install worktrunk@worktrunk+```## Configuration skill@@ -25,7 +27,8 @@ Claude Code is designed to load the skill automatically when it detects worktrunThe plugin tracks Claude sessions with status markers in `wt list`:-<span class="cmd">wt list</span>+```bash+$ wt list<b>Branch</b> <b>Status</b> <b>HEAD±</b> <b>main↕</b> <b>Remote⇅</b> <b>Path</b> <b>Commit</b> <b>Age</b> <b>Message</b>@ main <span class=d>^</span><span class=d>⇡</span> <span class=g>⇡1</span> . <span class=d>33323bc1</span> <span class=d>1d</span> <span class=d>Initial commit</span>+ feature-api <span class=d>↑</span> 🤖 <span class=g>↑1</span> ../repo.feature-api <span class=d>70343f03</span> <span class=d>1d</span> <span class=d>Add REST API endpoints</span>@@ -33,6 +36,7 @@ The plugin tracks Claude sessions with status markers in `wt list`:+ wip-docs <span class=c>?</span> <span class=d>–</span> ../repo.wip-docs <span class=d>33323bc1</span> <span class=d>1d</span> <span class=d>Initial commit</span><span class=d>○</span> <span class=d>Showing 4 worktrees, 2 with changes, 2 ahead</span>+```- 🤖 — Claude is working- 💬 — Claude is waiting for input@@ -41,9 +45,11 @@ The plugin tracks Claude sessions with status markers in `wt list`:Set status markers manually for any workflow:-<span class="cmd">wt config state marker set "🚧" # Current branch</span>-<span class="cmd">wt config state marker set "✅" --branch feature # Specific branch</span>-<span class="cmd">git config worktrunk.state.feature.marker '{"marker":"💬","set_at":0}' # Direct</span>+```bash+$ wt config state marker set "🚧" # Current branch+$ wt config state marker set "✅" --branch feature # Specific branch+$ git config worktrunk.state.feature.marker '{"marker":"💬","set_at":0}' # Direct+```## Statuslinediff --git a/skills/worktrunk/reference/config.md b/skills/worktrunk/reference/config.mdindex 5e5ab03aa..8d1599364 100644--- a/skills/worktrunk/reference/config.md+++ b/skills/worktrunk/reference/config.md@@ -411,7 +411,7 @@ Note the single underscore after `WORKTRUNK` and double underscores between nestOverride the LLM command in CI to use a mock:```bash-$ WORKTRUNK_COMMIT__GENERATION__COMMAND="echo 'test: automated commit'" wt merge+$ WORKTRUNK_COMMIT__GENERATION__COMMAND="echo 'test: automated commit'" wt merge```### Other environment variables@@ -533,7 +533,7 @@ $ wt config state default-branch set mainSet a marker for current branch:```bash-$ wt config state marker set "🚧 WIP"+$ wt config state marker set "🚧 WIP"```Clear all CI status cache:@@ -714,7 +714,7 @@ bugfix 🤖!↑⇡ ~/code/myproject.bugfixStored in git config as `worktrunk.state.<branch>.marker`. Set directly with:```bash-$ git config worktrunk.state.feature.marker '{"marker":"🚧","set_at":0}'+$ git config worktrunk.state.feature.marker '{"marker":"🚧","set_at":0}'```Without a subcommand, runs `get` for the current branch. For `--branch`, use `get --branch=NAME`.@@ -791,7 +791,7 @@ $ tail -5 .git/wt/logs/commands.jsonl | jq .View a specific hook log:```bash-$ cat "$(git rev-parse --git-dir)/wt/logs/feature-project-post-start-build.log"+$ cat "$(git rev-parse --git-dir)/wt/logs/feature-project-post-start-build.log"```Clear all logs:diff --git a/skills/worktrunk/reference/faq.md b/skills/worktrunk/reference/faq.mdindex 4f4f97760..b2a6c94ea 100644--- a/skills/worktrunk/reference/faq.md+++ b/skills/worktrunk/reference/faq.md@@ -10,20 +10,24 @@ Branch switching uses one directory: uncommitted changes from one agent get mixeGit's built-in worktree commands work but require manual lifecycle management:+```bash# Plain git worktree workflow-<span class="cmd">git worktree add -b feature-branch ../myapp-feature main</span>-<span class="cmd">cd ../myapp-feature</span>+$ git worktree add -b feature-branch ../myapp-feature main+$ cd ../myapp-feature# ...work, commit, push...-<span class="cmd">cd ../myapp</span>-<span class="cmd">git merge feature-branch</span>-<span class="cmd">git worktree remove ../myapp-feature</span>-<span class="cmd">git branch -d feature-branch</span>+$ cd ../myapp+$ git merge feature-branch+$ git worktree remove ../myapp-feature+$ git branch -d feature-branch+```Worktrunk automates the full lifecycle:-<span class="cmd">wt switch --create feature-branch # Creates worktree, runs setup hooks</span>+```bash+$ wt switch --create feature-branch # Creates worktree, runs setup hooks# ...work...-<span class="cmd">wt merge # Merges into default branch, cleans up</span>+$ wt merge # Merges into default branch, cleans up+```No cd back to main — `wt merge` runs from the feature worktree and merges into the target, like GitHub's merge button.@@ -179,11 +183,13 @@ All hook executions and LLM commands are recorded in `.git/wt/logs/commands.jsonView the log with `wt config state logs get`, or query directly:+```bash# Recent commands-<span class="cmd">tail -5 .git/wt/logs/commands.jsonl | jq .</span>+$ tail -5 .git/wt/logs/commands.jsonl | jq .# Failed commands-<span class="cmd">jq 'select(.exit != 0 and .exit != null)' .git/wt/logs/commands.jsonl</span>+$ jq 'select(.exit != 0 and .exit != null)' .git/wt/logs/commands.jsonl+```Clear with `wt config state logs clear`.diff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.mdindex 3ba77b1ed..3fe1c6542 100644--- a/skills/worktrunk/reference/hook.md+++ b/skills/worktrunk/reference/hook.md@@ -189,7 +189,14 @@ if ctx['branch'].startswith('feature/') and 'backend' in ctx['repo']:`wt hook <type>` runs hooks on demand — useful for testing during development, running in CI pipelines, or re-running after a failure.```bash-$ wt hook pre-merge # Run all pre-merge hooks|||wt hook pre-merge test # Run hooks named "test" from both sources|||wt hook pre-merge user: # Run all user hooks|||wt hook pre-merge project: # Run all project hooks|||wt hook pre-merge user:test # Run only user's "test" hook|||wt hook pre-merge project:test # Run only project's "test" hook|||wt hook pre-merge --yes # Skip approval prompts (for CI)|||wt hook pre-start --var branch=feature/test # Override template variable+$ wt hook pre-merge # Run all pre-merge hooks+$ wt hook pre-merge test # Run hooks named "test" from both sources+$ wt hook pre-merge user: # Run all user hooks+$ wt hook pre-merge project: # Run all project hooks+$ wt hook pre-merge user:test # Run only user's "test" hook+$ wt hook pre-merge project:test # Run only project's "test" hook+$ wt hook pre-merge --yes # Skip approval prompts (for CI)+$ wt hook pre-start --var branch=feature/test # Override template variable```The `user:` and `project:` prefixes filter by source. Use `user:` or `project:` alone to run all hooks from that source, or `user:name` / `project:name` to run a specific hook.diff --git a/skills/worktrunk/reference/list.md b/skills/worktrunk/reference/list.mdindex b3c791853..49577a5b4 100644--- a/skills/worktrunk/reference/list.md+++ b/skills/worktrunk/reference/list.md@@ -129,7 +129,29 @@ These appear across all columns while the table is loading:Query structured data with `--format=json`:```bash-$ # Current worktree path (for scripts)|||wt list --format=json | jq -r '.[] | select(.is_current) | .path'||||||# Branches with uncommitted changes|||wt list --format=json | jq '.[] | select(.working_tree.modified)'||||||# Worktrees with merge conflicts|||wt list --format=json | jq '.[] | select(.operation_state == "conflicts")'||||||# Branches ahead of main (needs merging)|||wt list --format=json | jq '.[] | select(.main.ahead > 0) | .branch'||||||# Integrated branches (safe to remove)|||wt list --format=json | jq '.[] | select(.main_state == "integrated" or .main_state == "empty") | .branch'||||||# Branches without worktrees|||wt list --format=json --branches | jq '.[] | select(.kind == "branch") | .branch'||||||# Worktrees ahead of remote (needs pushing)|||wt list --format=json | jq '.[] | select(.remote.ahead > 0) | {branch, ahead: .remote.ahead}'||||||# Stale CI (local changes not reflected in CI)|||wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'+# Current worktree path (for scripts)+$ wt list --format=json | jq -r '.[] | select(.is_current) | .path'++# Branches with uncommitted changes+$ wt list --format=json | jq '.[] | select(.working_tree.modified)'++# Worktrees with merge conflicts+$ wt list --format=json | jq '.[] | select(.operation_state == "conflicts")'++# Branches ahead of main (needs merging)+$ wt list --format=json | jq '.[] | select(.main.ahead > 0) | .branch'++# Integrated branches (safe to remove)+$ wt list --format=json | jq '.[] | select(.main_state == "integrated" or .main_state == "empty") | .branch'++# Branches without worktrees+$ wt list --format=json --branches | jq '.[] | select(.kind == "branch") | .branch'++# Worktrees ahead of remote (needs pushing)+$ wt list --format=json | jq '.[] | select(.remote.ahead > 0) | {branch, ahead: .remote.ahead}'++# Stale CI (local changes not reflected in CI)+$ wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'```**Fields:**diff --git a/skills/worktrunk/reference/llm-commits.md b/skills/worktrunk/reference/llm-commits.mdindex 1ceb1966d..9be94acbd 100644--- a/skills/worktrunk/reference/llm-commits.md+++ b/skills/worktrunk/reference/llm-commits.md@@ -49,10 +49,13 @@ These examples assume a feature worktree with changes to commit.Squashes all changes (uncommitted + existing commits) into one commit with an LLM-generated message, then merges to the default branch:+```bash+$ wt merge<span class=c>◎</span> <span class=c>Squashing 3 commits into a single commit <span style='color:var(--bright-black,#555)'>(5 files, <span class=g>+48</span></span></span><span style='color:var(--bright-black,#555)'>)</span>...<span class=c>◎</span> <span class=c>Generating squash commit message...</span><span style='background:var(--bright-white,#fff)'> </span> <b>feat(auth): Implement JWT authentication system</b><span style='background:var(--bright-white,#fff)'> </span> ...+```### wt step commitdiff --git a/skills/worktrunk/reference/remove.md b/skills/worktrunk/reference/remove.mdindex a493df9c2..1e3748edd 100644--- a/skills/worktrunk/reference/remove.md+++ b/skills/worktrunk/reference/remove.md@@ -13,7 +13,8 @@ $ wt removeRemove specific worktrees / branches:```bash-$ wt remove feature-branch|||wt remove old-feature another-branch+$ wt remove feature-branch+$ wt remove old-feature another-branch```Keep the branch:@@ -54,7 +55,9 @@ Worktrunk has two force flags for different situations:| `--force-delete` (`-D`) | Branch | Branch has unmerged commits |```bash-$ wt remove feature --force # Remove worktree with untracked files|||wt remove feature -D # Delete unmerged branch|||wt remove feature --force -D # Both+$ wt remove feature --force # Remove worktree with untracked files+$ wt remove feature -D # Delete unmerged branch+$ wt remove feature --force -D # Both```Without `--force`, removal fails if the worktree contains untracked files. Without `--force-delete`, removal keeps branches with unmerged changes. Use `--no-delete-branch` to keep the branch regardless of merge status.diff --git a/skills/worktrunk/reference/step.md b/skills/worktrunk/reference/step.mdindex 29c60f52f..5ebfb7385 100644--- a/skills/worktrunk/reference/step.md+++ b/skills/worktrunk/reference/step.md@@ -13,7 +13,10 @@ $ wt step commitManual merge workflow with review between steps:```bash-$ wt step commit|||wt step squash|||wt step rebase|||wt step push+$ wt step commit+$ wt step squash+$ wt step rebase+$ wt step push```## Operations@@ -102,7 +105,11 @@ stage = "tracked"Output the rendered LLM prompt to stdout without running the command. Useful for inspecting prompt templates or piping to other tools:```bash-$ # Inspect the rendered prompt|||wt step commit --show-prompt | less||||||# Pipe to a different LLM|||wt step commit --show-prompt | llm -m gpt-5-nano+# Inspect the rendered prompt+$ wt step commit --show-prompt | less++# Pipe to a different LLM+$ wt step commit --show-prompt | llm -m gpt-5-nano```### Command reference@@ -241,7 +248,9 @@ This is what `wt merge` would include — a single diff against the merge base.Arguments after `--` are forwarded to `git diff`:```bash-$ wt step diff -- --stat|||wt step diff -- --name-only|||wt step diff -- -- '*.rs'+$ wt step diff -- --stat+$ wt step diff -- --name-only+$ wt step diff -- -- '*.rs'```The diff is pipeable to tools like `delta`:@@ -255,7 +264,9 @@ $ wt step diff | deltaEquivalent to:```bash-$ cp "$(git rev-parse --git-dir)/index" /tmp/idx|||GIT_INDEX_FILE=/tmp/idx git add --intent-to-add .|||GIT_INDEX_FILE=/tmp/idx git diff $(git merge-base HEAD $(wt config state default-branch))+$ cp "$(git rev-parse --git-dir)/index" /tmp/idx+$ GIT_INDEX_FILE=/tmp/idx git add --intent-to-add .+$ GIT_INDEX_FILE=/tmp/idx git diff $(git merge-base HEAD $(wt config state default-branch))````git diff` ignores untracked files. `git add --intent-to-add .` registers them in the index without staging their content, making them visible to `git diff`. This runs against a copy of the real index so the original is never modified.@@ -432,30 +443,40 @@ All [hook template variables and filters](https://worktrunk.dev/hook/#template-vGet the port for the current branch:-<span class="cmd">wt step eval '{{ branch | hash_port }}'</span>+```bash+$ wt step eval '{{ branch | hash_port }}'16066+```Use in shell substitution:-<span class="cmd">curl http://localhost:$(wt step eval '{{ branch | hash_port }}')/health</span>+```bash+$ curl http://localhost:$(wt step eval '{{ branch | hash_port }}')/health+```Combine multiple values:-<span class="cmd">wt step eval '{{ branch | hash_port }},{{ ("supabase-api-" ~ branch) | hash_port }}'</span>+```bash+$ wt step eval '{{ branch | hash_port }},{{ ("supabase-api-" ~ branch) | hash_port }}'16066,16739+```Use conditionals and filters:-<span class="cmd">wt step eval '{{ branch | sanitize_db }}'</span>+```bash+$ wt step eval '{{ branch | sanitize_db }}'feature_auth_oauth2_a1b+```Show available template variables:-<span class="cmd">wt step eval --dry-run '{{ branch }}'</span>+```bash+$ wt step eval --dry-run '{{ branch }}'branch=feature/auth-oauth2worktree_path=/home/user/projects/myapp-feature-auth-oauth2...Result: feature/auth-oauth2+```Note: This command is experimental and may change in future versions.@@ -516,12 +537,14 @@ $ wt step for-each -- npm installUse branch name in command:-<span class="cmd">wt step for-each -- "echo Branch: {{ branch }}"</span>+```bash+$ wt step for-each -- "echo Branch: {{ branch }}"+```Pull updates in worktrees with upstreams (skips others):```bash-$ git fetch --prune && wt step for-each -- '[ "$(git rev-parse @{u} 2>/dev/null)" ] || exit 0; git pull --autostash'+$ git fetch --prune && wt step for-each -- '[ "$(git rev-parse @{u} 2>/dev/null)" ] || exit 0; git pull --autostash'```Note: This command is experimental and may change in future versions.@@ -563,7 +586,8 @@ Swap a branch into the main worktree. Exchanges branches and gitignored files be### Example```bash-$ # from ~/project (main worktree)|||wt step promote feature+# from ~/project (main worktree)+$ wt step promote feature```Before:@@ -642,7 +666,8 @@ Locked worktrees and the main worktree are always skipped. The current worktreeWorktrees younger than `--min-age` (default: 1 hour) are skipped. This prevents removing a worktree just created from the default branch — it looks "merged" because its branch points at the same commit.```bash-$ wt step prune --min-age=0s # no age guard|||wt step prune --min-age=2d # skip worktrees younger than 2 days+$ wt step prune --min-age=0s # no age guard+$ wt step prune --min-age=2d # skip worktrees younger than 2 days```### Examples@@ -803,7 +828,10 @@ port = "echo http://localhost:{{ branch | hash_port }}"``````bash-$ wt step deploy # run the alias|||wt step deploy --dry-run # show expanded command|||wt step deploy --var env=staging # pass extra template variables|||wt step deploy --yes # skip approval prompt+$ wt step deploy # run the alias+$ wt step deploy --dry-run # show expanded command+$ wt step deploy --var env=staging # pass extra template variables+$ wt step deploy --yes # skip approval prompt```When defined in both user and project config, both run — user first, then project. Project-config aliases require [command approval](https://worktrunk.dev/hook/#wt-hook-approvals) on first run, same as project hooks. User-config aliases are trusted.diff --git a/skills/worktrunk/reference/switch.md b/skills/worktrunk/reference/switch.mdindex 86517dffe..d358d2544 100644--- a/skills/worktrunk/reference/switch.md+++ b/skills/worktrunk/reference/switch.md@@ -7,7 +7,11 @@ Worktrees are addressed by branch name; paths are computed from a configurable t## Examples```bash-$ wt switch feature-auth # Switch to worktree|||wt switch - # Previous worktree (like cd -)|||wt switch --create new-feature # Create new branch and worktree|||wt switch --create hotfix --base production|||wt switch pr:123 # Switch to PR #123's branch+$ wt switch feature-auth # Switch to worktree+$ wt switch - # Previous worktree (like cd -)+$ wt switch --create new-feature # Create new branch and worktree+$ wt switch --create hotfix --base production+$ wt switch pr:123 # Switch to PR #123's branch```## Creating a branch@@ -25,7 +29,10 @@ If the branch already has a worktree, `wt switch` changes directories to it. Oth5. Spawns [post-start](https://worktrunk.dev/hook/#hook-types) and [post-switch hooks](https://worktrunk.dev/hook/#hook-types) in the background```bash-$ wt switch feature # Existing branch → creates worktree|||wt switch --create feature # New branch and worktree|||wt switch --create fix --base release # New branch from release|||wt switch --create temp --no-verify # Skip hooks+$ wt switch feature # Existing branch → creates worktree+$ wt switch --create feature # New branch and worktree+$ wt switch --create fix --base release # New branch from release+$ wt switch --create temp --no-verify # Skip hooks```## Shortcuts@@ -39,7 +46,11 @@ $ wt switch feature # Existing branch → creates worktre| `mr:{N}` | GitLab MR !N's branch |```bash-$ wt switch - # Back to previous|||wt switch ^ # Default branch worktree|||wt switch --create fix --base=@ # Branch from current HEAD|||wt switch pr:123 # PR #123's branch|||wt switch mr:101 # MR !101's branch+$ wt switch - # Back to previous+$ wt switch ^ # Default branch worktree+$ wt switch --create fix --base=@ # Branch from current HEAD+$ wt switch pr:123 # PR #123's branch+$ wt switch mr:101 # MR !101's branch```## Interactive picker@@ -81,7 +92,8 @@ Available on Unix only (macOS, Linux). On Windows, use `wt list` or `wt switch <The `pr:<number>` and `mr:<number>` shortcuts resolve a GitHub PR or GitLab MR to its branch. For same-repo PRs/MRs, worktrunk switches to the branch directly. For fork PRs/MRs, it fetches the ref (`refs/pull/N/head` or `refs/merge-requests/N/head`) and configures `pushRemote` to the fork URL.```bash-$ wt switch pr:101 # GitHub PR #101|||wt switch mr:101 # GitLab MR !101+$ wt switch pr:101 # GitHub PR #101+$ wt switch mr:101 # GitLab MR !101```Requires `gh` (GitHub) or `glab` (GitLab) CLI to be installed and authenticated. The `--create` flag cannot be used with `pr:`/`mr:` syntax since the branch already exists.diff --git a/skills/worktrunk/reference/tips-patterns.md b/skills/worktrunk/reference/tips-patterns.mdindex 98e521389..893980bc6 100644--- a/skills/worktrunk/reference/tips-patterns.md+++ b/skills/worktrunk/reference/tips-patterns.md@@ -7,7 +7,9 @@ Practical recipes for common Worktrunk workflows.Create a worktree and launch Claude in one command:```bash-$ alias wsc='wt switch --create --execute=claude'|||wsc new-feature # Creates worktree, runs hooks, launches Claude|||wsc feature -- 'Fix GH #322' # Runs `claude 'Fix GH #322'`+$ alias wsc='wt switch --create --execute=claude'+$ wsc new-feature # Creates worktree, runs hooks, launches Claude+$ wsc feature -- 'Fix GH #322' # Runs `claude 'Fix GH #322'````## Eliminate cold starts@@ -41,7 +43,8 @@ server = "lsof -ti :{{ branch | hash_port }} -sTCP:LISTEN | xargs kill 2>/dev/nuThe URL column in `wt list` shows each worktree's dev server:-<span class="cmd">wt list</span>+```bash+$ wt list<b>Branch</b> <b>Status</b> <b>HEAD±</b> <b>main↕</b> <b>Remote⇅</b> <b>URL</b> <b>Commit</b> <b>Age</b>@ main <span class=c>?</span> <span class=d>^</span><span class=d>⇅</span> <span class=g>⇡1</span> <span class=d><span class=r>⇣1</span></span> <span class=d>http://localhost:12107</span> <span class=d>41ee0834</span> <span class=d>4d</span>+ feature-api <span class=c>+</span> <span class=d>↕</span><span class=d>⇡</span> <span class=g>+54</span> <span class=r>-5</span> <span class=g>↑4</span> <span class=d><span class=r>↓1</span></span> <span class=g>⇡3</span> <span class=d>http://localhost:10703</span> <span class=d>6814f02a</span> <span class=d>30m</span>@@ -49,6 +52,7 @@ The URL column in `wt list` shows each worktree's dev server:+ <span class=d>fix-typos</span> <span class=d>_</span><span class=d>|</span> <span class=d>|</span> <span class=d>http://localhost:14301</span> <span class=d>41ee0834</span> <span class=d>4d</span><span class=d>○</span> <span class=d>Showing 4 worktrees, 2 with changes, 2 ahead, 2 columns hidden</span>+```Ports are deterministic — `fix-auth` always gets port 16460, regardless of which machine or when. The URL dims if the server isn't running.@@ -137,7 +141,9 @@ Custom emoji markers show agent state in `wt list`. The Claude Code plugin setsSet status manually for any workflow:```bash-$ wt config state marker set "🚧" # Current branch|||wt config state marker set "✅" --branch feature # Specific branch|||git config worktrunk.state.feature.marker '{"marker":"💬","set_at":0}' # Direct+$ wt config state marker set "🚧" # Current branch+$ wt config state marker set "✅" --branch feature # Specific branch+$ git config worktrunk.state.feature.marker '{"marker":"💬","set_at":0}' # Direct```See [Claude Code Integration](https://worktrunk.dev/claude-code/#installation) for plugin installation.@@ -195,7 +201,9 @@ Reference Taskfile/Justfile/Makefile in hooks:Special arguments work across all commands—see [`wt switch`](https://worktrunk.dev/switch/#shortcuts) for the full list.```bash-$ wt switch --create hotfix --base=@ # Branch from current HEAD|||wt switch - # Switch to previous worktree|||wt remove @ # Remove current worktree+$ wt switch --create hotfix --base=@ # Branch from current HEAD+$ wt switch - # Switch to previous worktree+$ wt remove @ # Remove current worktree```## Stacked branches@@ -214,12 +222,14 @@ Spawn a worktree with Claude running in the background:**tmux** (new detached session):```bash-$ tmux new-session -d -s fix-auth-bug "wt switch --create fix-auth-bug -x claude -- \||| 'The login session expires after 5 minutes. Find the session timeout config and extend it to 24 hours.'"+$ tmux new-session -d -s fix-auth-bug "wt switch --create fix-auth-bug -x claude -- \+$ 'The login session expires after 5 minutes. Find the session timeout config and extend it to 24 hours.'"```**Zellij** (new pane in current session):```bash-$ zellij run -- wt switch --create fix-auth-bug -x claude -- \||| 'The login session expires after 5 minutes. Find the session timeout config and extend it to 24 hours.'+$ zellij run -- wt switch --create fix-auth-bug -x claude -- \+$ 'The login session expires after 5 minutes. Find the session timeout config and extend it to 24 hours.'```This lets one Claude session hand off work to another that runs in the background. Hooks run inside the multiplexer session/pane.@@ -265,7 +275,9 @@ tmux = "tmux kill-session -t {{ branch | sanitize }} 2>/dev/null || true"To create a worktree and immediately attach:-<span class="cmd">wt switch --create feature -x 'tmux attach -t {{ branch | sanitize }}'</span>+```bash+$ wt switch --create feature -x 'tmux attach -t {{ branch | sanitize }}'+```## Xcode DerivedData cleanup@@ -345,7 +357,8 @@ A [bare repository](https://git-scm.com/docs/gitrepository-layout) has no workinCloning a bare repo into `<project>/.git` puts all worktrees under one directory:```bash-$ git clone --bare <url> myproject/.git|||cd myproject+$ git clone --bare <url> myproject/.git+$ cd myproject```With `worktree-path = "{{ repo_path }}/../{{ branch | sanitize }}"`, worktrees become subdirectories of `myproject/`:diff --git a/skills/worktrunk/reference/worktrunk.md b/skills/worktrunk/reference/worktrunk.mdindex 497ea3f05..817ad0b54 100644--- a/skills/worktrunk/reference/worktrunk.md+++ b/skills/worktrunk/reference/worktrunk.md@@ -102,7 +102,8 @@ $ cargo install worktrunk && wt config shell installOn Windows, `wt` defaults to Windows Terminal's command. Winget additionally installs Worktrunk as `git-wt` to avoid the conflict:```bash-$ winget install max-sixty.worktrunk|||git-wt config shell install+$ winget install max-sixty.worktrunk+$ git-wt config shell install```Alternatively, disable Windows Terminal's alias (Settings → Privacy & security → For developers → App Execution Aliases → disable "Windows Terminal") to use `wt` directly.@@ -119,17 +120,21 @@ $ paru worktrunk-bin && wt config shell installCreate a worktree for a new feature:-<span class="cmd">wt switch --create feature-auth</span>+```bash+$ wt switch --create feature-auth<span class=g>✓</span> <span class=g>Created branch <b>feature-auth</b> from <b>main</b> and worktree @ <b>repo.feature-auth</b></span>+```This creates a new branch and worktree, then switches to it. Do your work, then check all worktrees with [`wt list`](https://worktrunk.dev/list/):-<span class="cmd">wt list</span>+```bash+$ wt list<b>Branch</b> <b>Status</b> <b>HEAD±</b> <b>main↕</b> <b>Remote⇅</b> <b>Commit</b> <b>Age</b> <b>Message</b>@ feature-auth <span class=c>+</span> <span class=d>↑</span> <span class=g>+27</span> <span class=r>-8</span> <span class=g>↑1</span> <span class=d>4bc72dc9</span> <span class=d>2h</span> <span class=d>Add authentication module</span>^ main <span class=d>^</span><span class=d>⇡</span> <span class=g>⇡1</span> <span class=d>0e631add</span> <span class=d>1d</span> <span class=d>Initial commit</span><span class=d>○</span> <span class=d>Showing 2 worktrees, 1 with changes, 1 ahead, 1 column hidden</span>+```The `@` marks the current worktree. `+` means staged changes, `↑1` means 1 commit ahead of main, `⇡` means unpushed commits.@@ -138,12 +143,15 @@ When done, either:**PR workflow** — commit, push, open a PR, merge via GitHub/GitLab, then clean up:```bash-$ wt step commit # commit staged changes|||gh pr create # or glab mr create|||wt remove # after PR is merged+$ wt step commit # commit staged changes+$ gh pr create # or glab mr create+$ wt remove # after PR is merged```**Local merge** — squash, rebase onto main, fast-forward merge, clean up:-<span class="cmd">wt merge main</span>+```bash+$ wt merge main<span class=c>◎</span> <span class=c>Generating commit message and committing changes... <span style='color:var(--bright-black,#555)'>(2 files, <span class=g>+53</span></span></span>, no squashing needed<span style='color:var(--bright-black,#555)'>)</span><span style='background:var(--bright-white,#fff)'> </span> <b>Add authentication module</b><span class=g>✓</span> <span class=g>Committed changes @ <span class=d>a1b2c3d</span></span>@@ -155,11 +163,14 @@ $ wt step commit # commit staged changes|||gh pr create<span class=g>✓</span> <span class=g>Merged to <b>main</b> <span style='color:var(--bright-black,#555)'>(1 commit, 2 files, +53</span></span><span style='color:var(--bright-black,#555)'>)</span><span class=c>◎</span> <span class=c>Removing <b>feature-auth</b> worktree & branch in background (same commit as <b>main</b>,</span> <span class=d>_</span><span class=c>)</span><span class=d>○</span> Switched to worktree for <b>main</b> @ <b>repo</b>+```For parallel agents, create multiple worktrees and launch an agent in each:```bash-$ wt switch -x claude -c feature-a -- 'Add user authentication'|||wt switch -x claude -c feature-b -- 'Fix the pagination bug'|||wt switch -x claude -c feature-c -- 'Write tests for the API'+$ wt switch -x claude -c feature-a -- 'Add user authentication'+$ wt switch -x claude -c feature-b -- 'Fix the pagination bug'+$ wt switch -x claude -c feature-c -- 'Write tests for the API'```The `-x` flag runs a command after switching; arguments after `--` are passed to it. Configure [post-start hooks](https://worktrunk.dev/hook/) to automate setup (install deps, start dev servers).diff --git a/src/docs.rs b/src/docs.rsindex 0ae5baf83..87942e865 100644--- a/src/docs.rs+++ b/src/docs.rs@@ -9,9 +9,15 @@/// All shell commands in `console` blocks use `$ ` prefix. This function detects/// them and emits the appropriate shortcode form:///-/// - Single command, no `{{ }}`: `{{ terminal(cmd="...") }}` (Syntect highlighting)-/// - Single command + output, no `{{ }}`: `{% terminal(cmd="...") %}output{% end %}`-/// - Multiple commands or `{{ }}`: `{% terminal() %}` with `<span class="cmd">` body+/// - Commands without output: `{{ terminal(cmd="...") }}` (Syntect highlighting)+/// - Commands with output: `{% terminal(cmd="...") %}output{% end %}`+/// - Multiple commands/comments: `|||`‐delimited in `cmd` parameter+///+/// `{{ }}` in commands (e.g., Jinja2 template expressions) are replaced with+/// placeholders so Tera doesn't interpret them. The terminal shortcode template+/// replaces them back before Syntect highlighting. Double quotes are also+/// replaced with a placeholder since they'd close the `cmd="..."` parameter+/// (Tera has no backslash-escape mechanism for string literals).////// Blocks without `$ ` are left unchanged for the `console` → `bash` replacement.pub fn convert_dollar_console_to_terminal(text: &str) -> String {@@ -50,62 +56,43 @@ pub fn convert_dollar_console_to_terminal(text: &str) -> String {continue;}- let has_template_syntax = commands.iter().any(|c| c.contains("{{"));-- if has_template_syntax {- // {{ }} in commands — must use body approach (Tera would interpret- // template syntax in cmd parameter). Accent color only.- result.push_str("{% terminal() %}\n");- for bl in &block_lines {- if let Some(cmd) = bl.strip_prefix("$ ") {- result.push_str("<span class=\"cmd\">");- for ch in cmd.chars() {- match ch {- '<' => result.push_str("<"),- '>' => result.push_str(">"),- '&' => result.push_str("&"),- _ => result.push(ch),- }- }- result.push_str("</span>\n");+ // Use cmd parameter for Syntect highlighting on all blocks.+ // {{ and }} are replaced with placeholders so Tera doesn't interpret+ // them as template expressions. The terminal shortcode template+ // replaces them back before Syntect highlighting.+ // Multiple commands/comments joined with ||| delimiter;+ // the template splits and highlights each individually.+ let cmd_value: Vec<_> = block_lines+ .iter()+ .filter_map(|l| {+ if let Some(cmd) = l.strip_prefix("$ ") {+ Some(+ cmd.replace('"', "__WT_QUOT__")+ .replace("{{", "__WT_OPEN2__")+ .replace("}}", "__WT_CLOSE2__"),+ )+ } else if l.starts_with('#') || l.is_empty() {+ Some(l.to_string())} else {- result.push_str(bl);- result.push('\n');+ None // output lines go in body}- }- result.push_str("{% end %}\n");- } else {- // No {{ }} — use cmd parameter for Syntect highlighting.- // Multiple commands/comments joined with ||| delimiter;- // the template splits and highlights each line individually.- let cmd_value: Vec<_> = block_lines- .iter()- .filter_map(|l| {- if let Some(cmd) = l.strip_prefix("$ ") {- Some(cmd.replace('"', """))- } else if l.starts_with('#') || l.is_empty() {- Some(l.to_string())- } else {- None // output lines go in body- }- })- .collect();- let body_lines: Vec<_> = block_lines- .iter()- .filter(|l| !l.starts_with("$ ") && !l.starts_with('#') && !l.is_empty())- .collect();+ })+ .collect();+ let body_lines: Vec<_> = block_lines+ .iter()+ .filter(|l| !l.starts_with("$ ") && !l.starts_with('#') && !l.is_empty())+ .collect();- let cmd_str = cmd_value.join("|||");- if body_lines.is_empty() {- result.push_str(&format!("{{{{ terminal(cmd=\"{cmd_str}\") }}}}\n"));- } else {- result.push_str(&format!("{{% terminal(cmd=\"{cmd_str}\") %}}\n"));- for bl in &body_lines {- result.push_str(bl);- result.push('\n');- }- result.push_str("{% end %}\n");+ let cmd_str = cmd_value.join("|||");+ if body_lines.is_empty() {+ result.push_str(&format!("{{{{ terminal(cmd=\"{cmd_str}\") }}}}\n"));+ } else {+ result.push_str(&format!("{{% terminal(cmd=\"{cmd_str}\") %}}\n"));+ for bl in &body_lines {+ result.push_str(bl);+ result.push('\n');}+ result.push_str("{% end %}\n");}continue;}@@ -127,12 +114,11 @@ mod tests {#[test]fn test_convert_dollar_console_to_terminal() {- // Command+output with {{ }} → body approach+ // Command+output with {{ }} → cmd parameter with placeholdersassert_snapshot!(convert_dollar_console_to_terminal("```console\n$ wt step eval '{{ branch | hash_port }}'\n16066\n```"), @r#"- {% terminal() %}- <span class="cmd">wt step eval '{{ branch | hash_port }}'</span>+ {% terminal(cmd="wt step eval '__WT_OPEN2__ branch | hash_port __WT_CLOSE2__'") %}16066{% end %}"#);diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rsindex 4dc502386..d6b2cdd03 100644--- a/tests/integration_tests/readme_sync.rs+++ b/tests/integration_tests/readme_sync.rs@@ -1693,11 +1693,14 @@ static ZOLA_FRONTMATTER_PATTERN: LazyLock<Regex> =static ZOLA_TITLE_PATTERN: LazyLock<Regex> =LazyLock::new(|| Regex::new(r#"title\s*=\s*"([^"]+)""#).unwrap());-/// Regex to strip body-form terminal shortcodes ({% terminal(...) %}...{% end %})-static ZOLA_TERMINAL_BODY_PATTERN: LazyLock<Regex> =- LazyLock::new(|| Regex::new(r#"(?s)\{% terminal\([^)]*\) %\}\n?(.*?)\{% end %\}"#).unwrap());+/// Regex to strip body-form terminal shortcodes ({% terminal(...) %}...{% end %}).+/// Optionally captures the cmd parameter value (group 1) and body (group 2).+static ZOLA_TERMINAL_BODY_PATTERN: LazyLock<Regex> = LazyLock::new(|| {+ Regex::new(r#"(?s)\{%\s*terminal\((?:cmd="([^"]*)"\s*)?\)\s*%\}\n?(.*?)\{%\s*end\s*%\}"#)+ .unwrap()+});-/// Regex to strip self-closing terminal shortcodes ({{ terminal(cmd="...") }})+/// Regex to strip self-closing terminal shortcodes ({{ terminal(cmd="...") }}).static ZOLA_TERMINAL_SELF_CLOSING_PATTERN: LazyLock<Regex> =LazyLock::new(|| Regex::new(r#"\{\{ terminal\(cmd="([^"]*)"\) \}\}"#).unwrap());@@ -1714,6 +1717,43 @@ static AUTO_GENERATED_MARKER_PATTERN: LazyLock<Regex> = LazyLock::new(|| {static HTML_FIGURE_PATTERN: LazyLock<Regex> =LazyLock::new(|| Regex::new(r"(?s)<figure[^>]*>.*?</figure>\n*").unwrap());+/// Regex to strip `<span class="cmd">...</span>` lines from shortcode bodies.+/// These duplicate the cmd parameter content (the template uses `clean_body` for this).+static SPAN_CMD_PATTERN: LazyLock<Regex> =+ LazyLock::new(|| Regex::new(r#"<span class="cmd">[^<]*</span>\n?"#).unwrap());++/// Regex to convert `<span class="cmd">X</span>` → `$ X` for no-cmd body shortcodes.+static SPAN_CMD_TO_DOLLAR: LazyLock<Regex> =+ LazyLock::new(|| Regex::new(r#"<span class="cmd">([^<]*)</span>"#).unwrap());++/// Convert a `|||`-delimited cmd string (and optional body) into a ```bash block.+/// Each cmd line gets `$ ` prefix; comment lines (`#`) and blank lines pass through.+fn cmd_to_bash_block(cmd: &str, body: &str) -> String {+ let mut result = String::from("```bash\n");+ for line in cmd.split("|||") {+ if line.is_empty() {+ result.push('\n');+ } else if line.starts_with('#') {+ result.push_str(line);+ result.push('\n');+ } else {+ result.push_str("$ ");+ result.push_str(line);+ result.push('\n');+ }+ }+ // Strip <span class="cmd"> lines that duplicate the cmd parameter+ let clean_body = SPAN_CMD_PATTERN.replace_all(body, "");+ if !clean_body.is_empty() {+ result.push_str(&clean_body);+ if !clean_body.ends_with('\n') {+ result.push('\n');+ }+ }+ result.push_str("```");+ result+}+/// Transform docs content for skill file consumption////// Transforms:@@ -1736,11 +1776,30 @@ fn transform_docs_for_skill(content: &str) -> String {// Strip frontmatterlet content = ZOLA_FRONTMATTER_PATTERN.replace(content, "");- // Strip terminal shortcodes:- // - Body form: keep inner content- // - Self-closing: convert to `$ command` (plain text with prompt)- let content = ZOLA_TERMINAL_BODY_PATTERN.replace_all(&content, "$1");- let content = ZOLA_TERMINAL_SELF_CLOSING_PATTERN.replace_all(&content, "```bash\n$$ $1\n```");+ // Strip terminal shortcodes, converting cmd parameters back to `$ command` blocks.+ // Commands joined by `|||` are split into separate lines.+ let content = ZOLA_TERMINAL_BODY_PATTERN.replace_all(&content, |caps: ®ex::Captures| {+ let body = caps.get(2).map_or("", |m| m.as_str());+ match caps.get(1) {+ Some(cmd) => cmd_to_bash_block(cmd.as_str(), body),+ None if body.contains(r#"<span class="cmd">"#) => {+ // Old-style body shortcode with <span class="cmd"> — convert to $ lines+ let converted = SPAN_CMD_TO_DOLLAR.replace_all(body, "$$ $1");+ format!("```bash\n{converted}```")+ }+ None => body.to_string(),+ }+ });+ let content = ZOLA_TERMINAL_SELF_CLOSING_PATTERN+ .replace_all(&content, |caps: ®ex::Captures| {+ cmd_to_bash_block(caps.get(1).map_or("", |m| m.as_str()), "")+ });++ // Replace placeholders used to escape Tera template syntax in cmd parameters+ let content = content+ .replace("__WT_OPEN2__", "{{")+ .replace("__WT_CLOSE2__", "}}")+ .replace("__WT_QUOT__", "\"");// Strip AUTO-GENERATED marker comments (keep content)let content = AUTO_GENERATED_MARKER_PATTERN.replace_all(&content, "");