Sprint 4 Design Pack — GWP-266

Story Narrative

docs/software/runtime/README.md line 20 advertises four “Stubs to fill” sub-docs. One (cartridge-lifecycle.md) already exists and is well-fleshed-out — that bullet is stale and should be retired in this same PR. The other three (display-pipeline.md, audio-pipeline.md, coprocessor-bridge.md) are the integration-level docs an engineer would reach for first when joining the project: how does a glyph travel from a text-puts call to a pixel on the Elecrow? How does an nvelope-set reach the MAX98357A speaker? How does the Pi userspace daemon talk to the Pico? Each one is synthesis from existing sources — ADRs, the canonical hardware spec in CLAUDE.md, the FFI table in ADR-0005, the wire-format grammar at docs/software/api-reference/grammars/coprocessor-protocol.md, and the emulator source under kn86-emulator/src/. No new design decisions; just consolidation + diagram + reader-aimed framing.

Acceptance Criteria (expanded)

docs/software/runtime/display-pipeline.md (NEW)
- Reader frontmatter: “an engineer who needs to trace how cartridge draw calls reach the panels.”
- Sections: (1) Two-display target overview (primary 1024×600 Elecrow + auxiliary 256×64 SSD1322 OLED). (2) Logical framebuffer model — 960×600, 80×25 grid, 12×24 cell math, where the 8×8 glyph sits inside the cell, the 32-px horizontal letterbox per side. (3) The Row 0 / Rows 1–23 / Row 24 authority split (firmware owns 0 and 24; cart owns 1–23). (4) BITMAP vs TEXT vs SPLIT mode plumbing. (5) OLED routing — CIPHER glyphs go through the coprocessor bridge, never through the primary framebuffer (ADR-0015). (6) Pixel-perfect verification approach (emulator and device must produce byte-identical output for the same draw sequence).
- References: ADR-0014, ADR-0015, display.c, oled.c, font.c.
docs/software/runtime/audio-pipeline.md (NEW)
- Reader frontmatter: “an engineer wiring or debugging cart-side audio.”
- Sections: (1) Cart-side primitives (the psg-* and noise-* FFI calls — point at ADR-0005 §Audio rather than restating). (2) Pi-side path — primitive call → command queue → UART frame → Pico → YM2149 emulation → I2S → MAX98357A → 8Ω 28mm speaker. (3) Emulator path — the in-process coproc.c stub routes the same commands into psg.c directly; same cart-side semantics, no UART. (4) 44.1 kHz mono PCM cadence, 14-register YM2149 model, envelope/noise generators. (5) Latency budget end-to-end. (6) Where the audio callback lives (SDL on emulator; ALSA-or-pulse on Pi via Pico→I2S — confirm with platform engineering).
- References: ADR-0017, psg.c, sound.c, coproc.c, ADR-0005 §Audio.
docs/software/runtime/coprocessor-bridge.md (NEW)
- Reader frontmatter: “an engineer building or extending the Pi-side userspace daemon that owns /dev/serial0.”
- Sections: (1) What the bridge is responsible for (the Pi side of the UART link defined in docs/software/api-reference/grammars/coprocessor-protocol.md). (2) Command queue design — single-writer, bounded, drops-to-disk under back-pressure or NACKs and surfaces error to caller. (3) Backchannel event subscriber — the Pico can push events (CIPHER-LINE keypress on TERM seed-capture, audio underrun, etc.); the bridge demuxes and forwards to nOSh. (4) Error recovery — UART resync (frame-marker sentinel scan), command-timeout handling, full-restart escalation. (5) Boot-time handshake — version negotiation between Pi-side bridge and Pico-side firmware. (6) Emulator stub equivalence — coproc.c ships the same in-process API so cart code is target-agnostic.
- References: ADR-0017, docs/software/api-reference/grammars/coprocessor-protocol.md, coproc.c.
Frontmatter consistency: every new doc starts with a one-line “Reader” framing + an explicit “Related:” bulleted list. Match the pattern in cartridge-lifecycle.md lines 1–9.
README.md L20 stub list updated: retire cartridge-lifecycle.md from the stub list (it exists), tick the other three off.

Edge Cases (≥2)

audio-pipeline.md Pi-side ALSA-vs-Pico-only audio. ADR-0017 has the Pico owning YM2149 synthesis with I2S out direct to MAX98357A — meaning the Pi may not host any ALSA audio path at all in production. The doc author needs to flag this clearly: “audio leaves the Pi via UART commands, not via Pi audio out.” If platform engineering hasn’t fully decided whether the Pi keeps an ALSA path for future PCM voice barks (ADR-0017 + GWP-171 territory), surface this as an open question rather than guessing.
coprocessor-bridge.md and the cart-mount event source. Per ADR-0019, the cartridge bus is no longer the Pico’s responsibility (USB-MSC over the internal hub). The bridge doc must NOT imply the bridge handles cart events — those flow via udev on the Pi, not the UART. Easy to get wrong if author defaults to “everything coprocessor goes through here.”
Diagram volume. The temptation will be to add ASCII flow diagrams everywhere; restrain to one per doc (the end-to-end path) and lean on the existing ADRs for component-level diagrams. Otherwise these docs duplicate the ADR illustration content and drift later.

Engineering Hand-off Notes

Files (additive only, except README touch):
- docs/software/runtime/display-pipeline.md — NEW
- docs/software/runtime/audio-pipeline.md — NEW
- docs/software/runtime/coprocessor-bridge.md — NEW
- docs/software/runtime/README.md — update the L20 stub list (retire cartridge-lifecycle, add live links to the new three)
Do NOT touch: any ADR, any source under kn86-emulator/, any other docs/ subtree.
Audience tone: these are engineer-facing integration docs, not fiction-heavy. Match cartridge-lifecycle.md’s clarity, not the design-bible voice.
Length target: ~150–300 lines per doc. If a section threatens to grow past that, link to the source-of-truth (ADR or grammar spec) instead of restating.
Spec hygiene: zero canonical hardware values restated — every spec value links to CLAUDE.md Canonical Hardware Specification or to the relevant ADR.
Single PR. Doc-only; no test impact. Brief: doc-writing agent (or Marketing/Product agent in writing mode), not engineering.

Open Questions for Josh

Is the Pi expected to retain any ALSA / PulseAudio path at all for future PCM-voice-bark work (GWP-171), or does all audio leave via UART → Pico → I2S? Answer pins one paragraph in audio-pipeline.md.