Adom Wiki Skill Pack

@@ -14,13 +14,202 @@ description: >-   molecule page, pcb component, tape and reel, pin 1 orientation, pick and place,   kicad altium orcad fusion library, parametric specs, mouser digikey price stock,   provenance, prove the data, datasheet page citation, embed symbol footprint-  viewer, open chip in tool.+  viewer, open chip in tool, reusable component README, generic component page,+  component hero, chip hero, GLB orientation, Z-up, Y-up, chip standing on edge. ---  Parent skill: **adom-wiki-skillpack**  # Publishing a component (chip / molecule / PCB) +## Write for every user of the component++A purchased component page is a shared catalog record for the exact manufacturer+part number. Its title, description, Overview and README must make sense to an+engineer who has never seen the project that first used it. Lead with manufacturer,+exact MPN, function, package and source-backed capabilities. Explain general pin+functions, operating constraints, manufacturer resources and reusable library status.++Keep a particular board's reference designators, chosen resistor values, rail names,+selection rationale, experiment progress, desktop permissions and machine-specific+bridge status in that project's existing umbrella or molecule page. A short Related+link to a consuming project is useful; it must not turn the component description+into that project's progress report. Label application examples as examples, not+universal requirements. Keep shared artifact limitations on the component page when+they affect any user, with exact file/revision and evidence rather than session history.++Before publishing, search and reuse the exact component record, read its current+remote files, preserve other contributors' content and manufacturer originals, and+check which README actually renders. `readme.html` can shadow `README.md`; update+the visible prose too. Verify the live identity, generic description and source links.+Put board-specific notes in the existing project, not a new documentation repo.++## Source means authority; tools belong in provenance++The component page’s Source field identifies the manufacturer/reference authority+and links to its primary component, datasheet or CAD resource. Do not populate it+with adom-lbr, adom-symbol or another generation tool: those describe how an artifact+was produced, not where component facts and geometry originated. Record tool name,+version, inputs, transformations and original-source hashes in artifact provenance+while preserving attribution to upstream library authors.++## Default license++New Adom-authored component libraries, reference artwork and supporting code default+to an open-source license, not proprietary. State the chosen license in page metadata+and a license file. Preserve third-party manufacturer and upstream library terms+and attribution per asset; changing a page badge cannot relicense those originals.+Keep page visibility as its own user-controlled setting. When the user limits the+work to pages created in this project, this default does not authorize modifications+to pre-existing Basic Parts or other catalog records.++## Component GLB, Z-up and hero workflow++Read `adom-step`, `adom-lbr-component-fidelity` and `chip-thumbnailer` before+converting or posing a component; read [wiki-hero](../wiki-hero/SKILL.md) for hero+registration and the current `hero-studio` hardware workflow for composition.+If one is absent from the installed catalog, search the wiki by its name and read+the owning package's SKILL.md. An absent installed trigger is not evidence that+the workflow does not exist.++Adom's component/board world is **Z-up**, with the component seating plane on XY.+An original manufacturer STEP can use different axes. Preserve its bytes and hash;+record source units, source up axis, seating plane and pin-1 evidence separately+from the derived display transform. Standard glTF uses Y-up, while an Adom viewer+may already apply an axis conversion. Inspect both the GLB node transforms and the+actual viewer import/camera convention. Do not apply a blanket 90-degree rotation+twice or fix an orientation problem by changing only the camera.++For a derived GLB, retain provenance and the explicit source-to-Adom transform.+Check physical dimensions, underside/seat plane, pin-1-to-pad alignment and top+markings in the target viewer using top and oblique views before producing the+hero. A bounding box or successful conversion alone does not establish pin 1 or+seating. Inspect the physical underside contacts as well as the body: manufacturer+CAD downloads for the same MPN can differ in detail. Compare standalone STEP and+native-library STEP by original hashes, solid/face geometry and a settled underside+view. If a supplied library model omits contacts but the manufacturer standalone+model includes them, derive the display from that detailed original with an explicit+verified pose. Never invent terminal solids and attribute them to the manufacturer;+nonphysical footprint artwork is a separate layer and cannot repair missing contacts. A manufacturer's dimension mismatch remains a mismatch after rotation;+do not scale its geometry to conceal it. Preserve unverified status until checked.++Use the actual verified component geometry for a hardware hero. Virtual MPN marks+are labeled display derivatives or overlays, not claimed manufacturer markings.+Generate the matching symbol's central chip outline from the same oriented source,+preserve intelligent pin groups, and inspect symbol/footprint/model together.+Register the hero in page.json without duplicating it in the README; open the+authenticated live page in a work pane, preserve the editor and foreground, and+verify that the published model and hero have the same correct pose.++## Component creation acceptance contract++Use these Adom presentation defaults for newly authored component pages; honor a+user's explicit overrides and record the chosen values. Reusing a catalog component+does not itself authorize changing its shared page. When the user limits edits to+pages created for the current project, establish an explicit allowlist from creation+receipts/history and leave every pre-existing page, including Adom Basic Parts,+unchanged. Keep any proposed improvements to those records local unless separately+authorized. A polished+main sensor does not excuse incomplete buffers, supervisors, passives or connectors.+Keep project-specific implementation and session evidence in the existing project.++- Reuse an exact-MPN component wiki page when one exists; otherwise create one.+  Prefer validated Adom Basic Parts already on hand, then Mouser for new sourcing+  under the current InstaPCB guidance. Read `adom-basic-parts`, `instapcb` and+  `adom-parts-search`; check current stock and provenance, not historical snapshots.+  Basic Parts' validated manufacturer STEP assets are the preferred reusable source;+  verify the actual record rather than treating every available model as validated.+- Retain manufacturer datasheets and original manufacturer STEP files with source+  links, revision and hashes. Distributor access does not itself establish model+  authorship. Use the existing chip-fetcher/site skills and `adom-parts-search`.+  If browser access is required, use one Pup window with multiple tabs. Existing+  profile logins, approved credential import, Google sign-in and website email codes+  through `adom-google` are possible authorized access paths; never log secrets or+  bypass a permission rejection. Preserve provenance after browser downloads.+- Keep canonical symbol, footprint, pin-pad map and model bindings together in+  `adom-lbr`. Every IC symbol has intelligent functional pin groups and a central+  outline of its actual approved chip geometry, including small support ICs. Keep+  pin names, numbers and electrical types readable and preserve native vector art+  through exports. Conventional passive symbols must remain electrically recognizable.+- In each consuming schematic, add ordinary text explaining each chip instance's+  purpose, selection rationale, direction/power domain and unresolved assumptions.+  These board-specific explanations belong on the schematic and project page;+  they do not replace a reusable component description. Verify the comments and+  central illustration in the real webview and native imports, not only in a file.++### Readable 3D reference artwork++The physical chip remains sourced from the manufacturer. Add reference artwork as+separate named, nonphysical layers aligned to the verified footprint seating plane+in Adom Z-up. Preserve units, pin-1 orientation, pad rotations and corner radii.+Do not confuse copper boundaries with solder-mask or paste apertures.+For multi-part modules, a dot on an internal IC is not automatically the module’s+pin-1 indicator. Identify which component the mark belongs to, compare the module+pinout and physical terminal arrangement, and preserve original manufacturer marks.+Label an unverified marking honestly instead of promoting it to pin-1 evidence.++| Artwork | Required presentation |+|---|---|+| Copper-pad boundaries | Teal dashed outlines, 50% transparent (material alpha 0.50). |+| Silkscreen contours | 70% transparent (material alpha 0.30). |+| Pad labels | Actual signal/pin names, 50% transparent (alpha 0.50), placed legibly outside the body. |+| Package MPN | Exact manufacturer part number on a deliberately chosen clear surface, readable when zoomed in, using `adom-chip-laser`. |++Resolve signal names through the canonical pin-to-pad mapping and datasheet; never+substitute project net names or guess from pad ordering. Preserve active-low notation+and multi-function names. Pad numbers remain in the electrical data and pin-map+inspector; they are the fallback 3D label when no meaningful signal/pin name exists. For unnamed nonpolarized resistor/capacitor terminals, use each actual pad number so the labels remain unique; do not repeat a generic “Terminal” label. Omit uninstantiated `REF**` placeholders.+Unsupported footprint geometry or ambiguous mapping must be reported explicitly.++Read the `adom-chip-laser` skill before etching. If it is missing from the installed+catalog, find `adom/adom-chip-laser` on the wiki and read its SKILL.md. Use its actual+STEP-layer workflow for a derived marked STEP and convert that to GLB as appropriate.+Preserve the untouched manufacturer source separately. Mark the added MPN as a+virtual identification aid, not a claim about the manufacturer's real marking.+Choose the mark location from the actual geometry. Prefer a clear top area on+simple packages; for detailed or optical tops such as TMF8829, use a clear side+wall. Select the relevant manufacturer body/face, fit and orient the MPN, avoid+existing marks and pin-1 evidence, and inspect it from a suitable camera angle.+Do not alter optical windows, leads or seating surfaces. Check the+etch lies on the chosen surface and remains legible in the published viewer; a successful+service response is insufficient. Keep lights' off/lit/brightness states and motion+pivots/joints meaningful where the component participates in a digital twin.++Do not show internal CAD names such as `BODY-SON` as hover tooltips. Preserve useful+selection, geometry names and inspection capabilities; suppress low-value tooltip+presentation through the viewer's supported API. The Babylon viewer's `onMeshHover`+callback can return null to suppress a label. A temporary injected CSS rule is only+a current-window workaround, not a durable published fix. Report a missing wiki+integration option on the owning app's existing issue tracker after checking duplicates.++### Verify the visible delivery++Inspect top, oblique and underside views for body presence, seating, pin 1, exact MPN,+signal labels, dashed boundaries, material alpha and alignment. Verify imported+materials and actual pixels: a manifest or successful load does not prove appearance.+Reopen/reload to check persistent settings. Any native KiCad/Fusion/Altium model+view missing the chip fails component parity even if the footprint or board exists.+Report bridge omissions on the owning bridge project and request actionable AI hints.++Show the authenticated component page and library in a Hydrogen work pane while+keeping VS Code visible. Follow `adom-webview-wiki-review` for authentication; keep+native applications in the background using supported targeted capture controls.+Compare the same revision in KiCad, Fusion and Altium. Distinguish a verified export,+a successful import and visually validated parity. Do not claim parity from one alone.++When recording, capture real edits and purposeful inspections: scroll to relevant+specifications, follow pin groups, zoom into the MPN/pin-1 corner and orbit to pads.+Wait for model loading and camera-fit animation to settle before inspection shots.+Avoid arbitrary repetitive motion and interference with the human's camera. Keep+per-clip artifact revision, actions, useful time ranges, failure/repair labels and+separate engineering/highlight eligibility so later edits can tell either story.++Keep these conventions in this existing shared skill. Use `wiki-bloat` to decide+scope; component pages, one project umbrella and independently reusable molecules+are appropriate, while each artifact or lesson does not need another wiki repo.+Source submission, merged release, installed skill and an existing AI thread's+loaded guidance are separate states. Verify and report each honestly.+ `component` is a first-class **wiki page type** (alongside `app` and `skill`, see **wiki-api**). Structurally a component is usually the **Page** archetype; chip families use the **Family** archetype (see **wiki-repo-styles**), e.g. an `stm32f4`@@ -58,7 +247,9 @@ page.json** and push the CAD files; the wiki auto-renders:   blobs) from the `.kicad_mod`, - a **datasheet** section, and a **CAD downloads grid** (typed icons per file). -These are served at `https://wiki.adom.inc/viewer/{3d,symbol,footprint}/component/<slug>`+Resolve viewer links from the current component page. The owner-qualified route+verified on 9 September 2026 is+`https://wiki.adom.inc/viewer/{3d,symbol,footprint}/<owner>/component/<slug>` and are genuinely interactive (drag, zoom, layer toggle). They embed anywhere (the wiki dropped `frame-ancestors`), so you can `<iframe>` them into a custom page. @@ -326,3 +517,59 @@ downloads + BOM + assembly notes. Page archetype. > ⏳ This skill records the live constraints as of its writing (README.md is > sanitized, but `readme.html` custom pages SHIPPED, verified 2026-07-15; still > no page→desktop bridge). Re-verify and update when the bridge ships.++## Reuse reviewed chip artwork through the shared thumbnail widget++Before generating chip thumbnails or the illustration inside a symbol, inspect+that component's existing wiki repository for `<MPN>-thumbs.json` and the declared+artwork/cache manifest. Reuse matching cached artifacts. The component repository+is their shared home; do not keep the only copy in a project or temporary folder.++Use the wiki's existing registered `adom-chip-thumbnail` widget, maintained in+`adom/component-widgets`, and the registry instructions at `adom/widgets`. A+manifest-capable widget can summarize shaded previews, SVG outlines, editable+polylines, source files, hashes and review state from one Markdown tag:++```markdown+::adom-chip-thumbnail{src="/OWNER/COMPONENT/render/artwork/MPN-thumbs.json"}+```++Use an absolute wiki path. Keep README.md and the native symbol/footprint/3D+viewers; do not create a custom HTML README merely to show this widget. Check the+installed/live widget actually supports the manifest schema before adding tags.+A source change to a registered widget can affect every consuming page: preserve+legacy image-only use and test in the real sandbox, including the intended+reader's access level. Never widen component visibility to make a widget work.++The reusable artifact contract must include:++- Exact manufacturer part number, original manufacturer STEP hash, displayed GLB+  hash, generator/version, units, source-to-display rigid transform, and an+  explicit canonical Z-up frame. A 2D SVG can have Y-down pixel coordinates;+  that does not make the physical component Y-up.+- The selected marking surface, exact mark text, placement transform, size,+  original marking keep-outs, and hash of the reviewed marked source. Optical+  tops use a clear side wall. Reuse the reviewed placement; never call generic+  top-face embossing on an already reviewed marked model.+- Projection/camera settings, artwork source hash, SVG and editable polylines,+  per-artifact hashes/sizes, and original-authoring license scope. Include a+  reconstructible presentation source while preserving the manufacturer STEP.+- Separate review fields for display orientation, marking placement and the+  final projected artwork. Render success is not visual approval. Pin-1,+  native seating and electrical/manufacturing qualification remain separate.+- A cache key covering source geometry, pose, marking, projection and generator.+  Check it and file hashes before reuse. Model/pose/mark changes invalidate+  affected thumbnails and embedded symbol artwork. State when a hash check was+  made; never present an old publication-time check as continuous verification.++Update the chip illustration in every affected IC symbol when the approved+model or mark changes. Preserve pin numbers/names/electrical types, groups,+layout and purpose comments, and verify native export. Standard passive symbols+stay recognizable; their reusable chip artwork still belongs in their repos.++Each project-created component page should show the cache widget, even where+some artifacts are still pending; identify missing assets honestly. Respect the+user's scope restriction on pre-existing component pages. Do not regenerate a+cache merely to make every optional style exist. Verify previews and downloads,+record an inspection clip with purposeful motion, and expose machine-readable+status and next-step hints so the next AI can reuse the work economically.