# 1. Manufacturer page banners
adom-desktop browser_eval '{"sessionId":"x","expr":"document.body.textContent.match(/not recommended for new designs|nrnd|end of life|obsolete|last time buy|phased out/gi)?.slice(0,3)"}'

# 2. Mouser API
adom-mouser search "<MPN>" | jq '.components[0] | {lifecycle, stock_text, lead_time}'
# lifecycle != "" and != "Active" → flag

# 3. DigiKey API
adom-digikey search "<MPN>" | jq '.components[0].lifecycle'

{
  "checked_at": "2026-05-03T01:15:00Z",
  "primary_variant": "TPS25751DREFR",
  "primary_reason": "highest_stock",
  "variants": [
    {
      "mpn": "TPS25751DREFR",
      "mouser_pn": "595-TPS25751DREFR",
      "stock": 3276,
      "unit_price": "$2.99",
      "package": "DREF",
      "lifecycle": "Active",
      "lead_time": "...",
      "product_url": "...",
      "datasheet_url": "..."
    }
  ],
  "mouser": {
    "mouser_pn": "...",
    "in_stock": 2995,
    "expected_dates": [{"qty": 2995, "date": "2026-09-04"}],
    "min_order": 1, "multiple": 1, "lead_time_weeks": 20,
    "lifecycle": "active",
    "price_breaks": [{"qty": 1, "unit_price_usd": 4.14}],
    "product_url": "...",
    "rohs": true,
    "datasheet_url": "..."
  }
}

# Sourcing ladder (chip-fetcher playbook)

The defining rule for where chip-fetcher looks for CAD + datasheets, in priority order. Read this when starting any new MPN fetch, or when debugging why the agent went to the wrong source.

## The ladder, in priority order

1. **Manufacturer's own site** (`ti.com`, `nordicsemi.com`, `nxp.com`, `st.com`, `analog.com`, `microchip.com`, `bosch-sensortec.com`, `wago.com`, `vishay.com`, `diodes.com`, `renesas.com`, `espressif.com`, `latticesemi.com`). Datasheet, app notes, errata, lifecycle status, and a "CAD" / "Tools & Software" link if they partner with UL/CSE.
2. **SnapEDA / SnapMagic** (`snapeda.com`) — free CAD downloads (symbol + footprint + STEP + 3D + Altium/KiCAD/Eagle/OrCAD/etc.) for millions of parts. **Login required (most EEs already have one).** Comprehensive coverage especially for chips that aren't on UL/CSE — including Nordic, niche connectors, passives, etc. Should come right after manufacturer-direct, before chasing CSE-direct or UL-guess URLs.
3. **Mouser** (`adom-mouser search "<MPN>"`) — stock + pricing always, plus Mouser product page can surface UL/CSE deep-links.
4. **DigiKey** (`adom-digikey search "<MPN>"`) — broader catalog, niche industrial parts.
5. **Arrow** (`arrow.com`) — niche distributor.
6. **CSE direct** / **UL direct** — only when the manufacturer routes you there from their own page.
7. **LCSC** (`lcsc.com`, `datasheet.lcsc.com`) — **LAST RESORT, AVOID IF POSSIBLE.** LCSC redistributes manufacturer datasheets and EasyEDA-imported CAD, but quality is uneven and we lose the manufacturer's own provenance. Only fall here when steps 1–6 all returned nothing usable, and even then prefer to surface "we couldn't find this on the manufacturer's site" to the user instead of silently grabbing from LCSC.

Direct user quote (2026-05-06): *"when you're falling back to mouser for the search, after that you should do digikey, and then only after that try lcsc. i really want to avoid lcsc at all costs, but it is in the list if we're desperate."*

**Stock data is independent of the ladder:** always pull `stock.json` from the Mouser API alongside, regardless of where CAD/PDFs come from.

## Why manufacturer first (the ironclad rule)

- Vendor docs are authoritative (latest revision, full set of app notes).
- Manufacturer pages link to UL/SnapEDA deep-links specifically for their parts — find them by following the "CAD" link FROM the vendor page, never by guessing URLs.
- Errata + lifecycle status from the vendor is authoritative.

Direct user quotes:
- *"i keep telling you to not go beyond the manufacturers website."*
- *"look at the manufacturer web pages then. i want you always doing that first anyway before looking at 3rd party sites like mouser/digikey."*
- *"the whole point here is we want to get files, especially step files, from the manufacturer. so you can't cheat. only fallback to places like mouser when you're desperate."*

**🔒 IRONCLAD RULE: never leave the manufacturer's own website without explicit user approval.**

**This applies EVEN WHEN you "already know" the part.** When the agent has high prior confidence about a part (e.g. "LTST-C190KRKT is a Lite-On 0603 red LED, SnapMagic has it"), the cognitive shortcut is to skip the mfr-site probe and jump to the known-source. **Don't.** The rule isn't "check the mfr site when uncertain" — it's "always START at the mfr site, even when confident, before recommending or fetching from anywhere else." Confidence about the part identity is not a substitute for confirming the manufacturer's own site state.

The failure pattern that repeatedly trips this: user asks "do we have indicator LEDs?" → agent recalls a known part family from training → queries Mouser for stock validation → recommends fetching from SnapMagic — without ever opening `<mfr>.com`. That's a direct skill-rule violation. Direct user pushback (recurring): *"why do you keep not using the preference order i'm asking for?"*

The right reflex: open the manufacturer's product page first, even if it takes 30 seconds. Lite-On has `liteonopto.com`, Würth has `we-online.com`, etc. Walk the page, look for CAD/Datasheet/3D Model links. ONLY after exhausting the mfr's site is it OK to talk about SnapMagic / Mouser-CSE / UL fallbacks.

What this means in practice:
1. **Stay on `<vendor>.com` only.** Don't bounce to `3dfindit.com`, `partcommunity.com`, `mouser.componentsearchengine.com`, `vendor.ultralibrarian.com`, `snapeda.com`, `componentsearchengine.com`, or any third-party site **unless the manufacturer's own page links there explicitly** (e.g. TI/ST/ADI/Microchip embedding a `vendor.ultralibrarian.com/<slug>/embedded` URL counts as mfr-endorsed; navigating to UL via Google search does NOT).
2. **If you can't find CAD on the manufacturer's site, REPORT that to the user.** Don't go hunting on aggregators silently. The user will tell you what to do.
3. **Mfr-uploaded ≠ mfr-direct.** SamacSys hosts mfr-uploaded models, but the discovery / distribution channel is still third-party. Always check the mfr's site FIRST, exhaustively, even if you "know" it's going to fail.
4. **Native non-KiCad formats are still mfr-direct.** Altium `.IntLib`, OrCAD `.olb`/`.dml`, EAGLE `.lbr`, Renesas `.dml`, NXP `.bxl` — all of these qualify as mfr-authored. Pull them and convert to KiCad later; don't reject them because they're not in our preferred format.
5. **Exhaust the manufacturer's site before reporting "not available."** Walk every tab (Design Resources, Documentation, Tools & Software, Software & Drivers, Documents & Downloads, Hardware Files), expand every "Toggle" / accordion, click every icon-only button, scrape every `<img>` `alt`/`src`, follow every PDF/zip link, navigate to every Package / Pinout / Mechanical Drawing subcategory.

## Where SnapEDA shines (Tier 2)

When the manufacturer doesn't publish CAD directly (Nordic for example — `nordicsemi.com` doesn't expose chip CAD, only firmware SDK + reference-board Altium files), SnapEDA is the next viable free source. It's free with a login, and **most embedded engineers already have a SnapEDA account**.

Direct user pushback when chip-fetcher missed SnapEDA on Nordic's nRF52840-CKAA dead-end: *"why haven't you tried that before?"* Answer: should have. Adding to the ladder permanently.

## NRND / EOL / Last-Time-Buy is a hard stop for chip-fetcher's own picks

When a manufacturer page (or distributor lifecycle field) says any of these, treat it as a hard signal that the part is on its way out of the market:

- "Not Recommended for New Designs" / "NRND"
- "End of Life" / "EOL" / "Obsolete"
- "Last Time Buy" / "LTB" / "Last Order"
- DigiKey/Mouser `lifecycle` field set to anything except `active` / "" / "Active"
- Bosch/ST "Phased out" / "Mature"
- TI "Lifecycle: NRND"
- Mouser "Discontinued"
- Vendor pages with the explicit warning banner at the top

**The rule:**

1. **If the user explicitly asked for that exact MPN** → fetch it AND surface the lifecycle warning prominently. *"Heads up — TI has TPS40190EVM marked NRND, expect availability to drop within 2–3 years; do you still want it or should I find an active equivalent?"* Pause and let them decide. Their design might already be locked to that specific part for a reason (existing PCB, qual'd component, BOM compatibility).
2. **If chip-fetcher was choosing the part on its own** (default library picks, "popular" suggestions, batch fills, "show me a good op-amp" requests) → **DO NOT add it to the library.** Pick an active replacement. NRND parts will be unbuyable for InstaPCB users in 1–3 years; baking them into Adom's default library means real boards won't be manufacturable at scale.
3. **Always include `lifecycle` + `lifecycle_warning` in the stored `stock.json`** so downstream tools (InstaPCB, BOM checker) can flag these without re-scraping.

Direct user quote: *"if the page says 'not recommended for new designs' that you take that seriously. let the user know if they asked you specifically to get that part, but if you were just thinking that part was a good idea for some reason, it's not a good idea."*

**Detection sources** (check all three):

```bash
# 1. Manufacturer page banners
adom-desktop browser_eval '{"sessionId":"x","expr":"document.body.textContent.match(/not recommended for new designs|nrnd|end of life|obsolete|last time buy|phased out/gi)?.slice(0,3)"}'

# 2. Mouser API
adom-mouser search "<MPN>" | jq '.components[0] | {lifecycle, stock_text, lead_time}'
# lifecycle != "" and != "Active" → flag

# 3. DigiKey API
adom-digikey search "<MPN>" | jq '.components[0].lifecycle'
```

**Viewer badge:** when lifecycle is non-active, render a red "NRND" / "EOL" badge next to the stock badge so it's immediately visible during library browsing.

## Track Mouser stock + pricing as first-class data

chip-fetcher isn't just a CAD library — it's the source-of-truth for whether each chip can actually be put into an InstaPCB build. Every chip in `library/<MPN>/` should have current Mouser stock + price metadata cached alongside the CAD bundle.

**stock.json schema:**

```json
{
  "checked_at": "2026-05-03T01:15:00Z",
  "primary_variant": "TPS25751DREFR",
  "primary_reason": "highest_stock",
  "variants": [
    {
      "mpn": "TPS25751DREFR",
      "mouser_pn": "595-TPS25751DREFR",
      "stock": 3276,
      "unit_price": "$2.99",
      "package": "DREF",
      "lifecycle": "Active",
      "lead_time": "...",
      "product_url": "...",
      "datasheet_url": "..."
    }
  ],
  "mouser": {
    "mouser_pn": "...",
    "in_stock": 2995,
    "expected_dates": [{"qty": 2995, "date": "2026-09-04"}],
    "min_order": 1, "multiple": 1, "lead_time_weeks": 20,
    "lifecycle": "active",
    "price_breaks": [{"qty": 1, "unit_price_usd": 4.14}],
    "product_url": "...",
    "rohs": true,
    "datasheet_url": "..."
  }
}
```

Direct user quote: *"we need to know stuff is in stock at mouser so we can build the instapcb for the user, so you should be tracking that data too in chip-fetcher cuz it's really important data."*

## Multi-package variant tracking

When `adom-mouser search "<MPN>"` returns more than one variant of the chip, save **every variant** to `stock.json` under `variants[]` — not just the best/first one. Downstream tools (InstaPCB BOM picker, schematic-to-board flow, alternate-part suggester) need to know the user's choices, especially when packages differ.

Worked example: TPS25751 has both TPS25751DREFR (3276 @ $2.99, package: DREF) and TPS25751SRSMR (1425 @ $2.66, package: SRSM/RSM). Storing only the highest-stock variant hides that the user can pick a different package for layout reasons.

**Discovery:** any time the Mouser `components[]` array length > 1 AND the MPNs differ in suffix (different package), treat as multi-variant. If MPNs are identical (just differ in `mouser_pn`), it's the same chip from different inventory pools — collapse those.

Direct user quote: *"when you see multiple variants like that from mouser, you have to track that to let the user know the choices later downstream."*