---
name: aci-provenance
description: Real-world variant provenance for any MPN — datasheet + footprint + 3D trace, distributor-truthed bare-chip candidates (no fake variants), symbol-variant sub-grouping (SPI vs I2C etc), deep 3D-model search across manufacturer + community sources, citation-aware PDF deep-links, reveal-in-VS-Code. Feeds chipfit's variant picker so users never see invented variants. Trigger words — aci provenance, real-world variants, bare-chip variants, mpn variants, datasheet citations, deep 3d search, manufacturer-direct chip, mouser variant search, jlcpcb variants, lcsc fallback, symbol variants i2c spi, fp glb equivalence class, distributor truthed variants, footprint and 3d the same different pinout.
---

# aci-provenance — real-world variant provenance for any MPN

Wraps `adom-parts-search` + the local provenance JSON + a deep
manufacturer-3D-model search + a citation-aware PDF deep-linker
into a single Hydrogen webview. The output is the
`<mpn>-variants.json` manifest that chipfit's `/3d-variants`,
`aci library`, and `aci source --bom` all read.

## Run

```bash
node server.mjs --mpn RP2040 --port 8980
```

Then open in a Hydrogen webview tab:

```
https://<container-proxy>/proxy/8980/
```

## What it solves

Chipfit's old variant picker listed STEP files from the
kicad-packages3d cache. Most of those don't correspond to any
orderable distributor SKU. User feedback 2026-04-28: *"these
variants you're showing me don't exist in the real world and I'm
sad you fooled me."*

aci-provenance is the data plumbing fix:

- Bare-chip candidates only — filter out modules / dev boards
- Search MPN-family-prefix mode (e.g. `MCP4` returns the whole
  digital-pot family across SPI + I2C variants)
- Symbol-signature sub-grouping when same fp+3D carries
  different pinout (SPI vs I2C, single vs dual)
- Boot-time URL probe so we never ship a templated link that's
  bot-blocked or 404'd

## Companion app

[adom-pdf-viewer](https://github.com/adom-inc/adom-pdf-viewer)
serves the in-page PDF viewer aci-provenance deep-links into for
every page citation. Cited pages are highlighted in the thumbnail
strip with snippet labels ("footprint pad geometry", "GLB / package
model", etc.).

## Manifest schema

Written to `project-content/schematics/footprints/<mpn>/<mpn>-variants.json`:

```jsonc
{
  "prefix": "RP2040",
  "datasheet_recommended": { "full_mpn": "...", "marking": "...", "citation": "..." },
  "variants": [
    {
      "full_mpn": "SC0914(13)",
      "manufacturer": "Raspberry Pi",
      "marking": "RP2040 (RP2B2)",      // extracted from description
      "fp_glb_equivalence_class": "RP2040",
      "symbol_signature": "MPN:RP2040",  // family rules vary per MFR
      "protocol": ["SPI", "I2C", "UART", "USB1.1"],
      "lifecycle": "unknown",
      "distributors": [{ "name": "Mouser", "sku": "358-SC091413", "stock": 104213, "price_usd": {...} }],
      "datasheet_url": "...",
      "product_url": "..."
    }
  ],
  "footprint_variants": []
}
```

Full spec: [adom-chipfit/PLAN.md Part 5](https://github.com/adom-inc/adom-chipfit/blob/main/PLAN.md).

## Sample prompts

- "Run aci-provenance for RP2040 and show me the real-world
  variants Mouser carries"
- "Show me the MCP4 family — I want to see the I2C vs SPI
  symbol-variant axis with the same fp + same 3D"
- "Open this datasheet at page 608 with all the cited pages
  highlighted in the thumbnail strip"
- "Reveal /home/adom/project/.../RP2040-3d.glb in the VS Code
  Explorer"