Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
feat(docs): move experimental badges to headings (#1523)
Maximilian Roos879cbd906b57
diff --git a/README.md b/README.mdindex b1abb431d..23c7e626e 100644--- a/README.md+++ b/README.md@@ -87,7 +87,7 @@ git branch -d feat</pre></td>- **[Merge workflow](https://worktrunk.dev/merge/)** — squash, rebase, merge, clean up in one command- **[Interactive picker](https://worktrunk.dev/switch/#interactive-picker)** — browse worktrees with live diff and log previews- **[Copy build caches](https://worktrunk.dev/step/)** — skip cold starts by sharing `target/`, `node_modules/`, etc between worktrees-- **[`wt list --full`](https://worktrunk.dev/list/#full-mode)** — [CI status](https://worktrunk.dev/list/#ci-status) and [AI-generated summaries](https://worktrunk.dev/list/#llm-summaries-experimental) per branch+- **[`wt list --full`](https://worktrunk.dev/list/#full-mode)** — [CI status](https://worktrunk.dev/list/#ci-status) and [AI-generated summaries](https://worktrunk.dev/list/#llm-summaries) per branch- **[PR checkout](https://worktrunk.dev/switch/#github-pull-requests)** — `wt switch pr:123` to jump straight to a PR's branch- **[Dev server per worktree](https://worktrunk.dev/hook/#dev-servers)** — `hash_port` template filter gives each worktree a unique port- ...and **[lots more](#next-steps)**diff --git a/docs/content/config.md b/docs/content/config.mdindex f5a6977a6..5422943e2 100644--- a/docs/content/config.md+++ b/docs/content/config.md@@ -190,7 +190,7 @@ For context:Entries are keyed by project identifier (e.g., `github.com/user/repo`).-#### Setting overrides <span class="badge-experimental">experimental</span>+#### Setting overrides <span class="badge-experimental"></span>Override global user config for a specific project. Scalar values (like `worktree-path`) replace the global value. Hooks append — both global and per-project hooks run. Aliases merge — per-project aliases override global aliases on name collision.diff --git a/docs/content/faq.md b/docs/content/faq.mdindex f11799a8e..f281e974b 100644--- a/docs/content/faq.md+++ b/docs/content/faq.md@@ -166,7 +166,7 @@ Worktrunk runs `git` commands internally and optionally runs `gh` (GitHub) or `g1. **User hooks** (`~/.config/worktrunk/config.toml`) — Personal automation for all repositories2. **Project hooks** (`.config/wt.toml`) — Repository-specific automation-3. **LLM commands** (`~/.config/worktrunk/config.toml`) — Commit message generation and [branch summaries](@/llm-commits.md#branch-summaries-experimental)+3. **LLM commands** (`~/.config/worktrunk/config.toml`) — Commit message generation and [branch summaries](@/llm-commits.md#branch-summaries)4. **--execute flag** — Explicitly provided commandsUser hooks don't require approval (you defined them). Commands from project hooks require approval on first run. Approved commands are saved to user config. If a command changes, Worktrunk requires new approval.diff --git a/docs/content/hook.md b/docs/content/hook.mdindex 57e43dcbb..35eacc57f 100644--- a/docs/content/hook.md+++ b/docs/content/hook.md@@ -167,7 +167,7 @@ build = "cargo build --release"## User hooks-Define hooks in `~/.config/worktrunk/config.toml` to run for all repositories. User hooks run before project hooks and don't require approval. For repository-specific user hooks, see [setting overrides](@/config.md#setting-overrides-experimental).+Define hooks in `~/.config/worktrunk/config.toml` to run for all repositories. User hooks run before project hooks and don't require approval. For repository-specific user hooks, see [setting overrides](@/config.md#setting-overrides).```toml# ~/.config/worktrunk/config.tomldiff --git a/docs/content/list.md b/docs/content/list.mdindex 42941404a..8451ecb49 100644--- a/docs/content/list.md+++ b/docs/content/list.md@@ -24,7 +24,7 @@ The table renders progressively: branch names, paths, and commit hashes appear i## Full mode-`--full` adds columns that require network access or LLM calls: [CI status](#ci-status) (GitHub/GitLab pipeline pass/fail), line diffs since the merge-base, and [LLM-generated summaries](#llm-summaries-experimental) of each branch's changes. The table displays instantly and columns fill in as results arrive.+`--full` adds columns that require network access or LLM calls: [CI status](#ci-status) (GitHub/GitLab pipeline pass/fail), line diffs since the merge-base, and [LLM-generated summaries](#llm-summaries) of each branch's changes. The table displays instantly and columns fill in as results arrive.## Examples@@ -90,7 +90,7 @@ $ wt list --format=json| HEAD± | Uncommitted changes: +added -deleted lines || main↕ | Commits ahead/behind default branch || main…± | Line diffs since the merge-base with the default branch (`--full`) |-| Summary | LLM-generated branch summary (`--full` + `summary = true`, requires [`commit.generation`](@/config.md#commit)) <span class="badge-experimental">experimental</span> |+| Summary | LLM-generated branch summary (`--full` + `summary = true`, requires [`commit.generation`](@/config.md#commit)) <span class="badge-experimental"></span> || Remote⇅ | Commits ahead/behind tracking branch || CI | Pipeline status (`--full`) || Path | Worktree directory |@@ -117,7 +117,7 @@ The CI column shows GitHub/GitLab pipeline status:CI indicators are clickable links to the PR or pipeline page. Any CI dot appears dimmed when there are unpushed local changes (stale status). 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 <span class="badge-experimental">experimental</span>+### LLM summaries <span class="badge-experimental"></span>Reuses the [`commit.generation`](@/config.md#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.diff --git a/docs/content/llm-commits.md b/docs/content/llm-commits.mdindex 02ec1aa27..434f2b1c2 100644--- a/docs/content/llm-commits.md+++ b/docs/content/llm-commits.md@@ -89,14 +89,14 @@ $ wt step squashSee [`wt merge`](@/merge.md) and [`wt step`](@/step.md) for full documentation.-## Branch summaries <span class="badge-experimental">experimental</span>+## Branch summaries <span class="badge-experimental"></span>With `summary = true` and a `[commit.generation] command` configured, Worktrunk generates LLM branch summaries — one-line descriptions of each branch's changes since the default branch.Summaries appear in:- **`wt switch`** [interactive picker](@/switch.md#interactive-picker) — preview tab 5-- **`wt list --full`** — the Summary column (see [`wt list`](@/list.md#llm-summaries-experimental))+- **`wt list --full`** — the Summary column (see [`wt list`](@/list.md#llm-summaries))Enable in user config:diff --git a/docs/content/step.md b/docs/content/step.mdindex 53f63a506..9130e149c 100644--- a/docs/content/step.md+++ b/docs/content/step.md@@ -36,11 +36,11 @@ wt step push- `push` — Fast-forward target to current branch- [`diff`](#wt-step-diff) — Show all changes since branching (committed, staged, unstaged, untracked)- [`copy-ignored`](#wt-step-copy-ignored) — Copy gitignored files between worktrees-- [`for-each`](#wt-step-for-each) — <span class="badge-experimental">experimental</span> Run a command in every worktree-- [`promote`](#wt-step-promote) — <span class="badge-experimental">experimental</span> Swap a branch into the main worktree+- [`for-each`](#wt-step-for-each) — <span class="badge-experimental"></span> Run a command in every worktree+- [`promote`](#wt-step-promote) — <span class="badge-experimental"></span> Swap a branch into the main worktree- [`prune`](#wt-step-prune) — Remove worktrees and branches merged into the default branch-- [`relocate`](#wt-step-relocate) — <span class="badge-experimental">experimental</span> Move worktrees to expected paths-- [`<alias>`](#aliases) — <span class="badge-experimental">experimental</span> Run a configured command alias+- [`relocate`](#wt-step-relocate) — <span class="badge-experimental"></span> Move worktrees to expected paths+- [`<alias>`](#aliases) — <span class="badge-experimental"></span> Run a configured command alias## See also@@ -451,9 +451,9 @@ Usage: <b><span class=c>wt step copy-ignored</span></b> <span class=c>[OPTIONS]<Verbose output (-v: hooks, templates; -vv: debug report){% end %}-## wt step for-each+## wt step for-each <span class="badge-experimental"></span>-<span class="badge-experimental">experimental</span> Run command in each worktree. Executes sequentially with real-time output; continues on failure.+Run command in each worktree. Executes sequentially with real-time output; continues on failure.Executes a command sequentially in every worktree with real-time output. Continues on failure and shows a summary at the end.@@ -519,9 +519,9 @@ Usage: <b><span class=c>wt step for-each</span></b> <span class=c>[OPTIONS]</spaVerbose output (-v: hooks, templates; -vv: debug report){% end %}-## wt step promote+## wt step promote <span class="badge-experimental"></span>-<span class="badge-experimental">experimental</span> Swap a branch into the main worktree. Exchanges branches and gitignored files between two worktrees.+Swap a branch into the main worktree. Exchanges branches and gitignored files between two worktrees.**Experimental.** Use promote for temporary testing when the main worktree has special significance (Docker Compose, IDE configs, heavy build artifacts anchored to project root), and hooks & tools aren't yet set up to run on arbitrary worktrees. The idiomatic Worktrunk workflow does not use `promote`; instead each worktree has a full environment. `promote` is the only Worktrunk command which changes a branch in an existing worktree.@@ -593,9 +593,9 @@ Usage: <b><span class=c>wt step promote</span></b> <span class=c>[OPTIONS]</spanVerbose output (-v: hooks, templates; -vv: debug report){% end %}-## wt step prune+## wt step prune <span class="badge-experimental"></span>-<span class="badge-experimental">experimental</span> Remove worktrees merged into the default branch.+Remove worktrees merged into the default branch.Bulk-removes worktrees and branches that are integrated into the default branch, using the same criteria as `wt remove`'s branch cleanup. Stale worktree entries are cleaned up too.@@ -663,9 +663,9 @@ Usage: <b><span class=c>wt step prune</span></b> <span class=c>[OPTIONS]</span>Verbose output (-v: hooks, templates; -vv: debug report){% end %}-## wt step relocate+## wt step relocate <span class="badge-experimental"></span>-<span class="badge-experimental">experimental</span> Move worktrees to expected paths. Relocates worktrees whose path doesn't match the worktree-path template.+Move worktrees to expected paths. Relocates worktrees whose path doesn't match the worktree-path template.Moves worktrees to match the configured `worktree-path` template.diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.mdindex 1d1f42f57..491a54c36 100644--- a/docs/content/tips-patterns.md+++ b/docs/content/tips-patterns.md@@ -176,7 +176,7 @@ With `summary = true` and [`commit.generation`](@/config.md#commit) configured,summary = true```-Disabled by default — when enabled, each branch's diff is sent to the configured LLM for summarization. See [LLM Commits](@/llm-commits.md#branch-summaries-experimental) for details.+Disabled by default — when enabled, each branch's diff is sent to the configured LLM for summarization. See [LLM Commits](@/llm-commits.md#branch-summaries) for details.## JSON APIdiff --git a/docs/content/worktrunk.md b/docs/content/worktrunk.mdindex 3ff717731..3a24d29f7 100644--- a/docs/content/worktrunk.md+++ b/docs/content/worktrunk.md@@ -88,7 +88,7 @@ git branch -d feat{% end %}</td>- **[Merge workflow](@/merge.md)** — squash, rebase, merge, clean up in one command- **[Interactive picker](@/switch.md#interactive-picker)** — browse worktrees with live diff and log previews- **[Copy build caches](@/step.md)** — skip cold starts by sharing `target/`, `node_modules/`, etc between worktrees-- **[`wt list --full`](@/list.md#full-mode)** — [CI status](@/list.md#ci-status) and [AI-generated summaries](@/list.md#llm-summaries-experimental) per branch+- **[`wt list --full`](@/list.md#full-mode)** — [CI status](@/list.md#ci-status) and [AI-generated summaries](@/list.md#llm-summaries) per branch- **[PR checkout](@/switch.md#github-pull-requests)** — `wt switch pr:123` to jump straight to a PR's branch- **[Dev server per worktree](@/hook.md#dev-servers)** — `hash_port` template filter gives each worktree a unique port- ...and **[lots more](#next-steps)**diff --git a/docs/sass/custom.scss b/docs/sass/custom.scssindex dc499e8b6..e3a079271 100644--- a/docs/sass/custom.scss+++ b/docs/sass/custom.scss@@ -993,21 +993,24 @@ ul > li::marker {// Badges — status labels (experimental, deprecated, etc.)// ============================================================================-// Experimental badge — quiet label, reads as metadata not emphasis+// Experimental badge — empty span, text via ::after so it doesn't affect+// Zola's heading slug generation or page TOC entries..badge-experimental {display: inline-block;- font-size: 0.65rem;- font-weight: 600;- text-transform: uppercase;- letter-spacing: 0.04em;- color: var(--wt-color-text-soft);- border: 1px solid var(--wt-color-border-subtle);- border-radius: var(--wt-radius-pill);- padding: 0.05rem 0.5rem;vertical-align: middle;white-space: nowrap;- line-height: 1.4;+ &::after {+ content: "EXPERIMENTAL";+ font-size: 0.65rem;+ font-weight: 600;+ letter-spacing: 0.04em;+ color: var(--wt-color-text-soft);+ border: 1px solid var(--wt-color-border-subtle);+ border-radius: var(--wt-radius-pill);+ padding: 0.05rem 0.5rem;+ line-height: 1.4;+ }}// ============================================================================diff --git a/docs/templates/shortcodes/experimental.html b/docs/templates/shortcodes/experimental.htmlindex 44bfd92b5..580e796fe 100644--- a/docs/templates/shortcodes/experimental.html+++ b/docs/templates/shortcodes/experimental.html@@ -1 +1 @@-<span class="badge-experimental">experimental</span>+<span class="badge-experimental"></span>diff --git a/skills/worktrunk/reference/faq.md b/skills/worktrunk/reference/faq.mdindex a6b953ae4..070de9b51 100644--- a/skills/worktrunk/reference/faq.md+++ b/skills/worktrunk/reference/faq.md@@ -159,7 +159,7 @@ Worktrunk runs `git` commands internally and optionally runs `gh` (GitHub) or `g1. **User hooks** (`~/.config/worktrunk/config.toml`) — Personal automation for all repositories2. **Project hooks** (`.config/wt.toml`) — Repository-specific automation-3. **LLM commands** (`~/.config/worktrunk/config.toml`) — Commit message generation and [branch summaries](https://worktrunk.dev/llm-commits/#branch-summaries-experimental)+3. **LLM commands** (`~/.config/worktrunk/config.toml`) — Commit message generation and [branch summaries](https://worktrunk.dev/llm-commits/#branch-summaries)4. **--execute flag** — Explicitly provided commandsUser hooks don't require approval (you defined them). Commands from project hooks require approval on first run. Approved commands are saved to user config. If a command changes, Worktrunk requires new approval.diff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.mdindex fffa8f2bb..3a3fac877 100644--- a/skills/worktrunk/reference/hook.md+++ b/skills/worktrunk/reference/hook.md@@ -158,7 +158,7 @@ build = "cargo build --release"## User hooks-Define hooks in `~/.config/worktrunk/config.toml` to run for all repositories. User hooks run before project hooks and don't require approval. For repository-specific user hooks, see [setting overrides](https://worktrunk.dev/config/#setting-overrides-experimental).+Define hooks in `~/.config/worktrunk/config.toml` to run for all repositories. User hooks run before project hooks and don't require approval. For repository-specific user hooks, see [setting overrides](https://worktrunk.dev/config/#setting-overrides).```toml# ~/.config/worktrunk/config.tomldiff --git a/skills/worktrunk/reference/list.md b/skills/worktrunk/reference/list.mdindex 0c4412a5d..e3818217f 100644--- a/skills/worktrunk/reference/list.md+++ b/skills/worktrunk/reference/list.md@@ -8,7 +8,7 @@ The table renders progressively: branch names, paths, and commit hashes appear i## Full mode-`--full` adds columns that require network access or LLM calls: [CI status](#ci-status) (GitHub/GitLab pipeline pass/fail), line diffs since the merge-base, and [LLM-generated summaries](#llm-summaries-experimental) of each branch's changes. The table displays instantly and columns fill in as results arrive.+`--full` adds columns that require network access or LLM calls: [CI status](#ci-status) (GitHub/GitLab pipeline pass/fail), line diffs since the merge-base, and [LLM-generated summaries](#llm-summaries) of each branch's changes. The table displays instantly and columns fill in as results arrive.## Examplesdiff --git a/skills/worktrunk/reference/llm-commits.md b/skills/worktrunk/reference/llm-commits.mdindex f1c17c2aa..230e0bea1 100644--- a/skills/worktrunk/reference/llm-commits.md+++ b/skills/worktrunk/reference/llm-commits.md@@ -82,7 +82,7 @@ With `summary = true` and a `[commit.generation] command` configured, WorktrunkSummaries appear in:- **`wt switch`** [interactive picker](https://worktrunk.dev/switch/#interactive-picker) — preview tab 5-- **`wt list --full`** — the Summary column (see [`wt list`](https://worktrunk.dev/list/#llm-summaries-experimental))+- **`wt list --full`** — the Summary column (see [`wt list`](https://worktrunk.dev/list/#llm-summaries))Enable in user config:diff --git a/skills/worktrunk/reference/step.md b/skills/worktrunk/reference/step.mdindex ebb79cfdb..4d5e5e0f6 100644--- a/skills/worktrunk/reference/step.md+++ b/skills/worktrunk/reference/step.md@@ -427,9 +427,9 @@ Usage: <b><span class=c>wt step copy-ignored</span></b> <span class=c>[OPTIONS]<<b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>Verbose output (-v: hooks, templates; -vv: debug report)-## wt step for-each+## wt step for-each [experimental]-[experimental] Run command in each worktree. Executes sequentially with real-time output; continues on failure.+Run command in each worktree. Executes sequentially with real-time output; continues on failure.Executes a command sequentially in every worktree with real-time output. Continues on failure and shows a summary at the end.@@ -493,9 +493,9 @@ Usage: <b><span class=c>wt step for-each</span></b> <span class=c>[OPTIONS]</spa<b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>Verbose output (-v: hooks, templates; -vv: debug report)-## wt step promote+## wt step promote [experimental]-[experimental] Swap a branch into the main worktree. Exchanges branches and gitignored files between two worktrees.+Swap a branch into the main worktree. Exchanges branches and gitignored files between two worktrees.**Experimental.** Use promote for temporary testing when the main worktree has special significance (Docker Compose, IDE configs, heavy build artifacts anchored to project root), and hooks & tools aren't yet set up to run on arbitrary worktrees. The idiomatic Worktrunk workflow does not use `promote`; instead each worktree has a full environment. `promote` is the only Worktrunk command which changes a branch in an existing worktree.@@ -565,9 +565,9 @@ Usage: <b><span class=c>wt step promote</span></b> <span class=c>[OPTIONS]</span<b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>Verbose output (-v: hooks, templates; -vv: debug report)-## wt step prune+## wt step prune [experimental]-[experimental] Remove worktrees merged into the default branch.+Remove worktrees merged into the default branch.Bulk-removes worktrees and branches that are integrated into the default branch, using the same criteria as `wt remove`'s branch cleanup. Stale worktree entries are cleaned up too.@@ -633,9 +633,9 @@ Usage: <b><span class=c>wt step prune</span></b> <span class=c>[OPTIONS]</span><b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>Verbose output (-v: hooks, templates; -vv: debug report)-## wt step relocate+## wt step relocate [experimental]-[experimental] Move worktrees to expected paths. Relocates worktrees whose path doesn't match the worktree-path template.+Move worktrees to expected paths. Relocates worktrees whose path doesn't match the worktree-path template.Moves worktrees to match the configured `worktree-path` template.diff --git a/skills/worktrunk/reference/tips-patterns.md b/skills/worktrunk/reference/tips-patterns.mdindex f7849e572..f594d2fd2 100644--- a/skills/worktrunk/reference/tips-patterns.md+++ b/skills/worktrunk/reference/tips-patterns.md@@ -165,7 +165,7 @@ With `summary = true` and [`commit.generation`](https://worktrunk.dev/config/#cosummary = true```-Disabled by default — when enabled, each branch's diff is sent to the configured LLM for summarization. See [LLM Commits](https://worktrunk.dev/llm-commits/#branch-summaries-experimental) for details.+Disabled by default — when enabled, each branch's diff is sent to the configured LLM for summarization. See [LLM Commits](https://worktrunk.dev/llm-commits/#branch-summaries) for details.## JSON APIdiff --git a/skills/worktrunk/reference/worktrunk.md b/skills/worktrunk/reference/worktrunk.mdindex afa747ac4..cfbf34ddb 100644--- a/skills/worktrunk/reference/worktrunk.md+++ b/skills/worktrunk/reference/worktrunk.md@@ -73,7 +73,7 @@ git branch -d feat{% end %}</td>- **[Merge workflow](https://worktrunk.dev/merge/)** — squash, rebase, merge, clean up in one command- **[Interactive picker](https://worktrunk.dev/switch/#interactive-picker)** — browse worktrees with live diff and log previews- **[Copy build caches](https://worktrunk.dev/step/)** — skip cold starts by sharing `target/`, `node_modules/`, etc between worktrees-- **[`wt list --full`](https://worktrunk.dev/list/#full-mode)** — [CI status](https://worktrunk.dev/list/#ci-status) and [AI-generated summaries](https://worktrunk.dev/list/#llm-summaries-experimental) per branch+- **[`wt list --full`](https://worktrunk.dev/list/#full-mode)** — [CI status](https://worktrunk.dev/list/#ci-status) and [AI-generated summaries](https://worktrunk.dev/list/#llm-summaries) per branch- **[PR checkout](https://worktrunk.dev/switch/#github-pull-requests)** — `wt switch pr:123` to jump straight to a PR's branch- **[Dev server per worktree](https://worktrunk.dev/hook/#dev-servers)** — `hash_port` template filter gives each worktree a unique port- ...and **[lots more](#next-steps)**diff --git a/src/cli/mod.rs b/src/cli/mod.rsindex 9d5be95d9..130e75604 100644--- a/src/cli/mod.rs+++ b/src/cli/mod.rs@@ -478,7 +478,7 @@ The table renders progressively: branch names, paths, and commit hashes appear i## Full mode-`--full` adds columns that require network access or LLM calls: [CI status](#ci-status) (GitHub/GitLab pipeline pass/fail), line diffs since the merge-base, and [LLM-generated summaries](#llm-summaries-experimental) of each branch's changes. The table displays instantly and columns fill in as results arrive.+`--full` adds columns that require network access or LLM calls: [CI status](#ci-status) (GitHub/GitLab pipeline pass/fail), line diffs since the merge-base, and [LLM-generated summaries](#llm-summaries) of each branch's changes. The table displays instantly and columns fill in as results arrive.## Examples@@ -1251,7 +1251,7 @@ build = "cargo build --release"## User hooks-Define hooks in `~/.config/worktrunk/config.toml` to run for all repositories. User hooks run before project hooks and don't require approval. For repository-specific user hooks, see [setting overrides](@/config.md#setting-overrides-experimental).+Define hooks in `~/.config/worktrunk/config.toml` to run for all repositories. User hooks run before project hooks and don't require approval. For repository-specific user hooks, see [setting overrides](@/config.md#setting-overrides).```toml# ~/.config/worktrunk/config.tomldiff --git a/src/help.rs b/src/help.rsindex 96e35202a..0646af53e 100644--- a/src/help.rs+++ b/src/help.rs@@ -425,7 +425,7 @@ Commands with pages: merge, switch, remove, list"/// | CLI source | Web docs |/// |------------|----------|/// | `` `●` green `` | `<span style='color:#0a0'>●</span> green` |-/// | `[experimental]` | `<span class="badge-experimental">experimental</span>` |+/// | `[experimental]` | `<span class="badge-experimental"></span>` (text via CSS) |/// | plain URL | markdown link |////// Only runs on `after_long_help` markdown — not on terminal reference blocks (those go@@ -441,10 +441,11 @@ fn post_process_for_html(text: &str) -> String {.replace("`●` yellow", "<span style='color:#a60'>●</span> yellow").replace("`⚠` yellow", "<span style='color:#a60'>⚠</span> yellow").replace("`●` gray", "<span style='color:#888'>●</span> gray")- // Experimental badges — styled pill labels for web docs+ // Experimental badges — empty span, text added via CSS ::after.+ // Empty so the span doesn't affect Zola's heading slug generation..replace("[experimental]",- "<span class=\"badge-experimental\">experimental</span>",+ "<span class=\"badge-experimental\"></span>",)// Convert plain URL references to markdown links for web docs// CLI shows: "Open an issue at https://github.com/max-sixty/worktrunk."@@ -572,6 +573,18 @@ fn format_subcommand_section(let raw_help = combine_command_docs(sub);let raw_help = raw_help.replace("```console\n", "```bash\n");+ // Extract [experimental] marker from content start → badge on heading instead.+ // The badge span is empty — text comes from CSS ::after — so it doesn't affect+ // Zola's heading slug generation or page TOC entries.+ let (heading_badge, raw_help) = if let Some(rest) = raw_help.strip_prefix("[experimental] ") {+ (+ " <span class=\"badge-experimental\"></span>",+ rest.to_string(),+ )+ } else {+ ("", raw_help)+ };+// Split content at first subdoc placeholder so command reference comes before nested subdocslet subdoc_marker = "<!-- subdoc:";let (main_content, subdoc_content) = if let Some(pos) = raw_help.find(subdoc_marker) {@@ -598,7 +611,7 @@ fn format_subcommand_section(let reference_block = get_help_reference(&command_path, Some(80));// Format the section: heading, main content, command reference, then nested subdocs- let mut section = format!("## {}\n\n", full_command);+ let mut section = format!("## {full_command}{heading_badge}\n\n");if !main_help.is_empty() {section.push_str(main_help.trim());diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rsindex 258318b30..15b3a18b4 100644--- a/tests/integration_tests/readme_sync.rs+++ b/tests/integration_tests/readme_sync.rs@@ -1585,7 +1585,7 @@ fn transform_docs_for_skill(content: &str) -> String {// Replace experimental markers (shortcode and HTML badge) with plain textlet content = ZOLA_EXPERIMENTAL_SHORTCODE.replace_all(&content, "[experimental]");let content = content.replace(- "<span class=\"badge-experimental\">experimental</span>",+ "<span class=\"badge-experimental\"></span>","[experimental]",);