---
name: kicad-tour
description: "Run a guided KiCad tour on the user's laptop via adom-desktop — install a custom symbol library, walk the user through Symbol Editor → Footprint Editor → Schematic Editor → PCB Editor → 3D Viewer, then export gerbers. Two prebuilt packs ship under plugins/kicad/tour-pack/ (single resistor, fast) and plugins/kicad/tour-pack-rp2040/ (RP2040 breakout board, comprehensive). Trigger words — kicad tour, walk me through kicad, kicad demo, show me kicad, rp2040 breakout, resistor demo, kicad showcase, end-to-end kicad, send symbol and footprint, kicad export gerbers, gerbers for jlcpcb, gerbers for instapcb, kicad 3d board, kicad design walkthrough."
---

# kicad-tour

A guided 8-step walkthrough of the KiCad bridge end-to-end. Runs from any cloud
Docker session (or HD) — every command dispatches through `adom-desktop kicad_*`
to the bridge on the user's laptop. Each step produces a visible change in
KiCad that a viewer can see (and that the tour-runner script can screenshot).

**Read `kicad-interaction` first.** It covers the state-check + dialog rules
this tour follows.

## When to use

- User asks "show me what KiCad can do" / "walk me through kicad"
- Demo / onboarding flow when first connecting AD to KiCad
- Sanity check after a fresh AD install — proves every bridge verb works

## The 8-step tour (sequential, ~90s end-to-end)

Each step's CLI invocation is shown verbatim. The tour-runner Python script
(`plugins/kicad/skills/kicad-tour/tour_runner.py`) executes these exact calls
+ collects screenshots into a single output dir.

### Pre-step — pick a pack

```bash
# Fast demo (single 0805 resistor — proves the verbs work)
PACK=tour-pack
# Comprehensive demo (RP2040 breakout board — proves a real chip works)
PACK=tour-pack-rp2040
```

The packs are mounted by the bridge at:

- `C:/Github/adom-desktop/plugins/kicad/<PACK>/`
- (When AD is installer-deployed, look under
  `%LOCALAPPDATA%/Adom Desktop/bridges-cache/kicad/<PACK>/` — adjust paths.)

### Step 1 — install the custom symbol + footprint libraries

The tour-pack ships a `<Lib>.kicad_sym` and a `<Lib>.pretty/` directory. The
`kicad_install_library` verb copies them to the user's KiCad library tree
(`%USERPROFILE%/Documents/KiCad/10.0/{symbols,footprints}/`) and registers
them in `sym-lib-table` and `fp-lib-table`.

```bash
LIB=AdomTour   # or AdomRP2040 for the RP2040 pack

adom-desktop kicad_install_library "{
  \"libraryPath\":\"C:/Github/adom-desktop/plugins/kicad/${PACK}/${LIB}.kicad_sym\",
  \"libraryType\":\"symbol\",
  \"libraryName\":\"${LIB}\"
}"

adom-desktop kicad_install_library "{
  \"libraryPath\":\"C:/Github/adom-desktop/plugins/kicad/${PACK}/${LIB}.pretty\",
  \"libraryType\":\"footprint\",
  \"libraryName\":\"${LIB}\"
}"
```

### Step 2 — open Symbol Editor on the custom symbol

```bash
SYMBOL=R_AdomTour       # tour-pack
# SYMBOL=RP2040_AdomTour   # tour-pack-rp2040

adom-desktop kicad_open_symbol_editor "{
  \"libraryName\":\"${LIB}\",
  \"symbolName\":\"${SYMBOL}\"
}"
```

Wait ~5s for KiCad's startup. Screenshot via
`kicad_screenshot_all` — should show the new library highlighted in the
left-side library tree.

### Step 3 — open Footprint Editor on the custom footprint

```bash
FOOTPRINT=R_0805_AdomTour       # tour-pack
# FOOTPRINT=QFN-56_AdomRP2040    # tour-pack-rp2040

adom-desktop kicad_open_footprint_editor "{
  \"libraryName\":\"${LIB}\",
  \"footprintName\":\"${FOOTPRINT}\"
}"
```

### Step 4 — show 3D viewer for the footprint

```bash
# editor='fp' explicitly targets the Footprint Editor's 3D viewer
# (KiCad 9 worked via WM_COMMAND 20500; KiCad 10 may need adjustment —
# the fallback to PCB editor below covers the common case.)
adom-desktop kicad_open_3d_viewer '{"editor":"fp"}'
```

If this returns "3D Viewer did not open from Footprint Editor" on KiCad 10,
either skip to step 7 (the board's 3D viewer is the more reliable showcase
anyway) OR send `Alt+3` via AD's chord-aware keypress verb (focus the Footprint
Editor first):

```bash
# desktop_press_key owns modifier chords; kicad_send_key is only for single keys to an exact hwnd
adom-desktop desktop_press_key '{"keys":"alt+3"}'
```

### Step 5 — open the prebuilt schematic

The tour-pack ships `template/tour-demo.kicad_sch` (single R) or
`template/rp2040-breakout.kicad_sch` (RP2040 breakout). Each is wired to use
the custom library installed in step 1.

```bash
SCH=C:/Github/adom-desktop/plugins/kicad/${PACK}/template/tour-demo.kicad_sch
# SCH=C:/Github/adom-desktop/plugins/kicad/tour-pack-rp2040/template/rp2040-breakout.kicad_sch

adom-desktop kicad_open_schematic "{\"filePath\":\"${SCH}\"}"
```

### Step 6 — open the prebuilt board

Same idea — premade `.kicad_pcb` with the footprint placed and a
`(model "${KICAD10_3DMODEL_DIR}/...")` reference per footprint.

```bash
PCB=C:/Github/adom-desktop/plugins/kicad/${PACK}/template/tour-demo.kicad_pcb
adom-desktop kicad_open_board "{\"filePath\":\"${PCB}\"}"
```

### Step 7 — show the 3D view of the board

```bash
# editor='pcb' to target the board's 3D viewer (and skip the FP path
# which would otherwise be tried first when both editors are open).
adom-desktop kicad_open_3d_viewer '{"editor":"pcb"}'
```

This is the visual climax — the green board appears with the actual
3D chip model rendered on top. For the RP2040 pack this is a QFN-56
package; for the resistor pack it's a tiny 0805 chip.

### Step 8 — export gerbers

```bash
adom-desktop kicad_export_gerbers "{
  \"filePath\":\"${PCB}\",
  \"outputDir\":\"C:/tmp/${PACK}-gerbers\"
}"
```

Returns the list of generated `.gbr` / `.gtl` / `.gbl` / `.gm1` files.
These are JLCPCB- and InstaPCB-ready directly.

## Failure modes + recovery

| Symptom | Cause | Recovery |
|---|---|---|
| `Unknown command: export_gerbers` | Bridge < v0.7.1 | Update via `bridge_reinstall '{"name":"kicad"}'` |
| `3D Viewer did not open from Footprint Editor` | KiCad 10 WM_COMMAND ID different | Pass `editor='pcb'` (step 7 path) — works on board |
| `Library 'AdomTour' not found` after opening editor | KiCad cached its old lib-table state | Close all KiCad windows + reopen — sym/fp-lib-table is read at startup |
| Schematic opens with "older format" warning bar | Tour-pack files are KiCad 9 sexpr | Tolerable; KiCad 10 reads them. They convert on save. |
| `Cannot find footprint AdomTour:R_0805_AdomTour` | Footprint library install failed | Re-run step 1b; verify `%USERPROFILE%/Documents/KiCad/10.0/footprints/AdomTour.pretty/` exists |

## Cleanup

```bash
adom-desktop kicad_close '{}'                       # close all KiCad windows
rm -rf "%USERPROFILE%/Documents/KiCad/10.0/symbols/AdomTour.kicad_sym"
rm -rf "%USERPROFILE%/Documents/KiCad/10.0/footprints/AdomTour.pretty"
# (Or leave them — they're harmless even when not actively tour-touring.)
```

## Tour-runner Python

`plugins/kicad/skills/kicad-tour/tour_runner.py` orchestrates all 8 steps
non-interactively + pulls every screenshot to a local output dir. Usage:

```bash
python plugins/kicad/skills/kicad-tour/tour_runner.py \
    --pack tour-pack \
    --output /tmp/kicad-tour-shots
# or
python plugins/kicad/skills/kicad-tour/tour_runner.py \
    --pack tour-pack-rp2040 \
    --output /tmp/rp2040-tour-shots
```

Each step's CLI call is shown above stdout in human-readable form, with
the resulting screenshot named `01-symbol-editor.png`, `02-footprint-editor.png`,
etc. Exits 0 on full success.

When run from inside a Docker container (= relay path) vs. on the host
(= direct API path) the script's `adom-desktop` subprocess transparently
picks whichever is reachable. No config required.