parts: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this repo is

A KiCad parts library that is stored as data, not code. The CSV files in database/ are the database — GitPLM reads them directly and serves them to KiCad over the HTTP libraries API:

database/g-XXX.csv  ->  gitplm http (port 7654)  ->  KiCad

There is no build step and no database to regenerate. gitplm http watches database/ and reloads on save, so a CSV edit is live in KiCad immediately — no restart, no library refresh.

The older CSV -> SQLite3 -> ODBC -> KiCad path (parts_db_create in envsetup.sh, database/#gplm.kicad_dbl, database/parts.sqlite) is obsolete and kept only for anyone who has not migrated. parts.sqlite is generated and gitignored. Do not rebuild it unless the user says they are still on that path.

The category triad

A part's three-letter category code (RES, ICS, DIO, ...) names three files at once, and keeping them aligned is the point of the scheme:

Concern	Path
Data	database/g-XXX.csv
Symbols	symbols/g-XXX.kicad_sym
Footprints	footprints/g-XXX.pretty/

Adding a category means adding a database/g-XXX.csv; gitplm http discovers it on the next reload. There is no library list to register it in.

Column sets differ per category and are not in a consistent order — always head -1 the file before writing a row. A few categories (ASY, CBL, ENC, FAN, FST) are BOM-only and have no Symbol/Footprint columns.

IPNs are CCC-NNNN-VVVV and are the database key. partnumbers.md is the full specification.

Commands

# Validate a CSV: IPN format and sort order, duplicate IPNs, whether
# Symbol/Footprint references resolve against the installed KiCad libraries,
# field padding, datasheet links, spelling drift, and whether a variation code
# agrees with the value column. Run from the repo root.
scripts/check-csv.py --new-only database/g-reg.csv

# Pass the whole database to add the checks that need every file at once:
# one spelling per manufacturer, and no MPN carried by two live parts.
scripts/check-csv.py --new-only database/g-*.csv

# Check every resistor in a KiCad schematic against g-res.csv and repoint any
# IPN that disagrees with the resistance the symbol carries. Reports by
# default; --write applies. Accepts files or directories.
scripts/update-design-ipns.py path/to/design.kicad_sch

# Serve the database to KiCad; watches database/ and reloads on save.
gitplm http

# Markdown formatting (prettier pinned by .prettier-version)
. envsetup.sh && parts_format          # write
. envsetup.sh && parts_format_check    # check only