by adom
The one-stop-shop for publishing a hardware component (or molecule/board) to the Adom Wiki. The whole lifecycle: page anatomy, the clone→edit→preview→push loop and its hard rules, making a great hero image (Hero Component Studio — 16:10, overlay-safe, datasheet-backed), the animated 3D composite, the interactive 3D viewer, ct thumbnails, the datasheet-accuracy audit, and every wiki push/pull gotcha we've hit. Now includes the worked Path B (board) pipeline: STEP-to-GLB, refdes tagging, layer de-
← Commit history
SKILL.md+208−13@@ -132,17 +132,65 @@ end as the one seamless full-page README (§5.0).** default dwell. The author's whole input is one small JSON file; the geometry does the rest. Worked example: the feeder-reader mock's `viewer-config.json`; runnable viewer: `scripts/board-viewer-template.html`.+ - **PACE — the first cut is always too slow.** A caption you have already read is dead air, and+ a viewer that feels slow gets abandoned before the last grouping lands. Author the timeline+ **1.5× faster than feels right on the first pass** — i.e. divide every *duration* by 1.5+ (`drop_height_mm` is a distance, leave it). Use these as the **starting defaults**, not the+ numbers you slow down from:++ | Key | Value | Why |+ |---|---|---|+ | `fall_s` | **0.47** | the drop reads as a snap, not a float |+ | `stagger_s` | **0.027** | members of one grouping land as a beat |+ | `dwell_s` | **6.3** | enough to read eyebrow + head + rows, not to re-read |+ | `rest_s` | **4.0** | the closing look at the finished board |+ | per-group `d` | **4** for short captions (intro, mounting) | 2–3 rows do not need a full dwell |++ Tune a group UP only when its caption genuinely has more rows to read — never tune the whole+ reel down. (Verified on `adom/feeder-reader`: the original 0.7 / 0.04 / 9.5 / 6.0 pass read as+ sluggish; these values are that reel at 1.5×.) 2. **Provenance per §7B** — every table generated from the design files, DNP honoured, and every claim labelled generated / author-asserted / illustrative.-3. **Board maps instead of symbol/footprint SVGs** (a board has no schematic symbol): top + bottom- renders from the `.kicad_pcb` with pads coloured by functional section- (`scripts/kicad_board_map.py`).+3. **Schematic + layout come from the two Adom viewer apps — do NOT hand-roll them.** Earlier+ drafts of this skill invented their own board maps (`scripts/kicad_board_map.py`) and leaned on+ the wiki's plain `render/sheet-*.svg` images. Both are superseded: there are real, maintained+ apps that render the **EDA's own output** and add live interactivity, so a board page embeds+ those instead of static pictures.++ | Need | App | Command |+ |---|---|---|+ | Schematic (`.kicad_sch`, every sheet) | [`adom/adom-schematic-viewer`](https://wiki.adom.inc/adom/adom-schematic-viewer) | `adom-schematic-viewer embed --file <sheet>.kicad_sch --out sch-<n>.html` |+ | PCB layout (`.kicad_pcb`) | [`adom/adom-layout-viewer`](https://wiki.adom.inc/adom/adom-layout-viewer) | `adom-layout-viewer embed --file <board>.kicad_pcb --out layout.html` |++ - `embed` emits **one self-contained interactive HTML file** (SVG + metadata + viewer JS inlined,+ no external assets) — which is exactly what the wiki's sandboxed readme frame can host, and it+ keeps working on a **private** page with no cap plumbing at all (see §8k-vii).+ - What you get over a flat image: schematic — hover a symbol for KiCad-style highlight plus live+ MPN / stock / price / LCSC / wiki link, click to pin the card, and a component list linked to+ the drawing. Layout — click any pad/via/trace/zone to highlight the **whole net** while the+ rest dims, hover for pad number/size/shape/side/net + live part data, independent layer+ toggles and Top/Bottom mirroring.+ - Embed one `<iframe>` per schematic sheet (name them from the sheet, not `sheet-000`) and one+ for the layout; side panels auto-hide below 620 px, so give each frame real height.+ - Install: `adom-wiki pkg install adom/adom-schematic-viewer adom/adom-layout-viewer`. Both need+ `KICAD_SERVICE_API` (service-kicad) for the authentic render; the layout viewer self-renders if+ it can't reach it (and looks less like KiCad, so prefer having it up). 4. **`page.json` mapping for a board** (the schema is component-shaped; use this convention): `component.mpn` = the KiCad project name, `component.manufacturer` = the org (e.g. `Adom`), `component.category` = `board`, `component.model_3d_path` = the baked board GLB. Mandatory- files (the Path B analogue of Path A's datasheet PDF): the **board GLB**, the **board maps**,- and the **KiCad source** (or a pointer to where it lives).-5. **Any additional information the user wants to add** — a board page is theirs to compose.+ files: the **board GLB**, the **KiCad source** (or a pointer to where it lives), and the two+ **viewer embeds** from item 3.+5. **NO DATASHEET on a board or molecule page.** A board is not a catalogue part — it has no+ manufacturer datasheet, and a page that shows one is asserting a document that does not exist.+ Concretely: **ship no PDF in the repo.** The wiki auto-scans any PDF into a "Datasheet" section+ and *there is no manifest opt-out* (molecule-publish, page-polish rules), so a stray+ `<project>.pdf` silently grows a datasheet section nobody authored. The schematic and layout+ viewers of item 3 ARE the board's documentation — they replace both the datasheet and the+ "Symbol & Footprint" slot (a board has no schematic symbol either). If a board genuinely needs+ long-form docs, put them on a dedicated docs page or attach them as **release assets**, never as+ a PDF in the page repo. (Path A component pages are the opposite — there the datasheet is+ mandatory and every number cites it, §7.)+6. **Any additional information the user wants to add** — a board page is theirs to compose. Everything else — publishing mechanics, the **hero image and grid thumbnail** (§3), the wiki clone→push loop (§2), and every gotcha (§8) — is **shared** by both paths and applies to each.@@ -550,6 +598,104 @@ the FOV overlay at the datasheet 2θ½; glow colour → the dominant wavelength datasheet packing table; electricals (VF, IV, λD/λP) → tooltip datasheet rows. When all of that is in the model + tooltips, the viewer stands in for the datasheet for everyday reference. +### 5b-2. Path B sits INSIDE the molecule-pipeline — use it, don't reinvent it++A board/molecule page is not a bespoke artifact this skill invents from scratch: it is the output of+[`adom/molecule-pipeline`](https://wiki.adom.inc/adom/molecule-pipeline), the org's router for moving+a design from an EDA → the wiki → Hydrogen. **This skill composes that pipeline and adds the page+craft** (viewer choreography, hero, prose, provenance). Anything below that the pipeline already+owns, let it own — hand-rolling it is how pages drift out of spec.++```+KiCad ──kicad-export-molecule──┐+Fusion ─fusion-export-molecule─┼→ molecule-publish → WIKI → adom-molecule-import → HYDROGEN+Altium ─altium-export-molecule─┘ (convert+package+publish) (fetch + register)+```++Install: `adom-wiki pkg install adom/molecule-pipeline` (plus your EDA's export skill).++**Which shape am I?** Adom machine pins + MP1–MP4 markers → **molecule** (anchoring + footprint /+symbol JSON + all stats gates). Otherwise → **board** (plain convert, tag `board`, no anchor gates).+A plain PCB that *should* become a molecule goes through `kicad-to-molecule` first.++**Pipeline invariants that bind this skill (violate one and the page is broken, not just untidy):**++1. **The full published set reaches the wiki.** Molecule = OCCT GLB + STEP + schematic + board ++ footprint/symbol JSON. Plain board = GLB + STEP + **every** schematic sheet + board + project+ file. Both also carry the `render/` assets and component `dependencies`.+2. **The only GLB is OCCT's** (`step2glb`) — never an EDA-native export (KiCad / Fusion /+ service-kicad), which bypasses anchoring, gold pins, meter normalisation and footprint emit.+ ⚠️ This **supersedes** the `service-kicad pcb export glb-zup` shortcut: that is fine for a quick+ local preview, never for the published model.+3. **STEP is exported on the design machine** so custom 3D models bake in.+4. **Every stage verifies before the next starts** — a failed gate stops the run; never "probably fine".+5. **Import reuses, never regenerates** (`--no-optimize`).+6. **Every emitted GLB declares its up-axis** (`asset.extras.adomMolecule.upAxis`). An unstamped+ Y-up `render/board.glb` renders sideways on the wiki *and* wrong in APM — no single guess fixes both.++**Name the GLB exactly `<slug>.glb`.** At publish the wiki auto-converts the STEP into a *plain*+`<slug>.glb` and points `model_3d_path` at it — if your anchored GLB has any other name, the plain+one shadows it and every import silently gets an unanchored model. (This is what broke the COSMIIC+boards.) Verify by sha256: the GLB served at `model_3d_path` must be byte-identical to your gated+conversion output.++#### Versioning + the `render/` archive — `adom-nucleus` OWNS this++```bash+adom-wiki pkg install adom/adom-nucleus # once per container (APM was renamed to adom-nucleus)+adom-nucleus --render-board <slug> # AFTER pkg publish + repo push — ordering is load-bearing+```++- **Never hand-write `render/<version>/` or edit `render/manifest.json`.** `--render-board` fully+ owns the archive and content-dedups; double-writing fights it. (Learned the hard way on+ `adom/feeder-reader`, where a hand-built manifest had to be handed back to the tool.)+- Run it **after** publish: it stamps the archive with the version it reads from the *published*+ `package.json`. Run it early and it stamps the previous version.+- It renders + pushes top-level `render/*` = current version, then, **only if content changed**,+ writes `render/<version>/…` and prepends a `versions[]` entry to `manifest.json`+ (v2: `{v:2, current, versions[]}`, newest-first). A deps/metadata-only republish adds no entry.+- Verify: `manifest.json` parses, `current` == the version you just published, a content change+ added a `versions[]` entry, a metadata-only republish did not.+- **The registry tarball is the source of record per version** — `pkg install <owner>/<slug>@<version>`+ delivers any past version's real sources. `render/` is previews only, never source.+- Re-run on every content update so it never goes stale.++#### Component dependencies + auto-created part pages (NOT optional)++A board whose `dependencies` is `{}` while it has electrical parts is a **failed publish** — it looks+fine but shows up in APM/adom-nucleus with no BOM panel. The graph is+**`board → <board-slug>-library → components`**:++1. Parse the BOM (CSV beside the sources, else the `.kicad_sch`); **electrical rows only** — skip+ logos, silkscreen art, fiducials, mounting holes, mechanical symbols.+2. **Resolve the real MPN per row. Key components by MPN, never by value.** `R_4.3K_0402` is a+ property, not an identity; a row with no MPN and no unambiguous standard part is **FLAGGED for a+ human**, never silently dropped.+3. Create/update `<board-slug>-library` (`type: component`, `tags:["library"]`, a `library.step` so+ the 3D lint passes, hero + description) whose `dependencies` are the owner-qualified component+ refs. The board's `dependencies` is then exactly `{ "<owner>/<board-slug>-library": "*" }`.+4. **Auto-create any missing component page** (`type: component`, slug/title = normalized MPN) with+ `<MPN>.kicad_sym` + `<MPN>.kicad_mod` + STEP + step2glb GLB + `<MPN>.adom-lbr.json` + hero ++ `component` block. Assets come from the KiCad stdlib via `service-kicad` (`fp fetch`, `sym fetch`,+ `model fetch`), else from the board's own embedded footprint/symbol blocks. 3D is hard-required by+ publish lint — if a part's model exists only in the designer's local library, **flag the page as+ pending with the exact missing file; never fabricate geometry and never drop the part.**+5. **Order, one version per cycle:** component pages → library → board. A dep must exist when the+ depender publishes. Merge everything *before* the board's publish so the cycle produces exactly+ one registry version. MERGE deps, never overwrite (`component`, `hero`, `tags`, `model_3d_path`+ must survive).+6. **Inherit the board's visibility.** A private board's library and component pages are published+ **`--private` to the same org** — a public part page hanging off a private board leaks the design.++**Completion checklist (a Path B publish is NOT done until all pass):**++- [ ] `metadata.model_3d_path` set; page GLB sha256 == your gated conversion output+- [ ] board deps = its library page; library deps = every electrical BOM part+- [ ] every referenced component page exists, or is explicitly flagged pending with what it needs+- [ ] `render/manifest.json` present with `current` == the version just published+- [ ] no PDF anywhere in the repo (Path B item 5)+- [ ] molecule shape only: provenance stamp + footprint/symbol artifacts+ ### 5c. Path B build pipeline — board STEP → tagged, viewer-ready GLB Worked end-to-end on the Feeder Reader (130×50 mm, 4-layer, 143 footprints, 303 solids). Every@@ -629,7 +775,11 @@ driving the debug handle, not by waiting. --- -## 6. ct/ thumbnail bundle (standard on every page)+## 6. ct/ thumbnail bundle (standard on every COMPONENT page)++> **Path A only.** A board/molecule has no schematic symbol and no footprint, so it gets **no+> `ct/` symbol+footprint pair and no "Symbol & Footprint" section** — its equivalents are the+> `adom-schematic-viewer` + `adom-layout-viewer` embeds (Path B item 3). ```bash # stage the part's STEP into the chip-fetcher library, then:@@ -891,6 +1041,28 @@ Component pages take any hero image, but **new app/skill pages** hard-reject at the CLICK must be human. If the studio webview looks frozen, check the tab's **proxy mode** (`adom-cli hydrogen webview set-proxy false --name …`) — proxy mode silently blocks page JS. +**8k-vii. Interactive embeds on a PRIVATE page — signed caps, and the nested-srcdoc trap.**+Publisher HTML (readme frame, blob previews, `component.viewers` slots) is served sandboxed WITHOUT+`allow-same-origin`, so it runs as an opaque origin and its fetches are anonymous — on a private page+every asset 404s and the viewer comes up blank. As of `adom/wiki#73` the wiki fixes this with+**short-lived, page-scoped signed caps**: while serving a frame to an authenticated reader it mints a+token, injects a bootstrap that wraps `fetch` and rewrites `img/source/video/audio` srcs to append+`?cap=<token>` on same-host URLs, and the file routes (`/api/pages/.../files/*`, `/blob/*`) accept it+as the read grant. Verified on `adom/feeder-reader`: cap-only fetch = 200, no cap = 404.+Two things that will still bite you:+- **A nested sandboxed `srcdoc` iframe is a SEPARATE document** — it gets its own unpatched `fetch`+ and no `window.__wikiCap`, so the bootstrap does not reach a viewer embedded that way. Fix from the+ parent (which *does* have the cap): keep the frame's HTML in an inert `data-*` attribute, substitute+ the cap into it, then assign `srcdoc` once.+- **The bootstrap is appended at the END of the served document**, so any inline script that reads+ `window.__wikiCap` earlier sees `undefined` (silently → no cap → 404 → "bundle failed to load").+ Defer to `DOMContentLoaded` and poll briefly for the token before substituting.+Two ways to sidestep the whole class: the **native** viewers (trusted, unsandboxed, already+authenticated), and **self-contained** embeds like `adom-schematic-viewer/adom-layout-viewer embed`,+which fetch nothing. Note the readme itself is capped at **4 MB rendered** (`README_TOO_LARGE`), so+inlining a multi-MB 3D bundle+model into README.html is not a viable workaround — that is what the+cap mechanism is for.+ **8l. `WIKI_STRICT_AUTH`** rejects a push without a real author (`set-author`) + a changelog (≥2 words / ≥10 chars, specific). @@ -957,6 +1129,17 @@ reflects the corrected pads. - **`adom-wiki-hero-image`** (`adom/adom-wiki-hero-image`) — the canonical hero spec (16:10, 1600×1000@2×, midnight theme, one-app-one-screenshot). - **`adom-basic-parts`** — the basic-parts inventory + per-MPN slugs.+- **`molecule-pipeline`** (`adom/molecule-pipeline`) — **the router this skill's Path B sits inside**+ (§5b-2): EDA export → `molecule-publish` → wiki → `adom-molecule-import`. Owns the shape rules,+ the conversion gates, the dependency/library graph and the pipeline invariants.+- **`molecule-publish`** (`adom/molecule-publish`) — the convert/package/publish middle: OCCT+ conversion + stats gates, component dependencies + auto-created part pages, and the publish+ completion checklist.+- **`adom-nucleus`** (formerly `adom-project-manager`) — **owns `render/` and the per-version+ archive** via `--render-board <slug>`; also the consumer of the dependency graph (BOM panel).+- **`adom-schematic-viewer`** / **`adom-layout-viewer`** — the interactive schematic and PCB embeds a+ board page uses **instead of** hand-rolled board maps or static sheet images (Path B item 3).+- **`adom-step2glb`** — the OCCT conversion CLI/service that produces the one blessed GLB. ## Status — what's PROVEN vs still to build (read before trusting a section) @@ -967,8 +1150,17 @@ Be honest about maturity so nobody assumes a section is turnkey when it isn't. full-page README, the full-page **Timeline viewer** embed, static symbol/footprint SVGs, the hero from Hero Component Studio, the readme-frame self-sizing, the whole wiki push/rm flow. +**Proven LIVE on a private board page** (`adom/feeder-reader`, adom-org private):+- The **whole Path B page published and verified as an org member**: the two-mode interactive+ viewer (Assembly timeline + Static) rendering inside the private readme frame via the wiki's+ signed **caps** (§8k-vii, `adom/wiki#73`), alongside the native 3D viewer.+- The **cap plumbing for a nested sandboxed `srcdoc`** — the parent-substitution + deferred-token+ pattern in §8k-vii, which is what makes a custom viewer work on a private page at all.+- **What does NOT work on a private page:** inlining a self-contained multi-MB bundle+model into+ README.html — the readme render cap is 4 MB (`README_TOO_LARGE`). Measured at 26.8 MB.+ **Proven as a LOCAL mock** (built end-to-end on the **Feeder Reader** board — 130×50 mm, 4-layer,-143 footprints — viewed in the wiki-faithful preview harness; not yet pushed to the wiki):+143 footprints — viewed in the wiki-faithful preview harness): - **The Path B pipeline (§5c):** STEP→GLB (step2glb service verified; cascadio for trimesh-bound bakes), refdes tagging from the node hierarchy (297/297), stale-geometry detection (caught a real 7.3 mm post-export move), sheet-derived sections, transform baking, layer de-fighting,@@ -978,15 +1170,18 @@ Be honest about maturity so nobody assumes a section is turnkey when it isn't. user for 5 s on input) and **Static** (free camera, hover tooltips, legend isolate, author-specified toggles like Power) — config-driven via `adom-board-viewer-config/0.2` (`blocks[]` + `modes.assembly` + `modes.static`, see §Path B).-- **Board maps** (`scripts/kicad_board_geom.py` + `kicad_board_map.py`) and the **preview- harness** (`scripts/preview_readme/` — real sandbox flags + the readme-height handler + CORS).+- The **preview harness** (`scripts/preview_readme/` — real sandbox flags + the readme-height+ handler + CORS).+- ⚠️ **`scripts/kicad_board_map.py` / `kicad_board_geom.py` are SUPERSEDED** — board maps were this+ skill's own invention; a board page now embeds `adom-schematic-viewer` + `adom-layout-viewer`+ (Path B item 3). The scripts remain only for the section-colouring data the viewer config uses. **Still to build for Path B:** - **A `board-viewer-cli`** — the config shape exists and is authorable as JSON, but the "never hand-edit, go through a CLI" rule has no CLI yet for board viewer configs.-- **Publishing an actual board page to the wiki** (the mock proved the content pipeline and the- sandbox behaviour locally; the push itself is the standard §2 flow but hasn't been exercised- for a board).+- **Full molecule-pipeline conformance on a real page** — §5b-2 documents the invariants,+ `adom-nucleus --render-board` versioning, and the library/component dependency graph from+ `molecule-publish`; exercising all of it end-to-end on `adom/feeder-reader` is in progress. - **Board visual functions** (LEDs blinking, indicators). The LED-lighting method is referenced (Caleb's playbook) but not built into our tooling; the data-HUD path (§Path B) is the proven alternative for non-visual boards.
package.json+7−3@@ -2,7 +2,7 @@ "slug": "adom-hardware-component-publish", "title": "Publish a Hardware Component to the Adom Wiki", "type": "skill",- "version": "0.8.0",+ "version": "0.9.0", "description": "The one-stop-shop for publishing a hardware component (or molecule/board) to the Adom Wiki. The whole lifecycle: page anatomy, the clone\u2192edit\u2192preview\u2192push loop and its hard rules, making a great hero image (Hero Component Studio \u2014 16:10, overlay-safe, datasheet-backed), the animated 3D composite, the interactive 3D viewer, ct thumbnails, the datasheet-accuracy audit, and every wiki push/pull gotcha we've hit. Now includes the worked Path B (board) pipeline: STEP-to-GLB, refdes tagging, layer de-fighting, two-mode board viewer (Assembly merged with explanation + free-camera Static) template, board maps, preview harness. A living, refinable skill \u2014 add gotchas via PR. Private, Adom-only.", "tags": [ "skill",@@ -18,7 +18,11 @@ "adom", "reference" ],- "dependencies": {},+ "dependencies": {+ "adom/molecule-pipeline": "*",+ "adom/adom-schematic-viewer": "*",+ "adom/adom-layout-viewer": "*"+ }, "scripts": { "install": "./install.sh", "uninstall": "./uninstall.sh"@@ -62,4 +66,4 @@ "adom-hardware-component-publish" ], "discovery_pitch": "The one-stop-shop for putting a hardware component on the Adom Wiki and having it look right \u2014 the push loop, a great hero image, the 3D composite/viewer, and every gotcha, in one place."-}+}
page.json+6−2@@ -2,7 +2,7 @@ "slug": "adom-hardware-component-publish", "title": "Publish a Hardware Component to the Adom Wiki", "type": "skill",- "version": "0.8.0",+ "version": "0.9.0", "description": "The one-stop-shop for publishing a hardware component (or molecule/board) to the Adom Wiki. The whole lifecycle: page anatomy, the clone→edit→preview→push loop and its hard rules, making a great hero image (Hero Component Studio — 16:10, overlay-safe, datasheet-backed), the animated 3D composite, the interactive 3D viewer, ct thumbnails, the datasheet-accuracy audit, and every wiki push/pull gotcha we've hit. Now includes the worked Path B (board) pipeline: STEP-to-GLB, refdes tagging, layer de-fighting, two-mode board viewer (Assembly merged with explanation + free-camera Static) template, board maps, preview harness. A living, refinable skill — add gotchas via PR. Private, Adom-only.", "tags": [ "skill",@@ -18,7 +18,11 @@ "adom", "reference" ],- "dependencies": {},+ "dependencies": {+ "adom/molecule-pipeline": "*",+ "adom/adom-schematic-viewer": "*",+ "adom/adom-layout-viewer": "*"+ }, "scripts": { "install": "./install.sh", "uninstall": "./uninstall.sh"