basalt-ui 1.22.0 → 1.23.0

package/src/charts/primitives/CartesianChart.tsx

@@ -151,8 +151,24 @@ export type CartesianChartProps<T> = {
   /** Passing `y2` is what makes the chart dual-axis: it draws the right axis and widens the
    * right margin by measurement. Series opt in with `axis: 'right'`. */
   y2?: AxisConfig<T>
-  /** Exact number of x ticks. Default: as many as fit (`smartTicks`). */
+  /** Exact number of x ticks. Default: as many as fit (`smartTicks`). Ignored when
+   * `xTickValues` is set. */
   xTicks?: number
+  /**
+   * Which domain keys get a tick, chosen from the full key list and the resolved plot width.
+   * Takes precedence over `xTicks`; omit both for `smartTicks`.
+   *
+   * A COUNT is not always enough. `smartTicks`/`smartTicksEvery` append the final key
+   * unconditionally, so when the step does not land on the last index that appended tick sits a
+   * partial step from its neighbour — measured on a 24h window, two `DD.MM HH:MM` labels printed
+   * on top of each other at the right edge, at every tick count. The only fix a count can express
+   * is thinning the whole axis to avoid one crowded pair. A consumer whose labels are richer than
+   * the default `DD.MM` needs to pick the VALUES, which until now meant measuring the container
+   * itself with `useChartSize` to derive a count — the chart already knows its own width.
+   *
+   * `BandStrip`/`MirroredBars` take the identical prop, so the seam does not fork by kind.
+   */
+  xTickValues?: (keys: readonly string[], xMax: number) => readonly string[]
   /** X tick label formatter. Default `fmtAxisDate` (DD.MM). */
   formatX?: (key: string) => string
   /** Value-range bands on the left scale, drawn behind the marks. */
@@ -267,6 +283,7 @@ export function CartesianChart<T>({
   y,
   y2,
   xTicks,
+  xTickValues,
   formatX = fmtAxisDate,
   zones,
   xZones,
@@ -305,6 +322,7 @@ export function CartesianChart<T>({
           {...(y !== undefined && { y })}
           {...(y2 !== undefined && { y2 })}
           {...(xTicks !== undefined && { xTicks })}
+          {...(xTickValues !== undefined && { xTickValues })}
           formatX={formatX}
           {...(zones !== undefined && { zones })}
           {...(xZones !== undefined && { xZones })}
@@ -343,6 +361,7 @@ function CartesianPlot<T>({
   y,
   y2,
   xTicks,
+  xTickValues,
   formatX = fmtAxisDate,
   zones,
   xZones,
@@ -459,9 +478,15 @@ function CartesianPlot<T>({
     [rightDomain, yMax, y2?.nice],
   )
 
+  // Resolution order: explicit VALUES win, then an explicit COUNT, then as many as fit.
   const tickValues = useMemo(
-    () => (xTicks === undefined ? smartTicks(keys, xMax) : smartTicksEvery(keys, xTicks)),
-    [keys, xMax, xTicks],
+    () =>
+      xTickValues !== undefined
+        ? [...xTickValues(keys, xMax)]
+        : xTicks === undefined
+          ? smartTicks(keys, xMax)
+          : smartTicksEvery(keys, xTicks),
+    [keys, xMax, xTicks, xTickValues],
   )
 
   const cursor = useChartCursor<T>({

package/src/charts/primitives/HatchPattern.tsx

@@ -0,0 +1,55 @@
+import type { ReactNode } from 'react'
+import { alpha } from '../../tokens'
+
+/**
+ * A diagonal-hatch `<pattern>` — the one fill that reads as **absence** rather than as a weak
+ * measurement.
+ *
+ * A faint solid tint cannot do this job: it sits on the same perceptual axis as every other
+ * intensity of the same hue, so "nothing was measured here" and "everything measured here was
+ * fine" collapse into neighbouring steps of one ramp. Hatching is off that axis entirely and
+ * survives being placed beside a colour ramp of the same hue.
+ *
+ * `id` must be unique per document — `BandStrip` / `MirroredBars` namespace theirs with `chartId`.
+ * `opacity` is applied through `alpha()` on the stroke rather than as an `opacity` attribute, so
+ * the hue keeps resolving per colour scheme.
+ */
+export function HatchPattern({
+  id,
+  color,
+  opacity = 0.55,
+  size = 6,
+}: {
+  id: string
+  color: string
+  opacity?: number
+  size?: number
+}): ReactNode {
+  return (
+    <pattern
+      id={id}
+      width={size}
+      height={size}
+      patternUnits="userSpaceOnUse"
+      patternTransform="rotate(45)"
+    >
+      <line x1={0} y1={0} x2={0} y2={size} stroke={alpha(color, opacity)} strokeWidth={size / 3} />
+    </pattern>
+  )
+}
+
+/** `fill` value referencing a {@link HatchPattern} by id. */
+export function hatchFill(id: string): string {
+  return `url(#${id})`
+}
+
+/**
+ * The pattern's own repeat, shrunk to fit the band it textures.
+ *
+ * Left at a fixed 6px a sub-pixel band draws less than one diagonal rule, so a fill/hatch split
+ * inside one band antialiases into a single smudge no reader can tell from a fully-measured band.
+ * Floored at 2 — below that the stroke has nothing to render on.
+ */
+export function hatchSizeFor(bandWidth: number): number {
+  return Math.max(2, Math.min(6, Math.round(bandWidth)))
+}

package/src/cli/index.ts

@@ -511,6 +511,34 @@ type ProjectResolution = {
   ambiguous: string[] | null
 }
 
+/**
+ * Basalt projects in `cwd`'s immediate subtree — the fallback for a repo that declares no
+ * `workspaces` field at all.
+ *
+ * {@link collectWorkspacePackages} is the primary source and it is exact, but it answers `[]` for
+ * every repo whose root `package.json` carries no `workspaces` key. linewatch is that shape: the
+ * entire basalt consumer lives in `web/`, with no workspace declaration anywhere. Measured at its
+ * repo root, all three project-scoped commands got that wrong in a different way — `check-theme`
+ * printed `✓ no off-palette colors` having scanned ZERO files, `doctor` inferred `tokens-only` for
+ * a full Mantine consumer, and `sync` refused while naming `basalt-ui init` as the remedy, which is
+ * the one command that WOULD have written a competing install at the root. A gate that reports
+ * green having looked at nothing is the failure this resolver exists to prevent, so the search
+ * falls back to the layout when there is no declaration to read.
+ *
+ * Bounded to two levels (`web/`, `apps/admin/`), dot-directories and `node_modules` skipped, and it
+ * never descends INTO a project it found — a consumer's own nested package is not a rival candidate.
+ */
+function descendantProjects(cwd: string, depth = 2): string[] {
+  if (depth === 0) return []
+  const out: string[] = []
+  for (const name of subdirNames(cwd, { skipDotDirs: true })) {
+    const dir = resolve(cwd, name)
+    if (hasBasaltProject(dir)) out.push(dir)
+    else out.push(...descendantProjects(dir, depth - 1))
+  }
+  return out
+}
+
 function resolveProjectDir(cwd: string): ProjectResolution {
   const override = process.env['BASALT_CWD']
   if (override !== undefined && override.length > 0) {
@@ -519,9 +547,13 @@ function resolveProjectDir(cwd: string): ProjectResolution {
   }
   if (hasBasaltProject(cwd)) return { dir: cwd, relocatedFrom: null, ambiguous: null }
 
-  const candidates = collectWorkspacePackages(cwd)
+  const declared = collectWorkspacePackages(cwd)
     .packages.filter((pkg) => pkg.dir !== cwd && hasBasaltProject(pkg.dir))
     .map((pkg) => pkg.dir)
+  // The workspace declaration wins whenever there is one — it is exact, and a repo that declares
+  // its packages has already said where they are. The layout scan only answers for the repos that
+  // declare nothing; see descendantProjects.
+  const candidates = declared.length > 0 ? declared : descendantProjects(cwd)
   if (candidates.length === 1) {
     return { dir: candidates[0] as string, relocatedFrom: cwd, ambiguous: null }
   }
@@ -692,7 +724,7 @@ export function checkTheme(
   if (project.ambiguous !== null) {
     console.error(
       `✖ basalt-ui check-theme: no basalt config at ${invocationCwd}, and ${project.ambiguous.length} ` +
-        `workspace packages carry one (${project.ambiguous.map((d) => relativePosix(invocationCwd, d)).join(', ')}) — ` +
+        `packages below it carry one (${project.ambiguous.map((d) => relativePosix(invocationCwd, d)).join(', ')}) — ` +
         'run it from one of them, or set BASALT_CWD to pick.',
     )
     return 1
@@ -1176,13 +1208,21 @@ function auditAllows(
     `\n${live} live, ${dead} dead, ${outOfReach} unjudgeable, ${unaccountable} ` +
       'unaccountable (reported as theme-allow-unscoped by a normal run).',
   )
-  // The audit reads exactly what `check-theme` reads, and that is `basalt.roots`. A waiver in a
-  // file outside them is invisible here — not because it is fine, but because nothing scanned it.
-  // Saying the scope out loud is the difference between "0 dead" and "0 dead, over these files".
+  // The audit reads exactly what `check-theme` reads, and that is `scannableFiles` — which is
+  // WIDER than `basalt.roots`: it also takes each root's sibling `index.html` and `public/` tree
+  // (see appShellFiles) and anything named in `basalt.include`. Two consumers reported a live
+  // `public/site.webmanifest` waiver under a scope line saying files outside `roots` are not
+  // audited; the line was wrong, not the scan. Saying the scope out loud is the difference between
+  // "0 dead" and "0 dead, over these files" — so it has to name every class actually reached.
+  const includes = cfg.include ?? []
   lines.push(
-    `Scope: the ${scanned.length} file(s) check-theme scans under basalt.roots ` +
-      `(${resolveRoots(cfg).join(', ')}). A waiver outside them is not audited — widen roots to ` +
-      'cover it, or accept that nothing polices that file.',
+    `Scope: the ${scanned.length} file(s) check-theme scans — everything under basalt.roots ` +
+      `(${resolveRoots(cfg).join(', ')}), plus each root's sibling index.html and public/ tree, ` +
+      (includes.length === 0
+        ? 'plus anything named in basalt.include (none). '
+        : `plus basalt.include (${includes.join(', ')}). `) +
+      'A waiver in a file none of those reach is not audited — widen roots, or name it in ' +
+      'basalt.include, or accept that nothing polices that file.',
   )
   if (dead > 0) {
     lines.push(
@@ -1743,6 +1783,34 @@ function migrateLegacyOxfmt(cwd: string, pkgRoot: string, manifest: Manifest): v
   if (shipped !== null && onDisk === shipped) unlinkSync(legacyAbs)
 }
 
+/** The frozen `> Managed by basalt-ui (1.9.0).` opener every pre-fix DESIGN.md seed carries. */
+const DESIGN_VERSION_LINE = /^(> Managed by basalt-ui) \(\d+\.\d+\.\d+\)\./m
+
+/**
+ * Strip the frozen version out of an already-seeded `DESIGN.md` opener.
+ *
+ * `DESIGN.md` is a `seed`: written once, then consumer-owned and never reconciled. It opened with
+ * `> Managed by basalt-ui ({{BASALT_VERSION}})`, which is accurate for exactly as long as it takes
+ * to run one upgrade — measured across the seven consumers the same line read 1.0.0, 1.9.0, 1.21.0
+ * and 1.22.0 under an identical 1.22.0 install, and three rounds of reports treated that as four
+ * separate doc bugs. It was one: a version number in a file nothing ever rewrites.
+ *
+ * Dropping it from the template fixes new scaffolds only — every existing consumer would carry its
+ * stale number forever, since sync does not touch a seed. So sync deletes the parenthetical in
+ * place, and only that: not a re-seed, not a three-way merge. Everything else in the file is left
+ * exactly as the consumer wrote it, and a DESIGN.md whose opener was already rewritten by hand
+ * does not match at all.
+ */
+function migrateDesignVersionLine(cwd: string): void {
+  const dest = resolve(cwd, 'DESIGN.md')
+  const onDisk = readIfExists(dest)
+  if (onDisk === null || !DESIGN_VERSION_LINE.test(onDisk)) return
+  writeFileEnsuringDir(
+    dest,
+    onDisk.replace(DESIGN_VERSION_LINE, '$1 — run `basalt-ui doctor` for the version.'),
+  )
+}
+
 function writeFileEnsuringDir(abs: string, content: string): void {
   mkdirSync(dirname(abs), { recursive: true })
   writeFileSync(abs, content)
@@ -2519,7 +2587,12 @@ function readOxlintPresetPlugins(pkgRoot: string): string[] {
   }
 }
 
-type SyncOptions = { force?: boolean; check?: boolean }
+type SyncOptions = {
+  force?: boolean
+  check?: boolean
+  /** The raw flag list, read for `--tokens-only` / `--framework` exactly as check-theme reads it. */
+  flags?: readonly string[]
+}
 
 /**
  * The nearest ANCESTOR of `dir` (exclusive) carrying a basalt manifest, or null.
@@ -2554,11 +2627,16 @@ function findManifestAbove(dir: string): string | null {
  * `sync` does not get to make silently.
  */
 export function sync(opts: SyncOptions = {}, invocationCwd: string = process.cwd()): number {
+  const syncFlags = opts.flags ?? []
+  if (conflictingProfileFlags(syncFlags)) {
+    console.error('basalt-ui sync: --tokens-only and --framework are alternatives — pass one.')
+    return 1
+  }
   const project = resolveProjectDir(invocationCwd)
   if (project.ambiguous !== null) {
     console.error(
       `✖ basalt-ui sync: no basalt config at ${invocationCwd}, and ${project.ambiguous.length} ` +
-        `workspace packages carry one (${project.ambiguous.map((d) => relativePosix(invocationCwd, d)).join(', ')}) — ` +
+        `packages below it carry one (${project.ambiguous.map((d) => relativePosix(invocationCwd, d)).join(', ')}) — ` +
         'run it from one of them, or set BASALT_CWD to pick.',
     )
     return 1
@@ -2571,6 +2649,24 @@ export function sync(opts: SyncOptions = {}, invocationCwd: string = process.cwd
     )
   }
 
+  // Profile before the refusal, because in a tokens-only consumer the refusal's own advice is
+  // wrong: it names `basalt-ui init`, and `doctor` in the same directory at the same version says
+  // in so many words that init is NOT the fix there — it places a Mantine doctrine the consumer
+  // has no use for. Mirrors doctor's manifest row verbatim, and exits 0 so `sync --check` is
+  // wirable into a tokens-only repo's CI (the one drift gate every other consumer runs).
+  //
+  // DECLARED, never inferred — the same asymmetry check-theme applies, for the same reason: the
+  // answer SILENCES the whole reconciliation, and inferring it from a missing @mantine/core would
+  // turn a framework consumer that keeps Mantine in a sibling package into a silent no-op.
+  if (declaredProfile(readBasaltConfig(cwd), syncFlags) === 'tokens-only') {
+    console.log(
+      `basalt-ui sync: ${MANIFEST_PATH}: n/a — a tokens-only consumer has no scaffold to ` +
+        'reconcile. The token layer is refreshed by re-running `basalt-ui tokens:css`, and ' +
+        '`tokens:css --check` is its drift gate. Pass --framework to force the full profile.',
+    )
+    return 0
+  }
+
   // The refusal runs BEFORE reconcileRoots, which WRITES `basalt.roots` into package.json — that
   // key is half the damage: a second `basalt` block means check-theme scans a different tree
   // depending on which directory it was invoked from.
@@ -2595,7 +2691,10 @@ export function sync(opts: SyncOptions = {}, invocationCwd: string = process.cwd
   const rootsState = reconcileRoots(cwd, { write: opts.check !== true })
   const ctx = renderContext(cwd)
   const manifest = readManifest(cwd)
-  if (!opts.check) migrateLegacyOxfmt(cwd, ctx.pkgRoot, manifest)
+  if (!opts.check) {
+    migrateLegacyOxfmt(cwd, ctx.pkgRoot, manifest)
+    migrateDesignVersionLine(cwd)
+  }
   const peers = resolvePeerFlags(cwd, {})
   const placement = resolvePlacement(cwd)
   const files = managedFiles(peers, placement)
@@ -3228,8 +3327,8 @@ export function doctor(invocationCwd: string = process.cwd(), flags: string[] =
   if (project.ambiguous !== null) {
     console.error(
       `\nbasalt-ui doctor — ${invocationCwd}\n\n` +
-        `  ✖ no basalt config at ${invocationCwd}, and ${project.ambiguous.length} workspace ` +
-        `packages carry one (${project.ambiguous.map((d) => relativePosix(invocationCwd, d)).join(', ')}) — ` +
+        `  ✖ no basalt config at ${invocationCwd}, and ${project.ambiguous.length} packages ` +
+        `below it carry one (${project.ambiguous.map((d) => relativePosix(invocationCwd, d)).join(', ')}) — ` +
         'run doctor from one of them, or set BASALT_CWD to pick.\n\n' +
         '1 hard failure(s), 0 warning(s).\n',
     )
@@ -4120,7 +4219,8 @@ export async function guardHook(cwd: string = process.cwd()): Promise<number> {
 
 /** The one usage string — printed by `basalt help` / `--help` / `-h` AND the unknown-command fallback. */
 const USAGE =
-  'Usage: basalt-ui <init [--with-router] [--with-query] [--merge-lint] | sync [--force] [--check] |\n' +
+  'Usage: basalt-ui <init [--with-router] [--with-query] [--merge-lint] |\n' +
+  '                  sync [--force] [--check] [--tokens-only|--framework] |\n' +
   '                  check-theme [--audit-allows] | check-coverage | info [--json] |\n' +
   '                  doctor [--tokens-only|--framework] | guard-hook | tokens:css | fonts:css | help>\n\n' +
   'check-theme [--tokens-only|--framework] [--audit-allows]\n' +
@@ -4143,9 +4243,13 @@ const USAGE =
   'doctor [--tokens-only|--framework]\n' +
   '  Auto-detects a tokens-only consumer (no manifest + no @mantine/core) and checks only what\n' +
   '  applies. A check that cannot RUN is reported as SKIPPED and exits non-zero.\n\n' +
-  'check-theme / doctor honour BASALT_CWD, and relocate to the single workspace package carrying a\n' +
-  'basalt config when invoked from a repo root that has none — several carrying one is ambiguous\n' +
-  'and exits 1 in BOTH. --tokens-only and --framework are alternatives; passing both is an error.\n\n' +
+  'sync [--force] [--check] [--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' +
+  'check-theme / doctor / sync all resolve their project the same way: they honour BASALT_CWD, and\n' +
+  'relocate to the single package below the cwd carrying a basalt config when invoked from a repo\n' +
+  'root that has none — several carrying one is ambiguous and exits 1 in ALL THREE.\n' +
+  '--tokens-only and --framework are alternatives; passing both is an error.\n\n' +
   'Every subcommand accepts --help / -h to print this message and exit without running.'
 
 /**
@@ -4179,7 +4283,10 @@ export function run(argv: string[], cwd: string = process.cwd()): number | Promi
         mergeLint: flags.includes('--merge-lint'),
       })
     case 'sync':
-      return sync({ force: flags.includes('--force'), check: flags.includes('--check') }, cwd)
+      return sync(
+        { force: flags.includes('--force'), check: flags.includes('--check'), flags },
+        cwd,
+      )
     case 'check-theme':
       return checkTheme(cwd, flags)
     case 'check-coverage':

package/src/cli/shipped-versions.test.ts

@@ -0,0 +1,83 @@
+/**
+ * No shipped artifact may name a basalt version npm never served.
+ *
+ * Three rounds running, the newest `MIGRATING.md` heading named a phantom — `1.20.1` (shipped as
+ * 1.21.0), then `1.21.1` (shipped as 1.22.0) — because the docs pass runs BEFORE semantic-release
+ * computes the number, so whatever is written is a guess. That would be a docs problem alone if it
+ * stayed in docs. It does not: `sync` copies `agent/rules/**` and `agent/skills/**` verbatim into
+ * every consumer, so "Since 1.21.1" is currently shipped, as fact, into seven repos.
+ *
+ * This is the gate that ends it, and it is mechanical rather than editorial: every basalt-shaped
+ * version literal in a file a consumer receives must appear as a release heading in CHANGELOG.md —
+ * the one file `semantic-release` writes AFTER the number exists. A guessed version fails here
+ * before it can ship.
+ *
+ * Deliberately NOT a ban on version literals: `agent/rules/**` is release-history prose and
+ * "widened at 1.21.0, promoted at 1.22.0" is exactly the sentence a consumer needs. What it may
+ * not do is name a release that does not exist.
+ *
+ * The complementary half — no version stamped into a file nothing ever rewrites — lives in
+ * `toolchain-wiring.test.ts` ("DESIGN.md carries no version").
+ *
+ * Run: bun test packages/basalt-ui/src/cli/shipped-versions.test.ts
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { join, relative, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'bun:test'
+
+const PKG_ROOT = fileURLToPath(new URL('../../', import.meta.url))
+
+/** Every version CHANGELOG.md records, plus the one package.json currently declares. */
+const RELEASED = new Set<string>([
+  ...(
+    readFileSync(resolve(PKG_ROOT, 'CHANGELOG.md'), 'utf8').match(/^#+\s*\[?(\d+\.\d+\.\d+)/gm) ??
+    []
+  ).map((h) => h.replace(/^#+\s*\[?/, '')),
+  (JSON.parse(readFileSync(resolve(PKG_ROOT, 'package.json'), 'utf8')) as { version: string })
+    .version,
+])
+
+/**
+ * basalt's own version line is 0.x / 1.x, so a literal with any other major belongs to a peer
+ * (visx 4.0.0, motion 12.42.0, the fontsource 5.2.x trio) and is none of this gate's business. A
+ * `^`/`~`/`@`-prefixed literal is a dependency RANGE for the same reason — `vite-plugin-pwa
+ * (^1.3.0)` shares a major with basalt and is still not a claim about basalt.
+ */
+const BASALT_VERSION_LITERAL = /(^|[^-~^@\w.])([01]\.\d+\.\d+)(?![\w.])/g
+
+function versionsIn(content: string): string[] {
+  return [...content.matchAll(BASALT_VERSION_LITERAL)].map((m) => m[2] as string)
+}
+
+/** Every file under `dir`, recursively. */
+function filesUnder(dir: string): string[] {
+  return readdirSync(dir).flatMap((name) => {
+    const abs = join(dir, name)
+    return statSync(abs).isDirectory() ? filesUnder(abs) : [abs]
+  })
+}
+
+// Everything `init`/`sync` place in a consumer repo, plus the presets they `extends` into.
+const SHIPPED = [
+  ...filesUnder(resolve(PKG_ROOT, 'agent')),
+  resolve(PKG_ROOT, 'configs/check.yml'),
+  resolve(PKG_ROOT, 'configs/lefthook.yml'),
+]
+
+describe('shipped agent assets name only versions that exist', () => {
+  it.each(SHIPPED.map((abs) => [relative(PKG_ROOT, abs), abs] as const))(
+    '%s',
+    (_rel, abs: string) => {
+      const unreleased = [...new Set(versionsIn(readFileSync(abs, 'utf8')))].filter(
+        (v) => !RELEASED.has(v),
+      )
+      expect(unreleased).toEqual([])
+    },
+  )
+
+  it('reads a real changelog, so an empty RELEASED set can never make this vacuous', () => {
+    expect(RELEASED.size).toBeGreaterThan(20)
+    expect(RELEASED.has('1.21.1')).toBe(false)
+  })
+})

package/src/cli/toolchain-wiring.test.ts

@@ -344,7 +344,7 @@ describe('check-theme — finds the config a root-invoked hook cannot see', () =
   it('reports ambiguity rather than guessing when two packages carry a config', () => {
     ambiguousWorkspace()
     const { code, log } = capture(() => checkTheme(dir))
-    expect(log).toContain('2 workspace packages carry one')
+    expect(log).toContain('2 packages below it carry one')
     expect(log).toContain('BASALT_CWD')
     expect(code).toBe(1)
   })
@@ -363,7 +363,7 @@ describe('doctor — an ambiguous project is terminal, exactly as it is for chec
   it('short-circuits instead of running every check against the wrong root', () => {
     ambiguousWorkspace()
     const { code, log } = capture(() => doctor(dir))
-    expect(log).toContain('2 workspace packages carry one')
+    expect(log).toContain('2 packages below it carry one')
     expect(log).toContain('BASALT_CWD')
     expect(code).toBe(1)
     // The bug this pins shut: falling back to the invocation cwd ran the remaining checks against
@@ -381,7 +381,7 @@ describe('doctor — an ambiguous project is terminal, exactly as it is for chec
   it('still runs normally once BASALT_CWD picks a package', () => {
     ambiguousWorkspace()
     const { code, log } = capture(() => doctor(join(dir, 'apps/a')))
-    expect(log).not.toContain('workspace packages carry one')
+    expect(log).not.toContain('packages below it carry one')
     expect(code).toBe(1) // no install / no manifest there — but the checks RAN
     expect(log).toContain('guard-scan')
   })
@@ -945,7 +945,7 @@ describe('sync — a scaffold is init’s decision, never a drift refresh’s',
     ambiguousWorkspace()
     const { code, log } = capture(() => sync({}, dir))
     expect(code).toBe(1)
-    expect(log).toContain('2 workspace packages carry one')
+    expect(log).toContain('2 packages below it carry one')
     expect(log).toContain('BASALT_CWD')
   })
 
@@ -1043,3 +1043,170 @@ describe('doctor — exit status per outcome, not per printed string', () => {
     expect(capture(() => doctor(dir, ['--tokens-only', '--framework'])).code).toBe(1)
   })
 })
+
+// ── the project resolver, for a repo that declares no workspaces ───────────────────────────────
+//
+// linewatch keeps its whole basalt consumer in `web/` and declares no `workspaces` field anywhere.
+// Measured at its repo root, all three project-scoped commands got that wrong in a different way:
+// `check-theme` printed `✓ no off-palette colors` having scanned ZERO files, `doctor` inferred
+// `tokens-only` for a full Mantine consumer, and `sync` refused while naming `basalt-ui init` as
+// the remedy — the one command that WOULD have written a competing install at the root. The
+// workspace-declaration path already handled image-share's `apps/admin`; nothing handled this.
+
+/** linewatch's shape: no `workspaces` field, the whole consumer one directory down. */
+function undeclaredChild(child = 'web'): void {
+  write('package.json', JSON.stringify({ name: 'root' }))
+  write(`${child}/package.json`, JSON.stringify({ name: child, basalt: { roots: ['src'] } }))
+  write(`${child}/src/app.tsx`, "export const c = '#ff0000'\n")
+  write(join(child, MANIFEST_PATH), JSON.stringify({ version: 1, files: {} }))
+}
+
+describe('resolveProjectDir — a repo that declares no workspaces still has a layout', () => {
+  it('sync relocates into the undeclared child instead of refusing with init as the advice', () => {
+    undeclaredChild()
+    const { log } = capture(() => sync({ check: true }, dir))
+    expect(log).toContain('running in ./web, where it lives')
+    expect(log).not.toContain('basalt-ui init')
+  })
+
+  it('sync writes NOTHING at the root it was invoked from', () => {
+    undeclaredChild()
+    capture(() => sync({}, dir))
+    expect(readdirSync(dir).toSorted()).toEqual(['package.json', 'web'])
+    expect(readPkg()['basalt']).toBeUndefined()
+  })
+
+  it('check-theme scans the child rather than reporting green over zero files', () => {
+    undeclaredChild()
+    const { code, log } = capture(() => checkTheme(dir, []))
+    expect(log).toContain('running in ./web, where it lives')
+    expect(log).not.toContain('no off-palette colors')
+    expect(code).toBe(1)
+  })
+
+  it('doctor reports on the child, so it cannot infer tokens-only from the empty root', () => {
+    undeclaredChild()
+    const { log } = capture(() => doctor(dir, []))
+    expect(log).toContain(join(dir, 'web'))
+    expect(log).not.toContain('profile: tokens-only')
+  })
+
+  it('two undeclared children are ambiguous, named, and never guessed between', () => {
+    undeclaredChild('web')
+    undeclaredChild('admin')
+    const { code, log } = capture(() => sync({}, dir))
+    expect(code).toBe(1)
+    expect(log).toContain('2 packages below it carry one')
+    expect(log).toContain('./admin')
+    expect(log).toContain('./web')
+    expect(readdirSync(dir)).not.toContain('DESIGN.md')
+  })
+
+  it('a declared workspaces field still wins — the layout scan is a fallback, not a union', () => {
+    // `stray/` carries a basalt key but is not a workspace package. Treating both as candidates
+    // would turn a working single-candidate repo into an ambiguity error on upgrade.
+    write('package.json', JSON.stringify({ name: 'root', workspaces: ['apps/*'] }))
+    write('apps/web/package.json', JSON.stringify({ name: 'web', basalt: { roots: ['src'] } }))
+    write('apps/web/src/app.tsx', 'export const App = () => null\n')
+    write(join('apps/web', MANIFEST_PATH), JSON.stringify({ version: 1, files: {} }))
+    write('stray/package.json', JSON.stringify({ name: 'stray', basalt: { roots: ['src'] } }))
+    const { log } = capture(() => sync({ check: true }, dir))
+    expect(log).toContain('running in ./apps/web, where it lives')
+  })
+})
+
+// ── sync honours the profile doctor already reads ──────────────────────────────────────────────
+//
+// rollhook is tokens-only in both apps and declares it. `sync` told it to run `basalt-ui init` —
+// the exact advice `doctor`, in the same directory at the same version, exists to prevent — and
+// exited 1, which also put `sync --check` out of reach of the one CI drift gate every other
+// consumer runs.
+
+describe('sync — tokens-only is a pass, not a refusal', () => {
+  function tokensOnly(): void {
+    write(
+      'package.json',
+      JSON.stringify({ name: 'marketing', basalt: { roots: ['src'], profile: 'tokens-only' } }),
+    )
+    write('src/app.ts', 'export const c = 1\n')
+  }
+
+  it('reports n/a and exits 0, mirroring doctor’s manifest row', () => {
+    tokensOnly()
+    const { code, log } = capture(() => sync({}, dir))
+    expect(code).toBe(0)
+    expect(log).toContain('n/a — a tokens-only consumer has no scaffold to reconcile')
+    expect(log).not.toContain('basalt-ui init')
+  })
+
+  it('is wirable into CI: --check exits 0 instead of failing on a scaffold it must not have', () => {
+    tokensOnly()
+    expect(capture(() => sync({ check: true, flags: [] }, dir)).code).toBe(0)
+  })
+
+  it('writes nothing — no manifest, no DESIGN.md, no basalt.roots backfill', () => {
+    tokensOnly()
+    capture(() => sync({}, dir))
+    expect(readdirSync(dir).toSorted()).toEqual(['package.json', 'src'])
+  })
+
+  it('--framework forces the full profile back on', () => {
+    tokensOnly()
+    const { code, log } = capture(() => sync({ flags: ['--framework'] }, dir))
+    expect(code).toBe(1)
+    expect(log).toContain('refusing to scaffold')
+  })
+
+  it('contradictory profile flags exit 1, exactly as they do for check-theme and doctor', () => {
+    tokensOnly()
+    expect(capture(() => sync({ flags: ['--tokens-only', '--framework'] }, dir)).code).toBe(1)
+  })
+})
+
+// ── no shipped artifact carries a version number that goes stale ───────────────────────────────
+//
+// `DESIGN.md` is a seed: written once at init, then consumer-owned and never reconciled. Its
+// opener stamped `{{BASALT_VERSION}}`, so across the seven consumers the same line read 1.0.0,
+// 1.9.0, 1.21.0 and 1.22.0 under an identical 1.22.0 install — reported three rounds running as
+// four separate doc bugs. It was one bug: a version number in a file nothing ever rewrites.
+
+describe('DESIGN.md carries no version, and sync heals the ones already written', () => {
+  function seeded(): void {
+    write('package.json', JSON.stringify({ name: 'fixture', basalt: { roots: ['src'] } }))
+    write('src/app.tsx', 'export const App = () => null\n')
+    capture(() => init(dir))
+  }
+
+  it('a fresh scaffold stamps no version at all', () => {
+    seeded()
+    expect(read('DESIGN.md')).not.toMatch(/Managed by basalt-ui \(\d+\.\d+\.\d+\)/)
+    expect(read('DESIGN.md')).toContain('run `basalt-ui doctor` for the version')
+  })
+
+  it('sync rewrites a stale opener in place and leaves the rest of the file alone', () => {
+    seeded()
+    const consumerOwned = '\n## Series\n\nOurs: hrv, rhr.\n'
+    write('DESIGN.md', `# app — Design\n\n> Managed by basalt-ui (1.9.0). Thin.\n${consumerOwned}`)
+    capture(() => sync({}, dir))
+    expect(read('DESIGN.md')).toContain(
+      '> Managed by basalt-ui — run `basalt-ui doctor` for the version. Thin.',
+    )
+    expect(read('DESIGN.md')).toContain(consumerOwned)
+  })
+
+  it('--check writes nothing, including the heal', () => {
+    seeded()
+    const stale = '# app — Design\n\n> Managed by basalt-ui (1.9.0). Thin.\n'
+    write('DESIGN.md', stale)
+    capture(() => sync({ check: true }, dir))
+    expect(read('DESIGN.md')).toBe(stale)
+  })
+
+  it('leaves an opener the consumer already rewrote by hand untouched', () => {
+    seeded()
+    const owned = '# app — Design\n\n> Our own words entirely.\n'
+    write('DESIGN.md', owned)
+    capture(() => sync({}, dir))
+    expect(read('DESIGN.md')).toBe(owned)
+  })
+})