megamaid

Usage

kicad-cruncher megamaid project.kicad_pro -o output/megamaid
kicad-cruncher megamaid project.kicad_pro --dedupe fingerprint
kicad-cruncher megamaid project.kicad_pro --validate-kicad-cli

Arguments

file accepts a .kicad_pro project. If omitted, the command auto-detects exactly one .kicad_pro in the current directory. Schematic-only and PCB-only inputs are intentionally not accepted in this first public workflow because the extraction bundle needs the project root, local libraries, board file, and schematic files together.

-o selects the output directory. Without -o, artifacts are written under ./output/megamaid/. lib-extract is the separate cleaned library ingestion command.

The command reuses internal library extraction mode for symbols and footprints, then adds a broader embedded-asset pass that decodes board, footprint, schematic, symbol-library, and worksheet payloads. It also writes the same design-review bundle as design under design_review/.

--dedupe name collapses repeated assets by library name. --dedupe fingerprint collapses by stripped serialized content. --no-embed-models disables board-embedded model payload rehydration. --no-embed-external-models disables resolving external STEP/STP model paths into extracted footprints. --all-embedded-models scans the whole project and writes every embedded STEP/STP payload. --include-asset-scan includes the full model-reference scan in the metadata JSON. --validate-kicad-cli asks KiCad CLI to parse/upgrade the generated libraries, and --kicad-cli selects the executable.

Ownership

The KiCad parsing, metadata stripping, model path classification, external STEP/STP embedding, metadata bundle construction, and KiCad CLI validation helpers are owned by kicad-monkey. kicad-cruncher owns command-line ergonomics, output directory layout, manifest writing, README writing, logging, and exit status.

The command is non-destructive. It does not edit the source project, update sym-lib-table or fp-lib-table, relink schematic symbols, relink PCB footprints, or rewrite project text variables. Project-local table editing belongs to project-lib.

Output

The selected output directory contains a self-contained extraction bundle:

• symbols/*.kicad_sym: one single-symbol KiCad symbol library file per extracted symbol record.
• footprints.pretty/*.kicad_mod: one standalone KiCad footprint per extracted footprint record.
• models/*.{step,stp}: decoded embedded STEP/STP model payloads required by the extracted footprint records, or every embedded payload when --all-embedded-models is used.
• embedded_assets/embedded_files/*: decoded compressed KiCad (embedded_files ...) payloads from boards, placed footprints, schematics, footprint libraries, and symbol libraries.
• embedded_assets/schematic_images/*, embedded_assets/pcb_images/*, and embedded_assets/worksheet_bitmaps/*: decoded bitmap payloads from schematic, PCB, footprint, and worksheet image containers.
• design_review/<project-stem>_design.json: kicad_monkey.design.a0 design JSON.
• design_review/<project-stem>_compiled_schematic_graph.json: the exact occurrence-scoped schematic graph shared with the nested SVGs.
• design_review/<project-stem>_netlist.json: kicad_monkey.netlist.a0 netlist JSON.
• design_review/<project-stem>_netlist.net: kicad-cli-style S-expression netlist.
• design_review/design_review_manifest.json: nested kicad_cruncher.design_review_manifest.a0 artifact index.
• design_review/schematics/*.svg: one enriched schematic SVG per concrete hierarchy instance.
• design_review/pcb/copper_layers/*__review.svg: one enriched PCB review SVG per copper layer when a board is present.
• library_extraction.json: kicad_cruncher.library_extraction_bundle.a0 metadata with raw fields, canonical identity fields, source paths, source references, model-reference diagnostics, and optional project asset scan when --include-asset-scan is used.
• megamaid_manifest.json: kicad_cruncher.megamaid_manifest.a0 artifact index with counts, relative output paths, embedded asset records, nested design-review artifact records, mode, source project, and optional KiCad CLI validation results.
• README.md: short human-readable summary for agents and reviewers.

The library_extraction.json metadata follows docs/contracts/library_extraction_bundle.a0.schema.json. raw_fields is the raw KiCad parameter/property map with source key spelling preserved; canonical_fields is derived from those fields using case-insensitive alias matching for part fields such as mpn, mfg, value, description, and cad-reference.

The top-level manifest records the design_review directory, nested manifest, README, design JSON, compiled graph path/schema/linkage contract, netlist JSON, S-expression netlist, component count, net count, schematic SVG count, PCB SVG count, and relative SVG paths. The graph exists only in the nested shared design-review bundle; Megamaid does not synthesize or copy a second graph.

This command is intended for full project dissection and archival review. Clean reusable CAD ingestion is handled by lib-extract; metadata-preserving project-local extraction is handled by project-lib; broader asset diagnostics are handled by health.

Tests

L0 public CLI tests verify the command appears in root help, command help starts, and the manifest/design-doc inventory stays synchronized. L3 public workflow tests run megamaid against the sanitized 4-ch backplane corpus fixture and verify the manifest schema, output directories, metadata schema, symbol/footprint/model counts, internal stripping mode, embedded asset records, design JSON, netlist artifacts, schematic SVGs, and PCB review SVGs. The optional KiCad CLI validation path is covered by kicad-monkey L2 tests and can be exercised through --validate-kicad-cli when a local KiCad install is available.