Skip to content

README accuracy pass and TUI screenshot refresh for v0.2.0 - #174

Merged
MJohnson459 merged 1 commit into
mainfrom
readme-accuracy-v0.2.0
Aug 14, 2026
Merged

MJohnson459 merged 1 commit into
mainfrom
readme-accuracy-v0.2.0

Conversation

@MJohnson459

Copy link
Copy Markdown
Contributor

README accuracy pass and TUI screenshot refresh for v0.2.0. Branch
readme-accuracy-v0.2.0, one commit (8aeaa61), touching only README.md and
docs/images/voro-tui.png. cargo test --workspace passes: 876 tests, 0 failed.

Read #398's report first, as asked. All eleven of its follow-ups had landed
before I started, and #411 in particular had already corrected four Quickstart
claims (three screens → four, ⏎ expand vs ⏎ triage, the three-verdict menu,
the refine-is-not-a-verdict framing), so the README was in better shape than the
task body assumed. What remained was the key inventory and the review step.

Claims that were wrong

The a/A pair was missing entirely. The "other keys worth knowing" line
named s/x/h/e/l/q and nothing else, so the two keys that changed
meaning in #120 went undocumented. MESSAGE_KEYS in ui.rs:2016 and the
handlers at app.rs:1639-1640 confirm a is the headless quick-message into the
task's recorded session and A the interactive attach/resume. Both are now in
the key line.

Refine was described as proposal-only, and as leaving the task a proposal.
refine_selected (app.rs:1928) accepts Proposed | Ready, and the round moves
the task into refining — a real state, not an event — returning it to
proposed whatever it started from (transition.rs:126, and the refine
tests). So a refined ready task comes back through triage, which the README did
not say, and "the task stays a proposal" was wrong for that path and wrong about
the interim state for both. Rewritten, with C (cancel a round in flight) named.

g was described as medium-dependent. "creating it when the project reviews
through GitHub" reads as a per-project review-medium setting, which #130
removed. DESIGN.md §8 is explicit — "each one is static": pr/g is always
GitHub, open/o always a local viewer, and g on a checkout with no remote
refuses and names o. open_selected_pr (app.rs:2626) matches. Rewritten to
state the split, and to mention the confirmation modal that now precedes a
create.

Review's hand-off was unmentioned. legal_actions(Review) is Accept,
RejectWork, HandOff, Abandon (transition.rs:136), and w is bound directly
(app.rs:1643). The README said "accept or reject", so a reader had no idea
waiting existed. One clause added.

? was absent, which is the acceptance criterion and also what lets the tour
stop carrying a reference. Added to the navigation paragraph, and the key line
now closes with "? has the rest."

Two smaller additions, both at the README's existing altitude: mouse row
selection (#115main.rs:122), and c for document links, which was the one
landed feature from the "deserves a sentence" list that fits a key line.

Claims I verified as still correct

Four screens and what Config shows (draw_config, ui.rs:1682); tab cycling
and alt-1alt-4, including the gating to Projects/Config while no project
exists (toggle_screen/jump_to_screen, app.rs:1234-1259); first launch
opening on Projects (app.rs:685); 03 priority and 05 weight; n /
N / ctrl-n and the template's state: ready default (editor.rs:29); the
digest-then-triage two-step and the three verdicts; d/D; the completion
summary leading the review card (#407, ui.rs:908); the built-in viewers
code/cursor/zed and the add-viewer form fallback (BUILTIN_VIEWER_NAMES,
report_open); the accept-does-not-merge paragraph; every CLI verb the
Dispatching section names; Rust 1.88 (matches rust-version in the workspace
manifest) and the two prebuilt targets (dist-workspace.toml:13); and the plugin
section against .claude-plugin/marketplace.json.

No behavioural defects found, so nothing to propose. The one thing that looked
like an inconsistency — voro add defaulting to proposed while the ctrl-n
template defaults to ready — is deliberate per DESIGN.md §8, where planning
sessions and quick-propose both file through add and land in proposed.

Screenshot

docs/images/voro-tui.png regenerated, 1358x922 (was 1331x1270 — same width
class, shorter because the old shot was mostly empty detail pane).

Seeded a scratch store per .claude/skills/verify/SKILL.md (--db, not
VORO_DB, as the skill insists) with four projects at distinct weights —
voro:5, mote:4, atlas-api:3, notes-site:1 — and fourteen tasks spread across
proposed, ready, running, needs-input, review and waiting, with real-sounding
titles and bodies. Drove the real TUI in an isolated tmux at 110x38, selected the
review task so the card opens on its completion summary, captured with
capture-pane -e -p, converted the ANSI to HTML with a small parser I wrote for
this, and screenshotted it in headless Chrome at 2x device scale.

The new image shows what the old one could not: the per-state colour coding in
the queue's state column (#123/#129), proposal digests, the completion summary
inside its cyan agent-voice gutter (#407/#430), a running strip carrying two live
sessions plus a handed-off waiting task (#125), and the current footer
including ? keys. The old image showed a next-action verb column, no running
strip, and a footer with none of the review keys.

docs/images/claude-voro.png is out of scope as instructed, and is stale in
exactly the same ways — its Voro pane shows the old verb column, no running
strip, and the pre-#114 footer. It needs a manual recapture with a live Claude
session before the release is promoted.

The README's key inventory predated the `a`/`A` split, the `?` key map, and
the static review keys, so a v0.2.0 reader would have been told about a UI
that no longer exists.

Four claims were wrong. `a` is now a headless quick-message into the task's
own session and `A` the interactive jump-in, but the key line named neither.
Refine was described as a proposal-only action that left the task a proposal;
it works on ready work too, moves the task through a real `refining` state,
and returns a refined ready task through triage. `g` was described as
creating a PR "when the project reviews through GitHub", which reads as a
per-project medium setting — the keys are static now, `o` always local and
`g` always GitHub, with `g` naming `o` on a checkout with nowhere to push.
And review offers a hand-off (`w`) the walkthrough never mentioned.

The README now points at `?` for the full key map, which is what lets the
tour name only the keys it needs rather than carrying a reference.

The screenshot was reshot against a seeded scratch store: the queue's
state column and its per-state colours, the completion summary in its
agent-voice gutter, and a running strip carrying both live sessions and a
handed-off task — none of which existed when the old image was taken.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013EuZkRZHDodxhE3Xt22ry4
@MJohnson459
MJohnson459 merged commit 48dc852 into main Aug 14, 2026
7 checks passed
@MJohnson459
MJohnson459 deleted the readme-accuracy-v0.2.0 branch August 14, 2026 19:33
Sign up for free to 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