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

package/src/boardgen.ts

@@ -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,7 +23,7 @@
 // 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 type { BoardDataEntry } from '@typecad/cuttlefish/board-catalog';
@@ -36,6 +37,7 @@ import {
   socBusLabelsFromTree,
 } from '@typecad/cuttlefish/board-catalog';
 import type { ZephyrGpioController, ZephyrProbeMethod } from './chips/types.js';
+import { getBoardGateData } from '@typecad/cuttlefish/board-gate';
 
 /** A generated pin: schematic name, JS-safe identifier, HAL number. */
 interface GenPin {
@@ -56,7 +58,7 @@ export interface GeneratedBoard {
 
 /**
  * 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.
  */
@@ -65,7 +67,7 @@ function activeBoardData(): Record<string, BoardDataEntry> {
   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;
@@ -108,7 +110,7 @@ export function nrfSaadcAinPads(soc: string, identifier: string): readonly [numb
  * 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: string): readonly [number, number][] | undefined {
+function esp32DacPins(soc: string): readonly [number, number][] | undefined {
   const table: Record<string, readonly [number, number][]> = {
     esp32: [[0, 25], [1, 26]],
     esp32s2: [[0, 17], [1, 18]],
@@ -439,7 +441,7 @@ export function parsePinName(soc: string, name: string): { controller: string; p
  * generated off the installed SDK's tree) and contract records (custom PCB
  * specs) both route through here.
  */
-// ── User facts (cuttlefish.facts.json) ──────────────────────────────────────
+// ── User facts (typecad-hal.facts.json) ──────────────────────────────────────
 // The project-local escape hatch: facts the pipeline has not (or cannot)
 // harvest, declared per board and merged into the manifest BEFORE anything
 // else runs — board module exports, capability flags, validation, lowering
@@ -464,13 +466,13 @@ export interface UserBoardFacts {
   };
 }
 
-/** The whole cuttlefish.facts.json shape. */
+/** The whole typecad-hal.facts.json shape. */
 export interface UserFactsFile {
   boards: Record<string, UserBoardFacts>;
 }
 
 /** Parse + shape-validate the facts file; a clear error names the file. */
-export function parseUserFactsJson(text: string, source = 'cuttlefish.facts.json'): UserFactsFile {
+export function parseUserFactsJson(text: string, source = 'typecad-hal.facts.json'): UserFactsFile {
   let parsed: unknown;
   try {
     parsed = JSON.parse(text);
@@ -511,7 +513,11 @@ export function buildModule(
   userFacts?: UserBoardFacts,
   factsSuffix = '',
   seedWarnings: readonly string[] = [],
-): GeneratedBoard {  const soc = socOfTarget(entry.identifier);
+): GeneratedBoard {
+  // 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) ──────
@@ -667,7 +673,7 @@ export function buildModule(
       if (!adcSources.includes(r.source)) 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).
@@ -735,7 +741,7 @@ export function buildModule(
     }
     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) {
@@ -858,7 +864,7 @@ export function buildModule(
     ...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',
@@ -866,6 +872,9 @@ export function buildModule(
     '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}`));
@@ -879,40 +888,144 @@ export function buildModule(
     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<number, string[]>();
+  const noteAlias = (pin: GenPin | undefined, label: string): void => {
+    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<string, string[]>();
+  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: GenPin): string | undefined => {
+    const parts: string[] = [];
+    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: string[] = [];
-  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';`);
-  if (siliconPwm.length > 0 || pwmLedSpecs.length > 0 || pwmMatrix) ts.push(`export { PWM } from '@typecad/hal';`);
-  if (siliconAdc.length > 0) ts.push(`export { ADC } from '@typecad/hal';`);
-  if (siliconDac.length > 0) ts.push(`export { DAC } from '@typecad/hal';`);
-  if (buses.i2c.length > 0) ts.push(`export { I2CTarget } from '@typecad/hal';`);
-  if (buses.spi.length > 0) ts.push(`export { SPITarget } from '@typecad/hal';`);
-  if (buses.uart.length > 0) ts.push(`export { UART } from '@typecad/hal';`);
-  if (hwtimerControllers.length > 0) ts.push(`export { Counter } from '@typecad/hal';`);
-  if (hasUsb) ts.push(`export { USBConsole } from '@typecad/hal';`);
+  if (wdtNodeLabel) ts.push(`export { Watchdog } from '@typecad/hal/core';`);
+  if (siliconPwm.length > 0 || pwmLedSpecs.length > 0 || pwmMatrix) ts.push(`export { PWM, Servo } from '@typecad/hal/core';`);
+  if (siliconAdc.length > 0) ts.push(`export { ADC } from '@typecad/hal/core';`);
+  if (siliconDac.length > 0) ts.push(`export { DAC } from '@typecad/hal/core';`);
+  // The responder rides the same wired-bus fact as I2CTarget — target-mode
+  // support is a controller-driver property discovered at registration
+  // (-ENOSYS prints loudly), never a board-name gate.
+  if (buses.i2c.length > 0) ts.push(`export { I2CTarget, I2CResponder } from '@typecad/hal/core';`);
+  if (buses.spi.length > 0) ts.push(`export { SPITarget } from '@typecad/hal/core';`);
+  if (buses.uart.length > 0) ts.push(`export { UART } from '@typecad/hal/core';`);
+  if (hwtimerControllers.length > 0) ts.push(`export { Counter } from '@typecad/hal/core';`);
+  // Clock rides the same free-counter facts (the zephyr,rtc-counter shim
+  // wraps the counter when the board ships no hardware rtc alias).
+  if (hwtimerControllers.length > 0) ts.push(`export { Clock } from '@typecad/hal/core';`);
+  // CAN rides the harvested controller nodes (ESP32 TWAI, STM32 bxCAN,
+  // NXP FlexCAN…); a SoC with none exports nothing.
+  if ((entry.canNodes ?? []).length > 0) ts.push(`export { CAN } from '@typecad/hal/core';`);
+  // I2S rides the harvested i2s@ controllers.
+  if ((entry.i2sNodes ?? []).length > 0) ts.push(`export { I2S } from '@typecad/hal/core';`);
+  // Power rides the SoC's declared cpu-power-states (both the ESP32 family's
+  // standby + soft-off pair and STM32's suspend-to-idle count; a SoC with no
+  // declared states exports nothing).
+  if ((entry.powerStates ?? []).length > 0) ts.push(`export { Power } from '@typecad/hal/core';`);
+  // KEY/MOUSE are ungated token tables — the derived always-available
+  // re-export line above already carries them on every board; only the HID
+  // device classes ride the USB gate.
+  if (hasUsb) ts.push(`export { USBConsole, Keyboard, Mouse } 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('');
@@ -932,27 +1045,53 @@ export function buildModule(
     if (!pins.some((x) => x.ident === p.ident) && !extraPinDecls.some((x) => x.ident === p.ident)) 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: 'i2c' | 'spi' | 'uart', nodelabel: string): string[] =>
+    (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: 'i2c' | 'spi' | 'uart', index: number, nodelabel: string): string => {
+    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: string[] = [];
-  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) busLines.push(`export const USB0 = new USBConsole('USB0');`);
+  // 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
@@ -962,7 +1101,7 @@ export function buildModule(
   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) {
@@ -986,12 +1125,15 @@ export function buildModule(
     // GPIO driver API (`gpio_pin_configure` flags + `gpio_pin_interrupt_configure`):
     // every GPIO controller implements them, so they are universally true —
     // a platform fact, not a per-pad one. Analog/PWM ride the harvested
-    // silicon routes (honest per-pad facts).
+    // silicon routes (honest per-pad facts); PWM counts both route kinds —
+    // fixed pinctrl routes AND any-pad matrices (ESP32 LEDC, nRF psel), the
+    // same set union the pin JSDoc and the PWM export gate read, so the
+    // hover annotation and the capability flag cannot disagree.
     constants[`pins.all.${i}.capabilities.digitalInput`] = true;
     constants[`pins.all.${i}.capabilities.digitalOutput`] = true;
     constants[`pins.all.${i}.capabilities.analogInput`] = siliconAdcPins.has(p.halPin);
     constants[`pins.all.${i}.capabilities.analogOutput`] = siliconDacPins.has(p.halPin);
-    constants[`pins.all.${i}.capabilities.pwm`] = siliconPwmPins.has(p.halPin);
+    constants[`pins.all.${i}.capabilities.pwm`] = siliconPwmPins.has(p.halPin) || (matrixPwmPins?.has(p.halPin) ?? false);
     constants[`pins.all.${i}.capabilities.interrupt`] = true;
     constants[`pins.all.${i}.capabilities.pullUp`] = true;
     constants[`pins.all.${i}.capabilities.pullDown`] = true;
@@ -1000,6 +1142,34 @@ export function buildModule(
     constants[`pins.all.${i}.capabilities.touch`] = false;
     constants[`pins.all.${i}.capabilities.openDrain`] = true;
   });
+  // CPU power states — the harvested PM capability facts (which levels
+  // exist, their idle timing, and whether the automatic policy may enter
+  // them; ESP32's soft-off is explicit-entry only).
+  const powerStates = entry.powerStates ?? [];
+  powerStates.forEach((ps, i) => {
+    constants[`zephyr.power.states.${i}.name`] = ps.name;
+    if (ps.minResidencyUs !== undefined) constants[`zephyr.power.states.${i}.minResidencyUs`] = ps.minResidencyUs;
+    if (ps.exitLatencyUs !== undefined) constants[`zephyr.power.states.${i}.exitLatencyUs`] = ps.exitLatencyUs;
+    constants[`zephyr.power.states.${i}.enabled`] = ps.enabled;
+  });
+  if (powerStates.length > 0) {
+    constants['zephyr.power.softOff'] = powerStates.some((ps) => ps.name === 'soft-off');
+  }
+  if (entry.rtcWakeTimer) constants['zephyr.power.wakeTimer'] = true;
+  // CAN controllers — the harvested labeled nodes (the CAN class gate). The
+  // ESP32 TWAI pads ride along: loopback overlays route both TWAI functions
+  // onto the TX pad.
+  (entry.canNodes ?? []).forEach((c, i) => {
+    constants[`zephyr.can.controllers.${i}.nodeLabel`] = c.nodeLabel;
+    constants[`zephyr.can.controllers.${i}.compatible`] = c.compatible;
+    if (c.txPad !== undefined) constants[`zephyr.can.controllers.${i}.txPad`] = c.txPad;
+    if (c.rxPad !== undefined) constants[`zephyr.can.controllers.${i}.rxPad`] = c.rxPad;
+  });
+  // I2S controllers — the harvested labeled nodes (the I2S class gate).
+  (entry.i2sNodes ?? []).forEach((c, i) => {
+    constants[`zephyr.i2s.controllers.${i}.nodeLabel`] = c.nodeLabel;
+    constants[`zephyr.i2s.controllers.${i}.compatible`] = c.compatible;
+  });
   constants['peripherals.i2c.count'] = buses.i2c.length;
   constants['peripherals.spi.count'] = buses.spi.length;
   constants['peripherals.uart.count'] = buses.uart.length;
@@ -1161,16 +1331,61 @@ export function buildModule(
 
   // 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: 'i2c' | 'spi' | 'uart', nodelabel: string) =>
+    (entry.busPins ?? []).filter((b) => b.bus === kind && b.nodelabel === nodelabel).flatMap((b) => b.routes);
+  const busPinMap = (kind: 'i2c' | 'spi' | 'uart'): string => {
+    const parts: string[] = [];
+    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) {
@@ -1234,7 +1449,7 @@ export function buildModule(
     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: {
@@ -1264,8 +1479,8 @@ export function generateBoard(
   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
@@ -1286,7 +1501,7 @@ export function generateBoard(
       asBuiltWarnings.push(`ignoring as-built snapshot: ${(err as Error).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: UserBoardFacts | undefined;

package/src/chips/resolve.ts

@@ -230,6 +230,24 @@ export function resolveChipFromBoard(
   // (+ optional vid/pid for the device descriptor).
   const usbController = bc.get('zephyr.usb.controller') as string | undefined;
   const usbCdcInstances = bc.get('zephyr.usb.cdcInstances') as number | undefined;
+  const wakeTimer = bc.get('zephyr.power.wakeTimer') as boolean | undefined;
+  const i2sControllers: { nodeLabel: string; compatible: string }[] = [];
+  for (let ii = 0; bc.get(`zephyr.i2s.controllers.${ii}.nodeLabel`) !== undefined; ii++) {
+    i2sControllers.push({
+      nodeLabel: String(bc.get(`zephyr.i2s.controllers.${ii}.nodeLabel`)),
+      compatible: String(bc.get(`zephyr.i2s.controllers.${ii}.compatible`)),
+    });
+  }
+  const canControllers: { nodeLabel: string; compatible: string; txPad?: number; rxPad?: number }[] = [];
+  for (let ci = 0; bc.get(`zephyr.can.controllers.${ci}.nodeLabel`) !== undefined; ci++) {
+    canControllers.push({
+      nodeLabel: String(bc.get(`zephyr.can.controllers.${ci}.nodeLabel`)),
+      compatible: String(bc.get(`zephyr.can.controllers.${ci}.compatible`)),
+      ...(bc.get(`zephyr.can.controllers.${ci}.txPad`) !== undefined ? { txPad: Number(bc.get(`zephyr.can.controllers.${ci}.txPad`)) } : {}),
+      ...(bc.get(`zephyr.can.controllers.${ci}.rxPad`) !== undefined ? { rxPad: Number(bc.get(`zephyr.can.controllers.${ci}.rxPad`)) } : {}),
+    });
+  }
+
   const usbVid = bc.get('zephyr.usb.vid') as string | undefined;
   const usbPid = bc.get('zephyr.usb.pid') as string | undefined;
   // Optional 1200-baud touch-to-reset data (BOSSA-bootloader boards).
@@ -367,6 +385,9 @@ export function resolveChipFromBoard(
     ...(storageOffset != null && storageSize != null
       ? { storage: { offset: storageOffset, size: storageSize, ...(storagePreexisting ? { preexisting: true } : {}) } }
       : {}),
+    ...(wakeTimer ? { powerWakeTimer: true } : {}),
+    ...(canControllers.length > 0 ? { can: { controllers: canControllers } } : {}),
+    ...(i2sControllers.length > 0 ? { i2s: { controllers: i2sControllers } } : {}),
     ...(usbController && usbCdcInstances && usbCdcInstances > 0
       ? {
           usb: {

package/src/chips/types.ts

@@ -241,6 +241,15 @@ export interface ZephyrDacChannel {
  * Pure-data descriptor for a Zephyr board + its SoC's peripheral layout.
  */
 export interface ZephyrChipDescriptor {
+  /** The SoC's RTC wake timer (ESP32 family rtc_timer fact) — Power.offFor
+   *  arms it (esp_sleep_enable_timer_wakeup) before soft-off. */
+  readonly powerWakeTimer?: boolean;
+  /** CAN controllers (harvested labeled can@ nodes) — the lowering
+   *  addresses the first by its DT nodelabel. */
+  readonly can?: { controllers: readonly { nodeLabel: string; compatible: string; txPad?: number; rxPad?: number }[] };
+  /** I2S controllers (harvested labeled i2s@ nodes) — the lowering
+   *  addresses each by its DT nodelabel. */
+  readonly i2s?: { controllers: readonly { nodeLabel: string; compatible: string }[] };
   /** Zephyr board target (the `west build -b <id>` argument), e.g. 'xiao_ble'. */
   readonly id: string;
   /** SoC family, e.g. 'nrf52840'. */
@@ -446,7 +455,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[];