cargo build --release                                   # host OS
cargo build --release --target x86_64-pc-windows-gnu    # Windows, from Linux (mingw-w64 installed)
cargo check --target aarch64-apple-darwin --no-default-features   # type-check the macOS file from a box without a darwin C toolchain (net feature off)

kicad-bridge --port 47731
curl http://127.0.0.1:47731/status
curl -X POST http://127.0.0.1:47731/command -d '{"command":"kicad_describe"}'

# kicad-bridge (native)

The Rust port of the Adom KiCad Bridge. One binary per OS, no runtime to provision. Plan and phases: [docs/rust-port-plan.md](../docs/rust-port-plan.md).

## Layout

| Crate | What | OS-specific? |
|---|---|---|
| `crates/kicad-platform` | The `Platform` trait and exactly one implementation compiled in per target: `windows.rs`, `macos.rs` (Kyle), `linux.rs` (Barrett). Install discovery, settings and documents dirs, quiet child processes; later window control, UI automation, dialog sweep and focus etiquette. | Yes, this is the only crate that is |
| `crates/kicad-core` | Detection ordering, the kicad-cli runner and report parsers, KiCad file editing (phase 1b), IPC client (phase 2). Talks to the OS only through `kicad_platform::native()`. | No |
| `crates/kicad-bridge` | The binary: HTTP server (`/status`, `/command`), the verb catalog and the verb groups (one file per group, registered in `groups.rs`). | No |

A verb that needs something the current OS does not implement yet returns `kicad_platform::unsupported("...")`: `errorCode: not_supported_on_platform`, the OS, and the owner's name in the hint. Readiness and diagnostics carry a `platform.capabilities` block so an AI can tell what this build can do before calling anything.

## Build

```
cargo build --release                                   # host OS
cargo build --release --target x86_64-pc-windows-gnu    # Windows, from Linux (mingw-w64 installed)
cargo check --target aarch64-apple-darwin --no-default-features   # type-check the macOS file from a box without a darwin C toolchain (net feature off)
```

Per-OS dependencies go in `crates/kicad-platform/Cargo.toml` under the matching `[target.'cfg(...)'.dependencies]` table. Nothing OS-specific belongs in the other two crates.

## Run by hand

```
kicad-bridge --port 47731
curl http://127.0.0.1:47731/status
curl -X POST http://127.0.0.1:47731/command -d '{"command":"kicad_describe"}'
```

ab spawns it with `spawn.kind: "exe"` and appends `--port`; bind host comes from `ADOM_BIND_HOST`.

## Name verbs from the EDA Bridge Standard

The KiCad, Altium and Fusion bridges share one set of verb names and one board model, the
[EDA Bridge Standard](https://wiki.adom.inc/adom/eda-bridge-standard), so one AI and the shared checks work on all
three. Before you name a new verb, look its job up in `rust/crates/kicad-bridge/src/standard_names.txt` (the
standard's verbs; `verbs/standard.json` on the standard's page has each one's summary, inputs and reply):

- **The standard has the job**: name the verb after it (`kicad_net_classes`, not `kicad_netclasses`), or keep your
  name and add `(standard name, your verb)` to `catalog::ALIASES`, so both names are served.
- **It covers part of the job**: keep your name, list the verb in `kicad_only.txt`, and record it as partial in the
  standard's `tools/equivalents/kicad.json`.
- **The standard has no such job**: list the verb in `rust/crates/kicad-bridge/src/kicad_only.txt`. If other EDA
  tools could do the job, propose it to the standard (an issue titled `kicad-lane: propose ...` on its page; once
  the standard-lane thread agrees, the entry goes in `tools/proposed/kicad-lane.json`). When it lands, take the
  verb out of `kicad_only.txt` and give it the standard's arguments in `std_shapes.rs`.

`catalog.rs`'s test `every_verb_has_a_standard_decision` fails until every verb is one of the three, and
`bridge_json_declares_exactly_the_catalog` fails until `bridge.json` lists it. Each new verb also needs an entry in
the verb battery (`skills/kicad-bridge-test/run_verb_tests.py`): the battery fails a catalog verb it does not test.
`tools/build_native_release.py --publish` then syncs `bridge.json` and pushes `reference/kicad-<ver>.json` to the standard; the standard-lane thread regenerates the coverage (ping it, pinned issue #3 there).

## Adding a verb

0. Pick its name from the EDA Bridge Standard (above) and record the decision.
1. Add a `Verb` entry to `catalog.rs` (summary, mechanism, risk, timeout, input, example, hint, related, pitfalls). ab's Verbs tab renders it verbatim.
2. Add the match arm in `verbs.rs::dispatch`.
3. Add it to `bridge.json` and give it an entry in the verb battery (`skills/kicad-bridge-test/run_verb_tests.py`).
4. Keep the Python contract: same arg names, same `success`/`output`/`data` shape, so the verb runner in `skills/kicad-bridge-test` passes unchanged.