molecule-publish

For Drew.

Decision

We're dropping the auto-generated library wiki page from the molecule/board pipeline. A board/molecule should depend on its component pages directly:

before:  board ──> <board-slug>-library ──> components      (#15)
after:   board ──> components

Stage 2.6 (auto-create the missing component pages) is the good half and stays. It's specifically the synthetic <board-slug>-library page — and the gate rule that requires one — that should go.

Why

The library page was introduced in #15 to carry the parts list off the board. In practice it's an extra generated page per board that buys nothing and costs a lot:

1. It's a page nobody wants. Every board publish mints a second wiki page whose only content is a dependency list, plus a library.step that exists purely to get past the 3D lint, plus a hero and a description. 19 of the 21 library-tagged pages on the wiki right now are these board-specific stubs. They're hidden from the gallery by default, which is the tell — they're pipeline plumbing wearing a wiki page as a costume.
2. It's a recurring source of bugs, all of them about the indirection itself.
   • #5 — libraries inheriting the parent's board/molecule kind tag, so they render as boards. Closed, then recurred on the CoSMIIC set.
   • #17 — both Taprite carriers shipped green with a dep on a -library page that was never published. The board declared a library, the gate passed on the shape, APM expanded one hop into nothing and showed an empty BOM. One page in the chain is one more page that can 404, and it's the one no human ever looks at.
   • The gate has to special-case libraries throughout (is_library slug/tag sniffing, the stray-kind-tag check, the "board deps contain no -library page" FAIL). All of that complexity is the indirection defending itself.
3. Nothing reads it as a library. The only consumer is APM, and APM just expands it one hop straight back to the components. It was never a real grouping — it was a level of indirection that a consumer immediately undoes.
4. The dependency graph is the better place for this. board -> component is what the registry graph is for, and it's what the wiki dependency graph renders. Routing it through a stub makes the wiki's own graph less informative, not more.

What to change in molecule-publish

SKILL.md Stage 2.5

• Step 4 currently says "Publish the refs through a LIBRARY page (#15) — the board does NOT carry the raw parts list". Invert it: the board's dependencies is the owner-qualified component refs. Drop the <board-slug>-library creation, the library.step, the ["library", <topical>...] tagging rule, and the board -> library -> components graph diagram.
• Step 5 ordering becomes components → board (no library in between). Everything else in that step (one registry version per cycle, deps must exist before the depender publishes) still holds.
• The Stage 3 verify checklist line board dependencies = its library page; library page dependencies = ... becomes board dependencies = its component pages.
• Keep, unchanged: MPN-only identity (#142 / #8), reuse-over-recreate namespace probing, the publish throttle, merge-never-overwrite on dependencies, and all of Stage 2.6.

scripts/component_graph.py — cmd_gate

• Remove the FAIL: "board deps contain no '<board-slug>-library' page - the graph must be board -> library -> components (#15)".
• Remove the WARN: "board depends on raw component pages as well as its library" — that shape is now the correct one.
• Replace both with a check that the board's own dependencies cover the electrical BOM: every non-flagged electrical part in the plan should have a ref in deps. That's a stronger check than the old one (it catches a board that declares three parts out of forty, which the library rule never did) and it's now possible because the parts are on the board.
• The is_library branch and the stray-kind-tag check (#5) can stay as legacy validation only, so a re-publish of an existing library page still gets caught — but nothing should ever require or generate one.
• --allow-no-components keeps its current meaning.

plan output — the per-part table stays as-is; only the assembly step downstream of it changes.

Backward compatibility

Please don't break the boards already published on the old shape. Consumers should keep resolving board -> library -> components when a library dep is present; it just stops being produced. I've already done that half in APM (below).

Migration

19 board-specific library pages exist today (adom/*, barrett-land/*, noah/*, Ray/*, AravK/feeder-reader-library). Suggest a backfill pass that, per board: copies the library's dependencies onto the board, re-publishes the board, then marks the library page deprecated. Happy to run that for the adom/ + barrett-land/ ones once the pipeline change lands — I'd rather not do it before, or the next publish just regenerates them.

Two library-tagged pages are not in scope and should be left alone — they're genuine standalone libraries, not per-board stubs:

• barrett-land/adom-machine-parts-library (the machine pin/contact library, consumed by adom-library-importer)
• John Lauer/adom-basic-parts-fusion-lbr

Consumer side — already done

adom-project-manager is updated and building (board_deps in src/main.rs):

• A board's dependencies that are component pages are listed directly as its components.
• A dependency that is a library page is still expanded one hop, so every board already published keeps showing a BOM.
• The classification now keys on the page's identity (slug suffix / library tag) instead of the old "does this dep have dependencies of its own" heuristic. That heuristic was actively wrong under the new shape: a board depending directly on a component page that happens to carry dependencies would have had its children listed in place of the part itself.

Verified against both shapes: adom/usb3-to-ethernet-dataonly-molecule (legacy, via -library) still resolves 28 components, and adom/bme690-molecule / bmi270-molecule / bmv080-molecule / ams1117-3v3-molecule (direct deps) resolve theirs.

Note on #17

Once boards depend on components directly, #17's specific failure (a dep on a library page that was never published) mostly disappears with the library. The underlying ask there still stands and gets more valuable, not less — the gate should resolve every declared ref against the registry, not just check the shape, because a component page can exist while its package doesn't.

— Barrett's agent