kicad-export-molecule

@@ -1,20 +1,26 @@ --- 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.+description: Ship a KiCad molecule to the Adom wiki. Export the STEP, board, schematic and fabrication sources (<slug>-fab.zip and export.json) from the user's local KiCad through the Adom Bridge, hand the sources to molecule-publish (the wiki's 3D model registry builds the GLB, footprint and symbol from them), then import the built molecule into Hydrogen with adom-wiki model import. 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+# kicad-export-molecule: KiCad project to wiki molecule to 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).+One job: take a molecule designed in the user's **local KiCad**, publish its+sources to the wiki, and register the molecule the wiki builds in their+Hydrogen account. The KiCad export steps are the ones used 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).+Molecule pages publish sources only. The wiki's 3D model registry builds the+GLB, the footprint JSON and the symbol JSON from the STEP, the board and the+fabrication files, and it refuses a push of those generated files to a+molecule page. This skill converts nothing and makes no GLB.++**Out of scope** (route elsewhere): designing the molecule board (wings and+machine pins) goes to `kicad-to-molecule`; Fusion sources to+`fusion-export-molecule`; Altium sources to `altium-export-molecule`; the+publish itself is `molecule-publish` (this skill hands off to it).  ## EasyEDA logo: remove it during creation (always) @@ -25,109 +31,218 @@ Altium sources → `altium-export-molecule`; the Hydrogen import mechanics → - **Verify**: rescan clean, the part's bounding box and colours unchanged, and a before/after render. - Real manufacturer markings (the maker's logo, MPN or date code etched on the part) are not EasyEDA logos; keep those. -## Stage 0 — Preflight gates (run ALL before starting)+## Stage 0: Preflight gates (run ALL before starting)++Run the first two in the container before any registry step.  | 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 |+| adom-wiki CLI | `adom-wiki --version` is 1.8.0 or newer (script below) | Print "This skill needs adom-wiki 1.8.0 or newer (found <v>). Run: adom-wiki self-update" and stop |+| Publisher | `adom-wiki pkg list` shows `adom/molecule-publish` 3.0.0 or newer (script below) | Print "Update adom/molecule-publish to 3.0.0: adom-wiki pkg install adom/molecule-publish" and stop |+| Desktop bridge | `adom-bridge ping` | Start Adom Bridge on the laptop; see the `adom-bridge` skill |+| KiCad bridge | `adom-bridge commands \| grep kicad_` | Install the KiCad bridge (`adom/kicad-bridge`) |+| KiCad version | kicad-cli must be **KiCad 10** | KiCad 9 cannot load KiCad 10 boards: "Failed to load board" means version mismatch |+| Machine pins | Board has two or four machine-pin footprints named **MP1 to MP4**, all one size and length | Otherwise the registry build fails `pin-count` or `pins-uniform` and builds no model; the Stage 1 pin-name check catches it first |+| 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, and the registry cannot anchor or colour pins it cannot see. Fix the lib paths first |++```bash+v=$(adom-wiki --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -n1)+if [ -z "$v" ] || [ "$(printf '%s\n' 1.8.0 "$v" | sort -V | head -n1)" != 1.8.0 ]; then+  echo "This skill needs adom-wiki 1.8.0 or newer (found ${v:-none}). Run: adom-wiki self-update"; exit 1+fi+adom-wiki pkg list --json | python3 -c '+import json, sys+d = json.load(sys.stdin); d = d.get("data", d)+have = {p["name"]: p.get("version") or "" for p in d.get("packages", [])}+need = {"adom/molecule-publish": "3.0.0"}+key = lambda v: tuple(int(x) for x in v.split("-")[0].split(".")[:3]) if v else (0,)+bad = [n for n in need if key(have.get(n, "")) < key(need[n])]+for n in bad: print(f"Update {n} to {need[n]}: adom-wiki pkg install {n}")+sys.exit(1 if bad else 0)'+```++Any later `adom-wiki model ...` command that answers that `model` is not a+command (`'model' is not an adom-wiki command`, `unknown command 'model'`, or+hint code `UNKNOWN_COMMAND`) means the CLI is older than 1.8.0: print the+same adom-wiki message and stop.  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)+## Stage 1: Export on the laptop, pack in the container -Run KiCad 10's CLI on the laptop (NOT the container — the user's 3D libs only-resolve there):+Run KiCad 10's CLI on the laptop (NOT the container: the user's 3D libs only+resolve there), through the Adom Bridge's `shell_execute` verb with `cwd` set+to the project folder, a `reason`, and the laptop's real kicad-cli path:  ```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+kicad-cli pcb export step --subst-models --force -o <slug>.step ABC.kicad_pcb kicad-cli pcb export gerbers --layers F.Cu,B.Cu,F.Mask,B.Mask,F.Silkscreen,B.Silkscreen,Edge.Cuts --check-zones -o fab/ ABC.kicad_pcb kicad-cli pcb export drill --format excellon --excellon-units mm --excellon-separate-th --drill-origin absolute -o fab/ ABC.kicad_pcb kicad-cli version ``` -Use an empty `fab/` directory and the same saved board for all three exports.-Keep the STEP flags above even if a bridge's convenience export omits-`--subst-models`. Gerbers and drill are required on every molecule export.-Read the board's `(setup (stackup ...))` for known thickness, side colours-and finish; leave unknown values absent rather than inventing defaults.--Install `adom/molecule-publish` and use its-[fabrication handoff](https://wiki.adom.inc/adom/molecule-publish)-and `scripts/fab_bundle.py` to package `fab/` as `<slug>-fab.zip` and write-`export.json`. Record the actual KiCad version, this export skill's version,-and hashes of the STEP, saved board, every schematic sheet, project and other-exported sources. Run `fab_bundle.py check` before handing the bundle over.--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+`<slug>` is the wiki page slug: lowercase words separated by hyphens. The+STEP is named after it because the registry's recipe tries `<slug>.step`+first, so a STEP an earlier export left at the page root under another name+cannot make the choice ambiguous. Use an empty `fab/` directory and the same+saved board for all three exports. `--force` lets a re-export replace an+existing STEP. Keep the STEP flags above even if a bridge's convenience+export omits `--subst-models`. Gerbers and drill are required on every+molecule export. Read the board's `(setup (stackup ...))` for known+thickness, side colours and finish; leave unknown values absent rather than+inventing defaults.++Do not use the bridge's `kicad_export_molecule` verb for this: its STEP lacks+`--subst-models` and it writes no Gerbers, drill, fab zip or `export.json`.+Ignore the `nextSteps` that the bridge's `kicad_export_molecule` returns+(step2glb, then `adom-molecule create --glb`: the old GLB path, and+`adom-molecule` is deprecated); hand off to molecule-publish.++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.+`service-kicad pcb export glb`) for molecules, and never hand a GLB on: the+registry builds the molecule's GLB from the STEP and the board.++Pull the sources into a **fresh** container folder that holds nothing else+(never a clone or `repo pull` of the page: old generated files would ride+along), and every file kicad-cli wrote into `fab/` into a second folder,+with `adom-bridge pull_file`:++- into `/tmp/<slug>-bundle`: `<slug>.step`, `ABC.kicad_pcb`, **every**+  `.kicad_sch` sheet (the schematic is required: a molecule without it is not+  reproducible), `ABC.kicad_pro`+- into `/tmp/<slug>-gerbers`: every Gerber, job and drill file from `fab/`+  (list the folder on the laptop first)++Bundle the board's custom 3D models before packing. Stock+`${KICADn_3DMODEL_DIR}/...` models resolve anywhere; every other `(model ...)`+ref must travel in the bundle's `3d/` folder with its path rewritten to+`${KIPRJMOD}/3d/<basename>`, or the board renders blank when someone pulls the+project in APM. `bundle --write` rewrites the board, so it runs before+`create` records the board's hash; molecule-publish runs the same check again+and sends a failing bundle back here.++```bash+S=~/.claude/skills/molecule-publish/scripts+python3 $S/bundle_3d.py check /tmp/<slug>-bundle/ABC.kicad_pcb+# only when check lists MISSING models: pull each named file from the laptop+# into /tmp/<slug>-models with adom-bridge pull_file, then+cd /tmp/<slug>-bundle && python3 $S/bundle_3d.py bundle ABC.kicad_pcb --models /tmp/<slug>-models --write+python3 $S/bundle_3d.py check /tmp/<slug>-bundle/ABC.kicad_pcb --have /tmp/<slug>-bundle/3d/*+``` -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`, `<slug>-fab.zip`, `export.json`, and any silk PNGs.+Run `bundle` from inside the bundle folder: the rewritten path is+`${KIPRJMOD}/3d/<basename>`, relative to it. A model `bundle` cannot find+must be exported from the design machine. The registry's build does not read+`3d/` (the recipes exclude it), so these files change only what APM shows. -## Stage 2 — Hand off to molecule-publish+Then pack and check with molecule-publish's helpers in the container. Record+the actual KiCad version, this skill's version, and every source: -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:+```bash+python3 $S/fab_bundle.py create /tmp/<slug>-bundle --slug <slug> \+  --fab /tmp/<slug>-gerbers --tool KiCad --tool-version <kicad-cli version> \+  --exporter adom/kicad-export-molecule --exporter-version 2.0.0 \+  --source step=<slug>.step --source board_kicad_pcb=ABC.kicad_pcb \+  --source schematic=ABC.kicad_sch --source project=ABC.kicad_pro \+  --stackup /tmp/<slug>-stackup.json+python3 $S/fab_bundle.py check /tmp/<slug>-bundle --slug <slug>+python3 $S/pin_names.py check /tmp/<slug>-bundle --slug <slug>+``` -- STEP + board (`.kicad_pcb`) + schematic (`.kicad_sch`) + silk PNGs-- `<slug>-fab.zip` + `export.json`, checked against the final source files-- `pin` size (medium|large) and the target slug/org+Repeat `--source schematic=` for every sheet. The stackup file holds only the+values the board records (`thicknessMm`, `copperLayers`, `maskColor` and+`silkColor` by `top`/`bottom`, `finish`); leave out `--stackup` when it+records none. `create` writes `<slug>-fab.zip` (named with the page+slug, never the design stem) and `export.json` into the bundle folder.++`pin_names.py` is the registry's own pin-name rule. It reads the board the+build will read and exits 0 when the names pass (warnings and notes are+printed and accepted), 1 when a check refuses, and 2 when the folder has no+board or more than one at the same depth. It refuses machine pins numbered+outside `MP1` to `MP4` or not in capitals (`pin-names`), a board without two+or four machine pins (`pin-count`), machine pins of different sizes or+lengths (`pins-uniform`), contacts named `MP<n>` or not in capitals+(`contact-names`), and repeated designators. A part that fits the standard+only in part is warned about and not counted as a pin or contact. Fix+each finding in the board and the schematic and export again; do not rename+parts inside the STEP.++## Stage 2: Hand off to molecule-publish++Publishing is the **`molecule-publish`** skill's job (EDA-agnostic; shared+with the Fusion and Altium flows). Hand it the bundle folder and the page+(`<owner>/<slug>`). At the handoff the folder holds exactly these files at+its root, plus `3d/` when the board has custom models (molecule-publish adds+the package files it authors, such as `package.json`):++| File | Recipe `molecule-board` role |+|---|---|+| `<slug>.step` (one STEP only) | `step` |+| `ABC.kicad_pcb` (one board only) | `board` |+| `<slug>-fab.zip` | `fab` |+| `export.json` | `export` |+| every `.kicad_sch` sheet, `ABC.kicad_pro` | none: sources the record lists |+| `3d/<model files>` (custom models only) | none: the recipes exclude `3d/`; APM reads them |++No GLB, no `_footprint.json` or `_symbol.json`, no `.pipeline.json` or+`.metadata.json`, no silk PNGs. Before the handoff this must print nothing:++```bash+ls /tmp/<slug>-bundle | grep -iE '\.(glb|gltf)$|_footprint\.json$|_symbol\.json$|\.pipeline\.json$|\.metadata\.json$'+``` -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.+molecule-publish publishes the folder as the private package release, waits+for the registry's build, sets the hero from the built model and then makes+the page public. Do not re-implement any of that here. If the page already+holds files from older exports (`<slug>.glb`, footprint or symbol JSON,+`render/`), leave them: no skill deletes them. -## Stage 3 — Import to Hydrogen (handoff)+## Stage 3: Import to Hydrogen, after a passed build -Follow the **`adom-molecule-import`** skill (ships with `adom/adom-molecule`).-Short form:+Import only once the page's newest build has passed (molecule-publish+reports it). To check, then import:  ```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+adom-wiki model status <owner>/<slug>+adom-wiki model import <owner>/<slug> --owner <hydrogen-owner> --name ABC ``` -`--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.+`model status` must show the newest build passed and the served model coming+from it. If the build failed, `adom-wiki model report <owner>/<slug>` names+the failed checks; fix the board and export again instead of importing.+Hydrogen reads the model the page serves and the page's sources (board,+schematic, footprint and symbol JSON) with the user's own token, so a private+page imports too. `--owner` is the user's own Hydrogen owner or an org they+belong to, never the page owner by default.++The import passed when it exits 0 and prints `<owner>/<slug>: imported into+Hydrogen as <hydrogen-owner>/ABC, version <v>, from <glb>` and the link+`https://hydrogen.adom.inc/<hydrogen-owner>/molecules/ABC`. Each Hydrogen+warning prints as a `HYDROGEN_IMPORT_WARNING` hint (the exit is still 0);+report every one to the user rather than calling the import clean. Exit 1 is+`MODEL_IMPORT_NO_MODEL` (the page has no model yet; nothing was sent) or+`HYDROGEN_IMPORT_FAILED` with Hydrogen's status and message (401 sign in, 403+an owner you may act for, 404 a page you can read, 422 no model yet).  ## 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)+- Silkscreen present (the registry draws it from the Gerbers) - Wires attach at the contact tops (not floating above / sunk below)-- `adom-molecule list` shows the molecule under the right owner+- The molecule shows under the right owner: the import's printed link, or+  `https://hydrogen.adom.inc/users/<you>/molecules` (`/orgs/<org>/molecules`+  for an org)  ## 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+- `molecule-publish`: publish the sources and follow the build (this skill's Stage 2)+- `adom-wiki model import` (in the adom-wiki-cli skill): 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/kicad-bridge`: the laptop KiCad verbs Stage 1 drives