Add IO position enrichment tool + backfill Eventide H90 (#212)

.changeset/io-positions-enrichment.md

@@ -0,0 +1,20 @@
+---
+"catalog": minor
+---
+
+Add IO port positioning (`columnPosition` / `rowPosition`) enrichment.
+
+Starts issue #212: IO ports can now carry `columnPosition` (left-to-right) and
+`rowPosition` (top-to-bottom) values describing their spatial arrangement on a
+device edge, so the setup graph can render port layouts accurately. The schema
+already accepted these fields; this adds the convention, tooling, and first data.
+
+- New `pnpm enrich-io <slug>` interactive tool to assign column/row positions to a
+  hardware entry's IO ports, writing back to YAML while preserving formatting.
+- Document the ordering convention in `schema/CONTEXT.md` (via the generator) and
+  `CLAUDE.md`.
+- Fully correct and backfill the Eventide H90 Harmonizer as the validation case:
+  its IO now lists all 14 discrete rear-panel jacks (Inputs 1–4, Outputs 1–4,
+  Exp/Ctl 1–2, MIDI In, MIDI Out/Thru, USB-C, Power) with column/row positions,
+  replacing an incomplete 5-entry list that omitted the audio I/O and MIDI Out and
+  mis-positioned the jacks.

CLAUDE.md

@@ -117,6 +117,20 @@ preamp/mixer outputs; a powered speaker input is never `line`.
 (guitars/basses), `position`. Every product entry must include `primaryCategory`.
 These are enforced by `pnpm validate`, not just review.
 
+**Port ordering (optional):** `columnPosition` and `rowPosition` place a port
+within its `position` edge so the setup graph can render the layout. Both are
+1-based, numbered independently per edge, and go right after `position`:
+`columnPosition` is left-to-right (column 1 = leftmost, viewing that face
+head-on); `rowPosition` is top-to-bottom (row 1 = topmost). Stacked ports share a
+`columnPosition` and differ by `rowPosition`; a single-row edge uses
+`rowPosition: 1`. This is visual info from photos/manuals — assign it with
+`pnpm enrich-io <slug>`, not during bulk import.
+
+One `io` entry per **physical** jack (`maxConnections: 1`). Do not collapse an L/R
+pair into one stereo entry with `maxConnections: 2`, and do not split one jack in
+two — bulk imports get this wrong. E.g. the Eventide H90 has 14 discrete jacks
+(Inputs 1–4, Outputs 1–4, Exp/Ctl 1–2, MIDI In, MIDI Out/Thru, USB-C, Power).
+
 ## Content Entries
 
 Content entries (presets, sample packs, expansions) live in `data/content/` as a separate collection. Content `primaryCategory` values include `preset`, `preset-pack`, `sample-pack`, `drum-sample-pack`, `loop-pack`, `sound-library`, `soundfont`, `impulse-response`, and `multisample`.

data/hardware/eventide-audio-h90-harmonizer.yaml

@@ -7,41 +7,174 @@ description: A next-generation multi-effects powerhouse with 74 algorithms and
   comprehensive I/O, designed for guitar, bass, synths, and more, offering
   flexible routing and extensive sound possibilities.
 io:
-  - name: Expression Input 1
+  # Most jacks are on the rear (Top) edge: Inputs and Outputs in 2x2 grids
+  # (columns left-to-right, rows top-to-bottom), then Exp/Ctl, USB-C, and Power
+  # in a single row to their right. The MIDI In and Out/Thru jacks are on the
+  # Left side of the pedal. See the H90 Quick Reference Guide.
+  # Audio jacks are 1/4-inch TS; each in/out can be toggled between instrument
+  # and line level in the H90 software (the rear-panel "Line Lvl" LEDs indicate
+  # the current setting). `type` records the typical default; the toggle is noted
+  # in each port's description.
+  - name: Input 1
     signalFlow: input
     category: audio
-    type: cv/gate
+    type: instrument
     connection: 1/4-inch
+    connectorDetail:
+      - TS
     maxConnections: 1
-    position: Bottom
-  - name: Expression Input 2
+    position: Top
+    columnPosition: 1
+    rowPosition: 1
+    description: Instrument or line level, switchable in software.
+  - name: Input 2
     signalFlow: input
     category: audio
-    type: cv/gate
+    type: instrument
     connection: 1/4-inch
+    connectorDetail:
+      - TS
     maxConnections: 1
-    position: Bottom
-  - name: MIDI in
+    position: Top
+    columnPosition: 1
+    rowPosition: 2
+    description: Instrument or line level, switchable in software.
+  - name: Input 3 (Insert Return / Dual Path 2)
     signalFlow: input
-    category: midi
-    type: midi
-    connection: 5-pin din
+    category: audio
+    type: instrument
+    connection: 1/4-inch
+    connectorDetail:
+      - TS
     maxConnections: 1
-    position: Bottom
-  - name: USB Control
+    position: Top
+    columnPosition: 2
+    rowPosition: 1
+    description: Insert return or Dual Path 2 input. Instrument or line level,
+      switchable in software.
+  - name: Input 4 (Insert Return / Dual Path 2)
     signalFlow: input
+    category: audio
+    type: instrument
+    connection: 1/4-inch
+    connectorDetail:
+      - TS
+    maxConnections: 1
+    position: Top
+    columnPosition: 2
+    rowPosition: 2
+    description: Insert return or Dual Path 2 input. Instrument or line level,
+      switchable in software.
+  - name: Output 1
+    signalFlow: output
+    category: audio
+    type: line
+    connection: 1/4-inch
+    connectorDetail:
+      - TS
+    maxConnections: 1
+    position: Top
+    columnPosition: 3
+    rowPosition: 1
+    description: Instrument or line level, switchable in software.
+  - name: Output 2
+    signalFlow: output
+    category: audio
+    type: line
+    connection: 1/4-inch
+    connectorDetail:
+      - TS
+    maxConnections: 1
+    position: Top
+    columnPosition: 3
+    rowPosition: 2
+    description: Instrument or line level, switchable in software.
+  - name: Output 3 (Insert Send / Dual Path 2)
+    signalFlow: output
+    category: audio
+    type: line
+    connection: 1/4-inch
+    connectorDetail:
+      - TS
+    maxConnections: 1
+    position: Top
+    columnPosition: 4
+    rowPosition: 1
+    description: Insert send or Dual Path 2 output. Instrument or line level,
+      switchable in software.
+  - name: Output 4 (Insert Send / Dual Path 2)
+    signalFlow: output
+    category: audio
+    type: line
+    connection: 1/4-inch
+    connectorDetail:
+      - TS
+    maxConnections: 1
+    position: Top
+    columnPosition: 4
+    rowPosition: 2
+    description: Insert send or Dual Path 2 output. Instrument or line level,
+      switchable in software.
+  - name: Exp/Ctl 1
+    signalFlow: input
+    category: audio
+    type: expression
+    connection: 1/4-inch
+    connectorDetail:
+      - TRS
+    maxConnections: 1
+    position: Top
+    columnPosition: 5
+    rowPosition: 1
+  - name: Exp/Ctl 2
+    signalFlow: input
+    category: audio
+    type: expression
+    connection: 1/4-inch
+    connectorDetail:
+      - TRS
+    maxConnections: 1
+    position: Top
+    columnPosition: 5
+    rowPosition: 2
+  - name: USB-C
+    signalFlow: bidirectional
     category: digital
     type: usb
     connection: usb-c
     maxConnections: 1
-    position: Bottom
-  - name: Power Input
+    position: Top
+    columnPosition: 6
+    rowPosition: 1
+  - name: Power
     signalFlow: input
     category: power
     type: power
     connection: barrel
+    connectorDetail:
+      - center-positive
+    maxConnections: 1
+    position: Top
+    columnPosition: 7
+    rowPosition: 1
+  - name: MIDI In
+    signalFlow: input
+    category: midi
+    type: midi
+    connection: 5-pin din
+    maxConnections: 1
+    position: Left
+    columnPosition: 1
+    rowPosition: 1
+  - name: MIDI Out/Thru
+    signalFlow: output
+    category: midi
+    type: midi
+    connection: 5-pin din
     maxConnections: 1
-    position: Bottom
+    position: Left
+    columnPosition: 2
+    rowPosition: 1
 specs: |-
   - 74 professional algorithms
   - Dual algorithm design

package.json

@@ -15,6 +15,7 @@
     "version": "changeset version",
     "release": "changeset publish",
     "assign-ids": "tsx scripts/assign-ids.ts",
+    "enrich-io": "tsx scripts/enrich-io.ts",
     "format": "tsx scripts/format-yaml.ts",
     "format:check": "prettier --check \"data/**/*.yaml\"",
     "validate-urls": "tsx scripts/validate-urls.ts",

schema/CONTEXT.md

@@ -782,6 +782,21 @@ Accessory entries (cables, stands, acoustic treatment) live in `data/accessories
 **Aliases:**
 
 
+### Port Ordering: columnPosition / rowPosition (optional)
+
+`columnPosition` and `rowPosition` describe the spatial arrangement of ports
+**within a single `position` edge**, so the setup graph can render port layouts
+accurately. Both are optional 1-based integers; numbering is independent per edge.
+
+- `columnPosition`: left-to-right order, viewing that face head-on. Column 1 = leftmost.
+- `rowPosition`: top-to-bottom order, viewing that face head-on. Row 1 = topmost.
+- Ports stacked vertically share a `columnPosition` and differ by `rowPosition`.
+  A single-row edge uses `rowPosition: 1` on every port.
+- Place `columnPosition`/`rowPosition` immediately after `position`.
+
+These are visual/spatial values best read off product photos or the manufacturer's
+rear-panel diagram — assign them with `pnpm enrich-io <slug>`, not during bulk import.
+
 ### IO Types (advisory — unknown values produce warnings)
 
 - `line`