KiCad - the KiCad Bridge

@@ -171,8 +171,10 @@ the unsaved board in the editor without GUI clicks. | `kicad_route_net` | Commit one segment, a polyline, or branches on one net as one native Undo step | `filePath`, `expectedRevision`, exact `net`, `points` or `paths` | | `kicad_remove_route` | Remove specific unlocked copper items as one Undo step | `filePath`, `expectedRevision`, `itemIds` | | `kicad_routing_validate` | KiCad DRC on the unsaved editor snapshot | `filePath` |+| `kicad_add_zone` (from 1.0.5) | Add copper zones (pours) as ONE Undo step: the zone is filled and DRC-checked on a snapshot first, then created and filled through the IPC API | `filePath`, `expectedRevision`, `net`, `layers`, `polygon` [[x,y],...] mm, optional `priority`, `clearance`, `minThickness`, `connection` thermal/solid, or `zones: [...]` |+| `kicad_zone_state` (from 1.0.5) | Every zone with KiCad's filled copper area per layer and the coverage (what an ablation process keeps) | `filePath`, optional `refill: true` | -Read routing_state, choose waypoints, then route with its revision. Points may be+Pours come after the routing closes: which nets get one, which never do, priorities and the offline gate are the `kicad-copper-pours` skill in this package. Read routing_state, choose waypoints, then route with its revision. Points may be `"J1.1"`, `[x,y]`, or `{x,y,layer}`; `{pad:"J2.1",layer:"B.Cu"}` also works. Coordinates are mm, +y down. A layer marker changes the outgoing layer at that point using a through via, including at the final waypoint. Width defaults to

@@ -1,6 +1,6 @@ {   "slug": "kicad-bridge",-  "version": "1.0.140",+  "version": "1.0.141",   "type": "app",   "description": "Skills for your container so your AI knows how to drive the KiCad bridge. The bridge runtime itself is the release zip; Adom Bridge loads that.",   "tags": [@@ -30,6 +30,7 @@     "skills/kicad-3d-models/SKILL.md",     "skills/kicad-autorouting/SKILL.md",     "skills/kicad-place-route-loop/SKILL.md",+    "skills/kicad-copper-pours/SKILL.md",     "skills/kicad-tour/SKILL.md",     "skills/kicad-tour/tour_runner.py",     "skills/kicad-web-control/SKILL.md",

@@ -4,7 +4,7 @@   "slug": "kicad-bridge",   "title": "KiCad - the KiCad Bridge",   "brief": "Reference implementation of the KiCad bridge: multi-instance Python server, forward path via kicad-cli, reverse path via in-process plugin. Most complex of the three bundled bridges.",-  "version": "1.0.140",+  "version": "1.0.141",   "tags": [     "kicad",     "pcb",@@ -89,6 +89,7 @@     "skills/kicad-3d-models/SKILL.md",     "skills/kicad-autorouting/SKILL.md",     "skills/kicad-place-route-loop/SKILL.md",+    "skills/kicad-copper-pours/SKILL.md",     "skills/kicad-tour/SKILL.md",     "skills/kicad-tour/tour_runner.py",     "skills/kicad-web-control/SKILL.md",

@@ -35,7 +35,7 @@ The worked examples, power pours and current-density review live in the adom/cod  ## 100% or it is not done -A routing result with unconnected items is a failed take, not a result. The rule, and the loop that gets there (route, then change vias and order, then rip up, then go back and move the parts that block the escapes, then route again, to the bitter end), is the kicad-place-route-loop skill in this package. Read it before you report any routing number.+A routing result with unconnected items is a failed take, not a result. The rule, and the loop that gets there (route, then change vias and order, then rip up, then go back and move the parts that block the escapes, then route again, to the bitter end), is the kicad-place-route-loop skill in this package. Read it before you report any routing number. After the routing closes, the pours (kicad-copper-pours skill) are the next step, not an option.  ## Honesty rules 

@@ -0,0 +1,57 @@+---+name: kicad-copper-pours+description: After a board is 100 percent routed, the next step every AI on the KiCad Bridge takes before calling it done: copper pours. Which nets get a pour and why (current, heat, and copper retention, because InstaPCB's ablation process mills copper away, so every square millimetre kept is copper not removed), which nets never get one (switching nodes, crystal and clock, high-impedance analog, current-sense Kelvin paths, anything whose capacitance or impedance the pour would change, and anything that would make a ground loop), how to set priorities so small pours win inside big ones, thermal versus solid connections, 2-layer versus 4-layer strategy, the offline gate (tools/add_pours.py then KiCad's DRC), landing pours live with kicad_add_zone, measuring what stayed with kicad_zone_state, and the second loop: moving a trace or a part so a pour can carry the current or spread the heat. Trigger words: copper pour, pours, zone, zones, ground pour, power pour, polygon pour, copper fill, fill zones, ablation, copper ablation, retain copper, maximize copper, heatsink copper, thermal copper, current carrying, kicad_add_zone, kicad_zone_state, add a zone, pour the ground, pour VBAT, InstaPCB copper.+---++# Copper pours: the step after 100 percent routed++A board that is routed is not finished. The traces carry the signals; the copper pours carry the current, sink the heat, and, on an InstaPCB board, are the copper that does NOT get milled away. The kicad-place-route-loop skill ends at zero unconnected; this skill starts there and ends when every net that deserves a pour has one, the DRC is still clean, and the copper kept per layer is measured and reported. Then the placement and routing get a second look: sometimes a trace or a part has to move so a pour can do its job.++## Why pours, in one paragraph per reason++- **Current.** A 0.25 mm trace of 35 um copper carries about 0.5 A with a 10 C rise; a 1 mm trace about 2 A. A drone ESC's battery, phase and return paths carry tens of amps in pulses. No trace width that fits between pads does that; a pour does, on every layer it is on, stitched with vias.+- **Heat.** MOSFET tabs, regulator tabs, LED drivers and shunts dump heat into the copper they sit on. A pour under and around the tab, on both outer layers, joined by thermal vias, is the heatsink.+- **Copper retention.** InstaPCB's process is subtractive: it starts from a copper-clad board and ablates the copper that must go. Every square millimetre left as a pour is copper that never has to be removed: less machine time, less wear, less chance of a stray sliver. The metric is filled copper area per layer; `kicad_zone_state` reports it. "Maximize the pours" is the default; the exceptions below are the whole judgement.++## Which nets get a pour++In this order, because the priorities below follow it:++1. **Ground.** The return for everything. On a 4-layer board the inner plane is the ground; the outer layers still get a ground pour everywhere nothing else needs the copper, stitched to the plane through the existing pad and via connections. On a 2-layer board the ground pour on both sides IS the plane: pour it first, priority 0 (lowest), whole outline, thermal reliefs.+2. **The battery and supply rails that carry the load current** (+VBAT on an ESC, VIN on a driver, the output of a buck that feeds amps). Pour the region that holds the input contact, the bulk capacitors, the TVS and the high-side tabs. Priority 2, solid connections on tabs and bulk capacitors, thermal reliefs on small parts. On every outer layer, and stitched with vias.+3. **The load paths** (the three phase nets of a bridge, a motor or solenoid output, an LED string's common rail). One pour each, around the half-bridge's pads and its output contact. Priority 3, above the rail pour so the phase copper wins where they meet. Keep each phase pour compact: it is a switching node (see the exceptions).+4. **The return path through a shunt.** The net between the return contact and the shunt (GND_OUT on the ESC) is a load path too: pour it, priority 2, but keep the sense taps thin (below).+5. **Regulator inputs and outputs, the thermal tab nets of hot parts.** A modest pour under and around the tab on its own layer, priority 2.++## Which nets never get a pour, or a small one++- **Switching nodes.** The phase node of a bridge, the SW pin of a buck, the drain of a flyback switch: a big pour there is an antenna and a capacitor to everything under it (high dv/dt). Pour only what carries the current, compact, and keep the return-current pour on the same layer tight around it so the loop stays small. Never let a switching-node pour sprawl into the signal area.+- **Crystal, clock and reference oscillators.** No pour of any net but ground near them; even ground gets a solid guard, not a hatched field, and no pour under the crystal on the layer that carries the oscillator traces if the datasheet says so. Capacitance on OSC_IN or OSC_OUT shifts the frequency.+- **High-impedance and analog nodes.** BEMF dividers, comparator inputs, ADC inputs, op-amp inputs, sense dividers: a pour of the node itself adds capacitance and pickup; a pour of another net running beside it couples noise. Route them thin and short, keep pours of other nets at the normal clearance, and do not widen them.+- **Current-sense Kelvin taps.** The two thin traces from the shunt's pads to the sense amplifier must stay two thin traces from the pad edges: a pour that swallows them turns the shunt into the copper's resistance and the reading into noise. Pour the current side of the shunt, never the sense side.+- **Ground loops.** One ground. A second ground pour that reaches the first only through a long path, or an analog ground pour tied to the digital one at two places, is a loop with the return current of everything running around it. If the board has a star or a single-point tie, the pours respect it: one tie, and the pours never touch anywhere else.+- **Impedance-controlled and differential pairs.** USB, CAN, Ethernet, any pair with a target impedance: the pour of the reference plane under them stays, but no pour of any other net runs beside them, and the pair is not widened.+- **Isolation barriers.** Never fill an isolation gap with anything, and do not count floating copper as isolation distance.++## Priorities, connections, layers++- KiCad fills higher priority zones first and the lower ones around them, so: ground 0, rails 2, load paths and tab pours 3. Two pours of the same priority that overlap are a mistake; give one a higher number.+- **Thermal reliefs** on every pad by default (solderability); **solid** on the tabs, bulk capacitors and contacts of the current-carrying nets, where the copper has to conduct without spokes. The bridge's `connection` field is per zone; split a net into two zones when its tabs need solid and its small parts need reliefs.+- Minimum thickness 0.25 mm on outer layers keeps slivers out; clearance the board's own (0.2 mm on the ESC). Island removal always on: a floating island is copper with no potential.+- **2-layer boards:** ground pour both sides, whole outline; rail and load pours on the side that has the parts, mirrored on the other side where it is free and stitched with a via row; route signals so the ground pour stays continuous under them (a slot in the ground pour under a fast signal is a loop).+- **4-layer boards:** planes inside (ground, then the main supply), outer pours for current and heat and copper retention; the outer ground pour is stitched to the plane by every through pad and by stitching vias every few mm along the pour's edges; the rail and load pours use both outer layers with via stitching, and never the inner planes.+- **More layers:** the same, with the second ground plane adjacent to the signal layers that need it; pours on the outer layers are for current, heat and retention, the planes are the references.++## The loop, with the bridge++1. Route to 100 percent first (kicad-place-route-loop). Pours are not a way to connect things that the routing could not.+2. Write the pours as JSON, the `kicad_add_zone` shape: net, layers, polygon in mm, priority, connection. Draw each polygon from the pads it must cover (contacts, tabs, bulk capacitors), not from a guess; leave the sensitive parts above outside every non-ground polygon.+3. Gate offline: `tools/add_pours.py BOARD-routed.kicad_pcb --pours pours.json --drc --baseline BOARD-unrouted.kicad_pcb` splices the zones into a copy and runs KiCad's DRC with the zones filled: zero new errors, zero unconnected.+4. Land live: one `kicad_add_zone {"zones": [...]}` call per group (one undo step), or one per zone when the human should be able to undo them singly. The verb runs the same preflight on the editor's snapshot before anything lands and fills the new zones after.+5. Measure: `kicad_zone_state {"refill": true}` gives the filled copper per layer and the coverage. Report the numbers before and after the pours. That is the ablation metric.+6. Validate: `kicad_routing_validate` on the live board: zero new errors, zero unconnected, and read the warnings (copper slivers, thermal reliefs that could not be made).+7. Second look at the layout: if a rail pour is choked to a neck by a trace crossing it, move the trace (rip it with `kicad_remove_route`, route it on the other layer); if a hot tab has no copper because a part sits beside it, move the part (`kicad_move_footprint`) and route again; if a pour cannot reach a tab because the current has to cross a signal bus, add a via row and a matching pour on the other layer. Then gate, land, measure again. This is the same going-back that got the board to 100 percent routed; the pour numbers tell you when it is worth it.++## What to report++Per layer: filled copper before and after, in mm2 and as a percentage of the board; per pour: net, layer, area, connection style; the DRC result; and every judgement call above that applied (which nets were deliberately not poured and why). A pour count with no areas is not a report.

@@ -50,6 +50,10 @@ Nothing lands on the live board until the plan passes KiCad's own DRC offline: 2. Gate: zero new errors against the unrouted baseline (inherited library errors are counted separately and named), zero unconnected after the zones are filled. 3. Only then replay the plan on the live board (`route_live.py`), one `kicad_route_net` per net, `expectedRevision` from the previous reply, and finish with `kicad_routing_validate`, which must agree with the offline gate. +## After 100 percent: the pours++Routed is not finished. The nets that carry the current, sink the heat and, on an InstaPCB board, are the copper that does not get milled away get pours next: the kicad-copper-pours skill in this package, with the same offline gate and the same second look at placement and traces when a pour cannot do its job. The clock keeps running through it.+ ## Report the time the human waited  The headline number is the wall clock from the moment the human gave the prompt to the moment the finished board (or the issue that reports it) was handed back. Not the seconds the verbs took on the board, not the planning time. Record the prompt's timestamp in UTC as your first action, record the hand-back timestamp, and report both with the difference in minutes; the per-step times (planning, commits, on-the-board seconds) go in the table below it. A take that stops short of 100 percent has no finish time; when the loop above sends you back to placement, the clock keeps running.