{
  "schema_version": 1,
  "type": "skill",
  "slug": "tour",
  "title": "Tour",
  "brief": "Run an interactive guided tour of Gallia's KiCad integration.",
  "version": "1.0.0",
  "tags": [],
  "license": "MIT",
  "source_path": "SKILL.md",
  "readme": "# Gallia KiCad Feature Tour\n\nAn 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.\n\n## HARD RULES — Follow Every Time\n\nThese rules come from direct user feedback. They are non-negotiable.\n\n### 1. Be Very Talkative\n- The user complained about \"dead air time\" — there must be NO silent gaps\n- Every panel update should have a DETAILED description explaining what's happening, why it matters, and what the data means\n- Talk to the user in chat too between tool calls — explain your thinking\n- Descriptions should be 4-8 lines minimum, not 1-2 sentence stubs\n\n### 2. Take a Screenshot at EVERY Step\n- After every bridge command, window operation, or panel update — take a screenshot\n- Read the screenshot with the Read tool to verify what's on screen\n- If something looks wrong, fix it before moving on\n\n### 3. Verify Window Positions at Every Step\n- After taking a screenshot, CHECK that the expected KiCad window is visible and in the foreground\n- If it's not visible, re-issue `window front` and `window position` commands\n- Tell the user in the panel that you're verifying/fixing window positions\n- 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\"\n\n### 4. Newlines in Panel Text\n- When passing `--data` or `--description` to `tour_cli.py panel update`, use `\\n` for newlines\n- The CLI converts `\\\\n` → `\\n` automatically — just use `\\n` in your bash strings\n- NEVER show literal `\\n` to the user — always verify newlines render correctly\n\n### 5. Panel Must Not Clip\n- The narration panel uses `screen_height - 80` px to account for taskbar + titlebar\n- The \"Quit Tour\" button must ALWAYS be visible at the bottom\n- If you see it clipped in a screenshot, stop and fix it\n\n### 6. Shut Down Panel at End of Tour\n- When the tour completes (final summary step), ALWAYS run:\n  ```bash\n  tour_cli.py panel stop\n  ```\n- Also close any open KiCad editor windows\n- Do not leave the panel running after the tour ends\n\n### 7. Handle Errors Gracefully\n- If a KiCad window shows an error dialog, dismiss it (PostMessageW VK_RETURN) and explain what happened\n- If a bridge command fails, show the error in the panel and move to the next step\n- Never crash the tour — skip problematic steps and continue\n\n### 8. Kill Everything Before Starting\n- At the start of every tour, force-kill ALL KiCad processes and the old panel\n- Verify clean slate with `tasklist | grep` before proceeding\n- Check bridge server health before starting\n\n## Architecture\n\n```\nClaude Code (you — narrator + orchestrator)\n  │\n  ├── tour_cli.py panel start     → launch dark-themed narration panel (port 8799)\n  ├── tour_cli.py panel update    → push step/title/description/status/data to panel\n  ├── tour_cli.py panel stop      → shut down panel\n  ├── tour_cli.py screenshot      → capture desktop PNG → Read tool → you analyze it\n  ├── tour_cli.py highlight       → draw teal border overlay on screen (auto-dismiss)\n  ├── tour_cli.py bridge          → HTTP POST to KiCad bridge server (port 8772)\n  ├── tour_cli.py ipc-test        → run Rust IPC test binary\n  ├── tour_cli.py ipc-layer       → set KiCad active layer via IPC (live!)\n  ├── tour_cli.py window          → Win32 window find / position / close / front / wait\n  └── tour_cli.py preflight       → check all prerequisites\n```\n\n**Zero pip dependencies.** Only Python stdlib (tkinter, urllib, ctypes, subprocess).\n\n## Setup & Preflight\n\n```bash\n# Discover paths\nTOUR_DIR=\"$(cd ~/Github/adom-desktop/plugins/kicad/tour && pwd)\"\n\n# Check everything is ready\npython \"$TOUR_DIR/tour_cli.py\" preflight\n```\n\nPreflight prints `SCH_PATH` and `PCB_PATH` — save those for bridge commands.\n\nScreen size is 2560x1600 physical. Panel goes on the right (width=480). KiCad editors get positioned at `0 0 1840 1528`.\n\n## Tour Startup Sequence\n\n```bash\n# 1. Kill everything\ntaskkill //F //IM kicad.exe; taskkill //F //IM eeschema.exe; taskkill //F //IM pcbnew.exe\ntour_cli.py panel stop\n\n# 2. Check bridge\ntour_cli.py bridge health\n\n# 3. Get screen size\ntour_cli.py window screen-size\n\n# 4. Launch narration panel\ntour_cli.py panel start --port 8799\n\n# 5. Screenshot to verify panel position and Quit button visibility\ntour_cli.py screenshot\n# READ the screenshot — verify panel is on right, Quit button visible at bottom\n```\n\n## Panel Update Reference\n\n```bash\ntour_cli.py panel update \\\n  --step N --total 12 \\\n  --title \"Step Title\" \\\n  --act \"ACT_NAME\" \\\n  --description \"Multi-line description\\nwith newlines\" \\\n  --status \"Status text\" \\\n  --status-color \"#3fb950\" \\\n  --data \"Monospace data area\\nfor tables and results\" \\\n  --data-color \"#3fb950\"\n```\n\nColors: green=#3fb950, yellow=#d29922, blue=#58a6ff, red=#f85149, teal=#00b8b1\n\n## Workflow Per Step — FOLLOW THIS EXACTLY\n\nFor EVERY tour step:\n\n1. **Update panel** — set step number, title, act, description (4-8 lines explaining what you're about to do and why it matters)\n2. **Set status** — \"Running command...\" with yellow color (#d29922)\n3. **Execute** — run the bridge/window/IPC command\n4. **Update status** — change to green (#3fb950) with results summary\n5. **Update data area** — format the results as a clean monospace table\n6. **Verify window** — if a KiCad editor should be visible:\n   - Run `window front \"Editor Name\"` to ensure it's in foreground\n   - Run `window position \"Editor Name\" 0 0 1840 1528` if needed\n7. **Screenshot** — capture desktop, Read the PNG\n8. **Analyze** — verify the expected window is visible, panel looks right, button not clipped\n9. **Fix issues** — if window not visible, re-issue front/position commands; if panel text wrong, re-send update\n10. **Narrate in chat** — tell the user what you see, what's interesting, transition to next step\n\n## Tour Steps (12 Steps, 3 Acts)\n\n### Act 1: \"DESIGN\" — Analyze the Demo Schematic (Steps 1-6)\n\n**Step 1: Welcome**\n- Panel: overview of what the tour will demonstrate (3 acts, 12 steps)\n- Data area: show the act breakdown\n- No KiCad window needed yet\n\n**Step 2: Open Demo Schematic**\n- Bridge: `open_schematic filePath=<SCH_PATH>`\n- Window: wait → position (0,0,1840,1528) → front\n- Panel: explain that the bridge launches eeschema.exe via HTTP\n- Highlight the schematic area\n- Verify editor is in foreground via screenshot\n\n**Step 3: Schematic Statistics**\n- Bridge: `get_schematic_stats filePath=<SCH_PATH>`\n- Panel: show component count, wire count, power symbols, etc.\n- Explain: \"AI agents can instantly understand any design's scope\"\n\n**Step 4: List All Components**\n- Bridge: `list_schematic_components filePath=<SCH_PATH>`\n- Panel: format as Ref / Value / Footprint table\n- Explain: what each component does in the circuit\n\n**Step 5: Component Deep Dive (U1 — LM358)**\n- Bridge: `get_component_details filePath=<SCH_PATH> reference=U1`\n- Panel: show all properties, footprint, datasheet, position\n- Explain: dual op-amp, SOIC-8 package, TI datasheet\n\n**Step 6: Generate BOM**\n- Bridge: `generate_bom filePath=<SCH_PATH>`\n- Panel: format as Qty / Value / Package / Refs table\n- Explain: identical parts grouped (R1+R2 = qty 2), ready for procurement\n- Close schematic editor after this step\n\n### Act 2: \"LIBRARIES\" — Browse Component Libraries (Steps 7-9)\n\n**Step 7: Search Symbol Libraries**\n- Bridge: `search_symbols query=opamp limit=10`\n- Panel: format results as Library / Symbol / Pins table\n- Explain: 224 symbol libraries, thousands of components, regex search\n- Note in panel: \"No KiCad window needed — pure file parsing\"\n\n**Step 8: Symbol Detail — LM358 Pin Map**\n- Bridge: `get_symbol_info library=Amplifier_Operational symbol=LM358`\n- Panel: show full pin map — Pin# / Name / Type / Unit\n- Explain: AI can use pin data to auto-wire circuits correctly\n\n**Step 9: Search Footprint Libraries**\n- Bridge: `search_footprints query=QFP limit=10` (or 0805, SOIC, etc.)\n- Panel: format as Library / Name / Pads / Type table\n- Explain: 155+ footprint libraries, 15,000+ footprints, fast filename matching\n- Note: this command was added recently, searches system + user libraries\n\n### Act 3: \"PCB\" — PCB Board Analysis (Steps 10-11)\n\n**Step 10: Open PCB Layout**\n- Close any lingering KiCad windows first\n- Bridge: `open_board filePath=<PCB_PATH>`\n- Window: wait → position → front\n- If error dialog appears, dismiss it (PostMessageW VK_RETURN)\n- Panel: explain what the PCB editor shows (copper traces, pads, board outline)\n- Verify PCB Editor is in foreground via screenshot\n\n**Step 11: PCB Statistics**\n- Bridge: `get_pcb_statistics filePath=<PCB_PATH>`\n- Panel: format Board/Components/Routing sections\n- Explain: matches schematic (same component count), board dimensions, layer config\n- Close PCB editor after this step\n\n### Finale\n\n**Step 12: Tour Complete**\n- Panel: \"Tour Complete!\" with full capabilities summary\n- Data area: list ALL bridge command categories\n- Status: \"All 12 steps complete!\" in green\n- Chat: recap table of all 12 steps\n- **SHUT DOWN**: `tour_cli.py panel stop` and close any remaining KiCad windows\n\n## CLI Reference\n\n| Subcommand | Purpose | Example |\n|------------|---------|---------|\n| `preflight` | Check bridge, IPC, demo files | `tour_cli.py preflight` |\n| `screenshot [path]` | Capture desktop to PNG | `tour_cli.py screenshot` |\n| `highlight x y w h` | Draw highlight overlay | `tour_cli.py highlight 100 80 800 600 --label \"Schematic\"` |\n| `bridge <cmd> [k=v]` | Send bridge command | `tour_cli.py bridge get_schematic_stats filePath=...` |\n| `ipc-test [--section N]` | Run IPC test suite | `tour_cli.py ipc-test --section 1` |\n| `ipc-layer <id>` | Set active PCB layer | `tour_cli.py ipc-layer 34` |\n| `window <action> <title>` | Window management | `tour_cli.py window wait \"Schematic Editor\"` |\n| `panel <action>` | Narration panel control | `tour_cli.py panel start --port 8799` |\n\n### Highlight options\n```\n--color HEX       Border color (default: #00b8b1 teal)\n--duration MS     Auto-dismiss time (default: 5000)\n--label TEXT      Badge text above the highlight\n--thickness N     Border width in px (default: 3)\n```\n\n### Window actions\n| Action | Description |\n|--------|-------------|\n| `find <title>` | List windows matching title substring |\n| `close <title>` | Close the first matching window |\n| `front <title>` | Bring matching window to foreground |\n| `position <title> x y w h` | Move and resize window |\n| `wait <title> [--timeout N]` | Block until window appears (default 15s) |\n| `screen-size` | Print screen width and height |\n\n### Bridge commands available\n**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`\n\n**Schematic analysis:** `get_schematic_stats`, `get_schematic_hierarchy`, `list_schematic_components`, `get_component_details`, `list_schematic_nets`\n\n**PCB analysis:** `get_pcb_statistics`, `list_pcb_nets`, `list_pcb_footprints`, `find_tracks_by_net`\n\n**Libraries:** `list_symbol_libraries`, `search_symbols`, `search_footprints`, `get_symbol_info`\n\n**BOM & netlist:** `generate_bom`, `generate_netlist`, `trace_connection`, `get_net_connections`\n\n**Design checks:** `run_drc`, `run_erc`\n\n**Export:** `export_gerber`, `export_pdf`, `export_svg`, `export_step`, `export_bom_csv`\n\n### IPC layer IDs\n| Layer | ID |\n|-------|----|\n| F.Cu (front copper) | 3 |\n| In1.Cu (inner 1) | 4 |\n| In2.Cu (inner 2) | 5 |\n| B.Cu (back copper) | 34 |\n\n## DPI / Coordinate Notes\n\n- Screen: 2560x1600 physical, 150% DPI scaling\n- highlight.py is DPI-unaware — pass physical pixel coordinates, it converts internally\n- win_manager.py IS DPI-aware (SetProcessDPIAware) — coordinates are physical pixels\n- Panel uses tkinter logical pixels (winfo_screenwidth/height - 80px for taskbar)\n- KiCad editors: position at 0,0 size 1840x1528 (physical pixels, leaves room for panel)\n\n## Troubleshooting\n\n| Problem | Fix |\n|---------|-----|\n| Bridge OFFLINE | `python ~/Github/adom-desktop/plugins/kicad/server.py` (run in background) |\n| Panel not starting | Check port 8799 not in use; kill old panel process |\n| Quit button clipped | Panel should use `screen_h - 80` for height |\n| Literal `\\n` in panel | CLI auto-converts `\\\\n`→`\\n`; check your escaping |\n| KiCad window not in foreground | Re-issue `window front \"Editor Name\"` |\n| PCB \"Error loading\" dialog | Dismiss with PostMessageW VK_RETURN, continue |\n| Unicode error in window titles | tour_cli.py uses `.encode(\"ascii\",\"replace\").decode()` |\n| search_footprints timeout | Already optimized — fast-path filename match only |",
  "author": {
    "id": "695820315b5f1e4db2fcf602",
    "name": "Kyle Bergstedt",
    "email": "kyle@adom.inc"
  },
  "visibility": {
    "public": true
  },
  "hero": null,
  "sample_prompts": [],
  "discovery_triggers": [],
  "discovery_pitch": null,
  "metadata": {},
  "created_at": "2026-05-28T05:29:54.709Z",
  "updated_at": "2026-05-28T05:29:54.709Z",
  "sub_skills": [],
  "parent_app": null
}