@hybridlabor-api/aos 4.4.2-beta.3 → 4.4.2-beta.5

package/bin/aos-uninstall.mjs

@@ -47,6 +47,7 @@ const AGENTS = [
 ];
 
 const MODULE_DIRS = ['memB', 'bdb-synapse', 'bdb-os-remote', 'bdb-dev-creator-extension',
+  'bdb-hardware-pcb',
   'bdb-dev-tool-installer',
   'bdb-agent-orchestrator',      // AO
   'bdb-os-agent-workspace',      // AO's archived predecessor, if still lying around

package/docs/skills_table.md

@@ -181,6 +181,16 @@
 | `triage` | Move issues and external PRs through a state machine of triage roles, categorise, verify, and write agent-ready briefs. |
 | `typescript-pro` | Master TypeScript with advanced types, generics, and strict type safety. Handles complex type systems, decorators, and enterprise-grade patterns. |
 
+#### 🔩 Engineering & Hardware
+| Skill Name | Description |
+|------------|-------------|
+| `godmode-hardware-pcb` | Architectural authority for electrical schematics, PCB layout, KiCad projects, and OpenSCAD enclosures — trace geometry, impedance, stackup, and DFM/DRC/ERC sign-off. Use when designing or reviewing physical hardware before it goes to fabrication. |
+| `code-first-hardware-design` | Programmatic schematic capture, circuit synthesis (SKiDL, text netlists, S-expressions), and parametric 3D CAD enclosure co-design (OpenSCAD/BOSL2). Use when generating circuits in code, exporting netlists, scripting KiCad schematics, or designing 3D enclosures. |
+| `pcb-constraint-definition` | Translates high-level hardware requirements into formal engineering constraints, layer stackup calculations, netclasses, and custom DRC rules for KiCad. Use when defining board constraints, stackup, impedance matching, power budgeting, or netclasses. |
+| `pcb-layout-routing-automation` | Floorplanning, component placement rules, high-speed differential pair routing, return path continuity, thermal via arrays, and keepout enforcement for KiCad PCB layouts. Use when placing footprints, routing traces, creating ground planes, or managing thermal/RF keepouts. |
+| `pcb-validation-dfm-signoff` | Automated DRC/ERC verification, SI/PI screening, fab house DFM/DFA compliance, and production release sign-off for KiCad projects. Use when running final design rule checks, auditing manufacturing limits, generating Gerbers/BOM/CPL, or issuing DFM sign-off reports. |
+| `schematic-datasheet-analysis` | Electrical rule auditing, datasheet grounding, pinout validation, power tree tracing, and negative evidence analysis for KiCad schematics. Use when analyzing schematics, auditing pinmux/logic levels, checking component ratings, or validating datasheets. |
+
 #### 📦 Other Utilities
 | Skill Name | Description |
 |------------|-------------|

package/installer.js

@@ -694,6 +694,32 @@ function flushSessionManifest() {
     if (_sessionManifest) saveInstallManifest(_sessionManifest);
 }
 
+// skills/global_legacy/ has not existed in the shipped payload for a long
+// time -- the three `if (dir === 'global_legacy')` copy branches elsewhere in
+// this file have been dead code ever since, since that name never appears in
+// a fresh fs.readdirSync(skillsBase). Nothing populates a fresh
+// targetLegacyDir any more, but nothing ever removed an OLD one either: a
+// real Windows install this session still had 126 stale legacy skill copies
+// sitting in .codex/skills/legacy, indexed alongside the current top-level
+// copies of the same skills by the harness's own skill picker -- the
+// "duplicate skills" a live test reported. Since the source category is
+// permanently gone, an existing legacy dir is unconditionally obsolete, not
+// merely unmanaged: retire it instead of recreating an eternally-empty
+// placeholder for it.
+function retireObsoleteLegacyDir(targetLegacyDir) {
+    if (!targetLegacyDir || !fs.existsSync(targetLegacyDir)) return;
+    if (fs.existsSync(path.join(srcDir, 'skills', 'global_legacy'))) {
+        fs.mkdirSync(targetLegacyDir, { recursive: true });
+        return;
+    }
+    try {
+        fs.rmSync(targetLegacyDir, { recursive: true, force: true });
+        log.step(`Removed retired legacy skill copies at ${targetLegacyDir} (global_legacy has not shipped in a long time).`);
+    } catch (e) {
+        logDebug(e, 'retire legacy dir');
+    }
+}
+
 function resolveMcpsArg(availableMcps) {
     const requested = mcpsArg.split(',').map(s => s.trim()).filter(Boolean);
     const wantsNone = requested.some(r => ['none', 'core', 'core-only'].includes(r.toLowerCase()));
@@ -785,7 +811,10 @@ function detectPlatforms() {
         },
         {
             key: 'codex', name: 'ChatGPT Codex CLI', path: path.join(homeDir, '.codex'),
-            evidence: () => hasExecutable('codex'),
+            // Codex ships two ways: the standalone CLI binary, and embedded in
+            // the ChatGPT desktop app. A machine can have either without the
+            // other (e.g. ChatGPT desktop only, codex never put on PATH).
+            evidence: () => hasExecutable('codex') || anyExists(appBundle('ChatGPT')),
         },
         {
             key: 'claudecode', name: 'Claude Code CLI', path: path.join(homeDir, '.claude'),
@@ -900,6 +929,7 @@ function detectInstallState() {
         // The archived predecessor is deliberately NOT detected: a copy of it
         // should be removed, not carried forward into another install.
         { id: 'creator', dir: path.join(basePath, 'bdb-dev-creator-extension') },
+        { id: 'hardware', dir: path.join(basePath, 'bdb-hardware-pcb') },
         { id: 'installer', dir: path.join(basePath, 'bdb-dev-tool-installer') }
     ];
 
@@ -910,13 +940,23 @@ function detectInstallState() {
     }
 
     const currentVersion = pkg.version || '3.9.6';
-    const updateAvailable = isInstalled && (localVersion !== currentVersion);
+    // Was a bare !== -- any version string difference counted as "update
+    // available", downgrade included. A real Windows session ran `@latest`
+    // (resolving to the actual latest stable, 4.4.1) against a machine
+    // already on 4.4.2-beta.3 and the installer silently treated dropping two
+    // versions the same as a normal update -- no distinction, no warning.
+    // isNewerVersion() already exists and already handles prerelease
+    // ordering correctly; this just uses it in both directions instead of
+    // only for the npm-registry freshness check it was written for.
+    const versionChanged = isInstalled && localVersion !== currentVersion;
+    const isDowngrade = versionChanged && isNewerVersion(currentVersion, localVersion);
+    const updateAvailable = versionChanged && !isDowngrade;
 
     // Extend: also load the file-level install manifest so the caller can
     // seed manifest-aware writes during this same session.
     const installManifest = loadInstallManifest();
 
-    return { isInstalled, localVersion, currentVersion, updateAvailable, installedModules, manifest, installManifest };
+    return { isInstalled, localVersion, currentVersion, updateAvailable, isDowngrade, installedModules, manifest, installManifest };
 }
 
 function saveManifest(data = {}) {
@@ -1134,13 +1174,20 @@ function syncSkillsToGlobalHarnesses(excludeSkills = []) {
     // the very directories detectPlatforms() then read back as proof the
     // harness existed. ~/.agents is ours and always written.
     const detectedKeys = new Set(detectPlatforms().map((d) => d.key));
+    // No `|| fs.existsSync(d.dir)` fallback here on purpose: that fallback
+    // used to mean a directory AOS itself planted in a past run (before a
+    // harness was ever really detected) kept being "detected" forever,
+    // regardless of what detectPlatforms() found this run -- the exact
+    // circularity the block comment above warns about, just one layer down.
+    // A harness that stops being detected now simply stops receiving skill
+    // updates instead of perpetuating a false positive.
     const extraSkillDestinations = [
         { dir: path.join(homeDir, '.agents', 'skills'), key: null },
         { dir: path.join(homeDir, '.claude', 'skills'), key: 'claudecode' },
         { dir: path.join(homeDir, '.codex', 'skills'), key: 'codex' },
         { dir: path.join(homeDir, '.cursor', 'skills'), key: 'cursor' },
         { dir: path.join(homeDir, '.roo', 'skills'), key: 'vscode' },
-    ].filter((d) => d.key === null || detectedKeys.has(d.key) || fs.existsSync(d.dir));
+    ].filter((d) => d.key === null || detectedKeys.has(d.key));
 
     for (const { dir: dest } of extraSkillDestinations) {
         try {
@@ -1208,15 +1255,42 @@ function maskApiKey(key) {
     return key.substring(0, 4) + '...' + key.substring(key.length - 4);
 }
 
-async function promptCredentials(referenceMcpDir) {
-    if (isAutoYes) return { gemini: "", github: "", openwikiProvider: "google", openwikiModel: "", openwikiBaseUrl: "", keyEnvName: 'GEMINI_API_KEY' };
+// Provider -> its own API key env var name. Used both to find a previously
+// configured non-Google provider's key (loadExistingEnv only special-cased
+// Gemini/GitHub, so a Groq/Grok/NVIDIA/OpenAI/OpenRouter setup was invisible
+// to "keep existing" and silently looked unconfigured) and to build the
+// isAutoYes default without re-deriving the same mapping twice.
+const PROVIDER_KEY_ENV_NAMES = {
+    google: 'GEMINI_API_KEY', groq: 'GROQ_API_KEY', grok: 'XAI_API_KEY',
+    nvidia: 'NVIDIA_API_KEY', openrouter: 'OPENROUTER_API_KEY',
+    openai: 'OPENAI_API_KEY', ollama: null, custom: 'OPENWIKI_API_KEY',
+};
 
+async function promptCredentials(referenceMcpDir) {
     const existingEnv = loadExistingEnv(referenceMcpDir);
-    const existingGemini = existingEnv['GEMINI_API_KEY'] || existingEnv['GOOGLE_API_KEY'] || existingEnv['OPENWIKI_API_KEY'] || '';
     const existingGithub = existingEnv['GITHUB_PERSONAL_ACCESS_TOKEN'] || existingEnv['GITHUB_TOKEN'] || '';
     const existingProvider = existingEnv['OPENWIKI_PROVIDER'] || 'google';
     const existingModel = existingEnv['OPENWIKI_MODEL'] || '';
     const existingBaseUrl = existingEnv['OPENWIKI_BASE_URL'] || '';
+    const existingKeyEnvName = PROVIDER_KEY_ENV_NAMES[existingProvider] || 'OPENWIKI_API_KEY';
+    // Gemini/Google/OpenWiki-generic keys are also accepted as a fallback so
+    // an old config written before OPENWIKI_PROVIDER existed still resolves.
+    const existingGemini = existingEnv[existingKeyEnvName] || existingEnv['GEMINI_API_KEY'] || existingEnv['GOOGLE_API_KEY'] || existingEnv['OPENWIKI_API_KEY'] || '';
+
+    if (isAutoYes) {
+        // A non-interactive run (npx -y, or an --auto submodule install) must
+        // never silently discard a provider already configured on this
+        // machine -- this used to hard-reset to an empty Google/Gemini
+        // default on every unattended re-run, wiping a previously-chosen
+        // NVIDIA/Nemotron (or any other) provider and key each time.
+        if (existingGemini || existingProvider === 'ollama') {
+            return { gemini: existingGemini, github: existingGithub, openwikiProvider: existingProvider, openwikiModel: existingModel, openwikiBaseUrl: existingBaseUrl, keyEnvName: existingKeyEnvName };
+        }
+        // Nothing configured yet on this machine: default to NVIDIA NIM /
+        // Nemotron. Google was only ever a placeholder default, never the
+        // intended house default.
+        return { gemini: "", github: existingGithub, openwikiProvider: "nvidia", openwikiModel: "nvidia/llama-3.1-nemotron-70b-instruct", openwikiBaseUrl: "https://integrate.api.nvidia.com/v1", keyEnvName: 'NVIDIA_API_KEY' };
+    }
 
     const hasKeys = Boolean(existingGemini || existingGithub);
 
@@ -1243,7 +1317,7 @@ async function promptCredentials(referenceMcpDir) {
                 openwikiProvider: existingProvider,
                 openwikiModel: existingModel,
                 openwikiBaseUrl: existingBaseUrl,
-                keyEnvName: existingProvider === 'google' ? 'GEMINI_API_KEY' : 'OPENWIKI_API_KEY'
+                keyEnvName: existingKeyEnvName
             };
         }
     }
@@ -1928,6 +2002,25 @@ async function installCreatorExtension() {
     }
 }
 
+async function installHardwarePcb() {
+    const hwDir = path.join(moduleBasePath(), 'bdb-hardware-pcb');
+    if (!downloadOrUpdateModule('@hybridlabor-api/bdb-hardware-pcb', hwDir, 'BDB Hardware & PCB (KiCad + OpenSCAD)')) {
+        log.warn('Skipping Hardware & PCB setup: the module could not be downloaded.');
+        return;
+    }
+    if (DRY_RUN) {
+        log.step('[dry-run] would run BDB Hardware & PCB setup');
+        return;
+    }
+    const installerScript = path.join(hwDir, 'installer.js');
+    if (fs.existsSync(installerScript)) {
+        const setupResult = spawnSync('node', [installerScript, '--auto'], { stdio: 'inherit', cwd: hwDir });
+        if (setupResult.status !== 0) {
+            log.warn(`Hardware & PCB setup note: exit code ${setupResult.status}`);
+        }
+    }
+}
+
 async function installOSRemoteGateway() {
     const remoteDir = path.join(moduleBasePath(), 'bdb-os-remote');
     if (!downloadOrUpdateModule('@hybridlabor-api/bdb-os-remote', remoteDir, 'BDB OS Remote Gateway')) {
@@ -2074,9 +2167,10 @@ function verifyEcosystemInstallation() {
         { name: '3. heimdall-token-saver', pkg: '@hybridlabor-api/heimdall-token-saver', paths: [path.join(moduleBasePath(), 'heimdall-token-saver'), path.join(srcDir, 'vendor', 'token-saver')] },
         { name: '4. AO Agent Orchestrator', pkg: '@hybridlabor-api/bdb-agent-orchestrator', paths: [path.join(moduleBasePath(), 'bdb-agent-orchestrator')] },
         { name: '5. bdb-dev-creator-extension', pkg: '@hybridlabor-api/bdb-dev-creator-extension', paths: [path.join(moduleBasePath(), 'bdb-dev-creator-extension')] },
-        { name: '6. bdb-os-remote', pkg: '@hybridlabor-api/bdb-os-remote', paths: [path.join(moduleBasePath(), 'bdb-os-remote')] },
-        { name: '7. bdb-dev-tool-installer', pkg: '@hybridlabor-api/bdb-dev-tool-installer', paths: [path.join(moduleBasePath(), 'bdb-dev-tool-installer')] },
-        { name: '8. aos (bdb agent os)', pkg: '@hybridlabor-api/aos', paths: [srcDir] }
+        { name: '6. bdb-hardware-pcb', pkg: '@hybridlabor-api/bdb-hardware-pcb', paths: [path.join(moduleBasePath(), 'bdb-hardware-pcb')] },
+        { name: '7. bdb-os-remote', pkg: '@hybridlabor-api/bdb-os-remote', paths: [path.join(moduleBasePath(), 'bdb-os-remote')] },
+        { name: '8. bdb-dev-tool-installer', pkg: '@hybridlabor-api/bdb-dev-tool-installer', paths: [path.join(moduleBasePath(), 'bdb-dev-tool-installer')] },
+        { name: '9. aos (bdb agent os)', pkg: '@hybridlabor-api/aos', paths: [srcDir] }
     ];
 
     for (const mod of modules) {
@@ -3179,6 +3273,7 @@ async function promptOptionalModules(installedModules) {
             ? [{ id: 'ao', name: 'AO Agent Orchestrator (Session telemetry & WebUI)', fn: installOSAgentWorkspace }]
             : []),
         { id: 'creator', name: 'BDB Creator Extension (Generative 3D, Video & ComfyUI)', fn: installCreatorExtension },
+        { id: 'hardware', name: 'BDB Hardware & PCB (KiCad + OpenSCAD Electrical/PCB Design)', fn: installHardwarePcb },
         { id: 'installer', name: 'BDB Dev Tool Installer (Interactive Hub & CLI Launcher)', fn: installDevToolInstaller }
     ];
 
@@ -3520,7 +3615,7 @@ async function runQuickUpdate(installState) {
 
     fs.mkdirSync(backupDir, { recursive: true });
     fs.mkdirSync(paths.targetSkillDir, { recursive: true });
-    fs.mkdirSync(paths.targetLegacyDir, { recursive: true });
+    retireObsoleteLegacyDir(paths.targetLegacyDir);
     fs.mkdirSync(paths.targetWorkspaceDir, { recursive: true });
 
     // Initialize manifest for this update session.
@@ -3593,6 +3688,7 @@ async function runQuickUpdate(installState) {
         // 'ao' intentionally skipped here even for
         // existing installs -- see promptOptionalModules() for why.
         else if (subId === 'creator') await installCreatorExtension();
+        else if (subId === 'hardware') await installHardwarePcb();
         else if (subId === 'installer') await installDevToolInstaller();
     }
 
@@ -3945,7 +4041,7 @@ async function main() {
 
         installStep(`create the skill target directories (${t.value})`, () => {
             fs.mkdirSync(t.targetSkillDir, { recursive: true });
-            fs.mkdirSync(t.targetLegacyDir, { recursive: true });
+            retireObsoleteLegacyDir(t.targetLegacyDir);
             fs.mkdirSync(t.targetWorkspaceDir, { recursive: true });
         }, 'The skill copies below will most likely be skipped as well.');
 

package/lib/startup-ui.js

@@ -122,7 +122,9 @@ function buildTelemetryCard({ installState, detections, daemonStatus = [] }) {
     // 3. Installation State
     if (installState) {
         if (installState.isInstalled) {
-            const versionStatus = installState.updateAvailable
+            const versionStatus = installState.isDowngrade
+                ? `${BRAND.amber}⚠${BRAND.reset} ${BRAND.white}v${installState.localVersion}${BRAND.reset} installed ${BRAND.amber}(this payload is v${installState.currentVersion} — older, not an update)${BRAND.reset}`
+                : installState.updateAvailable
                 ? `${BRAND.amber}v${installState.localVersion}${BRAND.reset} ➔ ${BRAND.emerald}${BRAND.bold}v${installState.currentVersion}${BRAND.reset} ${BRAND.amber}(Update Available)${BRAND.reset}`
                 : `${BRAND.emerald}✔${BRAND.reset} ${BRAND.white}v${installState.currentVersion}${BRAND.reset} ${BRAND.dim}(Current & Up-to-date)${BRAND.reset}`;
             lines.push(`${G}  ${BRAND.lila}└─${BRAND.reset} ${BRAND.dim}Kernel State:${BRAND.reset}     ${versionStatus}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hybridlabor-api/aos",
-  "version": "4.4.2-beta.3",
+  "version": "4.4.2-beta.5",
   "description": "AOS — A Curated AI AGENT OS. Optimized agent skills and add-ons like memB, OpenWiki, Heimdall Token Saver, and Godmode architectures.",
   "main": "installer.js",
   "bin": {

package/scripts/validate-skills.mjs

@@ -13,7 +13,7 @@ const SKILLS = join(REPO, 'skills');
 
 const CATEGORIES = new Set([
   'design-ui-ux', 'engineering-method', 'media-eventtech',
-  'bdb-core', 'saas-ops', 'library',
+  'bdb-core', 'saas-ops', 'library', 'engineering-hardware',
 ]);
 const REQUIRED = ['name', 'description', 'category'];
 

package/skills/basic/godmode-hardware-pcb/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: godmode-hardware-pcb
+description: "Use when designing electrical schematics, PCB layouts, KiCad projects, or OpenSCAD enclosures — trace geometry, impedance, stackup, DFM/DRC/ERC sign-off, and hardware-software co-design boundaries."
+category: engineering-hardware
+---
+
+# ⚡ BDB Hardware & PCB Godmode
+
+This skill is the architectural authority for **Electrical Schematics, PCB Layout, Physical Constraints, and Manufacturing Sign-Off** in the AOS hardware engineering pipeline. It defines how agents must derive physical parameters from first principles, validate designs against IPC standards, and gate release to fabrication — without compromising on measurable, machine-checkable evidence.
+
+---
+
+## 1. Role & Architectural Boundaries
+
+* **Physical Design Authority:** Governs schematic capture, board layout, layer stackup, netclass definition, controlled-impedance routing, and DFM/DFA sign-off across KiCad-driven projects. Also governs parametric enclosure and mechanical co-design via OpenSCAD.
+* **Peer Integration:** Operates alongside `godmode-engineering` (firmware and software running on the board) and `godmode-eventtech` (live show-control hardware in the field) — this skill owns the board and enclosure itself, not the code that runs on it or the show that uses it. A request that touches firmware register maps or a live show's signal budget hands off to those peers instead of being re-derived here.
+* **No Informal Constraints:** A schematic or layout may never proceed on default trace widths, unconstrained nets, or "it looked fine in the 3D viewer." Every physical parameter traces back to a formula or a standard, not a guess.
+
+---
+
+## 2. Mathematical and Physical Foundations
+
+All trace geometry and thermal boundaries are derived from first principles and IPC standards, never estimated by eye:
+
+* **Trace Current Capacity (IPC-2152):** $I = k \cdot \Delta T^{0.44} \cdot A^{0.725}$, with $k = 0.048$ for external (convective) traces and $k = 0.024$ for internal (conductive-only) traces. A $2.5\text{A}$ DC rail at $\Delta T = 10^\circ\text{C}$ on $1\text{ oz}$ external copper needs $\approx 0.79\text{mm}$ trace width — not a rounded-up guess.
+* **Controlled Impedance (IPC-2141):** Single-ended microstrip $Z_0 = \frac{87}{\sqrt{\varepsilon_r + 1.41}} \ln\left(\frac{5.98h}{0.8w+t}\right)$; edge-coupled differential $Z_{diff} \approx 2Z_0\left(1 - 0.48e^{-0.96 s/h}\right)$. USB is a $90\Omega$ differential target, Ethernet/PCIe is $100\Omega$ — these are not interchangeable, and getting the pair spacing wrong by a fraction of $h$ misses the target by more than manufacturing tolerance forgives.
+* **DC IR Drop:** $R_{trace} = \rho \cdot L / (w \cdot t)$, $V_{drop} = I_{peak} \cdot R_{trace}$. On a $+3.3\text{V}$ rail, $V_{drop}$ must stay $\le 0.10\text{V}$ ($3\%$); if it doesn't, widen the trace or move the net to a copper flood — don't just note the number and move on.
+* **Crosstalk (the 3W rule):** center-to-center separation $D \ge 3w$ for parallel traces longer than $15\text{mm}$ keeps mutual coupling below a $70\%$ reduction threshold. This is the default spacing assumption for any signal or clock line, not an optional refinement.
+
+---
+
+## 3. Headless Validation — the Unforgiving Gate
+
+**No board may be released to fabrication on visual inspection or LLM self-attestation.** This is not a style preference; it's the same lesson this whole ecosystem has paid for repeatedly elsewhere: a clean-looking run is not evidence, a real exit code is.
+
+* **ERC:** `kicad-cli sch erc --exit-code-violations -o reports/erc_report.txt project.kicad_sch` — exit 0 means zero errors and zero unhandled warnings, not "looks connected."
+* **DRC:** `kicad-cli pcb drc --exit-code-violations --format json -o reports/drc_report.json board.kicad_pcb` — must show zero unrouted nets, zero clearance violations, zero broken annular rings, zero thermal spoke disconnections.
+* **DFM/DFA:** benchmark the layout against the target fab house's real capabilities (e.g. JLCPCB standard, PCBWay 4-layer minimum trace/space/via), not a generic "should be fine" assumption.
+* A non-zero exit code from any of the above is an immediate gate blockage — the pipeline halts, it does not continue with a caveat noted for later.
+
+---
+
+## 4. Dedicated MCP Tool Validation Requirement
+
+Before issuing schematic edits, layout changes, or fabrication exports, the agent MUST validate the required MCP servers are actually reachable — not assume they are because a config file lists them:
+
+1. **KiCad MCP:** validate the kicad-mcp-server responds over stdio (`tools/list` returns its full tool set — schematic editing, PCB layout, ERC/DRC execution, Gerber/BOM/CPL export) before issuing any node or netlist command.
+2. **OpenSCAD MCP:** validate the openscad-mcp-server responds before requesting parametric model generation, modification, or STL/3MF export for enclosure co-design.
+3. **Version awareness:** a stale or absent `kicad-cli` (KiCad 8+) or `openscad` binary on the host changes what's actually possible — check for it and say so plainly, rather than emitting commands that will fail downstream with no clear cause.
+
+---
+
+## 5. Hardware/Software Co-Design Boundary
+
+* PCB and enclosure design decisions here must stay coordinated with, but not encroach on, the firmware/software skills that consume the resulting pinout and register map — a GPIO reassignment on the board is a breaking change to firmware that already assumed the old pin, and must be flagged as such, not silently absorbed.
+* Mechanical (OpenSCAD) and electrical (KiCad) constraints are two halves of the same physical object: a connector placement that satisfies routing but collides with the enclosure wall is not a valid design, even if ERC/DRC both pass.
+
+---
+
+## Universal Agent Harness Integration
+
+This Godmode rulebook is universally available across the BDB ecosystem, installed alongside the `@hybridlabor-api/bdb-hardware-pcb` module (KiCad + OpenSCAD MCP servers, 5 companion skills under the `engineering-hardware` category):
+* **Claude Code / CLI Agents:** loaded during electrical, PCB, and enclosure design sessions.
+* **Peer skills:** `code-first-hardware-design`, `pcb-constraint-definition`, `pcb-layout-routing-automation`, `pcb-validation-dfm-signoff`, `schematic-datasheet-analysis`.
+
+## Overview
+This skill acts as the architectural authority for electrical and PCB design, enforcing IPC-standard physical constraints, headless validation gates, and hardware/software co-design boundaries.
+
+## When to Use
+- **Trigger:** The user is designing or modifying a schematic, PCB layout, layer stackup, netclass, or an OpenSCAD enclosure meant to house the board.
+- **Exclude:** Do not use for firmware/register-level software running on the board (hand off to `godmode-engineering`), or for live show-control signal routing in the field (hand off to `godmode-eventtech`).
+
+## Core Process
+1. Derive every trace width, impedance target, and clearance from the formulas above or a cited IPC standard — never from a rounded-up guess.
+2. Validate KiCad and OpenSCAD MCP servers are actually responsive before issuing edits.
+3. Run headless ERC and DRC with `--exit-code-violations`; treat any non-zero exit as a hard stop.
+4. Benchmark the layout against the real target fab house's DFM limits before calling a design release-ready.
+5. Cross-check the enclosure (OpenSCAD) against the board outline and connector placements (KiCad) before sign-off.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "0.25mm default trace width is fine for a power rail." | IPC-2152 current-capacity math, not the CAD tool's default, sets minimum trace width — a 2.5A rail needs ~0.79mm at 1oz copper, not the default. |
+| "The 3D viewer looks correct, so the board is done." | A visual check is not ERC/DRC. Only a headless run with `--exit-code-violations` and a real exit code is evidence. |
+| "USB and Ethernet differential pairs can use the same spacing." | USB targets 90Ω differential, Ethernet/PCIe targets 100Ω — same formula, different required spacing for the same dielectric height. |
+| "The GPIO can be reassigned in layout; firmware can just adapt." | A pin reassignment is a breaking change to any firmware that already assumed the old pinout — it must be flagged to the software side, not silently absorbed. |
+
+## Red Flags
+
+- Proceeding to layout with unconstrained nets or no defined netclasses.
+- Treating a clean-looking 3D render as equivalent to a passing ERC/DRC exit code.
+- Skipping DFM benchmarking against the actual target fab house's capabilities.
+- Changing a pinout or connector placement without flagging the firmware or enclosure impact.
+
+## Verification
+
+- [ ] Every load-bearing trace width/impedance/clearance traces back to a formula or IPC standard, not a default or a guess.
+- [ ] ERC and DRC were run headless with `--exit-code-violations`, and the actual exit code — not a description of the run — was checked.
+- [ ] KiCad and OpenSCAD MCP tool availability was validated before issuing edits.
+- [ ] DFM limits were checked against the real target fab house, not a generic assumption.
+- [ ] Any pinout/connector change was cross-checked against firmware assumptions and enclosure geometry.

package/skills/global_config/ask-tim/SKILL.md

@@ -84,6 +84,7 @@ If the user's intent matches one of these, jump to the corresponding section:
 * **"I'm managing the BDB SaaS multi-cloud fleet"** ➔ [BDB Ecosystem & SaaS Ops](#bdb-ecosystem--saas-ops)
 * **"I need Three.js, 3D, or motion work"** ➔ [Media & EventTech](#media--eventtech)
 * **"I need live event tech, TouchDesigner, or Resolume help"** ➔ [Media & EventTech](#media--eventtech)
+* **"I need PCB layout, schematic capture, or electrical/hardware design"** ➔ [Electrical & Hardware Design](#electrical--hardware-design)
 
 ---
 
@@ -304,6 +305,23 @@ Resolve and Premiere are interchangeable at this level: pick whichever is actual
 
 ---
 
+## 🔩 Electrical & Hardware Design
+
+Use these for schematic capture, PCB layout, and physical hardware design (KiCad, OpenSCAD).
+
+* **Top Picks:** `godmode-hardware-pcb`, `code-first-hardware-design`, `pcb-constraint-definition`
+
+* **Architectural authority**: `godmode-hardware-pcb` — enforces IPC-standard trace/impedance/stackup math and the headless ERC/DRC/DFM sign-off gate across the skills below; load it before starting schematic or layout work.
+* **Circuit synthesis & enclosures**: `code-first-hardware-design` — programmatic schematic capture (SKiDL, netlists, S-expressions) and parametric 3D CAD enclosure co-design (OpenSCAD/BOSL2).
+* **Constraints & stackup**: `pcb-constraint-definition` — translates hardware requirements into layer stackup, netclasses, impedance matching, and custom DRC rules before layout starts.
+* **Layout & routing**: `pcb-layout-routing-automation` — floorplanning, component placement, high-speed differential pair routing, thermal via arrays, and keepout enforcement.
+* **Validation & sign-off**: `pcb-validation-dfm-signoff` — automated DRC/ERC, SI/PI screening, fab house DFM/DFA compliance, and production release sign-off (Gerbers/BOM/CPL).
+* **Schematic & datasheet auditing**: `schematic-datasheet-analysis` — electrical rule auditing, datasheet grounding, pinout validation, and power tree tracing.
+
+These ship in the separate `@hybridlabor-api/bdb-hardware-pcb` power-up module (KiCad + OpenSCAD MCP servers), not in this base skills package — install it as an optional AOS module when hardware work comes up.
+
+---
+
 ## 🛡️ Overlap: The Supreme Godmodes
 
 When do you use a `godmode-*` skill versus a narrower skill?