# After user-handoff: poll for reCAPTCHA passed state
adom-desktop browser_eval "{\"sessionId\":\"$S\",\"expr\":\"!!(document.querySelector('[name=g-recaptcha-response]')?.value)\"}"
# returns true when user has passed → agent fires Submit

adom-desktop browser_eval '...recaptcha-passed-check...' \
  | jq -r '.result' \
  | grep -q true && echo "PASSED"

# 1. Foreground the page
adom-desktop browser_raise_os_window '{"sessionId":"chip-fetcher"}'

# 2. Screenshot for the chat
adom-desktop browser_screenshot '{"sessionId":"chip-fetcher","maxWidth":1500}'

# 3. Update activity badge so the dashboard shows "stuck — needs user"
curl -X POST http://127.0.0.1:8786/api/activity -d '{"mpn":"<MPN>","stage":"stuck — need user help"}'

# 4. Tell the user what you tried and ask one specific question.
#    GOOD: "WAGO product page has no .pdf anchor. The Generate Datasheet
#    modal opens but I can't find the CAD link. What do I click?"
#    BAD: "I couldn't find anything, what now?"

# 5. After the user answers, drive their suggested path AND
#    update SKILL.md (or the relevant playbook) with the new vendor-specific pattern.

# Handoff + watching (chip-fetcher playbook)

When the agent has to hand off a click to the user. Read this when you've decided you can't automate something — captcha, OAuth, OS-level prompt, etc.

## The escape valve, NOT the routine

**chip-fetcher does ALL the clicking.** Never ask the Adom user to click Download, Allow, dismiss a dialog, dismiss a cookie banner, or operate any browser UI on their behalf. chip-fetcher exists so the user *doesn't* have to do that work — once they've signed in (one time, per service), every subsequent click is the agent's job.

If a click looks impossible (Chrome permission dialog, OS-level prompt), the answer is **find a way** — pre-grant the permission via CDP, set a Chrome startup flag, screenshot-and-OS-click via desktop automation, or change the URL flow to skip the gate entirely. Reaching for "user, please click X" is a skill bug, not a workaround.

Direct user quote: *"do it yourself … you always have to do all the work, not the adom user."*

If the agent has genuinely tried every automated path and still cannot click something, fall back to surfacing the obstacle clearly (screenshot + one-line description) — but treat that as a failure mode worth fixing in the skill, not a routine handoff.

User clarification: *"if there are instances where you truly need the human's input, you have to stop and ask for their help."* That is the escape valve, not a routine fallback.

## When handing off a click, ALWAYS watch for the resulting state change

**Never end a user-handoff with "tell me when you're done" / "say done when you've clicked it" / "let me know once it's checked."** That's a skill bug. The agent's job after a handoff is to **immediately set up a watcher** that detects the state change and auto-continues — the user shouldn't have to think about coordination, just click the thing.

**The pattern:**

1. Foreground the pup window with `browser_raise_os_window`.
2. Tell the user **what** to click in one short sentence (e.g., *"please click the reCAPTCHA 'I'm not a robot' checkbox"*).
3. **Immediately arm a Monitor** that polls for the post-click signal — typically a DOM state change (button enabled / checkbox checked / specific class added) or a network signal (zip lands in Downloads, popup tab appears, API response).
4. When the Monitor fires, auto-continue the flow. The user only ever did one click.

**Wrong (asking for verbal confirmation):**
> "Click the reCAPTCHA, then tell me 'done' and I'll click Submit."

**Right (watching):**
> "Click the reCAPTCHA. I'm watching the page state — will auto-Submit when the checkbox goes green."

```bash
# After user-handoff: poll for reCAPTCHA passed state
adom-desktop browser_eval "{\"sessionId\":\"$S\",\"expr\":\"!!(document.querySelector('[name=g-recaptcha-response]')?.value)\"}"
# returns true when user has passed → agent fires Submit
```

## Examples of state changes worth watching for

| Handoff trigger | Signal to watch for |
|----------------|---------------------|
| reCAPTCHA "I'm not a robot" | `[name=g-recaptcha-response]`'s value populates (non-empty string) |
| Sign-in / OAuth | URL changes back to the post-login redirect, OR a logged-in indicator (avatar) appears |
| Slide CAPTCHA | Same-origin redirect away from the verification page, OR a session cookie gets set |
| Multi-file download Allow dialog | Next download click actually lands a file in Downloads (the Allow only shows once per origin) |
| User picks a CAD format | Submit button becomes enabled / loses `disabled` attribute |
| User confirms an OS-level prompt | Request-following signal (file appears, page navigates, etc.) |

**Implementation hint** — Monitor with a poll loop:

```bash
adom-desktop browser_eval '...recaptcha-passed-check...' \
  | jq -r '.result' \
  | grep -q true && echo "PASSED"
```

Wrap that in a Monitor `until ... do sleep 2; done` and the agent knows the moment the user clicks.

Direct user quote: *"you're always supposed to watch. why did you not do that this time? is it not in the skill?"*

## When stuck on a vendor — show user + let them teach you

chip-fetcher is a community-built, recursively-learning skill. When the agent hits a dead end on a CAD/datasheet fetch:

1. **Open the product page in pup foreground** (`browser_raise_os_window`).
2. **Take a screenshot** so the user can see exactly what page state the agent landed on.
3. **Ask the user one short question:** *"I can't find a CAD download path on this page — can you spot it? Click the right button or describe what you see."*
4. **Wait for the user's hint** (they'll often say "click the CAE icon," "click the Documents tab," "the dimensional drawing has a STEP link," etc.).
5. **Implement the path the user described.**
6. **Capture the new pattern into this skill** with a vendor-specific section so the next agent doing the same vendor's part finds it automatically. Cite the user's verbatim hint as the rationale.

Examples accumulated this way:
- **WAGO Generate Datasheet popup auto-closes** — *"wago opens the datasheet in a new tab, so you could just see that tab and then save it locally"* → added "clicks may open in new tab" rule
- **Mouser sidebar has both Datasheet AND ECAD** — *"remember that mouser has these"* → added Mouser-as-first-class playbook
- **WAGO has a CAE icon that opens UL embedded** — *"if you click the CAE button it pulls up the wago UL download which has cad"* → added vendor.ultralibrarian.com/Wago/Embedded/?vdrPN=<MPN>
- **Cookie banners block clicks via z-index** — *"you're supposed to always accept their stupid cookie dialogs automatically"* → cookie-walker rule
- **Slide-CAPTCHAs can't be scripted** — *"are you able to drive that?"* → user-handoff escape valve
- **Profile-name churn destroys auth** — *"why did you not remember that so my profile loads again?"* → profile-name-is-sacred rule

Direct user quote on the meta-rule: *"our users can help build out this skill as they need specific parts. so you should always show them the product page when you think you're at a dead end and let them help you figure out how to get the cad just like i have several times. then figure it out from their feedback and add to the skill for all other users. we can then make them almost be like a recursively learning loop from everyone."*

**Operational template** when the agent hits a dead end:

```bash
# 1. Foreground the page
adom-desktop browser_raise_os_window '{"sessionId":"chip-fetcher"}'

# 2. Screenshot for the chat
adom-desktop browser_screenshot '{"sessionId":"chip-fetcher","maxWidth":1500}'

# 3. Update activity badge so the dashboard shows "stuck — needs user"
curl -X POST http://127.0.0.1:8786/api/activity -d '{"mpn":"<MPN>","stage":"stuck — need user help"}'

# 4. Tell the user what you tried and ask one specific question.
#    GOOD: "WAGO product page has no .pdf anchor. The Generate Datasheet
#    modal opens but I can't find the CAD link. What do I click?"
#    BAD: "I couldn't find anything, what now?"

# 5. After the user answers, drive their suggested path AND
#    update SKILL.md (or the relevant playbook) with the new vendor-specific pattern.
```

## EDA-agnostic terminology in user-facing UI

**Adom is EDA-agnostic — chip-fetcher must support KiCad, Fusion 360 Electronics, Altium, OrCAD, EAGLE, and others.** Files on disk can be `.kicad_sym` / `.kicad_mod` (since KiCad's open format is the de-facto interchange), but **never expose those filenames as labels in the viewer or in user-facing CLI output**. Translate to neutral EDA terminology:

| under-the-hood file | user-facing label |
|--------------------|--------------------|
| `*.kicad_sym` | "SYMBOL" |
| `*.kicad_mod` | "FOOTPRINT" |
| `*.step` | "STEP" *(industry-standard, no translation needed)* |
| `*.pdf` | "PDF" or "DOCS" *(both are vendor-neutral)* |

Direct user quote: *"don't refer to stuff as MOD if what you mean by that is a footprint … we want adom to be applicable to all EDA software like kicad, fusion 360, altium, orcad, etc. so we don't want to go too heavy on any kicad references. its fine that we're using mod files under the hood, but we don't have to reveal that."*

Apply this rule to:
- Card badges in the viewer
- Filter labels ("missing footprint" not "missing MOD")
- CLI output (`chip-fetcher status` should print "footprint" not "mod")
- Status messages and tooltips
- Skill documentation when describing user-visible behavior