KiCad - the KiCad Bridge

@@ -1,7 +1,7 @@ --- name: adom-desktop-kicad public: true-description: "Launch and drive KiCad on the user's laptop (KiCad 7/8/9/10 supported, multi-version side-by-side) from this container via the adom-bridge CLI. Open schematics/boards/symbols/footprints, run DRC, install sym-lib-table / fp-lib-table libraries, show the 3D viewer, capture KiCad window screenshots, send keyboard shortcuts and click coordinates. Trigger words: kicad, open schematic, open board, open pcb, open symbol, open footprint, KiCad symbol editor, KiCad footprint editor, KiCad 3D viewer, run DRC, install KiCad library, sym-lib-table, fp-lib-table, KiCad screenshot, kicad_send_key, kicad_click, kicad_window_info, kicad_screenshot_all, close KiCad, kicad versions, kicad_list_versions, KiCad bridge."+description: "Launch and drive KiCad on the user's laptop (KiCad 7/8/9/10 supported, multi-version side-by-side) from this container via the adom-bridge CLI. Open schematics/boards/symbols/footprints, run DRC, install sym-lib-table / fp-lib-table libraries, show the 3D viewer, capture KiCad window screenshots, send keyboard shortcuts and click coordinates. Trigger words: kicad, open schematic, open board, open pcb, open symbol, open footprint, KiCad symbol editor, KiCad footprint editor, KiCad 3D viewer, run DRC, install KiCad library, sym-lib-table, fp-lib-table, KiCad screenshot, kicad_send_key, kicad_click, kicad_window_info, kicad_screenshot_all, close KiCad, kicad versions, kicad_list_versions, KiCad bridge, PCM, Plugin and Content Manager, PCM repository, kicad_pcm_install, kicad_pcm_add_repository, PCM update." ---  # adom-bridge: KiCad bridge@@ -104,7 +104,7 @@ If you pass a version that's not installed, the bridge returns a hint listing th | `kicad_run_drc` | `run_drc` | Run DRC on the current board, return violations | `filePath`, optional `kicadVersion` | | `kicad_fix_keyboard` | `fix_keyboard` | Workaround stuck-modifier bug after screen lock |: | | `kicad_screenshot_all` | `screenshot_all` | Capture every open KiCad window (lossless PNGs) |: |-| `kicad_send_key` | `send_key` | Single key to an EXACT `hwnd` (e.g. Enter/Escape to a dialog). For modifier CHORDS ("ctrl+s", "alt+3") use Bridge's `desktop_press_key`: don't route chords here. | `hwnd`, `key` |+| `kicad_send_key` | `send_key` | Single key to an EXACT `hwnd` (e.g. Enter/Escape to a dialog). For modifier CHORDS ("ctrl+s", "alt+3") use Bridge's `desktop_press_key`: don't route chords here. From 1.0.2 `menu` fires a menu item by label substring on the window's menu bar, background, no focus change (see "PCM repositories on the wiki") | `hwnd`, `key` or `menu` | | `kicad_click` | `click` | Send a click at (x, y) in a KiCad window | `hwnd`, `x`, `y` | | `kicad_adom_library_status` | `adom_library_status` | Report whether the Adom shared library is registered |: | | `kicad_adom_library_heal` | `adom_library_heal` | Reconcile the Adom library: `mode` merge (default) / repoint / prune; `dryRun` previews. From 0.9.279 `prune` drops symbols KiCad refuses | `mode`, `dryRun` |@@ -307,6 +307,31 @@ Every response: `success`, `output`, `path`, `backup`, `uuid`, `erc {ran, before - **`ai` is the recommendation.** It returns a plan request (pads, nets with their pads, the live routing state when the PCB editor has the board open) and mutates nothing; you then route with `kicad_route_net`, one native undo step per trace, DRC-checked per step, and you can explain every trace. Frontier models route real boards this way (the recorded Astra runs on the adom/codex page rebuilt a 94-footprint board to zero unconnected items). - **`freerouting`** is for the user who wants a deterministic pass. It is not installed by default: `kicad_freerouting {"action":"status"|"install"|"uninstall"}` fetches Freerouting's own bundle (88 MB download, 141 MB on disk, its own Java runtime inside, nothing installed on the PC, no UAC) into the bridge cache only when the user says yes, and removes it on its own. The full choice, the AI recipe and the verification rules are in the `kicad-autorouting` skill. +## PCM repositories on the wiki (from 1.0.2)++KiCad's Plugin and Content Manager (PCM) installs libraries and plugins from a "repository", which is three files behind anonymous HTTPS GETs: `repository.json`, `packages.json` and one zip per version. Every wiki page serves its files that way, so a wiki page IS a PCM repository, and a release is a version bump plus `adom-wiki repo push`. The bridge drives the same registry and the same 3rdparty folder KiCad's own dialog uses, so the two stay in agreement. The worked example, proven end to end on KiCad 10.0.5, is [docs/pcm.md](docs/pcm.md); its sample repository URL is `https://wiki.adom.inc/api/pages/adom/kicad-bridge/files/pcm/repository.json` and its package identifier is `com.adom.kicad-bridge.sample-lib`.++| Verb | Args | Key output |+|---|---|---|+| `kicad_pcm_add_repository` | `url`, optional `name` | `added`, `alreadyRegistered`, `name`, `repositoryId`, `verified` (the repository.json was fetched and is one), `file`, `backup` (`kicad.json.adom-bak`), `repositories[]`, `restartNeeded` |+| `kicad_pcm_remove_repository` | `url` | `removed`, `backup`, `repositories[]`. Packages installed from it stay installed |+| `kicad_pcm_list` | optional `checkUpdates` (default true) | per package `version`, `latestVersion`, `updateAvailable`, `updateCheck` (`ok`, `pinned`, `repository_not_registered`, `package_not_in_repository`, `fetch_failed`), `repositoryUrl`; top-level `count`, `updatesAvailable`, `repositories[]` |+| `kicad_pcm_install` | `identifier`, optional `repositoryUrl`, `version`, `update`, `libPrefix`, `force` | `version`, `installedTo`, `symbolLibraries`, `footprintLibraries`, `restartNeeded`; with `update:true` either `upToDate:true` or `previousVersion`, `version`, `updated:true` |+| `kicad_pcm_uninstall` | `identifier` | `removedDirs`, `recordRemoved`, `restartNeeded` |++The flow, in the order a user asks for it:++1. **Register**: `kicad_pcm_add_repository '{"url": REPO_URL}'`. Idempotent (`alreadyRegistered:true` on a second call). It edits `kicad.json`, which a running KiCad overwrites on exit, so do it with KiCad closed, or tell the user KiCad's own dialog (Plugin and Content Manager > Manage) is the alternative while it runs. `restartNeeded:true` is always reported: KiCad reads the list at start.+2. **Install**: `kicad_pcm_install '{"repositoryUrl": REPO_URL, "identifier": ID}'`. Newest version compatible with the detected KiCad unless `version` pins one; zip verified against `download_sha256`; unpacked under the 3rdparty root; the row written to `installed_packages.json` with the same `repository_id` KiCad computes, which is why KiCad's own dialog then shows the package as Installed. KiCad registers the `PCM_<name>` library rows itself on its next start (`pcm.lib_auto_add`).+3. **Check for updates**: `kicad_pcm_list '{}'`. `updatesAvailable` above 0 means a newer version is served; the per-package row says which (`latestVersion`) and `updateCheck` says why a check could not run.+4. **Update**, two ways, the user picks:+   - **Headless**: `kicad_pcm_install '{"identifier": ID, "update": true}'`. Resolves the repository from the installed row (no `repositoryUrl` needed), replaces the version on disk and in the registry, answers `previousVersion`, `version`, `updated:true`. KiCad's own PCM dialog shows the new version the next time it opens (no restart), and an editor shows the new content on its next open. `upToDate:true` means nothing to do.+   - **In KiCad**: tell the user that KiCad's PCM dialog shows the Update button on the package after a restart (its update check runs at startup, and the Refresh button inside an already open dialog does not recompute that flag). Update All, then Apply Pending Changes, then Close: KiCad writes `installed_packages.json` when the dialog closes, so `kicad_pcm_list` agrees only after Close.++To open the PCM dialog for a screenshot without touching the user's focus: `kicad_send_key '{"menu": "Plugin and Content Manager"}'` on the project manager (pass `hwnd` from `kicad_window_info` when more than one KiCad window is up), then `kicad_screenshot_all '{}'` captures the dialog as a child of that window. The same `menu` arg fires any menu item by label substring (`{"menu": "zoom to fit"}` on an editor). Two related facts from 1.0.2: the automatic dialog sweep leaves windows the user opened on purpose alone (the PCM dialog, "Applying Package Changes", Preferences, Manage Symbol/Footprint Libraries, Configure Paths, Board Setup, Schematic Setup, Symbol Fields Table, Design Rules), and `kicad_dismiss_dialogs '{"dismissAll": true}'` is the call that still closes them. Inside the PCM dialog, UI Automation reaches the tabs (`desktop_ui_select` with `role:"tab"`) and the "Update All", "Apply Pending Changes", "Refresh" and "Close" buttons (`desktop_ui_click`); the per-card Update button is not exposed to UIA.++Publishing your own repository (the packer, the layout, the release loop, and what bit): [docs/pcm.md](docs/pcm.md).+ ## Rescan after installs: `kicad_rescan_libraries`  Install N parts, call this once, then show them all (wiki #51). It reloads every open editor's library tree in place (seconds, nothing closed) and, given `footprints: ["Lib:Name", ...]`, loads each in the Footprint Editor as proof (`verified`, `probed[]`). `force: true` is the process restart and refuses while KiCad runs unless `confirmRestart: true`.

⋯ 1 unchanged line ⋯

⋯ 1 unchanged line ⋯

⋯ 1 unchanged line ⋯

⋯ 1 unchanged line ⋯

⋯ 1 unchanged line ⋯

⋯ 1 unchanged line ⋯

⋯ 1 unchanged line ⋯

⋯ 1 unchanged line ⋯

@@ -289,3 +289,6 @@ Total: roughly 18 to 21 weeks of one AI thread's time with human test time on th - [How the bridge compares](comparison.md): the competitive audit this plan was written alongside. - [Dashboard](dashboard.md): the dock card and the dashboard. - Verb reference and the live routing contract: the main [README](../README.md) and [SKILL.md](../SKILL.md).++- 2026-09-12 (later): comparison.md reworked after John's review. The three "where others lead" items are now "three claims we chose not to match" (KiCad reads its own files, permissions live in the AI harness and in ab, discovery is skills plus describe plus wiki auto-discovery). SPICE simulation added as the one open gap with an ecosystem-wide plan (ngspice runner in the container, kicad_export_spice, kicad_simulate); verified kicad-cli spice export and bundled ngspice on ConfRoomROG. PCM proof in progress (sample repository on the page, install, bump, update).+- 2026-09-12 (later): PCM proof passed end to end on ConfRoomROG (KiCad 10.0.5) and is written up in [pcm.md](pcm.md). The sample repository on this page (three anonymous files, `no-cache` JSON) was registered with `kicad_pcm_add_repository`, installed with `kicad_pcm_install` (1.0.0, `PCM_Adom_Sample` registered by KiCad itself on launch), bumped to 1.1.0 with the packer and pushed, seen by `kicad_pcm_list` (`updatesAvailable: 1`) and by KiCad's own PCM dialog after a restart (Update button on the card), updated the user's way through UI Automation (Update All, Apply Pending Changes, Close) with the Symbol Editor showing `R v1.1.0`, then bumped to 1.2.0 and updated headlessly with `kicad_pcm_install {update:true}` (`previousVersion 1.1.0, version 1.2.0, updated true`), which KiCad's dialog showed without a restart. Two fixes came out of it, both in the build that ships as 1.0.2: the automatic dialog sweep no longer closes tool windows opened on purpose (it had pressed Close on "Applying Package Changes" mid-apply and aborted the first update), and `kicad_send_key` gained `menu` (a label substring fired on the window's menu bar as a background menu command; how the PCM dialog is opened). New verbs: `kicad_pcm_add_repository`, `kicad_pcm_remove_repository`, `kicad_pcm_list` with the update check, `kicad_pcm_install {update:true}`; documented in SKILL.md under "PCM repositories on the wiki" and covered by the verb runner (real add in phase 4, conditional remove in phase 6). Three KiCad facts recorded for the port: `installed_packages.json` is written when the PCM dialog closes, Refresh inside an open dialog does not recompute the installed-package update flag (the startup check does), and the per-card Update button is not exposed to UIA while Update All, Apply Pending Changes, Refresh and Close are.

@@ -244,7 +244,7 @@ dependencies = [  [[package]] name = "kicad-bridge"-version = "1.0.1"+version = "1.0.2" dependencies = [  "kicad-core",  "kicad-platform",@@ -255,7 +255,7 @@ dependencies = [  [[package]] name = "kicad-core"-version = "1.0.1"+version = "1.0.2" dependencies = [  "kicad-ipc-rs",  "kicad-platform",@@ -280,7 +280,7 @@ dependencies = [  [[package]] name = "kicad-platform"-version = "1.0.1"+version = "1.0.2" dependencies = [  "serde",  "serde_json",

@@ -3,7 +3,7 @@ resolver = "2" members = ["crates/*"]  [workspace.package]-version = "1.0.1"+version = "1.0.2" edition = "2021" license = "MIT" publish = false

@@ -195,11 +195,11 @@ pub static VERBS: &[Verb] = &[     },     Verb {         name: "kicad_send_key",-        summary: "Send a key to KiCad; chords auto-resolve to menu commands (background)",+        summary: "Send a key to KiCad, or fire a menu item by label; chords and menu labels resolve to menu commands (background)",         mechanism: Mechanism::Window, risk: "input", timeout_sec: 30,-        input: "{\"key\": \"enter\"|\"escape\"|\"a\"|\"ctrl+s\", \"hwnd\"?: 123}",+        input: "{\"key\"?: \"enter\"|\"escape\"|\"a\"|\"ctrl+s\", \"menu\"?: \"Plugin and Content Manager\", \"hwnd\"?: 123}",         example: "kicad_send_key {\"hwnd\":123456,\"key\":\"escape\"}",-        hint: "For modifier CHORDS ('ctrl+s', 'alt+3', 'ctrl+shift+p') use Bridge's desktop_press_key; it owns full chord parsing; do not route chords here. Use this verb only for the case Bridge's focus-first model cannot cover: a single key delivered to an EXACT hwnd (e.g. Enter/Escape to a specific dialog from window_info).",+        hint: "menu: a label substring fired as a menu command on the target window without touching focus (e.g. menu:\"Plugin and Content Manager\" on the project manager opens the PCM dialog; the dialog is a child, kicad_screenshot_all captures it). For modifier CHORDS ('ctrl+s', 'alt+3', 'ctrl+shift+p') use Bridge's desktop_press_key; it owns full chord parsing; do not route chords here. Use this verb only for the case Bridge's focus-first model cannot cover: a single key delivered to an EXACT hwnd (e.g. Enter/Escape to a specific dialog from window_info).",         related: &["kicad_window_info", "kicad_click", "kicad_fix_keyboard"],         pitfalls: &["not for chords; use desktop_press_key", "needs a target hwnd (from window_info)", "allowForeground (real keystrokes) is not in the native build"],     },@@ -2343,6 +2343,29 @@ fn foreground_kicad_hwnd() -> Option<u64> { }  fn send_key(args: &Value) -> Value {+    // `menu`: a menu-item label (substring, case-insensitive) fired as WM_COMMAND on the+    // target window's menu bar, fully background. The way the PCM dialog is opened.+    if let Some(needle) = arg_str(args, "menu").map(str::trim).filter(|s| !s.is_empty()) {+        let target = match arg_any_u64(args, &["hwnd"]) {+            Some(h) => h,+            None => match foreground_kicad_hwnd() {+                Some(h) => h,+                None => return fail("no_window", "No KiCad window found to send the menu command to.", "kicad_window_info lists the windows; pass hwnd."),+            },+        };+        let title = title_of(target);+        return match menu_invoke_by_text(target, needle) {+            Ok(Some((id, label))) => json!({+                "success": true, "mechanism": "menu",+                "output": format!("Menu item '{label}' fired on '{title}' (background)"),+                "data": {"method": "menu-command", "cmdId": id, "menuItem": label, "hwnd": target, "title": title, "foreground": false},+                "_hint": "Resolved from the window's menu bar by label and fired with WM_COMMAND; no focus was touched. A dialog it opens is a child of this window: kicad_screenshot_all captures it.",+            }),+            Ok(None) => fail("menu_item_not_found", &format!("No menu item on '{title}' contains '{needle}'."), "kicad_window_info lists windows; the label match is a case-insensitive substring of the item text without '&'."),+            Err(e) if is_not_impl(&e) => unsupported("native menu walk (menu_tree)"),+            Err(e) => fail("menu_invoke_failed", &e, "Retry once the window is idle; pass hwnd explicitly."),+        };+    }     let Some(key) = arg_str(args, "key").map(str::trim) else {         return fail("missing_arg", "Missing required arg: key", "Pass key: a named key (enter/escape/tab/space/f1-f12), a single character, or a chord like 'ctrl+s'.");     };

@@ -200,6 +200,29 @@ pub fn is_progress_dialog(title: &str, body: &str) -> bool {     PROGRESS_TITLE_PATTERNS.iter().any(|p| t.starts_with(p) || t == *p) } +/// Tool windows KiCad opens on purpose from a menu (PCM, Preferences, the library+/// tables, Board/Schematic Setup). They are dialogs by window class but never an error+/// box: the sweep leaves them for the AI or the user to close.+pub const TOOL_DIALOG_TITLES: &[&str] = &[+    "plugin and content manager",+    "applying package changes",+    "preferences",+    "manage symbol libraries",+    "manage footprint libraries",+    "symbol libraries",+    "footprint libraries",+    "configure paths",+    "board setup",+    "schematic setup",+    "symbol fields table",+    "design rules",+];++pub fn is_tool_dialog(title: &str) -> bool {+    let t = title.trim().to_lowercase();+    TOOL_DIALOG_TITLES.iter().any(|p| t == *p || t.starts_with(&format!("{p} ")))+}+ pub fn is_save_prompt(title: &str, body: &str) -> bool {     let t = format!("{title} {body}").to_lowercase();     SAVE_PROMPT_PATTERNS.iter().any(|p| t.contains(p))@@ -232,6 +255,9 @@ pub fn sweep_decision(title: &str, body: &str, dismiss_all: bool) -> DialogActio     if is_progress_dialog(title, body) {         return DialogAction::LeaveProgress;     }+    if is_tool_dialog(title) && !dismiss_all {+        return DialogAction::Leave;+    }     let benign = is_benign_dialog(title, body);     if benign || dismiss_all {         DialogAction::Dismiss { benign }@@ -245,6 +271,8 @@ pub fn sweep_decision(title: &str, body: &str, dismiss_all: bool) -> DialogActio pub fn auto_sweep_decision(title: &str, body: &str) -> DialogAction {     if is_progress_dialog(title, body) {         DialogAction::LeaveProgress+    } else if is_tool_dialog(title) {+        DialogAction::Leave     } else {         DialogAction::Dismiss { benign: is_benign_dialog(title, body) }     }@@ -590,6 +618,12 @@ mod tests {         assert_eq!(auto_sweep_decision("Error", "Cannot open"), DialogAction::Dismiss { benign: false });         assert_eq!(auto_sweep_decision("Rendering", ""), DialogAction::LeaveProgress);         assert_eq!(auto_sweep_decision("Information", "converted to the new format"), DialogAction::Dismiss { benign: true });+        // Tool windows opened on purpose (PCM, Preferences, library tables) are never swept.+        assert_eq!(auto_sweep_decision("Plugin And Content Manager", ""), DialogAction::Leave);+        assert_eq!(auto_sweep_decision("Applying Package Changes", ""), DialogAction::Leave);+        assert_eq!(sweep_decision("Preferences", "", false), DialogAction::Leave);+        assert_eq!(sweep_decision("Plugin And Content Manager", "", true), DialogAction::Dismiss { benign: false });+        assert!(!is_tool_dialog("Error"));     }      #[test]