Add autowire documentation and update project structure

Autowire guide covers the decision tree, threshold tuning, workflow
patterns, and troubleshooting. CLAUDE.md updated to reflect the new
autowire/ package and tools/autowire.py.

CLAUDE.md

@@ -26,7 +26,12 @@ src/mckicad/
   __init__.py           # __version__ only
   server.py             # FastMCP 3 server + lifespan + module imports
   config.py             # Lazy config functions (no module-level env reads)
+  autowire/
+    __init__.py         # Package init
+    strategy.py         # Wiring decision tree: classify_net, crossing estimation
+    planner.py          # NetPlan → apply_batch JSON conversion
   tools/
+    autowire.py         # autowire_schematic MCP tool (1 tool)
     schematic.py        # kicad-sch-api: create/edit schematics (9 tools)
     project.py          # Project discovery and structure (3 tools)
     drc.py              # DRC checking + manufacturing constraints (4 tools)

docs/autowire_guide.md

@@ -0,0 +1,218 @@
+# Autowire Guide
+
+This guide explains the `autowire_schematic` tool, which analyzes unconnected nets in a KiCad schematic and automatically selects the best wiring strategy for each one.
+
+## Overview
+
+The autowire tool provides a single-call alternative to manually deciding wire vs label vs power symbol for every net. It:
+
+1. Analyzes the schematic's netlist to find unconnected nets
+2. Classifies each net into an optimal wiring strategy based on distance, fanout, crossings, and net name patterns
+3. Generates a batch plan compatible with `apply_batch`
+4. Optionally applies the wiring in one atomic operation
+
+Existing manual tools (`add_wire`, `connect_pins`, `add_label`, `apply_batch`) remain available for fine-grained control. Autowire is the "do the obvious thing" option.
+
+## Quick Reference
+
+| Task | Example Prompt |
+|------|---------------|
+| Preview wiring plan | `Autowire my schematic at /path/to/project.kicad_sch` |
+| Apply wiring | `Autowire my schematic at /path/to/project.kicad_sch with dry_run=False` |
+| Wire specific nets only | `Autowire only the SPI nets in my schematic` |
+| Exclude power nets | `Autowire my schematic, excluding GND and VCC` |
+| Adjust distance threshold | `Autowire with direct_wire_max_distance=30` |
+
+## How the Decision Tree Works
+
+For each unconnected net, the tool walks through these checks in order:
+
+| Priority | Condition | Strategy | Rationale |
+|----------|-----------|----------|-----------|
+| 1 | Power net (name matches GND/VCC/+3V3/etc, or pin type is `power_in`/`power_out`) | Power symbol | Standard KiCad convention for power rails |
+| 2 | Single-pin net | No-connect flag | Avoids ERC warnings on intentionally unused pins |
+| 3 | Cross-sheet net | Global label | Global labels are required for inter-sheet connectivity |
+| 4 | High fanout (>5 pins by default) | Global label | Labels scale better than wire stars for many connections |
+| 5 | Two-pin net, distance <= 10mm | Direct wire | Short enough that a wire is cleaner than a label |
+| 6 | Two-pin net, distance > 50mm | Local label | Too far for a clean wire run |
+| 7 | Two-pin net, mid-range with >2 crossings | Local label | Avoids visual clutter from crossing wires |
+| 8 | Two-pin net, mid-range with few crossings | Direct wire | Wire is the simplest connection |
+| 9 | 3-4 pin net | Local label | Star topology with labels is cleaner than a wire tree |
+
+All thresholds are tunable via tool parameters.
+
+## Using Autowire
+
+### Dry Run (Preview)
+
+Autowire defaults to `dry_run=True` — it shows you the plan without touching the schematic:
+
+```
+Autowire my schematic at ~/Projects/KiCad/amplifier/amplifier.kicad_sch
+```
+
+The response includes:
+- **Strategy summary** — counts by method (e.g., 12 direct wires, 8 local labels, 4 power symbols, 2 no-connects)
+- **Per-net plan** — each net's chosen method and the reasoning
+- **Batch file** — the generated JSON written to `.mckicad/autowire_batch.json`
+
+### Applying the Plan
+
+Once you've reviewed the dry run, apply with:
+
+```
+Autowire my schematic at ~/Projects/KiCad/amplifier/amplifier.kicad_sch with dry_run=False
+```
+
+This calls `apply_batch` internally, which means you get collision detection, label placement optimization, and power symbol stub generation for free.
+
+### Filtering Nets
+
+To wire only specific nets:
+
+```
+Autowire only the MOSI, MISO, and SCK nets in my schematic
+```
+
+To exclude nets you've already wired manually:
+
+```
+Autowire my schematic, excluding USB_D_P and USB_D_N
+```
+
+To exclude entire components (e.g., a connector you want to wire by hand):
+
+```
+Autowire my schematic, excluding refs J1 and J2
+```
+
+### Tuning Thresholds
+
+The default thresholds work well for typical schematics, but you can adjust them:
+
+| Parameter | Default | Effect |
+|-----------|---------|--------|
+| `direct_wire_max_distance` | 50.0mm | Pins farther apart than this get labels instead of wires |
+| `crossing_threshold` | 2 | More crossings than this triggers label fallback |
+| `high_fanout_threshold` | 5 | Nets with more pins than this get global labels |
+
+For dense boards with tight pin spacing:
+
+```
+Autowire my schematic with direct_wire_max_distance=25 and crossing_threshold=1
+```
+
+For sparse layouts where longer wires are acceptable:
+
+```
+Autowire my schematic with direct_wire_max_distance=80
+```
+
+## Understanding Results
+
+### Strategy Summary
+
+```json
+{
+  "strategy_summary": {
+    "direct_wire": 12,
+    "local_label": 8,
+    "global_label": 3,
+    "power_symbol": 6,
+    "no_connect": 2
+  },
+  "total_nets_classified": 31,
+  "nets_skipped": 45
+}
+```
+
+- **nets_skipped** includes already-connected nets plus any you excluded — these aren't counted in the classification total.
+
+### Per-Net Plan
+
+Each net entry explains the decision:
+
+```json
+{
+  "net": "SPI_CLK",
+  "method": "local_label",
+  "pin_count": 2,
+  "reason": "long distance (67.3mm > 50.0mm)"
+}
+```
+
+The `reason` field traces which branch of the decision tree was taken, useful for understanding why a particular strategy was chosen.
+
+### Batch File
+
+The generated `.mckicad/autowire_batch.json` uses the same schema as `apply_batch`. You can inspect it, edit it, and apply it manually if you want to tweak individual connections before committing:
+
+```
+Show me the contents of .mckicad/autowire_batch.json
+```
+
+## Crossing Estimation
+
+The crossing estimator checks whether a proposed direct wire between two pins would cross existing wires. It uses axis-aligned segment intersection: a horizontal wire crosses a vertical wire when their X/Y ranges overlap (strict inequality — touching endpoints don't count).
+
+This keeps the schematic visually clean by falling back to labels when wires would create a tangled crossing pattern.
+
+## Power Net Detection
+
+Power nets are identified by two methods:
+
+1. **Name matching** — GND, VCC, VDD, VSS, +3V3, +5V, +12V, +1.8V, VBUS, VBAT, and variants (AGND, DGND, PGND, etc.)
+2. **Pin type metadata** — if any pin on the net has `pintype` of `power_in` or `power_out` in the netlist, the net is treated as power regardless of its name
+
+This handles custom power rails that don't follow standard naming conventions.
+
+## Tips
+
+### Best Practices
+
+1. **Always dry-run first** — review the plan before applying. The default `dry_run=True` exists for a reason.
+2. **Wire critical nets manually** — for sensitive analog paths, differential pairs, or impedance-controlled traces, use `add_wire` or `connect_pins` directly, then let autowire handle the rest.
+3. **Use exclude_nets for partially-wired designs** — if you've already connected some nets, exclude them to avoid duplicate labels.
+4. **Run ERC after autowiring** — `validate_schematic` confirms the wiring is electrically correct.
+
+### Workflow
+
+A typical autowire workflow:
+
+1. Place all components and set values/footprints
+2. Wire critical signal paths manually (`connect_pins`, `add_wire`)
+3. Run `autowire_schematic` in dry-run to preview
+4. Review the plan — adjust thresholds or exclude specific nets if needed
+5. Apply with `dry_run=False`
+6. Run `validate_schematic` to verify
+7. Open in KiCad to visually inspect
+
+## Troubleshooting
+
+### No Nets Classified
+
+If autowire reports 0 nets classified:
+
+1. **Check that kicad-cli is available** — autowire needs it to export the netlist. Set `KICAD_CLI_PATH` if needed.
+2. **Verify the schematic has components** — an empty schematic has no nets to wire.
+3. **Check if nets are already connected** — autowire skips nets that appear in the connectivity graph. Run `analyze_connectivity` to see what's already wired.
+
+### Wrong Strategy for a Net
+
+If a net gets classified incorrectly:
+
+1. **Check pin types in the netlist** — a pin with `power_in` type will force POWER_SYMBOL even if the net name is unusual. Export and inspect the netlist with `import_netlist`.
+2. **Adjust thresholds** — if too many nets get labels when you want wires, increase `direct_wire_max_distance`.
+3. **Use only_nets/exclude_nets** — wire the problematic net manually and exclude it from autowire.
+
+### Netlist Export Fails
+
+If the auto-export step fails:
+
+1. **Provide a pre-exported netlist** — use `export_netlist` to create one, then pass it as `netlist_path`.
+2. **Check kicad-cli version** — KiCad 9+ is required for the `kicadsexpr` format.
+3. **Check schematic validity** — run `validate_schematic` to catch structural issues.
+
+## Attribution
+
+The wiring strategy decision tree is informed by [KICAD-autowire](https://github.com/arashmparsa/KICAD-autowire) (MIT, arashmparsa), which demonstrated the concept of automated wiring strategy selection. The mckicad implementation is original, built on the existing batch pipeline.