Gallia KiCad Feature Tour

An AI-guided interactive tour of Gallia's KiCad bridge commands. You orchestrate KiCad in real time — opening editors, parsing designs, searching libraries — while narrating to the user in a dark-themed side panel AND in chat.

HARD RULES — Follow Every Time

These rules come from direct user feedback. They are non-negotiable.

1. Be Very Talkative

• The user complained about "dead air time" — there must be NO silent gaps
• Every panel update should have a DETAILED description explaining what's happening, why it matters, and what the data means
• Talk to the user in chat too between tool calls — explain your thinking
• Descriptions should be 4-8 lines minimum, not 1-2 sentence stubs

2. Take a Screenshot at EVERY Step

• After every bridge command, window operation, or panel update — take a screenshot
• Read the screenshot with the Read tool to verify what's on screen
• If something looks wrong, fix it before moving on

3. Verify Window Positions at Every Step

• After taking a screenshot, CHECK that the expected KiCad window is visible and in the foreground
• If it's not visible, re-issue window front and window position commands
• Tell the user in the panel that you're verifying/fixing window positions
• For steps that don't need a KiCad window (library searches), say so explicitly in the panel: "No KiCad window needed for this step — library search is pure file parsing"

4. Newlines in Panel Text

• When passing --data or --description to tour_cli.py panel update, use \n for newlines
• The CLI converts \\n → \n automatically — just use \n in your bash strings
• NEVER show literal \n to the user — always verify newlines render correctly

5. Panel Must Not Clip

• The narration panel uses screen_height - 80 px to account for taskbar + titlebar
• The "Quit Tour" button must ALWAYS be visible at the bottom
• If you see it clipped in a screenshot, stop and fix it

6. Shut Down Panel at End of Tour

• When the tour completes (final summary step), ALWAYS run:

  tour_cli.py panel stop
  

• Also close any open KiCad editor windows
• Do not leave the panel running after the tour ends

7. Handle Errors Gracefully

• If a KiCad window shows an error dialog, dismiss it (PostMessageW VK_RETURN) and explain what happened
• If a bridge command fails, show the error in the panel and move to the next step
• Never crash the tour — skip problematic steps and continue

8. Kill Everything Before Starting

• At the start of every tour, force-kill ALL KiCad processes and the old panel
• Verify clean slate with tasklist | grep before proceeding
• Check bridge server health before starting

Architecture

Claude Code (you — narrator + orchestrator)
  │
  ├── tour_cli.py panel start     → launch dark-themed narration panel (port 8799)
  ├── tour_cli.py panel update    → push step/title/description/status/data to panel
  ├── tour_cli.py panel stop      → shut down panel
  ├── tour_cli.py screenshot      → capture desktop PNG → Read tool → you analyze it
  ├── tour_cli.py highlight       → draw teal border overlay on screen (auto-dismiss)
  ├── tour_cli.py bridge          → HTTP POST to KiCad bridge server (port 8772)
  ├── tour_cli.py ipc-test        → run Rust IPC test binary
  ├── tour_cli.py ipc-layer       → set KiCad active layer via IPC (live!)
  ├── tour_cli.py window          → Win32 window find / position / close / front / wait
  └── tour_cli.py preflight       → check all prerequisites

Zero pip dependencies. Only Python stdlib (tkinter, urllib, ctypes, subprocess).

Setup & Preflight

# Discover paths
TOUR_DIR="$(cd ~/Github/adom-desktop/plugins/kicad/tour && pwd)"

# Check everything is ready
python "$TOUR_DIR/tour_cli.py" preflight

Preflight prints SCH_PATH and PCB_PATH — save those for bridge commands.

Screen size is 2560x1600 physical. Panel goes on the right (width=480). KiCad editors get positioned at 0 0 1840 1528.

Tour Startup Sequence

# 1. Kill everything
taskkill //F //IM kicad.exe; taskkill //F //IM eeschema.exe; taskkill //F //IM pcbnew.exe
tour_cli.py panel stop

# 2. Check bridge
tour_cli.py bridge health

# 3. Get screen size
tour_cli.py window screen-size

# 4. Launch narration panel
tour_cli.py panel start --port 8799

# 5. Screenshot to verify panel position and Quit button visibility
tour_cli.py screenshot
# READ the screenshot — verify panel is on right, Quit button visible at bottom

Panel Update Reference

tour_cli.py panel update \
  --step N --total 12 \
  --title "Step Title" \
  --act "ACT_NAME" \
  --description "Multi-line description\nwith newlines" \
  --status "Status text" \
  --status-color "#3fb950" \
  --data "Monospace data area\nfor tables and results" \
  --data-color "#3fb950"

Colors: green=#3fb950, yellow=#d29922, blue=#58a6ff, red=#f85149, teal=#00b8b1

Workflow Per Step — FOLLOW THIS EXACTLY

For EVERY tour step:

1. Update panel — set step number, title, act, description (4-8 lines explaining what you're about to do and why it matters)
2. Set status — "Running command..." with yellow color (#d29922)
3. Execute — run the bridge/window/IPC command
4. Update status — change to green (#3fb950) with results summary
5. Update data area — format the results as a clean monospace table
6. Verify window — if a KiCad editor should be visible:
   • Run window front "Editor Name" to ensure it's in foreground
   • Run window position "Editor Name" 0 0 1840 1528 if needed
7. Screenshot — capture desktop, Read the PNG
8. Analyze — verify the expected window is visible, panel looks right, button not clipped
9. Fix issues — if window not visible, re-issue front/position commands; if panel text wrong, re-send update
10. Narrate in chat — tell the user what you see, what's interesting, transition to next step

Tour Steps (12 Steps, 3 Acts)

Act 1: "DESIGN" — Analyze the Demo Schematic (Steps 1-6)

Step 1: Welcome

• Panel: overview of what the tour will demonstrate (3 acts, 12 steps)
• Data area: show the act breakdown
• No KiCad window needed yet

Step 2: Open Demo Schematic

• Bridge: open_schematic filePath=<SCH_PATH>
• Window: wait → position (0,0,1840,1528) → front
• Panel: explain that the bridge launches eeschema.exe via HTTP
• Highlight the schematic area
• Verify editor is in foreground via screenshot

Step 3: Schematic Statistics

• Bridge: get_schematic_stats filePath=<SCH_PATH>
• Panel: show component count, wire count, power symbols, etc.
• Explain: "AI agents can instantly understand any design's scope"

Step 4: List All Components

• Bridge: list_schematic_components filePath=<SCH_PATH>
• Panel: format as Ref / Value / Footprint table
• Explain: what each component does in the circuit

Step 5: Component Deep Dive (U1 — LM358)

• Bridge: get_component_details filePath=<SCH_PATH> reference=U1
• Panel: show all properties, footprint, datasheet, position
• Explain: dual op-amp, SOIC-8 package, TI datasheet

Step 6: Generate BOM

• Bridge: generate_bom filePath=<SCH_PATH>
• Panel: format as Qty / Value / Package / Refs table
• Explain: identical parts grouped (R1+R2 = qty 2), ready for procurement
• Close schematic editor after this step

Act 2: "LIBRARIES" — Browse Component Libraries (Steps 7-9)

Step 7: Search Symbol Libraries

• Bridge: search_symbols query=opamp limit=10
• Panel: format results as Library / Symbol / Pins table
• Explain: 224 symbol libraries, thousands of components, regex search
• Note in panel: "No KiCad window needed — pure file parsing"

Step 8: Symbol Detail — LM358 Pin Map

• Bridge: get_symbol_info library=Amplifier_Operational symbol=LM358
• Panel: show full pin map — Pin# / Name / Type / Unit
• Explain: AI can use pin data to auto-wire circuits correctly

Step 9: Search Footprint Libraries

• Bridge: search_footprints query=QFP limit=10 (or 0805, SOIC, etc.)
• Panel: format as Library / Name / Pads / Type table
• Explain: 155+ footprint libraries, 15,000+ footprints, fast filename matching
• Note: this command was added recently, searches system + user libraries

Act 3: "PCB" — PCB Board Analysis (Steps 10-11)

Step 10: Open PCB Layout

• Close any lingering KiCad windows first
• Bridge: open_board filePath=<PCB_PATH>
• Window: wait → position → front
• If error dialog appears, dismiss it (PostMessageW VK_RETURN)
• Panel: explain what the PCB editor shows (copper traces, pads, board outline)
• Verify PCB Editor is in foreground via screenshot

Step 11: PCB Statistics

• Bridge: get_pcb_statistics filePath=<PCB_PATH>
• Panel: format Board/Components/Routing sections
• Explain: matches schematic (same component count), board dimensions, layer config
• Close PCB editor after this step

Finale

Step 12: Tour Complete

• Panel: "Tour Complete!" with full capabilities summary
• Data area: list ALL bridge command categories
• Status: "All 12 steps complete!" in green
• Chat: recap table of all 12 steps
• SHUT DOWN: tour_cli.py panel stop and close any remaining KiCad windows

CLI Reference

Subcommand	Purpose	Example
preflight	Check bridge, IPC, demo files	tour_cli.py preflight
screenshot [path]	Capture desktop to PNG	tour_cli.py screenshot
highlight x y w h	Draw highlight overlay	tour_cli.py highlight 100 80 800 600 --label "Schematic"
bridge <cmd> [k=v]	Send bridge command	tour_cli.py bridge get_schematic_stats filePath=...
ipc-test [--section N]	Run IPC test suite	tour_cli.py ipc-test --section 1
ipc-layer <id>	Set active PCB layer	tour_cli.py ipc-layer 34
window <action> <title>	Window management	tour_cli.py window wait "Schematic Editor"
panel <action>	Narration panel control	tour_cli.py panel start --port 8799

Highlight options

--color HEX       Border color (default: #00b8b1 teal)
--duration MS     Auto-dismiss time (default: 5000)
--label TEXT      Badge text above the highlight
--thickness N     Border width in px (default: 3)

Window actions

Action	Description
find <title>	List windows matching title substring
close <title>	Close the first matching window
front <title>	Bring matching window to foreground
position <title> x y w h	Move and resize window
wait <title> [--timeout N]	Block until window appears (default 15s)
screen-size	Print screen width and height

Bridge commands available

Editor control: open_schematic, open_board, open_symbol_editor, open_footprint_editor, open_3d_viewer, close_symbol_editor, close_footprint_editor, close_3d_viewer, close_kicad

Schematic analysis: get_schematic_stats, get_schematic_hierarchy, list_schematic_components, get_component_details, list_schematic_nets

PCB analysis: get_pcb_statistics, list_pcb_nets, list_pcb_footprints, find_tracks_by_net

Libraries: list_symbol_libraries, search_symbols, search_footprints, get_symbol_info

BOM & netlist: generate_bom, generate_netlist, trace_connection, get_net_connections

Design checks: run_drc, run_erc

Export: export_gerber, export_pdf, export_svg, export_step, export_bom_csv

IPC layer IDs

Layer	ID
F.Cu (front copper)	3
In1.Cu (inner 1)	4
In2.Cu (inner 2)	5
B.Cu (back copper)	34

DPI / Coordinate Notes

• Screen: 2560x1600 physical, 150% DPI scaling
• highlight.py is DPI-unaware — pass physical pixel coordinates, it converts internally
• win_manager.py IS DPI-aware (SetProcessDPIAware) — coordinates are physical pixels
• Panel uses tkinter logical pixels (winfo_screenwidth/height - 80px for taskbar)
• KiCad editors: position at 0,0 size 1840x1528 (physical pixels, leaves room for panel)

Troubleshooting

Problem	Fix
Bridge OFFLINE	python ~/Github/adom-desktop/plugins/kicad/server.py (run in background)
Panel not starting	Check port 8799 not in use; kill old panel process
Quit button clipped	Panel should use screen_h - 80 for height
Literal \n in panel	CLI auto-converts \\n→\n; check your escaping
KiCad window not in foreground	Re-issue window front "Editor Name"
PCB "Error loading" dialog	Dismiss with PostMessageW VK_RETURN, continue
Unicode error in window titles	tour_cli.py uses .encode("ascii","replace").decode()
search_footprints timeout	Already optimized — fast-path filename match only