---
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.

**Never use KiCad-native GLB export** (`kicad-cli pcb export glb` or
`service-kicad pcb export glb`) for molecules — it bypasses anchoring, gold
materials, normalization, and footprint emit. STEP only; OCCT makes the GLB.

Pull the **full bare-minimum bundle** to the container with
`adom-desktop pull_file`: `ABC.step`, `ABC.kicad_pcb`, **`ABC.kicad_sch`**
(schematic is required — a molecule without it is not reproducible),
`ABC.kicad_pro`, and any silk PNGs.

## Stage 2 — Hand off to molecule-publish

Conversion, packaging, and wiki publish are the **`molecule-publish`** skill's
job (EDA-agnostic; shared with the Fusion and Altium flows). Hand it the
bundle from Stage 1:

- STEP + board (`.kicad_pcb`) + schematic (`.kicad_sch`) + silk PNGs
- `pin` size (medium|large) and the target slug/org

It runs the OCCT molecule-mode conversion with the stats gates (`anchored`,
`footprint_applied`, `contact_z`, `warnings[]`), assembles the component
package (GLB + board + schematic + footprint + symbol + metadata), publishes
via `adom-wiki`, and verifies `model_3d_path`. Do not re-implement any of
that here.

## Stage 3 — 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

- `molecule-publish` — convert + package + publish (this skill's Stage 2)
- `adom-molecule-import` — the import half (this skill's Stage 3)
- `molecule-pipeline` — the top-level router across the whole chain
- `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