design

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 lookup indexes from the design JSON. design-review and dr are aliases for the same command and output contract.

Ownership

The semantic model and SVG enrichment contract are owned by kicad-monkey. kicad-cruncher must not re-parse KiCad pads, vias, nets, or hierarchy to invent parallel metadata. It calls the public kicad-monkey APIs, writes the returned artifacts into a review bundle, and applies a review visual theme to the enriched SVG records.

Design JSON is produced from KiCadDesign.to_json(). Schematic SVGs are produced from design.schematic_instances(), design.to_schematic_instance_ir(...), render_ir_to_svg(...), and the kicad-monkey schematic SVG enrichment helpers with enriched black-and-white role-theme render options. PCB review SVGs are produced from design.pcb.to_svg(..., profile="enriched") with the selected copper layer plus Edge.Cuts.

Output

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

• <input-stem>_design.json: kicad_monkey.design.a0 JSON.
• design_review_manifest.json: kicad_cruncher.design_review_manifest.a0 artifact index.
• 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.

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. 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.

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, README path, schematic SVG list, and PCB SVG list. Each schematic artifact records sheet number, sheet count, sheet name, sheet path, sheet UUID path, sheet instance path, and source schematic path. 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 a synthetic project and copied public KiCad corpus projects, including taillight, yoshi, and speedy cases. The tests verify the design JSON schema, text variables, component and net counts, alias behavior, manifest schema, README content, schematic SVG artifacts, PCB review SVG colors, and the exact PTH/NPTH hole metadata emitted by kicad-monkey.