CAD fidelity
The four fidelity classes for a CAD asset, the declared-zero exception, and what a preview does and does not prove.
CAD is optional (cad.enabled: false by default) and, when enabled, is honest about how well a symbol, footprint or 3D model actually represents the exact orderable variant it's attached to.
The four fidelity classes
| Fidelity | Meaning |
|---|---|
exact-vendor | Published by the manufacturer for this exact orderable variant |
family | Represents the package or series, not proven for this specific variant (for example, a generic library footprint) |
derived | Produced from an original by a recorded transformation — the receipt keeps input hashes, the script, its parameters, and output hashes |
unavailable | No usable asset; the state is documented, and nothing is fabricated to fill the gap |
A familiar-looking shape is not proof of the exact variant. Every acquired asset gets a receipt (circuit/) recording provider, product page, filename, date, SHA-256 and the fidelity class with its reasoning — see the generated project's circuit/ for the full field list.
For example, a project using the generic inventory profile could publish a Texas Instruments TMP1075DR with a family footprint: the KiCad SOIC-8_3.9x4.9mm_P1.27mm footprint fits the package outline, but its pads differ from TI's own D0008A land-pattern recommendation. The fact record and a "shared footprint package" page notice say so explicitly — a passing footprint/pin check never upgrades that to exact-vendor.
The declared-zero exception
Ordinarily, a selected PCB record with CAD disabled is a fatal configuration error — publishing a component page implies a package can be resolved. The one exception: with CAD disabled and expect.packages: 0 in the selection lock, a selected PCB record resolves no package, and its page visibly states "No footprint or 3D model is published for this record: CAD is not enabled for this project" instead of failing the build. Setting expect.packages above 0 (or leaving it unset) keeps the original error — the exception exists for a project that hasn't turned CAD on yet, not as a way to silently skip a package a reviewed selection already expects.
What a preview does and does not prove
A footprint SVG or a WRL viewer is a rendering result — nothing more. Generating one cleanly, or having it pass footprints check, does not prove pin correspondence, dimensional correctness, or physical seating. Workflow D's checklist (symbol pins vs. footprint pads vs. the datasheet pinout, 3D model dimensions vs. the mechanical drawing) is the actual verification step; the automated checks only confirm that what's committed matches what the CLI would regenerate from the same inputs.
The viewer stays WRL-only: STEP-to-WRL conversion is not provided. Where an official KiCad footprint's matched STEP+WRL pair only exists in an older tagged library release than the footprint itself, a project may pin from that older release, or record the WRL as unavailable — either way, in the receipt.
STEP is optional; WRL is required
Generation needs a WRL model for every published package — that's what the 3D viewer renders, and it's checked and projected. A STEP file, if a project keeps one for CAD-authoring or mechanical-review purposes outside this site, is never required and its absence is silent: no warning, no check failure. The one rule that does apply when a STEP file is present or declared is that it must share the WRL's basename, and its path must still pass the same containment checks as every other CAD path (relative to cad.modelRoot, no .., no absolute paths).