many eda additions

.claude/skills/kicad-port/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: kicad-port
+description: "Project skill for porting the Raspberry Pi CM5IO reference design into this custom CM5 carrier board. Use this skill on EVERY schematic/PCB task in this repo: editing .kicad_sch, defining or changing pinouts and nets, adding/removing circuit blocks, or verifying a design change. It encodes the source-of-truth for CM5 pins, the s-expression editing rules, and the MANDATORY verify loop (kicad-cli ERC + kicad-happy analyzer + diff-vs-reference). Always consult this skill before editing any KiCad file here, and run the verify loop after."
+---
+
+# CM5 Carrier — Port Workflow
+
+We are building a custom Raspberry Pi **CM5 carrier board** by porting the official
+**CM5IO reference design**. Work is currently in the **schematic / pinout phase**.
+
+This is a **diff-from-reference** project: every change starts from a known-good reference
+and must stay electrically defensible against it. Claude is the *editor* (surgical s-expr
+text edits); the tooling below is the *verifier*. Never edit without verifying.
+
+## Source of truth (consult before any pin/net decision)
+
+1. `cm5-datasheet.pdf` — authoritative CM5 module pinout, power sequencing, pin reservations.
+2. `CM5_Carrier_Pinout_BOM.md` / `CM5_Carrier_Design.md` — this board's intended pin map and BOM.
+3. `refs/CM5IO.kicad_sch` (+ `CM5_GPIO`, `CM5_HighSpeed`, `PCIe-M2` sub-sheets) — the reference
+   schematic we port FROM. Hierarchical design; sub-sheets are referenced by UUID.
+
+If a pin assignment disagrees between the datasheet and any other doc, **the datasheet wins** —
+flag the discrepancy, don't silently pick one.
+
+## S-expression editing rules (footguns)
+
+KiCad `.kicad_sch` / `.kicad_pcb` files are s-expression text — readable and Edit-able.
+But:
+
+- **NEVER hand-edit or hand-invent UUIDs.** Copy-pasting a symbol/sheet block as text and
+  reusing its UUID corrupts the schematic (KiCad treats duplicates as the same object).
+  If you need a new instance, generate a fresh UUID:
+  `python3 -c "import uuid; print(uuid.uuid4())"`
+- **Hierarchical nets:** a net can carry multiple labels across sheets (the analyzer's `LB-001`
+  finding). Prefer one canonical label style per cross-sheet net; don't rename one half.
+- **Power nets need a driver:** every power rail needs a power symbol or `PWR_FLAG`, or ERC fails.
+- After ANY structural edit, re-run the verify loop below. A passing Edit is not a passing design.
+- Coordinate edits through git. Another (context-free) agent may touch these files; commit small,
+  review diffs, never blind-overwrite a sheet you didn't just read.
+
+## The verify loop (MANDATORY after every schematic change)
+
+`python3` here is Homebrew 3.14 (the kicad-happy scripts require Python ≥ 3.10).
+Scripts live under `~/.claude/skills/kicad/scripts/` (symlinked from `kicad-happy/`).
+
+```bash
+SCH=path/to/your.kicad_sch          # the file you changed
+KSCR=~/.claude/skills/kicad/scripts
+
+# 1. KiCad's own ERC (the hard gate — must be clean before commit)
+kicad-cli sch erc --exit-code-violations --output /tmp/erc.json --format json "$SCH"
+#    non-zero exit => fix or revert before proceeding.
+
+# 2. kicad-happy structural review (catches what ERC won't: decoupling gaps,
+#    connector ground ratios, protocol/voltage mismatches, multi-label nets)
+python3 $KSCR/analyze_schematic.py "$SCH" --text          # human-readable
+python3 $KSCR/analyze_schematic.py "$SCH" -o /tmp/head.json   # machine-readable
+
+# 3. Diff against the committed reference baseline to see what your change moved
+python3 $KSCR/diff_analysis.py analysis/baseline/cm5io.json /tmp/head.json --text
+```
+
+Treat new WARN/ERROR findings in step 2/3 as regressions to justify or fix — not noise.
+
+## Optional deeper checks
+
+- **SPICE** (`spice` skill): validates analog subcircuits (regulator feedback dividers, RC/LC
+  filters, crystal load caps). Requires a simulator on PATH — **`ngspice` IS installed**
+  (`/opt/homebrew/bin/ngspice`) and the loop is validated end-to-end on the reference
+  (8 subcircuits pass, incl. the 5V→3.3V buck feedback divider). Run after the analyzer:
+  `python3 ~/.claude/skills/spice/scripts/simulate_subcircuits.py <analysis.json> -o sim.json`.
+- **Datasheets** (`datasheets` skill): extract CM5 / IC specs from PDFs so analyzer findings are
+  `datasheet-backed` rather than `heuristic`. Start with `cm5-datasheet.pdf`.
+
+## Schematic hygiene checklist (before declaring a sheet done)
+
+- [ ] All nets named — no auto-generated `Net-(R1-Pad1)` names in the final design
+- [ ] Power rails ALL_CAPS (`+3V3`, `+5V`, `GND`); active-low uses `n` prefix (`nRESET`, `nCS`)
+- [ ] `PWR_FLAG` on every power net with no explicit driver
+- [ ] No-connect markers on all intentionally unconnected pins
+- [ ] Hierarchical port names match the nets they carry
+- [ ] Reference designators follow convention (U/R/C/L/D/Q/J/SW/F/TP/BT), annotated by block
+- [ ] Title block filled (project, rev, date, author, one-line description)
+- [ ] Design notes added for non-obvious choices (pull-up values, protection ratings, placement)
+- [ ] **ERC passes with zero errors** (step 1 above)
+
+## Reference shelf (not wired into the loop)
+
+- `MCP-KiCad/` — MCP server over `pcbnew` (SWIG). PCB/fabrication only, Linux/flatpak-first.
+  Ignore until layout phase, and even then prefer `kicad-cli pcb` over it.
+- `kicad-claude-toolkit/` — greenfield "circuit-as-Python → PCB" generator + IPC bridge.
+  Built for new designs, not porting. Only its `schematic-hygiene` guidance (folded in above)
+  is relevant now.