kicad-export-molecule

@@ -0,0 +1,139 @@+---+name: kicad-export-molecule+description: Ship a KiCad molecule to the Adom wiki — export STEP + board from the user's local KiCad via the adom-desktop KiCad bridge, convert through the OCCT molecule pipeline (anchored GLB + footprint + symbol), publish as a wiki component package, then hand off to adom-molecule-import for Hydrogen registration. Use when the user says "publish my kicad molecule", "kicad molecule to the wiki", "upload molecule from kicad", "kicad to hydrogen", "ship this board as a molecule", "export molecule from kicad", or "kicad export molecule". For Fusion 360 sources see fusion-export-molecule; for Altium see altium-export-molecule; to design the molecule board itself see kicad-to-molecule.+user-invocable: true+argument-hint: "<board name or .kicad_pcb path> [--owner <hydrogen owner>] [--slug <wiki slug>]"+---++# kicad-export-molecule — KiCad project → wiki molecule → Hydrogen++One job: take a molecule designed in the user's **local KiCad**, publish it to+the wiki with a pipeline-ready artifact set, and register it in their Hydrogen+account. Validated end-to-end on real boards (PiProbe et al).++**Out of scope** (route elsewhere): designing the molecule board (wings ++machine pins) → `kicad-to-molecule`; Fusion sources → `fusion-export-molecule`;+Altium sources → `altium-export-molecule`; the Hydrogen import mechanics →+`adom-molecule-import` (this skill hands off to it).++## Stage 0 — Preflight gates (run ALL before starting)++| Gate | Check | If it fails |+|---|---|---|+| Desktop bridge | `adom-desktop ping` | Start Adom Desktop on the laptop; see `adom-desktop` skill |+| KiCad bridge | `adom-desktop commands \| grep kicad_` | Install the KiCad bridge (see `adom-desktop-kicad-bridge`) |+| KiCad version | kicad-cli must be **KiCad 10** | KiCad 9 cannot load KiCad 10 boards — "Failed to load board" means version mismatch |+| Markers | Board has **MP1–MP4 marker models** placed | Without ≥3 markers, OCCT anchoring SKIPS (graceful, but the GLB imports unanchored) |+| 3D models resolve | Machine-pin/contact models load in the user's local KiCad 3D viewer | Models referenced by paths that don't resolve are silently OMITTED from the STEP — anchoring/gold/measured-Z lose their geometry. Fix the lib paths first |++The models gate is the classic trap: the STEP only contains what resolves **on+the exporting machine**. "Renders fine for me" does not survive a machine hop.++## Stage 1 — Export on the laptop (adom-desktop KiCad bridge)++Run KiCad 10's CLI on the laptop (NOT the container — the user's 3D libs only+resolve there):++```bash+# via the bridge's run-command verb; use the laptop's real kicad-cli path+kicad-cli pcb export step --subst-models -o ABC.step ABC.kicad_pcb+```++Optional but recommended — silkscreen overlays (top + bottom):+- Export the silk layers to PNG (transparent background).+- Artwork must be **white**; if the export bakes black silk, recolor opaque+  pixels to white before converting (PIL: opaque → white). Black silk is the+  #1 cosmetic defect.++Gotcha: never write or touch KiCad files with PowerShell `Set-Content` — the+UTF-8 BOM corrupts S-expression files. Use the bridge's file verbs.++Pull everything to the container: `adom-desktop pull_file` for `ABC.step`,+`ABC.kicad_pcb`, and any silk PNGs.++## Stage 2 — Convert (OCCT molecule mode)++```bash+curl -s -X POST "https://step2glb-gmdoncpxdwx0.adom.cloud/convert?molecule=true&pin=medium" \+  -H "X-Client: <agent-name>" -H "X-Job-Name: ABC" \+  -F "[email protected]" -F "[email protected]_pcb" \+  # optional: -F "silk_top=@silk_top.png" -F "silk_bottom=@silk_bottom.png"+```++`pin` = the machine-pin size on the board (`medium` | `large`). Poll+`GET /jobs/{id}` until `status: complete`, then **verify the stats — do not+proceed on a degraded conversion**:++| Field | Must be | If not |+|---|---|---|+| `anchored` | `true` | Markers missing/undetected — fix Stage 0, re-export |+| `footprint_applied` | `true` | Board parse failed — check `warnings[]` (Cloudflare/UA, format) |+| `contact_z` | sane mm value (≈2.8–8.4) | Wrong `pin` param or missing contact models |+| `warnings[]` | empty | Read each one; "anchor skipped"/"footprint gen failed" are stop-signs |++Download the artifact set:+```bash+GET /jobs/{id}/result     → ABC.glb+GET /jobs/{id}/footprint  → ABC_footprint.json+GET /jobs/{id}/symbol     → ABC_symbol.json+```++> Upgrade path: once the `step2glb` CLI grows molecule flags+> (adom/adom-step2glb discussion #99), replace the curl with+> `step2glb convert ABC.step --molecule --board ABC.kicad_pcb --pin medium`.++## Stage 3 — Publish to the wiki++Component package dir:++```+abc/+  package.json          # slug, version, type: "component", description, tags+  ABC.glb               # the anchored, optimized model (reused at import — never regenerated)+  ABC.kicad_pcb         # board source+  ABC_footprint.json    # OCCT-authored (per-pad wire-attach z included)+  ABC_symbol.json+  README.md+```++```bash+adom-wiki pkg publish                      # registry layer+adom-wiki repo push <owner>/abc --files ABC.glb ABC.kicad_pcb ABC_footprint.json ABC_symbol.json README.md package.json -m "ABC molecule"+```++Verify: the page renders, the 3D model shows, and `metadata.model_3d_path` is+set (`adom-wiki api /api/v1/pages/abc`). The packaged `*_footprint.json` is+what Hydrogen's import prefers — publishing it here is what makes the import+zero-regeneration.++## Stage 4 — Import to Hydrogen (handoff)++Follow the **`adom-molecule-import`** skill (ships with `adom/adom-molecule`).+Short form:++```bash+adom-wiki repo clone <owner>/abc --dir /tmp/abc-import   # authenticated, binary-safe+adom-molecule create --owner <hydrogen-owner> --name ABC \+  --glb ABC.glb --pcb ABC.kicad_pcb --no-optimize+```++`--no-optimize` is the point: reuse the published GLB, skip re-optimization,+no silkscreen needed at import. Caveat: keep the wiki page **public** if the+import goes through Hydrogen's `/api/molecules/import` endpoint — private-page+support there is pending; the container-side flow above is already+private-safe.++## Acceptance checklist (in the Hydrogen editor)++- Board is Z-up with the front-left machine pin at the origin+- Machine pins/contacts render gold (not gray)+- Silkscreen present and white (if exported)+- Wires attach at the contact tops (not floating above / sunk below)+- `adom-molecule list` shows the molecule under the right owner++## Related++- `adom-molecule-import` — the import half (this skill's Stage 4)+- `fusion-export-molecule` / `altium-export-molecule` — same job, other EDAs+- `kicad-to-molecule` — make a plain PCB molecule-ready first (wings + pins)+- `adom-desktop-kicad-bridge` — the laptop KiCad verbs Stage 1 drives