bom

What this skill does

# BOM Management

BOM data lives in **KiCad schematic symbol properties** as the single source of truth. This skill orchestrates the full lifecycle: analyze the schematic, search distributors, validate parts, write properties back, export tracking CSVs, and generate order files.

## Related Skills

| Skill | Purpose |
|-------|---------|
| `kicad` | Read/analyze schematics, PCB, footprints |
| `digikey` | Search DigiKey, download datasheets (primary prototype source) |
| `mouser` | Search Mouser (secondary prototype source) |
| `lcsc` | Search LCSC (production/JLCPCB parts) |
| `element14` | Search Newark/Farnell/element14 (international) |
| `jlcpcb` | PCB fabrication & assembly ordering |
| `pcbway` | Alternative PCB fab & assembly |

## Scripts

Use `<skill-path>` to reference the BOM skill directory.

```bash
# Analyze schematic (JSON output, recursive sub-sheets)
python3 <skill-path>/scripts/bom_manager.py analyze path/to/schematic.kicad_sch --json --recursive

# Export BOM tracking CSV (creates new or merges with existing)
python3 <skill-path>/scripts/bom_manager.py export path/to/schematic.kicad_sch -o bom/bom.csv --recursive

# Generate per-distributor order files (5 boards + 2 spares/line)
python3 <skill-path>/scripts/bom_manager.py order bom/bom.csv --boards 5 --spares 2

# Quick single-distributor order (bypasses Chosen_Distributor column)
python3 <skill-path>/scripts/bom_manager.py order bom/bom.csv --distributor digikey

# Write properties to schematic (dry-run first, then apply)
echo '{"R1": {"MPN": "RC0805FR-0710KL", "Manufacturer": "Yageo"}}' \
  | python3 <skill-path>/scripts/edit_properties.py path/to/schematic.kicad_sch --dry-run

# Sync datasheet URLs from manifest.json back into schematic Datasheet properties
python3 <skill-path>/scripts/sync_datasheet_urls.py path/to/schematic.kicad_sch --recursive --dry-run
```

## Workflow

Skip steps that don't apply. Common shortcuts:
- **"Add Mouser PNs"** — search Mouser by MPN for each part → validate → write to schematic → update CSV
- **"Fill in the gaps"** — run analyzer with `--gaps-only`, address each missing field
- **"Update datasheet URLs"** — run `sync_datasheet_urls.py` to backfill empty Datasheet fields from the datasheets manifest
- **"Prepare for production"** — ensure every part has an LCSC number, check stock, set Chosen_Distributor to LCSC

### Step 1: Understand the Project

```bash
python3 <skill-path>/scripts/bom_manager.py analyze path/to/schematic.kicad_sch --json --recursive
```

The output tells you the project's field naming convention, which distributors are populated, what's missing, and the preferred distributor. Also look for an existing BOM tracking CSV in the project directory or `bom/` folder.

The script covers common patterns, but some projects use internal key systems or parametric fields. See `references/part-number-conventions.md` for the full catalog. Read the schematic if something seems off.

### Step 2: Sync Datasheets

**Do this immediately.** Datasheets are essential context for validation and part selection. Run the preferred distributor's sync first; if some fail, try others — they share the same `datasheets/` directory and skip already-downloaded parts.

```bash
python3 <digikey-skill-path>/scripts/sync_datasheets_digikey.py path/to/schematic.kicad_sch --recursive
python3 <lcsc-skill-path>/scripts/sync_datasheets_lcsc.py path/to/schematic.kicad_sch --recursive
python3 <element14-skill-path>/scripts/sync_datasheets_element14.py path/to/schematic.kicad_sch --recursive
```

DigiKey is best (direct PDF URLs). element14 is reliable (no bot protection). LCSC works for LCSC-only parts. Mouser is a last resort (often blocks downloads).

**Tell the user where datasheets are** (e.g., `hardware/<project>/datasheets/`). They'll reference them often.

**Cross-revision projects:** Use a single shared datasheets directory at the project level rather than per-revision. The same MPN's datasheet doesn't change between revisions.

Re-sync after writing new MPNs (Step 5) — the scripts are idempotent. Then backfill Datasheet URLs into the schematic:

```bash
python3 <skill-path>/scripts/sync_datasheet_urls.py path/to/schematic.kicad_sch --recursive
```

This reads `datasheets/manifest.json` (legacy name `index.json` still supported) and writes discovered datasheet URLs into empty schematic `Datasheet` properties. Opportunistic — only fills blanks. If a schematic already has a different URL, it warns about the mismatch without overwriting (use `--overwrite` to replace). Run with `--dry-run` first to preview.

### Step 3: Gather Part Information

**Watch for comma-separated MPNs.** Some symbols track multiple physical parts (e.g., battery holder + clip). Split on commas and search each MPN independently — searching the combined string matches the wrong product.

Search strategy based on what's available:
- Has MPN → search distributors by MPN to get their PNs and stock
- Has distributor PN but no MPN → search that distributor, get MPN, then search others
- Has only Value + Footprint → search by description (e.g., "100nF 0402 X7R 16V")

Use the project's preferred distributor first, then alternates. Prototype: DigiKey primary, Mouser secondary. Production: LCSC.

### Step 4: Validate Matches

**Don't assume existing PNs are correct** — distributor PNs go stale (discontinued, renumbered). Verify existing PNs resolve against the API. If a PN returns 404, flag it for replacement.

For every match, verify:
1. **Package** matches the schematic footprint (see cross-reference table below)
2. **Specs** match (capacitance, resistance, voltage, tolerance)
3. **Description** makes sense (a resistor ref should get a resistor)
4. **Lifecycle** — not obsolete or EOL
5. **Datasheet URL** is a direct PDF link (not a product page)

If ambiguous, ask the user. A wrong part is worse than a missing part.

### Step 5: Update the Schematic

**KiCad coexistence.** The script detects KiCad's lock file and warns but proceeds. KiCad doesn't auto-detect external changes — it keeps its in-memory copy. If KiCad is open, tell the user: *"Close and reopen the schematic (File → Open Recent) to see the changes. Don't save from KiCad first."*

If unsaved KiCad work exists, ask them to save first (Ctrl+S), then run the script, then reopen.

```bash
echo '{"R1": {"MPN": "RC0805FR-0710KL", "Manufacturer": "Yageo", "DigiKey": "311-10.0KCRCT-ND"}}' \
  | python3 <skill-path>/scripts/edit_properties.py path/to/schematic.kicad_sch
```

**Backups:** By default, no `.bak` file is created (git tracks changes). Pass `--backup` if the schematic is not in a git repo or has uncommitted changes the user wants to preserve.

**Respect the project's convention.** Write to `"Digi-Key_PN"` if that's what exists, not `"DigiKey"`. Use canonical names only for new projects.

**Always write Manufacturer alongside MPN** — every API returns it, it's free data.

### Step 6: Update the BOM Tracking CSV

```bash
python3 <skill-path>/scripts/bom_manager.py export path/to/schematic.kicad_sch -o bom/bom.csv --recursive
```

CSV columns are dynamic — only distributors the project uses get columns. Base columns: Reference, Qty, Value, Footprint, MPN, Manufacturer. Each active distributor gets a PN column + stock column. Tail columns: Chosen_Distributor, Datasheet, Validated, DNP, Notes.

The **Notes** column is seeded from schematic `BOM Comments` properties (or aliases like `Notes`, `Remarks`, `Ordering Notes`, etc.) on first export. On re-export, user edits in the CSV take priority — existing Notes values are preserved and schematic-sourced comments won't overwrite them.

**Merge behavior:** Re-exporting preserves user-managed columns (stock, Chosen_Distributor, Validated, Notes) while updating schematic-derived columns.

### Step 7: Check Stock

For each part with a distributor PN, query current stock via the corresponding distributor skill. Update stock columns in the CSV. Stock data goes stale — note the date and re-check befo