Documentation refresh: audit and update docs to cover the past two weeks of work

[dhilgaertner]

Goal

A lot has shipped over the past two weeks (24 merged PRs since 2026-04-17) but our docs have largely not kept up. Most files under docs/ were last touched around 2026-04-10 to 2026-04-15. This issue is for planning the documentation refresh — auditing what's drifted, deciding the structure, and assigning sections — before opening focused doc PRs.

Doc staleness snapshot

File	Last touched	Status
README.md	2026-04-22 (#189)	Partial — covers manager auto mode but nothing later
docs/configuration.md	2026-04-30 (#228)	Mostly current for automation toggles
docs/troubleshooting.md	2026-04-24 (#208)	Has a stop-hook fix; nothing newer
docs/architecture.md	2026-04-10 (#155)	Predates ~20 PRs
docs/cli-reference.md	2026-04-15 (#176)	Missing several CLI surfaces
docs/getting-started.md	2026-04-10 (#155)	Predates ~20 PRs
CHANGELOG.md	2026-04-05 (#87)	Stale — needs all recent entries
CLAUDE.md	2026-04-15 (#176)	Predates many automation hooks/flows

Themes that shipped and need coverage

1. Automation & auto-modes (largest gap)

• Add session analytics via Claude Code OpenTelemetry #137 Session analytics via Claude Code OpenTelemetry
• Require positive evidence before auto-completing sessions (#181) #182 Require positive evidence before auto-completing sessions
• Launch Manager terminal in auto permission mode by default #189 Manager terminal launches in auto permission mode by default
• Auto-start review sessions for opted-in repos #209 Auto-start review sessions for opted-in repos
• Auto-create workspace when assigned an issue with crow:auto label #211 Auto-create workspace when assigned an issue with crow:auto label
• Auto-suggest opening a PR upon session completion #213 Auto-suggest opening a PR on session completion
• Auto-respond to PR status changes (#201) #214 Auto-respond to PR status changes
• Auto-label PRs with crow:auto on open #222 Auto-label PRs with crow:auto on open
• Split automation toggles into dedicated Settings tab #228 Dedicated Settings → Automation tab (ground truth for toggles)

→ Needs: a single "Automation" doc (or major section) explaining the full lifecycle: assignment → workspace → session → review → PR open → status response → completion. Cross-link from configuration.md and getting-started.md.

2. Review board & session management

• Add 'Move to Active' button on completed sessions #188 "Move to Active" button on completed sessions
• Reconcile PR links for sessions missing reactive detection #205 PR link reconciliation for sessions missing reactive detection
• Filter projects from review board via exclude list #207 Filter projects from review board via exclude list
• Ignore subagent hook events fired after a turn's Stop (#199) #208 Ignore subagent hook events fired after a turn's Stop
• Add bulk delete for sessions in the sidebar #210 Bulk delete sessions in sidebar
• Add multi-select and batch Start Review to Review Board #212 Multi-select + batch Start Review on Review Board
• Add filtering for tickets list #220 Filtering for tickets list
• Per-section select all and icon-only cancel button #226 Per-section select all, icon-only cancel
• Add quick action buttons to session detail header #231 Quick action buttons on session detail header

→ Needs: a Review Board doc / section, plus updates to getting-started screenshots and session-management coverage.

3. Terminal runtime & rename

• Add ability to name terminals in the Terminals section #203 / Add ability to rename terminals #206 Rename terminals (UI + CLI)
• Recover from failed Ghostty surface creation (#217) #218 Recover from failed Ghostty surface creation
• Add tmux backend behind CROW_TMUX_BACKEND feature flag (#198) #229 tmux backend behind CROW_TMUX_BACKEND feature flag

→ Needs: cli-reference.md updates for crow rename-terminal (or whatever the verb landed as), troubleshooting entry for Ghostty recovery, and a new section in architecture.md explaining the dual Ghostty/tmux backend and the env flag.

4. GitLab path

• Fix GitLab fetch failing on GITLAB_HOST mismatch #215 Fix GitLab fetch failing on GITLAB_HOST mismatch
• Fix glab fetch failures from non-repo cwd and nested-group slug truncation #233 Fix glab fetch from non-repo cwd and nested-group slug truncation

→ Needs: configuration.md note on multi-host GitLab setup; troubleshooting.md note on nested-group repos.

5. Branding / minor

• Replace CorveilBrandmark PNG with SVG for crisper rendering #185 Replaced PNG brandmark with SVG (screenshot in docs may need re-export)

Proposed deliverables

1. Audit pass — a single PR or commit walking each doc file and flagging concrete drift against this list. (Output: a checklist comment on this issue.)
2. Automation doc — new docs/automation.md covering the full auto-flow lifecycle and every toggle in Settings → Automation, cross-referenced from README.md and configuration.md.
3. CLI reference refresh — sweep docs/cli-reference.md against the actual CLI surface (terminal rename, any new flags from the past two weeks).
4. Architecture refresh — add the Ghostty/tmux backend split (Add tmux backend behind CROW_TMUX_BACKEND feature flag (#198) #229) and the CROW_TMUX_BACKEND flag.
5. Troubleshooting refresh — Ghostty surface recovery (Recover from failed Ghostty surface creation (#217) #218), GitLab nested-group slugs (Fix glab fetch failures from non-repo cwd and nested-group slug truncation #233), GITLAB_HOST mismatch (Fix GitLab fetch failing on GITLAB_HOST mismatch #215).
6. CHANGELOG backfill — entries for everything from Add session analytics via Claude Code OpenTelemetry #137 forward. Decide whether to group by week or by version.
7. README skim — update screenshots if needed (Replace CorveilBrandmark PNG with SVG for crisper rendering #185, Per-section select all and icon-only cancel button #226, Add quick action buttons to session detail header #231 changed visible UI), confirm feature-list accuracy.

Acceptance criteria

• Each merged PR from Add session analytics via Claude Code OpenTelemetry #137 onward is either reflected in a doc or explicitly marked "no doc impact" in the audit checklist.
• docs/automation.md exists and is linked from README.md.
• docs/cli-reference.md matches actual crow CLI output as of HEAD.
• CHANGELOG.md is current through the latest release/tag.
• README screenshot reflects current UI.

Out of scope

• Writing the docs themselves — that happens in follow-up PRs.
• Restructuring the docs site / adding tooling (mkdocs, etc.) — separate concern.

Notes

The dev acceptance and feature-flag-cleanup docs for the tmux backend (#229) probably want to live in the automation doc once the flag flips on by default. For now, document the flag and the opt-in path.

[dhilgaertner]

Documentation refresh audit — completed in #PR

This is the audit deliverable called out in this issue. The corresponding PR ships every doc change inline rather than splitting the writing into follow-ups, since the drift was small enough to handle in one pass.

Per-file status

File	Last touched (before)	Status (after PR)
README.md	2026-04-10 (#155)	Updated — features list now covers automation suite, review board, terminal renaming, tmux backend; docs index links automation.md; Manager-terminal opt-out points at the Automation tab
CHANGELOG.md	2025-04-05 (#87)	Backfilled [Unreleased] with every PR from #137 → #234 grouped by theme
CLAUDE.md	(auto-scaffolded)	Not touched — managed by Scaffolder, not by hand
docs/automation.md	did not exist	New — canonical doc covering the full auto-flow lifecycle plus a per-toggle walkthrough of Settings → Automation
docs/cli-reference.md	2026-04-15 (#176)	Added crow rename-terminal (#206)
docs/architecture.md	2026-04-10 (#155)	Added TmuxBackend / TerminalRouter / AutoRespondCoordinator rows; new "Terminal Backends", "Settings", and "Review Board" sections
docs/configuration.md	2026-04-30 (#228)	Added CROW_TMUX_BACKEND and CROW_HOOK_DEBUG to env-var table; cross-linked automation.md
docs/getting-started.md	2026-04-10 (#155)	Added automation.md to Next Steps
docs/troubleshooting.md	2026-04-24 (#208)	Added rows for tmux backend missing, Ghostty surface retry (#218), GitLab nested groups (#233), GITLAB_HOST silent skip (#215), auto-respond not firing, and the silent-no-op hook-event behavior (#234); added [TerminalRouter] to debug tags
docs/terminal-runtime-research.md	2026-04-06	Appended "Implementation Status (2026-05)" footer noting #229 shipped the headless-PTY-via-tmux backend
docs/crow-screenshot.jpeg	older than #226/#231	Not re-exported in this PR — needs a fresh UI capture; flagged as a follow-up

Per-PR coverage (#137 → #234)

PR	Theme	Where it's documented
#137 OpenTelemetry analytics	Automation	automation.md — Per-PR feature notes
#152 Dock icon → Brandmark	Branding	CHANGELOG only (visual change, no doc impact)
#153 Fix PR review status	Bug	CHANGELOG only
#155 Earlier docs refresh	Tooling	CHANGELOG only
#159 Diagonal window resize	Bug	CHANGELOG only
#161 Batch Work-on malformed line	Bug	CHANGELOG only
#162 Silence noisy logs	Tooling	CHANGELOG only
#163 / #165 remoteControlEnabled	Automation	automation.md § Settings → Automation › Remote Control
#172 Log gh stderr	Tooling	CHANGELOG only
#174 Clickable ticket chips	UI	CHANGELOG only
#175 Consolidated GraphQL query	Performance	CHANGELOG only
#176 Open-source readiness	Tooling	CHANGELOG only
#178 CI Ghostty cache	Tooling	CHANGELOG only
#180 Duplicate-key crash	Bug	CHANGELOG only
#182 Positive-evidence completion	Automation	automation.md; README.md Auto-Complete
#185 SVG brandmark	Branding	CHANGELOG only
#188 Move to Active	Review board	architecture.md § Review Board
#189 Manager auto-permission	Automation	automation.md; configuration.md § Manager Terminal; README.md
#205 PR link reconciliation	Review board	architecture.md § Review Board
#206 Rename terminals	Terminal	cli-reference.md § rename-terminal; README.md § Terminals
#207 Filter review board	Review board	configuration.md § excludeReviewRepos; automation.md § Reviews
#208 Ignore post-Stop subagent hooks	Bug	troubleshooting.md (existing entry)
#209 Auto-start review	Automation	automation.md; architecture.md § Review Board
#210 Bulk delete	Review board	architecture.md § Review Board
#211 Auto-create on crow:auto	Automation	automation.md § Per-PR feature notes
#212 Multi-select batch review	Review board	architecture.md § Review Board
#213 Auto-suggest opening PR	Automation	automation.md; README.md § Automation Suite
#214 Auto-respond	Automation	automation.md § Auto-respond; troubleshooting.md
#215 GITLAB_HOST mismatch	GitLab	troubleshooting.md (existing entry, expanded)
#218 Ghostty surface recovery	Terminal	troubleshooting.md; CHANGELOG
#220 Tickets list filter	Review board	architecture.md § Review Board
#222 Auto-label PRs	Automation	automation.md § Per-PR feature notes
#226 Per-section select all	Review board	architecture.md § Review Board
#228 Settings → Automation tab	Automation	automation.md (entire doc); architecture.md § Settings
#229 tmux backend	Terminal	architecture.md § Terminal Backends; configuration.md § env vars; troubleshooting.md; terminal-runtime-research.md § Implementation Status; README.md § Terminals
#231 Quick action buttons	Review board	architecture.md § Review Board
#233 glab nested-group slugs	GitLab	troubleshooting.md
#234 hook-event silent no-op	Tooling	troubleshooting.md; CHANGELOG

Acceptance criteria

• Each merged PR from Add session analytics via Claude Code OpenTelemetry #137 onward is reflected in a doc or marked "no doc impact" in CHANGELOG
• docs/automation.md exists and is linked from README.md
• docs/cli-reference.md matches actual crow CLI output as of HEAD (sweep against Packages/CrowCLI/Sources/CrowCLILib/CrowCommand.swift showed only rename-terminal was missing)
• CHANGELOG.md [Unreleased] is current through Silently skip hook-event when Crow app is not running #234
• README screenshot reflects current UI — deferred, needs a fresh capture against Per-section select all and icon-only cancel button #226/Add quick action buttons to session detail header #231 layouts

Follow-ups out of scope

1. Re-export docs/crow-screenshot.jpeg against the current Settings/Review-Board UI — needs a clean app build and a UI capture session.
2. Tag a 0.2.0 release once the screenshot lands and the tmux backend opt-in is judged stable enough to ramp.