# KiCad to Markdown Parser

Converts KiCad 6+ projects into structured, AI-readable markdown documents. Upload a `.zip` or point it at a project directory — get back a comprehensive breakdown of your schematic and PCB.

## What It Extracts

| Source File | Data Extracted |
|-------------|---------------|
| `.kicad_pro` | Project name, net class definitions, design settings |
| `.kicad_sch` | Components, net labels, power symbols, wires, hierarchical sheets, **full netlist connectivity** |
| `.kicad_pcb` | Footprints, traces, vias, zones, board outline, layer stackup, design rules |

## Key Features

- **Netlist extraction from schematics** — traces wires using union-find, resolves net names from labels and power symbols
- **Hierarchical sheet support** — follows sub-sheets and extracts interface pins
- **PCB layout parsing** — board dimensions, layer stackup, component placement, routing summary
- **Coordinate system handling** — correctly transforms KiCad library Y-up to schematic Y-down with rotation/mirror support
- **Labels on wire segments** — handles labels placed mid-wire, not just at endpoints
- **Zip file support** — handles flat zips and single-subdirectory zips

## Usage

### CLI (preferred)

```bash
cd /home/adom/project/kicad-to-markdown
python3 cli.py /path/to/project/ -o output.md
python3 cli.py /path/to/project.zip -o output.md
```

### HTTP API

```bash
# Start server
cd /home/adom/project/kicad-to-markdown
uvicorn server:app --host 0.0.0.0 --port 8000 &

# Upload zip → get markdown
curl -F "file=@project.zip" http://localhost:8000/parse

# Upload zip → get JSON with stats
curl -F "file=@project.zip" http://localhost:8000/parse/json
```

## Output Structure

```
# KiCad Project: {name}
## Overview — component count, net count, board dimensions
## Components — table of all parts with ref, value, footprint, description
## Connectivity (Netlist) — named nets then unnamed nets, each listing connected pins
## Hierarchical Sheets — sub-sheet structure and interface pins
## Power Nets — which components connect to each power rail
## PCB Physical Layout
  ### Board Outline, Layer Stackup, Component Placement
  ### Routing Summary, Most Routed Nets, Copper Zones
## Design Rules — net classes with clearance/trace width settings
```

## Example Output

Tested on real projects:
- **Crosspoint Matrix 2CH 4x8** — 28 components, 78 PCB footprints, 169 nets, 7 hierarchical sheets, 4-layer 202×106mm board
- **STLink V3 Mods** — 72 components, 2 sheets, 79 nets

## Dependencies

Python 3.10+, `kiutils`, `fastapi`, `uvicorn`, `python-multipart`, `click`.

## Trigger Phrases

- "Parse a KiCad project"
- "Convert KiCad to markdown"
- "Understand a KiCad schematic"
- "Extract netlist"
- "Analyze a .kicad_sch"
- "What's in this KiCad project"