docs: internal bring-up reference (docs/ax/bringup.md)

[brickbots]

WP4 of the rev4 documentation update (rev4-docs-update-plan.md §4), reworked per Rich's call on this PR: bring-up is internal reference material, not manual content.

Net diff against main is two files — a new docs/ax/bringup.md and one line in CONTEXT-MAP.md. Nothing lands in docs/source/, and nothing enters the Sphinx build.

What changed since the first push

• git mv docs/source/bringup.rst → docs/ax/bringup.md, converted rST → Markdown. docs/ax/bringup/ held only CONTEXT.md; per CLAUDE.md the docs/ax/<area>.md slot beside it is where the deep-dive goes, alongside camera.md, catalog.md, positioning.md, equipment.md, sqm.md, ui.md.
• docs/source/index.rst reverted — git diff origin/main -- docs/source/index.rst is empty, byte for byte.
• Re-registered in the docs/ax house style: numbered ## N. sections, source files and the glossary link up front, ADR links inline (0006, 0007, 0009, 0017), a closing Gotchas list. The manual's voice and its reader-at-the-eyepiece scaffolding are gone — the whole file is now for someone at a bench, so it no longer says so as an aside.
• CONTEXT-MAP.md: added to the "Companion architecture docs live next to each CONTEXT.md" block (line 42ff), which is where the docs/ax/<area>.md files are indexed. That is one line, and it matches the surrounding style more closely than appending a second link to the Bring-up context bullet at line 17, where every entry links only its CONTEXT.md. Say the word if you'd rather have it on line 17 instead.

What the document covers

• What a bring-up run is, what it deliberately does not start, and when to run one.
• The command, --revision rev3 for a v3 board, --rotate 2 for Bloom/Heart, and why the panel is never derived from a hardware probe.
• The pre-flight, with the card-versus-board framing and the skipped vs FAIL encoding of it.
• The six checks by kind — probed (IMU, charger), exercised (switches), witnessed (screen, backlight, buzzer) — what each screen pattern proves, and a verdict section stating plainly that a pass says nothing about screen, backlight or buzzer. No witnessed check is ever described as passing.
• The dashboard, its three status rows, and the switch grid.
• The power hold, tap vs hold, --no-power-shutdown, --timeout, Ctrl-C.
• The printed summary, passing and failing, with a three-bullet guide to reading a failure.
• An options table, and six gotchas.

Both dangerous misreads survived the move intact and keep their own subsections:

• Blank cells are not faults — rev4 populates the right-hand column where v3 populates the bottom row; the run counts against the population map for the revision it is validating (18 on rev4, 17 on v3).
• The rev4 joystick is one component — those five right-hand positions are five contacts of one 5-way joystick. The grid says which contact; the part to rework is one joystick.

Issues folded in

• Buzzer never sounds on rev4: pifinder_setup.sh routes only PWM ch1, not ch0 #579 (pifinder_setup.sh routes only PWM ch1, so the rev4 buzzer on ch0/GPIO12 is silent) is now linked from the NOT ROUTED passage, so the dtoverlay=pwm-2chan,... workaround has a tracked home rather than living only in prose.
• Earcon.ERROR and Earcon.SOLVE_LOCK are defined but have no producer #581 (Earcon.ERROR / SOLVE_LOCK defined but unwired) is cited in a new gotcha recording that only STARTUP, KEYPRESS and SHUTDOWN are ever emitted — so nobody goes listening for an error tone that does not sound. The check table never implied one.
• Volume setting appears on hardware without a buzzer and does nothing #580 (Volume on v3) is out of scope for this file. The nearest relevant fact — that Hardware.open decides the buzzer seam from the pre-flight alone, so a --revision rev3 run on a card that routes ch0 will report BUZZER emitted for a buzzer a v3 board does not have — is recorded as its own gotcha.

Terminology discrepancy (flagged, not fixed)

docs/ax/bringup/CONTEXT.md describes the rev4 directional input in switch language — "rev4 carries a right-hand column instead, with its own centre SQUARE (18 switches)" — against a glossary defining switch as "one physical pushbutton on the board… a solder joint that can be cold, bridged or missing". Physically it is one 5-way joystick presenting five contacts.

The CONTEXT.md is untouched (grill-with-docs territory). bringup.md says "joystick", and carries a short blockquote noting the gap so the next reader does not "correct" the page back to the glossary's wording.

Figures

None referenced. Every figure is prose or a fenced block: a matrix map of the rev4 grid, the pre-flight line, the dashboard status rows, and both summary forms. The pre-flight and summary blocks were generated by running bringup.py's own formatters (format_preflight, format_summary, switches_detail) and are byte-identical to its output — column alignment included, and re-verified after the Markdown conversion.

Two photos from plan §6 remain wanted but are no longer blocking anything, since this file is not a manual page:

#	Photo	Notes
15	rev4 panel mid-bring-up, grid partly lit	Headless rendering works — the draw path composes a real 176 px frame off-Pi — but with no hardware attached the status rows read IMU -- unavailable / CHG -- unavailable, a board that looks half dead. Not shipped rather than stage a misleading frame.
16	rev4 panel showing the power-hold bar	Same. The bar renders (PWR → [#---] → [####]); the frame around it cannot be made honest off-hardware.

Verification

sphinx-build -b html -n -E -q docs/source /tmp/pf_bringup_check

Empty output, exit 0 — a full rebuild in nitpicky mode with the toctree entry gone, so no dangling reference and no orphaned document. grep -rln bringup docs/source/ returns nothing.

🤖 Generated with Claude Code