copperhead 0.4.0 → 0.6.0

package/src/config.ts

@@ -14,6 +14,12 @@ export interface CopperheadConfig {
   budgets: Record<string, number>;
   /** Content hashes of generated docs, for init idempotency (AC-1.4). */
   generatedHashes?: Record<string, string>;
+  /**
+   * How the repo was bootstrapped. `"create"` marks a Mode A pipeline repo
+   * (fab gate requires DEVPLAN.md). Written by `copperhead create`; absent on
+   * init-only / hand-maintained repos.
+   */
+  origin?: 'create' | 'init';
 }
 
 export const CONFIG_DIR = '.copperhead';
@@ -51,6 +57,7 @@ export async function loadConfig(repoRoot: string): Promise<CopperheadConfig> {
     maxRepairCycles: raw.maxRepairCycles ?? DEFAULTS.maxRepairCycles,
     budgets: raw.budgets ?? {},
     ...(raw.generatedHashes ? { generatedHashes: raw.generatedHashes } : {}),
+    ...(raw.origin === 'create' || raw.origin === 'init' ? { origin: raw.origin } : {}),
   };
 }
 
@@ -70,18 +77,27 @@ export interface ResolvedModel {
  * Accepted values (same set for `--model`, COPPERHEAD_MODEL, and `model` in
  * .copperhead/config.json):
  *
- * - `claude`  : the Anthropic provider on its default model.
- * - `claude-*`: any Anthropic model id, passed through verbatim, e.g.
+ * - `claude-code`     : the Claude Code saved-login provider on its default
+ *                       model. Needs NO API key — it reuses the logged-in Claude
+ *                       Code CLI / CLAUDE_CODE_OAUTH_TOKEN via the Agent SDK.
+ * - `claude-code:<id>`: the same provider on a specific model id.
+ * - `claude`  : the Anthropic API provider on its default model.
+ * - `claude-*`: any Anthropic API model id, passed through verbatim, e.g.
  *               `claude-opus-4-5`. Anything starting with `claude` routes here.
+ * - `codex`   : the locally installed Codex CLI using its saved ChatGPT login.
+ * - `codex:*` : Codex CLI with an explicit model id, e.g. `codex:gpt-5.6`.
  * - `gpt-5`   : the OpenAI provider on its default model.
  * - anything else: sent to the OpenAI provider verbatim as a model id, e.g.
  *               `gpt-5-mini` or `o3`.
  *
  * Routing is prefix-based, not a fixed list (see makeProvider in agent/loop.ts),
- * so a model released after this build still works without a code change. The
- * cost is that a typo like `claud-sonnet-5` silently routes to OpenAI and fails
- * there. The chosen provider must have its key set: ANTHROPIC_API_KEY for
- * `claude*`, OPENAI_API_KEY otherwise.
+ * matched top to bottom: `claude-code`/`claude-code:<id>` is checked BEFORE the
+ * `claude*` prefix, so it is never captured by the Anthropic API route. A model
+ * released after this build still works without a code change. The cost is that
+ * a typo like `claud-sonnet-5` silently routes to OpenAI and fails there.
+ * Anthropic and direct OpenAI providers require their API keys; `codex` requires
+ * a locally installed and authenticated Codex CLI, and `claude-code` requires a
+ * Claude Code login (CLAUDE_CODE_OAUTH_TOKEN); neither needs a model API key.
  */
 export function resolveModel(flag: string | undefined, config: CopperheadConfig, env = process.env): ResolvedModel {
   if (flag) return { model: flag, source: 'flag' };
@@ -90,6 +106,6 @@ export function resolveModel(flag: string | undefined, config: CopperheadConfig,
   if (env.OPENAI_API_KEY) return { model: 'gpt-5', source: 'openai-key' };
   if (env.ANTHROPIC_API_KEY) return { model: 'claude', source: 'anthropic-key' };
   throw new Error(
-    'no model configured: pass --model, set COPPERHEAD_MODEL, set model in .copperhead/config.json, or provide OPENAI_API_KEY/ANTHROPIC_API_KEY',
+    'no model configured: pass --model codex (uses your local Codex login), set COPPERHEAD_MODEL, set model in .copperhead/config.json, or provide OPENAI_API_KEY/ANTHROPIC_API_KEY',
   );
 }

package/src/kicad/bom-export.ts

@@ -0,0 +1,321 @@
+import { parseMarkdownTables, type TableRow } from '../memory/bom-table.js';
+
+/**
+ * Supplier-format BOM export (capability supplier-bom-export). Deterministic,
+ * LLM-free, network-free: a pure transformation of BOM.md into files a supplier
+ * accepts without hand-editing. BOM.md is the sole input (design D1) — it is
+ * already drift-checked against the schematic, so exports inherit that
+ * consistency guarantee.
+ */
+
+export type Supplier = 'jlcpcb' | 'digikey' | 'mouser';
+
+export const SUPPLIERS: readonly Supplier[] = ['jlcpcb', 'digikey', 'mouser'];
+
+/** CLI defaults for the quantity flags, shared so the "ignored for jlcpcb"
+ *  note fires only when the user actually set a non-default value. */
+export const DEFAULT_BOARDS = 1;
+export const DEFAULT_SPARES = 10;
+
+export function isSupplier(s: string): s is Supplier {
+  return (SUPPLIERS as readonly string[]).includes(s);
+}
+
+export interface BomRow {
+  refdes: string;
+  value: string;
+  footprint: string;
+  /** MPN column value as written (may be a placeholder like "UNVERIFIED"). */
+  mpn: string;
+  manufacturer: string;
+  /** LCSC part number when a column carries it, else ''. */
+  lcsc: string;
+  /** True when any cell carries the standalone token UNVERIFIED. */
+  unverified: boolean;
+  /** True when the MPN column carries an orderable part number (not a placeholder). */
+  hasMpn: boolean;
+}
+
+// Header aliases → canonical field. Matched after normalizing a header cell to
+// lowercase alphanumerics, so "LCSC Part #" and "lcsc_part" both hit `lcsc`.
+const HEADER_ALIASES: Record<string, keyof Pick<BomRow, 'refdes' | 'value' | 'footprint' | 'mpn' | 'manufacturer' | 'lcsc'>> = {
+  refdes: 'refdes',
+  ref: 'refdes',
+  designator: 'refdes',
+  reference: 'refdes',
+  value: 'value',
+  comment: 'value',
+  val: 'value',
+  footprint: 'footprint',
+  package: 'footprint',
+  mpn: 'mpn',
+  manufacturerpartnumber: 'mpn',
+  mfrpartnumber: 'mpn',
+  mfrpart: 'mpn',
+  partnumber: 'mpn',
+  manufacturer: 'manufacturer',
+  mfr: 'manufacturer',
+  lcsc: 'lcsc',
+  lcscpart: 'lcsc',
+  lcscpartnumber: 'lcsc',
+};
+
+const norm = (s: string): string => s.toLowerCase().replace(/[^a-z0-9]/g, '');
+
+// MPN cells that mean "no orderable part number yet". `UNVERIFIED` is the
+// init/scaffold placeholder (src/memory/scaffold.ts writes it into the MPN
+// column for every extracted symbol); the rest are common human shorthand.
+const MPN_PLACEHOLDERS = new Set(['', 'unverified', 'tbd', 'todo', 'tbc', 'na', 'none', '-', '—', '?']);
+
+const isMpnPlaceholder = (mpn: string): boolean => MPN_PLACEHOLDERS.has(mpn.trim().toLowerCase());
+
+const UNVERIFIED_RE = /\bUNVERIFIED\b/i;
+
+/**
+ * Parse BOM.md into rows by column header, tolerating extra/reordered columns.
+ * Only the header row and data rows of the first parts table are used; a table
+ * without a recognizable Refdes header yields no rows.
+ *
+ * NOTE: the drift gate this exporter runs behind (checkDrift in
+ * ../memory/drift.ts) reads Refdes|Value|Footprint *by position*, not by header.
+ * So while this parser tolerates reordering those base columns, reordering them
+ * makes checkDrift compare the wrong cells and the export refuses with a bogus
+ * drift message. Keep the base three columns first and in order; only append.
+ */
+export function parseBom(md: string): BomRow[] {
+  const tableRows = parseMarkdownTables(md);
+  const headerIdx = tableRows.findIndex((r) => r.cells.some((c) => HEADER_ALIASES[norm(c)] === 'refdes'));
+  const header = headerIdx === -1 ? undefined : tableRows[headerIdx];
+  if (!header) return [];
+  const col: Partial<Record<keyof BomRow, number>> = {};
+  header.cells.forEach((c, i) => {
+    const field = HEADER_ALIASES[norm(c)];
+    // First occurrence wins, so a stray later column never shadows the real one.
+    if (field && col[field] === undefined) col[field] = i;
+  });
+
+  const at = (row: TableRow, field: keyof BomRow): string => {
+    const i = col[field];
+    return i === undefined ? '' : (row.cells[i] ?? '').trim();
+  };
+
+  const rows: BomRow[] = [];
+  for (const row of tableRows.slice(headerIdx + 1)) {
+    const refdes = at(row, 'refdes');
+    if (!refdes) continue; // blank line / stray row
+    const mpn = at(row, 'mpn');
+    rows.push({
+      refdes,
+      value: at(row, 'value'),
+      footprint: at(row, 'footprint'),
+      mpn,
+      manufacturer: at(row, 'manufacturer'),
+      lcsc: at(row, 'lcsc'),
+      unverified: row.cells.some((c) => UNVERIFIED_RE.test(c)),
+      hasMpn: !isMpnPlaceholder(mpn),
+    });
+  }
+  return rows;
+}
+
+/**
+ * Passive footprint classifier (design D4): the library item after the `:` in a
+ * KiCad footprint id starts with `R_`, `C_`, or `L_` for the passive classes
+ * that lose parts to handling. Bare footprint names (no library) are matched
+ * too, so `R_0603` and `Resistor_SMD:R_0603_1608Metric` both classify.
+ */
+export function isPassiveFootprint(footprint: string): boolean {
+  const item = footprint.includes(':') ? footprint.slice(footprint.lastIndexOf(':') + 1) : footprint;
+  return /^[RCL]_/.test(item.trim());
+}
+
+/**
+ * Order quantity for one BOM line (requirement "Quantity arithmetic"):
+ * `ceil(perBoardCount × boards × (1 + spares/100))`, raised to
+ * `perBoardCount × boards + 2` for passive lines when the percentage yields
+ * less — losing two 0402s to tweezers is the norm and percentage-only spares
+ * under-order low-count passive lines (design D4).
+ */
+export function orderQuantity(
+  perBoardCount: number,
+  boards: number,
+  sparesPercent: number,
+  isPassive: boolean,
+): number {
+  const base = perBoardCount * boards;
+  // `base * (100 + spares) / 100` keeps the multiply in whole units before the
+  // divide, and the epsilon absorbs IEEE-754 dust so an exact result like 110
+  // does not ceil to 111 (100 × 1.1 is 110.00000000000001 in float). The dust is
+  // ~1e-13; 1e-9 is far below any real fractional quantity, so genuine fractions
+  // (44.5 → 45) are unaffected.
+  const withSpares = Math.ceil((base * (100 + sparesPercent)) / 100 - 1e-9);
+  return isPassive ? Math.max(withSpares, base + 2) : withSpares;
+}
+
+/** Natural refdes ordering: R2 before R10, and R* before U*. */
+function naturalCompare(a: string, b: string): number {
+  const pa = a.match(/^([A-Za-z]*)(\d*)/);
+  const pb = b.match(/^([A-Za-z]*)(\d*)/);
+  const alpha = (pa?.[1] ?? '').localeCompare(pb?.[1] ?? '');
+  if (alpha !== 0) return alpha;
+  const na = pa?.[2] ? parseInt(pa[2], 10) : 0;
+  const nb = pb?.[2] ? parseInt(pb[2], 10) : 0;
+  if (na !== nb) return na - nb;
+  return a.localeCompare(b);
+}
+
+/** RFC-4180 field quoting: quote when the field holds a comma, quote, or newline. */
+function csvField(value: string): string {
+  return /[",\n\r]/.test(value) ? `"${value.replace(/"/g, '""')}"` : value;
+}
+
+const csvRow = (fields: string[]): string => fields.map(csvField).join(',');
+
+export interface ExportOptions {
+  boards: number;
+  spares: number;
+  includeUnverified: boolean;
+}
+
+export interface ExportResult {
+  /** The supplier CSV, ending in a newline. */
+  csv: string;
+  /** Rows that made it into the file, in emit order. */
+  included: BomRow[];
+  /** Rows excluded, with the reason, for the warnings footer. */
+  excluded: { row: BomRow; reason: string }[];
+  /** Human-readable warning/notice lines (stderr + --json). */
+  warnings: string[];
+}
+
+interface Line {
+  rows: BomRow[];
+  /** Representative row (first, in refdes order) for value/footprint/mpn/etc. */
+  head: BomRow;
+  designators: string[];
+}
+
+/**
+ * Split rows into included/excluded by the ordering rules (requirement
+ * "Unorderable rows are excluded and reported"): MPN-less rows are always
+ * excluded; UNVERIFIED rows are excluded unless `includeUnverified`, and even
+ * then only when they carry a real MPN.
+ */
+function partition(
+  rows: BomRow[],
+  includeUnverified: boolean,
+): { included: BomRow[]; excluded: ExportResult['excluded'] } {
+  const included: BomRow[] = [];
+  const excluded: ExportResult['excluded'] = [];
+  for (const row of rows) {
+    if (!row.hasMpn) {
+      excluded.push({ row, reason: 'no MPN' });
+    } else if (row.unverified && !includeUnverified) {
+      excluded.push({ row, reason: 'UNVERIFIED' });
+    } else {
+      included.push(row);
+    }
+  }
+  return { included, excluded };
+}
+
+function groupBy(rows: BomRow[], key: (r: BomRow) => string): Line[] {
+  const map = new Map<string, BomRow[]>();
+  for (const r of rows) {
+    const k = key(r);
+    const arr = map.get(k);
+    if (arr) arr.push(r);
+    else map.set(k, [r]);
+  }
+  const lines: Line[] = [];
+  for (const groupRows of map.values()) {
+    const sorted = [...groupRows].sort((a, b) => naturalCompare(a.refdes, b.refdes));
+    // Groups are never empty (a key exists because a row produced it).
+    lines.push({ rows: sorted, head: sorted[0]!, designators: sorted.map((r) => r.refdes) });
+  }
+  // Deterministic line order: by the first designator of each line.
+  return lines.sort((a, b) => naturalCompare(a.designators[0]!, b.designators[0]!));
+}
+
+function buildWarnings(
+  supplier: Supplier,
+  included: BomRow[],
+  excluded: ExportResult['excluded'],
+  opts: ExportOptions,
+): string[] {
+  const { includeUnverified } = opts;
+  const warnings: string[] = [];
+  for (const { row, reason } of excluded) {
+    const hint =
+      reason === 'no MPN'
+        ? 'add an MPN in BOM.md — unorderable without one'
+        : 'verify against the datasheet or re-run with --include-unverified';
+    warnings.push(`EXCLUDED (${reason}): ${row.refdes} (${row.value || 'no value'}) — ${hint}`);
+  }
+  if (includeUnverified) {
+    for (const row of included) {
+      if (row.unverified) {
+        warnings.push(`INCLUDED but UNVERIFIED (--include-unverified): ${row.refdes} (${row.mpn}) — confirm before ordering`);
+      }
+    }
+  }
+  if (supplier === 'jlcpcb') {
+    // The JLCPCB assembly format has no quantity column — quantity is set from
+    // the board count entered at upload — so --boards/--spares never reach this
+    // file. Say so when the user supplied a non-default value, or they may order
+    // the wrong count expecting the flags to have taken effect.
+    if (opts.boards !== DEFAULT_BOARDS || opts.spares !== DEFAULT_SPARES) {
+      warnings.push(
+        'NOTE: --boards/--spares are ignored for jlcpcb — quantity is set from the board count you enter at JLCPCB upload',
+      );
+    }
+    const blank = included.filter((r) => !r.lcsc).map((r) => r.refdes);
+    if (blank.length) {
+      warnings.push(
+        `NOTE: no LCSC part # for ${blank.join(', ')} — JLCPCB accepts the upload but needs manual matching for these`,
+      );
+    }
+  }
+  return warnings;
+}
+
+function emitJlcpcb(lines: Line[]): string {
+  // JLCPCB assembly-service BOM: one line per Comment+Footprint+LCSC, designators
+  // grouped. Quantity is derived by JLCPCB from the designator count × the board
+  // count entered at upload, so there is no quantity column here (design/proposal).
+  const header = 'Comment,Designator,Footprint,LCSC Part #';
+  const body = lines.map((l) =>
+    csvRow([l.head.value, l.designators.join(','), l.head.footprint, l.head.lcsc]),
+  );
+  return [header, ...body].join('\n') + '\n';
+}
+
+function emitCart(lines: Line[], opts: ExportOptions, mpnHeader: string): string {
+  // DigiKey / Mouser cart upload: one line per MPN with a computed order
+  // quantity and the designators as the customer reference.
+  const header = `${mpnHeader},Manufacturer,Quantity,Customer Reference`;
+  const body = lines.map((l) => {
+    const qty = orderQuantity(l.designators.length, opts.boards, opts.spares, isPassiveFootprint(l.head.footprint));
+    return csvRow([l.head.mpn, l.head.manufacturer, String(qty), l.designators.join(',')]);
+  });
+  return [header, ...body].join('\n') + '\n';
+}
+
+/**
+ * Build the supplier CSV plus its warnings from parsed BOM rows. Pure: no I/O,
+ * so the emitters are golden-file testable in isolation (design D5).
+ */
+export function buildExport(rows: BomRow[], supplier: Supplier, opts: ExportOptions): ExportResult {
+  const { included, excluded } = partition(rows, opts.includeUnverified);
+  const lines =
+    supplier === 'jlcpcb'
+      ? groupBy(included, (r) => `${r.value}${r.footprint}${r.lcsc}`)
+      : groupBy(included, (r) => r.mpn);
+
+  let csv: string;
+  if (supplier === 'jlcpcb') csv = emitJlcpcb(lines);
+  else if (supplier === 'digikey') csv = emitCart(lines, opts, 'Manufacturer Part Number');
+  else csv = emitCart(lines, opts, 'Mfr. Part Number');
+
+  return { csv, included, excluded, warnings: buildWarnings(supplier, included, excluded, opts) };
+}

package/src/kicad/fab.ts

@@ -0,0 +1,121 @@
+/**
+ * Fab release gate checks (OpenSpec: add-fab-release-gate).
+ * Documentation presence is pure over file contents: LLM-free, network-free.
+ */
+
+/** Violation shape shared by the fab JSON report (`claim` / `actual` / optional location). */
+export interface FabViolation {
+  claim: string;
+  actual: string;
+  location?: string;
+}
+
+export interface FabCheckResult {
+  status: 'pass' | 'warn' | 'fail';
+  violations: FabViolation[];
+}
+
+export const DRAFT_QUALITY_HEADING = '## Draft quality';
+
+/** Config marker: repos produced by `copperhead create` set `origin` to `"create"`. */
+export const CREATE_ORIGIN = 'create';
+
+/**
+ * True when `.copperhead/config.json` marks the repo as create-produced.
+ * Accepts the raw parsed object (or a loaded config that retained `origin`).
+ */
+export function isCreateProducedRepo(config: unknown): boolean {
+  if (config === null || typeof config !== 'object') return false;
+  return (config as { origin?: unknown }).origin === CREATE_ORIGIN;
+}
+
+/**
+ * Body of `## Draft quality` through the next `##` heading, or `null` if the
+ * heading is absent. HTML comments and whitespace alone do not count as filled
+ * (init scaffolds the empty heading + a placeholder comment).
+ */
+export function draftQualitySection(layoutMd: string): string | null {
+  const lines = layoutMd.split(/\r?\n/);
+  let start = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i]!.trim() === DRAFT_QUALITY_HEADING) {
+      start = i + 1;
+      break;
+    }
+  }
+  if (start < 0) return null;
+
+  const body: string[] = [];
+  for (let i = start; i < lines.length; i++) {
+    const line = lines[i]!;
+    if (/^##\s/.test(line.trim())) break;
+    body.push(line);
+  }
+  return body.join('\n');
+}
+
+export function isFilledDraftQuality(sectionBody: string): boolean {
+  const withoutComments = sectionBody.replace(/<!--[\s\S]*?-->/g, '');
+  return withoutComments.trim().length > 0;
+}
+
+export interface DocumentationPresenceInput {
+  /** Full LAYOUT.md text, or `null` when the file is missing. */
+  layoutMd: string | null;
+  /** Whether docs/DEVPLAN.md exists on disk. */
+  devplanExists: boolean;
+  /** From {@link isCreateProducedRepo}; only create repos require DEVPLAN.md. */
+  isCreateRepo: boolean;
+  /** Docs directory name used in violation locations (default `docs`). */
+  docsDir?: string;
+}
+
+/**
+ * Documentation-presence check for `check --fab` (task 1.5):
+ * - LAYOUT.md must have a filled `## Draft quality` section
+ * - create-produced repos must also have DEVPLAN.md
+ *
+ * Failures use the drift-report voice: file as location, claim `"release-ready"`.
+ */
+export function checkDocumentationPresence(input: DocumentationPresenceInput): FabCheckResult {
+  const docs = (input.docsDir ?? 'docs').replace(/[/\\]+$/, '');
+  const violations: FabViolation[] = [];
+  const layoutLoc = `${docs}/LAYOUT.md`;
+  const claim = 'release-ready';
+
+  if (input.layoutMd === null) {
+    violations.push({
+      claim,
+      actual: 'LAYOUT.md missing',
+      location: layoutLoc,
+    });
+  } else {
+    const section = draftQualitySection(input.layoutMd);
+    if (section === null) {
+      violations.push({
+        claim,
+        actual: `missing ${DRAFT_QUALITY_HEADING} section`,
+        location: layoutLoc,
+      });
+    } else if (!isFilledDraftQuality(section)) {
+      violations.push({
+        claim,
+        actual: `${DRAFT_QUALITY_HEADING} section is empty`,
+        location: layoutLoc,
+      });
+    }
+  }
+
+  if (input.isCreateRepo && !input.devplanExists) {
+    violations.push({
+      claim,
+      actual: 'missing',
+      location: `${docs}/DEVPLAN.md`,
+    });
+  }
+
+  return {
+    status: violations.length === 0 ? 'pass' : 'fail',
+    violations,
+  };
+}

package/src/memory/bom-table.ts

@@ -0,0 +1,78 @@
+/**
+ * Shared markdown-table parsing for BOM.md and PINOUT.md (design D9's
+ * fixed-column contract). Originally lived inline in drift.ts; pulled out so
+ * the supplier BOM export work (add-supplier-bom-export) can parse BOM.md
+ * once, the same way, instead of duplicating this.
+ */
+
+export interface TableRow {
+    cells: string[];
+  }
+  
+  /**
+   * Parses every markdown pipe-table row out of a document, across however
+   * many tables the file contains, skipping separator rows (e.g. `|---|---|`).
+   * Malformed lines (stray `|` outside a real table) just become a row with
+   * whatever cells they split into — this function never throws.
+   */
+  export function parseMarkdownTables(md: string): TableRow[] {
+    const rows: TableRow[] = [];
+    for (const line of md.split('\n')) {
+      const t = line.trim();
+      if (!t.startsWith('|')) continue;
+      const cells = t
+        .split('|')
+        .slice(1, -1)
+        .map((c) => c.trim());
+      if (cells.every((c) => /^:?-+:?$/.test(c))) continue; // separator row
+      rows.push({ cells });
+    }
+    return rows;
+  }
+  
+  /** True for a table's header row. BOM.md and PINOUT.md both lead with a
+   * Refdes or Pin column, so one check covers both doc types. */
+  export const isHeader = (row: TableRow): boolean =>
+    row.cells.some((c) => /^(refdes|pin)$/i.test(c));
+  
+  /**
+   * A typed BOM.md data row, per the fixed column contract that `init` writes
+   * (Refdes | Value | Footprint | MPN | Rationale — see scaffold.ts's
+   * `bomTable`). `flags` currently only ever contains `UNVERIFIED` (the MPN
+   * column literally says so) or `MISSING_MPN` (no MPN column value at all);
+   * more may be added as the export/fab-gate work grows.
+   */
+  export interface BomRow {
+    refdes: string;
+    value?: string;
+    footprint?: string;
+    mpn?: string;
+    flags: string[];
+  }
+  
+  /**
+   * Parses BOM.md's data rows into typed rows. Rows without a refdes in
+   * column 1 are dropped rather than thrown on: a hand-edited doc with a
+   * ragged or partial table shouldn't crash `check` or `export bom`, it
+   * should just be skipped (drift/export callers report the gaps that
+   * matter through their own comparisons against the schematic).
+   */
+  export function parseBomTable(md: string): BomRow[] {
+    const rows = parseMarkdownTables(md).filter((r) => !isHeader(r));
+    const out: BomRow[] = [];
+    for (const row of rows) {
+      const [refdes, value, footprint, mpn] = row.cells;
+      if (!refdes) continue;
+      const flags: string[] = [];
+      if (mpn === 'UNVERIFIED') flags.push('UNVERIFIED');
+      else if (!mpn) flags.push('MISSING_MPN');
+      out.push({
+        refdes,
+        value: value || undefined,
+        footprint: footprint || undefined,
+        mpn: mpn || undefined,
+        flags,
+      });
+    }
+    return out;
+  }

package/src/memory/drift.ts

@@ -2,6 +2,7 @@ import { readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { listSymbols, pinNets, type SchematicSymbol } from '../kicad/sexp.js';
+import { parseMarkdownTables, isHeader } from './bom-table.js';
 
 /**
  * Doc-vs-schematic drift check (AC-2.3). BOM.md and PINOUT.md use fixed table
@@ -13,28 +14,6 @@ export interface DriftMismatch {
   actual: string;
 }
 
-export interface TableRow {
-  cells: string[];
-}
-
-export function parseMarkdownTables(md: string): TableRow[] {
-  const rows: TableRow[] = [];
-  for (const line of md.split('\n')) {
-    const t = line.trim();
-    if (!t.startsWith('|')) continue;
-    const cells = t
-      .split('|')
-      .slice(1, -1)
-      .map((c) => c.trim());
-    if (cells.every((c) => /^:?-+:?$/.test(c))) continue; // separator row
-    rows.push({ cells });
-  }
-  return rows;
-}
-
-const isHeader = (row: TableRow): boolean =>
-  row.cells.some((c) => /^(refdes|pin)$/i.test(c));
-
 /**
  * The zero-symbol carve-out in checkDrift is right for the create pipeline,
  * but it would let `check` silently pass an established repo whose schematic

package/src/memory/scaffold.ts

@@ -113,7 +113,8 @@ Generated by \`copperhead init\`; regenerated on re-runs (do not hand-edit).
 
 - \`schematic\` / \`board\`: repo-relative paths to the KiCad files copperhead operates on (currently: ${config.schematic ?? 'none'} / ${config.board ?? 'none'})
 - \`docs\`: design docs directory (docs-as-memory), default \`docs/\`
-- \`model\`: default model (\`gpt-5\` or \`claude\`); overridden by \`--model\` and \`COPPERHEAD_MODEL\`
+- \`model\`: default provider/model (\`codex\`, \`gpt-5\`, or \`claude\`); overridden by \`--model\` and \`COPPERHEAD_MODEL\`
+- local Codex uses the saved \`codex login\`; set \`COPPERHEAD_CODEX_PATH\` only when the executable is not on \`PATH\`
 - \`maxTurns\`: agent loop turn budget per run (default 40)
 - \`maxRepairCycles\`: ERC/DRC repair attempts before rollback (default 5)
 - \`budgets\`: free-form hard constraints (e.g. \`"sleep_current_uA": 25\`); surfaced verbatim into every run's system prompt