@typecad/framework-zephyr 1.0.0-alpha.13 → 1.0.0-alpha.15

package/dist/toolchain/index.js

@@ -19,24 +19,245 @@
 // ---------------------------------------------------------------------------
 import { spawnSync } from 'node:child_process';
 import { basename, dirname, join } from 'node:path';
-import { readdirSync, readFileSync, mkdirSync, rmSync } from 'node:fs';
+import { readdirSync, readFileSync, mkdirSync, rmSync, existsSync, writeFileSync } from 'node:fs';
 import { parseCompileErrors } from '@typecad/cuttlefish/api/shared';
-import { scaffoldZephyrProject, writeIfChanged } from './scaffold.js';
+import { scaffoldZephyrProject, writeIfChanged, appendLibraryOverlayFragments } from './scaffold.js';
+import { parseZephyrDts, asBuiltJson } from '../as-built.js';
 import { westSpawn, buildEnv } from './west-spawn.js';
 import { discoverWest } from './west-discover.js';
 import { writeDebugConfig, resolveDebugLocations } from './debug-config.js';
+import { bossacTouchReset } from './bossac-touch.js';
 import { ZephyrStrategy } from '../strategy.js';
 import { generateOverlay } from '../dt-config/overlay.js';
-import { chipForTarget } from '../chips/index.js';
+import { generateCustomBoard } from '../dt-config/custom-board.js';
+import { NO_BOARD_CHIP } from '../chips/index.js';
+import { resolveChipFromBoard } from '../chips/resolve.js';
+import { pwmDtAliasToken } from '../lowering/pwm.js';
 import { detectZephyrVersion, checkZephyrCompat, resolveBoardTarget } from './compat.js';
 import { DEFAULT_ZEPHYR_DISPLAY_PROFILE } from '../display/profiles.js';
-/** Default board target — the framework's MVP canonical board. */
-const DEFAULT_BOARD = 'xiao_ble';
+/**
+ * Resolve the chip for a build the same way the strategy does at emit time —
+ * from the board constants the transpile persisted next to the emitted
+ * source (`board-constants.json`). There is no registry fallback: a build
+ * whose constants did not persist stays NO_BOARD_CHIP, exactly like the
+ * emit-time path.
+ */
+function chipForBuild(projectRoot, board) {
+    try {
+        // The transpile writes the constants into the emit outDir, which is
+        // <projectRoot>/src for the standard layout (basename 'src' collapsed by
+        // projectRootFromOptions); check both locations.
+        const bcPath = [join(projectRoot, 'src', 'board-constants.json'), join(projectRoot, 'board-constants.json')]
+            .find(p => existsSync(p));
+        if (bcPath) {
+            const raw = JSON.parse(readFileSync(bcPath, 'utf8'));
+            const bc = new Map(Object.entries(raw));
+            const fromBoard = resolveChipFromBoard(bc);
+            if (fromBoard)
+                return fromBoard;
+        }
+    }
+    catch { /* constants unreadable — no board resolved */ }
+    return NO_BOARD_CHIP;
+}
+/**
+ * HAL pins the emitted sources read via adc.* — scanned from the emitted
+ * `__tc_adc<N>_setup()` call sites (N = channel index, mapped back to the HAL
+ * pin via the chip descriptor). Feeds the overlay's ADC pinctrl rewrite: on
+ * SoCs that mux ADC pads via pinctrl (STM32), only the read channels are
+ * switched to analog mode.
+ */
+function scanAdcReadPins(src, chip) {
+    const pins = [];
+    // Two used-signal forms:
+    //  - `__tc_adc<N>_setup()` / `__tc_adc_<ctrl>_<N>_setup()` CALL SITES
+    //    (empty parens — the adcInitLines definitions have `(void)` and would
+    //    otherwise mark every descriptor channel as used).
+    //  - `__tc_adct<pin>_done` lazy-guard vars — the thin-ADC read lowering's
+    //    inline setup (families without pinctrl groups, e.g. ESP32 SARADC,
+    //    never emit the setup-function form at all).
+    // Channel indices are unique per CONTROLLER, so the labeled form resolves
+    // (controller, channel) before mapping back to the HAL pin.
+    for (const m of src.matchAll(/__tc_adc(?:(\w+?)_)?(\d+)_setup\(\)/g)) {
+        const ch = Number(m[2]);
+        const label = m[1];
+        const c = chip.adc?.channels.find((x) => x.channel === ch && (x.controller ?? chip.adc?.nodeLabel) === (label ?? chip.adc?.nodeLabel));
+        if (c && !pins.includes(c.pin))
+            pins.push(c.pin);
+    }
+    for (const m of src.matchAll(/__tc_adct(\d+)_done/g)) {
+        const pin = Number(m[1]);
+        if (chip.adc?.channels.some((x) => x.pin === pin) && !pins.includes(pin))
+            pins.push(pin);
+    }
+    return pins;
+}
+/**
+ * HAL pins the emitted sources drive with dac.* — the DAC lowering's lazy
+ * per-pin setup guard is `__tc_dact<pin>_done` (lowering/dac.ts), so
+ * var-presence is the authoritative used-signal. Feeds the overlay's DAC
+ * pinctrl gating (same pattern as scanAdcReadPins).
+ */
+function scanDacWritePins(src) {
+    const pins = [];
+    for (const m of src.matchAll(/__tc_dact(\d+)_done/g)) {
+        const pin = Number(m[1]);
+        if (!pins.includes(pin))
+            pins.push(pin);
+    }
+    return pins;
+}
+/**
+ * HAL pins the emitted sources drive with pwm.* — the emitted source
+ * references each used spec as `__tc_pwm_<alias token>` (pwmVarName in
+ * lowering/pwm.ts), and the lowering only emits specs for driven pins, so
+ * var-presence is the authoritative signal. Feeds the overlay's per-pin
+ * pwm-leds gating (no dead DT channels).
+ */
+/**
+ * Inline-override markers (the escape hatch): the adc/pwm lowerings emit
+ * `/* cuttlefish-user-facts: <kind> pin=N [device=X] [pinctrl=P] channel=C *​/`
+ * comments when a construction carries routing overrides. Merged into the
+ * chip so the overlay synthesis + used-pin scans treat them as facts —
+ * the transpiler cannot create DT nodes, but this regen can.
+ */
+function applyUserFactMarkers(chip, src) {
+    const adcAdds = [];
+    const pwmAdds = [];
+    for (const m of src.matchAll(/\/\* cuttlefish-user-facts: (adc|pwm) ([^*]*?) \*\//g)) {
+        const kind = m[1];
+        const fields = new Map();
+        for (const kv of m[2].split(/\s+/).filter(Boolean)) {
+            const eq = kv.indexOf('=');
+            if (eq > 0)
+                fields.set(kv.slice(0, eq), kv.slice(eq + 1));
+        }
+        const pin = Number(fields.get('pin'));
+        const channel = Number(fields.get('channel'));
+        if (!Number.isFinite(pin) || !Number.isFinite(channel))
+            continue;
+        if (kind === 'adc') {
+            adcAdds.push({
+                pin,
+                channel,
+                ...(fields.get('device') ? { controller: fields.get('device') } : {}),
+                ...(fields.get('pinctrl') ? { pinctrl: fields.get('pinctrl') } : {}),
+            });
+        }
+        else if (fields.get('controller')) {
+            pwmAdds.push({ pin, channel, controller: fields.get('controller') });
+        }
+    }
+    if (adcAdds.length === 0 && pwmAdds.length === 0)
+        return chip;
+    const adc = chip.adc
+        ? chip.adc
+        : { nodeLabel: adcAdds.find((a) => !a.controller)?.controller ?? 'adc', resolution: 12, vrefMv: 3000, channels: [] };
+    const adcChannels = [...adc.channels];
+    for (const a of adcAdds) {
+        const existing = adcChannels.findIndex((c) => c.pin === a.pin);
+        if (existing >= 0)
+            adcChannels.splice(existing, 1);
+        adcChannels.push({ pin: a.pin, channel: a.channel, ...(a.controller ? { controller: a.controller } : {}), ...(a.pinctrl ? { pinctrl: a.pinctrl } : {}) });
+    }
+    const pwmSpecs = [...(chip.pwm?.specs ?? [])];
+    for (const p of pwmAdds) {
+        const existing = pwmSpecs.findIndex((s) => s.pin === p.pin);
+        if (existing >= 0)
+            pwmSpecs.splice(existing, 1);
+        pwmSpecs.push({ pin: p.pin, controller: p.controller, channel: p.channel });
+    }
+    return {
+        ...chip,
+        adc: { ...adc, channels: adcChannels },
+        pwm: { ...(chip.pwm ?? { specs: [] }), specs: pwmSpecs },
+    };
+}
+function scanPwmUsedPins(src, chip) {
+    const pins = (chip.pwm?.specs ?? [])
+        .filter((s) => src.includes(`__tc_pwm_${pwmDtAliasToken(s)}`))
+        .map((s) => s.pin);
+    // Matrix pins (ESP32 LEDC) have no static specs — recover the driven pins
+    // from the same alias-var presence signal (`__tc_pwm_tc_pwm<N>`), keeping
+    // only pins the descriptor's matrix allows (the regex grabs the full
+    // number, so pin 4 never matches a reference to pin 45).
+    const matrix = chip.pwm?.matrix;
+    if (matrix) {
+        const present = new Set();
+        for (const match of src.matchAll(/__tc_pwm_tc_pwm(\d+)/g)) {
+            present.add(Number(match[1]));
+        }
+        for (const pin of matrix.pins) {
+            if (present.has(pin))
+                pins.push(pin);
+        }
+    }
+    return pins;
+}
+/**
+ * Bus controller indexes the emitted sources actually reference — the shim
+ * declares one `__tc_<bus><N>_dev` state block per used instance (gated by
+ * collectUsedBusIndices at transpile time), so var-presence is the
+ * authoritative signal. The overlay enables only these controllers: an
+ * enabled-but-unused one claims its default pins (i2c0's GP4/GP5 on the
+ * Pico) which a program driving the OTHER controller may want as GPIO.
+ * Empty list (no state blocks — e.g. display/touch composites that use the
+ * driver API directly) means "no signal"; the caller then passes undefined
+ * so the overlay enables every declared controller, preserving old behavior.
+ */
+function scanUsedBusInstances(src, controllers, bus) {
+    if (!controllers)
+        return undefined;
+    const used = [];
+    for (let i = 0; i < controllers.length; i++) {
+        if (src.includes(`__tc_${bus}${i}_dev`))
+            used.push(i);
+    }
+    return used.length > 0 ? used : undefined;
+}
+/** Scan the emitted source for thin SPI targets (hal/spi-target.ts): the
+ *  spi_dt_spec state block's tc-spit-cfg comment carries the construction
+ *  facts, the same channel tc-sensor-cfg uses. */
+export function scanSpiTargets(src) {
+    const out = new Map();
+    for (const m of src.matchAll(/tc-spit-cfg: tc_spit_spi(\d+)_cs(\d+) hz=(\d+) mode=(\d+)/g)) {
+        const ref = { busIndex: parseInt(m[1], 10), cs: parseInt(m[2], 10), hz: parseInt(m[3], 10), mode: parseInt(m[4], 10) };
+        out.set(`${ref.busIndex}|${ref.cs}`, ref);
+    }
+    return [...out.values()];
+}
+export function scanSensorParts(src) {
+    const out = new Map();
+    for (const m of src.matchAll(/__tc_sensor_([a-z0-9_]+)_(i2c|spi)(\d+)_(0x[0-9a-f]+|cs[0-9]+)_dev\b/g)) {
+        const port = m[4].startsWith('0x') ? parseInt(m[4], 16) : parseInt(m[4].slice(2), 10);
+        const ref = { part: m[1], busIndex: parseInt(m[3], 10), port, busKind: m[2], spiHz: 0, spiMode: 0, alertPin: -1 };
+        out.set(`${ref.part}|${ref.busKind}${ref.busIndex}|${ref.port}`, ref);
+    }
+    // Construction facts ride the state block's config comment — merge by
+    // nodelabel so the scanner stays the single source for the overlay.
+    for (const m of src.matchAll(/tc-sensor-cfg: tc_([a-z0-9_]+)_(i2c|spi)(\d+)_(0x[0-9a-f]+|cs[0-9]+) hz=(\d+) mode=(\d+) alert=(-?\d+)/g)) {
+        const port = m[4].startsWith('0x') ? parseInt(m[4], 16) : parseInt(m[4].slice(2), 10);
+        const key = `${m[1]}|${m[2]}${m[3]}|${port}`;
+        const existing = out.get(key);
+        if (existing) {
+            existing.spiHz = parseInt(m[5], 10);
+            existing.spiMode = parseInt(m[6], 10);
+            existing.alertPin = parseInt(m[7], 10);
+        }
+    }
+    return [...out.values()];
+}
 function targetFromOptions(o) {
-    // The cuttlefish CLI populates ToolchainOptions.buildTarget from
-    // config.frameworkData.buildTarget. Accept frameworkData.target as an alias.
+    // The cuttlefish CLI populates ToolchainOptions.buildTarget from the
+    // config's board: (frameworkData.buildTarget for board-less projects).
+    // Accept frameworkData.target as an alias. No silent default: building for
+    // a wrong hard-coded board is the split-brain trap.
     const fcTarget = o.frameworkConfig?.target;
-    return o.buildTarget ?? fcTarget ?? DEFAULT_BOARD;
+    const board = o.buildTarget ?? fcTarget;
+    if (!board) {
+        throw new Error('No build target: set board: in cuttlefish.config.ts (or frameworkData.buildTarget for custom-board projects).');
+    }
+    return board;
 }
 /**
  * Derive the Zephyr project root from the cuttlefish-emitted source path.
@@ -59,32 +280,193 @@ export function projectRootFromOptions(o) {
  */
 const BUILD_TIMEOUT_MS = 600_000;
 const FLASH_TIMEOUT_MS = 120_000;
+export function resolveProbeMethod(zc, chip, purpose = 'flash') {
+    const probe = zc?.probe;
+    const runner = zc?.runner;
+    const userArgs = zc?.runnerArgs ?? [];
+    if (probe && runner) {
+        return {
+            ok: false,
+            error: `cuttlefish.config.ts sets both zephyr.probe ('${probe}') and zephyr.runner ('${runner}'). ` +
+                `They are two ways to choose the probe method — remove one.`,
+        };
+    }
+    if (probe) {
+        const methods = chip.probeMethods ?? [];
+        const method = methods.find((m) => m.id === probe);
+        if (!method) {
+            const listAll = methods
+                .map((m) => `${m.id} (${m.runner}${m.description ? ` — ${m.description}` : ''})`)
+                .join('; ');
+            return {
+                ok: false,
+                error: methods.length > 0
+                    ? `Unknown probe method '${probe}' for ${chip.id}. Supported: ${listAll}.`
+                    : `This board (${chip.id}) ships no probe-method table, so 'zephyr.probe' cannot resolve '${probe}'. ` +
+                        `Use the raw 'zephyr.runner' field instead (run 'west flash --context' in the build dir for options).`,
+            };
+        }
+        if (purpose === 'debug' && method.debug === false) {
+            const debuggable = methods.filter((m) => m.debug !== false).map((m) => m.id).join(', ');
+            return {
+                ok: false,
+                error: `The '${probe}' method cannot debug ${chip.id} — a bootloader is not a debugger. ` +
+                    `Debug-capable methods: ${debuggable || '(none — this board needs an external probe)'}.`,
+            };
+        }
+        return {
+            ok: true,
+            runner: method.runner,
+            args: [...(method.args ?? []), ...userArgs],
+        };
+    }
+    return { ok: true, runner, args: userArgs };
+}
 /**
- * Build the `west flash` argument list for a board.
- *
- * Runner selection: each board's board.cmake declares a sensible default flash
- * runner for its hardware (xiao_ble → nrfutil, esp32* → esptool), and `west
- * flash` resolves it automatically. The framework only intervenes where the
- * board default needs an argument it can't infer:
- *   - An explicit `zephyr.runner` (from cuttlefish.config.ts) always wins.
- *   - ESP32 boards forward the port via `--esp-device` (esptool reads the
- *     device from it); board.cmake still picks the runner.
- *   - Every other board trusts the board.cmake default. Previously this forced
- *     `--runner nrfjprog` for every non-ESP32 target, which broke boards whose
- *     default is not nrfjprog (xiao_ble defaults to nrfutil) and required
- *     Nordic J-Link tools that a USB-bootloader board does not have.
+ * Run an openocd session against the board's probe config — the shared
+ * engine for the pre-flash quiesce and the post-flash SYSRESETREQ (see the
+ * call sites in upload()). The config is the probe method's verbatim
+ * debugCfg from the board catalog (the same lines `west debug` uses);
+ * `commands` are appended after `-f <cfg> -c init`. Returns a flash note on
+ * success, undefined when skipped or failed (best-effort by design).
+ */
+function openocdProbeSession(buildDir, zc, chip, commands) {
+    // Config resolution — two sources, in order:
+    //   1. The named probe method's verbatim debugCfg from the board catalog
+    //      (written to a temp cfg), when zephyr.probe names a method that has
+    //      one.
+    //   2. The board's own support/openocd.cfg in the Zephyr tree — the exact
+    //      config `west flash` resolves for the openocd runner. This covers
+    //      raw `zephyr.runner: 'openocd'` (no named probe) and probe methods
+    //      that ship no debugCfg of their own.
+    const probeId = zc?.probe;
+    const method = chip.probeMethods?.find((m) => m.id === probeId);
+    const cfgLines = method?.debugCfg;
+    // Session reset policy: `reset_config none`. The session's resets are
+    // core-domain by design — vector-catch halt before the flash write,
+    // SYSRESETREQ to boot — so they must not depend on the SRST pin. Boards
+    // like the WeAct Black Pill don't break NRST out at all: under the board
+    // cfg's `srst_only`, every `reset` asserts a pin that reaches nothing
+    // (the target never resets, `reset halt` catches the core mid-app in
+    // dirty state and the flash algorithm times out) while the probe's
+    // floating SRST sense reports phantom "external reset detected" events
+    // that leave the session's halt state inconsistent. Method-declared west
+    // quirks (`--cmd-pre-init=…`) are appended after and override the
+    // default for boards whose facts carry one.
+    const preInit = [
+        'reset_config none',
+        ...(method?.args ?? [])
+            .filter((a) => a.startsWith('--cmd-pre-init='))
+            .map((a) => a.slice('--cmd-pre-init='.length)),
+    ];
+    const install = discoverWest();
+    const sdkRoot = process.env.ZEPHYR_SDK_INSTALL_DIR || install?.sdkInstallDir;
+    if (!sdkRoot)
+        return undefined;
+    const openocdExe = join(sdkRoot, 'hosttools', 'openocd', 'bin', process.platform === 'win32' ? 'openocd.exe' : 'openocd');
+    if (!existsSync(openocdExe))
+        return undefined;
+    // Script search path: the SDK layouts differ across versions — prefer the
+    // share/ form west's own runner uses, fall back to the scripts/ form.
+    const shareScripts = join(sdkRoot, 'hosttools', 'openocd', 'share', 'openocd', 'scripts');
+    const binScripts = join(sdkRoot, 'hosttools', 'openocd', 'scripts');
+    const searchDir = existsSync(shareScripts) ? shareScripts : binScripts;
+    let cfgArgs;
+    let sessionCfg;
+    if (cfgLines && cfgLines.length > 0) {
+        sessionCfg = join(buildDir, 'cuttlefish-probe.cfg');
+    }
+    else {
+        // The board target's qualifier ('blackpill_f411ce/stm32f411xe' →
+        // 'blackpill_f411ce') identifies the board dir; the vendor segment is
+        // not part of the target, so probe the boards/ tree for it.
+        const zephyrBase = process.env.ZEPHYR_BASE || install?.zephyrBase;
+        const boardDir = (chip.id ?? '').split('/')[0];
+        if (!zephyrBase || !boardDir)
+            return undefined;
+        const boardsRoot = join(zephyrBase, 'boards');
+        let supportCfg;
+        try {
+            for (const vendor of readdirSync(boardsRoot)) {
+                const candidate = join(boardsRoot, vendor, boardDir, 'support', 'openocd.cfg');
+                if (existsSync(candidate)) {
+                    supportCfg = candidate;
+                    break;
+                }
+            }
+        }
+        catch {
+            return undefined;
+        }
+        if (!supportCfg)
+            return undefined;
+        cfgArgs = ['-s', dirname(supportCfg), '-f', supportCfg];
+    }
+    try {
+        mkdirSync(buildDir, { recursive: true });
+        if (sessionCfg) {
+            writeFileSync(sessionCfg, cfgLines.join('\n') + '\n', 'utf-8');
+            cfgArgs = ['-f', sessionCfg];
+        }
+        const res = spawnSync(openocdExe, [
+            '-s', searchDir, ...cfgArgs,
+            // Pre-init TCL AFTER the cfg (overrides its reset_config) and BEFORE
+            // init — the same position west gives --cmd-pre-init.
+            ...preInit.map((c) => ['-c', c]).flat(),
+            '-c', 'init',
+            ...commands.map((c) => ['-c', c]).flat(),
+            '-c', 'shutdown',
+        ], {
+            cwd: buildDir,
+            encoding: 'utf-8',
+            timeout: 20_000,
+        });
+        return res.status === 0 ? `-- probe session ok: ${commands.join('; ')}` : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Whether a flash runner carries the upload over a serial port. Runner-gated,
+ * never board-name-gated: esptool and bossac are the only runners
+ * `buildFlashArgs` forwards `--port` to, so they are the only ones that
+ * cannot flash without one. Probe runners (openocd, jlink) and USB flows
+ * (dfu-util, uf2 mass storage) need no port — a missing `--port` must not
+ * block them.
  *
- * Exported (pure) so the runner-selection contract is unit-testable without
+ * Exported (pure) so the port-requirement contract is unit-testable without
  * spawning west.
  */
-export function buildFlashArgs(buildDir, board, userRunner, port) {
+export function uploadRequiresPort(runner) {
+    return runner === 'esptool' || runner === 'bossac';
+}
+export function buildFlashArgs(buildDir, userRunner, port, flashRunner, runnerArgs) {
+    // flashRunner is the runner the flash will actually use — the explicit
+    // zephyr.runner when set, else the board's declared default from its probe
+    // table. It gates the esptool port forwarding below; only an EXPLICIT
+    // userRunner forces west's --runner (board defaults stay board.cmake's
+    // choice). Runner-gated, never board-name-gated: any board whose flash
+    // runs esptool gets the same forwarding.
     const args = ['flash', '-d', buildDir];
     if (userRunner) {
         args.push('--runner', userRunner);
     }
-    if (port && board.startsWith('esp32')) {
+    if (port && flashRunner === 'esptool') {
         args.push('--esp-device', port);
     }
+    // The bossac runner defaults its port to /dev/ttyACM0 — on Windows that
+    // never matches, so the port MUST be forwarded or bossac fails with
+    // "No device found on /dev/ttyACM0" (same class of port-forwarding
+    // problem as the esptool --esp-device above).
+    if (port && flashRunner === 'bossac') {
+        args.push('--bossac-port', port);
+    }
+    // Extra runner-specific flags, appended verbatim (west's runner parsers
+    // accept them after the runner is selected).
+    if (runnerArgs && runnerArgs.length > 0) {
+        args.push(...runnerArgs);
+    }
     return args;
 }
 /**
@@ -181,8 +563,6 @@ export const Toolchain = {
         // logic in scaffold via the usage scan. Mirrors how Arduino's library
         // resolution is a pre-build artifact step.
         const projectRoot = basename(outputDir) === 'src' ? dirname(outputDir) : outputDir;
-        const board = DEFAULT_BOARD;
-        const chip = chipForTarget(board);
         // Scan the emitted source for usage tokens (same authoritative signal the
         // scaffold uses). entryPoint is the path to main.cpp; its dir is src/.
         const srcDir = dirname(entryPoint);
@@ -196,6 +576,12 @@ export const Toolchain = {
         }
         catch { /* src may not exist yet on first prepare */ }
         const uses = (t) => src.includes(t);
+        // Inline-override markers (the escape hatch): the lowerings emit
+        // `cuttlefish-user-facts` comments carrying routing the transpiler
+        // cannot synthesize (adc device/pinctrl, pwm controller/channel).
+        // Merged into the chip BEFORE the scans + overlay generation, so the DT
+        // nodes, pinctrl groups, and used-pin recovery treat them as facts.
+        const chip = applyUserFactMarkers(chipForBuild(projectRoot, ''), src);
         // Display usage tokens: the minimal GFX runtime (display_write/_fill_rect)
         // and the UI display adapter (display_init / __tc_display_dev /
         // DEVICE_DT_GET on the display nodelabel). Both paths need the DT overlay
@@ -212,17 +598,65 @@ export const Toolchain = {
         // references (FT6336U on I2C, XPT2046 on the display's SPI bus).
         const usesTouch = uses('ft6336u') || uses('touch_');
         const usesXpt = uses('xpt2046');
+        const sensorParts = scanSensorParts(src);
+        const spiTargetParts = scanSpiTargets(src);
         const overlay = generateOverlay(chip, {
-            usesI2c: uses('i2c_'),
-            usesSpi: uses('spi_'),
-            usesUart: uses('uart_'),
+            // __tc_<bus> matches the shim state block — a begin()-only program
+            // emits no driver API call but still declares the DT device. A
+            // constructed sensor is also a bus user (its device handle is the
+            // only i2c reference a sensor-only program carries).
+            usesI2c: uses('i2c_') || uses('__tc_i2c') || sensorParts.length > 0,
+            usesSensor: uses('sensor_') || sensorParts.length > 0,
+            usesFloatFormat: /%[-0-9.]*[eEfFgG]/.test(src),
+            sensorParts,
+            spiTargets: spiTargetParts,
+            usesSpi: uses('spi_') || uses('__tc_spi') || spiTargetParts.length > 0,
+            usesUart: uses('__tc_uart'),
+            usesUsb: uses('__tc_usb'),
+            usesPwm: uses('pwm_'),
+            usesAdc: uses('adc_'),
+            adcReadPins: scanAdcReadPins(src, chip),
+            dacWritePins: scanDacWritePins(src),
+            pwmUsedPins: scanPwmUsedPins(src, chip),
+            i2cUsedInstances: scanUsedBusInstances(src, chip.i2c?.controllers, 'i2c'),
+            spiUsedInstances: scanUsedBusInstances(src, chip.spi?.controllers, 'spi'),
+            uartUsedInstances: scanUsedBusInstances(src, chip.uart?.controllers, 'uart'),
+            // Preferences/FS — same tokens scaffoldZephyrProject scans (the ZMS
+            // settings_* API + __tc_prefs shim, the __tc_fs mount shim); drive the
+            // storage-partition synthesis + /chosen settings pointer.
+            usesPreferences: uses('settings_') || uses('__tc_prefs'),
+            usesFS: uses('__tc_fs'),
+            usesWdt: uses('wdt_'),
+            usesHwtimer: uses('counter_') || uses('__tc_hw'),
             usesDisplay,
             usesTouch: usesTouch || usesXpt,
             touchController: usesXpt ? 'xpt2046' : 'ft6336u',
         }, displayProfile);
         const overlayDir = join(projectRoot, 'boards');
         mkdirSync(overlayDir, { recursive: true });
-        writeIfChanged(join(overlayDir, `${board}.overlay`), overlay);
+        // prepare() runs before the real target is known — the placeholder name
+        // never matches `west build -b <board>` (compile rewrites the overlay
+        // under the actual board's name below).
+        writeIfChanged(join(overlayDir, 'board.overlay'), overlay);
+        // Thin SPI targets need an app-local binding: a compatible-less DT node
+        // generates NO property macros, so SPI_DT_SPEC_GET's spi-max-frequency
+        // lookup would not exist. The binding has no driver — it exists so
+        // gen_defines emits the spi properties for the target nodes.
+        if (spiTargetParts.length > 0) {
+            const bindingsDir = join(projectRoot, 'dts', 'bindings');
+            mkdirSync(bindingsDir, { recursive: true });
+            writeIfChanged(join(bindingsDir, 'cuttlefish,spi-target.yaml'), [
+                'description: |',
+                '  Cuttlefish thin SPITarget (hal/spi-target.ts) — a raw spi_dt_spec',
+                '  peer. No driver binds this compatible; it exists so devicetree',
+                '  generation emits the spi properties (spi-max-frequency,',
+                '  spi-cpol/spi-cpha, reg = the cs-gpios index) that SPI_DT_SPEC_GET',
+                '  consumes from the generated C++.',
+                'compatible: "cuttlefish,spi-target"',
+                'include: spi-device.yaml',
+                '',
+            ].join('\n'));
+        }
     },
     compile(o) {
         const projectRoot = projectRootFromOptions(o);
@@ -253,7 +687,20 @@ export const Toolchain = {
         // the <default>.overlay it wrote does not match `west build -b <board>`.
         // Zephyr auto-detects boards/<board>.overlay under APPLICATION_CONFIG_DIR.
         try {
-            const chip = chipForTarget(board);
+            const chip = chipForBuild(projectRoot, board);
+            // Custom-board generation: an MCU-only target (no board package) has no
+            // upstream Zephyr board — generate one under boards/typecad/<name>/ from
+            // the chip's silicon data. Opt-in via `zephyr.customBoard: true` in
+            // cuttlefish.config.ts; the board takes its name from the build target.
+            // Idempotent — regenerated on every compile, before the overlay pass.
+            if (zc?.customBoard === true) {
+                const generated = generateCustomBoard(projectRoot, chip, board.split('/')[0]);
+                if (!generated) {
+                    throw new Error(`zephyr.customBoard is set, but the resolved chip ('${chip.id}') carries no ` +
+                        `silicon board data. Custom-board generation requires an MCU-only config ` +
+                        `(mcu set, board absent) whose MCU package ships a zephyr block.`);
+                }
+            }
             const srcDir = join(projectRoot, 'src');
             let src = '';
             try {
@@ -339,10 +786,35 @@ export const Toolchain = {
                 touchWiring = { controller: 'xpt2046', ...(touchWiring ?? {}) };
             }
             const overlayDiagnostics = [];
+            const sensorParts = scanSensorParts(src);
+            const spiTargetParts = scanSpiTargets(src);
             const overlay = generateOverlay(chip, {
-                usesI2c: uses('i2c_'),
-                usesSpi: uses('spi_'),
-                usesUart: uses('uart_'),
+                // __tc_<bus> matches the shim state block — a begin()-only program
+                // emits no driver API call but still declares the DT device. A
+                // constructed sensor is also a bus user (see scanSensorParts).
+                usesI2c: uses('i2c_') || uses('__tc_i2c') || sensorParts.length > 0,
+                usesSensor: uses('sensor_') || sensorParts.length > 0,
+                usesFloatFormat: /%[-0-9.]*[eEfFgG]/.test(src),
+                sensorParts,
+                spiTargets: spiTargetParts,
+                usesSpi: uses('spi_') || uses('__tc_spi') || spiTargetParts.length > 0,
+                usesUart: uses('__tc_uart'),
+                usesUsb: uses('__tc_usb'),
+                usesPwm: uses('pwm_'),
+                usesAdc: uses('adc_'),
+                adcReadPins: scanAdcReadPins(src, chip),
+                usesDac: uses('dac_') || uses('__tc_dac'),
+                dacWritePins: scanDacWritePins(src),
+                pwmUsedPins: scanPwmUsedPins(src, chip),
+                i2cUsedInstances: scanUsedBusInstances(src, chip.i2c?.controllers, 'i2c'),
+                spiUsedInstances: scanUsedBusInstances(src, chip.spi?.controllers, 'spi'),
+                uartUsedInstances: scanUsedBusInstances(src, chip.uart?.controllers, 'uart'),
+                // Preferences/FS — same tokens scaffoldZephyrProject scans; drive the
+                // storage-partition synthesis + /chosen settings pointer.
+                usesPreferences: uses('settings_') || uses('__tc_prefs'),
+                usesWdt: uses('wdt_'),
+                usesHwtimer: uses('counter_') || uses('__tc_hw'),
+                usesFS: uses('__tc_fs'),
                 usesDisplay,
                 usesTouch: uses('ft6336u') || uses('touch_') || usesXpt,
                 touchController: usesXpt ? 'xpt2046' : 'ft6336u',
@@ -356,9 +828,28 @@ export const Toolchain = {
             // Write the board-specific overlay (the one west loads). Zephyr looks for
             // boards/<board_id>.overlay under APPLICATION_CONFIG_DIR — use the bare
             // board id (before any hardware-qualifier suffix, e.g. 'esp32_devkitc'
-            // not the full 'esp32_devkitc/esp32/procpu' target string).
+            // not the full 'esp32_devkitc/esp32/procpu' target string). Library
+            // packages' overlay fragments are appended by the scaffold helper.
             const boardId = board.split('/')[0];
-            writeIfChanged(join(overlayDir, `${boardId}.overlay`), overlay);
+            writeIfChanged(join(overlayDir, `${boardId}.overlay`), appendLibraryOverlayFragments(overlay, projectRoot));
+            // Thin SPI targets need the app-local binding (see the transpile-side
+            // write for the rationale): no compatible → no generated spi props →
+            // SPI_DT_SPEC_GET's spi-max-frequency lookup does not exist.
+            if (spiTargetParts.length > 0) {
+                const bindingsDir = join(projectRoot, 'dts', 'bindings');
+                mkdirSync(bindingsDir, { recursive: true });
+                writeIfChanged(join(bindingsDir, 'cuttlefish,spi-target.yaml'), [
+                    'description: |',
+                    '  Cuttlefish thin SPITarget (hal/spi-target.ts) — a raw spi_dt_spec',
+                    '  peer. No driver binds this compatible; it exists so devicetree',
+                    '  generation emits the spi properties (spi-max-frequency,',
+                    '  spi-cpol/spi-cpha, reg = the cs-gpios index) that SPI_DT_SPEC_GET',
+                    '  consumes from the generated C++.',
+                    'compatible: "cuttlefish,spi-target"',
+                    'include: spi-device.yaml',
+                    '',
+                ].join('\n'));
+            }
         }
         catch { /* best-effort overlay regen; the build surfaces DT errors */ }
         // Use a stable build dir so incremental builds reuse the Ninja graph.
@@ -439,11 +930,11 @@ export const Toolchain = {
         // toolchain compile() debug-config wiring.
         if (result.status === 0 && isGdbDebug) {
             try {
-                const { workspaceRoot, sketchRel } = resolveDebugLocations(projectRoot);
+                const { workspaceRoot, appRel } = resolveDebugLocations(projectRoot);
                 writeDebugConfig({
                     projectRoot,
                     workspaceRoot,
-                    sketchRel,
+                    appRel,
                     target: board,
                     buildDir,
                     sourceMapPath: join(dirname(o.sourcePath), `${basename(o.sourcePath)}.thcppmap.json`),
@@ -453,6 +944,41 @@ export const Toolchain = {
                 console.warn(`[cuttlefish] gdb debug config generation failed: ${e.message}`);
             }
         }
+        // As-built snapshot: after a successful build, the resolved devicetree
+        // at <buildDir>/zephyr/zephyr.dts carries the board's pinctrl labels —
+        // the STABLE name grammar, immune to vendor macro churn. Harvest its
+        // routes into .cuttlefish/as-built.json; the next build's board-module
+        // generation merges them per-pin over the catalog harvest (build wins,
+        // silently when they agree). One-build freshness lag on first setup,
+        // self-maintaining after. Best-effort — a missing/unparseable artifact
+        // never fails the build.
+        if (result.status === 0) {
+            try {
+                const dtsPath = join(buildDir, 'zephyr', 'zephyr.dts');
+                const dtsText = readFileSync(dtsPath, 'utf8');
+                const facts = parseZephyrDts(dtsText);
+                const total = facts.adc.length + facts.pwm.length + facts.dac.length;
+                if (total > 0) {
+                    // Write beside the project's board module — the .cuttlefish dir the
+                    // config loader reads from, discovered by walking up to the
+                    // generated board.json (the scaffold root and the config root are
+                    // different dirs in the standard layout: src/out vs project root).
+                    let cfDir = join(projectRoot, '.cuttlefish');
+                    for (let dir = projectRoot;; dir = dirname(dir)) {
+                        if (existsSync(join(dir, '.cuttlefish', 'board.json'))) {
+                            cfDir = join(dir, '.cuttlefish');
+                            break;
+                        }
+                        const parent = dirname(dir);
+                        if (parent === dir)
+                            break;
+                    }
+                    mkdirSync(cfDir, { recursive: true });
+                    writeIfChanged(join(cfDir, 'as-built.json'), asBuiltJson(board, facts));
+                }
+            }
+            catch { /* best-effort snapshot — nothing to harvest or unreadable */ }
+        }
         return {
             success: result.status === 0,
             output: header + output,
@@ -464,20 +990,137 @@ export const Toolchain = {
         const buildDir = join(projectRoot, 'build');
         const board = targetFromOptions(o);
         const zc = o.zephyrConfig;
-        const runner = zc?.runner;
-        const args = buildFlashArgs(buildDir, board, runner, o.port);
-        const inv = westSpawn(args, {
-            cwd: projectRoot,
-            encoding: 'utf-8',
-            timeout: FLASH_TIMEOUT_MS,
-        });
-        const result = spawnSync(inv.command, inv.args, inv.options);
-        const fstdout = typeof result.stdout === 'string' ? result.stdout : (result.stdout?.toString() ?? '');
-        const fstderr = typeof result.stderr === 'string' ? result.stderr : (result.stderr?.toString() ?? '');
-        const raw = fstdout + fstderr;
+        const chip = chipForBuild(projectRoot, board);
+        const probe = resolveProbeMethod(zc, chip, 'flash');
+        if (!probe.ok) {
+            return { success: false, output: `-- west flash: ${probe.error}` };
+        }
+        // BOSSA bootloader boards with touch-reset data: open the app's console
+        // port at 1200 baud (the firmware's USB shim reboots into the
+        // bootloader), wait for the bootloader identity, and flash THAT port.
+        // Falls back to the configured port (manual double-tap) on any failure.
+        let flashPort = o.port;
+        const flashNotes = [];
+        // The runner this flash will actually use: the explicit choice, else the
+        // board's declared default (first probe-method entry). Gates port
+        // forwarding and the bossac touch below — board.cmake still resolves
+        // the default runner itself.
+        const flashRunner = probe.runner ?? chip.probeMethods?.[0]?.runner;
+        // Serial-port runners cannot flash without a port; every other runner
+        // (probe or USB) proceeds — whether a port is required is the runner's
+        // call, not the CLI's blanket gate.
+        if (uploadRequiresPort(flashRunner) && !flashPort) {
+            return {
+                success: false,
+                output: `-- upload requires a port for ${flashRunner} flashing. Set --port <port> on the command line (or the CUTTLEFISH_PORT env var).`,
+            };
+        }
+        if (flashRunner === 'bossac' && flashPort && chip.usb?.touchReset) {
+            const touch = bossacTouchReset(flashPort, chip.usb.touchReset);
+            flashNotes.push(`-- ${touch.note}`);
+            if (touch.port)
+                flashPort = touch.port;
+        }
+        const args = buildFlashArgs(buildDir, probe.runner, flashPort, flashRunner, probe.args);
+        // openocd flashes go through a dedicated session instead of `west flash`.
+        // west's flow has three sequential races that each strand the board: the
+        // connect happens against a running (often USB-active) application, the
+        // erase precedes the write so the vector table is 0xFFFFFFFF while the
+        // RAM algorithm runs (any exception → core LOCKUP at 0xFFFFFFFE, "timeout
+        // waiting for algorithm"), and the trailing `reset run` frequently does
+        // not reach the core. This session is deterministic end to end: halt at
+        // the reset vector (static target for the DAP), mask interrupts for the
+        // algorithm (exceptions cannot vector through erased flash), unmask
+        // after, and boot the flashed app with a direct SYSRESETREQ. Falls back
+        // to `west flash` when the image or session is unavailable.
+        let westFallback = true;
+        if (probe.runner === 'openocd') {
+            const hex = join(buildDir, 'zephyr', 'zephyr.hex');
+            if (existsSync(hex)) {
+                // Forward slashes + TCL quoting so project paths with spaces work.
+                const hexArg = `"${hex.replace(/\\/g, '/')}"`;
+                // Target addressing: `cortex_m` is a PER-TARGET subcommand — a bare
+                // `cortex_m maskisr on` is an unknown command (a silent no-op inside
+                // catch). Resolve the session's target object once and address it.
+                // Cortex-M-only, self-gating: on other cores the cortex_m method
+                // errors and catch contains it (the plain flash path is safe there
+                // without masking — the lockup class is Cortex-M vectoring).
+                const flashed = openocdProbeSession(buildDir, zc, chip, [
+                    'set _tgt [lindex [target names] 0]',
+                    'reset halt',
+                    'catch { $_tgt cortex_m maskisr on }',
+                    `flash write_image erase ${hexArg}`,
+                    'catch { $_tgt cortex_m maskisr off }',
+                    // Boot the flashed app. Cortex-M: a direct SYSRESETREQ via AIRCR —
+                    // pin-independent, always reaches the core, and clears PRIMASK
+                    // (so the masked algorithm leaves nothing behind). Other cores:
+                    // openocd's generic reset run. A halted core STAYS halted across
+                    // a core-initiated reset (debug halt state survives — that is how
+                    // reset halt works), so resume it; on a running core resume errors
+                    // and the catch swallows it.
+                    'if {[catch {$_tgt cortex_m maskisr on}] == 0} { $_tgt cortex_m maskisr off; mww 0xE000ED0C 0x05FA0004 } else { reset run }',
+                    'sleep 100',
+                    'catch { resume }',
+                    'sleep 200',
+                ]);
+                if (flashed) {
+                    westFallback = false;
+                    flashNotes.push('-- probe flash ok: halt → masked write → SYSRESETREQ');
+                }
+            }
+        }
+        let result;
+        let raw = '';
+        let ok = false;
+        if (westFallback) {
+            const inv = westSpawn(args, {
+                cwd: projectRoot,
+                encoding: 'utf-8',
+                timeout: FLASH_TIMEOUT_MS,
+            });
+            result = spawnSync(inv.command, inv.args, inv.options);
+            const fstdout = typeof result.stdout === 'string' ? result.stdout : (result.stdout?.toString() ?? '');
+            const fstderr = typeof result.stderr === 'string' ? result.stderr : (result.stderr?.toString() ?? '');
+            raw = fstdout + fstderr;
+            ok = classifyUploadResult(probe.runner, result.status, raw);
+            // A SUCCESSFUL west openocd flash can still leave the core HALTED:
+            // west's trailing `reset run` does not reach a core behind an unwired
+            // SRST, and the user's only recourse is the NRST button. Boot it from
+            // a probe session instead — one core reset (a halted core re-halts at
+            // the reset vector; a running core restarts the just-flashed app)
+            // plus a resume.
+            if (ok && probe.runner === 'openocd') {
+                const booted = openocdProbeSession(buildDir, zc, chip, [
+                    'set _tgt [lindex [target names] 0]',
+                    'if {[catch {$_tgt cortex_m maskisr on}] == 0} { $_tgt cortex_m maskisr off; mww 0xE000ED0C 0x05FA0004 } else { reset run }',
+                    'sleep 100',
+                    'catch { resume }',
+                    'sleep 200',
+                ]);
+                if (booted)
+                    flashNotes.push('-- probe boot ok: SYSRESETREQ → resume');
+            }
+            // Fallback-path recovery: a failed west flash leaves the core in
+            // lockup; a direct SYSRESETREQ clears it so the caller's retry (or a
+            // later flash) starts from a clean chip.
+            if (!ok && probe.runner === 'openocd') {
+                const revived = openocdProbeSession(buildDir, zc, chip, [
+                    'init',
+                    'set _tgt [lindex [target names] 0]',
+                    'if {[catch {$_tgt cortex_m maskisr on}] == 0} { $_tgt cortex_m maskisr off; mww 0xE000ED0C 0x05FA0004 } else { reset run }',
+                    'sleep 300',
+                ]);
+                if (revived)
+                    flashNotes.push(revived);
+            }
+        }
+        else {
+            ok = true;
+        }
         return {
-            success: classifyUploadResult(runner, result.status, raw),
-            output: cleanseUploadOutput(runner, result.status, raw),
+            success: ok,
+            output: [...flashNotes, cleanseUploadOutput(probe.runner, westFallback ? result.status : 0, raw)]
+                .filter(Boolean).join('\n'),
         };
     },
     monitor(o) {
@@ -492,7 +1135,7 @@ export const Toolchain = {
         }
         // ESP32 USB-CDC console runs at 115200 (the Zephyr ESP32 board default).
         // The CLI's generic default of 9600 is wrong for this target; honor an
-        // explicit --baud / config.console.baudRate when given, else 115200.
+        // explicit --baud when given, else 115200.
         const baud = o.baud ?? 115200;
         const install = discoverWest();
         const py = install?.pythonExecutable ?? process.env.PYTHON ?? 'python';
@@ -507,15 +1150,27 @@ export const Toolchain = {
         });
     },
     debug(o) {
-        // Launch an interactive GDB session for the last build. `west debug`
-        // auto-resolves the runner (openocd for esp32s3, nrfjprog/jlink for nRF)
-        // and the GDB binary from the build dir's CMakeCache/board.cmake — no
+        // Launch an interactive GDB session for the last build. The probe method
+        // resolves exactly like flashing (zephyr.probe / zephyr.runner — the same
+        // attach session, so the same quirks apply); debug-incapable methods
+        // (bootloaders) are rejected with the debug-capable list. west debug
+        // resolves the GDB binary from the build dir's CMakeCache — no
         // hand-authored gdbinit needed. Inherits stdio so GDB runs interactively.
-        // (Not invoked by the standard build/compile flow; powers an explicit
-        // debug-attach entry point for terminal-driven debugging without VS Code.)
         const projectRoot = projectRootFromOptions(o);
         const buildDir = join(projectRoot, 'build');
-        const inv = westSpawn(['debug', '-d', buildDir], {
+        const board = targetFromOptions(o);
+        const zc = o.zephyrConfig;
+        const probe = resolveProbeMethod(zc, chipForBuild(projectRoot, board), 'debug');
+        if (!probe.ok) {
+            console.error(`-- west debug: ${probe.error}`);
+            process.exitCode = 1;
+            return;
+        }
+        const debugArgs = ['debug', '-d', buildDir];
+        if (probe.runner)
+            debugArgs.push('--runner', probe.runner);
+        debugArgs.push(...probe.args);
+        const inv = westSpawn(debugArgs, {
             cwd: projectRoot,
             encoding: 'utf-8',
             stdio: 'inherit',