@hybridlabor-api/bdb-hardware-pcb 0.1.0

package/README.md

@@ -0,0 +1,116 @@
+# BDB Hardware & PCB
+
+`@hybridlabor-api/bdb-hardware-pcb` — Electrical Engineering, PCB Design, and 3D
+Mechanical Enclosure tooling for AI coding agents: 5 skills plus two MCP
+servers (KiCad, OpenSCAD) exposing 55 tools over stdio JSON-RPC.
+
+Supports **KiCad 9 & 10** automation and **OpenSCAD** parametric enclosures
+across **Anthropic Claude Code**, **OpenAI Codex**, and **Google Antigravity
+(Gemini)**.
+
+---
+
+## Install
+
+### Option A — as part of AOS
+
+If you already use `@hybridlabor-api/bdb-dev-optimized-agent-skills` (AOS),
+its installer offers this package as an optional module (same mechanism as
+`bdb-synapse` / `bdb-dev-creator-extension`): AOS downloads this package and
+runs its `installer.js --auto` for you. No separate step needed.
+
+### Option B — standalone
+
+```bash
+npx @hybridlabor-api/bdb-hardware-pcb
+```
+
+This runs `installer.js` directly, non-interactively, on macOS, Linux, or
+Windows. It will:
+
+1. Set up the `kicad-mcp-server` and `openscad-mcp-server` Python virtual
+   environments (via `uv sync` if `uv` is on `PATH`, otherwise
+   `python3`/`python -m venv` + `pip install -e .`).
+2. Detect which harnesses are present on this machine (`~/.claude`,
+   `~/.codex`, `~/.gemini`, `~/.agents`) and, for each one found:
+   - copy the 5 skill directories into its skills folder,
+   - merge the `kicad` and `openscad` MCP server entries into its real MCP
+     config file (without touching any other entries already there).
+
+Every step prints one line saying what it actually did, or why it was
+skipped. Nothing is silently a no-op.
+
+Re-run the installer any time (e.g. after moving/reinstalling this package)
+to refresh the registered paths — it is idempotent and self-healing: it
+rewrites stale `command` paths in place rather than leaving them broken.
+
+---
+
+## Verify
+
+```bash
+./scripts/test_mcp_connection.sh --all
+```
+
+Spawns both MCP servers over real stdio, performs the JSON-RPC `initialize`
+handshake, lists tools, and validates every tool's schema — 47 tools from
+KiCad + 8 from OpenSCAD = **55 tools**, exit code 0 on success.
+
+Read [`HANDOFF_REVIEW.md`](HANDOFF_REVIEW.md) for the detailed verification
+dossier, and
+[`docs/adr/ADR-001-KICAD-OPENSCAD-MCP-STRATEGY.md`](docs/adr/ADR-001-KICAD-OPENSCAD-MCP-STRATEGY.md)
+for the architecture decision record behind the KiCad/OpenSCAD MCP choice.
+
+---
+
+## The 5 skills
+
+1. [`code-first-hardware-design`](skills/code-first-hardware-design/SKILL.md) — programmatic schematics via SKiDL, OpenSCAD parametric enclosures, text-based netlists.
+2. [`pcb-constraint-definition`](skills/pcb-constraint-definition/SKILL.md) — differential impedance, high-voltage creepage/clearance, return-path routing.
+3. [`schematic-datasheet-analysis`](skills/schematic-datasheet-analysis/SKILL.md) — automated PDF datasheet parsing, pinmux validation, decoupling networks.
+4. [`pcb-layout-routing-automation`](skills/pcb-layout-routing-automation/SKILL.md) — stackup configuration, placement heuristics, auto-routing via CLI.
+5. [`pcb-validation-dfm-signoff`](skills/pcb-validation-dfm-signoff/SKILL.md) — automated ERC/DRC execution, SI/PI integrity audits, DFM manufacturing constraints.
+
+## MCP servers
+
+- **KiCad MCP Server** (`mcp_servers/kicad-mcp-server`, upstream: [Seeed-Studio/kicad-mcp-server](https://github.com/Seeed-Studio/kicad-mcp-server)) — 47 tools: schematic capture, netlist generation, pinmux analysis, ERC, DRC, 3D rendering.
+- **OpenSCAD MCP Server** (`mcp_servers/openscad-mcp-server`, upstream: [jhacksman/OpenSCAD-MCP-Server](https://github.com/jhacksman/OpenSCAD-MCP-Server)) — 8 tools: parametric 3D enclosure modeling, STL export, multi-view PNG rendering.
+
+Both are third-party Python MCP servers vendored under `mcp_servers/`; their
+`.venv/` is created fresh at install time and is never shipped in the npm
+package.
+
+---
+
+## Repository layout
+
+```
+bdb-hardware-pcb/
+├── installer.js          # cross-platform installer (npx entry point / AOS module)
+├── config/mcp/            # reference-only MCP config templates (placeholder paths;
+│                           # installer.js generates the real, machine-specific config)
+├── docs/adr/               # architectural decision records (ADR-001)
+├── mcp_servers/
+│   ├── kicad-mcp-server     # vendored Python MCP server (KiCad)
+│   └── openscad-mcp-server  # vendored Python MCP server (OpenSCAD)
+├── scripts/
+│   ├── test_mcp_connection.py  # zero-dependency stdlib JSON-RPC tester
+│   ├── test_mcp_connection.sh  # multi-harness test runner
+│   ├── run_kicad_mcp.sh        # self-locating KiCad MCP launcher
+│   ├── run_openscad_mcp.sh     # self-locating OpenSCAD MCP launcher
+│   ├── openscad_wrapper.sh     # macOS / Linux OpenSCAD binary shim
+│   └── install_mcps.sh         # legacy bash-only venv setup (macOS/Linux only —
+│                                 # installer.js is the cross-platform replacement)
+├── skills/                # the 5 skills above
+├── HANDOFF_REVIEW.md      # verification dossier
+└── README.md
+```
+
+## Notes on portability
+
+`config/mcp/*.json` and `config/mcp/codex.toml` are reference templates only
+— they contain the placeholder `__INSTALL_DIR__`, never a real machine path,
+and are not read by `installer.js` at install time (it generates configs
+dynamically from `os.homedir()` and its own install directory). They are
+resolved to a real path only by `scripts/test_mcp_connection.sh`, for local
+verification.

package/config/mcp/antigravity.json

@@ -0,0 +1,22 @@
+{
+  "_comment": "Reference template only. installer.js generates the real, machine-specific config at install time (see mcpServerEntries() & installIntoHarness() in ../../installer.js) — nothing reads this file at runtime. __INSTALL_DIR__ below is a placeholder for wherever this package is actually installed; it is substituted only by scripts/test_mcp_connection.sh for local verification.",
+  "mcpServers": {
+    "kicad": {
+      "command": "__INSTALL_DIR__/scripts/run_kicad_mcp.sh",
+      "args": [],
+      "env": {
+        "KICAD_CLI_PATH": "/Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli"
+      }
+    },
+    "openscad": {
+      "command": "__INSTALL_DIR__/scripts/run_openscad_mcp.sh",
+      "args": [
+        "--transport",
+        "stdio"
+      ],
+      "env": {
+        "OPENSCAD_EXECUTABLE": "__INSTALL_DIR__/scripts/openscad_wrapper.sh"
+      }
+    }
+  }
+}

package/config/mcp/claude.json

@@ -0,0 +1,22 @@
+{
+  "_comment": "Reference template only. installer.js generates the real, machine-specific config at install time (see mcpServerEntries() & installIntoHarness() in ../../installer.js) — nothing reads this file at runtime. __INSTALL_DIR__ below is a placeholder for wherever this package is actually installed; it is substituted only by scripts/test_mcp_connection.sh for local verification.",
+  "mcpServers": {
+    "kicad": {
+      "command": "__INSTALL_DIR__/scripts/run_kicad_mcp.sh",
+      "args": [],
+      "env": {
+        "KICAD_CLI_PATH": "/Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli"
+      }
+    },
+    "openscad": {
+      "command": "__INSTALL_DIR__/scripts/run_openscad_mcp.sh",
+      "args": [
+        "--transport",
+        "stdio"
+      ],
+      "env": {
+        "OPENSCAD_EXECUTABLE": "__INSTALL_DIR__/scripts/openscad_wrapper.sh"
+      }
+    }
+  }
+}

package/config/mcp/codex.toml

@@ -0,0 +1,25 @@
+# ==============================================================================
+# OpenAI Codex MCP Server Configuration - Hardware & PCB Tools
+# ==============================================================================
+# Reference template only. installer.js generates the real, machine-specific
+# config at install time (see registerMcpServers() in ../../installer.js) --
+# nothing reads this file at runtime. __INSTALL_DIR__ below is a placeholder
+# for wherever this package is actually installed; it is substituted only by
+# scripts/test_mcp_connection.sh for local verification.
+# ==============================================================================
+
+[mcp_servers.kicad]
+command = "__INSTALL_DIR__/scripts/run_kicad_mcp.sh"
+args = []
+enabled = true
+
+[mcp_servers.kicad.env]
+KICAD_CLI_PATH = "/Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli"
+
+[mcp_servers.openscad]
+command = "__INSTALL_DIR__/scripts/run_openscad_mcp.sh"
+args = ["--transport", "stdio"]
+enabled = true
+
+[mcp_servers.openscad.env]
+OPENSCAD_EXECUTABLE = "__INSTALL_DIR__/scripts/openscad_wrapper.sh"

package/docs/adr/ADR-001-KICAD-OPENSCAD-MCP-STRATEGY.md

@@ -0,0 +1,334 @@
+# ADR-001: KiCad 9/10 & OpenSCAD MCP Integration and AI Hardware Automation Strategy
+
+- **Status**: RATIFIED
+- **Date**: 2026-09-14
+- **Authors**: BDB Agent OS Core Architecture Team (Worker 1)
+- **Target Systems**: BDB Agent OS (AOS), Antigravity (Gemini CLI), Claude Code, OpenAI Codex
+- **Deciders**: Architect, TechLead, Reviewer, Shipping
+- **References**:
+  - `https://github.com/mixelpixx/Konnect`
+  - `https://github.com/mixelpixx/KiCAD-MCP-Server`
+  - `https://github.com/Seeed-Studio/kicad-mcp-server`
+  - `https://github.com/aklofas/kicad-happy`
+  - `https://github.com/jhacksman/OpenSCAD-MCP-Server`
+  - `https://github.com/archimedes-market/mcp-openscad-render-loop`
+  - `https://github.com/petrijr/openscad-mcp`
+
+---
+
+## 1. Context and Problem Statement
+
+Hardware engineering and printed circuit board (PCB) design have historically resisted AI automation due to:
+1. **Monolithic, GUI-Centric Workflows**: Traditional electronic design automation (EDA) tools rely heavily on interactive graphical mouse input and proprietary binary or poorly specified text formats.
+2. **Fragile In-Process Scripting Bindings**: Legacy scripting in KiCad (v5–v8) depended on SWIG-generated C++ bindings (`pcbnew.so`) that suffer from severe memory safety issues (such as C++ object destructors executing out of sync with Python garbage collection, leading to segmentation faults), lack schematic authoring APIs, and demand tight coupling to platform-specific Python runtimes.
+3. **Severe LLM Context Window Overhead**: Exposing full EDA tool suites via the Model Context Protocol (MCP) frequently dumps 200+ tool definitions into the prompt, consuming 20,000 to 25,000 tokens *per conversation turn* before any domain reasoning begins.
+4. **Mechanical & Thermal Decoupling**: Enclosure design is traditionally isolated from PCB layout, leading to manual dimension transcriptions, clearance mismatches, and standoff misalignments.
+5. **Lack of Grounded Electrical Reasoning ("AI Slop")**: Naive LLM agents emit syntactically plausible circuits with invalid component ratings, floating high-impedance CMOS pins, missing bypass capacitors, acid traps, and return paths crossing plane splits.
+
+To establish an autonomous, production-grade hardware engineering capability inside the BDB Agent OS (AOS) ecosystem across all target harnesses (**Google Antigravity**, **Anthropic Claude Code**, and **OpenAI Codex**), we must select and integrate an optimal constellation of MCP servers, headless CLI engines, and domain intelligence frameworks.
+
+---
+
+## 2. Decision Drivers
+
+- **Memory Safety and Stability**: Elimination of in-process C++ crashes and cross-runtime desynchronization.
+- **Support for KiCad 9.0 and 10.0 Roadmap**: Alignment with KiCad's official out-of-process IPC API (Protocol Buffers over Nanomsg Next Generation - NNG) and headless `kicad-cli`.
+- **Context Window Economics**: Protection of agent reasoning budgets via tiered starter kits and on-demand toolset activation.
+- **Git-Native / Repository-Bound State**: All generated hardware artifacts (`.kicad_sch`, `.kicad_pcb`, `.scad`, `.stl`, Gerbers) must reside directly in the project workspace, not in opaque hidden local directories.
+- **Deterministic Verification Gates**: Unforgiving automated checks (ERC, DRC, DFM) driven by CLI exit codes rather than subjective LLM self-assessments.
+- **Multi-Harness Compatibility**: Unified operation across Antigravity, Claude Code, and Codex with zero external packaging friction on Apple Silicon macOS and Linux.
+
+---
+
+## 3. Comprehensive Evaluation of KiCad Tooling Options
+
+We evaluated four primary tools and MCP server candidates for KiCad integration:
+
+### 3.1 `mixelpixx/KiCAD-MCP-Server` (v2.x)
+- **Architecture**: Dual-runtime hybrid. A Node.js/TypeScript frontend implements the MCP stdio protocol and orchestrates a Python 3.10+ backend via child-process stdio RPC (`LLM -> TypeScript MCP -> Python Bridge -> SWIG/IPC -> KiCad`).
+- **Interaction Mechanisms**:
+  - *PCB*: Legacy SWIG bindings to `pcbnew`.
+  - *Schematic*: S-expression regex search-and-replace using `kicad-skip`.
+  - *Export*: Subprocess calls to `kicad-cli`.
+  - *Autorouting*: Freerouting Java bridge.
+- **Tool Surface**: 233 tools registered (173 indexed across 16 categories) plus 23 dynamic resources.
+- **Identified Failure Modes & Architectural Scars**:
+  - *SWIG Memory Corruption*: Documented in repository issue #362. Calling `BOARD.Remove()` hands C++ object ownership to Python; when Python drops the reference, it executes the C++ destructor on an object KiCad still references, causing process-wide memory corruption.
+  - *Multi-Runtime Friction on macOS*: Requires `setup-macos.sh` to link KiCad's bundled Python framework (`/Applications/KiCad/KiCad.app/Contents/Frameworks/python3`) with Node.js and handle System Integrity Protection (SIP) path restrictions.
+  - *Subprocess RPC Desync*: Documented in issue #373 where standard input/output desynchronization between Node.js and the Python child process causes dropped or misrouted JSON-RPC responses.
+  - *Context Budget Exhaustion*: Startup tool registration injects ~23,000 tokens of JSON schema into every turn.
+- **Assessment**: **SUPERSEDED / DEPRECATED**. The repository author has officially transitioned development to `Konnect`.
+
+### 3.2 `Seeed-Studio/kicad-mcp-server`
+- **Architecture**: Pure Python implementation built on `fastmcp` (`mcp[cli]>=1.27,<2.0`).
+- **Interaction Mechanisms**:
+  - *Dual-Mode PCB Engine*: Recommended mode runs inside KiCad's bundled Python interpreter for native `pcbnew` track geometry and design rules; fallback mode runs in standard Python with text-based S-expression parsing of `.kicad_pcb`.
+  - *Schematic Engine*: Pure Python AST parser (`SchematicParser`) and paren-counting S-expression injector (`schematic_editor.py`) for placing components and routing wires.
+  - *Validation*: Subprocess execution of `kicad-cli sch erc` and `kicad-cli pcb drc`.
+- **Tool Surface**: Focused set of ~25–30 tools covering schematic queries, component/wire placement, netlist tracing, hierarchical sheet traversal, and pinmux analysis.
+- **Unique Capabilities**:
+  - *Embedded Linux Device Tree Generation*: Features an automated tool (`generate_device_tree`) that maps schematic pin assignments directly into Linux Device Tree (`.dts`) source code.
+  - *PartReel API Integration*: Direct access to 21,000+ verified open-source hardware components.
+- **Assessment**: **ADOPTED AS SECONDARY / EMBEDDED UTILITY**. Excellent lightweight, single-language pure-Python tool for embedded Linux workflows and environments where native binary compilation is impossible.
+
+### 3.3 `mixelpixx/Konnect`
+- **Architecture**: Purpose-built successor to `KiCAD-MCP-Server` for KiCad 10. Written in pure Rust (1.78+). Packaged as a single static binary (~20 MB) with zero runtime dependencies (no Node.js, Python, pip, or npm trees).
+- **Interaction Mechanisms**:
+  - *Official KiCad 10 IPC API*: Native client for KiCad's Protobuf-over-NNG (Nanomsg Next Generation) socket interface (`KICAD_API_SOCKET`). Allows real-time, non-blocking PCB layout modifications integrated directly into KiCad's native Undo/Redo stack.
+  - *Native Rust S-Expression Engine*: Byte-for-byte fidelity S-expression parser and serializer for `.kicad_sch` with atomic transactional file updates (`write` -> `fsync` -> atomic `rename`), strict UUID preservation, and syntax versioning.
+  - *Routing Engine*: Native Rust Specctra `.dsn` export, integrated Freerouting invocation, and transactional `.ses` session import.
+  - *Exports*: Headless `kicad-cli` batch integration.
+- **Tool Surface & Context Management**:
+  - Exposes 226 tools organized across 21 toolsets (`schematic_capture`, `pcb_layout`, `pcb_routing`, `design_rules`, `audits`, `jlcpcb`, `reference_circuits`, `manufacturing`, etc.).
+  - **Dynamic Tool Router**: Implements on-demand toolset loading. On startup, exposes a ~2,000-token starter kit with meta-tools (`enable_toolset`, `get_recent_calls`). Agents dynamically enable only the toolsets required for the active phase (e.g., `schematic_capture` in Phase 2, `manufacturing` in Phase 5), preserving 85–90% of the LLM context window.
+- **Packaging**: Pre-compiled Universal binary (`macos-universal` for Apple Silicon arm64 and Intel x86_64). Drops into KiCad Plugin & Content Manager (PCM) or executes standalone via stdio/HTTP.
+- **License**: AGPL-3.0 for open-source workflows.
+- **Assessment**: **ADOPTED AS PRIMARY CAD MCP SERVER**. Solves memory corruption, runtime friction, and context exhaustion simultaneously.
+
+### 3.4 `aklofas/kicad-happy`
+- **Architecture**: Electronics engineering intelligence, simulation, and audit suite. Implemented in pure Python 3.10+ using only Python Standard Library modules (zero third-party dependencies; optional `pymupdf` for PDF parsing).
+- **Interaction Mechanisms**: Direct read-only AST parsing of `.kicad_sch`, `.kicad_pcb`, and Gerber files. Operates completely independently of running KiCad instances, `pcbnew`, or `kicad-cli`.
+- **Domain Intelligence Capabilities (11 Specialized Skills)**:
+  - *Circuit Topology Detection*: Autonomously identifies subcircuits including buck/boost power stages, LDO regulators, feedback voltage dividers, RC low-pass/high-pass filters, crystal oscillators, and reset generators.
+  - *Automated SPICE Testbench Generation*: Translates detected subcircuits into complete, runnable SPICE netlists (ngspice, LTspice, Xyce) with automated Monte Carlo component tolerance sweeps ($\pm 1\%, \pm 5\%$).
+  - *44-Rule EMC Pre-Compliance Engine*: Performs physical audits across PCB copper: return path interruptions across plane splits, differential pair length skew ($< 0.1\text{mm}$), PDN high-frequency decoupling loop inductance, and chassis ground isolation.
+  - *Connector ESD Audit*: Verifies that external connectors (USB, HDMI, headers) have dedicated bidirectional TVS diode arrays located within 2mm of entry pins with low-inductance ground returns.
+  - *Component Sourcing*: Multi-vendor API querying (DigiKey, Mouser, LCSC, JLCPCB, PCBWay) for live pricing, stock validation, and lifecycle status.
+- **Assessment**: **ADOPTED AS CORE DOMAIN INTELLIGENCE SUITE**. Fills the critical gap between mechanical CAD operations and electrical engineering reasoning.
+
+---
+
+## 4. Comprehensive Evaluation of OpenSCAD Tooling Options
+
+We evaluated four MCP and code-first CAD options for parametric enclosure co-design:
+
+### 4.1 `jhacksman/OpenSCAD-MCP-Server` (v0.2.0)
+- **Stack**: Python 3.11+ using `fastmcp`, `fastapi`, and `uvicorn`.
+- **Mechanism**: Invokes headless OpenSCAD CLI (`subprocess.run`). Implements atomic file writes via temporary `.render-*` folders and detects assert errors via regex scanning of stderr/stdout.
+- **Features**: Generates 3D models from built-in CSG primitive dictionaries; compiles custom SCAD code; renders 4 orthogonal/perspective PNG views (`perspective`, `front`, `top`, `right`).
+- **Limitation**: Maintains an internal, stateful, hidden model repository (`~/.local/share/openscad-mcp/models/<id>/<rev>`), returning abstract model UUIDs. This decouples generated CAD models from the project's Git repository.
+
+### 4.2 `archimedes-market/mcp-openscad-render-loop`
+- **Stack**: Pure Python FastMCP server.
+- **Mechanism**: Headless OpenSCAD CLI integration designed specifically for iterative agent loops: edit parameters -> render -> compute metrics -> adjust.
+- **Tools**:
+  - `validate_scad`: Fast syntax and parameter check via `openscad -o /dev/null --check-parameters true` without triggering full geometry generation.
+  - `render_stl`: Renders STL with native `-D key=val` parameter overrides.
+  - `render_png`: Renders camera-aligned preview PNGs (`iso`, `top`, `front`, `right`).
+  - `parametric_sweep`: Executes Cartesian sweeps across parameter ranges (up to 256 combinations) to test fit tolerances.
+  - `compute_metrics`: Uses `numpy-stl` to compute bounding box dimensions (`[dx, dy, dz]`), total volume ($\text{mm}^3$), surface area ($\text{mm}^2$), and triangle count directly into machine-readable JSON.
+- **Assessment**: **ADOPTED AS PRIMARY OPENSCAD MCP SERVER**. Workspace-relative, stateless execution perfectly matches Git-based AOS workflows.
+
+### 4.3 `petrijr/openscad-mcp`
+- **Stack**: Python 3.10+ standard MCP server.
+- **Features**: Content-addressed cache (`OPENSCAD_MCP_CACHE_ROOT`), batch rendering, and inline Base64 `ImageContent` returns.
+- **Assessment**: Strong secondary alternative; architecture verified.
+
+### 4.4 `fboldo/openscad-mcp-server`
+- **Stack**: Node.js running `openscad-wasm`.
+- **Assessment**: **REJECTED**. Severe performance degradation on complex geometry; lacks font rendering; cannot leverage the C++ Manifold geometry kernel.
+
+---
+
+## 5. Architectural Synthesis & Comparison Matrices
+
+### 5.1 KiCad Tooling Comparison Matrix
+
+| Dimension | `mixelpixx/KiCAD-MCP-Server` | `Seeed-Studio/kicad-mcp-server` | `mixelpixx/Konnect` | `aklofas/kicad-happy` | `kicad-cli` |
+|---|---|---|---|---|---|
+| **Language & Runtime** | Node.js + Python 3.10+ | Pure Python 3.10+ (`fastmcp`) | Pure Rust 1.78+ (Single Binary) | Pure Python 3.10+ (Stdlib) | C++ Native CLI |
+| **KiCad Connection** | Node stdio -> Python -> SWIG / IPC | Python `pcbnew` SWIG or S-exp text | Official KiCad 10 IPC (NNG/Protobuf) | File-based AST parser | Direct native CLI invocation |
+| **KiCad 9 Support** | Full (SWIG + experimental IPC) | Full (SWIG + text fallback) | Limited (IPC schema changes) | Full (format agnostic) | Full (`kicad-cli` v9) |
+| **KiCad 10 Support** | Partial (legacy bugfixes) | Full (supported via SWIG/CLI) | **Native / Primary Target** | **Full (format agnostic)** | **Native (`kicad-cli` v10)** |
+| **Tool Count** | 233 tools | ~25–30 tools | 226 tools across 21 toolsets | 11 specialized skills | 8 primary CLI subcommands |
+| **Context Overhead** | High (~23,000 tokens) | Low (~3,500 tokens) | **Optimized (~2,000 token starter kit)** | **Negligible (Skill on-demand)** | 0 tokens (CLI execution) |
+| **Schematic Editing** | Regex / paren-matching text | Pure Python S-exp injection | **Native Rust S-exp AST (atomic writes)** | Read-only analysis | Export & ERC only |
+| **PCB Real-time Sync** | Flaky (SWIG crashes, IPC early) | No (file-based or in-process) | **Yes (Full IPC + native Undo/Redo)** | No (offline analyzer) | No (batch processing) |
+| **Electrical Intelligence**| Basic net traversal | Pinmux & Linux DTS generation | Decoupling & rail audits | **Deep (Power trees, SPICE, 44 EMC rules)** | DRC/ERC violations only |
+| **Packaging Friction** | High (`setup-macos.sh`, SIP) | Medium (`pip install -e .`) | **Zero (Universal binary in PATH)** | **Zero (Standard Library only)** | High (Requires KiCad cask) |
+| **License** | MIT | MIT | AGPL-3.0 | MIT | GPL-3.0 |
+| **AOS Role** | *Deprecated* | *Secondary (Device Trees)* | **Primary CAD MCP Server** | **Core Intelligence & Review Suite** | **Headless CI/CD Hard Gate** |
+
+### 5.2 OpenSCAD Tooling Comparison Matrix
+
+| Dimension | `jhacksman/OpenSCAD-MCP-Server` | `archimedes-market/mcp-openscad-render-loop` | `petrijr/openscad-mcp` | `fboldo/openscad-mcp-server` |
+|---|---|---|---|---|
+| **Runtime** | Python 3.11+ (`fastmcp`, `uvicorn`) | Python 3.10+ (`fastmcp`) | Python 3.10+ (`mcp`) | Node.js / Bun (`npx`) |
+| **Execution Engine** | Native OpenSCAD CLI | Native OpenSCAD CLI | Native OpenSCAD CLI | WASM in JS runtime |
+| **State Paradigm** | Stateful UUID store in `~/.local/` | **Stateless / Workspace-relative** | Stateless + SHA256 cache | Stateless in-memory |
+| **Syntax Check** | Full render only | Fast check (`-o /dev/null --check-parameters`)| Compiler diagnostics | Failed render error |
+| **Parametric Overrides** | Hardcoded SCAD edits | Native `-D key=val` injection | Native `-D key=val` injection | String replacement |
+| **Physical Metrics** | None | **`compute_metrics` (bbox, volume, triangles)**| Metadata inspection | None |
+| **Multi-View Previews** | Automatic 4 PNGs | Configurable single view PNG | Configurable single view PNG | Single view PNG |
+| **AOS Role** | *Reference / Fallback* | **Primary OpenSCAD MCP Server** | *Secondary Alternative* | *Rejected (Slow WASM)* |
+
+---
+
+## 6. KiCad 9 and 10 Architectural Evolution: SWIG vs IPC vs CLI
+
+The transition from KiCad 8 through 9 to 10 marks a fundamental architectural shift in how automated agents interact with EDA software:
+
+```
++---------------------------------------------------------------------------------------------+
+|                                KICAD SCRIPTING EVOLUTION                                    |
++---------------------------------------------------------------------------------------------+
+|  KiCad 8.x and earlier:                                                                     |
+|    Agent -> Python Process -> SWIG In-Process C++ Bindings (pcbnew.so) -> PCB Memory Space  |
+|    * CRITICAL FLAWS: No schematic API; SWIG memory desync segfaults; thread-unsafe.        |
++---------------------------------------------------------------------------------------------+
+|  KiCad 9.0 (Transition Phase):                                                              |
+|    - SWIG deprecated; early IPC daemon introduced over UNIX sockets for PCB Editor.          |
+|    - kicad-cli expanded with JSON formatting for ERC and DRC reports.                       |
++---------------------------------------------------------------------------------------------+
+|  KiCad 10.0 (Modern Architecture):                                                          |
+|    - Official IPC API: Protocol Buffers over Nanomsg Next Generation (NNG).                 |
+|    - Out-of-process, thread-safe, non-blocking requests mapped to native Undo/Redo stack.   |
+|    - Direct IPC hooks for both Schematic and PCB Editors.                                   |
+|    - kicad-cli v10 adds .kicad_jobset batch execution and enhanced custom rule evaluation.  |
++---------------------------------------------------------------------------------------------+
+```
+
+### 6.1 Why SWIG is Obsolete for AI Agents
+1. **Destructor Race Conditions**: In-process Python bindings allow Python's garbage collector to destroy underlying C++ pointer objects while KiCad's internal viewport or connectivity graph still references them, triggering instant `SIGSEGV` aborts.
+2. **Lack of Schematic API**: SWIG bindings were historically compiled exclusively for `pcbnew`. Automated schematic authoring via SWIG is impossible, forcing reliance on brittle regex injection.
+3. **Interpreter Lock-In**: Under macOS, SWIG binaries must match the exact Python dynamic library (`libpython3.x.dylib`) compiled into the KiCad application bundle, breaking standard virtual environments.
+
+### 6.2 The KiCad 10 IPC Architecture (NNG + Protobuf)
+KiCad 10 standardizes on an external IPC daemon communicating over local UNIX domain sockets (`/tmp/kicad_api.sock` or `KICAD_API_SOCKET` environment variable) or Windows named pipes. Requests and responses are strongly typed using Google Protocol Buffers.
+- **Benefits for Agents**:
+  - The agent runs in an isolated process (Rust, Python, or Go) with zero risk of crashing the CAD core.
+  - Modifications are transacted through KiCad's command manager, preserving the interactive Undo/Redo stack so human engineers can review agent actions step-by-step.
+  - Headless execution can run against a virtual frame buffer (`xvfb-run` on Linux) or headless IPC server.
+
+### 6.3 The Deterministic Headless CLI (`kicad-cli`)
+For automated CI/CD and release gating, interactive IPC is replaced by `kicad-cli`. It operates directly on files, requires no running GUI or socket, and produces deterministic exit codes:
+- `kicad-cli sch erc --exit-code-violations project.kicad_sch`: Returns `0` if clean; returns `1` if electrical rule violations exist.
+- `kicad-cli pcb drc --exit-code-violations --format json -o drc_report.json board.kicad_pcb`: Emits structured JSON diagnostics.
+- `kicad-cli jobset run manufacturing.kicad_jobset`: Atomically produces Gerbers, drill files, BOMs, and STEP models in a single headless pass.
+
+---
+
+## 7. OpenSCAD Engine Acceleration & Host Packaging
+
+### 7.1 The Manifold Geometry Engine
+Legacy OpenSCAD releases used CGAL for Constructive Solid Geometry (CSG) booleans. On intricate enclosure designs containing dozens of USB/connector cutouts, screw threads, and ventilation grilles, CGAL frequently stalls for minutes or hits CPU timeouts.
+Modern OpenSCAD (snapshots 2024–2026) incorporates the **Manifold** geometry kernel:
+- Achieves **10x to 100x rendering acceleration**.
+- Guarantees 2-manifold output (water-tight meshes essential for 3D printing slicing and collision analysis).
+- Enabled via the command-line flag: `--backend=Manifold`.
+
+### 7.2 macOS Packaging & Gatekeeper Resolution
+On macOS host systems:
+- Standard Homebrew `brew install --cask openscad` points to the stale 2021.01 release, which was **disabled by Homebrew maintainers on 2026-09-01** due to macOS Gatekeeper quarantine verification failures.
+- **Mandatory Installation Directive**:
+  ```bash
+  brew install --cask openscad@snapshot
+  ```
+  This installs the modern, signed snapshot build containing the Manifold backend, located at `/Applications/OpenSCAD.app/Contents/MacOS/OpenSCAD`.
+
+### 7.3 BOSL2 Parametric Enclosure Standard
+To eliminate the extreme computational cost of OpenSCAD's naive `minkowski()` sums, the AOS enclosure design pipeline mandates the **BOSL2** (Belfry OpenSCAD Library v2) framework:
+- Uses analytical rounded geometry: `cuboid([w, d, h], rounding=2, edges="Z")`.
+- Native mounting bosses with heat-set brass insert pockets:
+  * M2: $3.2\text{mm}$ hole diameter, $4.0\text{mm}$ depth, $\ge 1.5\text{mm}$ wall thickness.
+  * M3: $4.0\text{mm}$ hole diameter, $5.7\text{mm}$ depth, $\ge 1.8\text{mm}$ wall thickness.
+- Automated board collision checking via `%import("board.stl")` background visualization.
+
+---
+
+## 8. Multi-Agent Pipeline Mapping Across AOS Phases (`/startcycle`)
+
+The recommended tooling maps directly into the 5 distinct phases of the AOS multi-agent lifecycle:
+
+```
+====================================================================================================
+ PHASE 1: ARCHITECT & SYSTEM PLANNING
+ --------------------------------------------------------------------------------------------------
+ Agents: Architect, TechLead
+ Primary Skills: pcb-constraint-definition, kicad-happy:datasheets, kicad-happy:bom
+ Tooling: Konnect (reference_circuits, jlcpcb toolsets)
+ Responsibilities:
+   1. Translate product spec into formal `constraints.yaml` and `.kicad_dru` custom rules.
+   2. Select layer stackup (e.g. 4-Layer JLC04161H-7628) and target impedances (50Ω single, 90Ω diff).
+   3. Source verified, in-stock active components using JLCPCB / LCSC / DigiKey APIs.
+====================================================================================================
+                                                 |
+                                                 v
+====================================================================================================
+ PHASE 2: CODE-FIRST HARDWARE & CIRCUIT SYNTHESIS
+ --------------------------------------------------------------------------------------------------
+ Agents: Godmode_Engineering, Godmode_Media_EventTech
+ Primary Skills: code-first-hardware-design, schematic-datasheet-analysis
+ Tooling: SKiDL (Python), Konnect (schematic_capture), Seeed (device_tree), OpenSCAD + BOSL2
+ Responsibilities:
+   1. Synthesize schematic netlist programmatically via SKiDL or atomic S-expression placement.
+   2. Extract PCB board outline (`Edge.Cuts`) and mounting hole centroid CSV.
+   3. Generate parametric 3D printed enclosure (`enclosure.scad`) with BOSL2 snap-fits and standoffs.
+   4. If embedded Linux target, generate Device Tree source (`.dts`) from pin assignments.
+====================================================================================================
+                                                 |
+                                                 v
+====================================================================================================
+ PHASE 3: PCB LAYOUT & ROUTING AUTOMATION
+ --------------------------------------------------------------------------------------------------
+ Agents: Godmode_Engineering
+ Primary Skills: pcb-layout-routing-automation
+ Tooling: Konnect (pcb_layout, pcb_routing), Freerouting (Specctra DSN/SES)
+ Responsibilities:
+   1. Execute floorplanning: decouple IC pins within 1.5mm, cluster power stages, isolate analog.
+   2. Enforce 45-degree trace routing and constant differential pair spacing ($W/S$).
+   3. Execute automated routing pass via Specctra DSN/SES Freerouting bridge.
+   4. Flood continuous ground reference planes and drop perimeter stitching via fences.
+====================================================================================================
+                                                 |
+                                                 v
+====================================================================================================
+ PHASE 4: ADVERSARIAL ELECTRICAL & MECHANICAL REVIEW
+ --------------------------------------------------------------------------------------------------
+ Agents: Reviewer (Adversarial Doubt-Driven Review)
+ Primary Skills: schematic-datasheet-analysis, kicad-happy (kicad, spice, emc), mcp-openscad-render-loop
+ Tooling: kicad-happy (44 EMC rules, ngspice testbenches), OpenSCAD (compute_metrics, render_png)
+ Responsibilities:
+   1. Grounded datasheet audit: verify every pin rating, voltage threshold, and pull-up resistor.
+   2. Negative evidence analysis: detect floating CMOS inputs and unvalidated DNP components.
+   3. Run automated SPICE simulation on feedback dividers, filters, and power supplies.
+   4. Run 44-rule EMC pre-compliance audit (return paths over plane splits, diff skew < 0.1mm).
+   5. Verify mechanical enclosure clearances and render 4-view PNG verification collage.
+====================================================================================================
+                                                 |
+                                                 v
+====================================================================================================
+ PHASE 5: FABRICATION RELEASE GATE & DFM SIGNOFF
+ --------------------------------------------------------------------------------------------------
+ Agents: Godmode_Shipping
+ Primary Skills: pcb-validation-dfm-signoff
+ Tooling: kicad-cli (sch erc, pcb drc, jobset run), OpenSCAD (export_model STL/3MF)
+ Responsibilities:
+   1. Execute headless DRC/ERC hard gate: zero tolerance for errors (`--exit-code-violations`).
+   2. Audit fab-house DFM specs: min trace/space (5/5 mil), drill (0.2mm), solder mask dam (0.1mm).
+   3. Verify SMT assembly fiducials (3 non-collinear markers) and pin-1 orientation indicators.
+   4. Generate production release package: Gerbers (RS-274X/X2), Excellon drill, CPL/Centroid, BOM.
+   5. Sign off and publish `DFM_SIGNOFF_REPORT.md` and `production_artifacts/release.zip`.
+====================================================================================================
+```
+
+---
+
+## 9. Final Recommendations & Implementation Directives
+
+1. **Primary KiCad CAD Server**: Standardize on **`mixelpixx/Konnect`** running as a native Rust static binary over stdio.
+2. **Core Electrical Review & Simulation Suite**: Standardize on **`aklofas/kicad-happy`** (pure Python, zero dependencies) for all circuit topology tracing, SPICE testbench generation, and 44-rule EMC pre-compliance audits.
+3. **Headless Verification Gate**: Mandate **`kicad-cli` (v10)** for automated DRC/ERC release gates and manufacturing exports.
+4. **Primary OpenSCAD MCP Server**: Standardize on **`archimedes-market/mcp-openscad-render-loop`** (stateless, workspace-relative, exposing `validate_scad`, `render_stl`, `render_png`, and `compute_metrics`).
+5. **OpenSCAD Host Runtime**: Mandate **`brew install --cask openscad@snapshot`** with the **`--backend=Manifold`** flag configured for high-speed 3D rendering.
+6. **Skills Suite**: Deploy the 5 comprehensive, non-slop AI-era PCB skills under `skills/` and mirror them to `~/.agents/skills/` for universal discovery across Antigravity, Claude Code, and Codex.
+
+---
+
+## 10. Invalidation Conditions
+
+This architectural decision record shall be formally reviewed and revised if:
+1. KiCad upstream alters or deprecates the Nanomsg Next Generation (NNG) / Protobuf IPC transport.
+2. An upstream license change restricts AGPL-3.0 in proprietary commercial client deployments (in which case `Seeed-Studio/kicad-mcp-server` under MIT will be elevated to primary CAD server).
+3. OpenSCAD introduces a native, reliable STEP B-Rep export kernel, eliminating the CSG/B-Rep boundary.
+4. A unified single MCP server emerges that combines native KiCad 10 IPC editing, SPICE simulation, and 44-rule EMC analysis in a single memory-safe binary.