GET /api/v1/pages/<slug>/files/page.json     # is it type:"component"? component.mpn, org
GET /api/v1/discover?triggers=<MPN>          # discovery hits (LOOSE — see gotchas)
GET /api/v1/search?q=<MPN>                    # full-text (throws on hyphens — strip them)
GET /api/v1/pages/<slug>/files               # { "files":[ {"path","type":"blob|tree"} ] }
GET /api/v1/pages/<slug>/files/<path>        # raw file bytes

---
name: wiki-bundle-reuse
description: Reuse an already-published Adom Wiki component bundle as a part-source BEFORE re-fetching from external vendors. The wiki (wiki.adom.inc) hosts `component` pages whose git repo carries a complete, Adom-vetted CAD bundle (<mpn>.kicad_sym/.kicad_mod, STEP/GLB, datasheet PDF, 3D-outline SVGs). If the part is already there, pull that bundle — it's free, fast, and guarantees Adom-consistent geometry + provenance. Trigger words — wiki part source, reuse published bundle, adom-wiki source, component page reuse, query the wiki first, wiki.adom.inc bundle, pull from wiki, wiki cad cache.
---

# Reusing published wiki component bundles as a part-source

The Adom Wiki is the **first** step on chip-fetcher's sourcing ladder — ahead of
manufacturer / SnapMagic / Mouser / DigiKey / Arrow / CSE-UL / LCSC. If a part is
already published as a `component` page with a CAD bundle, reuse it instead of
scraping vendors again. Reference implementation: `chip-fetcher/src/sources/wiki.rs`
(+ `Source::AdomWiki` first in `src/sourcing.rs`). Reads only — the public read
API needs no token.

## The API (read-only, public)

```
GET /api/v1/pages/<slug>/files/page.json     # is it type:"component"? component.mpn, org
GET /api/v1/discover?triggers=<MPN>          # discovery hits (LOOSE — see gotchas)
GET /api/v1/search?q=<MPN>                    # full-text (throws on hyphens — strip them)
GET /api/v1/pages/<slug>/files               # { "files":[ {"path","type":"blob|tree"} ] }
GET /api/v1/pages/<slug>/files/<path>        # raw file bytes
```

No HTTP crate in chip-fetcher — shell `curl -fsSL --max-time N` (matches the
dependency-free, shell-a-sibling-binary style of the rest of the CLI).

## The gotchas (every one learned the hard way)

1. **`search` (FTS) throws on hyphens.** Never send a raw hyphenated MPN — strip
   hyphens for the query. Prefer the exact-slug and `discover` paths; `search` is
   the fallback.
2. **`discover`/`search` return LOOSE matches.** A nonsense MPN and `ADS1115`
   both "matched" `b2b-zr` before this was fixed — the API happily returns a
   popular/related page. **You MUST verify** the candidate's
   `component.mpn` (normalized) equals the requested MPN. Without that check the
   feature reuses the wrong part's bundle.
3. **`component.mpn` can be malformed.** Some pages glue a description onto it
   (`"BQ7692003PWR — BQ76920 3–5 Cell …"`), so its normalized form won't match.
   **Also accept a slug match** (`norm(slug) == norm(mpn)`) — the slug is the
   page's clean identity.
   - Normalize for all comparisons: lowercase + drop non-alphanumerics
     (`B2B-ZR` → `b2bzr`).
4. **Pull ONLY the canonical file of each type.** Pages carry variant/compare
   models — `B2B-ZR-v2.glb`, `B2B-ZR-compare.glb`, `B2B-ZR-mate.glb`. Match the
   file stem to the part (`stem == mpn`) so you grab `<mpn>.glb`, not 14 variants
   that collapse onto one canonical name. For outline SVGs, require the
   `<mpn>-3d-outline-…` prefix.
5. **Key file selection off the REQUESTED MPN, not `component.mpn`.** On-disk
   files are named after the real part number; the requested MPN is what the user
   typed and what the library dir is keyed by. (Using a malformed `component.mpn`
   as the prefix would reject the page's own files.)
6. **Files live in git (`/files`), not releases.** `/releases` is empty for these
   pages; there's no package tarball to `adompkg install`.
7. **Most component pages are metadata-only stubs.** They have `page.json` +
   `README.md` and *no* CAD files. Treat "page exists but has no core CAD"
   (`.kicad_sym`/`.kicad_mod`/`.step`) as **not a usable bundle → fall through**
   to the vendor ladder. Don't claim a wiki hit when there's nothing to pull.

## Pull + provenance

- Route core CAD + datasheet through the importer so they get magic-byte
  validation + canonical `<mpn>.<ext>` naming + a per-source variant
  (`<mpn>.adomwiki.kicad_sym`). Copy GLB/WRL/outline SVGs in directly.
- Stamp provenance `discovery_source = content_origin = "adom-wiki"` + the page
  URL on every file, plus an `adom-wiki` `fetched_via_chain` entry, so the source
  carat shows **"Adom Wiki"** (see `chip-provenance-labeling`). `source_label`
  maps `adom-wiki → "Adom Wiki"`.

## Fall-through contract

`try_fetch(mpn) -> Ok(None)` when there's no match OR only a metadata-only page,
so the caller drops straight into the existing ladder unchanged. The wiki source
ADDS a step; it never removes one.

## The reuse cache is sparse today

As of this writing, most component pages are metadata-only; only some (e.g. the
JST connectors, a few passives + ICs) carry real bundles. The value grows as full
bundles get published — so the natural companion is a **write-back**: publish a
completed bundle to the wiki after a successful vendor fetch, so the cache fills
itself. (Not built yet — flagged as the obvious next step.)