Chip Fetcher (cf)

@@ -0,0 +1,116 @@+---+name: adom-chip-fetcher-dock+description: How Chip Fetcher lives in the Hydrogen Dock Bar (the app-launcher rail on the right edge of ah). What the dock card does when clicked, the contract this app implements (version-aware serve --print-url, direct 127.0.0.1 URL, /api/status LEDs with CORS, webview ownership via ADOM_DOCK_WEBVIEW, the Say it strip, the settings modal, taskbar progress), where dockbar.json lives and why it is in the PAGE REPO, the first-run path for a brand-new user, and how to diagnose a red LED or a launch that never answers. Parent skill: adom-chip-fetcher. Trigger words: chip fetcher dock, dock bar chip fetcher, add chip fetcher to my dock, chip fetcher card, chip fetcher LED red, chip fetcher not answering, dockbar.json chip fetcher, chip fetcher serve print-url, chip fetcher dock webview, chip fetcher say it, chip fetcher first run, chip fetcher doctor.+---++# Chip Fetcher in the Dock Bar++Parent skill: **adom-chip-fetcher**. Read that one for sourcing chips; read this one for the launcher.++## Purpose++The Dock Bar is Hydrogen's app launcher: a rail of cards on the right edge of the+workspace, one card per wiki app. The Chip Fetcher card is the zero-setup way in for a+brand-new Adom user: one click installs the CLI and its thirteen sister tools into their+container, starts the dashboard server, and shows the MAIN dashboard in the dock's webview+tab. There is no separate launcher or status page: the dock click lands on the same+dashboard `chip-fetcher app` opens in pup.++The card's LED is live health read from `/api/status` every 15 seconds while the rail is+open, so a user sees at a glance whether the app, its sister tools, the desktop bridge and+pup are ready before they ask for their first part.++## What a click does, step by step++1. Hydrogen opens a webview tab named **Chip Fetcher** (from `webview.title` in+   `dockbar.json`) showing the launch interstitial, with this app's favicon+   (`docs/img/dock-chip-fetcher.svg`) from the first frame and the `say` phrases on it.+2. It runs the manifest's `container_command` steps in the user's workspace container:+   - **Installing Chip Fetcher**: `adom-wiki pkg install adom/adom-chip-fetcher`, skipped+     when `command -v adom-chip-fetcher` already succeeds (the `skip_if`). PATH is+     prefixed with `~/.local/bin`, where wiki CLIs land. The install pulls every+     dependency (adom-symbol, adom-footprint, adom-step, adom-lbr, adom-chipsmith,+     adom-chip-thumbnailer, adom-concur, adom-ds2sf, adom-sfconvert, adom-parts-search,+     adom-mouser, adom-digikey, adom-jlcpcb), the binary under both names+     (`adom-chip-fetcher` + `chip-fetcher`), the UI assets, and both AI skills.+   - **Starting the Chip Fetcher dashboard**: `adom-chip-fetcher serve --print-url` with+     `await: "url"`; the dock scrapes the printed URL and polls it until it answers.+3. `serve` takes over the interstitial tab itself: the dock sets `ADOM_DOCK_WEBVIEW` (the+   tab name) and `ADOM_DOCK_APP` in each step's environment, and the detached server calls+   `adom-cli hydrogen webview open-or-refresh --name "$ADOM_DOCK_WEBVIEW" --url+   http://127.0.0.1:8786/`. Re-running with the same name just renavigates the tab: that+   idempotence is the ownership handle. Unset variable (a hand-run serve) touches nothing.+4. The dock polls `GET /api/status` every 15 seconds and paints the card's LED from the+   payload's top-level `state`.++## The contract, as implemented here++| Rule | Where | How |+|---|---|---|+| Serve self-backgrounds | `src/serve.rs` + `src/dock.rs` | spawns a detached copy of itself (`serve --detached-child`, own session via setsid), waits up to 15 s for `/health`, prints the URL, exits 0. The dock's exec returns in ~100 ms |+| Serve is idempotent and version-aware | `src/dock.rs` | an instance of OURS at the same version is reused (URL printed, webview reclaimed). A DIFFERENT version is retired first: victims matched by EXACT argv (`adom-chip-fetcher serve ...` or the `chip-fetcher` alias), never by substring, because a substring match kills the shell that invoked it |+| Direct URL | `src/dock.rs` | prints `http://127.0.0.1:8786/`, never the `/proxy/<port>/` form and never the name `localhost` (Windows resolves it IPv6-first while WSL binds IPv4; ~800 ms per request vs 13) |+| Health with CORS | `src/serve.rs` + `src/dock.rs` | `GET /health` = `{ok, app, version}`. `GET /api/status` is cached 10 s so the dock's 2 s probe budget always lands. EVERY response carries `Access-Control-Allow-Origin: *` and `OPTIONS` answers 204: the dock probes cross-origin from the shell page, and without the header the card reads "not answering" while curl says 200 |+| Per-facet LEDs + owned rollup | `src/dock.rs` (`build_facets`) | facets: Dashboard, AI skill, Sister tools (13 binaries on PATH), Desktop (`adom-bridge targets`), Library (parts + completeness; an incomplete library is work in progress, never a warning). Top-level `state` is our own rollup and wins; each facet carries a `_hint` naming the exact fix |+| Say it | `dockbar.json` + the page | six phrases in the user's noun ("fetch STM32F103C8T6 with **chip fetcher**"), shown on the interstitial and as the FIRST strip on the dashboard: copy on click, Try it stages into this app's own AI thread (census first, history second, copy fallback; `src/dock.rs::try_phrase`) |+| Settings window | the page | the cog at the right end of the 44px header opens the settings-layout modal: Components (Install / Update rows with a live console), Taskbar, Dashboard, Logins (pup's vault), two-click Restore defaults |+| Taskbar progress | `src/taskbar.rs` | the whole lookup paints an INDETERMINATE bar on the dashboard pup window's taskbar button (`pup_progress`), driven by the heartbeat protocol; short verbs (cse, ds2sf) fill a determinate bar from persisted running averages (`~/.config/adom-chip-fetcher/durations.json`). Toggle: `chip-fetcher settings set taskbar_progress off` |++## The first-run path (what a newbie sees)++The dock click is designed to work on a container that has NEVER seen chip-fetcher:++1. The install step runs in the interstitial's console, line by line.+2. The dashboard opens with the **Say it** strip first, the **component LED row** under it,+   and (library empty) a **Welcome card** with three numbered steps: check the LEDs, say a+   phrase to your AI, watch the cards land.+3. `adom-chip-fetcher doctor` prints the same facets in the terminal, one line each with a+   Hint per problem; `doctor --fix` installs whatever is missing. Run it before the first+   fetch on any new container.+4. The dock's staged AI prompt (dockbar.json `ai`) tells the AI to read the skill, run+   doctor, and ask which part numbers to source.++## Where the files live++- `dockbar.json` (manifest 1.2.0) is at the ROOT of the wiki **page repo**+  (`adom-wiki repo show adom/adom-chip-fetcher dockbar.json`). The dock reads the page+  repo, NOT the registry tarball; the two stores are separate. Any edit must be pushed+  with `adom-wiki repo push` or the dock never sees it. The `say` list in it is the single+  source both the interstitial and the dashboard strip read (`GET /api/say`).+- `docs/img/dock-chip-fetcher.svg` (the favicon the manifest names) must exist at that+  path in the page repo, monochrome white.+- The card's artwork is the page's hero + one-line brief, rendered from the wiki page on+  the dock's next poll; nothing ships in the app for it.++## Add the card to a dock++Dock settings (the gear at the top of the rail), **Add app**, `adom/adom-chip-fetcher`.+Being in the curated list is not required. A card with no LED means the app is not+running; that is the honest state.++## Diagnose++Read the LED payload first; every facet carries a `_hint`:++```bash+adom-chip-fetcher health            # {ok, app, version} or a Hint to start serve+adom-chip-fetcher doctor            # one line per facet + Hints; exit 1 while anything needs attention+curl -s http://127.0.0.1:8786/api/status | python3 -m json.tool+```++| Symptom | Cause | Fix |+|---|---|---|+| Card reads "not answering" while the page works | CORS stripped from `/api/status` | `curl -si http://127.0.0.1:8786/api/status \| grep -i access-control` must show `*`; update the package if missing |+| Launch fails "never answered" | serve ran in the foreground (dock killed it at timeout) or the port is held by something that is not us | `adom-chip-fetcher serve --print-url` by hand prints the error and a Hint |+| Works for the author, fails for users | binary not on PATH in the exec shell | the manifest steps prefix `PATH="$HOME/.local/bin:$PATH"`; check `~/.local/bin/adom-chip-fetcher` exists |+| Yellow LED | a facet's detail says which: skill missing, sister tools missing, no desktop on the bridge | `adom-chip-fetcher doctor --fix`, or open Adom Hydrogen on the desktop |+| Users pinned to an old dashboard after an update | an old server kept the port | `serve` retires a running instance whose version differs; relaunch from the card or run `adom-chip-fetcher serve --print-url` once |+| The tab did not get taken over | `ADOM_DOCK_WEBVIEW` unset (hand-run) or `adom-cli` missing | expected for a hand-run; the dock navigates the interstitial itself as a fallback |+| Say it strip empty | `dockbar.json` missing from the page repo copy the server reads | reinstall the package (`~/.local/share/adom-chip-fetcher/dockbar.json`), or push dockbar.json to the page repo |++## Cold verify (what the dock thread checks)++On a box that has never had the CLI: add the card, click it, watch the console run the+install step (every sister tool lands), then the serve step print+`http://127.0.0.1:8786/`, then the tab navigate to the dashboard with the Say it strip on+top, the LED row populated, the Welcome card up, and the card's LED green within 15 s.