basalt-ui 1.29.2 → 1.30.1

package/src/charts/primitives/ChartFrame.tsx

@@ -6,11 +6,12 @@ import { useChartSize } from '../hooks/useChartSize'
 import { deriveLegend } from '../series'
 import type { ChartLegendConfig, LegendPlacement, SeriesStyle } from '../series'
 import {
-  chartTierMetrics,
-  legendEntryCap,
   resolveChartTier,
+  resolveFrameHeight,
+  resolveLegendRollup,
   resolvePlotRect,
 } from './chart-frame-layout'
+import type { ResponsiveChartHeight } from './chart-frame-layout'
 import { ChartTierProvider } from './chart-tier'
 import { ChartLegend } from './ChartLegend'
 import { ChartEmpty, ChartError, ChartPending, resolveChartState } from './ChartPending'
@@ -18,7 +19,13 @@ import type { ChartState } from './ChartPending'
 
 /** Re-exported for `ChartFrame.test.tsx` and any other consumer that previously reached these
  * through `ChartFrame` — the layout math itself lives in `./chart-frame-layout` (pure, DOM-free). */
-export { legendEntryCap, resolvePlotRect, resolveChartTier } from './chart-frame-layout'
+export {
+  legendEntryCap,
+  resolveLegendRollup,
+  resolvePlotRect,
+  resolveChartTier,
+} from './chart-frame-layout'
+export type { ResponsiveChartHeight } from './chart-frame-layout'
 
 const DEFAULT_HEIGHT = 240
 const DEFAULT_MIN_WIDTH = 200
@@ -28,7 +35,18 @@ const DEFAULT_MIN_WIDTH = 200
 export type ChartFrameLegend = {
   /** Default 'bottom'. */
   placement?: LegendPlacement
-  /** Wrap cap → "+N more" rollup at high cardinality. */
+  /**
+   * Wrap cap → "+N more" rollup at high cardinality.
+   *
+   * An explicit value WINS OUTRIGHT — over the phone tier's two-row default (`chartTierMetrics`)
+   * AND over a `fill` frame's measured fit (`legendEntryCap`). 1.30.0 fixed only the first half:
+   * the fit still ran `Math.min(fitted, caller)` on top, so meteo's 7-entry meteogram legend in a
+   * 150px docked row rendered 2 entries at `maxRows` 3, 6 AND 99 — five series drawn in colours
+   * nothing named. Both losers are DEFAULTS (the tier's, and `VX.minPlotHeight`); this is the one
+   * number a caller stated, so under `fill` the PLOT yields the height instead
+   * ({@link resolvePlotRect}'s `legendWins`). State a number too large for the box and the plot
+   * gets what is left — visible, and yours.
+   */
   maxRows?: number
   /** Visually separate role: series | overlay | reference. */
   groups?: boolean
@@ -47,8 +65,16 @@ export type ChartFrameLegend = {
 export type ChartFrameProps = BasaltProps & {
   /** Series identity — drives the derived legend. Pass the SAME array the kind draws + tooltips from. */
   series: readonly SeriesStyle[]
-  /** Fixed height in pixels. Used when neither `aspectRatio` nor `fill` is set. Default 240. */
-  height?: number
+  /**
+   * Height in pixels, or one per size step. Used when neither `aspectRatio` nor `fill` is set.
+   * Default 240.
+   *
+   * `{ base: 180, md: 260 }` is the declarative escape from a page of fixed-height charts: the
+   * steps are compared against the frame's own MEASURED width, not the viewport, so a chart squeezed
+   * by a `PageAside` gets the short height on a desktop too. A plain number is unchanged and stays
+   * supported ({@link resolveFrameHeight}).
+   */
+  height?: number | ResponsiveChartHeight
   /** height = Math.round(containerWidth / aspectRatio). Ignored when `fill` is set. */
   aspectRatio?: number
   /** Fill the parent flex/grid cell's measured height instead of a fixed/derived one. */
@@ -206,49 +232,37 @@ export function ChartFrame({
     ? containerH
     : aspectRatio !== undefined
       ? Math.round(containerW / aspectRatio)
-      : (height ?? DEFAULT_HEIGHT)
+      : resolveFrameHeight(height ?? DEFAULT_HEIGHT, containerW)
 
   const sideLegendWidth = legendVisible && vertical ? legendW : 0
   const topBottomLegendHeight = legendVisible && !vertical ? legendH : 0
 
+  const legendItems = legend === false ? [] : deriveLegend(series)
+  const togglable = legend !== false && (legend.toggle ?? legendItems.length > 1)
+
+  // The cap, and who pays for it — one pure decision ({@link resolveLegendRollup} states the three
+  // cases and why the composition, not either half, is what shipped broken). A fixed-height frame
+  // grows around its legend; a `fill` one cannot, so its legend rolls up to the measured fit
+  // instead of eating the plot — unless the caller stated a number, which nothing trims and the
+  // plot pays for. Top/bottom only: a side legend costs width, not height.
+  const { maxRows, legendWins } = resolveLegendRollup({
+    ...(legend !== false && legend.maxRows !== undefined && { statedMaxRows: legend.maxRows }),
+    tier,
+    fillBand: legendVisible && fill && !vertical,
+    items: legendItems,
+    containerW,
+    available: resolvedHeight - VX.minPlotHeight,
+  })
+
   const plot = resolvePlotRect({
     containerW,
     resolvedHeight,
     minWidth,
     sideLegendWidth,
     topBottomLegendHeight,
+    ...(legendWins && { legendWins }),
   })
 
-  const legendItems = legend === false ? [] : deriveLegend(series)
-  const togglable = legend !== false && (legend.toggle ?? legendItems.length > 1)
-
-  // A fixed-height frame grows around its legend; a `fill` one cannot, so its legend rolls up
-  // instead of eating the plot (see `legendEntryCap`). Top/bottom only — a side legend costs
-  // width, not height.
-  // The tier's own cap folds in as an upper bound BEFORE the fill measurement, so a phone-width
-  // `fill` frame can only ever roll up further, never less (`chartTierMetrics`).
-  const tierMaxRows = chartTierMetrics(tier).legendMaxRows
-  const callerMaxRows =
-    legend === false
-      ? undefined
-      : legend.maxRows === undefined
-        ? tierMaxRows
-        : tierMaxRows === undefined
-          ? legend.maxRows
-          : Math.min(legend.maxRows, tierMaxRows)
-
-  const maxRows =
-    legend === false
-      ? undefined
-      : fill && !vertical
-        ? legendEntryCap({
-            items: legendItems,
-            containerW,
-            available: resolvedHeight - VX.minPlotHeight,
-            ...(callerMaxRows !== undefined && { callerMaxRows }),
-          })
-        : callerMaxRows
-
   const legendNode =
     legend === false || resolvedState !== null ? null : (
       <div ref={legendRef} style={legendWrapperStyle(vertical)}>

package/src/charts/primitives/chart-frame-layout.ts

@@ -39,6 +39,70 @@ export function resolveChartTier(containerW: number): ChartTier {
   return containerW > 0 && containerW < VX.phoneChartWidth ? 'phone' : 'desktop'
 }
 
+/**
+ * A chart height stated per size step instead of as one number — the declarative escape from "every
+ * chart on this page is 260px tall on a 375px phone too".
+ *
+ * `base` is required and is the height a box narrower than every named step gets; each further key
+ * is the height from that step UP. Keys are Mantine's breakpoint names so a consumer writes the
+ * vocabulary they already write, and nothing more than `sm`/`md`/`lg` is offered: `xs`/`xl` would
+ * be two more rungs nobody has asked a chart to have.
+ *
+ * ```tsx
+ * <ChartFrame series={series} height={{ base: 180, md: 260 }}>{…}</ChartFrame>
+ * ```
+ */
+export type ResponsiveChartHeight = {
+  /** Below the narrowest STATED step — and NOT the first-frame value; see {@link resolveFrameHeight}. */
+  base: number
+  /** From 768px of MEASURED container width up. */
+  sm?: number
+  /** From 992px up. */
+  md?: number
+  /** From 1200px up. */
+  lg?: number
+}
+
+/**
+ * The measured CONTAINER width, in px, each {@link ResponsiveChartHeight} key takes effect at.
+ *
+ * The numbers are what Mantine's `sm`/`md`/`lg` breakpoints resolve to at the 16px initial font
+ * size, so a consumer's mental model transfers — but they are compared against the element's own
+ * MEASURED box, never the viewport, for the reason {@link resolveChartTier} states: a chart in a
+ * `PageAside`-squeezed grid cell on a 1440px desktop is as narrow as one on a phone, and the
+ * viewport agrees with neither. Keeping them as plain numbers here is also what keeps this file
+ * Mantine-free — `theme.breakpoints` is on the coupled side of the boundary.
+ */
+const HEIGHT_STEP_WIDTH = { sm: 768, md: 992, lg: 1200 } as const
+
+/** Widest-first, so the first step that fits is the answer. */
+const HEIGHT_STEPS = ['lg', 'md', 'sm'] as const
+
+/**
+ * Resolve a `height` prop — a plain number, or a {@link ResponsiveChartHeight} — against the
+ * measured container width.
+ *
+ * A plain number passes through untouched: this is a WIDENING of the prop, not a replacement, and
+ * every existing `height={240}` must keep meaning exactly 240.
+ *
+ * An UNMEASURED box (`containerW <= 0` — SSR, or before the `ResizeObserver`'s first callback)
+ * resolves to the LARGEST stated step, matching {@link resolveChartTier}'s first-frame rule: the
+ * first paint must not be phone-shaped chrome that grows one frame later. Falling to `base` there
+ * would make every SSR'd chart short and then jump.
+ */
+export function resolveFrameHeight(
+  height: number | ResponsiveChartHeight,
+  containerW: number,
+): number {
+  if (typeof height === 'number') return height
+  const widest = HEIGHT_STEPS.find((step) => height[step] !== undefined)
+  if (containerW <= 0) return widest === undefined ? height.base : (height[widest] ?? height.base)
+  const step = HEIGHT_STEPS.find(
+    (name) => containerW >= HEIGHT_STEP_WIDTH[name] && height[name] !== undefined,
+  )
+  return step === undefined ? height.base : (height[step] ?? height.base)
+}
+
 /**
  * How much of `VX.margin` a phone-tier chart keeps as its FLOOR. The measured law is unchanged —
  * a side may still only grow past its floor (`autoMargin`) — this only stops a static token from
@@ -73,7 +137,7 @@ export type ChartTierMetrics = {
   /** Floating tooltip `minWidth`, px. */
   tooltipMinWidth: number
   /** Default entry cap on the legend, or `undefined` for no default cap. An explicit
-   * `legend.maxRows` still wins as the upper bound. */
+   * `legend.maxRows` replaces it outright ({@link resolveLegendMaxRows}). */
   legendMaxRows: number | undefined
   /** Per-side margin FLOORS (`VX.margin` is a floor, never a ceiling — §1). */
   margin: ChartMargin
@@ -111,6 +175,75 @@ export function chartTierMetrics(tier: ChartTier): ChartTierMetrics {
   return tier === 'phone' ? PHONE_METRICS : DESKTOP_METRICS
 }
 
+/**
+ * Which legend cap applies: the caller's, or the tier's own default.
+ *
+ * **An explicit `callerMaxRows` wins OUTRIGHT.** This used to be `Math.min(caller, tier)`, which
+ * made the documented per-chart opt-out ("opt back out with an explicit `legend.maxRows`") false in
+ * the one direction anybody needs it. The tier's `PHONE_LEGEND_MAX_ROWS` is a DEFAULT for charts
+ * that said nothing — a chart that names a number has already answered the question the default
+ * exists to answer, and it matters because the tier keys on the measured box: a 380px inspector
+ * panel on a 1440px desktop is "a phone", so a six-series legend rolled up to two rows + `+4 more`
+ * with no way to say no. `margin` and `xLabelRotate` always had that escape; the legend did not.
+ *
+ * The measured {@link legendEntryCap} a `fill` frame applies is NOT a second ceiling on top of
+ * this: it resolves an ABSENT cap only. 1.30.0 ran it over the caller's number as well
+ * (`Math.min(fitted, caller)`), which made "wins outright" false again in the one place it was
+ * needed — meteo measured a 7-entry legend pinned to 2 entries at `maxRows` 3, 6 AND 99, with 5
+ * series drawn in colours the legend refused to name. The fit is not physics either: it derives
+ * from `VX.minPlotHeight`, which is a framework DEFAULT about the plot. Two defaults do not
+ * outvote the one number a caller stated, so the PLOT yields the height instead
+ * ({@link resolvePlotRect}'s `legendWins`) — visibly, in the frame the caller sized.
+ */
+export function resolveLegendMaxRows(input: {
+  callerMaxRows?: number | undefined
+  tier: ChartTier
+}): number | undefined {
+  return input.callerMaxRows ?? chartTierMetrics(input.tier).legendMaxRows
+}
+
+/**
+ * The whole legend-cap decision in one place: which cap `ChartLegend` gets, and whether the plot
+ * pays for it.
+ *
+ * It lives here rather than inline in `ChartFrame` because the COMPOSITION is what broke. 1.30.0
+ * had both halves right on their own — {@link resolveLegendMaxRows} honoured a stated cap,
+ * {@link legendEntryCap} measured a fit — and then ran the second over the first, which no test
+ * could see because neither pure function was wrong and the frame that combined them needs a
+ * `ResizeObserver` to test. Now the combination is a pure function too.
+ *
+ * Three cases, in order:
+ * 1. The caller STATED a number → it is the cap, and on a `fill` band the plot yields
+ *    (`legendWins`). Nothing measured or defaulted trims it.
+ * 2. No `fill` band → the tier's default (or none), because the frame simply grows.
+ * 3. A `fill` band with nothing stated → the measured fit, bounded by the tier's default.
+ */
+export function resolveLegendRollup(input: {
+  /** The caller's own `legend.maxRows`. */
+  statedMaxRows?: number | undefined
+  tier: ChartTier
+  /** A visible top/bottom legend on a `fill` frame — the one shape whose box cannot grow. */
+  fillBand: boolean
+  items: readonly LegendEntry[]
+  containerW: number
+  /** Frame height the legend may consume — `resolvedHeight - VX.minPlotHeight`. */
+  available: number
+}): { maxRows: number | undefined; legendWins: boolean } {
+  const { statedMaxRows, tier, fillBand, items, containerW, available } = input
+  if (statedMaxRows !== undefined) return { maxRows: statedMaxRows, legendWins: fillBand }
+  const tierMaxRows = resolveLegendMaxRows({ callerMaxRows: undefined, tier })
+  if (!fillBand) return { maxRows: tierMaxRows, legendWins: false }
+  return {
+    maxRows: legendEntryCap({
+      items,
+      containerW,
+      available,
+      ...(tierMaxRows !== undefined && { defaultMaxRows: tierMaxRows }),
+    }),
+    legendWins: false,
+  }
+}
+
 /**
  * Resolve the plot rect from the measured box and the measured legend band. Pure and exported so
  * the two floors below are testable without a `ResizeObserver`.
@@ -125,9 +258,11 @@ export function chartTierMetrics(tier: ChartTier): ChartTierMetrics {
  *   `height={240}` toward zero and the body stopped rendering entirely. The plot stops at
  *   `VX.minPlotHeight` and the frame's own box grows by the difference instead — it is a flex
  *   column with `height: auto`, so that growth is automatic. Under `fill` the box CANNOT grow, so
- *   the legend is capped instead ({@link legendEntryCap}). An unmeasured box (`resolvedHeight <=
- *   0`, i.e. a `fill` frame before its first measurement) stays at 0 and renders nothing, exactly
- *   as before — the floor must never invent a height for a box nobody has measured.
+ *   the legend is capped instead ({@link legendEntryCap}) — UNLESS the caller stated
+ *   `legend.maxRows`, which is `legendWins`: there the floor itself yields, because a floor is a
+ *   default and the caller's number is not. An unmeasured box (`resolvedHeight <= 0`, i.e. a
+ *   `fill` frame before its first measurement) stays at 0 and renders nothing, exactly as before —
+ *   the floor must never invent a height for a box nobody has measured.
  */
 export function resolvePlotRect(input: {
   containerW: number
@@ -135,12 +270,28 @@ export function resolvePlotRect(input: {
   minWidth: number
   sideLegendWidth: number
   topBottomLegendHeight: number
+  /**
+   * The caller stated `legend.maxRows` on a `fill` frame, so the legend takes the rows it asked
+   * for and the plot takes what is left — `VX.minPlotHeight` stops being a floor. Without this the
+   * honoured cap would push the frame's content PAST its own cell (the plot holds 120px, the legend
+   * band adds its own) and paint over whatever sits below it; with it, the cost of the caller's
+   * number lands where they can see it. Spend the whole box on legend rows and there is no plot
+   * left to draw — that is their arithmetic, made visible rather than silently rolled up.
+   */
+  legendWins?: boolean
 }): { width: number; height: number } {
-  const { containerW, resolvedHeight, minWidth, sideLegendWidth, topBottomLegendHeight } = input
+  const {
+    containerW,
+    resolvedHeight,
+    minWidth,
+    sideLegendWidth,
+    topBottomLegendHeight,
+    legendWins = false,
+  } = input
+  const plotFloor = legendWins ? 0 : VX.minPlotHeight
   return {
     width: containerW === 0 ? minWidth : Math.max(containerW - sideLegendWidth, 1),
-    height:
-      resolvedHeight <= 0 ? 0 : Math.max(resolvedHeight - topBottomLegendHeight, VX.minPlotHeight),
+    height: resolvedHeight <= 0 ? 0 : Math.max(resolvedHeight - topBottomLegendHeight, plotFloor),
   }
 }
 
@@ -186,17 +337,25 @@ function entriesWithinRows(items: readonly LegendEntry[], width: number, rows: n
  * MEASURING the labels, not from assuming one entry per row — otherwise a five-entry legend that
  * fits on one line would roll up to `+2 more` in every 240px cell, moving rendering for charts
  * that never had the bug. Returns `undefined` when the whole legend already fits.
+ *
+ * This resolves an ABSENT cap. A caller who stated `legend.maxRows` never reaches here at all —
+ * `ChartFrame` routes around it — because `Math.min`-ing a stated number against this one made the
+ * documented escape inert in exactly the narrow `fill` panel it exists for
+ * ({@link resolveLegendMaxRows}).
  */
 export function legendEntryCap(input: {
   items: readonly LegendEntry[]
   containerW: number
   /** Frame height the legend may consume — `resolvedHeight - VX.minPlotHeight`. */
   available: number
-  /** An explicit caller cap always wins as the upper bound. */
-  callerMaxRows?: number
+  /**
+   * The cap that applies when nothing explicit was stated — today only the tier's own default
+   * ({@link chartTierMetrics}). Two defaults contending: the smaller wins.
+   */
+  defaultMaxRows?: number
 }): number | undefined {
-  const { items, containerW, available, callerMaxRows } = input
-  if (containerW <= 0 || items.length === 0) return callerMaxRows
+  const { items, containerW, available, defaultMaxRows } = input
+  if (containerW <= 0 || items.length === 0) return defaultMaxRows
   const rows = Math.max(
     1,
     Math.floor((available - LEGEND_PAD_Y + VX.legendGap) / (LEGEND_LINE_H + VX.legendGap)),
@@ -205,8 +364,8 @@ export function legendEntryCap(input: {
     legendBandHeight(rows) <= available &&
     entriesWithinRows(items, containerW, rows) >= items.length
   ) {
-    return callerMaxRows
+    return defaultMaxRows
   }
   const fitted = Math.max(1, entriesWithinRows(items, containerW, rows))
-  return callerMaxRows === undefined ? fitted : Math.min(fitted, callerMaxRows)
+  return defaultMaxRows === undefined ? fitted : Math.min(fitted, defaultMaxRows)
 }

package/src/cli/check-theme.ts

@@ -19,6 +19,7 @@ import {
   conflictingProfileFlags,
   declaredProfile,
   DEFAULT_ROOTS,
+  hasBasaltKey,
   readBasaltConfig,
   resolveExemptRules,
   resolveProjectDir,
@@ -96,6 +97,18 @@ export function checkTheme(
     // A configured-but-wrong root is never intentional, and silently scanning 0 files under the
     // built-in defaults (argo's pre-migration layout) is the same failure mode for every other
     // consumer — both cases fail loud instead of warn-plus-green.
+    // The WRONG-DIRECTORY case leads, and since 1.29.0's single resolver it is the common one:
+    // lefthook and GitHub Actions both run at the REPO ROOT while the config lives in a package
+    // below it. Only the roots messages used to print, sending a consumer to edit `basalt.roots` in
+    // a package.json that has no `basalt` block at all.
+    if (!hasBasaltKey(cwd)) {
+      console.error(
+        `✖ basalt-ui check-theme: ${cwd}/package.json has no "basalt" key — very likely not the ` +
+          'package you meant to scan (BASALT_CWD, else the invocation cwd; nothing is inferred). ' +
+          'At a repo root? Give the command `root: <pkg>/` (lefthook) or `working-directory: ' +
+          '<pkg>` (Actions), or set BASALT_CWD=<pkg>. If this directory IS it, run `basalt-ui init`.',
+      )
+    }
     if (cfg.roots === undefined) {
       console.error(
         `✖ basalt-ui check-theme: 0 files scanned — no "basalt.roots" configured in package.json, and ` +

package/src/cli/doctor.ts

@@ -4,7 +4,7 @@
  * managed-file manifest path) back from `./index`, this package's shared CLI helpers.
  */
 import { existsSync } from 'node:fs'
-import { resolve } from 'node:path'
+import { relative, resolve } from 'node:path'
 
 import type { BasaltConfig } from './index'
 import {
@@ -19,7 +19,10 @@ import {
   parseJsonc,
   readBasaltConfig,
   readIfExists,
+  readManifest,
   resolveProjectDir,
+  resolveRoots,
+  scannableFiles,
   shippedAssetPath,
 } from './index'
 import { findManifestAbove, parentInstallAdvice } from './sync'
@@ -102,16 +105,22 @@ function resolveAiMajorSkewReason(cfg: BasaltConfig): {
  * Check a consumer repo's basalt integration and print a pass/warn report.
  *
  * Narrowed to what a single-directory-scoped run can actually verify — no workspace-glob walking,
- * no ascend/descend project discovery (see {@link resolveProjectDir}). Four checks, numbered in
+ * no ascend/descend project discovery (see {@link resolveProjectDir}). Six checks, numbered in
  * the order they run and print:
  *
  * Hard failures (exit non-zero):
  *   1. `.basalt/manifest.json` exists (`basalt-ui init` was run).
- *   2. `oxlint-preset` ("rules in sync"): the consumer's `.oxlintrc.json` extends the shipped
+ *   2. `install-parity`: basalt-ui resolves, doctor prints WHERE and at what version, and that
+ *      version agrees with the manifest's `basaltVersion`.
+ *   3. `guard-scan`: `check-theme` would scan more than zero files, sharing `scannableFiles` so the
+ *      two cannot disagree. Both RESTORED in 1.30.0 after four minors gone with no MIGRATING row —
+ *      README § `doctor` carries what their absence cost (a no-op CI gate, a green guard scanning
+ *      nothing, and two basalt-WRITTEN docs describing output the CLI no longer produced).
+ *   4. `oxlint-preset` ("rules in sync"): the consumer's `.oxlintrc.json` extends the shipped
  *      preset AND that path resolves. `init` keeps an existing config, so the framework's whole
  *      lint half can be silently off — one repo carried six real violations invisibly across five
  *      minors this way.
- *   4. `ai-major-parity`: within THIS package.json, `dependencies`/`devDependencies`/
+ *   6. `ai-major-parity`: within THIS package.json, `dependencies`/`devDependencies`/
  *      `peerDependencies` agree on the `ai` package's major. `basalt/ai-sdk-major` (the oxlint
  *      plugin rule) already catches this per linted FILE against its nearest package.json; this
  *      check exists for the shape a lint run cannot see — a package whose own manifest asks its
@@ -121,7 +130,7 @@ function resolveAiMajorSkewReason(cfg: BasaltConfig): {
  *      already agree warns that the exemption is stale.
  *
  * Warning (non-fatal):
- *   3. `lefthook-preset` ("lefthook wired"): a pre-commit command runs `check-theme`, read from
+ *   5. `lefthook-preset` ("lefthook wired"): a pre-commit command runs `check-theme`, read from
  *      `lefthook dump --format json` (resolves `extends`/`include`/`root:` the way lefthook itself
  *      does — see {@link inspectLefthookGate}). No lefthook config at all is a pass (a consumer may
  *      gate elsewhere); a config that resolves but wires no guard command warns; a config lefthook
@@ -189,7 +198,39 @@ export function doctor(invocationCwd: string = process.cwd(), flags: string[] =
 
   const install = findBasaltInstall(cwd)
 
-  // ── Hard check 2: the consumer's oxlint config extends the shipped preset ──
+  // ── Hard check 2: install matches the manifest, and doctor says WHERE (the CLAUDE-block's claim)
+  const manifestVersion = profile === 'tokens-only' ? undefined : readManifest(cwd).basaltVersion
+  const at = install.dir === null ? '' : `${relative(cwd, install.dir)} (${install.version})`
+  if (install.dir === null) {
+    fail(
+      'install-parity: basalt-ui does not resolve here, above, or in a sibling workspace package.',
+    )
+  } else if (manifestVersion === undefined || install.version === manifestVersion) {
+    const matches = manifestVersion === undefined ? '' : " and matches the manifest's basaltVersion"
+    pass(`basalt-ui resolves at ${at}${matches}`)
+  } else {
+    fail(
+      `install-parity: basalt-ui resolves at ${at}, but ${MANIFEST_PATH} was last written by ` +
+        `${manifestVersion} — the managed layer is from a different release than the code. Run ` +
+        '`basalt-ui sync` (or `bun install`, if the lockfile is what is stale).',
+    )
+  }
+
+  // ── Hard check 3: the guard sees files — zero-file roots are a green guard enforcing nothing ──
+  const scanned = profile === 'tokens-only' ? null : scannableFiles(cwd, cfg).length
+  if (scanned === null) {
+    pass('guard-scan: n/a — a tokens-only consumer runs the token lane, not the file walk')
+  } else if (scanned === 0) {
+    fail(
+      'guard-scan: `check-theme` would scan ZERO files here — either `basalt.roots` points at ' +
+        'paths that do not exist, or this is not the package the config lives in (BASALT_CWD, ' +
+        'else the cwd; nothing is inferred).',
+    )
+  } else {
+    pass(`guard-scan: check-theme covers ${scanned} file(s) under ${resolveRoots(cfg).join(', ')}`)
+  }
+
+  // ── Hard check 4: the consumer's oxlint config extends the shipped preset ──
   // `init` KEEPS an existing `.oxlintrc.json`, so a repo can carry the whole scaffold with the
   // framework's lint half switched off and nothing anywhere saying so. One repo ran five minors
   // that way and surfaced six real `basalt/no-raw-font-size` errors the moment it was wired.
@@ -235,7 +276,7 @@ export function doctor(invocationCwd: string = process.cwd(), flags: string[] =
     }
   }
 
-  // ── Warn check 3: the pre-commit hook actually runs the guard ──────────────
+  // ── Warn check 5: the pre-commit hook actually runs the guard ──────────────
   // Read via `lefthook dump --format json`, which resolves `extends`/`include`/remote configs/
   // `root:` the way lefthook itself does — see {@link inspectLefthookGate}.
   const repoRoot = findRepoRoot(cwd)
@@ -262,7 +303,7 @@ export function doctor(invocationCwd: string = process.cwd(), flags: string[] =
     )
   }
 
-  // ── Hard check 4: ai package major version parity within THIS package.json ─
+  // ── Hard check 6: ai package major version parity within THIS package.json ─
   // basalt/ai-sdk-major (the lint rule) is per-file against the NEAREST package.json, so a lint
   // run scoped to one workspace package only ever sees that package's own `ai` major and is
   // perfectly happy. This check reads the SAME package.json across its dependencies/

package/src/cli/help.ts

@@ -21,6 +21,7 @@ export const COMMAND_OPTIONS: Record<string, Record<string, { type: 'string' | '
   sync: {
     force: { type: 'boolean' },
     check: { type: 'boolean' },
+    verbose: { type: 'boolean' },
     'tokens-only': { type: 'boolean' },
     framework: { type: 'boolean' },
   },
@@ -65,7 +66,7 @@ export function unknownFlag(cmd: string, flags: readonly string[]): string | nul
 /** The one usage string — printed by `basalt help` / `--help` / `-h` AND the unknown-command fallback. */
 export const USAGE =
   'Usage: basalt-ui <--version | init [--with-router] [--with-query] [--merge-lint] |\n' +
-  '                  sync [--force] [--check] [--tokens-only|--framework] |\n' +
+  '                  sync [--force] [--check] [--verbose] [--tokens-only|--framework] |\n' +
   '                  check-theme [--audit-allows] |\n' +
   '                  doctor [--tokens-only|--framework] | guard-hook | tokens:css | fonts:css | help>\n\n' +
   'check-theme [--tokens-only|--framework] [--audit-allows]\n' +
@@ -89,9 +90,10 @@ export const USAGE =
   '  Checks THIS project only: the manifest exists, the oxlint preset is wired, the pre-commit\n' +
   '  hook runs check-theme (via `lefthook dump`), and the ai package major is consistent within\n' +
   '  this package.json. Profile is DECLARED, same as check-theme — never inferred.\n\n' +
-  'sync [--force] [--check] [--tokens-only|--framework]\n' +
+  'sync [--force] [--check] [--verbose] [--tokens-only|--framework]\n' +
   '  Refreshes an EXISTING install; it never creates one (that is init). A tokens-only consumer\n' +
-  '  has no scaffold to reconcile, so sync reports n/a and exits 0 there — as doctor does.\n\n' +
+  '  has no scaffold to reconcile, so sync reports n/a and exits 0 there — as doctor does.\n' +
+  '  --check prints the permanent placement skips as a COUNT; --verbose spells them out again.\n\n' +
   'check-theme / doctor / sync all resolve their project the same way: BASALT_CWD, else the\n' +
   'invocation cwd — nothing inferred, nothing ascended or descended into.\n' +
   '--tokens-only and --framework are alternatives; passing both is an error.\n\n' +

package/src/cli/index.ts

@@ -333,6 +333,17 @@ function sanitizeSeverity(cfg: BasaltConfig): BasaltConfig {
   return { ...cfg, severity: kept as Partial<Record<GuardKind, GuardSeverity>> }
 }
 
+/** Does `cwd`'s own `package.json` carry a `basalt` key? — "misconfigured roots" vs "wrong
+ *  directory", the failure a root-invoked hook hits since 1.29.0's single resolver. Never a walk. */
+export function hasBasaltKey(cwd: string): boolean {
+  const raw = readIfExists(resolve(cwd, 'package.json'))
+  try {
+    return raw !== null && (JSON.parse(raw) as { basalt?: unknown }).basalt !== undefined
+  } catch {
+    return false
+  }
+}
+
 export function readBasaltConfig(cwd: string): BasaltConfig {
   try {
     const pkg = JSON.parse(readFileSync(resolve(cwd, 'package.json'), 'utf8')) as {
@@ -1114,6 +1125,44 @@ export function managedFiles(
   return [...rules, ...skills, claudeBlock, design, oxfmt, ...rootTooling, oxlintrc, ...scaffolds]
 }
 
+/**
+ * The PERMANENT placement skips as sentences — one text for `init` and `sync`, which carried two
+ * near-copies that had already drifted apart. Correct and unchanging, which is why `sync --check`
+ * hides them behind `--verbose`. `extends` alone is NOT the recipe for the hook, and saying only
+ * that shipped a broken one: lefthook merges the preset's commands but runs every one at the REPO
+ * ROOT, with no oxlint config, no local binary and no basalt config. `root:` moves the invocation
+ * cwd per command and merges (the preset does not define it) — see the preset's MONOREPO RECIPE.
+ */
+export function placementNotices(cwd: string, placement: PlacementFlags): string[] {
+  const out: string[] = []
+  const install = findBasaltInstall(cwd)
+  const asset = (n: string): string => shippedAssetPath(install, placement.repoRoot, n)
+  // Bare, no `./` — a lefthook `root:` and an Actions `working-directory:` are already repo-relative.
+  const pkg = relativePosix(placement.repoRoot, cwd).replace(/^\.\//, '')
+  const notRoot = `(not the repo root — repo root detected at ${placement.repoRoot})`
+  if (!placement.isPackageRepoRoot) {
+    out.push(
+      `skipped lefthook.yml ${notRoot} — lefthook only reads config at the repo root. Extend ` +
+        `${asset('configs/lefthook.yml')} from your root lefthook.yml AND give every merged ` +
+        `command \`root: '${pkg}/'\` — \`pre-commit.commands.{oxlint,oxfmt,check-theme}.root: ` +
+        `'${pkg}/'\` — or they run at the root where your oxlint config, your binaries and your ` +
+        'basalt config are not.',
+      `skipped .github/workflows/check.yml ${notRoot} — GitHub Actions only reads .github/ at the ` +
+        `repo root; copy the steps from ${asset('configs/check.yml')} into your root CI workflow ` +
+        `instead, and give each one \`working-directory: ${pkg}\` — the same relocation \`root:\` ` +
+        'performs for lefthook, and needed for the same reason.',
+    )
+  }
+  if (placement.relocatedQueryClient !== null) {
+    out.push(
+      `skipped src/query-client.ts (found an existing query client at ` +
+        `${relative(cwd, placement.relocatedQueryClient)}) — import it from there instead of ` +
+        're-seeding at the original path.',
+    )
+  }
+  return out
+}
+
 export type Manifest = {
   version: 1
   /** The basalt-ui version that last wrote this manifest — `doctor`'s one reconciliation axis. */