adom-chip-fetcher doctor            # every component with a Hint per problem
adom-chip-fetcher --version         # should match the published package
curl -s 127.0.0.1:8786/health       # {ok, app, version, installed_version, stale}
adom-chip-fetcher ui state          # what the page is showing
adom-chip-fetcher ui console        # the page's console ring buffer
adom-wiki issue list adom/adom-chip-fetcher

# chip-fetcher (cf) thread handoff

Written 2026-08-24 by the `adom-chipfetcher` thread running in John's cloud container,
so the work can continue in an ah AI thread on AdomLapper (32 GB) instead. The
conversation history does not move; everything you need is here and in the page repo.

## Where the truth lives

- **Source of record: the wiki page repo** `adom/adom-chip-fetcher`. It is byte-identical
  to the working tree that produced 1.4.5. Clone it and you have everything:
  `adom-wiki repo clone adom/adom-chip-fetcher --dir ~/project/chip-fetcher`
- **Published package**: 1.4.5. Every earlier 1.3.x/1.4.x is deprecated with a reason.
- **The cloud container ALSO has a working tree** at `/home/adom/project/chip-fetcher`
  with ~100 files changed and NOT committed to git (John has not asked for a commit; the
  GitHub remote `adom-inc/chip-fetcher` is many commits behind). Nothing is lost: the wiki
  repo holds the same bytes. If John wants git history, commit from whichever tree he says.

## Your identity and etiquette

- ai-thread name: **adom-chipfetcher**. Pass `--ai-thread "adom-chipfetcher"` on every
  `adom-bridge` call and `adom-chip-fetcher` invocation.
- John works on **AdomLapper**. Never foreground, resize, or switch tabs on windows he is
  using. Signal with `pup_alert_window` (taskbar flash) and the taskbar progress bar.
- The dashboard lives in a pup window (`sessionId adom-chip-fetcher-dashboard`), opened and
  maximized ONCE by `adom-chip-fetcher app`, and also in the ah dock's own webview tab.
- Show John results in pup and log them to shotlog; never just claim something is done.

## What this app is

Chip Fetcher crawls the web on the user's behalf to gather everything about the chips they
care about: datasheet, symbol, footprint, 3D model, stock and pricing, manufacturer site
first. Users drive it by talking to their AI with the word **cf**, never by clicking. The
dashboard is a dock-bar app whose main UI is the dock target.

## State as of 1.4.5

Shipped today: the Hydrogen Dock Bar contract (always-fresh launch, `/api/status` LEDs with
CORS, `serve --print-url` self-backgrounding and version-aware), the settings-layout modal,
indeterminate taskbar progress for lookups, vendor logins on pup's OS-keychain vault
(chip-fetcher stores no passwords), the transport migrated to `adom-bridge` + `pup_*`,
`doctor --fix` with self-healing for broken sister packages, sample parts seeded from the
wiki, a guided demo (play/pause/prev/next/exit, pre-baked adom-tts clips, ab captions), the
full-width newbie panel, a visible line-drawing favicon, and a self-watch that hands the
port over when a package update replaces the binary.

## Open items, in priority order

1. **UN-PARK Send to AI (in progress, do this first).** John ruled 2026-08-24: "we are
   re-enabling the send to ai." Flip `SAY_SEND_PARKED` in `src/serve.rs` (currently `true`,
   which short-circuits `/api/say-send` before any control-API call). Then follow the
   un-park checklist in the `say-strip` skill: re-read the tag literal (must be
   `dock:adom-chip-fetcher`, the PAGE SLUG, not the card id), keep the failure path
   (error toast + copy fallback), and verify from a CLEAN `adom-wiki pkg install` rather
   than the source tree.
2. **Required fast-follow: a shell-version guard.** Published Hydrogen 1.0.141 predates the
   crash fix, so a pre-fix shell must get an honest refusal plus the copy fallback rather
   than a crash. UNSOLVED DETAIL: the control API exposes no semver. `GET /buildinfo` and
   `GET /health` return only `build_sha`, `build_epoch`, `build_local`, `build_dirty`
   (measured on John's box: sha 356050b4, built Aug 24 6:08 AM, dirty). Decide with the ah
   build thread (project-c3 owns the dock queue) whether to gate on `build_epoch >= <fix
   epoch>`, on a capability probe, or on a version field they add. Do not invent a semver
   comparison against a field that does not exist.
3. **Newbie panel 1.12.0 two-column table spec.** adom-ui-design changed the layout again
   (demo button left, prompts as a quiet TABLE right, not pills). project-c3 said to WAIT
   for their broadcast before matching pup pixel for pixel, because pup is the reference
   and John is reviewing it.
4. **project-c3 will re-run the cf dock card in ah** and inject an ah-native screenshot of
   1.4.5 into the `dock-dashboards` shotlog channel. Nothing needed from us.
5. **Git commit** of the ~100 changed files, if John wants history. Not yet approved.

## Upstream bugs I filed (each is issue #1 on its page)

- `adom/adom-step`, `adom/adom-chipsmith`: install.sh never installs the binary it ships.
- `adom/adom-concur`: install.sh sudo-installs to /usr/local, fails in containers.
- `adom/adom-sfconvert`: ships no binary at all.
`doctor --fix` self-heals the first three from the package payload; sfconvert cannot be
healed locally and was hand-copied onto John's box as a stopgap.

## Hard-won traps, do not rediscover these

- **A test that cannot fail is worse than no test.** I shipped an invisible favicon because
  my check substituted `currentColor` for white before rendering. Render a favicon AS ITS
  OWN DOCUMENT at 16px on `#161b22` and count pixels: 0 bright / 62 dark was the bug,
  88 bright / 0 dark is the fix.
- **`currentColor` is black in a favicon.** Hardcode `#e6edf3` in any SVG loaded as its own
  document; keep `currentColor` only for SVG inlined in markup.
- **After a package update**, `/proc/<pid>/exe` resolves to `<path> (deleted)` while
  `/proc/<pid>/cmdline` stays clean. Strip the suffix before any path use.
- **The stale-server bug was a race**, not bad matching: the dock updates the package while
  the launch steps run, so `serve` can be the OLD binary reusing itself. Three defences are
  in place (handoff when not the installed build, port-ownership retirement, self-watch).
- **`/tmp` is shared across concurrent AI threads** in this container. Write payloads to
  your own scratchpad; another thread's file nearly made me drive the wrong app.
- **`pgrep -f 'adom-chip-fetcher serve'` matches your own shell** and kills it. Anchor the
  pattern (`^/path/to/adom-chip-fetcher serve`).
- **Never trust a version stamp alone** on incremental builds; check a code marker.

## Fast orientation commands

```bash
adom-chip-fetcher doctor            # every component with a Hint per problem
adom-chip-fetcher --version         # should match the published package
curl -s 127.0.0.1:8786/health       # {ok, app, version, installed_version, stale}
adom-chip-fetcher ui state          # what the page is showing
adom-chip-fetcher ui console        # the page's console ring buffer
adom-wiki issue list adom/adom-chip-fetcher
```