Update routing docs for freeroute; demote FreeRouting JAR to fallback

docs-site/src/content/docs/development/architecture.md

@@ -29,7 +29,7 @@ src/mckicad/
     drc.py              # DRC checking + manufacturing constraints
     bom.py              # BOM generation and export
     export.py           # Gerber, drill, PDF, SVG via kicad-cli
-    routing.py          # FreeRouting autorouter integration
+    routing.py          # Autorouter integration (freeroute CLI, JAR fallback)
     analysis.py         # Board validation + real-time analysis
     pcb.py              # IPC-based PCB manipulation via kipy
   resources/
@@ -42,7 +42,7 @@ src/mckicad/
     path_validator.py   # Path security / directory traversal prevention
     secure_subprocess.py # Safe subprocess execution with timeouts
     ipc_client.py       # kipy IPC wrapper for live KiCad connection
-    freerouting.py      # FreeRouting JAR engine
+    freerouting.py      # Autorouter engine: prefers freeroute CLI, falls back to FreeRouting JAR; native headless SES applier
     file_utils.py       # Project file discovery
     kicad_utils.py      # KiCad path detection, project search
     sexp_parser.py      # S-expression parsing for pin position resolution

docs-site/src/content/docs/getting-started.md

@@ -26,7 +26,7 @@ Tools degrade gracefully: if KiCad is not running, IPC-dependent tools report th
 
 **Export and manufacturing** -- Generate Gerber files, drill files, PDFs, and SVGs for your boards. Everything goes through kicad-cli with proper layer selection and output directory organization.
 
-**Autorouting** -- Route PCBs automatically via FreeRouting integration with configurable strategies (conservative, balanced, aggressive) and technology profiles.
+**Autorouting** -- Route PCBs automatically through a fully headless, Java-free pipeline built on [freeroute](https://git.supported.systems/warehack.ing/freeroute) (a native-Python port of the FreeRouting engine), with the FreeRouting JAR available as a fallback for maximum net completion on dense boards.
 
 **Board analysis** -- Live board statistics, connectivity monitoring, component detail inspection, and routing quality analysis through the IPC API.
 

docs-site/src/content/docs/getting-started/configuration.md

@@ -28,7 +28,21 @@ These settings control where the server looks for KiCad projects:
 |---------------------|-------------|---------|---------|
 | `KICAD_APP_PATH` | Path to the KiCad installation | Auto-detected per platform | `/Applications/KiCad/KiCad.app` |
 | `KICAD_CLI_PATH` | Explicit path to kicad-cli | Auto-detected | `/usr/bin/kicad-cli` |
-| `FREEROUTING_JAR_PATH` | Path to FreeRouting JAR | Auto-detected in common locations | `~/freerouting.jar` |
+| `FREEROUTE_CLI` | Path to the freeroute CLI (preferred autorouter) | Auto-discovered on PATH | `~/.local/bin/freeroute` |
+| `FREEROUTING_JAR_PATH` | Path to the FreeRouting JAR (optional fallback) | Auto-detected in common locations | `~/freerouting.jar` |
+
+### Routing options
+
+Autorouting is configured per call through the `routing_config` argument of `route_pcb_automatically`, not through environment variables. The freeroute-specific keys are:
+
+| Key | Description | Default |
+|-----|-------------|---------|
+| `freeroute_engine` | Router engine: `room`, `exact`, or `grid` | `room` |
+| `freeroute_pack` | Enable channel packing for tighter routing | `true` |
+| `freeroute_shove` | Allow shoving existing traces to make room | Engine-dependent |
+| `freeroute_diagonal` | Allow 45-degree / diagonal trace shortening | Engine-dependent |
+
+See the [Autorouting guide](/guides/routing/) for what each engine does and when to reach for it.
 
 ### Server settings
 

docs-site/src/content/docs/getting-started/installation.md

@@ -101,15 +101,29 @@ List all my KiCad projects
 
 If the server is running and configured correctly, it will scan your search paths and return a list of `.kicad_pro` files.
 
-## Optional: FreeRouting (autorouting)
+## Optional: autorouting
 
-For automated PCB routing, install FreeRouting:
+For automated PCB routing, install [freeroute](https://git.supported.systems/warehack.ing/freeroute), a native-Python, Java-free autorouter:
+
+```bash
+uv tool install freeroute
+# or: pip install freeroute
+```
+
+That is the whole setup. freeroute is pure standard library with no dependencies and no Java runtime. mckicad auto-discovers the `freeroute` command on your PATH; if it lives somewhere unusual, set `FREEROUTE_CLI` in your `.env` to the executable path. Verify with the `check_routing_capability` tool.
+
+See the [Autorouting guide](/guides/routing/) for the full pipeline, engine choices, and honest scope.
+
+### Fallback: FreeRouting JAR
+
+freeroute completes fewer nets than the original FreeRouting engine on dense commercial boards (it drops a net rather than emit a DRC violation). If you need maximum completion on a hard board and have Java available, keep the FreeRouting JAR as a fallback:
 
 1. Download the JAR from [freerouting.app](https://freerouting.app/)
 2. Place it at one of the auto-detected paths: `~/freerouting.jar`, `/usr/local/bin/freerouting.jar`, or `/opt/freerouting/freerouting.jar`
 3. Install a Java runtime (`java` must be on your PATH)
-4. Verify with the `check_routing_capability` tool
-5. Or set `FREEROUTING_JAR_PATH` in your `.env` file to an explicit path
+4. Or set `FREEROUTING_JAR_PATH` in your `.env` file to an explicit path
+
+mckicad prefers freeroute when it is installed and falls back to the JAR only when freeroute is missing or cannot route the board.
 
 ## Development commands
 

docs-site/src/content/docs/reference/environment.md

@@ -58,9 +58,23 @@ KICAD_APP_PATH=/Applications/KiCad/KiCad.app
 - Windows: `C:\Program Files\KiCad`
 - Linux: `/usr/share/kicad`
 
+### FREEROUTE_CLI
+
+Path to the [freeroute](https://git.supported.systems/warehack.ing/freeroute) CLI, the preferred autorouter. freeroute is a native-Python, Java-free port of the FreeRouting engine.
+
+```
+FREEROUTE_CLI=~/.local/bin/freeroute
+```
+
+**Default:** Auto-discovered on your system PATH. Set this only if the `freeroute` executable is installed in a location that is not on PATH. Install it with `uv tool install freeroute` or `pip install freeroute`.
+
+Used by: `route_pcb_automatically`, `check_routing_capability`.
+
+Per-call engine and packing behaviour is controlled through the `routing_config` argument (`freeroute_engine`, `freeroute_pack`, `freeroute_shove`, `freeroute_diagonal`), not through environment variables. See the [Autorouting guide](/guides/routing/).
+
 ### FREEROUTING_JAR_PATH
 
-Path to the FreeRouting JAR file for automated PCB routing.
+Path to the FreeRouting JAR file. This is the optional fallback autorouter, used only when freeroute is not installed or cannot route a given board. mckicad prefers freeroute (see `FREEROUTE_CLI`).
 
 ```
 FREEROUTING_JAR_PATH=~/freerouting.jar
@@ -71,7 +85,7 @@ FREEROUTING_JAR_PATH=~/freerouting.jar
 - `/usr/local/bin/freerouting.jar`
 - `/opt/freerouting/freerouting.jar`
 
-Requires a Java runtime (`java` must be on PATH).
+Requires a Java runtime (`java` must be on PATH). Only needed for maximum net completion on dense boards; the primary freeroute path needs no Java.
 
 ### LOG_LEVEL
 
@@ -104,7 +118,11 @@ KICAD_USER_DIR=~/Documents/KiCad
 # KiCad application path
 # KICAD_APP_PATH=/usr/share/kicad
 
-# FreeRouting JAR for autorouting
+# Autorouter: freeroute is preferred and auto-discovered on PATH.
+# Set FREEROUTE_CLI only if it is installed off-PATH.
+# FREEROUTE_CLI=~/.local/bin/freeroute
+
+# Optional FreeRouting JAR fallback (needs Java; only for dense boards)
 # FREEROUTING_JAR_PATH=~/freerouting.jar
 
 # Logging level

docs-site/src/content/docs/reference/tools.md

@@ -155,12 +155,12 @@ See [Autowiring guide](/guides/autowire/) for details on the decision tree.
 
 ## Routing tools
 
-`tools/routing.py` -- FreeRouting autorouter integration.
+`tools/routing.py` -- autorouter integration. Prefers the Java-free [freeroute](https://git.supported.systems/warehack.ing/freeroute) CLI and falls back to the FreeRouting JAR. See the [Autorouting guide](/guides/routing/).
 
 | Tool | Description |
 |------|-------------|
-| `check_routing_capability` | Check whether automated PCB routing is available |
-| `route_pcb_automatically` | Automatically route a PCB using FreeRouting |
+| `check_routing_capability` | Check whether automated PCB routing is available (freeroute or JAR) |
+| `route_pcb_automatically` | Automatically route a PCB, headless, via freeroute (JAR fallback) |
 | `analyze_routing_quality` | Analyze current PCB routing for quality and potential issues |
 
 ## PCB tools (IPC)