@typecad/framework-zephyr 1.0.0-alpha.16 → 1.0.0-alpha.18

package/dist/boardgen.js

@@ -6,9 +6,10 @@
 // CONTRACT (custom PCB spec) — and emits the two artifacts a project
 // carries instead of a board package:
 //
-//   .cuttlefish/board.ts   — typed pin/bus/LED/BUTTON exports (the virtual
-//                            @typecad/board module points here)
-//   .cuttlefish/board.json — the BoardConstants flat map (pins.all.*,
+//   .typecad-hal/board.ts   — typed pin/bus/LED/BUTTON exports (the virtual
+//                            '@typecad/hal' module resolves here via the
+//                            project tsconfig — the single import surface)
+//   .typecad-hal/board.json — the BoardConstants flat map (pins.all.*,
 //                            peripherals.*, zephyr.*) the transpiler's
 //                            resolveChipFromBoard reconstructs its chip
 //                            view from
@@ -22,13 +23,14 @@
 // matrices) are absent for every board alike.
 //
 // Pure: returns the file contents; the caller (cuttlefish config-loader via
-// the strategy hook, or `cuttlefish board regen`) writes them.
+// the strategy hook, or `typecad-hal board regen`) writes them.
 // ----------------------------------------------------------------------------
 import { parseAsBuiltJson } from './as-built.js';
 import { loadBoardCatalogOverlay, GENERATOR_REV, boardRecordFingerprint, factsFingerprint, findBoardInCatalog, socBusLabelsFromTree, } from '@typecad/cuttlefish/board-catalog';
+import { getBoardGateData } from '@typecad/cuttlefish/board-gate';
 /**
  * The catalog lookups resolve against the local overlay — the user's own
- * Zephyr tree (`cuttlefish board sync`, auto-refreshed when the tree
+ * Zephyr tree (`typecad-hal board sync`, auto-refreshed when the tree
  * moves). There is no compiled-in database: a machine with no tree and no
  * overlay has no boards, and the error below says exactly that.
  */
@@ -36,7 +38,7 @@ function activeBoardData() {
     const data = loadBoardCatalogOverlay()?.data;
     if (!data) {
         throw new Error(`No board catalog on this machine. The catalog is generated from your Zephyr tree —\n` +
-            `run 'cuttlefish board sync' (or point CUTTLEFISH_BOARD_CATALOG at a catalog file).`);
+            `run 'typecad-hal board sync' (or point TYPECAD_HAL_BOARD_CATALOG at a catalog file).`);
     }
     return data;
 }
@@ -75,7 +77,7 @@ export function nrfSaadcAinPads(soc, identifier) {
  * S3/C3/C6/H2 dropped it. Sourced from the HAL's dac_periph.c
  * (`dac_channel_io_num[]`), like the nRF SAADC table is from the PS.
  */
-export function esp32DacPins(soc) {
+function esp32DacPins(soc) {
     const table = {
         esp32: [[0, 25], [1, 26]],
         esp32s2: [[0, 17], [1, 18]],
@@ -408,7 +410,7 @@ export function parsePinName(soc, name) {
     return undefined;
 }
 /** Parse + shape-validate the facts file; a clear error names the file. */
-export function parseUserFactsJson(text, source = 'cuttlefish.facts.json') {
+export function parseUserFactsJson(text, source = 'typecad-hal.facts.json') {
     let parsed;
     try {
         parsed = JSON.parse(text);
@@ -445,6 +447,9 @@ export function userFactsForTarget(file, target) {
     return hit ? file.boards[hit] : undefined;
 }
 export function buildModule(entry, userFacts, factsSuffix = '', seedWarnings = []) {
+    // The ungated surface is derived from the project's own hal copy — same
+    // resolution (project → cwd → monorepo sibling) as the engine's HAL parser.
+    const { ungated: BOARD_UNGATED_EXPORTS, ungatedTypes: BOARD_UNGATED_TYPE_EXPORTS } = getBoardGateData();
     const soc = socOfTarget(entry.identifier);
     const conv = namingConvFor(soc);
     // ── Controller table + datasheet sweep (the same for every board) ──────
@@ -609,7 +614,7 @@ export function buildModule(entry, userFacts, factsSuffix = '', seedWarnings = [
                 adcSources.push(r.source);
         }
     }
-    // User facts (cuttlefish.facts.json) — the escape hatch. User routes win
+    // User facts (typecad-hal.facts.json) — the escape hatch. User routes win
     // PER PIN over every harvested source above, and each takeover is warned.
     // Seeded with the pinctrl harvest's own lint results (name↔value
     // disagreements — routes dropped as untrustworthy upstream of here).
@@ -679,7 +684,7 @@ export function buildModule(entry, userFacts, factsSuffix = '', seedWarnings = [
         if (siliconDac.length > 0 && !dacSources.includes('dac'))
             dacSources.push('dac');
     }
-    // User facts (cuttlefish.facts.json): dac channels win per pin, and the
+    // User facts (typecad-hal.facts.json): dac channels win per pin, and the
     // declared device joins the sources (no analogDevices cross-check — the
     // user vouches for it).
     if (userFacts?.dac) {
@@ -803,7 +808,7 @@ export function buildModule(entry, userFacts, factsSuffix = '', seedWarnings = [
         ...pins.map((p) => p.ident),
         'LED',
         'BUTTON',
-        // '@typecad/hal' imports — a connector silkscreen label can literally be
+        // '@typecad/hal/core' imports — a connector silkscreen label can literally be
         // 'Pin' (phyBOARD-Atlas), and `export const Pin` merges with the import.
         'Pin',
         'I2CBus',
@@ -811,6 +816,9 @@ export function buildModule(entry, userFacts, factsSuffix = '', seedWarnings = [
         'UART',
         'USBConsole',
         'PWM',
+        // The ungated re-export block: a label colliding with any re-exported
+        // hal name would be a duplicate module export.
+        ...BOARD_UNGATED_EXPORTS,
     ]);
     buses.i2c.forEach((_, i) => reservedNames.add(`I2C${i}`));
     buses.spi.forEach((_, i) => reservedNames.add(`SPI${i}`));
@@ -826,49 +834,149 @@ export function buildModule(entry, userFacts, factsSuffix = '', seedWarnings = [
             continue;
         connectorLabelOwner.set(label, pin);
     }
+    // ── Per-pin editor annotations ──────────────────────────────────────────
+    // The same harvested facts board.json carries, stamped as JSDoc on the
+    // datasheet pin exports so plain tsserver surfaces them in hover and
+    // completion detail — board intelligence with zero editor extension. Only
+    // pins WITH a fact (silicon route, any-pad matrix membership, bus role, or
+    // an alias) get a doc line: bare pads stay bare, and the absence of an
+    // annotation says "plain GPIO" without stamping it on every line. Facts and
+    // module derive from the same route sets below, so they cannot disagree.
+    const pwmRouteByPin = new Map(siliconPwm.map((s) => [s.pin, s]));
+    const adcRouteByPin = new Map(siliconAdc.map((s) => [s.pin, s]));
+    const dacRouteByPin = new Map(siliconDac.map((s) => [s.pin, s]));
+    // Any-pad PWM matrices (ESP32 LEDC, nRF psel, RP2 slices) ride global pad
+    // numbers — same base arithmetic the manifest's matrix pins use.
+    const matrixBase = controllers.find((c) => c.nodelabel === 'gpio0')?.minPin ?? 0;
+    const matrixPwmPins = pwmMatrix
+        ? new Set(pwmMatrix.pads.map((pad) => matrixBase + pad))
+        : undefined;
+    // Aliases (connector silkscreen labels, LED/BUTTON) keyed by the aliased
+    // pin's HAL number — connectorLabelOwner's values ARE the sweep's GenPin
+    // objects, so identity holds through the LED/BUTTON facts too.
+    const aliasesByPin = new Map();
+    const noteAlias = (pin, label) => {
+        if (!pin)
+            return;
+        const list = aliasesByPin.get(pin.halPin);
+        if (list)
+            list.push(label);
+        else
+            aliasesByPin.set(pin.halPin, [label]);
+    };
+    for (const [label, pin] of connectorLabelOwner)
+        noteAlias(pin, label);
+    if (ledPinFinal)
+        noteAlias(ledPinFinal, 'LED');
+    if (buttonPin)
+        noteAlias(buttonPin, 'BUTTON');
+    extraLedPins.forEach((p, i) => noteAlias(p, `LED${i + 1}`));
+    extraButtonPins.forEach((p, i) => noteAlias(p, `BUTTON${i + 1}`));
+    // Bus roles (SDA/SCL/MOSI/…) keyed by the route's pad NAME — best-effort
+    // uppercase match; pads whose spelling the pin sweep can't place simply
+    // carry no role line. (busPads is defined further down; this walks
+    // entry.busPins directly to stay above it.)
+    const rolesByPinName = new Map();
+    for (const b of entry.busPins ?? []) {
+        const index = buses[b.bus]?.indexOf(b.nodelabel) ?? -1;
+        if (index < 0)
+            continue;
+        const instance = `${b.bus.toUpperCase()}${index}`;
+        for (const route of b.routes) {
+            if (!route.pad || !route.role)
+                continue;
+            const name = route.pad.toUpperCase();
+            const role = `${instance} ${route.role.toUpperCase()}`;
+            const list = rolesByPinName.get(name);
+            if (list) {
+                if (!list.includes(role))
+                    list.push(role);
+            }
+            else {
+                rolesByPinName.set(name, [role]);
+            }
+        }
+    }
+    const pinDoc = (p) => {
+        const parts = [];
+        const pwm = pwmRouteByPin.get(p.halPin);
+        if (pwm)
+            parts.push(`PWM ${pwm.controller} ch${pwm.channel}`);
+        else if (pwmMatrix && matrixPwmPins?.has(p.halPin)) {
+            parts.push(`PWM ${pwmMatrix.controller} ch0-${pwmMatrix.channelCount - 1} (any pad)`);
+        }
+        const adc = adcRouteByPin.get(p.halPin);
+        // Primary-unit routes (pinctrl and ESP SARADC alike) omit the controller
+        // field — fall back to the pinctrl sources, then the ESP primary unit.
+        if (adc)
+            parts.push(`ADC ${adc.controller ?? adcSources[0] ?? espAdcUnit ?? 'adc'} ch${adc.channel}`);
+        const dac = dacRouteByPin.get(p.halPin);
+        if (dac)
+            parts.push(`DAC ch${dac.channel}`);
+        parts.push(...(rolesByPinName.get(p.name.toUpperCase()) ?? []));
+        const aliases = aliasesByPin.get(p.halPin);
+        if (aliases)
+            parts.push(`aliases: ${aliases.join(', ')}`);
+        return parts.length > 0 ? parts.join(' · ') : undefined;
+    };
     const ts = [];
-    ts.push(`// GENERATED by cuttlefish boardgen from the Zephyr board catalog —`);
+    ts.push(`// GENERATED by typecad-hal boardgen from the Zephyr board catalog —`);
     ts.push(`// ${entry.identifier} (${entry.name}, ${entry.vendor}).`);
-    ts.push(`// Regenerate with: npx cuttlefish board regen`);
+    ts.push(`// Regenerate with: npx typecad-hal board regen`);
     ts.push('');
-    ts.push(`import { Pin, I2CBus, SPIBus, UART${hasUsb ? ', USBConsole' : ''}${pwmLedSpecs.length > 0 ? ', PWM' : ''} } from '@typecad/hal';`);
+    // The generated module IS the user's '@typecad/hal' (the project tsconfig
+    // maps that specifier here), so it reaches the implementation package via
+    // the './core' subpath — the one specifier the paths mapping does not
+    // capture, avoiding a circular self-reference.
+    ts.push(`import { Pin, I2CBus, SPIBus, UART${hasUsb ? ', USBConsole' : ''}${pwmLedSpecs.length > 0 ? ', PWM' : ''} } from '@typecad/hal/core';`);
     ts.push('');
     // ── Hardware-class gateway ─────────────────────────────────────────────
-    // The board module is the NARROWED surface: every hardware class re-export
-    // here exists only when this board's facts support it, so importing
-    // unavailable hardware fails at module resolution (editor + transpile)
-    // instead of at a deep diagnostic. '@typecad/hal' stays the implementation
-    // package; user code imports hardware from '@typecad/board'.
+    // This module is the NARROWED surface behind the user's '@typecad/hal'
+    // import: every hardware class gated on board facts is re-exported below
+    // only when this board's facts support it, so importing unavailable
+    // hardware fails at module resolution (editor + transpile) instead of at
+    // a deep diagnostic. Everything not gated (the lists hal ships in
+    // gate.ts) is re-exported verbatim so the full authoring surface stays
+    // importable from the same specifier ('@typecad/hal' is the one specifier —
+    // the old '@typecad/board' alias was removed with the rename).
+    ts.push('// Always-available HAL surface (not gated on board facts).');
+    ts.push(`export { ${BOARD_UNGATED_EXPORTS.join(', ')} } from '@typecad/hal/core';`);
+    ts.push(`export type { ${BOARD_UNGATED_TYPE_EXPORTS.join(', ')} } from '@typecad/hal/core';`);
+    ts.push('');
     ts.push('// Hardware this board actually has — unavailable hardware is not importable.');
-    ts.push(`export { GPIO, Thread, Time, Sensor } from '@typecad/hal';`);
     if (wdtNodeLabel)
-        ts.push(`export { Watchdog } from '@typecad/hal';`);
+        ts.push(`export { Watchdog } from '@typecad/hal/core';`);
     if (siliconPwm.length > 0 || pwmLedSpecs.length > 0 || pwmMatrix)
-        ts.push(`export { PWM } from '@typecad/hal';`);
+        ts.push(`export { PWM } from '@typecad/hal/core';`);
     if (siliconAdc.length > 0)
-        ts.push(`export { ADC } from '@typecad/hal';`);
+        ts.push(`export { ADC } from '@typecad/hal/core';`);
     if (siliconDac.length > 0)
-        ts.push(`export { DAC } from '@typecad/hal';`);
+        ts.push(`export { DAC } from '@typecad/hal/core';`);
     if (buses.i2c.length > 0)
-        ts.push(`export { I2CTarget } from '@typecad/hal';`);
+        ts.push(`export { I2CTarget } from '@typecad/hal/core';`);
     if (buses.spi.length > 0)
-        ts.push(`export { SPITarget } from '@typecad/hal';`);
+        ts.push(`export { SPITarget } from '@typecad/hal/core';`);
     if (buses.uart.length > 0)
-        ts.push(`export { UART } from '@typecad/hal';`);
+        ts.push(`export { UART } from '@typecad/hal/core';`);
     if (hwtimerControllers.length > 0)
-        ts.push(`export { Counter } from '@typecad/hal';`);
+        ts.push(`export { Counter } from '@typecad/hal/core';`);
     if (hasUsb)
-        ts.push(`export { USBConsole } from '@typecad/hal';`);
+        ts.push(`export { USBConsole } from '@typecad/hal/core';`);
     // Store/File: a persisted backend needs a storage region — either the
     // board's own storage_partition (harvested reg) or a synthesizable one
     // (flash size known, no existing partition to collide with).
     if (entry.storageReg || (entry.flashKb && !entry.hasStoragePartition)) {
-        ts.push(`export { Store, File } from '@typecad/hal';`);
+        ts.push(`export { Store, File } from '@typecad/hal/core';`);
     }
     ts.push('');
     if (pins.length > 0) {
         ts.push(`// Datasheet-named pins (derived from the board's devicetree controllers)`);
+        ts.push(`// Pins with harvested facts carry them as JSDoc (hover shows routes/roles/aliases);`);
+        ts.push(`// a pin without a doc line is plain GPIO — no PWM/ADC/DAC route on this board.`);
         for (const p of pins) {
+            const doc = pinDoc(p);
+            if (doc)
+                ts.push(`/** ${doc} */`);
             ts.push(`export const ${p.ident} = Pin.fromPort('${p.name}');`);
         }
         ts.push('');
@@ -892,28 +1000,52 @@ export function buildModule(entry, userFacts, factsSuffix = '', seedWarnings = [
             extraPinDecls.push(p);
     }
     for (const p of extraPinDecls) {
-        ts.push(`/** ${p.name} (derived from the devicetree controller label). */`);
         ts.push(`export const ${p.ident} = Pin.fromPort('${p.name}');`);
     }
     if (ledPinFinal) {
-        ts.push(`/** On-board LED (${entry.led ? `devicetree ${entry.led.dtSpec}` : 'addressable strip — no gpio-leds node'}). */`);
+        ts.push(`/** On-board LED${entry.led ? '' : ' — addressable strip, this is its data pin'}. */`);
         ts.push(`export const LED = ${ledPinFinal.ident};`);
     }
     if (buttonPin) {
-        ts.push(`/** User button (devicetree ${entry.button?.dtSpec}). */`);
+        ts.push(`/** User button. */`);
         ts.push(`export const BUTTON = ${buttonPin.ident};`);
     }
     if (ledPinFinal || buttonPin || extraPinDecls.length > 0)
         ts.push('');
-    // Bus instance exports from the board's own DTS-wired controllers.
+    // Bus instance exports from the board's own DTS-wired controllers. When the
+    // harvest parsed a controller's pinctrl overrides, the JSDoc carries its pad
+    // routes ("SDA=PB7, SCL=PB8") — the same facts the pins.<bus> conflict-map
+    // constants hold, surfaced for hover.
+    const busPadPairs = (kind, nodelabel) => (entry.busPins ?? [])
+        .filter((b) => b.bus === kind && b.nodelabel === nodelabel)
+        .flatMap((b) => b.routes)
+        .filter((r) => r.pad && r.role)
+        .map((r) => `${r.role.toUpperCase()}=${r.pad}`);
+    const busDoc = (kind, index, nodelabel) => {
+        const label = kind === 'i2c' ? `I2C bus ${index}` : kind === 'spi' ? `SPI bus ${index}` : `UART ${index}`;
+        const pads = busPadPairs(kind, nodelabel);
+        return `Board-wired ${label}${pads.length > 0 ? ` (${pads.join(', ')})` : ''}.`;
+    };
     const busLines = [];
-    buses.i2c.forEach((_, i) => busLines.push(`export const I2C${i} = new I2CBus('I2C${i}');`));
-    buses.spi.forEach((_, i) => busLines.push(`export const SPI${i} = new SPIBus('SPI${i}');`));
-    buses.uart.forEach((_, i) => busLines.push(`export const UART${i} = new UART('UART${i}');`));
+    buses.i2c.forEach((nodelabel, i) => {
+        busLines.push(`/** ${busDoc('i2c', i, nodelabel)} */`);
+        busLines.push(`export const I2C${i} = new I2CBus('I2C${i}');`);
+    });
+    buses.spi.forEach((nodelabel, i) => {
+        busLines.push(`/** ${busDoc('spi', i, nodelabel)} */`);
+        busLines.push(`export const SPI${i} = new SPIBus('SPI${i}');`);
+    });
+    buses.uart.forEach((nodelabel, i) => {
+        busLines.push(`/** ${busDoc('uart', i, nodelabel)} */`);
+        busLines.push(`export const UART${i} = new UART('UART${i}');`);
+    });
     // USB CDC instance (the thin HAL's USBConsole): the board's DTS turns the
-    // device controller on (zephyr_udc0 status okay).
-    if (hasUsb)
+    // device controller on (zephyr_udc0 status okay). CDC has no pinctrl pad
+    // routes — the console rides the controller's silicon-fixed DP/DM pads.
+    if (hasUsb) {
+        busLines.push(`/** USB serial console — the board's USB connector (no pin to configure). */`);
         busLines.push(`export const USB0 = new USBConsole('USB0');`);
+    }
     // PWM-driven LEDs (pwm-leds): addressed by the board's own devicetree
     // alias (DT_ALIAS(pwm_led0) in the lowering) — no overlay needed. The
     // construction period comes from the DTS cell when it is a plain number
@@ -922,7 +1054,7 @@ export function buildModule(entry, userFacts, factsSuffix = '', seedWarnings = [
     pwmLedSpecs.forEach((l, i) => {
         const period = l.periodNs ?? 1_000_000;
         const name = i === 0 ? 'PWMLED' : `PWMLED${i}`;
-        busLines.push(`/** Board PWM LED (devicetree ${l.alias}${l.flags?.length ? ', ' + l.flags.join(' ') : ''}). */`);
+        busLines.push(`/** Board PWM-driven LED (already constructed — call setDuty() to dim it). */`);
         busLines.push(`export const ${name} = new PWM(${8192 + i}, { periodNs: ${period} });`);
     });
     if (busLines.length > 0) {
@@ -1126,16 +1258,67 @@ export function buildModule(entry, userFacts, factsSuffix = '', seedWarnings = [
     });
     // Bus controllers the board's own DTS wires up — resolveChipFromBoard
     // reconstructs the bus lists from these, and the overlays enable the
-    // nodes the program uses.
+    // nodes the program uses. Each controller also carries its board-DTS
+    // pinctrl routes when the harvest parsed them (`pinctrl` = the route
+    // names, `pads` = `role=PAD` pairs) — the diagnostics report's
+    // peripheral-usage table and the pins.<bus> conflict-map read them.
+    const busPads = (kind, nodelabel) => (entry.busPins ?? []).filter((b) => b.bus === kind && b.nodelabel === nodelabel).flatMap((b) => b.routes);
+    const busPinMap = (kind) => {
+        const parts = [];
+        buses[kind].forEach((nodelabel, i) => {
+            const pairs = busPads(kind, nodelabel)
+                .filter((r) => r.pad && r.role)
+                .map((r) => `${r.role}=${r.pad}`);
+            if (pairs.length > 0)
+                parts.push(`${i}:${pairs.join(',')}`);
+        });
+        return parts.join(';');
+    };
     buses.i2c.forEach((nodelabel, i) => {
         constants[`zephyr.i2c.controllers.${i}.nodeLabel`] = nodelabel;
+        const routes = busPads('i2c', nodelabel);
+        if (routes.length > 0) {
+            constants[`zephyr.i2c.controllers.${i}.pinctrl`] = routes.map((r) => r.name).join(',');
+            constants[`zephyr.i2c.controllers.${i}.pads`] = routes.filter((r) => r.pad).map((r) => `${r.role ?? ''}=${r.pad}`).join(',');
+        }
     });
     buses.spi.forEach((nodelabel, i) => {
         constants[`zephyr.spi.controllers.${i}.nodeLabel`] = nodelabel;
+        const routes = busPads('spi', nodelabel);
+        if (routes.length > 0) {
+            constants[`zephyr.spi.controllers.${i}.pinctrl`] = routes.map((r) => r.name).join(',');
+            constants[`zephyr.spi.controllers.${i}.pads`] = routes.filter((r) => r.pad).map((r) => `${r.role ?? ''}=${r.pad}`).join(',');
+        }
     });
     buses.uart.forEach((nodelabel, i) => {
         constants[`zephyr.uart.controllers.${i}.nodeLabel`] = nodelabel;
+        const routes = busPads('uart', nodelabel);
+        if (routes.length > 0) {
+            constants[`zephyr.uart.controllers.${i}.pinctrl`] = routes.map((r) => r.name).join(',');
+            constants[`zephyr.uart.controllers.${i}.pads`] = routes.filter((r) => r.pad).map((r) => `${r.role ?? ''}=${r.pad}`).join(',');
+        }
     });
+    // The board's console controller (chosen zephyr,console) — the
+    // diagnostics annotate the UART instance the bootloader logs on.
+    if (entry.console)
+        constants['zephyr.console'] = entry.console;
+    // Bus pad conflict maps (analyzeResources): "<inst>:<role>=<PAD>,...;..."
+    const i2cPinMap = busPinMap('i2c');
+    const spiPinMap = busPinMap('spi');
+    const uartPinMap = busPinMap('uart');
+    if (i2cPinMap)
+        constants['pins.i2c'] = i2cPinMap;
+    if (spiPinMap)
+        constants['pins.spi'] = spiPinMap;
+    if (uartPinMap)
+        constants['pins.uart'] = uartPinMap;
+    // Board silicon identity for the diagnostics metadata (the report's
+    // SRAM/flash context) — flash is a devicetree fact, sram/clock are not
+    // harvested and stay absent.
+    if (soc)
+        constants['mcu'] = soc;
+    if (entry.flashKb)
+        constants['memory.flash'] = entry.flashKb * 1024;
     // USB device (CDC-ACM): the board's DTS turned the controller on.
     if (hasUsb) {
         constants['zephyr.usb.controller'] = entry.usbController ?? 'zephyr_udc0';
@@ -1202,7 +1385,7 @@ export function buildModule(entry, userFacts, factsSuffix = '', seedWarnings = [
         constants,
         // Source fingerprint: covers the record content, the extraction
         // revision, and the tree provenance (when the record came from a
-        // catalog). `cuttlefish build` recomputes it cheaply and regenerates
+        // catalog). `typecad-hal build` recomputes it cheaply and regenerates
         // this module when it moves — a board change in the config, the catalog
         // overlay, or the Zephyr tree itself recreates the module.
         source: {
@@ -1227,8 +1410,8 @@ export function generateBoard(target, opts) {
     if (!found) {
         const hint = loadBoardCatalogOverlay()
             ? `'${target}' is not a board target in the current catalog. ` +
-                `It may be new in your Zephyr tree — run 'cuttlefish board sync' and retry.`
-            : `No board catalog on this machine. Run 'cuttlefish board sync' first.`;
+                `It may be new in your Zephyr tree — run 'typecad-hal board sync' and retry.`
+            : `No board catalog on this machine. Run 'typecad-hal board sync' first.`;
         throw new Error(hint);
     }
     // The as-built snapshot (this project's last successful build's resolved
@@ -1250,7 +1433,7 @@ export function generateBoard(target, opts) {
             asBuiltWarnings.push(`ignoring as-built snapshot: ${err.message}`);
         }
     }
-    // The project's cuttlefish.facts.json, when present: the section for THIS
+    // The project's typecad-hal.facts.json, when present: the section for THIS
     // board merges into the manifest (user routes win per pin), and the raw
     // text hashes into the module's source fingerprint so edits regenerate.
     let facts;

package/dist/chips/types.d.ts

@@ -436,7 +436,7 @@ export interface ZephyrChipDescriptor {
      * verified with the board, instead of in user configs. One probe method
      * serves BOTH flashing and debugging (the same attach session); entries
      * that cannot debug (bootloaders) set `debug: false`. Users select one via
-     * `zephyr.probe` in cuttlefish.config.ts or `--probe` on the CLI;
+     * `zephyr.probe` in typecad-hal.config.ts or `--probe` on the CLI;
      * `zephyr.runner`/`runnerArgs` remain the raw escape hatch underneath.
      */
     readonly probeMethods?: readonly ZephyrProbeMethod[];

package/dist/debug-codegen.js

@@ -6,7 +6,7 @@
 // stdlibSupport.hasIostream=false), so the GenericStrategy's std::cout fallback
 // used by the debug preprocessor would NOT compile. This module routes every
 // debug line through printk("...\n") — the always-available Zephyr console,
-// with no CONFIG_CONSOLE dependency — so `cuttlefish build --debug` produces
+// with no CONFIG_CONSOLE dependency — so `typecad-hal build --debug` produces
 // compiling output.
 //
 // The halt primitive is __tc_debug_wait_for_continue() (emitted in

package/dist/display/touch-adapter.js

@@ -1,5 +1,5 @@
 // ---------------------------------------------------------------------------
-// Zephyr touch adapters for the Cuttlefish UI rendering pipeline.
+// Zephyr touch adapters for the TypeCAD UI rendering pipeline.
 //
 // Two controllers, both driven directly (polling, no in-tree driver):
 //   - FT6336U capacitive over I2C (i2c_write_read_dt)