Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs: require full release documentation review (#4412)
Maximilian Roos7ac07ecf6712
diff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.mdindex 3e15f3b44..dea788cba 100644--- a/.claude/skills/release/SKILL.md+++ b/.claude/skills/release/SKILL.md@@ -27,7 +27,7 @@ metadata:```Launch a ci-reporter to monitor `$RUN` to completion (avoid `gh run watch` — it can hang). Fix any failure before continuing.3. **Check current version**: Read `version` in `Cargo.toml`-4. **Review commits**: Check commits since last release to understand scope of changes. Audit the cumulative diff for the data-loss surface (see [Data-Loss Surface Review](#data-loss-surface-review)) before proceeding.+4. **Review commits**: Check commits since last release to understand scope of changes. Audit the cumulative diff for the data-loss surface (see [Data-Loss Surface Review](#data-loss-surface-review)) and documentation (see [Documentation Review](#documentation-review)).5. **Check library API compatibility (advisory)**: Run `cargo semver-checks check-release -p worktrunk` (install with `cargo install cargo-semver-checks --locked` if missing) as a bump-level input, not a compat gate — worktrunk ships breaking library changes freely. If it reports breaking changes, that's fine; under semver the bump must still be minor (pre-1.0) or major (post-1.0). See "Library API Compatibility" below.6. **Credit contributors**: Check for external PR authors and issue reporters (see "Credit External Contributors" and "Credit Issue Reporters" below)7. **Determine release type**: Pick the bump from the changes (including semver-checks result). Ask the user only if the choice is genuinely ambiguous (see below).@@ -41,7 +41,7 @@ metadata:```bashgit reset --soft HEAD~1 && git add -A && git commit -m "Release vX.Y.Z"```-11. **Merge to main**: push the release branch, open a PR, wait for CI, and merge it. Keep the worktree — the remaining steps run from it. Then move the branch onto the merged tip:+11. **Merge to main**: complete the documentation review on the final candidate, then push the release branch, open a PR, wait for CI, and merge it. Keep the worktree — the remaining steps run from it. Then move the branch onto the merged tip:```bashgit fetch origin && git reset --keep origin/main```@@ -53,6 +53,8 @@ metadata:```Clean means the changelog at `origin/main` documents every user-facing commit listed. With no drift the list is one line, the `Release vX.Y.Z (#NNNN)` squash commit. Review anything else that drifted in during the window and fold what's user-facing into the changelog with a follow-up squash PR, then re-fetch and re-run. The list only grows across passes — the drifted commits stay, joined by the follow-up's own squash commit — so each pass re-checks coverage over a longer list.+ Extend the documentation review to any changes since its reviewed SHA, including corrections and commits that arrived during CI. Record the final reviewed SHA and resolve findings before tagging.+Once clean, tag `origin/main`. The check and the tag then name the same ref, and it's main's tip, so the tag is reachable from `main`:```bashgit tag vX.Y.Z origin/main && git push origin vX.Y.Z@@ -93,6 +95,27 @@ Pool the candidates, dedupe, and analyze each against the data-safety invariantsSurface the full adjudicated list and get explicit sign-off before tagging. Do not tag a release with an unresolved deletion-surface candidate, even if it looks acceptable.+## Documentation Review++The release reviews all documentation changes since the previous release, including changes already on `main` and edits made during release preparation. Public docs are curated product guidance: each passage should help readers understand or use Worktrunk, with detail proportional to how many readers need it.++Start from the full release diff to inventory documentation wherever it lives:++```bash+git diff --name-status v<last-version> HEAD+git diff v<last-version> HEAD+```++Give an independent reviewer the previous tag, candidate SHA, and complete inventory. Cover site pages, README files, CLI help, configuration and command examples, shipped skills, and release notes. Review canonical sources once and check their generated copies for agreement; `docs/AGENTS.md` defines ownership and sync.++The reviewer reads every changed passage in its surrounding section and checks:++- **Purpose and proportion:** does it change what readers understand or do? Cut redundant explanations and implementation or regression details that belong in tests or PRs. A correctness fix needs prose only when usage changes or an existing claim becomes false.+- **Clarity and concision:** use concrete, consistent terminology; introduce concepts before relying on them; rewrite definitions in place rather than layering caveats. Shortening must preserve necessary instructions and qualifications.+- **Accuracy and usability:** verify claims against behavior and examples against their commands. Check links and read affected rendered sections as a reader encounters them.++For each finding, give the location, reader impact, and a concrete replacement or deletion. Apply corrections in the canonical source, regenerate mirrors, and run the checks in `docs/AGENTS.md`. Have the reviewer check the corrected passages before closing findings. Record the reviewed range and SHA, coverage, findings, and their disposition in the release review; unresolved findings block tagging. Changelog claims and credits also receive the verification below.+## CHANGELOG ReviewDraft entries from the commits since the last release:diff --git a/docs/src/content/docs/config.md b/docs/src/content/docs/config.mdindex 12fcc4441..1fabb011c 100644--- a/docs/src/content/docs/config.md+++ b/docs/src/content/docs/config.md@@ -636,7 +636,6 @@ On first run without shell integration, Worktrunk offers to install it. On first## Environment variablesAll user config options can be overridden with environment variables using the `WORKTRUNK_` prefix.-Invalid environment overrides are ignored with a warning; other valid overrides still apply.### Naming convention@@ -1257,7 +1256,7 @@ $ wt list### Use cases- **Work status** — `🚧` WIP, `✅` ready for review, `🔥` urgent-- **Agent tracking** — The agent plugins ([Claude Code](/claude-code/), Codex, OpenCode, Pi, oh-my-pi) set markers automatically+- **Agent tracking** — [Agent plugins](/claude-code/) set markers automatically- **Notes** — Any short text: `"blocked"`, `"needs tests"`### Storagediff --git a/docs/src/content/docs/extending.md b/docs/src/content/docs/extending.mdindex cc65e0751..573935a77 100644--- a/docs/src/content/docs/extending.md+++ b/docs/src/content/docs/extending.md@@ -231,7 +231,7 @@ Aside from the differences below, hooks and aliases behave the same.| Source discrimination | `user:` / `project:` / `user:name` / `project:name` filter syntax | Run user first, then project; no filter syntax || `--help` | `wt hook --help` lists hook types; `wt hook <type> --help` shows flags and arguments for that type | The template body is the documentation: `wt <alias> --help` redirects to `wt config alias show` / `dry-run`. `wt --help` and `wt step --help` list configured aliases alongside built-in commands || Inspection | `wt hook show [type] [--expanded]` | `wt config alias show <name>` / `wt config alias dry-run <name>` |-| Stdin | A hook running in the foreground inherits parent stdin, same as aliases (interactive prompts work) — `pre-*` hooks, and any type under `wt hook <type> --foreground`; detached `post-*` hooks and concurrent children read EOF | Serial steps inherit parent stdin (pipes pass through; interactive TUIs like `wt switch` keep the tty); concurrent children read EOF |+| Stdin | See [Interactive hooks](/hook/#interactive-hooks) | Serial steps inherit parent stdin || Template-context extras | `hook_type`, `hook_name`, per-type operation vars (`base`, `target`, `pr_number`, …) | `args` on top of the shared base variables |</details>diff --git a/docs/src/content/docs/faq.md b/docs/src/content/docs/faq.mdindex 0282ddb05..76bdd8107 100644--- a/docs/src/content/docs/faq.md+++ b/docs/src/content/docs/faq.md@@ -139,6 +139,7 @@ Worktrunk stores repository state, caches, and logs under `.git/`:| Location | Purpose | Created by ||----------|---------|------------|| `git config worktrunk.*` | Cached default branch, switch history, branch markers, custom variables | Various commands |+| `refs/wt-backup/<branch>` | [Squash backups](/step/#wt-step-squash--recovering-staged-changes); preserved by state clearing | `wt step squash`, `wt merge` || `.git/wt/cache/{kind}/*.json` | Cached CI status, the largest PR/MR number seen (sizes the `wt list` CI column), and git command results (merge-tree, integration probes, diff stats, ancestry checks, ahead/behind counts, merge bases) | `wt list`, `wt merge`, `wt remove` || `.git/wt/cache/summary/{branch}/{hash}.json` | Cached LLM branch summaries, content-addressed by diff hash | `wt list --full`, `wt switch` (when `[list] summary = true`) || `.git/wt/cache/picker-preview/*.json` | Rendered preview panes for the interactive picker | `wt switch` |@@ -152,7 +153,7 @@ Worktrunk stores repository state, caches, and logs under `.git/`:None of this is tracked by git or pushed to remotes.-**To remove:** `wt config state clear` removes all repository data: config keys, caches, markers, hints, variables, logs, and stale trash. It prompts before removing anything worktrunk can't recompute, unless you pass `--yes`.+**To remove:** `wt config state clear` removes repository state: config keys, caches, markers, hints, variables, logs, and stale trash. It prompts before removing anything worktrunk can't recompute, unless you pass `--yes`.### 5. Agent integrations@@ -215,7 +216,7 @@ A branch checked out in a second worktree is retained regardless, `-D` included.- `wt merge` / `wt step push` — the target branch's checked-out worktree is updated to the merged commits, so a file those commits delete disappears from it, and an ignored file at a path they track is overwritten — the same result a `git merge` run in that worktree would produce. Uncommitted changes at paths the merge doesn't touch stay in place, staged or not; one at a path it does touch refuses the merge upfront, naming the file- `wt remove` / `wt step prune` — unregister a stale worktree (`⊟` in `wt list`) by deleting its `.git/worktrees/<id>` entry, as `git worktree prune` does, but for that worktree only. Files still in its directory stay. An entry whose index holds staged changes, or with a rebase, merge, or other operation in progress, is kept unless `wt remove --force` names it, since `git worktree repair` can restore it only while the entry exists- `wt remove` — also stops the removed worktree's `git fsmonitor--daemon` (under `core.fsmonitor=true`), and sweeps `.git/wt/trash/` entries older than 24 hours along with fsmonitor daemons whose worktree no longer exists-- `wt config state clear` — removes all worktrunk data from `.git/` (config keys, caches, markers, hints, variables, logs, stale trash)+- `wt config state clear` — clears config keys, caches, markers, hints, variables, logs, and stale trash- `wt config shell install` — replaces an existing fish or Nushell wrapper file whole, and removes one an older version installed at a previous location (fish `conf.d/wt.fish`, Nushell `<config-dir>/vendor/autoload/wt.nu`), printing each removal; [Files created](/shell-integration/#files-created) names the file each shell gets- `wt config shell uninstall` — removes the lines that run `wt config shell init` from bash/zsh/PowerShell rc files, and deletes wrapper and completion files carrying worktrunk's content markers (fish `functions/`, `conf.d/`, and `completions/`; nushell `vendor/autoload`). Every removed line is printed- `wt config plugins opencode uninstall` / `wt config plugins pi uninstall` / `wt config plugins omp uninstall` — deletes that agent's `worktrunk.ts` plugin file. Only worktrunk's own file is touched; the rest of the agent's plugin directory is left alonediff --git a/docs/src/content/docs/hook.md b/docs/src/content/docs/hook.mdindex d92f420c1..cb317f55d 100644--- a/docs/src/content/docs/hook.md+++ b/docs/src/content/docs/hook.md@@ -79,7 +79,7 @@ A string is a single command:pre-start = "npm install"```-A table is multiple commands that run concurrently:+A table names commands. With multiple keys, they run concurrently:```toml# .config/wt.toml@@ -262,7 +262,7 @@ setup = "cp {{ worktree_path_of_branch('main') }}/config.local {{ worktree_path## Interactive hooks-A hook running in the foreground inherits wt's stdin, so it can ask before continuing:+Hooks can prompt when run serially in the foreground, as in this `pre-start` hook:```toml# .config/wt.toml@@ -270,10 +270,6 @@ A hook running in the foreground inherits wt's stdin, so it can ask before contitrust = "gum confirm 'trust this worktree?' && mise trust"```-That covers `pre-*` hooks and any type under `wt hook <type> --foreground`, except where the hook is a concurrent group — a table with two or more keys, whose children would race for the terminal, so each reads EOF instead. A detached `post-*` hook reads EOF too, having no terminal at all. Nothing is ever piped in — a hook reads its context through template variables, whatever form it runs in.--Foreground steps run in order and share one stdin, so a step that drains it to EOF — a `cat` or a `read` loop — leaves nothing for the steps behind it when that stdin is a pipe or a file. Under a terminal each step can prompt in turn. Steps accumulate across config files, so a user `[pre-start]` and a project `[pre-start]` form one pipeline.-Logic that templates can't express belongs in a script, with the values it needs passed as arguments:```tomldiff --git a/docs/src/content/docs/list.md b/docs/src/content/docs/list.mdindex 7d3d2ed09..817152de6 100644--- a/docs/src/content/docs/list.md+++ b/docs/src/content/docs/list.md@@ -426,7 +426,7 @@ The single highest-priority state describing the branch's relation to the defaul### integration reasons-`default_branch.integration.reason` records which check matched. Checks run cheapest-first and the first match wins. The reason itself is JSON-only: the table shows `"same_commit"` as `_` (or `–` with uncommitted changes) and every other reason as `⊂` when the working tree is clean:+`default_branch.integration.reason` records which check matched. Checks run cheapest-first and the first match wins. See [Default branch](#default-branch) for symbols.| Value | Meaning ||-------|---------|diff --git a/docs/src/content/docs/merge.md b/docs/src/content/docs/merge.mdindex 05f213c8d..8d0853488 100644--- a/docs/src/content/docs/merge.md+++ b/docs/src/content/docs/merge.md@@ -78,7 +78,7 @@ $ wt merge --no-commit --no-rebase`wt merge` runs these steps:1. **Commit** — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in the background. This step is skipped when squashing (the default) — changes are staged during the squash step instead. With `--no-squash`, this is the only commit step.-2. **Squash** — Combines all commits since target into one (like GitHub's "Squash and merge"). Use `--stage` to control what gets staged: `all` (default), `tracked`, or `none`. Working-tree changes swept into the squash are backed up first to `refs/wt-backup/<branch>`; see [`wt step squash`](/step/#wt-step-squash) for recovery. With `--no-squash`, individual commits are preserved.+2. **Squash** — Combines all commits since target into one (like GitHub's "Squash and merge"). Pre-commit hooks run before staging; post-commit hooks run in the background after committing. Use `--stage` to control what gets staged: `all` (default), `tracked`, or `none`. Working-tree changes swept into the squash are backed up first to `refs/wt-backup/<branch>`; see [`wt step squash`](/step/#wt-step-squash) for recovery. With `--no-squash`, individual commits are preserved.3. **Rebase** — Rebases onto target, skipping when nothing needs replaying ([`wt step rebase`](/step/#wt-step-rebase) gives the conditions). A conflict stops the merge with the rebase left open in the worktree, to resolve or abort. With `--no-rebase`, the graph produced by earlier commit/squash steps is preserved and the target must be able to fast-forward to its tip.4. **Pre-merge hooks** — Hooks run after rebase, before merge. Failures abort. See [`wt hook`](/hook/).5. **Merge** — Fast-forward merge to the target branch ([`wt step push`](/step/#wt-step-push)). With `--no-ff`, a merge commit is created instead — semi-linear history after the default rebase, while explicit `--no-rebase` preserves the graph produced by earlier steps before adding the merge commit. Non-fast-forward merges are rejected.diff --git a/docs/src/content/docs/remove.md b/docs/src/content/docs/remove.mdindex b60eec74a..6e89c4b86 100644--- a/docs/src/content/docs/remove.md+++ b/docs/src/content/docs/remove.md@@ -104,7 +104,7 @@ Unix only; on Windows `--reap` is rejected.## JSON output-`--format=json` prints one object per removal to stdout: `{kind, branch, path, branch_outcome, branch_checked_out_at}` for a worktree, with `pruned` in place of `path` for a branch-only removal, plus `detached_worktree` — a detached worktree left at the branch's configured path.+`--format=json` prints one object per removal to stdout: `{kind, branch, path, branch_outcome, branch_checked_out_at}` for a worktree, with `pruned` in place of `path` for a branch-only removal. Branch-only results also include `detached_worktree`: the path of a detached worktree left behind, or `null`.`branch_outcome` names what happened to the branch, so a caller can tell a deletion the removal declined from one it was never asked to make:diff --git a/docs/src/content/docs/step.md b/docs/src/content/docs/step.mdindex 03c3792a4..f3ddac75a 100644--- a/docs/src/content/docs/step.md+++ b/docs/src/content/docs/step.md@@ -205,9 +205,9 @@ The squash commit is made on a detached HEAD, as `git rebase` does, so git's own### Recovering staged changes-Before absorbing staged changes, Worktrunk backs up the index to `refs/wt-backup/<branch>`. The backup commit's parent preserves the branch tip before squashing. Unstaged and untracked files outside the selected staging mode stay in the original worktree and are not captured by the backup.+Before squashing staged changes, Worktrunk saves them to `refs/wt-backup/<branch>`. Changes left unstaged are not included in the backup.-The output prints the backup ref and a command to open its saved commit on a recovery branch in a new worktree. That command uses the backup's immutable SHA and skips project hooks. It preserves current branches, files, and staging, and also works after `wt merge` removes the source worktree.+The output prints a command to recover the saved changes in a new worktree, including after `wt merge` removes the original.### Options@@ -825,7 +825,7 @@ In `wt list`, candidates show `_` (same commit) or `⊂` (content integrated). RLocked worktrees, worktrees with uncommitted changes, and the main worktree are always skipped. The current worktree is removed last, triggering cd to the primary worktree. Pre-remove and post-remove hooks run for each removal; a candidate whose hooks include an unapproved project command is skipped with `(approval required)` (pre-approve with `wt config approvals add`, or pass `--yes`).-Removals and their hooks may run concurrently across worktrees. Each worktree's pre-remove hooks finish before its removal begins. Hooks must coordinate writes to shared resources and avoid writing into other worktrees being pruned.+Prune removes worktrees concurrently, so hooks that write shared resources must coordinate those writes.### Min-age guarddiff --git a/docs/src/content/docs/tips-patterns.md b/docs/src/content/docs/tips-patterns.mdindex afcac31e1..be38f1525 100644--- a/docs/src/content/docs/tips-patterns.md+++ b/docs/src/content/docs/tips-patterns.md@@ -68,7 +68,7 @@ git fetch origingit remote set-head origin --auto```-`git clone --bare` records the `origin` URL but no fetch refspec, so without the `git config` line `git fetch` never creates remote-tracking branches like `origin/main`, and tools that read them (lazygit, editor integrations) see no remote branches. `git remote set-head` then points `origin/HEAD` at the remote's default branch.+The fetch refspec creates remote-tracking branches such as `origin/main`; `git remote set-head` records the remote's default branch.With `worktree-path = "{{ repo_path }}/../{{ branch | sanitize }}"`, worktrees become subdirectories of `myproject/`:@@ -114,7 +114,7 @@ Now `wt switch --create feature` creates `myproject/feature/`.The project config (`.config/wt.toml`) must live inside a worktree — the bare `.git` directory has no tracked files. Once the first worktree exists, create it from there:```bash-cd myproject/main+wt switch mainwt config create --project```diff --git a/plugins/worktrunk/skills/worktrunk/reference/config.md b/plugins/worktrunk/skills/worktrunk/reference/config.mdindex 6cf051803..facf030f7 100644--- a/plugins/worktrunk/skills/worktrunk/reference/config.md+++ b/plugins/worktrunk/skills/worktrunk/reference/config.md@@ -628,7 +628,6 @@ On first run without shell integration, Worktrunk offers to install it. On first## Environment variablesAll user config options can be overridden with environment variables using the `WORKTRUNK_` prefix.-Invalid environment overrides are ignored with a warning; other valid overrides still apply.### Naming convention@@ -1249,7 +1248,7 @@ $ wt list### Use cases- **Work status** — `🚧` WIP, `✅` ready for review, `🔥` urgent-- **Agent tracking** — The agent plugins ([Claude Code](https://worktrunk.dev/claude-code/), Codex, OpenCode, Pi, oh-my-pi) set markers automatically+- **Agent tracking** — [Agent plugins](https://worktrunk.dev/claude-code/) set markers automatically- **Notes** — Any short text: `"blocked"`, `"needs tests"`### Storagediff --git a/plugins/worktrunk/skills/worktrunk/reference/extending.md b/plugins/worktrunk/skills/worktrunk/reference/extending.mdindex 2e8756f4f..58a6cb5cc 100644--- a/plugins/worktrunk/skills/worktrunk/reference/extending.md+++ b/plugins/worktrunk/skills/worktrunk/reference/extending.md@@ -227,7 +227,7 @@ Aside from the differences below, hooks and aliases behave the same.| Source discrimination | `user:` / `project:` / `user:name` / `project:name` filter syntax | Run user first, then project; no filter syntax || `--help` | `wt hook --help` lists hook types; `wt hook <type> --help` shows flags and arguments for that type | The template body is the documentation: `wt <alias> --help` redirects to `wt config alias show` / `dry-run`. `wt --help` and `wt step --help` list configured aliases alongside built-in commands || Inspection | `wt hook show [type] [--expanded]` | `wt config alias show <name>` / `wt config alias dry-run <name>` |-| Stdin | A hook running in the foreground inherits parent stdin, same as aliases (interactive prompts work) — `pre-*` hooks, and any type under `wt hook <type> --foreground`; detached `post-*` hooks and concurrent children read EOF | Serial steps inherit parent stdin (pipes pass through; interactive TUIs like `wt switch` keep the tty); concurrent children read EOF |+| Stdin | See [Interactive hooks](https://worktrunk.dev/hook/#interactive-hooks) | Serial steps inherit parent stdin || Template-context extras | `hook_type`, `hook_name`, per-type operation vars (`base`, `target`, `pr_number`, …) | `args` on top of the shared base variables |</details>diff --git a/plugins/worktrunk/skills/worktrunk/reference/faq.md b/plugins/worktrunk/skills/worktrunk/reference/faq.mdindex 0d5228b8e..c4dd0ecbc 100644--- a/plugins/worktrunk/skills/worktrunk/reference/faq.md+++ b/plugins/worktrunk/skills/worktrunk/reference/faq.md@@ -135,6 +135,7 @@ Worktrunk stores repository state, caches, and logs under `.git/`:| Location | Purpose | Created by ||----------|---------|------------|| `git config worktrunk.*` | Cached default branch, switch history, branch markers, custom variables | Various commands |+| `refs/wt-backup/<branch>` | [Squash backups](https://worktrunk.dev/step/#wt-step-squash--recovering-staged-changes); preserved by state clearing | `wt step squash`, `wt merge` || `.git/wt/cache/{kind}/*.json` | Cached CI status, the largest PR/MR number seen (sizes the `wt list` CI column), and git command results (merge-tree, integration probes, diff stats, ancestry checks, ahead/behind counts, merge bases) | `wt list`, `wt merge`, `wt remove` || `.git/wt/cache/summary/{branch}/{hash}.json` | Cached LLM branch summaries, content-addressed by diff hash | `wt list --full`, `wt switch` (when `[list] summary = true`) || `.git/wt/cache/picker-preview/*.json` | Rendered preview panes for the interactive picker | `wt switch` |@@ -148,7 +149,7 @@ Worktrunk stores repository state, caches, and logs under `.git/`:None of this is tracked by git or pushed to remotes.-**To remove:** `wt config state clear` removes all repository data: config keys, caches, markers, hints, variables, logs, and stale trash. It prompts before removing anything worktrunk can't recompute, unless you pass `--yes`.+**To remove:** `wt config state clear` removes repository state: config keys, caches, markers, hints, variables, logs, and stale trash. It prompts before removing anything worktrunk can't recompute, unless you pass `--yes`.### 5. Agent integrations@@ -211,7 +212,7 @@ A branch checked out in a second worktree is retained regardless, `-D` included.- `wt merge` / `wt step push` — the target branch's checked-out worktree is updated to the merged commits, so a file those commits delete disappears from it, and an ignored file at a path they track is overwritten — the same result a `git merge` run in that worktree would produce. Uncommitted changes at paths the merge doesn't touch stay in place, staged or not; one at a path it does touch refuses the merge upfront, naming the file- `wt remove` / `wt step prune` — unregister a stale worktree (`⊟` in `wt list`) by deleting its `.git/worktrees/<id>` entry, as `git worktree prune` does, but for that worktree only. Files still in its directory stay. An entry whose index holds staged changes, or with a rebase, merge, or other operation in progress, is kept unless `wt remove --force` names it, since `git worktree repair` can restore it only while the entry exists- `wt remove` — also stops the removed worktree's `git fsmonitor--daemon` (under `core.fsmonitor=true`), and sweeps `.git/wt/trash/` entries older than 24 hours along with fsmonitor daemons whose worktree no longer exists-- `wt config state clear` — removes all worktrunk data from `.git/` (config keys, caches, markers, hints, variables, logs, stale trash)+- `wt config state clear` — clears config keys, caches, markers, hints, variables, logs, and stale trash- `wt config shell install` — replaces an existing fish or Nushell wrapper file whole, and removes one an older version installed at a previous location (fish `conf.d/wt.fish`, Nushell `<config-dir>/vendor/autoload/wt.nu`), printing each removal; [Files created](https://worktrunk.dev/shell-integration/#files-created) names the file each shell gets- `wt config shell uninstall` — removes the lines that run `wt config shell init` from bash/zsh/PowerShell rc files, and deletes wrapper and completion files carrying worktrunk's content markers (fish `functions/`, `conf.d/`, and `completions/`; nushell `vendor/autoload`). Every removed line is printed- `wt config plugins opencode uninstall` / `wt config plugins pi uninstall` / `wt config plugins omp uninstall` — deletes that agent's `worktrunk.ts` plugin file. Only worktrunk's own file is touched; the rest of the agent's plugin directory is left alonediff --git a/plugins/worktrunk/skills/worktrunk/reference/hook.md b/plugins/worktrunk/skills/worktrunk/reference/hook.mdindex 5006b6541..b0e4af4b0 100644--- a/plugins/worktrunk/skills/worktrunk/reference/hook.md+++ b/plugins/worktrunk/skills/worktrunk/reference/hook.md@@ -73,7 +73,7 @@ A string is a single command:pre-start = "npm install"```-A table is multiple commands that run concurrently:+A table names commands. With multiple keys, they run concurrently:```toml# .config/wt.toml@@ -256,7 +256,7 @@ setup = "cp {{ worktree_path_of_branch('main') }}/config.local {{ worktree_path## Interactive hooks-A hook running in the foreground inherits wt's stdin, so it can ask before continuing:+Hooks can prompt when run serially in the foreground, as in this `pre-start` hook:```toml# .config/wt.toml@@ -264,10 +264,6 @@ A hook running in the foreground inherits wt's stdin, so it can ask before contitrust = "gum confirm 'trust this worktree?' && mise trust"```-That covers `pre-*` hooks and any type under `wt hook <type> --foreground`, except where the hook is a concurrent group — a table with two or more keys, whose children would race for the terminal, so each reads EOF instead. A detached `post-*` hook reads EOF too, having no terminal at all. Nothing is ever piped in — a hook reads its context through template variables, whatever form it runs in.--Foreground steps run in order and share one stdin, so a step that drains it to EOF — a `cat` or a `read` loop — leaves nothing for the steps behind it when that stdin is a pipe or a file. Under a terminal each step can prompt in turn. Steps accumulate across config files, so a user `[pre-start]` and a project `[pre-start]` form one pipeline.-Logic that templates can't express belongs in a script, with the values it needs passed as arguments:```tomldiff --git a/plugins/worktrunk/skills/worktrunk/reference/list.md b/plugins/worktrunk/skills/worktrunk/reference/list.mdindex 93457d45a..6dc1c9193 100644--- a/plugins/worktrunk/skills/worktrunk/reference/list.md+++ b/plugins/worktrunk/skills/worktrunk/reference/list.md@@ -410,7 +410,7 @@ The single highest-priority state describing the branch's relation to the defaul### integration reasons-`default_branch.integration.reason` records which check matched. Checks run cheapest-first and the first match wins. The reason itself is JSON-only: the table shows `"same_commit"` as `_` (or `–` with uncommitted changes) and every other reason as `⊂` when the working tree is clean:+`default_branch.integration.reason` records which check matched. Checks run cheapest-first and the first match wins. See [Default branch](#default-branch) for symbols.| Value | Meaning ||-------|---------|diff --git a/plugins/worktrunk/skills/worktrunk/reference/merge.md b/plugins/worktrunk/skills/worktrunk/reference/merge.mdindex b3fa8a208..aecd9fa45 100644--- a/plugins/worktrunk/skills/worktrunk/reference/merge.md+++ b/plugins/worktrunk/skills/worktrunk/reference/merge.md@@ -64,7 +64,7 @@ $ wt merge --no-commit --no-rebase`wt merge` runs these steps:1. **Commit** — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in the background. This step is skipped when squashing (the default) — changes are staged during the squash step instead. With `--no-squash`, this is the only commit step.-2. **Squash** — Combines all commits since target into one (like GitHub's "Squash and merge"). Use `--stage` to control what gets staged: `all` (default), `tracked`, or `none`. Working-tree changes swept into the squash are backed up first to `refs/wt-backup/<branch>`; see [`wt step squash`](https://worktrunk.dev/step/#wt-step-squash) for recovery. With `--no-squash`, individual commits are preserved.+2. **Squash** — Combines all commits since target into one (like GitHub's "Squash and merge"). Pre-commit hooks run before staging; post-commit hooks run in the background after committing. Use `--stage` to control what gets staged: `all` (default), `tracked`, or `none`. Working-tree changes swept into the squash are backed up first to `refs/wt-backup/<branch>`; see [`wt step squash`](https://worktrunk.dev/step/#wt-step-squash) for recovery. With `--no-squash`, individual commits are preserved.3. **Rebase** — Rebases onto target, skipping when nothing needs replaying ([`wt step rebase`](https://worktrunk.dev/step/#wt-step-rebase) gives the conditions). A conflict stops the merge with the rebase left open in the worktree, to resolve or abort. With `--no-rebase`, the graph produced by earlier commit/squash steps is preserved and the target must be able to fast-forward to its tip.4. **Pre-merge hooks** — Hooks run after rebase, before merge. Failures abort. See [`wt hook`](https://worktrunk.dev/hook/).5. **Merge** — Fast-forward merge to the target branch ([`wt step push`](https://worktrunk.dev/step/#wt-step-push)). With `--no-ff`, a merge commit is created instead — semi-linear history after the default rebase, while explicit `--no-rebase` preserves the graph produced by earlier steps before adding the merge commit. Non-fast-forward merges are rejected.diff --git a/plugins/worktrunk/skills/worktrunk/reference/remove.md b/plugins/worktrunk/skills/worktrunk/reference/remove.mdindex 27389e235..c0ca3d985 100644--- a/plugins/worktrunk/skills/worktrunk/reference/remove.md+++ b/plugins/worktrunk/skills/worktrunk/reference/remove.md@@ -96,7 +96,7 @@ Unix only; on Windows `--reap` is rejected.## JSON output-`--format=json` prints one object per removal to stdout: `{kind, branch, path, branch_outcome, branch_checked_out_at}` for a worktree, with `pruned` in place of `path` for a branch-only removal, plus `detached_worktree` — a detached worktree left at the branch's configured path.+`--format=json` prints one object per removal to stdout: `{kind, branch, path, branch_outcome, branch_checked_out_at}` for a worktree, with `pruned` in place of `path` for a branch-only removal. Branch-only results also include `detached_worktree`: the path of a detached worktree left behind, or `null`.`branch_outcome` names what happened to the branch, so a caller can tell a deletion the removal declined from one it was never asked to make:diff --git a/plugins/worktrunk/skills/worktrunk/reference/step.md b/plugins/worktrunk/skills/worktrunk/reference/step.mdindex 4ea3b4cb0..06c31b296 100644--- a/plugins/worktrunk/skills/worktrunk/reference/step.md+++ b/plugins/worktrunk/skills/worktrunk/reference/step.md@@ -193,9 +193,9 @@ The squash commit is made on a detached HEAD, as `git rebase` does, so git's own### Recovering staged changes-Before absorbing staged changes, Worktrunk backs up the index to `refs/wt-backup/<branch>`. The backup commit's parent preserves the branch tip before squashing. Unstaged and untracked files outside the selected staging mode stay in the original worktree and are not captured by the backup.+Before squashing staged changes, Worktrunk saves them to `refs/wt-backup/<branch>`. Changes left unstaged are not included in the backup.-The output prints the backup ref and a command to open its saved commit on a recovery branch in a new worktree. That command uses the backup's immutable SHA and skips project hooks. It preserves current branches, files, and staging, and also works after `wt merge` removes the source worktree.+The output prints a command to recover the saved changes in a new worktree, including after `wt merge` removes the original.### Options@@ -813,7 +813,7 @@ In `wt list`, candidates show `_` (same commit) or `⊂` (content integrated). RLocked worktrees, worktrees with uncommitted changes, and the main worktree are always skipped. The current worktree is removed last, triggering cd to the primary worktree. Pre-remove and post-remove hooks run for each removal; a candidate whose hooks include an unapproved project command is skipped with `(approval required)` (pre-approve with `wt config approvals add`, or pass `--yes`).-Removals and their hooks may run concurrently across worktrees. Each worktree's pre-remove hooks finish before its removal begins. Hooks must coordinate writes to shared resources and avoid writing into other worktrees being pruned.+Prune removes worktrees concurrently, so hooks that write shared resources must coordinate those writes.### Min-age guarddiff --git a/plugins/worktrunk/skills/worktrunk/reference/tips-patterns.md b/plugins/worktrunk/skills/worktrunk/reference/tips-patterns.mdindex 6446e1daa..7075ca01a 100644--- a/plugins/worktrunk/skills/worktrunk/reference/tips-patterns.md+++ b/plugins/worktrunk/skills/worktrunk/reference/tips-patterns.md@@ -64,7 +64,7 @@ git fetch origingit remote set-head origin --auto```-`git clone --bare` records the `origin` URL but no fetch refspec, so without the `git config` line `git fetch` never creates remote-tracking branches like `origin/main`, and tools that read them (lazygit, editor integrations) see no remote branches. `git remote set-head` then points `origin/HEAD` at the remote's default branch.+The fetch refspec creates remote-tracking branches such as `origin/main`; `git remote set-head` records the remote's default branch.With `worktree-path = "{{ repo_path }}/../{{ branch | sanitize }}"`, worktrees become subdirectories of `myproject/`:@@ -110,7 +110,7 @@ Now `wt switch --create feature` creates `myproject/feature/`.The project config (`.config/wt.toml`) must live inside a worktree — the bare `.git` directory has no tracked files. Once the first worktree exists, create it from there:```bash-cd myproject/main+wt switch mainwt config create --project```diff --git a/skills/worktrunk/reference/config.md b/skills/worktrunk/reference/config.mdindex 6cf051803..facf030f7 100644--- a/skills/worktrunk/reference/config.md+++ b/skills/worktrunk/reference/config.md@@ -628,7 +628,6 @@ On first run without shell integration, Worktrunk offers to install it. On first## Environment variablesAll user config options can be overridden with environment variables using the `WORKTRUNK_` prefix.-Invalid environment overrides are ignored with a warning; other valid overrides still apply.### Naming convention@@ -1249,7 +1248,7 @@ $ wt list### Use cases- **Work status** — `🚧` WIP, `✅` ready for review, `🔥` urgent-- **Agent tracking** — The agent plugins ([Claude Code](https://worktrunk.dev/claude-code/), Codex, OpenCode, Pi, oh-my-pi) set markers automatically+- **Agent tracking** — [Agent plugins](https://worktrunk.dev/claude-code/) set markers automatically- **Notes** — Any short text: `"blocked"`, `"needs tests"`### Storagediff --git a/skills/worktrunk/reference/extending.md b/skills/worktrunk/reference/extending.mdindex 2e8756f4f..58a6cb5cc 100644--- a/skills/worktrunk/reference/extending.md+++ b/skills/worktrunk/reference/extending.md@@ -227,7 +227,7 @@ Aside from the differences below, hooks and aliases behave the same.| Source discrimination | `user:` / `project:` / `user:name` / `project:name` filter syntax | Run user first, then project; no filter syntax || `--help` | `wt hook --help` lists hook types; `wt hook <type> --help` shows flags and arguments for that type | The template body is the documentation: `wt <alias> --help` redirects to `wt config alias show` / `dry-run`. `wt --help` and `wt step --help` list configured aliases alongside built-in commands || Inspection | `wt hook show [type] [--expanded]` | `wt config alias show <name>` / `wt config alias dry-run <name>` |-| Stdin | A hook running in the foreground inherits parent stdin, same as aliases (interactive prompts work) — `pre-*` hooks, and any type under `wt hook <type> --foreground`; detached `post-*` hooks and concurrent children read EOF | Serial steps inherit parent stdin (pipes pass through; interactive TUIs like `wt switch` keep the tty); concurrent children read EOF |+| Stdin | See [Interactive hooks](https://worktrunk.dev/hook/#interactive-hooks) | Serial steps inherit parent stdin || Template-context extras | `hook_type`, `hook_name`, per-type operation vars (`base`, `target`, `pr_number`, …) | `args` on top of the shared base variables |</details>diff --git a/skills/worktrunk/reference/faq.md b/skills/worktrunk/reference/faq.mdindex 0d5228b8e..c4dd0ecbc 100644--- a/skills/worktrunk/reference/faq.md+++ b/skills/worktrunk/reference/faq.md@@ -135,6 +135,7 @@ Worktrunk stores repository state, caches, and logs under `.git/`:| Location | Purpose | Created by ||----------|---------|------------|| `git config worktrunk.*` | Cached default branch, switch history, branch markers, custom variables | Various commands |+| `refs/wt-backup/<branch>` | [Squash backups](https://worktrunk.dev/step/#wt-step-squash--recovering-staged-changes); preserved by state clearing | `wt step squash`, `wt merge` || `.git/wt/cache/{kind}/*.json` | Cached CI status, the largest PR/MR number seen (sizes the `wt list` CI column), and git command results (merge-tree, integration probes, diff stats, ancestry checks, ahead/behind counts, merge bases) | `wt list`, `wt merge`, `wt remove` || `.git/wt/cache/summary/{branch}/{hash}.json` | Cached LLM branch summaries, content-addressed by diff hash | `wt list --full`, `wt switch` (when `[list] summary = true`) || `.git/wt/cache/picker-preview/*.json` | Rendered preview panes for the interactive picker | `wt switch` |@@ -148,7 +149,7 @@ Worktrunk stores repository state, caches, and logs under `.git/`:None of this is tracked by git or pushed to remotes.-**To remove:** `wt config state clear` removes all repository data: config keys, caches, markers, hints, variables, logs, and stale trash. It prompts before removing anything worktrunk can't recompute, unless you pass `--yes`.+**To remove:** `wt config state clear` removes repository state: config keys, caches, markers, hints, variables, logs, and stale trash. It prompts before removing anything worktrunk can't recompute, unless you pass `--yes`.### 5. Agent integrations@@ -211,7 +212,7 @@ A branch checked out in a second worktree is retained regardless, `-D` included.- `wt merge` / `wt step push` — the target branch's checked-out worktree is updated to the merged commits, so a file those commits delete disappears from it, and an ignored file at a path they track is overwritten — the same result a `git merge` run in that worktree would produce. Uncommitted changes at paths the merge doesn't touch stay in place, staged or not; one at a path it does touch refuses the merge upfront, naming the file- `wt remove` / `wt step prune` — unregister a stale worktree (`⊟` in `wt list`) by deleting its `.git/worktrees/<id>` entry, as `git worktree prune` does, but for that worktree only. Files still in its directory stay. An entry whose index holds staged changes, or with a rebase, merge, or other operation in progress, is kept unless `wt remove --force` names it, since `git worktree repair` can restore it only while the entry exists- `wt remove` — also stops the removed worktree's `git fsmonitor--daemon` (under `core.fsmonitor=true`), and sweeps `.git/wt/trash/` entries older than 24 hours along with fsmonitor daemons whose worktree no longer exists-- `wt config state clear` — removes all worktrunk data from `.git/` (config keys, caches, markers, hints, variables, logs, stale trash)+- `wt config state clear` — clears config keys, caches, markers, hints, variables, logs, and stale trash- `wt config shell install` — replaces an existing fish or Nushell wrapper file whole, and removes one an older version installed at a previous location (fish `conf.d/wt.fish`, Nushell `<config-dir>/vendor/autoload/wt.nu`), printing each removal; [Files created](https://worktrunk.dev/shell-integration/#files-created) names the file each shell gets- `wt config shell uninstall` — removes the lines that run `wt config shell init` from bash/zsh/PowerShell rc files, and deletes wrapper and completion files carrying worktrunk's content markers (fish `functions/`, `conf.d/`, and `completions/`; nushell `vendor/autoload`). Every removed line is printed- `wt config plugins opencode uninstall` / `wt config plugins pi uninstall` / `wt config plugins omp uninstall` — deletes that agent's `worktrunk.ts` plugin file. Only worktrunk's own file is touched; the rest of the agent's plugin directory is left alonediff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.mdindex 5006b6541..b0e4af4b0 100644--- a/skills/worktrunk/reference/hook.md+++ b/skills/worktrunk/reference/hook.md@@ -73,7 +73,7 @@ A string is a single command:pre-start = "npm install"```-A table is multiple commands that run concurrently:+A table names commands. With multiple keys, they run concurrently:```toml# .config/wt.toml@@ -256,7 +256,7 @@ setup = "cp {{ worktree_path_of_branch('main') }}/config.local {{ worktree_path## Interactive hooks-A hook running in the foreground inherits wt's stdin, so it can ask before continuing:+Hooks can prompt when run serially in the foreground, as in this `pre-start` hook:```toml# .config/wt.toml@@ -264,10 +264,6 @@ A hook running in the foreground inherits wt's stdin, so it can ask before contitrust = "gum confirm 'trust this worktree?' && mise trust"```-That covers `pre-*` hooks and any type under `wt hook <type> --foreground`, except where the hook is a concurrent group — a table with two or more keys, whose children would race for the terminal, so each reads EOF instead. A detached `post-*` hook reads EOF too, having no terminal at all. Nothing is ever piped in — a hook reads its context through template variables, whatever form it runs in.--Foreground steps run in order and share one stdin, so a step that drains it to EOF — a `cat` or a `read` loop — leaves nothing for the steps behind it when that stdin is a pipe or a file. Under a terminal each step can prompt in turn. Steps accumulate across config files, so a user `[pre-start]` and a project `[pre-start]` form one pipeline.-Logic that templates can't express belongs in a script, with the values it needs passed as arguments:```tomldiff --git a/skills/worktrunk/reference/list.md b/skills/worktrunk/reference/list.mdindex 93457d45a..6dc1c9193 100644--- a/skills/worktrunk/reference/list.md+++ b/skills/worktrunk/reference/list.md@@ -410,7 +410,7 @@ The single highest-priority state describing the branch's relation to the defaul### integration reasons-`default_branch.integration.reason` records which check matched. Checks run cheapest-first and the first match wins. The reason itself is JSON-only: the table shows `"same_commit"` as `_` (or `–` with uncommitted changes) and every other reason as `⊂` when the working tree is clean:+`default_branch.integration.reason` records which check matched. Checks run cheapest-first and the first match wins. See [Default branch](#default-branch) for symbols.| Value | Meaning ||-------|---------|diff --git a/skills/worktrunk/reference/merge.md b/skills/worktrunk/reference/merge.mdindex b3fa8a208..aecd9fa45 100644--- a/skills/worktrunk/reference/merge.md+++ b/skills/worktrunk/reference/merge.md@@ -64,7 +64,7 @@ $ wt merge --no-commit --no-rebase`wt merge` runs these steps:1. **Commit** — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in the background. This step is skipped when squashing (the default) — changes are staged during the squash step instead. With `--no-squash`, this is the only commit step.-2. **Squash** — Combines all commits since target into one (like GitHub's "Squash and merge"). Use `--stage` to control what gets staged: `all` (default), `tracked`, or `none`. Working-tree changes swept into the squash are backed up first to `refs/wt-backup/<branch>`; see [`wt step squash`](https://worktrunk.dev/step/#wt-step-squash) for recovery. With `--no-squash`, individual commits are preserved.+2. **Squash** — Combines all commits since target into one (like GitHub's "Squash and merge"). Pre-commit hooks run before staging; post-commit hooks run in the background after committing. Use `--stage` to control what gets staged: `all` (default), `tracked`, or `none`. Working-tree changes swept into the squash are backed up first to `refs/wt-backup/<branch>`; see [`wt step squash`](https://worktrunk.dev/step/#wt-step-squash) for recovery. With `--no-squash`, individual commits are preserved.3. **Rebase** — Rebases onto target, skipping when nothing needs replaying ([`wt step rebase`](https://worktrunk.dev/step/#wt-step-rebase) gives the conditions). A conflict stops the merge with the rebase left open in the worktree, to resolve or abort. With `--no-rebase`, the graph produced by earlier commit/squash steps is preserved and the target must be able to fast-forward to its tip.4. **Pre-merge hooks** — Hooks run after rebase, before merge. Failures abort. See [`wt hook`](https://worktrunk.dev/hook/).5. **Merge** — Fast-forward merge to the target branch ([`wt step push`](https://worktrunk.dev/step/#wt-step-push)). With `--no-ff`, a merge commit is created instead — semi-linear history after the default rebase, while explicit `--no-rebase` preserves the graph produced by earlier steps before adding the merge commit. Non-fast-forward merges are rejected.diff --git a/skills/worktrunk/reference/remove.md b/skills/worktrunk/reference/remove.mdindex 27389e235..c0ca3d985 100644--- a/skills/worktrunk/reference/remove.md+++ b/skills/worktrunk/reference/remove.md@@ -96,7 +96,7 @@ Unix only; on Windows `--reap` is rejected.## JSON output-`--format=json` prints one object per removal to stdout: `{kind, branch, path, branch_outcome, branch_checked_out_at}` for a worktree, with `pruned` in place of `path` for a branch-only removal, plus `detached_worktree` — a detached worktree left at the branch's configured path.+`--format=json` prints one object per removal to stdout: `{kind, branch, path, branch_outcome, branch_checked_out_at}` for a worktree, with `pruned` in place of `path` for a branch-only removal. Branch-only results also include `detached_worktree`: the path of a detached worktree left behind, or `null`.`branch_outcome` names what happened to the branch, so a caller can tell a deletion the removal declined from one it was never asked to make:diff --git a/skills/worktrunk/reference/step.md b/skills/worktrunk/reference/step.mdindex 4ea3b4cb0..06c31b296 100644--- a/skills/worktrunk/reference/step.md+++ b/skills/worktrunk/reference/step.md@@ -193,9 +193,9 @@ The squash commit is made on a detached HEAD, as `git rebase` does, so git's own### Recovering staged changes-Before absorbing staged changes, Worktrunk backs up the index to `refs/wt-backup/<branch>`. The backup commit's parent preserves the branch tip before squashing. Unstaged and untracked files outside the selected staging mode stay in the original worktree and are not captured by the backup.+Before squashing staged changes, Worktrunk saves them to `refs/wt-backup/<branch>`. Changes left unstaged are not included in the backup.-The output prints the backup ref and a command to open its saved commit on a recovery branch in a new worktree. That command uses the backup's immutable SHA and skips project hooks. It preserves current branches, files, and staging, and also works after `wt merge` removes the source worktree.+The output prints a command to recover the saved changes in a new worktree, including after `wt merge` removes the original.### Options@@ -813,7 +813,7 @@ In `wt list`, candidates show `_` (same commit) or `⊂` (content integrated). RLocked worktrees, worktrees with uncommitted changes, and the main worktree are always skipped. The current worktree is removed last, triggering cd to the primary worktree. Pre-remove and post-remove hooks run for each removal; a candidate whose hooks include an unapproved project command is skipped with `(approval required)` (pre-approve with `wt config approvals add`, or pass `--yes`).-Removals and their hooks may run concurrently across worktrees. Each worktree's pre-remove hooks finish before its removal begins. Hooks must coordinate writes to shared resources and avoid writing into other worktrees being pruned.+Prune removes worktrees concurrently, so hooks that write shared resources must coordinate those writes.### Min-age guarddiff --git a/skills/worktrunk/reference/tips-patterns.md b/skills/worktrunk/reference/tips-patterns.mdindex 6446e1daa..7075ca01a 100644--- a/skills/worktrunk/reference/tips-patterns.md+++ b/skills/worktrunk/reference/tips-patterns.md@@ -64,7 +64,7 @@ git fetch origingit remote set-head origin --auto```-`git clone --bare` records the `origin` URL but no fetch refspec, so without the `git config` line `git fetch` never creates remote-tracking branches like `origin/main`, and tools that read them (lazygit, editor integrations) see no remote branches. `git remote set-head` then points `origin/HEAD` at the remote's default branch.+The fetch refspec creates remote-tracking branches such as `origin/main`; `git remote set-head` records the remote's default branch.With `worktree-path = "{{ repo_path }}/../{{ branch | sanitize }}"`, worktrees become subdirectories of `myproject/`:@@ -110,7 +110,7 @@ Now `wt switch --create feature` creates `myproject/feature/`.The project config (`.config/wt.toml`) must live inside a worktree — the bare `.git` directory has no tracked files. Once the first worktree exists, create it from there:```bash-cd myproject/main+wt switch mainwt config create --project```diff --git a/src/cli/config.rs b/src/cli/config.rsindex b49e434a0..05c7f8c4b 100644--- a/src/cli/config.rs+++ b/src/cli/config.rs@@ -1198,7 +1198,7 @@ wt list## Use cases- **Work status** — `🚧` WIP, `✅` ready for review, `🔥` urgent-- **Agent tracking** — The agent plugins ([Claude Code](/claude-code/), Codex, OpenCode, Pi, oh-my-pi) set markers automatically+- **Agent tracking** — [Agent plugins](/claude-code/) set markers automatically- **Notes** — Any short text: `"blocked"`, `"needs tests"`## Storagediff --git a/src/cli/mod.rs b/src/cli/mod.rsindex 763e54a6e..298851d2b 100644--- a/src/cli/mod.rs+++ b/src/cli/mod.rs@@ -1210,7 +1210,7 @@ The single highest-priority state describing the branch's relation to the defaul### integration reasons-`default_branch.integration.reason` records which check matched. Checks run cheapest-first and the first match wins. The reason itself is JSON-only: the table shows `"same_commit"` as `_` (or `–` with uncommitted changes) and every other reason as `⊂` when the working tree is clean:+`default_branch.integration.reason` records which check matched. Checks run cheapest-first and the first match wins. See [Default branch](#default-branch) for symbols.| Value | Meaning ||-------|---------|@@ -1400,7 +1400,7 @@ Unix only; on Windows `--reap` is rejected.## JSON output-`--format=json` prints one object per removal to stdout: `{kind, branch, path, branch_outcome, branch_checked_out_at}` for a worktree, with `pruned` in place of `path` for a branch-only removal, plus `detached_worktree` — a detached worktree left at the branch's configured path.+`--format=json` prints one object per removal to stdout: `{kind, branch, path, branch_outcome, branch_checked_out_at}` for a worktree, with `pruned` in place of `path` for a branch-only removal. Branch-only results also include `detached_worktree`: the path of a detached worktree left behind, or `null`.`branch_outcome` names what happened to the branch, so a caller can tell a deletion the removal declined from one it was never asked to make:@@ -1497,7 +1497,7 @@ $ wt merge --no-commit --no-rebase`wt merge` runs these steps:1. **Commit** — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in the background. This step is skipped when squashing (the default) — changes are staged during the squash step instead. With `--no-squash`, this is the only commit step.-2. **Squash** — Combines all commits since target into one (like GitHub's "Squash and merge"). Use `--stage` to control what gets staged: `all` (default), `tracked`, or `none`. Working-tree changes swept into the squash are backed up first to `refs/wt-backup/<branch>`; see [`wt step squash`](/step/#wt-step-squash) for recovery. With `--no-squash`, individual commits are preserved.+2. **Squash** — Combines all commits since target into one (like GitHub's "Squash and merge"). Pre-commit hooks run before staging; post-commit hooks run in the background after committing. Use `--stage` to control what gets staged: `all` (default), `tracked`, or `none`. Working-tree changes swept into the squash are backed up first to `refs/wt-backup/<branch>`; see [`wt step squash`](/step/#wt-step-squash) for recovery. With `--no-squash`, individual commits are preserved.3. **Rebase** — Rebases onto target, skipping when nothing needs replaying ([`wt step rebase`](/step/#wt-step-rebase) gives the conditions). A conflict stops the merge with the rebase left open in the worktree, to resolve or abort. With `--no-rebase`, the graph produced by earlier commit/squash steps is preserved and the target must be able to fast-forward to its tip.4. **Pre-merge hooks** — Hooks run after rebase, before merge. Failures abort. See [`wt hook`](/hook/).5. **Merge** — Fast-forward merge to the target branch ([`wt step push`](/step/#wt-step-push)). With `--no-ff`, a merge commit is created instead — semi-linear history after the default rebase, while explicit `--no-rebase` preserves the graph produced by earlier steps before adding the merge commit. Non-fast-forward merges are rejected.@@ -1686,7 +1686,7 @@ A string is a single command:pre-start = "npm install"```-A table is multiple commands that run concurrently:+A table names commands. With multiple keys, they run concurrently:```toml# .config/wt.toml@@ -1869,7 +1869,7 @@ setup = "cp {{ worktree_path_of_branch('main') }}/config.local {{ worktree_path## Interactive hooks-A hook running in the foreground inherits wt's stdin, so it can ask before continuing:+Hooks can prompt when run serially in the foreground, as in this `pre-start` hook:```toml# .config/wt.toml@@ -1877,10 +1877,6 @@ A hook running in the foreground inherits wt's stdin, so it can ask before contitrust = "gum confirm 'trust this worktree?' && mise trust"```-That covers `pre-*` hooks and any type under `wt hook <type> --foreground`, except where the hook is a concurrent group — a table with two or more keys, whose children would race for the terminal, so each reads EOF instead. A detached `post-*` hook reads EOF too, having no terminal at all. Nothing is ever piped in — a hook reads its context through template variables, whatever form it runs in.--Foreground steps run in order and share one stdin, so a step that drains it to EOF — a `cat` or a `read` loop — leaves nothing for the steps behind it when that stdin is a pipe or a file. Under a terminal each step can prompt in turn. Steps accumulate across config files, so a user `[pre-start]` and a project `[pre-start]` form one pipeline.-Logic that templates can't express belongs in a script, with the values it needs passed as arguments:```toml@@ -2607,7 +2603,6 @@ On first run without shell integration, Worktrunk offers to install it. On first## Environment variablesAll user config options can be overridden with environment variables using the `WORKTRUNK_` prefix.-Invalid environment overrides are ignored with a warning; other valid overrides still apply.### Naming conventiondiff --git a/src/cli/step.rs b/src/cli/step.rsindex 0fbe2a90b..ecf82ee9a 100644--- a/src/cli/step.rs+++ b/src/cli/step.rs@@ -136,9 +136,9 @@ The squash commit is made on a detached HEAD, as `git rebase` does, so git's own## Recovering staged changes-Before absorbing staged changes, Worktrunk backs up the index to `refs/wt-backup/<branch>`. The backup commit's parent preserves the branch tip before squashing. Unstaged and untracked files outside the selected staging mode stay in the original worktree and are not captured by the backup.+Before squashing staged changes, Worktrunk saves them to `refs/wt-backup/<branch>`. Changes left unstaged are not included in the backup.-The output prints the backup ref and a command to open its saved commit on a recovery branch in a new worktree. That command uses the backup's immutable SHA and skips project hooks. It preserves current branches, files, and staging, and also works after `wt merge` removes the source worktree.+The output prints a command to recover the saved changes in a new worktree, including after `wt merge` removes the original.## Options@@ -627,7 +627,7 @@ In `wt list`, candidates show `_` (same commit) or `⊂` (content integrated). RLocked worktrees, worktrees with uncommitted changes, and the main worktree are always skipped. The current worktree is removed last, triggering cd to the primary worktree. Pre-remove and post-remove hooks run for each removal; a candidate whose hooks include an unapproved project command is skipped with `(approval required)` (pre-approve with `wt config approvals add`, or pass `--yes`).-Removals and their hooks may run concurrently across worktrees. Each worktree's pre-remove hooks finish before its removal begins. Hooks must coordinate writes to shared resources and avoid writing into other worktrees being pruned.+Prune removes worktrees concurrently, so hooks that write shared resources must coordinate those writes.## Min-age guarddiff --git a/tests/snapshots/integration__integration_tests__help__help_config_long.snap b/tests/snapshots/integration__integration_tests__help__help_config_long.snapindex 763049d0d..f742aba4b 100644--- a/tests/snapshots/integration__integration_tests__help__help_config_long.snap+++ b/tests/snapshots/integration__integration_tests__help__help_config_long.snap@@ -615,7 +615,6 @@ On first run without shell integration, Worktrunk offers to install it. On first[1m[32mEnvironment variables[0mAll user config options can be overridden with environment variables using the [2mWORKTRUNK_[0m prefix.-Invalid environment overrides are ignored with a warning; other valid overrides still apply.[32mNaming convention[0mdiff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_marker.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_marker.snapindex 4c9943e66..3d50a588e 100644--- a/tests/snapshots/integration__integration_tests__help__help_config_state_marker.snap+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_marker.snap@@ -88,7 +88,7 @@ Markers appear at the end of the Status column, after git symbols:[1m[32mUse cases[0m- [1mWork status[0m — [2m🚧[0m WIP, [2m✅[0m ready for review, [2m🔥[0m urgent-- [1mAgent tracking[0m — The agent plugins (Claude Code, Codex, OpenCode, Pi, oh-my-pi) set markers automatically+- [1mAgent tracking[0m — Agent plugins set markers automatically- [1mNotes[0m — Any short text: [2m"blocked"[0m, [2m"needs tests"[0m[1m[32mStorage[0mdiff --git a/tests/snapshots/integration__integration_tests__help__help_list_long.snap b/tests/snapshots/integration__integration_tests__help__help_list_long.snapindex c9c1840ec..49237640d 100644--- a/tests/snapshots/integration__integration_tests__help__help_list_long.snap+++ b/tests/snapshots/integration__integration_tests__help__help_list_long.snap@@ -486,7 +486,7 @@ The single highest-priority state describing the branch's relation to the defaul[32mintegration reasons[0m-[2mdefault_branch.integration.reason[0m records which check matched. Checks run cheapest-first and the first match wins. The reason itself is JSON-only: the table shows [2m"same_commit"[0m as [2m_[0m (or [2m–[0m with uncommitted changes) and every other reason as [2m⊂[0m when the working tree is clean:+[2mdefault_branch.integration.reason[0m records which check matched. Checks run cheapest-first and the first match wins. See Default branch for symbols.Value Meaning──────────────────── ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────diff --git a/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap b/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snapindex db8e55156..e5ba6551f 100644--- a/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap+++ b/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap@@ -596,9 +596,7 @@ full meaning of each value ([2m"is_main"[0m, [2m"orphan"[0m, [2m"empty"[0m[32mintegration reasons[0m[2mdefault_branch.integration.reason[0m records which check matched. Checks run-cheapest-first and the first match wins. The reason itself is JSON-only: the-table shows [2m"same_commit"[0m as [2m_[0m (or [2m–[0m with uncommitted changes) and every other-reason as [2m⊂[0m when the working tree is clean:+cheapest-first and the first match wins. See Default branch for symbols.Value Meaning────────────── ───────────────────────────────────────────────────────────────diff --git a/tests/snapshots/integration__integration_tests__help__help_md_merge.snap b/tests/snapshots/integration__integration_tests__help__help_md_merge.snapindex 028a300e2..c6f5af4be 100644--- a/tests/snapshots/integration__integration_tests__help__help_md_merge.snap+++ b/tests/snapshots/integration__integration_tests__help__help_md_merge.snap@@ -173,7 +173,7 @@ $ wt merge --no-commit --no-rebase`wt merge` runs these steps:1. **Commit** — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in the background. This step is skipped when squashing (the default) — changes are staged during the squash step instead. With `--no-squash`, this is the only commit step.-2. **Squash** — Combines all commits since target into one (like GitHub's "Squash and merge"). Use `--stage` to control what gets staged: `all` (default), `tracked`, or `none`. Working-tree changes swept into the squash are backed up first to `refs/wt-backup/<branch>`; see [`wt step squash`](/step/#wt-step-squash) for recovery. With `--no-squash`, individual commits are preserved.+2. **Squash** — Combines all commits since target into one (like GitHub's "Squash and merge"). Pre-commit hooks run before staging; post-commit hooks run in the background after committing. Use `--stage` to control what gets staged: `all` (default), `tracked`, or `none`. Working-tree changes swept into the squash are backed up first to `refs/wt-backup/<branch>`; see [`wt step squash`](/step/#wt-step-squash) for recovery. With `--no-squash`, individual commits are preserved.3. **Rebase** — Rebases onto target, skipping when nothing needs replaying ([`wt step rebase`](/step/#wt-step-rebase) gives the conditions). A conflict stops the merge with the rebase left open in the worktree, to resolve or abort. With `--no-rebase`, the graph produced by earlier commit/squash steps is preserved and the target must be able to fast-forward to its tip.4. **Pre-merge hooks** — Hooks run after rebase, before merge. Failures abort. See [`wt hook`](/hook/).5. **Merge** — Fast-forward merge to the target branch ([`wt step push`](/step/#wt-step-push)). With `--no-ff`, a merge commit is created instead — semi-linear history after the default rebase, while explicit `--no-rebase` preserves the graph produced by earlier steps before adding the merge commit. Non-fast-forward merges are rejected.diff --git a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap b/tests/snapshots/integration__integration_tests__help__help_merge_long.snapindex 14876477c..e18602ef4 100644--- a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap+++ b/tests/snapshots/integration__integration_tests__help__help_merge_long.snap@@ -157,7 +157,7 @@ Preserve the exact clean commit graph and tip:[2mwt merge[0m runs these steps:1. [1mCommit[0m — Pre-commit hooks run, then uncommitted changes are committed. Post-commit hooks run in the background. This step is skipped when squashing (the default) — changes are staged during the squash step instead. With [2m--no-squash[0m, this is the only commit step.-2. [1mSquash[0m — Combines all commits since target into one (like GitHub's "Squash and merge"). Use [2m--stage[0m to control what gets staged: [2mall[0m (default), [2mtracked[0m, or [2mnone[0m. Working-tree changes swept into the squash are backed up first to [2mrefs/wt-backup/<branch>[0m; see [2mwt step squash[0m for recovery. With [2m--no-squash[0m, individual commits are preserved.+2. [1mSquash[0m — Combines all commits since target into one (like GitHub's "Squash and merge"). Pre-commit hooks run before staging; post-commit hooks run in the background after committing. Use [2m--stage[0m to control what gets staged: [2mall[0m (default), [2mtracked[0m, or [2mnone[0m. Working-tree changes swept into the squash are backed up first to [2mrefs/wt-backup/<branch>[0m; see [2mwt step squash[0m for recovery. With [2m--no-squash[0m, individual commits are preserved.3. [1mRebase[0m — Rebases onto target, skipping when nothing needs replaying ([2mwt step rebase[0m gives the conditions). A conflict stops the merge with the rebase left open in the worktree, to resolve or abort. With [2m--no-rebase[0m, the graph produced by earlier commit/squash steps is preserved and the target must be able to fast-forward to its tip.4. [1mPre-merge hooks[0m — Hooks run after rebase, before merge. Failures abort. See [2mwt hook[0m.5. [1mMerge[0m — Fast-forward merge to the target branch ([2mwt step push[0m). With [2m--no-ff[0m, a merge commit is created instead — semi-linear history after the default rebase, while explicit [2m--no-rebase[0m preserves the graph produced by earlier steps before adding the merge commit. Non-fast-forward merges are rejected.diff --git a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap b/tests/snapshots/integration__integration_tests__help__help_remove_long.snapindex e82a17e06..e87df4618 100644--- a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap+++ b/tests/snapshots/integration__integration_tests__help__help_remove_long.snap@@ -185,7 +185,7 @@ Unix only; on Windows [2m--reap[0m is rejected.[1m[32mJSON output[0m-[2m--format=json[0m prints one object per removal to stdout: [2m{kind, branch, path, branch_outcome, branch_checked_out_at}[0m for a worktree, with [2mpruned[0m in place of [2mpath[0m for a branch-only removal, plus [2mdetached_worktree[0m — a detached worktree left at the branch's configured path.+[2m--format=json[0m prints one object per removal to stdout: [2m{kind, branch, path, branch_outcome, branch_checked_out_at}[0m for a worktree, with [2mpruned[0m in place of [2mpath[0m for a branch-only removal. Branch-only results also include [2mdetached_worktree[0m: the path of a detached worktree left behind, or [2mnull[0m.[2mbranch_outcome[0m names what happened to the branch, so a caller can tell a deletion the removal declined from one it was never asked to make: