# 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:
  ```bash
  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

```bash
# 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

```bash
# 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

```bash
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 |