altium_bom '{"projectPath":"C:\\proj\\board.PrjPcb","boards":10}'

altium-bom read  --project 'C:\proj\board.PrjPcb' --boards 10 --target <box>   # altium_bom -> bom.json
altium-bom price bom.json                                  # price.md, price.csv, suggestions.json
altium-bom fill  bom.json --suggestions bom-price/suggestions.json            # dry run
altium-bom fill  bom.json --suggestions bom-price/suggestions.json --apply    # write onto the sheets

altium_sheet_params '{"projectPath":"C:\\proj\\board.PrjPcb","designators":["R1","R2"],
                      "params":{"MPN":"RC0402FR-0710KL","Manufacturer":"YAGEO","Mouser Part #":"603-RC0402FR-0710KL"}}'

---
name: altium-bom
description: >-
  The Altium bill of materials an AI can work with: altium_bom reads every schematic sheet of a
  project (device sheets included) with its parts' parameters, merges the board's placement and a
  variant, groups one line per manufacturer part number, checks what an order needs (missing MPNs and
  distributor numbers, a part number on two footprints, board-only or sheet-only parts, DNP), and
  writes bom.csv, a JLCPCB BOM + CPL, and Mouser and DigiKey BOM-upload files. altium-bom (container
  CLI) prices it with adom-parts-search (stock, price, lifecycle, JLCPCB-only parts) and writes the
  missing distributor numbers back onto the sheets with altium_sheet_params. Use when asked for an
  Altium BOM, to price or source an Altium board, to export for JLCPCB, Mouser or DigiKey, or to fill
  in part numbers. Trigger words: altium bom, bill of materials, price the bom, source the parts,
  jlcpcb bom, cpl, pick and place, mouser bom, digikey bom, missing part numbers, altium_bom,
  altium_sheet_params, altium-bom.
---

Parent skill: **altium-bridge**

# altium-bom

Altium's own BOM is an OutJob and an ActiveBOM document built for a person clicking through a grid.
These verbs give an AI the same project data as JSON, with the checks and files an order needs.

## Read the BOM

```bash
altium_bom '{"projectPath":"C:\\proj\\board.PrjPcb","boards":10}'
```

- Reads every `.SchDoc` the `.PrjPcb` lists, `[DeviceSheetN]` managed sheets included, then the board's
  placement (footprint, position from the board origin, rotation, side). A 46-sheet, 1046-part board
  takes about 20 s.
- `variant: "<description>"`: the variant's Not Fitted parts become DNP and its alternate parts are listed
  (`alternates[]`). DNP also comes from a `DNP` / `Do Not Populate` parameter or `Fitted=false`.
- One line per manufacturer part number (else per value + footprint), designators in natural order.
- Parameter names are matched across libraries: `MPN` = `Manufacturer Part Number` = `PartNumber` =
  `Mfr Part #`; `Mouser Part #`, `DigiKey Part #` / `Digi-Key Part Number`, `LCSC Part #` / `JLCPCB
  Part #`. Only those values are read from the parts (some libraries carry huge blob parameters).
- Graphical, Net Tie (no BOM) and Standard (no BOM) parts stay out (`checks.excludedKinds`).
- Each line says where its parts come from (`sourceLibrary`, `managed` for workspace and vault parts).

**checks**: `missingMpn`, `missingManufacturer`, `missingPartNumbers{mouser, digikey, lcsc}`,
`inconsistent` (one part number on two footprints, or two distributor numbers), `dnp`,
`excludedKinds`, `boardNotOnSheet` (placed on the board only: test pads, fiducials, mounting holes, and
the copies of a repeated multi-channel sheet), `sheetNotOnBoard` (not placed yet).

**files** (default `<project folder>\BOM\`, or `outputDir`; `write:false` for none):

| File | For |
|---|---|
| `bom.csv` | everything per line: quantity, designators, value, footprint, MPN, manufacturer, distributor numbers |
| `bom-jlcpcb.csv` + `cpl-jlcpcb.csv` | JLCPCB assembly (their column names; mm, Top/Bottom). Check rotations on JLCPCB's preview |
| `bom-mouser.csv`, `bom-digikey.csv` | the Mouser BOM Tool and DigiKey BOM Manager uploads, quantities times `boards` |
| `bom.json` | the reply's lines and checks |

## Price and fill from the container

`adom-wiki pkg install adom/altium-bridge` installs the `altium-bom` command.

```bash
altium-bom read  --project 'C:\proj\board.PrjPcb' --boards 10 --target <box>   # altium_bom -> bom.json
altium-bom price bom.json                                  # price.md, price.csv, suggestions.json
altium-bom fill  bom.json --suggestions bom-price/suggestions.json            # dry run
altium-bom fill  bom.json --suggestions bom-price/suggestions.json --apply    # write onto the sheets
```

- `price` makes ONE `adom-parts-search` call per line (Mouser, DigiKey and JLCPCB together). That spends a
  shared daily quota: price a BOM once, not in a loop.
- Flags per line: `NO_MPN`, `NOT_FOUND`, `NO_STOCK`, `LOW_STOCK` (less than the boards need),
  `JLCPCB_ONLY` (in stock for JLCPCB assembly, not at Mouser or DigiKey), `LIFECYCLE_<VENDOR>` (NRND,
  obsolete), `PN_DIFFERS_<VENDOR>` (the BOM's number is not the one the vendor lists for the MPN, often
  the reel/cut-tape twin).
- `fill` writes the distributor numbers a line lacks. It replaces a differing one only with `--replace`.

## Write parameters onto the sheets

```bash
altium_sheet_params '{"projectPath":"C:\\proj\\board.PrjPcb","designators":["R1","R2"],
                      "params":{"MPN":"RC0402FR-0710KL","Manufacturer":"YAGEO","Mouser Part #":"603-RC0402FR-0710KL"}}'
```

Each designator is found on whichever sheet holds it; a missing parameter is added hidden; each touched
sheet is saved (`save:false` to leave it). The placed parts change, not the library (`altium_set_params`
changes a library part). The board picks the parameters up with Design > Update PCB Document.

## Limits

- A repeated (multi-channel) sheet is read once: its copies' designators show in `boardNotOnSheet`.
- A workspace-managed part's description is not read from its vault (that call hung on Altium's example
  content); a `Description` parameter is used when the part has one.
- Variant support follows the documented `.PrjPcb` format; no example project with variants was at hand.
- `adom-parts-search` has no JLCPCB price; JLCPCB-only lines are not in the priced total.