KiCad - the KiCad Bridge

@@ -0,0 +1,104 @@+# The KiCad dock card and dashboard++Everything a user meets before the first `kicad_*` verb: the card in Hydrogen's dock bar, what clicking it+does, and the dashboard it opens. Read this if you are new to the bridge, or if you are building another+bridge's dashboard and want the same shape.++<img src="/blob/app/kicad-bridge/docs/img/dashboard-in-hydrogen.png" width="760" alt="The KiCad dashboard open as a webview tab in Hydrogen">++## The dock card++Hydrogen's dock bar (the rail on the right edge of the workspace) shows one card per installed Adom app.+The KiCad card comes from this page's `dockbar.json`. Its parts:++- **Title, icon, brief**: "KiCad - the KiCad Bridge", the KiCad line icon, the page brief.+- **Health LED**: the dock polls the dashboard's `/api/status` every 15 seconds and colours the card's dot+  from the same status the dashboard shows, so the card is honest before you click.+- **Say phrases**: the sentences a user can say to their AI instead of clicking anything. They name real+  content: the XL555 part, the drone motor carrier, the ESC G431 project, the Adom Basic Parts library.++## What a click does++The card's `launch` block runs two steps inside the user's own container, with a console you can watch:++1. **Installing or updating the KiCad bridge**: `adom-wiki pkg update kicad-bridge`, or a fresh install if+   the package is missing. This is the skills-plus-dashboard package, not the bridge runtime; the runtime is+   fetched by Adom Bridge itself from this page's manifest.+2. **Starting the KiCad Dashboard**: `kicad-dashboard serve --print-url`. The server backgrounds itself,+   prints its URL, and the dock opens that URL in a webview tab titled "KiCad Dashboard".++A re-click focuses the existing tab. The launch also names the AI thread for this app (`kicad-dashboard`)+and stages a prompt for it, so the dashboard's Send buttons and the demo run under a known identity.++## The dashboard, top to bottom++**Header.** The KiCad Bridge name, the target chip (which box the bridge answers on: `target: AdomLapper`),+a refresh button, the help toggle that shows or hides the prompts panel, and the settings cog.++**Say it (the newbie panel).** The one panel a first-time user needs:++- **Play the demo** runs the guided tour live in the user's KiCad: six beats on the ESC G431 board from+  the wiki (STM32 symbol, LQFP-48 footprint, the chip in 3D, the schematic, the 2D board, the 3D board).+  Each beat loads its window with a short narration line, then, once the window is verified on screen,+  explains what you see while the view zooms, pans or orbits. Adom Bridge's glass remote at the bottom+  right is the user's: play, pause, next, back, mute, stop. Every press is acknowledged with a small+  caption and honoured within a second.+- **The recording** beside it is the same tour recorded on a real desktop. It plays inline; the player's+  fullscreen control grows the webview to most of the Hydrogen window.+- **Six phrases** to say to your AI, each with copy and send buttons. Send opens a new AI thread with the+  phrase and shows progress in a toast.++**Status pills.** One row of LEDs, the same ones the dock card mirrors. Four are critical, four advisory:++| Pill | Green means | Red means |+|---|---|---|+| Relay | the cloud relay lists at least one box | no boxes connected |+| Box | the selected box answers | the box is offline |+| Bridge | the KiCad bridge answers on that box | the bridge is not answering |+| KiCad | KiCad is installed there (version shown) | KiCad not found |+| Updates | bridge and package current | an update is ready or stuck |+| Plugin | the in-KiCad plugin is bound (live instances counted) | not bound |+| Focus contract | the bridge is quiet, nothing parked or held | a verb is mid-flight |+| User presence | the user is idle | the user is active at the keyboard |++A red pill always carries its next step in its tooltip, taken from the status payload's hint.++**Boxes and actions.** Pick which box KiCad runs on when more than one is connected. Setup, Launch KiCad+and Close KiCad act on that box. The bridge only ever drives KiCad instances it launched; a KiCad the user+opened is never touched.++**Demos.** The guided demo (above) and "Tour a wiki part end to end": pull a part page from the wiki,+install its symbol, footprint and 3D model into KiCad, and generate a single-part project.++**KiCad surfaces.** One button per view for a real wiki part: fetch, install, open just that surface in+the background, and render it from `kicad_state`.++**Verb times on this box.** Every verb dispatch is logged with its outcome; p50 and p90 per verb converge+just by using the bridge. A wide gap between them means two code paths wearing one name.++**Copy-paste prompts.** Longer prompts for an AI, for the things the phrases do not cover.++**Settings.** Taskbar activity (the progress bar and Adom badge the bridge paints on KiCad's taskbar+buttons while it works) and the overlay badge, each with its own status.++## How the dashboard talks to the bridge++The dashboard is a small server in the user's container. Every button is one call to `/api/action` with a+verb name, the target box and arguments; it forwards through Adom Bridge to the KiCad bridge on that box.+`/api/status` builds the LED row from `adom-bridge targets`, the bridge's status verb and the plugin+probe. `/api/say-send` and `/ai-threads/run-prompt` hand a phrase to a new AI thread and report its+progress. Nothing here bypasses the bridge: whatever the dashboard can do, an AI can do by name.++## Sync with the desktop remote++The demo's progress poll carries the panel state, mute, the last press, and the per-beat verification+record. The dashboard's demo pill follows it: a mute pressed on the desktop remote flips the pill's speaker,+a stop from the remote's X hides the pill and toasts "closing the demo tour". Mute is session-only and is+never remembered across runs.++## For other dashboards++This layout is the dock dashboard contract: house header, say strip, status pill row, then the app's own+content. The contract and its parts live in the adom-ui-design skills (dock-dashboard, dash-header,+say-strip, status-leds, newbie-panel, dash-demo). Building a demo like this one, with its remote,+captions, narration, verification, recording and embedding, is the adom/demo-authoring-skillpack.