diff --git a/spikes/hardware-boards/DESIGN-LANGUAGE.md b/spikes/hardware-boards/DESIGN-LANGUAGE.md
new file mode 100644
index 000000000..22c9ff5d3
--- /dev/null
+++ b/spikes/hardware-boards/DESIGN-LANGUAGE.md
@@ -0,0 +1,75 @@
+# Board diagram design language — cheat sheet
+
+Vocabulary for talking about LightPlayer board diagrams. Everything renders from
+board metadata (plain JSON) through one SVG renderer.
+
+## Layout vocabulary
+
+| Term | Meaning |
+|---|---|
+| **Unit** `u` | Pin pitch = row height. THE scaling factor — every other dimension derives from it. |
+| **Row** | One pin's horizontal band, `u` tall. All annotation for a pin lives in its row, so every pin can be annotated simultaneously. |
+| **Cell** | A typed chip inside a row. Width fits content; height is fixed (`0.78u`). |
+| **Rail** | The stack of rows on a left/right board edge. Rails extend outward from the pads. |
+| **Band** | Horizontal strip above/below the rails holding rows for top/bottom-edge pins (screw terminals etc.), which can't have vertical rows. |
+| **Leader** | Elbow line connecting a top/bottom pad to its band row. |
+| **Pad** | The pin's physical marker on the board edge, colored by role. |
+| **Label** | The pin's name, silkscreen-style *inside* the board edge, colored by role. Keeps outside cells left-aligned into columns. |
+
+## Derived geometry (all from `u`)
+
+| Element | Size |
+|---|---|
+| Row height / pin pitch | `1.00u` |
+| Cell height | `0.78u` |
+| Pad | `0.62u × 0.45u` |
+| Cell font | `0.50u` |
+| Cell gap | `0.22u` |
+
+## Cell types
+
+| Type | Color family | Used for |
+|---|---|---|
+| `name` | slate | Pin name (band rows only; rails put names inside the board) |
+| `pwr` / `gnd` | red / dim | Power and ground |
+| `adc` `dac` `touch` | green / blue / orange | Analog capabilities |
+| `spi` `i2c` `uart` `usb` | violet / cyan / brown / amber | Buses |
+| `strap` | amber | Boot-strap pins — usable, with care |
+| `warn` | dim orange | Caution: input-only, XTAL, PSRAM-reserved, JTAG |
+| `conn` | **violet** | A bound connection (studio convention: bound = violet) |
+| swatch | — | Discovery color code (n solid squares) |
+
+## Pin roles (pad + label color, drives eligibility)
+
+`pwr5` `pwr3` `gnd` `io` `ioin` (input-only) `strap` `usb` `ctl` (EN/RST) `nc`
+
+Output-eligible for LEDs: `io`, `strap`. Never: `ioin`, `usb` (e.g. C6 IO12/13
+USB-JTAG), `nc`, power/ctl, and pins already bound or reserved (onboard RGB).
+
+## Renderer modes
+
+| Mode | Question it answers | Where |
+|---|---|---|
+| `plain` | what does the board look like? | catalog / picker thumbnails |
+| `caps` | what's *supported* on each pin? | boards page detail |
+| `wired` | what's *connected*? | device card hardware pane |
+| `swatch` | which pin are my LEDs on? | pin discovery |
+
+## Discovery language
+
+- **Order test**: the 9-pixel palindrome `K-R-G-B-W-B-G-R-K`, repeated on every
+ free pin. K bounds each repeat, W marks the center; palindrome ⇒ direction
+ doesn't matter; K/W are permutation-invariant ⇒ the perceived row uniquely
+ identifies the strip's color order (RGB/GRB/…).
+- **Code**: a pin's steady color sequence. Codes are **palindromes** — data
+ direction is unknown, so a code and its reverse are indistinguishable; a
+ palindrome reads the same from either end. Displayed with **K (off) pixels
+ between digits** so color runs read unambiguously, but no leading/trailing K —
+ short strips (even 3 LEDs) must still show 1-digit codes. A `d`-digit code
+ occupies `2d−1` physical pixels.
+- **Code plan**: smallest `d digits × c colors` with `c^ceil(d/2) ≥ free pins`
+ (a length-`d` palindrome has `ceil(d/2)` free digits), colors drawn in order
+ from the palette `R G B C M Y W` (K is reserved as the separator). Even digit
+ counts are never optimal, so the ladder is 1 digit (1 px) → 3 digits (5 px) →
+ 5 digits (9 px). E.g. 20 pins → `3 digits × 5 colors` = 25 `X·Y·X` codes on
+ 5 pixels.
diff --git a/spikes/hardware-boards/README.md b/spikes/hardware-boards/README.md
new file mode 100644
index 000000000..dac4c73c5
--- /dev/null
+++ b/spikes/hardware-boards/README.md
@@ -0,0 +1,39 @@
+# Hardware / board selection — UX spike
+
+Raw-HTML exploration (repo spike convention) for board selection as a first-class
+feature. Feature notes: Dropbox `Planning/lp2025/_features/hardware - selection, pin discovery.md`.
+
+Open `index.html` (any static server). **Rev 2** after Yona's gate feedback.
+
+## The row layout engine (rev 2 core)
+
+The pin row is the layout unit: `u` = pin pitch = row height, and everything
+derives from it (pad `0.6u`, cell `0.78u`, font `0.5u`). Concepts:
+
+- **Row** — one pin's horizontal band; cells never leave it, so *every* pin can
+ hold cells simultaneously (rev 1's staggered callouts could not).
+- **Cell** — typed chip in a row: name, capability (`adc`/`touch`/`spi`/`i2c`/
+ `uart`/`usb`/`strap`/`warn`), connection (violet = bound), or color swatch.
+- **Rail** — the stack of rows on a board edge (left/right extend outward).
+- **Band + Leader** — top/bottom-edge pins (e.g. QuinLED screw terminals) get
+ rows in a band above/below the rails, tied to the pad by an elbow leader line.
+
+One renderer, four modes: `plain` (catalog thumbnails), `caps` (what's
+supported — the classic pinout-diagram view), `wired` (what's connected, device
+card), `swatch` (pin discovery). Board defs are plain JSON — agent-buildable
+(this page's were), user-editable later.
+
+## Surfaces
+
+1. **Boards catalog** — cards w/ SVG wireframe, gold/silver/bronze tier, price,
+ purchase links, sort + SoC filter.
+2. **Board pinout** — full capability view per board + the design-language doc.
+3. **Provisioning picker** — flasher-detected SoC leads; mismatches collapse;
+ dashed generic fallback.
+4. **Device card · hardware pane** — wired connections inline in pin rows;
+ QuinLED demos the top-edge terminal band.
+5. **Pin discovery** — solid color codes (no motion). Step 1: color-order test
+ (K-R-G-B-K-B-G-R-K on every pin; user picks the row they see → RGB/GRB/…).
+ Step 2: combinatoric codes — smallest pixels×colors from RGBCMYW covering the
+ free-pin count, computed in code (e.g. 20 pins → 2 px × 5 colors). Input-only,
+ USB-JTAG (C6 IO12/13), and in-use pins are auto-skipped.
diff --git a/spikes/hardware-boards/index.html b/spikes/hardware-boards/index.html
new file mode 100644
index 000000000..176415be2
--- /dev/null
+++ b/spikes/hardware-boards/index.html
@@ -0,0 +1,1347 @@
+
+
+
+
+Hardware & board selection — design spike
+
+
+
+
+
+
Hardware & board selection — design spike · rev 2
+
+ Rev 2 after gate feedback: the pin row is the layout unit — one row height
+ drives pads, cells, and type, and every pin can hold cells simultaneously. Pin
+ discovery switched from motion patterns to solid color codes with a
+ color-order pretest. All boards still render from one metadata schema.
+
+
+
1 Boards catalog
+
The "what should I buy" page. Thumbnails are the same renderer in plain mode.
+
+ Gold first-class, tested every release
+ Silver supported, tested occasionally
+ Bronze community-verified, should work
+
+
+ Sort
+
+
+ SoC
+
+
+
+
+
+
+
+
+
+
+ proposed board metadata (one entry, verbatim from this page's data)
+
+
+
+
2 Board pinout — the row layout engine
+
+ The full "what's supported" view (compare: the classic pinout diagrams). Every pin
+ owns a row; capability cells sit inside it. Boards pick their own row height via
+ scale — nothing ever overlaps because the row is the unit.
+
+
+ Board
+
+
+
+
+
+
+
Anatomy — the vocab in place
+
+
+
+
Design language (proposed)
+
+
Unit u
pin pitch = row height. Everything scales from it:
+ pad 0.6u, cell 0.78u, font 0.5u.
+
Row
one pin's horizontal band. Cells never leave their row, so
+ every pin can be annotated at once.
+
Cell
typed chip in a row: name, capability
+ (adc, touch, spi…), connection,
+ or swatch. Width fits content; height is fixed.
+
Rail
the stack of rows on a board edge. Left/right rails extend
+ outward from the pads.
+
Band
top/bottom-edge pins can't have vertical rows — their rows
+ go in a band above/below the rails, tied to the pad by a leader line.
+
Leader
elbow line from a pad to its band row.
+
+
+
Pad
the pin's physical marker on the edge, colored by role.
+
Label
pin name, silkscreen-style inside the board — so
+ outside cells share one start edge and align into columns.
+
+
Board defs are plain JSON — buildable by agents (this page's were), editable
+ by users later. Same renderer, four modes: plain ·
+ caps · wired · swatch.
+ Full vocab: DESIGN-LANGUAGE.md next to this file.
+
+
+
+
+
3 Provisioning — pick your board
+
+ We know the SoC from the flasher. Matching boards lead; mismatches collapse; dashed
+ generic card is the escape hatch.
+
+
+ Detected SoC
+
+
+
+
+
+
+
+
+
+
+
4 Device card — hardware pane
+
+ "What's connected" — same rows, connection cells (violet = bound). Every pin keeps
+ its name cell, so the wiring reads in context. Second card: screw terminals on the
+ top edge land in a band with leader lines.
+
+ QuinLED-Dig-Uno
+ top-edge terminals → band + leaders
+
+
+
+
+
5 Pin discovery — solid color codes
+
+ No motion: each free pin shows a steady color code on the first pixels of whatever
+ strip is attached. Step 1 nails down the strip's color order (otherwise color codes
+ lie); step 2 assigns combinatoric codes — pixel count × color set computed from how
+ many free pins we need to cover.
+
+
+
+
Step 1 of 2What colors do you see?
+
+ Every pin repeats this 9-pixel palindrome (K = off, W = center marker) — it reads
+ the same from either end, so it doesn't matter which way your strip runs. If the
+ color order isn't RGB you'll see swapped colors — pick the row that matches.
+