Report whether KiCad is running and its IPC API reachable, the KiCad and API versions, the instance, the project directory, the open documents with their dirty state, and which tools this instance supports. Always answers: 'not running' and 'API disabled' come back as data.

Summarize the board open in KiCad's PCB editor, live (including unsaved changes): path, title block, copper and total layer counts, counts of footprints, nets, tracks, vias and zones, outline size, and dirty state. Fails fast with a structured error when KiCad is unreachable or no board is open.

Read what is selected in KiCad's PCB editor, live, as stable file-level references that kct commands accept: footprints (reference designators), pads ('REF.PAD'), nets (of the selected copper, pads and zones), nets_of_footprints (nets reached through selected footprints' pads), other (tracks, vias, zones and graphics, with a session-scoped id and no_file_reference: true), undescribed (selected items this client cannot decode, counted, never dropped), and bbox (mm, file frame) with the board-frame offset. Optional kinds filter (e.g. ['footprint', 'pad']); include_geometry adds per-item positions and boxes. An empty selection is an ordinary empty result.

Point the user at kicad-tools findings in KiCad's PCB editor: resolve each finding's locators (reference designators, 'REF.PAD', net names, a point) against the live board and select the affected items (replacing the selection). findings is the JSON a kct command printed with --format json (kct check, kct drc, kct detect-mistakes, kct net-status), or a list of its findings. mode: select | highlight | both; focus: 'all', a finding index, 'next' or 'previous'; zoom: true/false. On KiCad 10 there is no documented zoom or net-highlight API, so highlight and zoom report unsupported_on_this_kicad while the selection still happens. Per finding the result lists the resolved items, the locators that did not resolve with a reason, and the action taken, plus totals. Findings whose pcb_sha256 no longer matches the board are still resolved and flagged possibly_stale. A finding's location is optional: one with a null or missing location is resolved from its names and reported with has_point false.

Before a file-based tool (kct) touches a board open in KiCad, make the file on disk match the editor. A board proven clean is left alone. A dirty board, or one whose dirty state is unknown (always possible on KiCad 10), is refused unless allow_save=true; then it is saved and the file is checked to have changed. Returns each document's state before, the action (none/saved/refused) and the file SHA-256 plus editor_sha256 to pass to sync_from_disk. The schematic cannot be saved over KiCad 10's API: it is refused unless schematic_unverified_ok=true.

After a file-based tool (kct) wrote a board that is open in KiCad, reload the editor from the file. Refuses, changing nothing, if the editor may hold unsaved work: dirty or unknown (KiCad 10 has no dirty query) unless discard_unsaved=true. The board counts as clean only when openkonnect reads the editor's content now and it equals the file now (byte-identical, or on KiCad 10.0.7 equal token for token apart from KiCad's known save formatting); no hash you pass can prove it clean. editor_hash (editor_sha256 from save_before_external_write) lets openkonnect detect an edit made in KiCad since (document_dirty); unchanged, it stays unknown. expected_hash (the file hash after your tool wrote it) refuses an unexpected write with stale_input. The reload is not an undo step. The schematic cannot be reloaded over KiCad 10's API: it is reported as manual_reload_required.

Run one allow-listed kicad-tools write command (kct) on the board open in KiCad, following the handoff protocol: check the session, save the editor (allow_save=true is needed when dirty state is unknown, as on KiCad 10), run the command with a timeout, then reload the editor from the file only if the command succeeded and changed it. An edit made in KiCad while the command ran makes the reload refuse with document_dirty, and nothing is lost; discard_unsaved=true reloads anyway and discards that edit. command is an argv list without 'kct', and must contain the token {board}, which is replaced by the board's path, e.g. ["route", "{board}", "-o", "{board}"]. Board only on KiCad 10.