@hybridlabor-api/aos 4.6.0 → 4.6.2

package/installer.js

@@ -2002,8 +2002,27 @@ async function installOpenWikiVisualizer() {
         return;
     }
     if (!hasExecutable('openwiki')) {
-        log.warn('Skipping OpenWiki Visualizer setup: the openwiki CLI was not found on PATH. Install it with: npm install -g openwiki@latest');
-        return;
+        // Fresh machines always land here -- skipping leaves :4321 dead with
+        // only a warn line. Offer the global install instead.
+        let installCli = isAutoYes;
+        if (!isAutoYes) {
+            const answer = await askConfirm({
+                message: 'OpenWiki CLI not found. Install it globally (npm install -g openwiki@latest) so the :4321 visualizer daemon can run?',
+                initialValue: true,
+            });
+            installCli = !isCancel(answer) && !!answer;
+        }
+        if (installCli) {
+            try {
+                log.step('Installing OpenWiki CLI globally (npm install -g openwiki@latest)...');
+                execSync('npm install -g openwiki@latest', { stdio: 'ignore' });
+            } catch (e) { logDebug(e, 'openwiki cli install'); }
+        }
+        if (!hasExecutable('openwiki')) {
+            log.warn('Skipping OpenWiki Visualizer setup: the openwiki CLI is not on PATH. Install it with: npm install -g openwiki@latest');
+            return;
+        }
+        log.ok('OpenWiki CLI installed.');
     }
     // launchd starts agents with a minimal PATH that never includes npm's global
     // bin dir, so resolve the absolute binary path now instead of relying on PATH at boot.
@@ -2013,6 +2032,79 @@ async function installOpenWikiVisualizer() {
         openwikiBin = execSync(lookup, { encoding: 'utf8' }).split(/\r?\n/)[0].trim() || 'openwiki';
     } catch (e) { logDebug(e, 'openwiki path lookup'); }
 
+    // The openwiki CLI is a Node script (#!/usr/bin/env node shebang). Under
+    // launchd's minimal PATH there is no node either, so the agent died with
+    // "env: node: No such file or directory" (exit 127) on every boot until
+    // the interpreter itself is baked in as an absolute path.
+    let nodeBin = 'node';
+    try {
+        const lookup = process.platform === 'win32' ? 'where node' : 'command -v node';
+        nodeBin = execSync(lookup, { encoding: 'utf8' }).split(/\r?\n/)[0].trim() || 'node';
+    } catch (e) { logDebug(e, 'node path lookup'); }
+
+    // Which wiki :4321 serves is per-machine setup configuration, not a
+    // hardcoded path: every computer tracks different projects, and bare
+    // `openwiki visualize` only serves ~/openwiki, which never exists (the
+    // agent then exits 1 with "Wiki directory not found"). The choice is
+    // persisted in ~/.openwiki/visualizer.json so Quick Update reuses it
+    // without asking again; the bundled ecosystem aggregate is only the
+    // first-run default.
+    const visualizerConfigPath = path.join(homeDir, '.openwiki', 'visualizer.json');
+    const looksLikeWiki = (dir) => fs.existsSync(path.join(dir, 'index.md'))
+        || fs.existsSync(path.join(dir, 'openwiki'))
+        || fs.existsSync(path.join(dir, '.openwiki'));
+    const readVisualizerConfig = () => {
+        try {
+            const raw = JSON.parse(fs.readFileSync(visualizerConfigPath, 'utf8'));
+            if (raw && typeof raw.wikiPath === 'string' && fs.existsSync(raw.wikiPath)) return raw.wikiPath;
+        } catch (e) { logDebug(e, 'visualizer config read'); }
+        return null;
+    };
+    const writeVisualizerConfig = (wikiPath) => {
+        try {
+            fs.mkdirSync(path.dirname(visualizerConfigPath), { recursive: true });
+            fs.writeFileSync(visualizerConfigPath, JSON.stringify({ wikiPath, updatedAt: new Date().toISOString() }, null, 2));
+        } catch (e) { logDebug(e, 'visualizer config write'); }
+    };
+    let wikiPath = readVisualizerConfig();
+    const ecosystemWiki = path.join(homeDir, '.openwiki', 'ecosystem-wiki');
+    const syncScript = path.join(srcDir, 'skills', 'global_config', 'openwiki-skill', 'scripts', 'sync_ecosystem_wiki.py');
+    if (!wikiPath) {
+        if (looksLikeWiki(ecosystemWiki)) {
+            wikiPath = ecosystemWiki;
+        } else if (fs.existsSync(syncScript) && hasExecutable('python3')) {
+            try {
+                execSync(`python3 "${syncScript}"`, { stdio: 'ignore' });
+                if (looksLikeWiki(ecosystemWiki)) wikiPath = ecosystemWiki;
+            } catch (e) { logDebug(e, 'ecosystem wiki sync'); }
+        }
+        if (!wikiPath && !isAutoYes) {
+            const answer = await text({
+                message: `Which wiki should the :4321 visualizer serve? (directory) [default: ${ecosystemWiki}]`,
+                placeholder: ecosystemWiki,
+            });
+            if (!isCancel(answer) && answer && answer.trim()) {
+                const candidate = answer.trim().replace(/^~(?=$|\/|\\)/, homeDir);
+                if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) {
+                    wikiPath = candidate;
+                    if (!looksLikeWiki(candidate)) {
+                        log.warn(`No wiki markers found in ${candidate} — the daemon may exit until a wiki is generated there.`);
+                    }
+                } else {
+                    log.warn(`Directory not found: ${candidate} — continuing without a visualizer path.`);
+                }
+            }
+        }
+    }
+    if (wikiPath) {
+        writeVisualizerConfig(wikiPath);
+    } else {
+        log.warn('OpenWiki Visualizer: no servable wiki configured — registering without a path, the daemon will exit until a wiki exists.');
+    }
+    const visualizeArgs = wikiPath
+        ? `<string>${nodeBin}</string>\n        <string>${openwikiBin}</string>\n        <string>visualize</string>\n        <string>${wikiPath}</string>\n        <string>--port</string>`
+        : `<string>${nodeBin}</string>\n        <string>${openwikiBin}</string>\n        <string>visualize</string>\n        <string>--port</string>`;
+
     if (process.platform === 'darwin') {
         const plistPath = path.join(homeDir, 'Library', 'LaunchAgents', 'com.bdb.openwiki-visualize.plist');
         const plistContent = `<?xml version="1.0" encoding="UTF-8"?>
@@ -2023,9 +2115,7 @@ async function installOpenWikiVisualizer() {
     <string>com.bdb.openwiki-visualize</string>
     <key>ProgramArguments</key>
     <array>
-        <string>${openwikiBin}</string>
-        <string>visualize</string>
-        <string>--port</string>
+        ${visualizeArgs}
         <string>4321</string>
         <string>--no-open</string>
     </array>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hybridlabor-api/aos",
-  "version": "4.6.0",
+  "version": "4.6.2",
   "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",
   "engines": {

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

@@ -57,46 +57,100 @@ Before issuing schematic edits, layout changes, or fabrication exports, the agen
 
 ---
 
+## 6. Iterative Visual Loop — Render as Complement, Not Gate
+
+A render never replaces ERC/DRC, but every edit must be seen before the next
+one lands. Generate in small batches, render after each batch, and compare
+against the reference with a vision-capable model before continuing:
+
+1. **Orient first:** locate project files (the kicad-project-find helper in
+   the companion module, or raw `find` for `*.kicad_pro`, `*.kicad_sch`,
+   `*.kicad_pcb`), then report `kicad-cli` path and version. If `kicad-cli`
+   is absent, stop and say `BLOCKED` — do not emit commands that will fail
+   downstream.
+2. **Small batches:** place or edit at most 5–10 components per batch, on a
+   fixed 0.5mm or 1mm placement grid. Never generate a whole schematic or
+   board in one shot.
+3. **Render after every batch:**
+   - schematic: `kicad-cli sch export svg --output out/ design.kicad_sch`
+   - board layers: `kicad-cli pcb export svg --output out/ board.kicad_pcb`
+   - board 3D: `kicad-cli pcb render --output board-top.png board.kicad_pcb`
+   - The companion module ships these as the kicad-render, kicad-drc-json,
+     and kicad-erc-json helper scripts.
+4. **Vision diff:** load the fresh render into the vision model alongside the
+   reference (photo, datasheet figure, or schematic from the web). On chaos —
+   overlapping symbols, nets crossing the sheet, decoupling far from pins —
+   fix before the next batch.
+5. **Machine checks per batch:** `kicad-cli sch erc` and `kicad-cli pcb drc`
+   with `--exit-code-violations`. Unconnected-pin warnings after a messy
+   batch are worked off systematically, not batched up for the end.
+6. **Substrate routing:** live board/session edits prefer `kicad-python` IPC;
+   render, export, DRC/ERC, and fabrication outputs use `kicad-cli`;
+   deterministic offline file edits use a structured S-expression parser
+   (e.g. `kiutils`), never hand-rolled regex on `.kicad_sch` / `.kicad_pcb`.
+7. **Evidence report:** close every batch with target, commands run, artifact
+   paths, check outputs, and one of
+   `DONE` / `DONE_WITH_CONCERNS` / `BLOCKED` / `NEEDS_CONTEXT`.
+
+### Shared placement preamble (applies to every schematic/layout batch)
+
+- Schematic flow goes left to right (inputs left, outputs right); VCC points
+  up, GND points down; use global labels or hierarchical sheets instead of
+  dragging dozens of wires across the sheet.
+- Every decoupling capacitor sits on the same layer as its IC, within 1.5mm
+  of the power pin, in the sequence rail-via → cap pad → IC pin.
+- Reverse-engineering work (rebuilding a board photo or web schematic in
+  KiCad) routes to `schematic-reverse-engineering` first: identify parts via
+  a parts source, record manufacturer part numbers, verify symbol/footprint
+  visually before use, and never invent pinouts from memory.
+
 ## 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):
+This Godmode rulebook is universally available across the BDB ecosystem, installed alongside the `@hybridlabor-api/bdb-hardware-pcb` module (KiCad + OpenSCAD MCP servers, 6 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`.
+* **Peer skills:** `code-first-hardware-design`, `pcb-constraint-definition`, `pcb-layout-routing-automation`, `pcb-validation-dfm-signoff`, `schematic-datasheet-analysis`, `schematic-reverse-engineering`.
 
 ## 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.
+This skill acts as the architectural authority for electrical and PCB design, enforcing IPC-standard physical constraints, iterative visual verification, 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.
+- **Trigger:** The user is designing or modifying a schematic, PCB layout, layer stackup, netclass, or an OpenSCAD enclosure meant to house the board — including rebuilding a board photo or web schematic in KiCad.
 - **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.
+2. Validate KiCad and OpenSCAD MCP servers are actually responsive before issuing edits; confirm `kicad-cli` path and version.
+3. Work in batches of at most 5–10 components on a fixed grid; render after every batch and vision-diff against the reference before continuing (see section 6).
+4. Run headless ERC and DRC with `--exit-code-violations` per batch; treat any non-zero exit as a hard stop.
+5. Benchmark the layout against the real target fab house's DFM limits before calling a design release-ready.
+6. 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. |
+| "The 3D viewer looks correct, so the board is done." | A render complements ERC/DRC, it never replaces them. A clean render with a non-zero ERC/DRC exit code is still BLOCKED; a passing exit code with no render is DONE_WITH_CONCERNS. |
+| "Rendering every few components slows me down; one big generation is faster." | One-shot generation produces overlapping symbols and unconnected pins that cost more to untangle than batches of 5–10 with a render between them. |
 | "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.
+- Generating a whole schematic or board in one shot with no intermediate render.
 - Treating a clean-looking 3D render as equivalent to a passing ERC/DRC exit code.
+- Skipping the vision diff against the reference photo or schematic after a batch.
 - Skipping DFM benchmarking against the actual target fab house's capabilities.
 - Changing a pinout or connector placement without flagging the firmware or enclosure impact.
+- Inventing a footprint or pinout from memory when a parts source was available.
 
 ## Verification
 
 - [ ] Every load-bearing trace width/impedance/clearance traces back to a formula or IPC standard, not a default or a guess.
+- [ ] Work proceeded in batches of at most 5–10 components with a render and vision diff per batch; artifact paths are reported.
 - [ ] 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.
+- [ ] KiCad and OpenSCAD MCP tool availability was validated before issuing edits; `kicad-cli` path and version are on record.
 - [ ] 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.
+- [ ] Reverse-engineered parts cite a real manufacturer part number and source, not memory.