KiCad - the KiCad Bridge

@@ -184,8 +184,87 @@ replay a mutation. A postCommitError means the copper was committed but the subsequent read or save failed. Revision checking is optimistic: avoid concurrent manual edits while committing. Connectivity state that changes mid-read is refused. -For a visible trace-by-trace demo, call route_net once per segment/via; for a-net-by-net demo, send each whole path. See [demo/routing/README.md](demo/routing/README.md).+### General routing workflow++Use this workflow for ordinary board work, repair, and review with any Adom AI+caller. Recording and demonstration playback are optional, separate tasks; no+demo script, narrator, Codex package, or particular model is required to use the+bridge verbs.++1. Resolve the requested desktop through Adom Bridge with explicit target and+   caller identity. Read runtime version, document path, current live revision,+   IPC availability and existing edits. Preserve development pins and other+   callers' work. Package skill version and desktop bridge runtime version are+   different: verify both when a capability appears missing.+2. Inspect the schematic netlist, footprint pads, existing copper and project+   rules before planning. Determine supply voltages, return paths, protection,+   switching nodes and sensitive signals. Component ratings bound capability;+   they do not establish actual load or simultaneous current. Obtain missing+   load/duty, copper thickness and manufacturer constraints before making+   current-capacity or insulation claims.+3. Choose widths, vias and clearances from those requirements. Prefer horizontal,+   vertical and 45-degree trace segments with deliberate pad escapes. Do not+   claim arbitrary-angle straight segments are curved routing; use curves only+   if the discovered editor API supports them and the resulting geometry can+   be checked. Minimize unnecessary vias and keep return paths continuous.+4. Inspect heat-producing devices, exposed pads and existing thermal vias before+   allocating copper. Confirm the electrical net of each exposed pad from the+   actual component documentation. Expand connected same-net copper where it+   improves the thermal path without compromising isolation or routing. External+   copper, inner-layer routing and thermal vias depend on the real stackup and+   assembly process; copper area alone does not establish device temperature.+5. For copper-ablation manufacturing, retain useful connected copper with pours+   where authorized. Respect required isolation, pad access, solderability and+   switching-node constraints. Do not expand every net indiscriminately, add+   floating islands by default, or interpret a tool's minimum kerf as adequate+   electrical clearance. Zone creation requires a separately discovered supported+   operation; route_net does not create pours.+6. Read routing_state, compute a path, dry-run it, and commit against that revision.+   Group a logical net path with points/paths for a useful Undo operation. Keep+   validation enabled for ordinary routing. remove_route uses explicit itemIds;+   do not assume it supports dryRun. Read back the changed copper and revision.+7. Validate the final live board, then save when requested. Record remaining+   errors, warnings and unconnected items separately, including inherited issues.+   Successful routing means the edit succeeded, not that the whole PCB passed+   electrical review or is ready to manufacture.++From runtime 0.9.341, routing validation refills disposable snapshot zones and+reports potentially capped DRC lists. Inspect zonesRefilled,+violationReportMayBeTruncated and unconnectedCountIsLowerBound. A capped count+is a lower bound, and drc_incomplete refuses an uncertifiable error comparison.+Do not disable validation to turn that refusal into a claimed success. Older+runtimes lacking these fields do not establish equivalent validation.++### First-run and diagnostic handling++Discover current verb schemas and read response hints and nested errors before+retrying. A timeout can leave an editor open or an edit committed. Inspect state+and dialogs first. Use kicad_errors, kicad_log_tail and targeted desktop_ui_tree+reads to capture the actual blocker; do not blindly press Escape or Cancel on+unknown dialogs. In particular, cancelling a setup wizard can open a second+confirmation. UIA can identify and invoke a benign control without coordinate+clicks, but KiCad may still raise itself: follow kicad-uia foreground etiquette.++KiCad 9/10 eeschema does not host the Python reverse-bridge plugin. For plugin+health, inspect kicad_bridge_status and ping a discovered pcbnew instance;+plugin_not_running for eeschema is not an installation failure. Live routing+uses the separate KiCad IPC API; a plugin ping alone does not prove IPC readiness.++Resolve stock libraries through the detected KiCad installation and configured+path overrides. Do not repair a resolution failure by moving stock libraries+into Documents. Report the requested library, resolved path, installed KiCad+version and exact response. For footprint-load failures, collect status, errors,+log_tail (errorsOnly:true), plugin_diagnose and list_footprints from the same run.++Test installation separately from first editor launch. Confirm host detection,+CLI version, actual editor readiness and required APIs. Only clear configuration+or uninstall when the user authorized it. Treat successful close with forceKilled+as forced termination, not graceful save/close. Preserve evidence and report+reproducible problems in the KiCad Bridge wiki issues, with explicit test skips.+A passing subset is not all-verbs acceptance.++For optional presentation and recordings, see [demo/routing/README.md](demo/routing/README.md).+  ## Offline copper editing (from 0.9.340)