Akcli parts sourcing

akcli-parts-sourcing — driving akcli jlc for JLCPCB/LCSC search and BOM hygiene

akcli jlc searches the JLCPCB / LCSC catalog (via the public jlcsearch service). It is the only networked akcli feature — every other command runs fully offline. For plain schematic read/analyze/draw mechanics (formats, op-list rules, exit-code legend, config discovery), see the akcli-circuit-design skill; this skill covers only the sourcing loop.

Core sourcing principles (follow these)

• Prefer Basic (B) parts, then Preferred (P). Extended parts add per-reel assembly fees at JLCPCB. Surface the stock count with every recommendation — a perfect part with 0 stock is not sourced.
• Compare at the build quantity. The --json output carries the full price_tiers ladder; the headline price is the lowest-qFrom tier only.
• Check assemblability before falling in love with a package. JLCPCB's PCBA line has hard minimums (0402/0201, BGA pitch, pin pitch) — see the akcli-jlcpcb-capabilities skill.
• The schematic is authoritative. Record every sourcing decision on the schematic (an LCSC parameter per designator), never only in a side document.
• A downloaded datasheet can become audited facts — after jlc datasheet fetches the PDF, the akcli-datasheet-facts skill extracts its numbers into datasheets/extracted/ (sha256+page pinned) so akcli review analyze upgrades findings to datasheet_backed. Source → PDF → facts is one chain.
• Read the datasheet before committing a part — electrical characteristics, absolute maximum ratings and the typical application circuit come from the PDF, not from memory (step 4 below).
• Never manually sed the fp-lib-table or a symbol's Footprint field. Run akcli library audit <project> to find FOOTPRINT_LIB_UNREGISTERED, then fix it with akcli library repair <project> --rename-footprint-lib OLD=NEW --apply — hand edits drift out of sync with the schematic and the 3D models.

Workflow

(1) Search — find candidate parts

akcli jlc search NE555                     # keyword search (default 20 results)
akcli jlc search NE555 --limit 5
akcli jlc search "0603 100nF" --json       # machine-readable part objects
akcli jlc search "0402 47K" --category Resistors   # drop NTC thermistors etc.
akcli jlc show C7593                       # one part by LCSC C-number (bare 7593 also works)
akcli jlc show C2040 --easyeda             # + 3D/STEP availability, EasyEDA manufacturer/MPN/package

The query matches MPN, category, and C-number. Read the category column before picking a part: a value/package query (0402 47K) mixes NTC thermistors (Sensors) in with chip resistors — pass --category Resistors (case-insensitive exact match, client-side filter) when the query is by value/package. Text output is a table (LCSC MPN PACKAGE STOCK PRICE B DESCRIPTION) where the B column is B for a JLCPCB Basic part, P for Preferred, - otherwise. --json part fields: lcsc, mpn, package, stock, price (lowest-qFrom tier as a float, or null), basic, datasheet, category, and attributes (with subcategory, is_preferred, and the full price_tiers [{qFrom,qTo,price},...] ladder). Compare candidates on stock, price tier at the build quantity, and Basic status — not just the first hit.

No results is exit 0 with a stderr notice; network/HTTP failures exit 7 with one ERROR: NETWORK: ... line. --easyeda is best-effort: on failure it prints (metadata unavailable) and never breaks the command.

(2) Convert — turn a C-number into a KiCad library

akcli jlc add C2040                                   # symbol + footprint
akcli jlc add C2040 --3d                              # + 3D STEP model
akcli jlc add C2040 --out ./mylib --lib-name akcli --force
akcli jlc add C2040 --footprint-lib proj_jlc --3d-path relative

--footprint-lib NICKNAME sets the fp-lib-table nickname written into the symbol's Footprint field (and the footprint output directory) — the default hardcoded footprint is the #1 cause of "KiCad can't find footprint"; set it to the nickname your project's fp-lib-table actually registers. --3d-path {relative|absolute|'${VAR}'} is a portability trade-off: relative (default) only resolves next to the library, absolute always resolves on this machine but breaks on another, and a ${VAR} prefix resolves portably via a KiCad path variable.

Conversion runs in-process (vendored MIT JLC2KiCadLib core — no external binary). Without --out, output lands under config [paths] parts_dir (fallback ./akcli-parts/<C-number>/). Output layout: symbol/<lib-name>.kicad_sym, footprint/<name>.kicad_mod, footprint/packages3d/<name>.step (with --3d). Exit codes: 0 success, 2 bad usage, 4 part has no EasyEDA CAD data, 6 conversion failed/empty, 7 network error.

A converted library is a claim, not a fact. Verify before wiring in:

1. Pin count vs datasheet — akcli read <out>/symbol/<lib>.kicad_sym must match the package drawing exactly; spot-check power/ground/pin-1 in --json.
2. Footprint keying — check pin-1 marking, pad numbering and courtyard against the datasheet land pattern (read the .kicad_mod or view it in KiCad).

(3) Place and close the BOM loop

--place emits a one-op place_component op-list (place.json) with lib_id read from the produced .kicad_sym — never guessed from filenames — and prints the ready draw command including the --symbols flag it needs. Pass --symbols here even though draw can fall back to the project/global sym-lib-table: a freshly converted symbol is not registered in any table yet, so the fallback cannot find it.

akcli jlc add C2040 --out ./mylib --place --designator U1 --at 1000 1500
akcli draw board.kicad_sch --ops ./mylib/place.json --symbols ./mylib/symbol/akcli.kicad_sym          # dry-run first
akcli draw board.kicad_sch --ops ./mylib/place.json --symbols ./mylib/symbol/akcli.kicad_sym --apply
akcli check board.kicad_sch --bom              # dup designators, refdes gaps, missing value/footprint
akcli component board.kicad_sch U1             # confirm the placed part's pin -> net map

• Missing value/footprint findings: fix via a set_component_parameters op (fields: designator required; optional value, footprint, parameters) applied with akcli plan / akcli draw --apply — see the akcli-circuit-design skill for op-list mechanics.

• Match designators to sourced parts: record each designator's LCSC C-number (e.g. as an LCSC entry in the op's parameters object) so the fabrication BOM maps R10 -> C25804 unambiguously. Re-run akcli check board.kicad_sch --bom after every edit; it exits 1 while findings remain (--fail-on never for report mode).

• After any --apply, re-read (akcli read / akcli net) to confirm the write — never assume.

• Run akcli library audit <project> to cross-check sym/fp-lib-table ↔ schematic ↔ footprint ↔ 3D. Fix any FOOTPRINT_LIB_UNREGISTERED/MODEL_MISSING finding with akcli library repair <project> --rename-footprint-lib OLD=NEW --3d-path absolute --apply (leaves a .bak, then re-audits) instead of manual sed.

• No catalog symbol? Author one from the datasheet's pin table — never by hand-writing S-expressions. Transcribing a pin table is the part you do reliably; laying out coordinates is not, and that failure is silent: two pins on one connection point make KiCad join them into a single node in every placement, with no ERC violation to find (the symbol is what told ERC they are the same node). Write a schemas/symbol-pins.schema.json document — one object per pin with number, name, type (a KiCad electrical type) and side (left/right/top/bottom), optionally group to keep related pins together — and let akcli place it:

  akcli library new-symbol pins.json
  akcli library new-symbol pins.json -o MyLib.kicad_sym --apply
  akcli library lint-symbols MyLib.kicad_sym
  

  side and type are required and never guessed. The generator refuses (exit 6, nothing written) if its own output would put two differing pins on one point; stack_with is the only sanctioned way to share a coordinate, and it requires the same name and type. Run lint-symbols over any imported or vendor-converted .kicad_sym too — SYMLIB_PIN_TYPE_UNSPECIFIED is where converted symbols turn KiCad's ERC pin-conflict matrix into a rubber stamp. Multi-unit symbols are not supported yet; the refusal says so explicitly.

(4) Datasheets — resolve, fetch, read, verify

akcli jlc datasheet C2984661                  # resolve: PDF URL + MPN + manufacturer
akcli jlc datasheet C2984661 --fetch --out datasheets   # download -> ./datasheets (project-local)
akcli jlc datasheet board.kicad_sch --fetch --out datasheets  # every BOM line with an LCSC id, one run
akcli jlc datasheet board.kicad_sch --resolve-mpn --fetch --out datasheets  # MPN-only lines: catalog lookup first

• Links come from the part's EasyEDA record (szlcsc-hosted PDF; the jlcsearch mirror carries none, and lcsc.com bot-gates plain downloads). --fetch verifies the %PDF magic — an HTML challenge page is reported as fetch-failed, never saved as a broken .pdf. Existing files are the cache; --force refetches.
• Only direct .pdf links are fetched; a page-link row keeps the product/ viewer URL — fetch THAT with a browser-grade fetcher (WebFetch) to locate the PDF. no-link rows print the LCSC product-page hint. Either way the fastest fallback is the manufacturer's own site — original-vendor PDFs (vishay.com, ti.com, onsemi.com, ...) download fine with plain curl.
• Read in chunks (PDF readers cap ~20 pages/request; the tables live early): absolute maximum ratings -> recommended operating conditions -> electrical characteristics -> typical application circuit. Feed table values into akcli calc inputs (akcli-design-calc skill rule 5) and margin-check the placed circuit against the absolute-max column. Quote the table row (symbol, condition, min/typ/max) in the report so review can retrace it.
• Datasheet → SPICE model (diodes). A forward-voltage table row also feeds akcli sim fit-diode --point 0.37@20m --n-prior 1.05 (a Schottky prior), which fits a .model and can write Sim.Device/Sim.Params straight onto the part (--apply <sch> --designator D1 --write) — turning a sourced diode into a simulatable one. See docs/sim.md and the akcli-design-calc skill.
• Batch mode surfaces no-lcsc lines — pin C-numbers first with jlc bom --suggest/--fix, then re-run.
• Live dashboard BOM links: when akcli view live <sch> (path optional — it auto-discovers the single .kicad_sch in the CWD) runs its networked BOM check (?check=1), each priced line with an LCSC id gains an inline datasheet link (resolved via the same EasyEDA path as jlc datasheet; direct PDFs and page-links get distinct glyphs). It is per-line failure-tolerant and absent on the offline BOM — a fast way to eyeball coverage while reviewing the board.

When NOT to use this skill

• Parts with no LCSC listing (jlc show returns a no part ... found notice): there is no Digi-Key/Mouser/Octopart client in akcli. Source from the vendor and flag for human review.
• Controlled, long-lead, or supply-critical parts (automotive-qualified, ITAR, allocated MCUs): JLCPCB stock is a point-in-time snapshot, not a procurement commitment. Flag these for human sourcing instead of relying on stock > 0.
• Offline environments: jlc is the only networked subcommand; everything else in akcli still works. Without network, jlc search/jlc show exit 7.

Exit codes (jlc family)

0 success, including clean no-results (stderr notice) · 1 lint-style problems (jlc bom stock/id problems; jlc datasheet not-found/no-link/fetch-failed) · 2 usage error · 7 network error. Full legend and error-line format: see the akcli-circuit-design skill.