From dad59e0f32930cf913fb1df39965eb077f8cf795 Mon Sep 17 00:00:00 2001 From: Jeffrey Louden Date: Sat, 11 Jul 2026 22:26:44 -0400 Subject: [PATCH 1/2] Add /io-enrich command (Pillar 2) + correct Apollo Twin X I/O Follow-up to #212. Adds the enrichment pipeline that works down the io-quality worklist using authoritative sources. - .claude/commands/io-enrich.md: manual-first, verify-don't-guess process for fixing/enriching a hardware entry's io (one entry per physical jack; positions and column/row from the manual's panel diagrams; adversarial verification). - Pilot: rewrite Universal Audio Apollo Twin X io from 6 broken entries (collapsed output pairs, split Thunderbolt, missing all inputs, uniform Top) to 11 discrete jacks with correct front/rear positions and column/row layout, sourced from the Apollo Twin X Hardware Manual. Co-Authored-By: Claude Opus 4.8 (1M context) --- .changeset/io-enrich-command.md | 21 +++ .claude/commands/io-enrich.md | 137 ++++++++++++++++++ .../universal-audio-apollo-twin-x.yaml | 113 +++++++++++++-- 3 files changed, 256 insertions(+), 15 deletions(-) create mode 100644 .changeset/io-enrich-command.md create mode 100644 .claude/commands/io-enrich.md diff --git a/.changeset/io-enrich-command.md b/.changeset/io-enrich-command.md new file mode 100644 index 000000000..0b3e114ba --- /dev/null +++ b/.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. diff --git a/.claude/commands/io-enrich.md b/.claude/commands/io-enrich.md new file mode 100644 index 000000000..bd3a9476e --- /dev/null +++ b/.claude/commands/io-enrich.md @@ -0,0 +1,137 @@ +--- +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/.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 the scratchpad with + `curl -sL` and open it with the Read tool — the panel/connections diagrams are + the ground truth for the jack set AND their physical layout. + - **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/.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 ` 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. diff --git a/data/hardware/universal-audio-apollo-twin-x.yaml b/data/hardware/universal-audio-apollo-twin-x.yaml index b06aa38f1..165ec105b 100644 --- a/data/hardware/universal-audio-apollo-twin-x.yaml +++ b/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: Thunderbolt 3 + signalFlow: bidirectional category: digital - type: s/pdif + type: thunderbolt + connection: thunderbolt 3 + maxConnections: 1 + position: Top + columnPosition: 1 + rowPosition: 1 + - name: Optical Input + signalFlow: input + category: digital + type: adat connection: toslink maxConnections: 1 position: Top - - name: Two 1/4" Monitor Outs + columnPosition: 1 + rowPosition: 2 + description: Optical TOSLINK carrying ADAT or S/PDIF, switchable in software. + - name: Power Supply Input + signalFlow: input + category: power + type: power + connection: barrel + connectorDetail: + - center-positive + maxConnections: 1 + position: Top + columnPosition: 2 + rowPosition: 1 + 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 From 773d80aa00dd9ece519a47026c9214eeff65ddcf Mon Sep 17 00:00:00 2001 From: Jeffrey Louden Date: Sun, 12 Jul 2026 08:38:05 -0400 Subject: [PATCH 2/2] Fix Apollo Twin X rear left-cluster grid; harden manual download - Apollo Twin X: the rear panel's left cluster is a 2x2 grid, not a vertical stack. Per the Hardware Manual diagram, OPTICAL IN is top-left with the Thunderbolt port to its right, and the 12VDC barrel sits below Thunderbolt. Reorder Optical before Thunderbolt and set Optical (1,1), Thunderbolt (2,1), Power (2,2). The margin callout numbering (22/21/20) was misread as a stack. - /io-enrich: download manuals with `curl --fail --show-error --location` to an explicit scratchpad path so an HTTP error stops the workflow instead of saving an error page that Read would open as a bogus PDF. Co-Authored-By: Claude Opus 4.8 (1M context) --- .claude/commands/io-enrich.md | 16 +++++++++++--- .../universal-audio-apollo-twin-x.yaml | 22 +++++++++---------- 2 files changed, 24 insertions(+), 14 deletions(-) diff --git a/.claude/commands/io-enrich.md b/.claude/commands/io-enrich.md index bd3a9476e..45f643ae9 100644 --- a/.claude/commands/io-enrich.md +++ b/.claude/commands/io-enrich.md @@ -46,9 +46,19 @@ 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 the scratchpad with - `curl -sL` and open it with the Read tool — the panel/connections diagrams are - the ground truth for the jack set AND their physical layout. + 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/-manual.pdf" "" + ``` + + 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 `) 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 diff --git a/data/hardware/universal-audio-apollo-twin-x.yaml b/data/hardware/universal-audio-apollo-twin-x.yaml index 165ec105b..a4aec5d89 100644 --- a/data/hardware/universal-audio-apollo-twin-x.yaml +++ b/data/hardware/universal-audio-apollo-twin-x.yaml @@ -61,15 +61,6 @@ io: columnPosition: 2 rowPosition: 1 description: Front panel. - - name: Thunderbolt 3 - signalFlow: bidirectional - category: digital - type: thunderbolt - connection: thunderbolt 3 - maxConnections: 1 - position: Top - columnPosition: 1 - rowPosition: 1 - name: Optical Input signalFlow: input category: digital @@ -78,8 +69,17 @@ io: maxConnections: 1 position: Top columnPosition: 1 - rowPosition: 2 + 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 @@ -90,7 +90,7 @@ io: maxConnections: 1 position: Top columnPosition: 2 - rowPosition: 1 + rowPosition: 2 description: 12VDC locking barrel connector; the unit is not bus-powered. - name: Line Output 3 signalFlow: output