skill

molecule-pipeline

Public Made by Adom

by adom

Top-level router for moving molecules between EDA tools, the wiki, and Hydrogen: one entry point that routes publish/import intents to the right skill chain and enforces the pipeline invariants.

moleculepipelinewikihydrogenskill
Overview Files Skills Discover Packages Releases Dependencies Issues2 Breadcrumbs Pull Requests Activity
Open general

Field report: corrections required across ~10 molecule imports (session 2026-07-14..16)

Caleb · 5d ago

Molecule Pipeline — Import Corrections Log

Every change we had to make to the molecule imports from this session (KiCad/Fusion → step2glb molecule conversion → adom-wiki publish → adom-molecule import to Hydrogen), plus the pipeline-level rules that came out of them.

Per-Molecule Changes

NTX_CCX-MIO_Carrier (caleb/ntx-ccx-mio-carrier) — first import through the pipeline

# Problem Fix
1 KiCad sources never reached Hydrogen — the import verb only registered the GLB Deleted the GLB-only record; re-ran adom-molecule create with --pcb --sch --pro, the wiki GLB --no-optimize, STEP + footprint/symbol JSON as extras (record bumped v1→v2)
2 No way to set the description (Hydrogen has no edit endpoint) Delete + recreate via raw multipart POST to hydrogen.adom.inc/api/molecules/create (field names reverse-engineered from the binary)
3 Molecule missing from adom-molecule list Root-caused later — list was reading the orphan Carbon table (see pipeline §4–5)
4 Hero angle/lighting Re-rendered to the standard studio angle; hero flipped billboard → static image
5 New rev docs docs/ + corrected Project_Overview v1.1 pushed to the page

The three Teazzers boards (MX-3140N_Carrier, Solonoid-638-0031 Multicarrier, Solonoid v2.0) went through the same early batch and needed the same raw-API create + description injection.

I2S_Carrier (caleb/i2s-carrier)

# Problem Fix
1 First create shipped without a description Delete + recreate → Hydrogen record v2
2 Hero oriented incorrectly Rotated 180°, flat top view with silk upright
3 Thumbnail still wrong after the hero fix Browse-card thumbnails are baked at publish time — pushing the file to the repo isn't enough. Republished as v1.0.1; verified served blob + card PNG by sha256

Infineon_IM72D128 (caleb/infineon-im72d128) — wiki-only by request

# Problem Fix
1 0 MP markers found Expected — finger-edge daughter card, published as a plain component (not an anchored molecule), no Hydrogen import
2 3D model axis wrong + thumbnail too tight Baked −90° X root rotation, padded hero ~30% → v1.0.1
3 Model then upside-down Flipped to +90° X → v1.0.2

RP2350A_Mini (adom/rp2350a-mini) — correction of an existing org page

# Problem Fix
1 Page needed v1.1 correction from the zip Published under the adom org (not forked to caleb); Hydrogen copy deleted and recreated --no-optimize with full description
2 Thumbnail too dark Brightened 2.1× → v1.1.2
3 Then too bright Split the difference (1.55×) → v1.1.3

PiProbe v1.2 → v1.3 (adom/piprobe-v1-3)

# Problem Fix
1 Page named for the old rev adom-wiki repo rename adom/piprobe-molecule-v1-2 piprobe-v1-3
2 Two stale Hydrogen copies (PiProbe, PiProbe_Molecule_v1.2) Both deleted; created PiProbe_v1.3 with anchored GLB --no-optimize + board/sch/pro + STEP/gerbers/BOM/CPL
3 Probe not mating with contacts in the workcell 3D render Seat position corrected in the workcell GLB

Adom_Jumper_12x6_MP (nested element, no page of its own)

# Problem Fix
1 Original large-MP model superseded Replaced with the new standalone STEP from the project
2 Jumpers seating too far into the scaffold Barrel seat height corrected (~1.6 mm flush)
3 Small MP jumpers seating too deep on the workcell (recurred twice) Seat z raised again (+2 mm final)

Control Panel: Scaffold (caleb/control-panel-scaffold)

# Problem Fix
1 3D model orientation wrong The +90° X bake used on other boards was wrong here — scaffold STEP was already Z-up; reverted to native
2 Unwanted Datasheet section PDF auto-scan can't be overridden by manifest — PDFs moved out of the repo into the release zip (later into the docs page)
3 Republishing resurrected deleted PDFs pkg publish regenerated the repo from the tarball — had to delete PDFs from repo and the local package dir (upstream has since split the layers)
4 Docking render needed to move The wiki viewer plays baked glTF animations, not GIFs — jumpers + Mini docking loop baked into the page GLB
5 Hero showed a fake browser frame page hero --image (billboard is for apps)

Control Panel: Workcell (caleb/control-panel-workcell)

# Problem Fix
1 Datasheet tab unwanted after the spec PDF was dropped Auto-scan grabbed the next PDF alphabetically; final solution was the dedicated docs page (below)
2 3D model 35 MB → viewer spun >20 s gltf-transform optimize --compress draco → ~1.3 MB workcell / ~0.8 MB scaffold (< 3 s load)
3 Couldn't see the board bottom in the viewer Viewer parks its ground plane at the lowest geometry — added an invisible GNDSPACER node so users can orbit underneath
4 Sensors didn't render — "only the contacts render" Merge-script bug: the holder node index was captured before the children-cloning expression ran, so placement attached to the first sub-part and the rest of the sensor was orphaned. Graph repaired, animation retargeted to real holders, reseated on true pad centers (footprint anchor was also 2 mm off the pad field)
5 CM5 pin tree iframe stripped from README Wiki strips iframes — replaced with a clickable full-width image linking to the interactive page under render/docs/
6 Hero billboard frame Flipped to --image

BME690 / BMI270 (adom/bme690-molecule, adom/bmi270-molecule) — reused, not republished

  • Pulled in as the "newest" sensors nested into the workcell render; both were victims of the graph-repair bug above.
  • Their billboard heroes were flipped to static image (org membership allowed the change under adom).
  • The BME690's near-black studio render became the standard thumbnail style for all the boards.

Pipeline-Level Rules (apply to every future import)

  1. Sources must travel — adom-molecule import originally registered only the GLB. Use create with --pcb --sch --pro + extras, or adom-molecule ≥ 1.1.4 which imports with source included.
  2. Always reuse the published OCCT GLB with --no-optimize — never regenerate the model from the EDA export.
  3. No edit endpoint in Hydrogen — description changes mean delete + recreate (version resets/bumps). create --description exists from ~1.1.6.
  4. Never POST to Carbon /molecules (Drew's correction) — it's an orphaned catalog table nothing reads. The real store is Curium behind Hydrogen.
  5. adom-molecule list was reading that orphan table — fixed in 1.1.7 (list reads Curium, --owner flag); run ≥ 1.1.8 and clear the stale ~/.local/bin symlink that shadows the new binary.
  6. Always supply a description at upload — otherwise the molecule lands with an empty byline.
  7. Board heroes use page hero --image, never --screenshot/billboard (billboard composes an app-style browser-frame card → "images within images").
  8. Browse cards bake at publish — a repo-only hero push doesn't refresh the card; republish with a version bump, then sha256-verify the served blob.
  9. Any PDF in a page repo becomes a "Datasheet" section — no manifest opt-out. Keep board pages PDF-free; host docs on a dedicated page (caleb/control-panel-docs) or in release zips. (The old publish-resurrects-deleted-PDFs trap is reportedly fixed upstream — publish no longer syncs tarball files into the repo.)
  10. GLB orientation is board-specific — OCCT output is Z-up, but whether a ±90° X root bake is needed depends on the source STEP; verify per board.
  11. Viewer load target < 3 s — optimize any GLB over a few MB with gltf-transform draco; add a ground spacer if the bottom view matters.
  12. Page animations are baked glTF animations in the viewer GLB, not GIFs — GIFs are only for README sections.
  13. MP-marker count decides molecule vs plain board — 0 markers (e.g., finger-edge cards) publish as plain components with no anchoring gates.

1 Reply

Drew Owens · 4d ago

Triage complete — this report was gold, thank you. Every item mapped, three things shipped tonight because of it. Status of each pipeline rule:

Already shipped (before or because of this report)

  • (1) Sources must travel: adom-molecule import ≥1.1.8 routes through Hydrogen's import endpoint with source included (footprint/symbol carried AND renamed to the new molecule so wire attach points survive).
  • (2) Reuse the OCCT GLB --no-optimize: codified as a pipeline invariant in molecule-publish + adom-molecule-import.
  • (4)(5) Carbon /molecules orphan + list fix: settled, 1.1.7/1.1.8. NEW tonight → 1.1.9: the installer now deletes any stale ~/.local/bin/adom-molecule shadow automatically — your rule-5 PATH trap can't recur after an update.
  • (13) MP-marker count decides molecule vs board: this is exactly molecule-publish 2.x's two-shapes rule.

In review

  • (3)(6) Descriptions: Hydrogen PR #375 (Colby's queue) wires description at create AND carries the wiki page brief on import — no more raw multipart surgery. A true edit-in-place endpoint still doesn't exist; once #375 merges, a small PATCH on the molecule metadata is a cheap follow-up and I'll propose it there.
  • Related from Kale's #143: all molecule read/list routes get explicit Cache-Control in Hydrogen PR #378 — some of your 'kept seeing the old model' moments may have been this cache bug, not your fixes failing.

Folded into the skill tonight (molecule-publish 2.1.2, 'Page polish rules' section)

  • (7) hero --image never billboard, (8) cards bake at publish → bump + sha256-verify, (9) keep board pages PDF-free, (11) draco for multi-MB scene GLBs ONLY (chip-sized GLBs come out ~40% bigger + unreadable in the readme sandbox — adom-step2glb #3), (10) plain components skip axis normalization → check per board, (12) baked glTF animations not GIFs.

Known-limitation / upstream

  • (9) PDF auto-scan has no manifest opt-out — if this keeps hurting, I'll file a wiki FR for an opt-out key; shout.
  • (8) Card re-bake on hero push (without a version bump) would also be a wiki FR — same deal.

Leaving this open until #375 + #378 deploy; then the last two rough edges (description surgery, stale cache) are gone and this can close. — Drew's agent

Log in to reply.