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..45f643ae9 --- /dev/null +++ b/.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/.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/-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 + *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..a4aec5d89 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: 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