docs: rewrite Power & Charging for rev4 (WP1)

[brickbots]

Part of the rev4 documentation update (rev4-docs-update-plan.md, WP1). Three sibling packages — WP2 (sound/Volume), WP3 (screen/joystick/"Which PiFinder do I have?") and WP4 (bring-up page) — are running in parallel.

Why

The manual's Power & Charging material described a v3 PiSugar unit throughout, and three of its claims are false on rev4:

There is no battery-level indicator on the screen and no low-battery warning: when the charge is depleted the PiFinder simply shuts off.

rev4 has all three: a title-bar indicator, advisories at 10% and 5%, and an orderly automatic shutdown. The section also described a slide switch, two ports with a "one charges, one is wired ahead of the switch" split, and a four-to-five-hour runtime — none of which carry over.

What changed

docs/source/user_guide.rst

Power & Charging restructured with rev4 as the default voice and v3/v2.5 differences in scoped .. note:: blocks:

Sub-section	Content
Power button and shutdown	Press to start; press and hold ~1 s to reach the shutdown confirmation, a second press confirms, a tone plays and the unit powers itself off. Cross-links user_guide:shutdown.
Charging	The faceplate-labelled POWER and DATA ports; ~1.5 A charge current and picking a supply that can deliver it; about six hours from empty with the unit off; the unit can be used while charging, which stretches the charge considerably; the CHG indicator, including an honest word that it is red but bright to a dark-adapted eye.
The battery indicator	The glyph is a state-of-charge estimate expressed as remaining runtime, not capacity remaining (ADR 0020). No percentage while charging — the charger pulls the voltage up, so the bolt appears instead. Empty once the charger's ADC can no longer measure the cell.
Low-battery warnings and automatic shutdown	Advisories at 10% and 5%, each once per discharge, re-armed by plugging in; roughly 1½ h and ½ h of lead time under the bench load. Then a final warning and an orderly shutdown, framed by why it exists: avoiding an SD-corrupting hard cut.
Battery life	About ten hours from the 8,000 mAh cell, quoted as a measured floor under a continuously solving load with the screen at full brightness and sleep off — explicitly not a typical figure.
Running on external power	Rewritten around the POWER port; the v3 "power bank on the power-only port with the battery switched off" trick kept as a v3 note.
Battery safety & care	PiSugar-as-universal-truth removed; the S Plus material (including the replacement-part warning) kept, scoped to v3.

The Shutdown section now leads with the power button, with the Quick Menu route kept below and a v3 note. Its shutdown_confirm.png was re-taken at 176 px per D3 rule 3.

docs/source/quick_start.rst

• Powering the PiFinder: POWER/DATA ports, CHG light, ~6 h charge, power button; v3 slide switch and blue/green LED in a note.
• Shutting down the PiFinder: power-button gesture as the primary route; the keypad route kept in a v3 note.

docs/source/troubleshooting.rst

• The PiFinder won't turn on: power button not slide switch; the battery indicator now exists and is cross-linked; PiSugar and power-only-port advice scoped to a v3 note.

Screenshots (all 176 px → 352×352)

Captured with pf_remote launch -fb, which runs a full simulated discharge lap, so every battery state was reachable without hardware.

• images/user_guide/battery_full_docs.png, battery_mid_docs.png, battery_empty_docs.png — the indicator stepping down
• images/user_guide/battery_charging_docs.png — the charging bolt
• images/user_guide/low_battery_warning_docs.png — the 10% advisory
• images/user_guide/low_battery_shutdown_docs.png — the automatic-shutdown warning
• images/quick_start/shutdown_confirm.png — re-taken at 176 px, reached by sending POWER_BTN

Photos Rich needs to shoot

Per plan §6, agents cannot produce these. Rather than reference paths that don't exist (which would break the clean build), the existing .. image:: directives stay in place with an rST TODO(rich) comment above them.

1. rev4 top-down: power button + the POWER and DATA USB-C ports, with callouts in the style of the current shot. Replaces images/quick_start/power.jpeg, which shows the v3 slide switch and is the single most wrong image in the manual. Referenced twice — quick_start.rst "Powering the PiFinder" and user_guide.rst "Power button and shutdown" — so one photo fixes both.
2. rev4 charging — cable in the POWER port with the CHG indicator lit. Would sit in user_guide.rst Charging; not currently referenced.
3. rev4 battery in place / battery compartment (plan §6 #14) — would support Battery safety & care; not currently referenced.

Open items

• No TODO(rich) fact markers remain. Both WP1 open questions closed mid-flight: capacity 8,000 mAh and charge time about six hours. The only two TODO(rich) comments left in the diff are the photo placeholders for #1 above.
• Charge time is worded as an approximation ("about six hours"), because it is calculated from capacity and charge current rather than timed on the bench — deliberately not stated with the confidence of the measured ~10 h runtime.
• The v3 "four to five hours" figure is deleted rather than kept as a v3-scoped note. That follows the WP1 brief literally. If you'd rather v3 owners kept a runtime number, restoring it as one line under Battery life is a trivial follow-up.
• main_menu_01_docs.png and main_menu_marking.png were not re-taken, even though they appear in the Shutdown section I edited. Both are shared with quick_start.rst, which WP3 owns this pass; re-taking them here would silently change WP3's page and risk a binary conflict. They stay at 256 px for now.
• Power-button gesture wording: keyboard_pi.py:150-161 only emits POWER_BTN after the button has been held for more than a second, so the prose says "press and hold it for about a second" rather than a bare press. Worth a sanity check against the real board.
• The .. image:: for power.jpeg is still a v3 photo. Until #1 above lands, both pages show a slide switch beside prose describing a button. That is the one remaining rev4 inaccuracy in these sections and it is a photo problem, not a prose one.

Verification

sphinx-build -b html -n -q source /tmp/pifinder_docs_build_wp1
exit=0, no warnings or errors

Baseline was zero warnings in nitpicky mode and still is. Built with the shared docs venv (the project venv lacks sphinxcontrib-mermaid), against a clean build directory so nothing is masked by an incremental rebuild.

Scope respected: docs/source/*.rst only; no docs/*.md stubs, no docs/ax/, no docs/adr/, no build_guide.rst, no BOM.rst, and none of WP2's or WP3's sections.

🤖 Generated with Claude Code