Public command

design

Generate a KiCad design review bundle from a KiCad project or schematic input.

Usage

kicad-cruncher design project.kicad_pro -o output/design
kicad-cruncher design-review project.kicad_pro
kicad-cruncher dr project.kicad_pro
kicad-cruncher design schematic.kicad_sch
kicad-cruncher design --no-indexes

Arguments

file accepts .kicad_pro and .kicad_sch. If no file is provided, the command auto-detects exactly one .kicad_pro in the current directory. PCB-only inputs are intentionally rejected because the review bundle is centered on the schematic-backed KiCadDesign aggregate.

-o selects the output directory. Without -o, artifacts are written under ./output/design/. --no-indexes omits optional legacy lookup indexes from the design JSON but retains the compiled graph and SVG graph view. design-review and dr are aliases for the same command and output contract.

Ownership

The KiCad semantic model, compiled graph, netlist, Plotter-IR, and base SVG contracts are owned by kicad-monkey. kicad-cruncher owns CLI orchestration, review enrichment and theme, artifact layout, budgets, and transactional publication; Monkey must not depend on Cruncher or acquire higher-level report concepts.

On the promoted Windows x64 executable path, Cruncher composes the Monkey Rust crates directly. It loads the exact project/schematic carriers, creates one source-bound structured-facts handle, produces Design JSON and both netlists, renders occurrence-bound schematic and per-copper-layer PCB review SVGs, and publishes the complete bundle without Python or the kicad-monkey-native transport process. The Python module path remains the cross-platform implementation and exact migration oracle; its Windows native-provider environment switches describe that legacy module path, not the standalone Rust executable.

Output

The command writes the following files into the selected output directory:

<input-stem>_design.json: kicad_monkey.design.a0 JSON.
<input-stem>_compiled_schematic_graph.json: the exact compiled_schematic_graph object from the Design JSON.
<input-stem>_netlist.json: kicad_monkey.netlist.a0 JSON.
<input-stem>_netlist.net: kicad-cli-style S-expression netlist.
design_review_manifest.json: kicad_cruncher.design_review_manifest.a0 artifact index, including native source/netlist provenance when that provider is selected.
README.md: agent-facing explanation of the generated bundle.
schematics/*.svg: one enriched schematic SVG per concrete hierarchy instance.
pcb/copper_layers/*__review.svg: one enriched PCB review SVG per copper layer when a board is present.

DesignReviewGraphLinkage

Rationale

Review agents need authoritative connectivity and hierarchy context for rendered schematic objects without joining by mutable labels or reconstructing nets from geometry.

Purpose

The bundle writes the exact Monkey compiled graph once and gives every schematic SVG a page-scoped forward/reverse view over that graph. The authoritative drawing key is page_occurrence_ref + artifact_key + element_id.

Test Requirements

L3 verifies exact graph equality with Design JSON, final SVG selector uniqueness, reused page ownership, --no-indexes, nested Megamaid discovery, and consumer-only SVG-to-net-to-component and graph-to-SVG traversal.

Working Definition

The interface is working when every advertised graph selector resolves exactly once in its owning SVG and an artifact-only consumer can traverse connectivity and hierarchy without names, text, DOM order, or geometry.

Design JSON

The design JSON keeps the kicad_monkey.design.a0 schema unchanged. It includes project metadata and text variables, schematic hierarchy, sheet instances, components, nets, variants, optional PnP data, and optional lookup indexes. kicad-cruncher does not rename text_variables or add duplicate parameter fields.

Higher-level applications should use the JSON relationships and SVG link fields together. Repeated hierarchical sheets can share source UUIDs, so instance-aware fields such as sheet path and sheet instance path must be preserved.

Schematic SVGs

Schematic SVGs use the enriched kicad-monkey schematic SVG contract. Groups are wrapped around source objects so tools can connect rendered graphics back to symbols, pins, sheets, ports, power symbols, and nets. Each metadata payload includes compiled_schematic_graph_view, which identifies the canonical page occurrence and indexes graph links by SVG element id and graph target. Filenames use the concrete sheet instance name, not just the reusable schematic source filename, so repeated hierarchical sheets are reviewable as separate pages.

The design-review command uses the kicad_cruncher.design_review.schematic_svg.a0 black-and-white schematic role theme from kicad-monkey. The root enrichment attributes and schematic-enrichment-a0 metadata payload are embedded in every schematic SVG, so tools still map graphics back to source objects and nets.

PCB Review SVGs

Each PCB review SVG contains one copper layer plus Edge.Cuts. Physical geometry comes from kicad-monkey enriched PCB SVG output. kicad-cruncher only adds root review attributes such as data-review-theme, data-review-layer, and data-review-draw-order, then recolors existing SVG elements according to the review theme.

The command reuses a render cache for the duration of one design-review bundle. The cache preserves the same enriched metadata, root viewBox, width, height, and coordinate framing as the direct per-layer render path, but avoids rebuilding the board IR for every copper layer. The cache is not shared across daemon, plugin, process, or mutable-board lifetimes.

Drill and slot semantics come from existing kicad-monkey records. The records must use data-primitive="pad-hole" or data-primitive="via-hole", data-hole-owner, data-hole-kind, data-hole-plating, and dimensional fields such as data-hole-diameter-mm or data-hole-width-mm / data-hole-height-mm. The plating values are plated, non_plated, or unknown.

The review theme colors pads black, tracks/arcs/vias/zones light gray, Edge.Cuts black, plated drill records blue, plated slot records cyan, non-plated drill records red, non-plated slot records orange, and unknown-plating hole records neutral gray. Unknown plating is retained as unknown and should be treated as review-required data, not silently converted to plated or non-plated.

The command must not create a second drill/slot overlay group, add duplicate plating attributes such as boolean mirrors, or translate non_plated into a different spelling. Applications should read the canonical kicad-monkey attributes directly.

Manifest

design_review_manifest.json records the design JSON path, compiled graph artifact/schema/type/identity namespace/counts/linkage contract, netlist JSON path, KiCad S-expression netlist path, README path, schematic SVG list, and PCB SVG list. Each schematic artifact additionally records canonical page occurrence, artifact key, graph-link count, and resolved SVG-identity count. Each PCB artifact records the SVG path, copper layer, included layers, and the count of enriched drill/slot records present in that SVG.

Tests

L3 public workflow tests execute design, design-review, and dr against synthetic and reviewed KiCad projects, including HLR, taillight, Yoshi, Speedy, and the 4-channel backplane. L3_011 compares the Rust CLI with the Python oracle across CLI behavior, structured artifacts, hierarchy, fonts and worksheets, schematic review SVGs, PCB review SVGs, complete bundles, and transactional failure. L3_012 installs both Rust executable names, extracts led_component from the reviewed KM_CORPUS ZIP, removes Python from the runtime environment, generates a bundle, rejects workspace-path leakage, and verifies the hash/version/commit-bound release candidate and tamper failures.

Legacy Python-Module NativeDesignFactsProvider

Purpose: obtain source-bound compiled schematic graph and version-E netlist facts from the packaged Monkey native process on the selected Windows x64 path.

Rationale: provider selection remains a Cruncher orchestration decision while parsing, bounded transport, and result validation remain Monkey-owned. Native failure is terminal.

Test Requirements: prove one invocation, exact snapshot and metadata binding, graph/netlist publication, and absence of Python graph or version-E fallback.

Working Definition: the selected provider returns validated facts whose graph and exact netlist bytes are published transactionally with matching manifest provenance.