molecule-publish

Hi Drew. #14 gave the pipeline the ability to auto-create missing component pages for an uploaded board, and #8 set the rule that those pages are keyed by MPN. That rule has now been revised and expanded into a skill, and I think the pipeline should call it rather than keep its own page-creation logic.

Skill: adom/adom-component-page v2.0.0 (public, adom-wiki pkg install adom/adom-component-page).

What changed since #8

1. Slug is now <manufacturer>-<mpn>, not the bare MPN

ams-ams1117, umw-ams1117, microchip-lan7800.

The bare MPN cannot express a real case we just hit. AMS1117 is second-sourced: Advanced Monolithic Systems and UMW both publish a datasheet for that exact part number, and they disagree on things that matter:

One slug for both would silently merge two different parts. Two slugs cannot collide.

2. One page per DATASHEET, not one page per MPN

This is the part I think matters most for the pipeline, because a board BOM is exactly where it goes wrong.

The datasheet draws the family boundary. If a datasheet covers six voltages across three packages, that is one page covering all six, not six pages. A board that happens to use the 3.3 V part should have its component page cover the whole family, so the next board that uses the 1.8 V part links to the same page instead of creating a sibling.

Concretely: adom/ams1117-3-3 and adom/ams1117-1-2 both exist today, both are per-variant splits of one datasheet family, and both are now being deprecated. A pipeline that creates a page per BOM line will keep generating those.

3. Pages render through a hand-built readme.html

Fixed ten-section shape (identity, at a glance, specifications, symbol + footprint viewers, pin map, variants, assets, implementation, datasheet, provenance), on the Adom theme tokens. templates/readme.html in the skill is the skeleton. README.md is shadowed by it.

4. Missing things get a placeholder, never silence

If a file or a fact is not available, the page says so and links to opening a pull request. A missing Assets row reads as "this part has no Altium library". A placeholder reads as "nobody has contributed one yet", which is true and actionable. This is the pattern the pipeline needs most, because an auto-created page from a board upload will almost always be missing a datasheet, real specs and a pin map.

What I am proposing

When the pipeline auto-creates a component page for an uploaded board:

1. Resolve the manufacturer, not just the MPN, and slug <mfr>-<mpn>.
2. Dedup against three shapes before creating: <mfr>-<mpn>, the legacy bare <mpn>, and the base part (searching ams1117 surfaces ams1117-3-3, which is the signal that a family page is what is wanted).
3. Do not create a page per BOM line without a boundary check. If the part is one row of a datasheet's ordering table and a family page exists, link it and stop. If no family page exists, create the family page rather than the single variant.
4. Emit readme.html from the template, with placeholders wherever board-derived data cannot fill a section.
5. Keep the existing library/dependency wiring from #14 and #15, just pointed at the new slugs.

Steps 1, 2 and 4 are mechanical and I think drop straight into the current code path. Step 3 is the one that needs judgement, and it may be the right call for the pipeline to flag rather than decide: create the page, tag it needs-family-review, and let a human confirm whether it should be folded into a family. Happy either way, and happy to be told step 3 is out of scope for an automated path.

What is already in the skill you can lift directly

• scripts/inject_layers.py works around adom-footprint 1.0.20 emitting the fab, silk and courtyard layer groups empty (adom/adom-footprint#2). Without it, every footprint viewer on every auto-created page shows floating pads with no component outline. This affects the pipeline's existing pages today.
• scripts/build_switcher.py wraps N footprint embeds into one package switcher, for family pages with several packages.
• templates/page.json and templates/readme.html.
• reference/worked-example.md is the AMS1117 build end to end with every command, including the two places it went wrong first.

Two defects this surfaced, since they came from published pages

Both are real and both are the kind of thing an automated path will reproduce at scale:

1. adom/ams1117-3-3 ships a footprint with the tab on pad 4 as its own net. The AMS1117 tab is VOUT (pin 2). The heat path ends up floating. The fix is picking the land pattern by the datasheet's pin function, not by package name: SOT-223-3_TabPin2, not SOT-223.
2. adom/ams1117-1-2 ships a footprint that is entirely on back layers (B.Cu / B.Mask / B.Paste / B.SilkS / B.Fab / B.CrtYd) with no front geometry at all. Anything placed from it lands bottom-side.

No rush on any of this, and push back freely if the boundary rule is too much for an automated path to carry.