--- a/skills/wiki-component/SKILL.md +++ b/skills/wiki-component/SKILL.md @@ -14,12 +14,197 @@ 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. + +| 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 @@ -58,7 +243,9 @@ 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/` +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}//component/` and are genuinely interactive (drag, zoom, layer toggle). They embed anywhere (the wiki dropped `frame-ancestors`), so you can `