docs(skill): say which worktree a command acts on

[worktrunk-bot]

Problem

wt finds the repository from the working directory and the worktree from the command's own arguments, but the worktrunk skill never says so — so agents treat the global -C <path> as the worktree selector and layer it on top of a branch argument that already names the target. #3889 measured 144 same-repo wt -C calls across 87 transcripts, most of them redundant.

Solution

Three changes, matching the fix the issue proposes:

• New "Which worktree a command acts on" section in skills/worktrunk/SKILL.md, placed before the config material so it reads early. Two rules: a command that names a branch already names its worktree, and -C moves the working directory (a different repository, a command with no branch argument, or a caller pinned outside a repo) rather than the worktree selection. Two ✓/✗ pairs from the issue make it concrete.
• Skill description: extended so it fires while an agent is composing a command — "working out which worktree a wt command will act on, or reaching for the global -C <path> to target one" — not only when editing config or debugging hooks.
• claude-code.md sentence scoped. The -C endorsement is now explicitly about the marker commands, which "take no worktree argument of their own", with a closing clause pointing at the general case.

Verified against the CLI rather than assumed:

Command	Worktree selector	-C warranted?
wt switch [BRANCH], wt remove [BRANCHES]...	branch argument	no
wt step diff --branch, wt step commit --branch	--branch	no
wt config state marker set --branch	--branch, but cwd must be in the repo	yes, when the host pins cwd outside
wt merge, wt step rebase|squash|push	none — [TARGET] is the merge target	yes

Also confirms the issue's second example: wt switch --create's --base already defaults to the default branch, so -C /path/to/repo "so it bases off main" changes nothing.

Not included

The issue's second suggestion — a paragraph on the -C doc comment in src/cli/mod.rs — is left out deliberately, as the issue itself flags it as "worth weighing separately": it regenerates the Global Options block on every command page and a large number of test_help snapshots. Happy to follow up if you want it.

Testing

cargo test --test integration test_docs_are_in_sync regenerated the four mirrors (skills/worktrunk/reference/claude-code.md, both plugin-skill copies, and the .well-known digest + description) and passes on a second run. cargo test --test integration readme_sync (16 tests) and test_plugin_layout_is_consolidated are green. The root-relative /switch/ and /remove/ links expand to https://worktrunk.dev/... in the skill copy as expected.

---

Closes #3889 — automated triage

[worktrunk-bot]

Two factual problems, both in the assertion the PR is built around. Verified against wt config state marker set --help / marker clear --help and require_selected_branch in src/git/repository/worktrees.rs.

claude-code.md now contradicts the SKILL.md section this same PR adds. The new clause says the marker commands "take no worktree argument of their own" — but wt config state marker set and marker clear both take --branch <BRANCH>, the very next sentence of the same bullet describes it, and rule 1 of the new "Which worktree a command acts on" section lists wt config state marker set --branch <branch> as a command that already names its worktree. The trailing "That pairing is specific to commands with no worktree selector" repeats the error and drops marker from its branch-naming list. The real reason a pinned-elsewhere host needs -C here is the one rule 2 already gives: the repository lookup still comes from the working directory. That's a stronger scoping than the invented one, and it doesn't leave an agent concluding --branch isn't available on the marker commands — which is the redundant--C reach #3889 counted.

The path-alias sentence over-reaches on one of its four commands. marker set/clear resolve --branch through require_selected_branch, which returns GitError::DetachedHead for ResolvedWorktree::Worktree { branch: None } — a marker is keyed by branch name, so there's nothing to key. The other three do handle it: wt step diff --branch goes through require_worktree (takes Worktree { path, .. }), and wt remove matches Worktree { path, branch: _ } and removes by path.

Everything else checks out. I re-verified each row of the PR body's table against --help — [TARGET] on merge/step rebase|squash|push is the merge target with no worktree selector, switch --base does default to the default branch, ../<repo>.<branch> matches the documented default layout — and the sync taxonomy is right: the two primaries (docs/src/content/docs/claude-code.md, skills/worktrunk/SKILL.md) are edited, the three mirrors are generated, the .well-known digest matches sha256sum skills/worktrunk/SKILL.md, and test_docs_are_in_sync passes locally.

Suggestions are on the primaries only; the mirrors and digest regenerate from cargo test --test integration test_docs_are_in_sync. I'll push these myself shortly since this is a bot-authored PR with no human author waiting — flagging them here first so the review records the state they respond to.