Skip to content

Correct the Worktrees docs and document shortcut pins - #943

Merged
selfcontained merged 1 commit into
mainfrom
docs/worktrees-audit-2026-08-11
Aug 12, 2026
Merged

Correct the Worktrees docs and document shortcut pins#943
selfcontained merged 1 commit into
mainfrom
docs/worktrees-audit-2026-08-11

Conversation

@selfcontained

Copy link
Copy Markdown
Owner

Nightly docs audit. Slice: the in-app Worktrees section (carried next_focus), plus the user-facing gaps in the diff since 9319fcaa.

Worktrees deep-dive

Audited docs-sections/worktrees.tsx against agents/workspace-prep.ts, shared/git/worktree.ts, agents/tmux/setup-script.ts, agents/archive.ts, and the create-dialog controls.

  • Wrong claim fixed. "When creation fails" said the card shows an Attention badge. That badge renders only for status === "error" (agent-card-header.tsx); a worktree failure goes through markSetupFailed, which sets stopped, and the reconciler never revisits it because its query only selects running/stopping/creating/archiving. The real signal is the status line flipping to Blocked with the git error — now what the docs say.
  • Fork point. Both launch paths fetch the starting branch from origin and fork the new branch from origin/<starting branch>; checking out the starting branch directly uses the local copy, and repos without an origin fall back to local. None of that was documented.
  • Branch deletion on cleanup. Removing a worktree also deletes the branch Dispatch created for it, and answering Archive and remove worktree force-deletes it (git branch -D) along with unpushed commits. The section only described the directory.
  • Terminal agents skip the dependency install in the setup script.

Verified-accurate and left alone: checkbox default/disabled state, .env copy, lockfile list and priority, sibling vs .dispatch/worktrees/ location, auto-generated branch name, per-cwd new-branch preference, partial-worktree cleanup on failure, and the archive keep/remove prompt.

Diff-driven

Deferred

Backlog gets the hold-badge-after-reload item (unchanged) and a note that the Archive and remove worktree button copy doesn't mention branch deletion — a product call, not a docs fix. Next run: the Repo Tools section against .dispatch/tools.json handling and lifecycle hooks.

Worktrees deep-dive against workspace-prep.ts, shared/git/worktree.ts,
tmux/setup-script.ts, and archive.ts:
- "When creation fails" claimed the card shows an Attention badge. That
badge renders only for status `error`; a worktree failure goes through
markSetupFailed, which sets `stopped` — and the reconciler never
revisits it, since its query only selects running/stopping/creating/
archiving. What users actually see is the status line flipping to
Blocked with the git error, so say that.
- Both launch paths fetch the starting branch from origin and fork the
new branch from `origin/<branch>`; checking out the starting branch
directly uses the local copy. Neither was documented.
- Removing a worktree also deletes the branch Dispatch created for it,
and "Archive and remove worktree" force-deletes it (`branch -D`)
including unpushed commits. The section only described the directory.
- The tmux setup script skips the dependency install for terminal-type
agents.
Also from the diff since the last audit: the shortcut-pin `disabled`
state (#937) in the Pins paragraph, the two terminal injection routes
inject-text (#935) and inject-pin (#930) in the api-spec Terminal table,
and a new ambient tip for shortcut pins deep-linked to a new
media#media-sidebar anchor.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@selfcontained
selfcontained merged commit 2f0e2c3 into mainAug 12, 2026
1 check passed
@selfcontained
selfcontained deleted the docs/worktrees-audit-2026-08-11 branch August 12, 2026 04:12
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

@selfcontained