Camera GPIO Interface PCB Agent Guidance

This file is the canonical project guidance for agent sessions in this repository.

Session Start

Read this file first.

If AGENT_MEMORY_REPO is set and points at a directory, read $AGENT_MEMORY_REPO/AGENTS.md before planning or editing.

Then read, in this order:

• docs/rev0-plan.md: the whole design record, with the resume checklist at the end. Its dated update notes at the top supersede older statements below them.
• docs/kicad-libs-handoff-2026-09-24.md: what kicad-libs prepared for this board and which plan statements it corrected.
• docs/autoroute-log.md: the layout record, run by run, with every hand repair; then docs/session-handoff-2026-09-26.md: where the routed board stands and what is left before fabrication.

If sibling checkouts exist, also read:

• ../orb-weaver-context/context/agent-index.md
• ../orb-weaver-context/context/kicad-agent-context.md
• ../board-interfaces/docs/instrument-port-digital.md
• ../kicad-libs/docs/design-blocks.md
• ../kicad-libs/docs/blackfly-s-gpio-channel-design-block.md
• ../kicad-libs/docs/instrument-port-netclasses.md

If .agents/handoff.local.md exists, read it before planning or editing.

If the task is multi-step, risky, or likely to span more than one session, read .agents/PLANS.md and keep it updated as work progresses.

Repository Purpose

This repository owns the KiCad implementation and board-specific notes for camera-gpio-interface-pcb: three FLIR Blackfly S GPIO channels on pluggable screw terminals, two BNC inputs from a pyControl breakout, four 3.3 V BNC outputs to a Neuropixels OneBox, an InstrumentPort-Digital-50 with every camera line tapped, and USB power. No MCU, no firmware.

Board Rules

• kicad-libs owns the shared symbols, footprints, internal parts, vendor mappings and design blocks; board-interfaces owns the InstrumentPort contract. Do not copy library assets here. A placed block is a board-owned copy; re-annotate copies into 4-digit bands as mouse-joystick-pcb does.
• Blocks placed, all from orb_weaver_private: blackfly_s_gpio_channel_mcv6_vertical three times, logic_input_2ch_5v_schmitt_sn74lvc2g17 for the two BNC inputs, usb2_vertical, 5v_to_3v3_tps73733, instrument_port_digital_50_dut_ffc_boundary_vertical.
• Every BNC output is fixed at 3.3 V through 470 Ω. There is no 5 V option; the plan records why.
• USBLC6-2P6 is a two-line array: pins 1 and 6 are one node, 3 and 4 the other. Nine on the board: one for the two inputs, two for the four outputs, two inside each camera block. Use only orb_weaver_smd:USBLC6-2P6_SOT-666.
• Instrument tap nets end in _INST and take the INSTRUMENT netclass from the instrument-taps profile. Every unused LV541A input is tied to ground at the board.
• +5V_USB is the opto drive level and the ESD clamp reference. It must stay a 5 V rail.
• Fab floors (0.1 mm clearance and track width) live in Board Setup > Constraints, never as unconditional .kicad_dru rules; such a rule replaces every netclass clearance instead of flooring it. rule_severities.clearance stays at error. Decided 2026-09-26: the 146 findings between 0.10 and 0.19 mm inherited from the InstrumentPort and USB block layouts (all against the 0.20 mm default class, none voltage-bearing) are accepted as fab-floor copper inside blocks. The .kicad_dru rule "Low-voltage block clearance is advisory" demotes every pair where neither side is a voltage-bearing class to warning, the mouse-joystick form, never severity ignore; make fab's error-level DRC gate passes and make clearance-check (254 findings, 0 voltage-bearing, against the 256 baseline) is the gate for new or worsened findings. Delete the rule when kicad-libs re-routes the two blocks at 0.20 mm and they are re-placed here.
• A JLCPCB placement rotation correction goes in kicad-libs/vendor_specs/jlcpcb/footprint-rotations.csv, never in a footprint. This board was the first to place the Phoenix MCV 6 vertical and the LED_0402-1005_KNB footprint at JLCPCB; the placement preview of the 2026-09-26 order showed both oriented correctly (MCV 6 at +180, LED at 0), which kicad-libs records as verified rows.
• Mark unverified pinouts, cable orientation and electrical limits as open decisions. Record bench results in docs/bringup-log.md.

Development Environment

Prefer Makefile targets:

• make test: guidance and scaffold presence check
• make kicad-edits: open the project in the managed KiCad
• make kicad-shell, make kicad-version
• make codex / make claude: agent sessions with sibling checkouts added
• make agent-reflection
• make validate-db, make check-kicad-libs
• make fab, make docs, make docs-check
• make clearance-baseline before routing, then make export-dsn or make freeroute, make import-ses, make clearance-check: the shared kicad-libs routing helpers, described in ../kicad-libs/docs/freerouting-autorouting.md. This board exports with EXPORT_DSN_OPTIONS="--refill --protect-prerouted --power-layer In1.Cu" because In1.Cu carries the /GND plane; the routed result and its checks are in docs/autoroute-log.md

The pinned Guix channel in .guix/channels.scm carries KiCad 10.0.6, the version the design blocks were saved with, so this repository has no local KiCad overlay. The sibling ../kicad-libs checkout is used through ORB_WEAVER_KICAD_LIBS when present; the orb-weaver-kicad-libs channel pin only selects the packaged helper commands. Bump pins deliberately, not as cleanup.

docs/generated/ and the block between the <!-- BEGIN/END GENERATED BOARD DOCUMENTATION --> markers in README.md are written by make docs. Never hand-edit either.

Netclass profiles applied 2026-09-25 with ../kicad-libs/bin/orb-weaver-kicad-apply-netclasses: instrument-taps and hv-power-24v (its HV classes match nothing here; it supplies PWR_5V, PWR_3V3 and the _LOCAL variants), plus the board-local kicad/netclass-profiles/camera-gpio-narrow-rails.json, which puts PWR_5V_NARROW and PWR_3V3_NARROW (0.20 mm track, 0.20 mm clearance, 0.6/0.3 mm via) one priority step above the shared rail classes so /+5V and /+3.3V can enter the 0.5 mm-pitch SOT-666 and DRY6 pads they feed. The shared widths cannot reach those pins (docs/autoroute-log.md, run 2); a class that is wider than the pin it must connect to gets a narrower local class rather than a hand-routed neck. Re-apply any of the three if --check reports drift; the helper preserves unrelated classes and patterns.

Validation

For schematic and layout work, run KiCad ERC and DRC through the managed environment once the design is mature enough for them to be meaningful, and compare the exported netlist against the plan's tables after edits; ERC alone did not catch earlier electrical findings on mouse-joystick-pcb.

ORB_WEAVER_KICAD_LIBS must resolve for KiCad to find the database, footprint and design-block libraries.

Board Manifest

kicad/board-manifest.yaml is the board's manifest (kicad-libs decision D20, derived 2026-10-02): every placed block with its anchor from docs/generated/mechanical-datums.json, each port mapped to the label it meets in its parent sheet or open with a reason, the board-authored sheets, the netclass profiles and every net's class. After placing, wiring or moving a block run make mechanical-datums, then make board-manifest-derive (keeps the written meanings and reasons) and make board-manifest-check; make board-manifest-render regenerates the block between the markers at the top of docs/interface-map.md, which is a rendering of the manifest and is never edited by hand; the narrative below the block is. A port the manifest neither maps nor leaves open with a reason is an error, not a note.

make compose makes the project agree with the manifest (D28), creating the sheet instances, pin connections and PCB groups it lacks and never moving or renaming; make compose-check is the dry run. make refresh-block INSTANCE= brings one placed block up to its library block and reports what changed (D22). kicad/board.yaml with subsystem recipes is the board's source (D27) when one is written: make expand writes the manifest from it and make expand-check compares. The Makefile targets come from kicad-libs templates/kicad-repo/Makefile and call the sibling checkout's launchers.

Publication Layers

This repository is mirrored to GitHub for the rig's researchers, so it has two layers (decided 2026-10-12):

• Citable layer: README.md, CITATION.cff, LICENSE, LICENSES/, kicad/, docs/generated/ and every document the README lists. It must open and read without any Orb Weaver checkout and must not refer to codeberg.org or to orb-weaver-* repositories. KiCad library identifiers (orb_weaver_private:…, orb_weaver_smd:…) and the generated-block comments are allowed; they are library references, not links. Files in other repositories are cited as <repository>/<path> with no ../ and no URL; docs/development.md maps each repository name to its URL.
• Development layer: docs/development.md, the documents it lists, AGENTS.md, .agents/, .codex/, Makefile and .guix/. These may name the sibling checkouts and the Orb Weaver repositories.

A new document goes into exactly one of the two lists. LICENSES/NOTICE.md keeps its kicad-libs URL: it is the CC-BY-SA attribution for the embedded symbols, footprints and blocks.