docs: plan for updating the user manual for rev4 hardware

[brickbots]

Adds rev4-docs-update-plan.md at the repo root (following the bringup-implementation-plan.md precedent), plus the tooling needed to act on it. No .rst is changed — the manual itself is untouched.

⚠️ Agents working WP1–WP4: do not branch from main while this PR is open. See Branching below.

Why

v2.6.1 ships full software support for rev4, but docs/source/ still describes rev3 exclusively. In the power/charging area it is not merely incomplete — it is actively wrong for a rev4 owner:

• user_guide.rst:773-776 — "There is no battery-level indicator on the screen and no low-battery warning: when the charge is depleted the PiFinder simply shuts off." False in all three claims on rev4.
• user_guide.rst:819-841 — PiSugar S Plus as the charging story. rev4 has an on-board BQ25895.
• quick_start.rst:48-68, troubleshooting.rst:16-33 — a white slide switch. rev4 has a momentary power button.
• Volume (Settings → User Pref) shipped in 2.6.1 with zero documentation, in neither user_guide.rst nor menu_map.rst.

Decisions (settled — recorded in §2)

1. rev4 becomes the default voice; v3/v2.5 differences go in .. note:: blocks.
2. "rev4" alongside "v3"/"v2.5", no retro-rename of the older names.
3. 176 px is the default for new screenshots. No mass replacement of the 118 existing 256×256 shots; a page's shots get re-taken when that page is edited anyway.
4. rev4 DIY build path out of scope, with no scoping note — build_guide.rst and BOM.rst untouched. This deleted WP5.

Battery life: now a real number

The bench campaign closed 2026-07-26 (six discharges, two units — ADR 0020 updated in #573). Runtime is about 10 hours: 9h55m and 10h03m under a deliberate worst case — camera solving continuously, screen at full brightness, display sleep off. The plan tells WP1 to quote it as a floor and note that ordinary observing runs longer, and to drop the v3/PiSugar "four to five hours" entirely. This closed the plan's first open question.

Branching — where WP agents start

WP1–WP4 depend on three things that exist only on this branch: the pf_remote.py --display headless_176 / -fb flags, the docs skill's rev4 rules plus the corrected product knowledge base, and the plan file itself. A WP branch cut from main looks perfectly healthy and quietly produces 128 px screenshots and rev3-default prose.

• Preferred: merge this PR first, then WP agents branch from main normally. It is a plan doc, a skill/tooling change and no product code, so it is cheap to land.
• While it is open: git reset --hard origin/worktree-rev4-docs-plan after EnterWorktree (the harness bases worktrees on origin/HEAD, which can resolve to release in this clone), and open WP PRs with --base worktree-rev4-docs-plan. GitHub retargets them to main on merge.
• Do not wait on ADR 0020: battery profiling complete — refit derived, deliberately not adopted #573. Nothing in WP1–WP4 depends on it.

WP0 is implemented here

The plan shouldn't document a flag that doesn't exist, so this branch adds it:

• pf_remote.py launch --display {headless_176,headless,headless_320}, defaulting to headless_176 — rev4's panel without asking.
• pf_remote.py launch -fb/--fakebattery — the rev4 battery monitor, needed for any title-bar shot (plain -fh emulates rev3, so the icon is simply absent).
• Both skills updated; the docs skill's product-knowledge-base.md rewritten — it described rev4 as "a planned future revision… still in early design… no working prototype on a scope yet," which would have poisoned anything an agent wrote from it.

Verified end to end, not by inspection: launched headless with -fb, captured /api/screen at 176×176 with the battery icon present, converted through screenshot_to_doc.py to a 352×352 amber PNG.

What remains

WP1 (Power & Charging rewrite) · WP2 (Sound + Volume) · WP3 (screen, joystick, "Which PiFinder do I have?") · WP4 (new bring-up page). WP1/WP2/WP3 all edit user_guide.rst, so they need separate worktrees or sequencing; WP4 is the safe one to parallelise, since it only adds a page and one toctree line.

Notable findings

• rev4's directional input is a single 5-way joystick (centre press = SQUARE), not separate arrow buttons. The code and docs/ax/bringup/CONTEXT.md describe it in switch language against a glossary defining switch as "one physical pushbutton" — flagged as a /grill-with-docs candidate. It matters for bring-up: a builder with one dead direction is reflowing one component, not hunting five switches.
• No rev4 case STLs, gerbers or KiCad project are tracked, so a rev4 build guide couldn't be written from the repo even if it were in scope.

Verification

sphinx-build -n reports zero warnings on this branch, matching the origin/main baseline — so any warning a later agent sees is one they introduced. That build needs a throwaway venv; the project venv lacks sphinxcontrib-mermaid, which menu_map.rst requires. Both facts are recorded in §5.

🤖 Generated with Claude Code