KiCad - the KiCad Bridge

@@ -99,6 +99,27 @@ subprocess (like kicad-cli) — NOT AD's gated `run_script`.  **Dispatcher special cases** (`dispatch_command`): `readiness`, `describe`, `check_for_updates` return BEFORE the plugin auto-install + the KiCad-not-installed pre-check (they must work with KiCad absent). `upgrade` also bypasses that pre-check (it INSTALLS KiCad — do not gate the installer behind "KiCad not installed") and refreshes the detection cache on success. +### ⚖️ Every file you add to this repo may ship to every AD user++The release zip is **auto-bundled into Adom Desktop**, so repo weight is user-facing weight. Before+adding a file, know which artifact it belongs to:++| Adding… | Goes in | Ships in the zip? |+|---|---|---|+| handler / runtime `.py` | repo root / `handlers/` | **yes** |+| a data file the code READS (e.g. `templates/blank-board.kicad_pcb`) | `templates/` | **yes** — and it must be in the zip or the verb breaks at runtime |+| a `.ps1` a handler shells out to | repo root | **yes** |+| docs, tutorials, demo scripts, screenshots, hero art, fonts, sample projects, videos | `docs/`, `demo/`, `tour-pack*/` | **NO** |+| a skill (user/dev/publish) | `skills/<name>/SKILL.md` | **NO** — skills ride the container **pkg**; duplicating them in the zip is the #1 source of bloat |++If a new verb needs a data file, put it in `templates/` and confirm it survives the zip's exclusion+filter — the publish skill's §2 KEEP list must name it. (`kicad_export_molecule` is the worked+example: pure code + the existing `kicad-cli`, no new assets.)++Audit 2026-07-19 found **649 KB** of never-referenced weight (219 KB of hero *fonts*, five+duplicated `skills/` trees, demo docs in the zip; 496 KB of PNGs in the pkg). Don't re-grow it —+full KEEP/EXCLUDE policy lives in `kicad-bridge-publish` §2/§4.+ ## Fresh-machine gotchas (all hard-won, all fixed — don't regress them)  - **Install scope is mandatory.** KiCad 10's NsisMultiUser installer: bare `/S` = `rc=666660` (invalid params). Pass `/allusers /S` (elevated) or `/currentuser /S` (per-user, `%LOCALAPPDATA%\Programs\KiCad`, **no UAC**). See `handlers/upgrade.py`.@@ -120,6 +141,16 @@ subprocess (like kicad-cli) — NOT AD's gated `run_script`.  `refresh_bridges {name:kicad}` pulls the new cache; the RUNNING instance keeps its old code until it dies — `bridge_kill {name:kicad}` forces a fresh spawn that loads the new version and re-detects. The first verb after a kill returns a `bridge_starting` envelope — retry. Confirm the running version via `bridge_log_read` ("starting v0.9.xx"). +**Smoke test that a repackaged zip is COMPLETE** (run after any change to the zip's file set — a+missing data file only shows up at runtime, not at build):++1. Static: every local import in the zip resolves inside the zip, and each data file the code reads+   (`certs/cacert.pem`, `templates/blank-board.kicad_pcb`, `*.ps1`) is present.+2. Live, on a real target: `kicad_describe` → expected **verb count** (44 @ v0.9.62 — a drop means a+   handler failed to import), then call one verb that touches a data file.+3. "KiCad is not installed" from a verb is the correct **guard**, not a packaging failure — don't+   chase it as a regression. Check `kicad_readiness.detected` to tell the two apart.+ ## Hard-won field notes (winvm full-battery, 2026-07)  **Headless / GPU-less VM 3D rendering — deploy Mesa llvmpipe.** KiCad's 3D viewer needs

@@ -61,9 +61,24 @@ adom-wiki release create adom/adom-desktop-kicad-bridge <ver> \  ## 4. Publish the skills pkg (container docs) -**The pkg is skills-only — it is NOT the bridge.** Say so in `package.json` `description` and at-the top of the README: the pkg teaches a container agent the `kicad_*` verbs; the **release zip**-is what AD downloads and runs as the bridge runtime. Users conflate them constantly.+**The pkg is skills-only — it is NOT the bridge.** The pkg teaches a container agent the `kicad_*`+verbs; the **release zip** is what AD downloads and runs as the bridge runtime. Users conflate them+constantly, so say it — but say it in **ONE LINE**.++⚠️ **`description` is rendered inside the page's Install card. Keep it to one or two sentences.**+A paragraph there is worse than saying nothing — it buries the install command in a wall of text.+(Learned the hard way 2026-07-19: a 486-char description explaining the whole two-artifact model+turned the Install card into an unreadable block; John: *"you're overdoing it with that install+description."* Cut to 145 chars.) The full explanation belongs in the README body, not the card.++Canonical description — copy this shape:++> Skills for your container so your AI knows how to drive the KiCad bridge.+> The bridge runtime itself is the release zip — Adom Desktop loads that.++The longer version (the "Two artifacts on this page — which one do you want?" comparison table:+what it is / who loads it / contains / do you install it manually, closing with **"The package is+not the bridge."**) lives near the TOP of `README.md`, where there's room for it.  **No images in the pkg.** The README references page art by ABSOLUTE `https://wiki.adom.inc/blob/app/adom-desktop-kicad-bridge/<name>.png` URLs, so the PNGs render on@@ -111,7 +126,38 @@ VM** (e.g. ADOMBASELINE) whenever the UI/flow changes — never hand-mock them:    `curl -so /dev/null -w '%{http_code}'` each blob URL to confirm 200. 5. `shotlog paste <png> -c kicad-bridge -d "<caption>"` to show John the live captures. -## 7. Standing rules+## 7. Showing the published page to John (pup)++**pup opens windows in the BACKGROUND by default.** `foreground: true` on `browser_open_window` is+the ONLY thing that puts a window on his screen — maximizing, sizing, `browser_alert_window`+(taskbar flash) and `browser_raise_os_window` do NOT. (2026-07-19: he asked "show me in pup" three+times because the window was open, correct and maximized — but behind everything.)++- He asked to be shown → open with `foreground: true`, then `desktop_set_window_state maximize` ONCE.+  (`state` accepts `maximize|minimize|restore` — there is **no** `"foreground"` state.)+- The standing "never foreground a window he already has" rule protects windows **he** is using; it+  does not apply to a window you just opened because he asked to see something.+- Sessions die between turns — `browser_list_windows` first; if the session is gone, open fresh+  rather than `browser_navigate` into a dead sessionId.+- **Never touch a session another AI thread owns** (you'll see unfamiliar sessionIds like+  `wiki-lockdemo`, `plate-out`). Open your own.+- Multiple pages → ONE maximized window, `browser_open_tab` per page, land on the important tab.+- Then `adom-shotlog inject` each capture and hand him the phone URL+  (`SHOTLOG_AD_TARGET=AdomLapper adom-shotlog open --channel <ch>` when several desktops are connected).++## 8. Upstream: what the SDK still owes every bridge++Two issues are open on `adom/adom-desktop-bridges` (filed 2026-07-19) — if you hit these problems,+they're known, and the fix belongs in the SDK, not just here:++1. **SDK should require every bridge to explain pkg-vs-zip** (one line, on the page + in+   `package.json.description`). The SDK documents the artifacts ("Artifact 1 — the RUNTIME…") but+   never tells authors to explain them to users, so no page does.+2. **SDK should document artifact hygiene** — the KEEP/EXCLUDE policy in §2 + the no-images-in-pkg+   rule in §4, ideally enforced by a `bridge lint` that fails on images/videos/archives in either+   artifact.++## 9. Standing rules  - Commit source to `main` in lockstep with each publish (drift = the bug that once dropped `updateManifestUrl`). - After ANY wiki change, refresh the wiki pup window showing the page.