Add /io-enrich command (Pillar 2) + correct Apollo Twin X I/O

.changeset/io-enrich-command.md

@@ -0,0 +1,21 @@
+---
+"catalog": minor
+---
+
+Add the `/io-enrich` enrichment command and correct the Apollo Twin X I/O.
+
+Pillar 2 of the I/O data-quality plan (#212): a repeatable, authoritative-source
+process for fixing and enriching a hardware entry's `io`.
+
+- New `.claude/commands/io-enrich.md` codifies the manual-first workflow proven on
+  the Eventide H90: read the manufacturer manual/QRG panel diagrams, model one
+  entry per physical jack, set positions and column/row from the diagram, verify
+  adversarially (flag ambiguous jack faces to the user rather than guess), then
+  validate and cite sources.
+- Piloted it on the **Universal Audio Apollo Twin X**, replacing an incorrect
+  6-entry list (collapsed "Two 1/4\" Monitor Outs"/"Line Outs" pairs, a split
+  Thunderbolt, no mic/line/instrument inputs, everything guessed as `Top`) with
+  the real 11 discrete jacks: front-panel Hi-Z and headphone (`Bottom`), and
+  rear-panel (`Top`) Mic/Line 1–2 combo inputs, Monitor L/R, Line Out 3/4,
+  optical, Thunderbolt, and 12VDC power — with column/row layout from the Apollo
+  Twin X Hardware Manual.

.claude/commands/io-enrich.md

@@ -0,0 +1,147 @@
+---
+description: Correct and enrich a hardware entry's I/O from authoritative sources (manuals, photos)
+---
+
+Fix and enrich the `io` (input/output ports) of one hardware entry using
+authoritative sources, then validate and summarize with citations. This is the
+manual/agentic pass that bulk import cannot do reliably — port layout is visual
+and combine/split errors are common (see issue #212).
+
+**Argument:** an optional hardware slug (filename without `.yaml`). If omitted,
+pick the highest-priority target from the triage report.
+
+## Before starting
+
+Read these once so you follow the conventions exactly:
+
+- `schema/CONTEXT.md` → "IO Fields (Hardware)" (valid signalFlow, category,
+  position, types, connections, and the columnPosition/rowPosition convention).
+- `CLAUDE.md` → the IO field-formatting section (field order, one entry per
+  physical jack, passive-speaker `speaker-level` rule, connectorDetail).
+
+Core rules that drive everything below:
+
+- **One `io` entry per physical jack**, each `maxConnections: 1`. Never collapse
+  an L/R or numbered pair ("Outputs 1/2", "Analog In L/R") into one entry, and
+  never split a single jack into two. This is the #1 import defect.
+- `type` is the signal characteristic (line, instrument, mic, expression, usb…);
+  `connection` is the physical connector (1/4-inch, xlr, usb-c, 5-pin din…).
+  Don't swap them. Note software-switchable levels in the port `description`.
+- `position` is the device edge the jack sits on (Top = rear edge, Bottom =
+  front, Left/Right = sides). `columnPosition`/`rowPosition` order jacks within
+  that edge (left→right / top→bottom, viewing the face head-on).
+
+## Phase 1 — Select the target and read current state
+
+1. If a slug was given, use `data/hardware/<slug>.yaml`. Otherwise run
+   `pnpm io-quality` and take the top of the **Correctness** worklist (or ask
+   the user which list — correctness, missing-I/O, or spatial — to work).
+2. Read the current entry: its `name`, `url`, `manufacturer`, `primaryCategory`,
+   and existing `io`. Note what looks wrong (collapsed pairs, uniform guessed
+   positions, missing jacks, no column/row).
+
+## Phase 2 — Gather authoritative sources
+
+Prefer primary sources; marketing/retailer copy is a cross-check only.
+
+1. **Manufacturer manual / quick-reference guide (best source).** From the
+   product `url`, find the vendor's downloads/support page and locate the User
+   Manual or Quick Reference Guide **PDF**. Download it to an explicit scratchpad
+   file and open that with the Read tool — the panel/connections diagrams are the
+   ground truth for the jack set AND their physical layout:
+
+   ```bash
+   curl --fail --show-error --location \
+     -o "$SCRATCHPAD/<slug>-manual.pdf" "<manual-url>"
+   ```
+
+   Use `--fail` so an HTTP error stops here instead of silently saving an error
+   page that Read would then open as a bogus "PDF". Confirm it really is a PDF
+   (`file <path>`) before reading. If the download fails, find another source —
+   never fall back to guessing the layout from memory.
+   - **Check every panel, not just the rear.** Manuals have separate Front / Rear
+     / Side / Top panel sections. Missing inputs almost always mean a panel was
+     overlooked (e.g. the Apollo Twin X's Hi-Z and headphone jacks are on the
+     *front*). Read each panel section before concluding the set is complete.
+2. **Product photos** of the rear/side panels (for position and column/row).
+3. **Spec sheet / a retailer listing** to cross-check the jack count and
+   connector types. Note: many retailers return HTTP 403 to WebFetch — don't
+   rely on them for layout; use them only to corroborate the set.
+
+Record the source URLs you actually used — they go in the summary.
+
+## Phase 3 — Build the corrected `io`
+
+`io` is for **connectors only**. Exclude non-port controls that appear on the
+same panel — power switches, Kensington/security slots, ground screws, vent, and
+built-in mics/talkback — even when the manual numbers them alongside the jacks.
+
+For every physical jack, in the manual's own left-to-right / top-to-bottom order:
+
+- `name` (use the panel label), `signalFlow`, `category`, `type`, `connection`,
+  `connectorDetail` (if known, e.g. TS/TRS/center-positive), `maxConnections: 1`,
+  `position`, then `columnPosition`/`rowPosition` when the layout is visible.
+- Add a `description` for anything non-obvious (switchable level, insert/dual
+  role, phantom power, etc.).
+- Field order: name, signalFlow, category, type, connection, connectorDetail,
+  maxConnections, position, columnPosition, rowPosition, description.
+
+Assign `columnPosition`/`rowPosition` only for edges whose layout you can
+actually see. Grids (e.g. stacked in/out pairs) share a column and differ by
+row; a single row uses `rowPosition: 1`. If you can't see an edge's layout,
+set `position` and leave column/row off rather than guessing.
+
+## Phase 4 — Verify (do not skip)
+
+- **Count/labels:** confirm the jack set against at least two sources.
+- **Positions are visual — be adversarial.** For each jack ask "does the diagram
+  actually show it on this face?" If a jack is drawn in a separate/perspective
+  view or a source is ambiguous (a classic case: MIDI jacks that turn out to be
+  on a side, not the rear), find a clearer source or **ask the user** — never
+  invent Top/Bottom/Left/Right or column/row.
+- Track a confidence level and citation for the set, the positions, and the
+  column/row so the summary is honest about what's verified vs inferred.
+
+## Phase 5 — Apply, format, validate
+
+1. Edit only the `io:` block of the YAML, preserving the rest of the file. A
+   brief comment above `io:` describing the panel layout is welcome.
+2. `npx prettier --write data/hardware/<slug>.yaml` then `pnpm validate`.
+3. Fix any errors and re-run. There must be no new advisory warnings for this
+   file — especially **W128** (combine), **W120** (unknown type), **W121**
+   (unknown connection). Add genuinely-new connector/type values to the schema
+   YAML via the same PR only when you've confirmed they're valid.
+4. Optional: `pnpm build` and query `hardware_io` to confirm the rows land.
+
+For just column/row on an already-correct entry, `pnpm enrich-io <slug>` is the
+interactive shortcut instead of hand-editing.
+
+## Phase 6 — Summarize
+
+Report:
+
+- **Before → after**: jacks added/removed/split, position/type corrections,
+  column/row added.
+- **Sources** actually used (URLs).
+- **Confidence** per dimension and **anything you flagged for the user** to
+  confirm (e.g. an ambiguous jack face).
+- Validation results (format/validate pass, warning check).
+
+Then offer to `/ship` (create changeset + PR) or, for a batch, move to the next
+target from `pnpm io-quality`.
+
+## Batch mode
+
+To work several at once, iterate the `pnpm io-quality` worklist one device at a
+time — each through Phases 2–5 with its own verification. Do **not** bulk-guess
+positions across many devices from a single template; every device's layout is
+its own visual fact. Log any device you skip (e.g. no manual found) so coverage
+isn't silently overstated.
+
+## Worked example
+
+The Eventide H90 (`eventide-audio-h90-harmonizer`) is the reference: 14 discrete
+rear-edge jacks with Inputs/Outputs as 2×2 column/row grids, plus MIDI In and
+Out/Thru on the **Left** side — the jack set and rear layout came from the H90
+Quick Reference Guide PDF, and the MIDI side was confirmed with the user rather
+than guessed from the ambiguous diagram.

data/hardware/universal-audio-apollo-twin-x.yaml

@@ -33,48 +33,131 @@ specs: |-
   - Thunderbolt 3 port
   - Talkback microphone
 io:
-  - name: Optical Toslink Input
+  # Front-panel jacks are on the Bottom edge (Hi-Z instrument left, headphone
+  # right); everything else is on the rear (Top edge). Layout and connector
+  # types are from the Apollo Twin X Hardware Manual front/rear panel diagrams.
+  - name: Hi-Z Instrument Input
+    signalFlow: input
+    category: audio
+    type: instrument
+    connection: 1/4-inch
+    connectorDetail:
+      - TS
+    maxConnections: 1
+    position: Bottom
+    columnPosition: 1
+    rowPosition: 1
+    description: Front panel. Accepts a 1/4" mono TS plug only; overrides the
+      channel 1 mic/line input.
+  - name: Headphone Output
+    signalFlow: output
+    category: audio
+    type: headphone
+    connection: 1/4-inch
+    connectorDetail:
+      - TRS
+    maxConnections: 1
+    position: Bottom
+    columnPosition: 2
+    rowPosition: 1
+    description: Front panel.
+  - name: Optical Input
     signalFlow: input
     category: digital
-    type: s/pdif
+    type: adat
     connection: toslink
     maxConnections: 1
     position: Top
-  - name: Two 1/4" Monitor Outs
+    columnPosition: 1
+    rowPosition: 1
+    description: Optical TOSLINK carrying ADAT or S/PDIF, switchable in software.
+  - name: Thunderbolt 3
+    signalFlow: bidirectional
+    category: digital
+    type: thunderbolt
+    connection: thunderbolt 3
+    maxConnections: 1
+    position: Top
+    columnPosition: 2
+    rowPosition: 1
+  - name: Power Supply Input
+    signalFlow: input
+    category: power
+    type: power
+    connection: barrel
+    connectorDetail:
+      - center-positive
+    maxConnections: 1
+    position: Top
+    columnPosition: 2
+    rowPosition: 2
+    description: 12VDC locking barrel connector; the unit is not bus-powered.
+  - name: Line Output 3
     signalFlow: output
     category: audio
     type: line
     connection: 1/4-inch
+    connectorDetail:
+      - TRS
     maxConnections: 1
     position: Top
-  - name: Two 1/4" Line Outs (Alt)
+    columnPosition: 3
+    rowPosition: 1
+  - name: Line Output 4
     signalFlow: output
     category: audio
     type: line
     connection: 1/4-inch
+    connectorDetail:
+      - TRS
     maxConnections: 1
     position: Top
-  - name: 1/4" Trs Headphone Out
+    columnPosition: 3
+    rowPosition: 2
+  - name: Monitor Output L
     signalFlow: output
     category: audio
-    type: headphone
+    type: line
     connection: 1/4-inch
+    connectorDetail:
+      - TRS
     maxConnections: 1
     position: Top
-  - name: Thunderbolt 3
+    columnPosition: 4
+    rowPosition: 1
+  - name: Monitor Output R
+    signalFlow: output
+    category: audio
+    type: line
+    connection: 1/4-inch
+    connectorDetail:
+      - TRS
+    maxConnections: 1
+    position: Top
+    columnPosition: 4
+    rowPosition: 2
+  - name: Mic/Line Input 2
     signalFlow: input
-    category: digital
-    type: thunderbolt
-    connection: thunderbolt 3
+    category: audio
+    type: mic
+    connection: combo jack
     maxConnections: 1
     position: Top
-  - name: Thunderbolt 3
-    signalFlow: output
-    category: digital
-    type: thunderbolt
-    connection: thunderbolt 3
+    columnPosition: 5
+    rowPosition: 1
+    description: Combo XLR (mic) / 1/4" TRS (line), switchable; +48V phantom
+      power and a 75 Hz low-cut are available.
+  - name: Mic/Line Input 1
+    signalFlow: input
+    category: audio
+    type: mic
+    connection: combo jack
     maxConnections: 1
     position: Top
+    columnPosition: 6
+    rowPosition: 1
+    description: Combo XLR (mic) / 1/4" TRS (line), switchable; +48V phantom
+      power and a 75 Hz low-cut are available.
 prices:
   - amount: 1199
     currency: USD