Publish shell integration, add a footer, dedupe global options

[max-sixty]

Guides and site presentation: one home per topic, a shell-integration page, a footer, and three rendering fixes.

Global options were emitted once per command reference

clap repeats the same ~20-line Global Options: block in every reference it renders, so a page assembled from subdocs stacked 11 copies on /config/ and 13 on /step/. That padded the pages and gave site search that many near-identical hits — "squash" returned both #command-reference and #command-reference-2. take_global_options cuts each reference at the heading as it is built, keeping only the first; one kept flag threads through the subdoc expansion and the page streams out rather than accumulating. Terminal --help renders through clap directly and is unchanged.

The config page also carried colliding anchors — two "Hooks" (#hooks, #hooks-1), two "Aliases", and seven "Examples" (#examples … #examples-6) — now qualified at their source in src/cli/config.rs: User/Project hooks, User/Project aliases, and Approval/Alias/State/Cache/Log/Variable examples.

/step/ still has its own set (eight "Examples", two "Options", two "Arguments", plus "Staging" and "Dry run" pairs). Qualifying those moves existing /step/#examples-N anchors, so it wants a pass of its own with the inbound links audited; the deduplication above already removes 13 Global Options blocks from that page.

Shell integration has a page

Shell-integration debugging was skill-only: five named warning messages, a PowerShell checklist, and the wrapper mechanism, with no site page — while the FAQ's answer to "wt switch didn't cd" was to install the Claude Code plugin. It is now /shell-integration/, offered first, with the plugin as the second route. The llms.txt listing serves every page as /<slug>.md from a hand-created symlink, so a new page was a 404 the listing still advertised; the symlink is added and the sync now fails when a listed page has none.

Presentation

• A site footer carries the version (read from Cargo.toml at build time), releases, changelog and license. No page named any of them, and /code-signing/ was reachable only from inside a collapsed block on the homepage. Starlight's Footer is wrapped rather than replaced.
• wt list --full renders 1157px inside an 800px content column, so 40% of it sat behind a horizontal scrollbar with the pane beside the column empty. A terminal frame now takes the whole pane where there is slack, measured with a query container rather than recomputed from Starlight's layout formula.
• The wt-command-reference frames offered a copy button for 3,877 characters of generated help text; they now expose no copy control. A console block listing several commands is as often a menu of alternatives as a recipe, and nothing in the markup tells them apart, so every command line in such a block carries its own copy control alongside the block's.
• The four command demos and the two hand-written figures get captions; the 2.33 MB homepage GIF below the fold loads lazily.

Sidebar order is pinned

site-navigation.mjs told readers a test_sidebar_matches_frontmatter_order would fail when the authored sidebar and the pages' sidebar.order disagreed. No such test existed, and the disagreement it describes is exactly what the survey found: remove listed before merge, Agent integration ahead of lower-numbered pages. The test is written, so the sidebar and the llms.txt ordering derived from the frontmatter can't drift apart again.

Guide corrections

• Tips & patterns was 26 flat H2 recipes in no order, all 26 in the sidebar. They group under five H2s — setup and layout, aliases and hooks, per-worktree services, working with agents, status/commits/logs — with each recipe demoted to H3. Anchors are level-independent, so existing /tips-patterns/#… fragments still resolve.
• -x 'opencode run' has been broken since 0.75.0 made -x a literal program: it is -x opencode -- run '<task>'.
• The branch-summary preview moved from tab 5 to 6 when the unified-diff tab landed; the recipe names the summary tab instead of a number.
• The Caddy recipe claimed feature-auth hashes to port 16460 — that is fix-auth's port. It is 18283.
• _ in wt list is same-commit and clean; the same-commit-with-changes glyph is –, which is not safe to delete.
• wt step prune removes branches with no worktree too, and the min-age guard ages a worktree by its creation time and a bare branch by its oldest reflog entry.
• wt step eval -v prints fifteen variables; the example showed two under a lead calling them "the available template variables".
• A filter applied to {{ vars.<key> }} acts on the placeholder the preview substitutes, so {{ vars.port | default('8080') }} previews as {{ vars.port }}, filter gone.
• The .git/wt/cache/ table was missing picker-preview, and wt config state clear prompts unless --yes.
• skills/worktrunk/reference/README.md was a symlink to the repo README that SKILL.md never referenced, and the plugin mirror dereferenced it into a 262-line copy carrying the star-history token, share links, and a logo path resolving nowhere. Nothing generated it, so deleting the symlink is the whole fix.
• One home per topic: agent handoffs stay in tips-patterns, activity markers in claude-code.md, alias-template deferral in extending.md, and the codename filter's two worktree-path recipes give way to the config page that owns path templates. The FAQ's "Running tests" and "How can I contribute?" duplicated the README's Contributing block down to the share URLs.
• The FAQ linked /worktrunk/#install, the noindex compatibility route; the plugin hook shim's Windows Terminal hint pointed there too. Both use /#install, where the new sidebar Install entry goes.
• Example names settle on myproject / feature-auth; "sibling to main repo" becomes "sibling to the main worktree", and wt remove's "target worktree" becomes "the worktree being removed" per the project's own terminology rule.

UX survey items: #36, #37, #38, #39, #45, #47, #48, #49, #50, #51, #52, #61, #94, #95, #96, #97, #99, #100.

Reviewable files: the hand-written pages under docs/src/content/docs/ (notably the new shell-integration.md, tips-patterns.md, faq.md), docs/src/components/Footer.astro, docs/src/plugins/worktrunk-terminal.mjs, docs/src/site-navigation.mjs, docs/tests/*.mjs, src/help.rs, plugins/worktrunk/hooks/wt.sh. Generated mirrors and snapshots are regenerated.

This was written by Claude Code on behalf of max-sixty

🤖 Generated with Claude Code

https://claude.ai/code/session_01XAUYWFN9d9oh6jyoQiouHb

[worktrunk-bot]

Checked the generator change by auditing what actually left the generated pages: across config.md, step.md, list.md, switch.md, merge.md and remove.md the only removed lines are Global Options blocks (12 on /step/, 10 on /config/, 1 on /list/) — nothing else is cut, and wt config show's Output: group survives, so the "section is last" assumption holds where it's exercised. Two things below.

/step/ still carries the anchor collisions /config/ just lost. The qualified headings landed in src/cli/config.rs only, so on the current head /config/ is down to the structural #command-reference repeats while /step/ is unchanged from the base: eight Examples (#examples … #examples-7, at the page top plus rebase, push, eval, for-each, prune, relocate, tether), two Options (commit, squash), two Arguments (for-each, tether), and pairs for Staging and Dry run. That's the same near-identical-search-hit problem the description opens with, on the page it names as the worse of the two, and the description reads as though both were covered. The fix is the same shape as the config.rs one — qualify at the after_long_help source in src/cli/step.rs.

Not approving. src/cli/mod.rs and src/cli/step.rs hold the wt remove --force-delete and wt step prune definitions, which this repo's Data-Loss Surface: Hold for Human Review puts outside what I approve even when the diff is help text. For what it's worth the edits there run the safe direction and check out against the code: _ really is same-commit and clean (MainState::Empty vs SameCommit in src/commands/list/model/state.rs), prune really does age a bare branch by its oldest reflog entry (orphan_branch_age takes .lines().last()), and feature-auth really does hash to 18283, not fix-auth's 16460.

[worktrunk-bot]

This is the file's only pointer that leaves the skill: every other one is a bundled path (reference/config.md#user-hooks, reference/step.md#wt-step-for-each), and this content ships beside it at reference/tips-patterns.md#agent-handoffs — the section the inlined tmux/Zellij commands moved to. An agent reading the skill without network access loses the handoff commands entirely, which is the one place they were guaranteed to have them.

Suggested change

	When the user requests spawning a worktree with an agent in a background session ("spawn a worktree for...", "hand off to another agent"), use the tmux or Zellij command from [Agent handoffs](https://worktrunk.dev/tips-patterns/#agent-handoffs), substituting the CLI you are running as for `claude`.
	When the user requests spawning a worktree with an agent in a background session ("spawn a worktree for...", "hand off to another agent"), use the tmux or Zellij command from `reference/tips-patterns.md#agent-handoffs`, substituting the CLI you are running as for `claude`.

[max-sixty]

Right on both counts.

The description did read as though /step/ was covered; it wasn't — the qualified headings landed in src/cli/config.rs only. Corrected it to say so, and to note why /step/ wants a pass of its own rather than a line in this one: qualifying those headings moves existing /step/#examples-N anchors, so the inbound links need auditing the way config.rs's did. What this branch does give that page is the 13 Global Options blocks it no longer repeats.

The data-loss hold is understood and correct — src/cli/mod.rs and src/cli/step.rs carry the wt remove --force-delete and wt step prune definitions, so this needs a human on it regardless of the diff being help text. Leaving it for the repo owner. Thanks for verifying the three factual claims (_ as same-commit-and-clean, orphan_branch_age's .lines().last(), and 18283) even while holding.

This was written by Claude Code on behalf of max-sixty

[worktrunk-bot]

One item from the review sits outside "both counts": the inline suggestion on skills/worktrunk/SKILL.md (thread) is still open at bf6475d1. Line 140 sends agent handoffs to https://worktrunk.dev/tips-patterns/#agent-handoffs — the file's only content pointer that leaves the skill, with every other one a bundled path — while skills/worktrunk/reference/tips-patterns.md ships in the same directory carrying that exact ### Agent handoffs section. Flagging only because it's the one point the reply doesn't touch; whether it belongs on this branch is your call.

[worktrunk-bot]

#4001 (mine, opened this morning) re-derived the /worktrunk/#install → /#install fix this PR already makes — same four non-test edits, same widening of SITE_LINK_PATTERN. I've closed it as a duplicate; nothing here needs changing.

One piece of it may be worth carrying over, in a weaker form than my review of #4001 claimed. That review said this PR leaves the widened regex untested. It doesn't: reverting (?:([^)/#]+)/)? back to ([^)/]+)/ on this branch fails test_docs_are_in_sync, because the FAQ's ](/#install) then falls through to assert_no_untransformed_site_links. What's actually uncovered is narrower — the pin is coupled to that one FAQ line, so rewording it silently unpins the widening, and the bare ](/) form has no coverage at all (grep -rn '](/)' docs/src/content/docs/ src/cli/ returns nothing).

This test closes both gaps. It passes on this branch at bf6475d1 as written, dropped in after test_legacy_zola_link_fails_the_guardrail:

/// A link naming the site root carries no page segment. Both generated
/// surfaces have to rewrite it, or the only spelling the docs can use is
/// `/worktrunk/` — the route the home page itself marks `noindex` with a
/// canonical pointing back at `/`.
///
/// `](/page)` (a page segment without its trailing slash) stays unmatched, so
/// the guardrail keeps catching it instead of the widened pattern quietly
/// absorbing it.
#[test]
fn test_site_root_links_rewrite_to_the_canonical_url() {
    let rewrite = |content: &str| {
        SITE_LINK_PATTERN
            .replace_all(content, expand_site_link)
            .into_owned()
    };
    assert_eq!(
        rewrite("See [installation](/#install) and [hooks](/hook/#types)."),
        "See [installation](https://worktrunk.dev/#install) and \
         [hooks](https://worktrunk.dev/hook/#types)."
    );
    assert_eq!(
        rewrite("[Worktrunk](/) is a CLI."),
        "[Worktrunk](https://worktrunk.dev/) is a CLI."
    );
    // Both surfaces, since each applies the rewrite on its own path.
    assert!(
        transform_docs_to_github("[install](/#install)").contains("https://worktrunk.dev/#install")
    );
    assert!(
        finalize_skill_content("[install](/#install)").contains("https://worktrunk.dev/#install")
    );
    // Unchanged: a slash-less page segment is still not a site link.
    assert_eq!(rewrite("[hooks](/hook)"), "[hooks](/hook)");
}

Take it or leave it — the fix itself is complete here either way.

What I ran

In a worktree at bf6475d1, with only the test above added:

• cargo test --test integration test_site_root_links_rewrite_to_the_canonical_url — passes.
• Same test with SITE_LINK_PATTERN reverted to ([^)/]+)/ — fails on the first assertion ([installation](/#install) left unrewritten).
• Whole suite with the regex reverted and the new test removed, to check what the existing tests already catch — test_docs_are_in_sync fails on the FAQ line, 18 others pass. That is the coupling described above.