@protoboardai/ext-hardware 0.0.0-stage → 0.2.0

package/evals/e2e-desk-rover/solution/desk-rover.uhd.ts

@@ -0,0 +1,60 @@
+import type { InterfaceLink, ModuleDef } from "@deltarobotics/uhd";
+
+/**
+ * Desk rover sensor bench (docs/brief.md): an Arduino UNO R3 with the
+ * Adafruit Motor Shield V2 stacked on its headers, and a VL53L4CD breakout
+ * on the shared I2C bus, powered from the UNO's 5 V pin. Powered from the
+ * UNO's USB port (R5); the UNO's VIN and DC jack and the shield's VIN and
+ * motor terminal are marked unconnected on purpose (R5), so check reports
+ * them as info and the test plan does not power them.
+ */
+const link = (id: string, name: string, a: [string, string], b: [string, string], extra: Partial<InterfaceLink> = {}): InterfaceLink => ({
+  id,
+  name,
+  a: { child: a[0], interfaceId: a[1] },
+  b: { child: b[0], interfaceId: b[1] },
+  ...extra,
+});
+
+export const DESK_ROVER: ModuleDef = {
+  id: "desk-rover",
+  name: "Desk rover sensor bench",
+  kind: "module",
+  version: "0.1.0",
+  description: "Arduino UNO R3 with an Adafruit Motor Shield V2 stacked on it and an Adafruit VL53L4CD time-of-flight breakout on the I2C bus; a desk rig for the rover's obstacle detection.",
+  interfaces: [],
+  children: [
+    {
+      id: "uno",
+      moduleDefId: "arduino-uno-rev3",
+      name: "Arduino UNO R3",
+      unconnected: [
+        { interfaceId: "vin", reason: "the bench runs from the UNO's USB port (R5)" },
+        { interfaceId: "dc_jack", reason: "the bench runs from the UNO's USB port (R5)" },
+      ],
+    },
+    {
+      id: "shield",
+      moduleDefId: "adafruit-1438-motor-shield-v2",
+      name: "Motor shield",
+      unconnected: [
+        { interfaceId: "arduino_vin", reason: "VIN jumper not fitted: the motors get their own supply" },
+        { interfaceId: "vmotor_in", reason: "stays unconnected until the rover's battery is chosen (R5)" },
+      ],
+    },
+    { id: "tof", moduleDefId: "adafruit-5396-vl53l4cd", name: "ToF sensor" },
+  ],
+  links: [
+    // R1: the shield stacks on the UNO's headers (11 mm stack height assumed, as in examples/uno-motor-bench)
+    link("shield_mount", "Shield on the UNO's headers", ["uno", "mount"], ["shield", "mount"], { mate: { gapMm: 11 } }),
+    link("shield_i2c", "Shield I2C", ["uno", "i2c"], ["shield", "i2c"]),
+    // R2: the shield's logic power from the UNO's headers
+    link("shield_5v", "Shield 5V", ["uno", "5v"], ["shield", "arduino_5v"]),
+    link("shield_ioref", "Shield IOREF", ["uno", "ioref"], ["shield", "arduino_ioref"]),
+    link("shield_gnd", "Shield GND", ["uno", "gnd_1"], ["shield", "arduino_gnd"]),
+    // R3: the sensor on the I2C bus, 5 V from the UNO, common ground
+    link("tof_i2c", "ToF I2C", ["uno", "i2c"], ["tof", "i2c"]),
+    link("tof_power", "ToF 5V", ["uno", "5v"], ["tof", "vin"]),
+    link("tof_gnd", "ToF GND", ["uno", "gnd_2"], ["tof", "gnd"]),
+  ],
+};

package/evals/find-reversed-cell-leads/case.json

@@ -0,0 +1,78 @@
+{
+  "schema": "protoboard.eval-case/v0",
+  "title": "Find the cell leads soldered the wrong way round, with the scenario that describes it hidden",
+  "skills": ["system-compose", "system-review", "harness-author"],
+  "tags": ["fault", "system", "hidden-seed", "harder"],
+  "fixture": {
+    "from": "../../../../examples/smart-bottle",
+    "exclude": ["release", "docs"],
+    "steps": [
+      {
+        "note": "the seed is hidden: the scenario that describes it is taken out of src/scenarios.ts, and the datasheets (docs/, which list the scenarios) are not copied, so the agent has to find the fault, not match it to a scenario",
+        "replace": { "file": "src/scenarios.ts", "find": "  {\n    id: \"cell-leads-reversed\",\n    label: \"Cell leads soldered the wrong way round\",\n    description: \"The red lead goes to BAT- and the black lead to BAT+.\",\n    expect: [\"UHD_LINK_STATE\"],\n    system: recompose(SMART_BOTTLE, \"bat_pads\", { p1: \"bat_neg\", p2: \"bat_pos\" }),\n  },\n", "with": "", "count": 1 }
+      },
+      {
+        "note": "the fault of the (removed) cell-leads-reversed scenario, applied to the system itself. With PB-869 merged check reports it as UHD_LINK_STATE on the battery pads, beside the battery leads' route being stale",
+        "replace": { "file": "src/bottle.uhd.ts", "find": "compose: { p1: \"bat_pos\", p2: \"bat_neg\" }", "with": "compose: { p1: \"bat_neg\", p2: \"bat_pos\" }", "count": 1 }
+      }
+    ]
+  },
+  "instruction": "During a rework of the smart bottle's cap, the cell's leads were unsoldered from the cap board and soldered back on, and the system model (src/bottle.uhd.ts) was updated to match the bench. Since then the cap does not power on. Find what is wrong in the system model and fix it so the model describes a cap that works; then say in one or two sentences what the fault was and how you found it. The board, the parts, the harness modules, their routed geometry and the scenarios are correct; do not change them.",
+  "tools": { "read": true, "edit": true, "commands": ["npx protoboard *", "npx tsx node_modules/@protoboardai/ext-hardware/skills/*"] },
+  "budget": { "turns": 30, "seconds": 900, "usd": 4 },
+  "graders": [
+    {
+      "id": "fault-fixed-and-named",
+      "kind": "fault",
+      "code": "UHD_LINK_STATE",
+      "subject": "bat",
+      "seeded": ["HARNESS_ROUTE_STALE"],
+      "caught": "(revers|swap|backward|wrong way|polarity|crossed|flipped)",
+      "description": "check reports reversed 2-pin pads (PB-869): the fault is UHD_LINK_STATE on the battery pads, with the battery leads' route stale (subject /bat/, so an unrelated link-state warning elsewhere does not count), and it must be gone. The answer names the reversal"
+    },
+    {
+      "id": "check-clean",
+      "kind": "check",
+      "maxErrors": 0,
+      "ran": ["uhd/checkSystem", "ext:@protoboardai/ext-harness-cad/routes"],
+      "diagnostics": [
+        { "code": "HARNESS_ROUTE_STALE", "subject": "battery", "present": false },
+        { "code": "UHD_LINK_STATE", "subject": "bat", "present": false }
+      ]
+    },
+    {
+      "id": "leads-restored",
+      "kind": "facts",
+      "definition": "smart-bottle",
+      "facts": [
+        { "path": "links[id=bat_pads].b.child", "equals": "board" },
+        { "path": "links[id=bat_pads].b.interfaceId", "equals": "bat_pads" },
+        { "path": "links[id=bat_pads].b.compose.p1", "equals": "bat_pos" },
+        { "path": "links[id=bat_pads].b.compose.p2", "equals": "bat_neg" }
+      ],
+      "description": "the red lead (p1) on BAT+, the black lead (p2) on BAT-, in the link the cell-leads-reversed scenario recomposes"
+    },
+    {
+      "id": "scenarios-hold",
+      "kind": "script",
+      "script": "skills/system-compose/scripts/scenarios.ts",
+      "args": ["--json"],
+      "facts": [
+        { "path": "[id=nominal].ok", "equals": true },
+        { "path": "[id=probe-dq-on-gnd-pad].ok", "equals": true },
+        { "path": "[id=module-on-vbus].ok", "equals": true }
+      ],
+      "description": "the nominal build is clean and the other scenarios are still caught (the exit code is not graded: the cell-leads-reversed scenario is taken out of the fixture)"
+    },
+    { "id": "route-untouched", "kind": "digest", "file": "src/harnesses/bottle-battery-leads/out/body.manifest.json", "changed": false, "description": "regenerating the route would hide the symptom, not fix the fault" },
+    { "id": "board-untouched", "kind": "digest", "file": "src/boards/bottle-cap/bottle-cap.uhd.ts", "changed": false },
+    { "id": "harnesses-untouched", "kind": "digest", "file": "src/harnesses/harnesses.uhd.ts", "changed": false },
+    { "id": "scenarios-untouched", "kind": "digest", "file": "src/scenarios.ts", "changed": false }
+  ],
+  "solution": [
+    { "protoboard": ["check"], "expect": { "exit": 1 } },
+    { "replace": { "file": "src/bottle.uhd.ts", "find": "compose: { p1: \"bat_neg\", p2: \"bat_pos\" }", "with": "compose: { p1: \"bat_pos\", p2: \"bat_neg\" }", "count": 1 } },
+    { "protoboard": ["check"] },
+    { "say": "The cell's leads were reversed on the board's BAT pads: link bat_pads put the red lead (p1) on bat_neg and the black lead (p2) on bat_pos. check reported UHD_LINK_STATE on bat_pads (no compatible protocol/role between cell:lead_pos and board:bat_neg) and that the battery leads' route was generated for different ends; the route was right and the compose was wrong, so I put p1 back on bat_pos and p2 on bat_neg, and the route is current again." }
+  ]
+}

package/evals/fix-gnss-uart-swap/case.json

@@ -0,0 +1,32 @@
+{
+  "schema": "protoboard.eval-case/v0",
+  "title": "Find and fix a GNSS lead soldered with RX and TX swapped",
+  "skills": ["system-compose", "system-review"],
+  "tags": ["fault", "system"],
+  "fixture": {
+    "from": "../../../../examples/quadcopter-5in",
+    "exclude": ["docs"],
+    "steps": [
+      {
+        "note": "the gnss-rx-tx-swapped scenario (src/scenarios.ts), applied to the system itself",
+        "replace": { "file": "src/quadcopter.uhd.ts", "find": "p2: \"fc:uart1_tx\", p3: \"fc:uart1_rx\"", "with": "p2: \"fc:uart1_rx\", p3: \"fc:uart1_tx\"", "count": 1 }
+      }
+    ]
+  },
+  "instruction": "`npx protoboard check` reports an error on this quadcopter since the GNSS lead was re-soldered to the flight controller. Find what is wrong, fix the system model so that check reports no errors, and say in one or two sentences what the fault was. The purchased parts' definitions are correct; do not edit anything under parts/.",
+  "tools": { "read": true, "edit": true, "commands": ["npx protoboard *", "npx tsx node_modules/@protoboardai/ext-hardware/skills/*"] },
+  "budget": { "turns": 20, "seconds": 600, "usd": 2 },
+  "graders": [
+    { "id": "fault-fixed-and-named", "kind": "fault", "code": "UHD_LINK_STATE", "caught": "(rx|tx|receive|transmit)[^.]*(swap|revers|cross|wrong|backward)|(swap|revers|cross)[^.]*(rx|tx)" },
+    { "id": "check-clean", "kind": "check", "maxErrors": 0, "ran": ["uhd/checkSystem"] },
+    { "id": "pads-restored", "kind": "text", "file": "src/quadcopter.uhd.ts", "matches": ["p2:\\s*\"fc:uart1_tx\",\\s*p3:\\s*\"fc:uart1_rx\""], "description": "the soldered end is back on the pads the lead was built for: p2 on TX1, p3 on RX1" },
+    { "id": "gnss-part-untouched", "kind": "digest", "file": "parts/catalog/matek-m9n-5883.json", "changed": false },
+    { "id": "fc-part-untouched", "kind": "digest", "file": "parts/catalog/dolphinrc-f405-v3-flight-controller.json", "changed": false }
+  ],
+  "solution": [
+    { "protoboard": ["check"], "expect": { "exit": 1 } },
+    { "replace": { "file": "src/quadcopter.uhd.ts", "find": "p2: \"fc:uart1_rx\", p3: \"fc:uart1_tx\"", "with": "p2: \"fc:uart1_tx\", p3: \"fc:uart1_rx\"", "count": 1 } },
+    { "protoboard": ["check"] },
+    { "say": "The GNSS lead's soldered end had its RX and TX wires swapped on the FC's UART1 pads (p2 on RX1, p3 on TX1); I put p2 back on uart1_tx and p3 on uart1_rx, and check now reports no errors." }
+  ]
+}

package/evals/fix-two-wiring-faults/case.json

@@ -0,0 +1,97 @@
+{
+  "schema": "protoboard.eval-case/v0",
+  "title": "Find and fix two wiring faults at once: the O4 powered from the pack, and the GNSS RX and TX swapped",
+  "skills": ["system-compose", "system-review", "harness-author"],
+  "tags": ["fault", "system", "two-faults", "harder"],
+  "fixture": {
+    "from": "../../../../examples/quadcopter-5in",
+    "exclude": ["docs"],
+    "steps": [
+      {
+        "note": "the seeds are hidden: the two scenarios that describe them are taken out of src/scenarios.ts (docs/, which lists them, is not copied), so the agent has to find the faults, not match them to scenarios",
+        "replace": { "file": "src/scenarios.ts", "find": "  {\n    id: \"o4-on-vbat\",\n    label: \"O4 wired to raw 6S\",\n    description: \"The DJI O4 power lead is soldered to the battery instead of the 10 V BEC.\",\n    expect: [\"UHD_LINK_STATE\"],\n    // The cable's red wire is cut off the DJI plug and soldered to the XT60\n    // lead: positions 2-6 still mate, VCC now comes straight off the pack.\n    system: {\n      ...QUADCOPTER_5IN,\n      links: [\n        ...(QUADCOPTER_5IN.links ?? []).map((l) => (l.id === \"dji_fc\" ? { ...l, childLinks: [2, 3, 4, 5, 6].map((n) => ({ a: `p${n}`, b: `p${n}` })) } : l)),\n        { id: \"video_power\", name: \"O4 VCC on the pack\", a: { child: \"battery\", interfaceId: \"battery_out\" }, b: { child: \"video\", interfaceId: \"vcc\" }, harness: \"dji_cable\" },\n      ],\n    },\n  },\n", "with": "", "count": 1 }
+      },
+      { "replace": { "file": "src/scenarios.ts", "find": "  {\n    id: \"gnss-rx-tx-swapped\",\n    label: \"GNSS lead with RX and TX swapped\",\n    description: \"The soldered end of the GNSS lead has its RX and TX wires on the wrong pads (GNSS TX on TX1).\",\n    expect: [\"UHD_LINK_STATE\"],\n    system: recompose(QUADCOPTER_5IN, \"gnss_pads\", { p2: \"fc:uart1_rx\", p3: \"fc:uart1_tx\" }),\n  },\n", "with": "", "count": 1 } },
+      {
+        "note": "the fault of the (removed) o4-on-vbat scenario on the system itself: the 3-in-1 cable's VCC position cut off the plug, the O4's VCC soldered to the pack",
+        "replace": {
+          "file": "src/quadcopter.uhd.ts",
+          "find": "    link(\"dji_fc\", \"DJI socket\", [\"stack\", \"dji_socket\"], [\"dji_cable\", \"end_fc\"]),\n",
+          "with": "    link(\"dji_fc\", \"DJI socket\", [\"stack\", \"dji_socket\"], [\"dji_cable\", \"end_fc\"], { childLinks: [2, 3, 4, 5, 6].map((n) => ({ a: `p${n}`, b: `p${n}` })) }),\n    link(\"video_power\", \"O4 VCC\", [\"battery\", \"battery_out\"], [\"video\", \"vcc\"], { harness: \"dji_cable\" }),\n",
+          "count": 1
+        }
+      },
+      {
+        "note": "and the fault of the (removed) gnss-rx-tx-swapped scenario",
+        "replace": { "file": "src/quadcopter.uhd.ts", "find": "p2: \"fc:uart1_tx\", p3: \"fc:uart1_rx\"", "with": "p2: \"fc:uart1_rx\", p3: \"fc:uart1_tx\"", "count": 1 }
+      }
+    ]
+  },
+  "instruction": "This quadcopter came back from a bench repair: the GNSS lead was re-soldered to the flight controller, and the DJI O4's power lead was repaired. The system model (src/quadcopter.uhd.ts) was updated to match the bench, and since then `npx protoboard check` reports errors. Find everything that is wrong, fix the system model so that it describes the quad as it is meant to be built and check reports no errors, and say in a sentence or two per fault what each one was. The purchased parts' definitions and the harness modules are correct; do not edit anything under parts/ or src/harnesses/.",
+  "tools": { "read": true, "edit": true, "commands": ["npx protoboard *", "npx tsx node_modules/@protoboardai/ext-hardware/skills/*"] },
+  "budget": { "turns": 30, "seconds": 900, "usd": 4 },
+  "graders": [
+    {
+      "id": "o4-power-fixed-and-named",
+      "kind": "fault",
+      "code": "UHD_LINK_STATE",
+      "subject": "video_power|dji",
+      "caught": "(o4|air unit|video|vtx)[\\s\\S]*(battery|pack|vbat|6s|raw|xt60|25\\.2|unregulated)|(battery|pack|vbat|6s|raw|xt60)[\\s\\S]*(o4|air unit|video|vtx)"
+    },
+    {
+      "id": "gnss-fixed-and-named",
+      "kind": "fault",
+      "code": "UHD_LINK_STATE",
+      "subject": "gnss",
+      "caught": "(rx|tx|receive|transmit)[^.]*(swap|revers|cross|wrong|backward)|(swap|revers|cross)[^.]*(rx|tx)"
+    },
+    {
+      "id": "check-clean",
+      "kind": "check",
+      "maxErrors": 0,
+      "ran": ["uhd/checkSystem", "ext:@protoboardai/ext-harness-cad/routes"],
+      "diagnostics": [{ "code": "HARNESS_ROUTE_STALE", "present": false }, { "severity": "error", "message": "O4|GNSS|UART1", "present": false }]
+    },
+    {
+      "id": "wired-as-designed",
+      "kind": "facts",
+      "definition": "quadcopter-5in",
+      "facts": [
+        { "path": "links[id=video_power]", "exists": false },
+        { "path": "links[id=dji_fc].childLinks", "exists": false },
+        { "path": "links[id=dji_fc].b.child", "equals": "dji_cable" },
+        { "path": "links[id=dji_o4].b.child", "equals": "video" },
+        { "path": "links[id=gnss_pads].b.compose.p2", "equals": "fc:uart1_tx" },
+        { "path": "links[id=gnss_pads].b.compose.p3", "equals": "fc:uart1_rx" }
+      ],
+      "description": "the O4 takes its power through the 3-in-1 cable again (every position of the DJI socket, no lead to the pack), and the GNSS lead's p2 is on TX1, p3 on RX1. Re-pointing the O4 lead at another rail clears the error but is not the quad as designed"
+    },
+    {
+      "id": "scenarios-hold",
+      "kind": "script",
+      "script": "skills/system-compose/scripts/scenarios.ts",
+      "args": ["--json"],
+      "exit": 0,
+      "facts": [{ "path": "[id=nominal].ok", "equals": true }]
+    },
+    { "id": "harnesses-untouched", "kind": "digest", "file": "src/harnesses/harnesses.uhd.ts", "changed": false },
+    { "id": "scenarios-untouched", "kind": "digest", "file": "src/scenarios.ts", "changed": false },
+    { "id": "gnss-part-untouched", "kind": "digest", "file": "parts/catalog/matek-m9n-5883.json", "changed": false },
+    { "id": "o4-part-untouched", "kind": "digest", "file": "parts/catalog/dji-o4-air-unit.json", "changed": false }
+  ],
+  "solution": [
+    { "protoboard": ["check"], "expect": { "exit": 1 } },
+    {
+      "replace": {
+        "file": "src/quadcopter.uhd.ts",
+        "find": "    link(\"dji_fc\", \"DJI socket\", [\"stack\", \"dji_socket\"], [\"dji_cable\", \"end_fc\"], { childLinks: [2, 3, 4, 5, 6].map((n) => ({ a: `p${n}`, b: `p${n}` })) }),\n    link(\"video_power\", \"O4 VCC\", [\"battery\", \"battery_out\"], [\"video\", \"vcc\"], { harness: \"dji_cable\" }),\n",
+        "with": "    link(\"dji_fc\", \"DJI socket\", [\"stack\", \"dji_socket\"], [\"dji_cable\", \"end_fc\"]),\n",
+        "count": 1
+      }
+    },
+    { "replace": { "file": "src/quadcopter.uhd.ts", "find": "p2: \"fc:uart1_rx\", p3: \"fc:uart1_tx\"", "with": "p2: \"fc:uart1_tx\", p3: \"fc:uart1_rx\"", "count": 1 } },
+    { "protoboard": ["check"] },
+    { "command": ["npx", "tsx", "node_modules/@protoboardai/ext-hardware/skills/system-compose/scripts/scenarios.ts"] },
+    { "say": "Two faults. 1) The O4's VCC was soldered to the battery (link video_power from battery_out, 18-25.2 V) with only positions 2-6 of the 3-in-1 cable mated, while the O4 takes 3.7-13.2 V: I removed that lead and mated every position of the DJI socket again, so the O4 is powered from the FC's 10 V BEC through the cable. 2) The GNSS lead's RX and TX were swapped on the FC's UART1 pads (p2 on RX1, p3 on TX1); I put p2 back on uart1_tx and p3 on uart1_rx. check reports no errors and every remaining fault scenario is caught." }
+  ]
+}

package/evals/rough-draft-is-concept/case.json

@@ -0,0 +1,36 @@
+{
+  "schema": "protoboard.eval-case/v0",
+  "title": "A rough draft is the concept level: three to six blocks, and a question before going deeper",
+  "skills": ["build-a-project", "system-compose"],
+  "tags": ["system", "concept", "scoping"],
+  "fixture": { "from": "fixture" },
+  "instruction": "I have an idea for a product (docs/brief.md). Give me a rough draft of it in this Protoboard project so I can look at it as a diagram: the top-level module is `trail-light` (export TRAIL_LIGHT in src/trail-light.uhd.ts, as protoboard.config.ts expects). There is no network and no parts service. Follow the stack's build-a-project SOP. End by telling me what the draft shows and what you assumed.",
+  "tools": { "read": true, "edit": true, "commands": ["npx protoboard *"] },
+  "budget": { "turns": 30, "seconds": 900, "usd": 4 },
+  "graders": [
+    { "id": "root-composed", "kind": "fault", "code": "PB_ROOT_NOT_FOUND" },
+    { "id": "check-clean", "kind": "check", "maxErrors": 0, "absent": ["PB_INVALID_ENDPOINT", "PB_UNRESOLVED_DEFINITION"], "ran": ["uhd/checkSystem"] },
+    {
+      "id": "three-to-six-blocks",
+      "kind": "facts",
+      "definition": "trail-light",
+      "description": "The concept level: 3 to 6 top-level capability blocks, connected",
+      "facts": [{ "path": "children.2.id" }, { "path": "children.6", "exists": false }, { "path": "links.1.id" }]
+    },
+    { "id": "nothing-deeper", "kind": "files", "absent": ["src/boards", "src/harnesses", "src/enclosures", "docs/sourcing", "parts/local", "release"] },
+    { "id": "asks-before-going-deeper", "kind": "text", "matches": ["\\?", "deeper|next level|go further|break (it|them|each)|inside each"] },
+    { "id": "brief-untouched", "kind": "digest", "file": "docs/brief.md", "changed": false },
+    {
+      "id": "plain-and-honest",
+      "kind": "rubric",
+      "files": ["src/trail-light.uhd.ts"],
+      "rubric": "The person asked for a rough draft of a clip-on trail light from a four-line idea. 1. The model is a concept: three to six top-level blocks named for what they do (power, control, light, button, housing or similar), each with only the interfaces that join it to the others, and the links between them; no real part numbers, no circuit boards, no component-level detail, no file or folder per board. 2. Each block says it is a placeholder with no part chosen. 3. The final answer describes the draft in plain words with any abbreviation spelled out, states what was assumed (for example a single lithium cell, a supply voltage) as assumptions, and asks whether to go a level deeper instead of going there. 4. It does not claim the design is verified, sourced or ready to build."
+    }
+  ],
+  "solution": [
+    { "protoboard": ["check"], "expect": { "exit": 1 } },
+    { "write": { "file": "src/trail-light.uhd.ts", "from": "solution/trail-light.uhd.ts" } },
+    { "protoboard": ["check"] },
+    { "say": "Here is the rough draft, at concept level: four blocks in src/trail-light.uhd.ts. Power (a rechargeable cell and its charging from a phone charger) supplies Control and Light; Button tells Control when it is pressed; Control tells Light how bright to be. Every block is a placeholder: no part is chosen and no circuit board is drawn. Assumed, not decided: one lithium cell and a low-voltage controller. The housing and the clip are not in the draft yet. check: 0 errors. Do you want me to go a level deeper and break each block into what is inside it?" }
+  ]
+}

package/evals/rough-draft-is-concept/fixture/AGENTS.md

@@ -0,0 +1,9 @@
+# trail-light
+
+A Protoboard hardware project. The system is described in UHD
+(`@deltarobotics/uhd`): modules, interfaces, links, harnesses, artifacts.
+
+- `npx protoboard inspect [instance]`, `npx protoboard check`, `npx protoboard build`
+- `npx protoboard skills` lists the installed SOPs; start with **build-a-project**.
+- The top-level module lives under `src/` (`src/trail-light.uhd.ts`, export `TRAIL_LIGHT`).
+- Decisions go in `docs/decisions.md`; the idea is in `docs/brief.md`.

package/evals/rough-draft-is-concept/fixture/docs/brief.md

@@ -0,0 +1,8 @@
+# Trail light: the idea
+
+EVAL FIXTURE (an idea, not a specification).
+
+A light that clips to a backpack strap for walking at dusk. It should run a
+few evenings on one charge, charge from a phone charger, have one button
+(on, dim, off), and survive rain. Nothing is chosen yet: no parts, no size,
+no price.

package/evals/rough-draft-is-concept/fixture/docs/decisions.md

@@ -0,0 +1,3 @@
+# Decisions
+
+One entry per engineering decision: context, options, choice, evidence.

package/evals/rough-draft-is-concept/fixture/package.json

@@ -0,0 +1 @@
+{ "name": "trail-light", "version": "0.1.0", "private": true, "type": "module" }

package/evals/rough-draft-is-concept/fixture/protoboard.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from "@protoboardai/core";
+
+// EVAL FIXTURE: a project set up with `protoboard init` and nothing in it yet:
+// src/trail-light.uhd.ts does not exist. The person has an idea, not a design.
+export default defineConfig({
+  name: "trail-light",
+  root: { source: "src/trail-light.uhd.ts", export: "TRAIL_LIGHT" },
+  sources: ["src/**/*.uhd.ts", "parts/local/**/*.uhd.ts"],
+  catalog: "parts/catalog",
+  extensions: ["@protoboardai/ext-hardware"],
+});

package/evals/rough-draft-is-concept/solution/trail-light.uhd.ts

@@ -0,0 +1,40 @@
+import type { InterfaceDef, InterfaceLink, ModuleDef } from "@deltarobotics/uhd";
+
+/**
+ * Trail light, concept level (docs/brief.md): four capability blocks and the
+ * connections between them. Every block is a placeholder: no part is chosen,
+ * no board is drawn. The voltages are working assumptions for a single
+ * lithium cell and a 3.3 V controller, to be settled at the next level.
+ */
+const power = (id: string, name: string, role: "source" | "sink"): InterfaceDef => ({ id, name, domain: "electrical", exposed: true, protocols: [{ type: "power", roles: [role] }] });
+const signal = (id: string, name: string, role: "output" | "input"): InterfaceDef => ({ id, name, domain: "electrical", exposed: true, protocols: [{ type: "gpio", roles: [role] }] });
+
+const block = (id: string, name: string, description: string, interfaces: InterfaceDef[]): ModuleDef => ({ id, name, kind: "module", description: `Placeholder, no part chosen yet. ${description}`, interfaces, children: [], links: [] });
+
+export const TRAIL_POWER = block("trail-light-power", "Power", "A rechargeable cell, its charging from a USB phone charger, and the supply for everything else.", [power("supply", "Supply out", "source")]);
+export const TRAIL_CONTROL = block("trail-light-control", "Control", "Reads the button and sets the light: on, dim, off.", [power("supply", "Supply in", "sink"), signal("button", "Button in", "input"), signal("dim", "Brightness out", "output")]);
+export const TRAIL_LIGHT_OUTPUT = block("trail-light-output", "Light", "The LED and what drives it at two brightness levels.", [power("supply", "Supply in", "sink"), signal("dim", "Brightness in", "input")]);
+export const TRAIL_BUTTON = block("trail-light-button", "Button", "One push button the wearer can find with gloves on.", [signal("press", "Press out", "output")]);
+
+const link = (id: string, name: string, a: [string, string], b: [string, string]): InterfaceLink => ({ id, name, a: { child: a[0], interfaceId: a[1] }, b: { child: b[0], interfaceId: b[1] } });
+
+export const TRAIL_LIGHT: ModuleDef = {
+  id: "trail-light",
+  name: "Trail light",
+  kind: "module",
+  version: "0.1.0",
+  description: "Concept: a clip-on light for walking at dusk. Four blocks; nothing below them is decided.",
+  interfaces: [],
+  children: [
+    { id: "power", moduleDefId: "trail-light-power", name: "Power" },
+    { id: "control", moduleDefId: "trail-light-control", name: "Control" },
+    { id: "light", moduleDefId: "trail-light-output", name: "Light" },
+    { id: "button", moduleDefId: "trail-light-button", name: "Button" },
+  ],
+  links: [
+    link("control_supply", "Supply to the control", ["power", "supply"], ["control", "supply"]),
+    link("light_supply", "Supply to the light", ["power", "supply"], ["light", "supply"]),
+    link("button_press", "Button to the control", ["button", "press"], ["control", "button"]),
+    link("brightness", "Brightness", ["control", "dim"], ["light", "dim"]),
+  ],
+};

package/evals/tidy-the-diagram/case.json

@@ -0,0 +1,30 @@
+{
+  "schema": "protoboard.eval-case/v0",
+  "title": "The diagram reads before the build is done: no strip of parts, nothing on top of anything, measured and looked at",
+  "skills": ["build-a-project"],
+  "tags": ["system", "diagram", "layout"],
+  "fixture": { "from": "fixture" },
+  "instruction": "Someone opened this project's diagram and said it is one long strip of parts, with two of them on top of each other. Make the diagram readable before you hand it back. Do not change what the system is (src/ stays as it is). There is no network and no parts service. Follow the stack's guidance (AGENTS.md, the build-a-project SOP). End by telling me what you changed and how the diagram measures now.",
+  "tools": { "read": true, "edit": true, "commands": ["npx protoboard *"] },
+  "budget": { "turns": 25, "seconds": 900, "usd": 3 },
+  "graders": [
+    { "id": "found-before", "kind": "fault", "code": "PB_DIAGRAM_LAYOUT" },
+    { "id": "layout-clean", "kind": "check", "maxErrors": 0, "absent": ["PB_DIAGRAM_LAYOUT"], "ran": ["protoboard/layout", "uhd/checkSystem"] },
+    { "id": "model-untouched", "kind": "digest", "file": "src/bike-computer.uhd.ts", "changed": false },
+    { "id": "layout-saved", "kind": "digest", "file": ".protoboard/display.json", "changed": true },
+    { "id": "says-the-numbers", "kind": "text", "matches": ["cross", "overlap|on top|strip|row"] },
+    {
+      "id": "laid-out-by-function",
+      "kind": "rubric",
+      "files": [".protoboard/display.json"],
+      "rubric": "The person asked for the bike computer's diagram to be made readable without changing the model. 1. The saved layout puts the controller near the middle with the blocks it talks to around it, the USB port and the battery on the feeding side, and no long row or column of blocks. 2. The agent measured the layout (protoboard layout or project_layout) after changing it and reports the numbers (crossings, overlaps, the longest row) honestly, including anything still above the limits. 3. The final answer says what changed in plain words and does not claim the model or design changed."
+    }
+  ],
+  "solution": [
+    { "protoboard": ["layout", "--check"], "expect": { "exit": 1 } },
+    { "protoboard": ["layout", "", "--apply"] },
+    { "protoboard": ["layout", "--check"] },
+    { "protoboard": ["check"] },
+    { "say": "The diagram was one row of nine blocks with the buzzer on top of the radio. I laid the top level out again with protoboard layout --apply: the controller in the middle, the USB port and the battery feeding it from the left, the sensors, screen, buzzer, buttons and radio around it. It now measures 0 overlaps, longest row 3 and few line crossings, and check no longer lists PB_DIAGRAM_LAYOUT. Only .protoboard/display.json changed; the model in src/ is as it was." }
+  ]
+}

package/evals/tidy-the-diagram/fixture/.protoboard/display.json

@@ -0,0 +1,20 @@
+{
+  "schema": "uhd.display/v0",
+  "diagram": {
+    "layouts": {
+      "": {
+        "nodes": {
+          "screen": { "x": 60, "y": 140 },
+          "usb": { "x": 400, "y": 140 },
+          "gps": { "x": 740, "y": 140 },
+          "control": { "x": 1080, "y": 140 },
+          "buttons": { "x": 1420, "y": 140 },
+          "power": { "x": 1760, "y": 140 },
+          "motion": { "x": 2100, "y": 140 },
+          "radio": { "x": 2440, "y": 140 },
+          "buzzer": { "x": 2500, "y": 160 }
+        }
+      }
+    }
+  }
+}

package/evals/tidy-the-diagram/fixture/AGENTS.md

@@ -0,0 +1,9 @@
+# bike-computer
+
+A Protoboard hardware project. The system is described in UHD
+(`@deltarobotics/uhd`): modules, interfaces, links, harnesses, artifacts.
+
+- `npx protoboard inspect [instance]`, `npx protoboard check`, `npx protoboard build`
+- `npx protoboard skills` lists the installed SOPs; start with **build-a-project**.
+- The top-level module lives under `src/` (`src/bike-computer.uhd.ts`, export `BIKE_COMPUTER`).
+- The diagram's layout is saved in `.protoboard/display.json`, the one file under `.protoboard/` you may write.

package/evals/tidy-the-diagram/fixture/docs/brief.md

@@ -0,0 +1,5 @@
+# Bike computer
+
+A handlebar computer for road bikes: speed, distance and the route on a small
+screen, from GPS and a motion sensor; a buzzer for turns; two buttons; a phone
+link over Bluetooth; charged from USB-C. Concept level only so far.

package/evals/tidy-the-diagram/fixture/package.json

@@ -0,0 +1 @@
+{ "name": "bike-computer", "version": "0.1.0", "private": true, "type": "module" }

package/evals/tidy-the-diagram/fixture/protoboard.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from "@protoboardai/core";
+
+// EVAL FIXTURE: a concept-level bike computer, nine blocks, whose diagram was
+// saved as one long row of cards with two of them on top of each other
+// (.protoboard/display.json). The model is right; the diagram is not.
+export default defineConfig({
+  name: "bike-computer",
+  root: { source: "src/bike-computer.uhd.ts", export: "BIKE_COMPUTER" },
+  sources: ["src/**/*.uhd.ts", "parts/local/**/*.uhd.ts"],
+  catalog: "parts/catalog",
+  extensions: ["@protoboardai/ext-hardware"],
+});

package/evals/tidy-the-diagram/fixture/src/bike-computer.uhd.ts

@@ -0,0 +1,63 @@
+import type { InterfaceDef, InterfaceLink, ModuleDef } from "@deltarobotics/uhd";
+
+/**
+ * Bike computer, concept level (docs/brief.md): nine capability blocks around
+ * the controller. Every block is a placeholder: no part is chosen.
+ */
+const power = (id: string, name: string, role: "source" | "sink"): InterfaceDef => ({ id, name, domain: "electrical", exposed: true, protocols: [{ type: "power", roles: [role] }] });
+const signal = (id: string, name: string, role: "output" | "input"): InterfaceDef => ({ id, name, domain: "electrical", exposed: true, protocols: [{ type: "gpio", roles: [role] }] });
+const block = (id: string, name: string, description: string, interfaces: InterfaceDef[]): ModuleDef => ({ id, name, kind: "module", description: `Placeholder, no part chosen yet. ${description}`, interfaces, children: [], links: [] });
+
+export const BIKE_USB = block("bike-usb", "USB-C port", "Charging input.", [power("vbus", "VBUS out", "source")]);
+export const BIKE_POWER = block("bike-power", "Battery and charging", "A lithium cell, its charger and the 3.3 V supply.", [power("vbus", "VBUS in", "sink"), power("v3v3", "3.3 V out", "source")]);
+export const BIKE_CONTROL = block("bike-control", "Controller", "Reads the sensors and buttons, draws the screen, talks to the phone.", [
+  power("v3v3", "3.3 V in", "sink"),
+  signal("gps", "GPS data in", "input"),
+  signal("motion", "Motion data in", "input"),
+  signal("screen", "Screen out", "output"),
+  signal("buzz", "Buzzer out", "output"),
+  signal("buttons", "Buttons in", "input"),
+  signal("radio", "Radio out", "output"),
+]);
+export const BIKE_GPS = block("bike-gps", "GPS", "Position and speed.", [power("v3v3", "3.3 V in", "sink"), signal("data", "Data out", "output")]);
+export const BIKE_MOTION = block("bike-motion", "Motion sensor", "Tilt and vibration, for climbs and crashes.", [power("v3v3", "3.3 V in", "sink"), signal("data", "Data out", "output")]);
+export const BIKE_SCREEN = block("bike-screen", "Screen", "A small sunlight-readable display.", [power("v3v3", "3.3 V in", "sink"), signal("data", "Data in", "input")]);
+export const BIKE_BUZZER = block("bike-buzzer", "Buzzer", "Beeps before a turn.", [signal("drive", "Drive in", "input")]);
+export const BIKE_BUTTONS = block("bike-buttons", "Buttons", "Two buttons usable with gloves.", [signal("press", "Press out", "output")]);
+export const BIKE_RADIO = block("bike-radio", "Bluetooth radio", "The link to the phone.", [power("v3v3", "3.3 V in", "sink"), signal("data", "Data in", "input")]);
+
+const link = (id: string, name: string, a: [string, string], b: [string, string]): InterfaceLink => ({ id, name, a: { child: a[0], interfaceId: a[1] }, b: { child: b[0], interfaceId: b[1] } });
+
+export const BIKE_COMPUTER: ModuleDef = {
+  id: "bike-computer",
+  name: "Bike computer",
+  kind: "module",
+  version: "0.1.0",
+  description: "Concept: a handlebar bike computer. Nine blocks; nothing below them is decided.",
+  interfaces: [],
+  children: [
+    { id: "usb", moduleDefId: "bike-usb", name: "USB-C port" },
+    { id: "power", moduleDefId: "bike-power", name: "Battery and charging" },
+    { id: "control", moduleDefId: "bike-control", name: "Controller" },
+    { id: "gps", moduleDefId: "bike-gps", name: "GPS" },
+    { id: "motion", moduleDefId: "bike-motion", name: "Motion sensor" },
+    { id: "screen", moduleDefId: "bike-screen", name: "Screen" },
+    { id: "buzzer", moduleDefId: "bike-buzzer", name: "Buzzer" },
+    { id: "buttons", moduleDefId: "bike-buttons", name: "Buttons" },
+    { id: "radio", moduleDefId: "bike-radio", name: "Bluetooth radio" },
+  ],
+  links: [
+    link("charge", "USB charging", ["usb", "vbus"], ["power", "vbus"]),
+    link("control_supply", "Supply to the controller", ["power", "v3v3"], ["control", "v3v3"]),
+    link("gps_supply", "Supply to the GPS", ["power", "v3v3"], ["gps", "v3v3"]),
+    link("motion_supply", "Supply to the motion sensor", ["power", "v3v3"], ["motion", "v3v3"]),
+    link("screen_supply", "Supply to the screen", ["power", "v3v3"], ["screen", "v3v3"]),
+    link("radio_supply", "Supply to the radio", ["power", "v3v3"], ["radio", "v3v3"]),
+    link("gps_data", "GPS data", ["gps", "data"], ["control", "gps"]),
+    link("motion_data", "Motion data", ["motion", "data"], ["control", "motion"]),
+    link("screen_data", "Screen data", ["control", "screen"], ["screen", "data"]),
+    link("buzz", "Buzzer drive", ["control", "buzz"], ["buzzer", "drive"]),
+    link("buttons", "Buttons", ["buttons", "press"], ["control", "buttons"]),
+    link("radio_data", "Radio data", ["control", "radio"], ["radio", "data"]),
+  ],
+};

package/ops/bom.ts

@@ -0,0 +1,22 @@
+import { bom, type OperationFn } from "@protoboardai/core";
+
+/** BOM export: quantities multiplied through the instance tree, one line per definition, with origin. */
+export const bom_: OperationFn = (ctx) => {
+  const rows = bom(ctx.project);
+  const out = ctx.inputs.out ?? "docs";
+  const md = [
+    `# Bill of materials — ${ctx.project.name}`,
+    "",
+    "Generated by `protoboard run bom` from the resolved project. Do not edit by hand.",
+    "",
+    "| Qty | Part | Manufacturer | Part number | Origin |",
+    "| ---: | --- | --- | --- | --- |",
+    ...rows.map((r) => `| ${r.quantity} | ${r.name ?? r.definition} (\`${r.definition}\`) | ${r.manufacturer ?? ""} | ${r.partNumber ?? ""} | ${r.origin} |`),
+    "",
+  ].join("\n");
+  ctx.writeOutput(`${out}/bom.md`, md, "BOM (markdown)");
+  ctx.writeOutput(`${out}/bom.json`, JSON.stringify(rows, null, 2) + "\n", "BOM (JSON)");
+  const total = rows.reduce((s, r) => s + r.quantity, 0);
+  return { status: "succeeded", summary: `${rows.length} lines, ${total} items`, data: { lines: rows.length, items: total } };
+};
+export { bom_ as bom };