basalt-ui 1.40.3 → 1.41.0

package/dist/cli/index.js

@@ -7,6 +7,7 @@ import {
   readFileSync,
   rmdirSync,
   statSync,
+  realpathSync,
   unlinkSync,
   writeFileSync
 } from "node:fs";
@@ -233,6 +234,8 @@ function waiverHintFor(relPath, profile) {
 const BLOCK_BEGIN_PREFIX = "<!-- basalt:begin";
 const BLOCK_END = "<!-- basalt:end -->";
 const MANIFEST_PATH = ".basalt/manifest.json";
+const AGENTS_MD = "AGENTS.md";
+const LEGACY_BLOCK_HOST = "CLAUDE.md";
 function sha256(text) {
   return createHash("sha256").update(text, "utf8").digest("hex");
 }
@@ -308,6 +311,91 @@ function applyBlock(host, block) {
 ${block.trim()}
 `;
 }
+function sameFile(a, b) {
+  try {
+    return realpathSync(a) === realpathSync(b);
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+function hasManagedBlock(host) {
+  return host !== null && host.includes(BLOCK_BEGIN_PREFIX);
+}
+function scanBlock(host) {
+  const begin = hasManagedBlock(host);
+  if (!begin && !host.includes(BLOCK_END)) return { region: null, problem: null };
+  const bad = (problem) => ({ region: null, problem });
+  if (!begin) return bad(`\`${BLOCK_END}\` with no \`${BLOCK_BEGIN_PREFIX}\``);
+  let region;
+  try {
+    region = findBlockRegion(host);
+  } catch (error) {
+    return bad(error.message);
+  }
+  if (region === null) return bad(`\`${BLOCK_BEGIN_PREFIX}\` has no matching \`${BLOCK_END}\``);
+  if (host.indexOf(BLOCK_END) < region.start || host.indexOf(BLOCK_END, region.end) !== -1) {
+    return bad(`an extra or misplaced \`${BLOCK_END}\` outside the basalt block`);
+  }
+  return { region, problem: null };
+}
+function isAgentsImportLine(line) {
+  return line.trim() === `@${AGENTS_MD}`;
+}
+function importsAgentsMd(text) {
+  return text.split(/\r?\n/).some(isAgentsImportLine);
+}
+function migrateBlockToAgentsMd(cwd, manifest, opts = {}) {
+  const legacyHash = manifest.files[LEGACY_BLOCK_HOST];
+  if (legacyHash !== void 0) {
+    manifest.files[AGENTS_MD] ??= legacyHash;
+    delete manifest.files[LEGACY_BLOCK_HOST];
+  }
+  const none = { pending: false, deletedHost: false, problem: null };
+  const legacyAbs = resolve(cwd, LEGACY_BLOCK_HOST);
+  const agentsAbs = resolve(cwd, AGENTS_MD);
+  const legacy = readIfExists(legacyAbs);
+  if (legacy === null) return none;
+  try {
+    if (sameFile(legacyAbs, agentsAbs)) return none;
+  } catch (error) {
+    const why = error.code ?? error.message;
+    return { ...none, problem: `cannot tell whether ${LEGACY_BLOCK_HOST} is ${AGENTS_MD} (${why})` };
+  }
+  const legacyScan = scanBlock(legacy);
+  const { region } = legacyScan;
+  if (legacyScan.problem !== null) {
+    return { ...none, problem: `${LEGACY_BLOCK_HOST}: ${legacyScan.problem}` };
+  }
+  if (region === null) return none;
+  const agents = readIfExists(agentsAbs) ?? "";
+  const agentsScan = scanBlock(agents);
+  if (agentsScan.problem !== null)
+    return { ...none, problem: `${AGENTS_MD}: ${agentsScan.problem}` };
+  const legacyBlock = legacy.slice(region.start, region.end);
+  if (agentsScan.region !== null && normalizeForLedger(agents.slice(agentsScan.region.start, agentsScan.region.end)) !== normalizeForLedger(legacyBlock)) {
+    return {
+      ...none,
+      problem: `${LEGACY_BLOCK_HOST} and ${AGENTS_MD} each carry a basalt block and they differ \u2014 delete the stale block from ${LEGACY_BLOCK_HOST} (or the one in ${AGENTS_MD}, if ${LEGACY_BLOCK_HOST}'s is the one you want kept), then re-run.`
+    };
+  }
+  const before = legacy.slice(0, region.start).trimEnd();
+  const after = legacy.slice(region.end).trimStart();
+  const remainder = before === "" || after === "" ? `${before}${after}` : `${before}
+
+${after}`;
+  const deletedHost = remainder.split(/\r?\n/).every((l) => l.trim() === "" || isAgentsImportLine(l));
+  if (opts.dryRun === true) return { pending: true, deletedHost, problem: null };
+  if (agentsScan.region === null) writeFileEnsuringDir(agentsAbs, applyBlock(agents, legacyBlock));
+  if (deletedHost) unlinkSync(legacyAbs);
+  else writeFileSync(legacyAbs, `${remainder.trimEnd()}
+`);
+  return { pending: true, deletedHost, problem: null };
+}
+function blockMigrationProblem(cwd) {
+  const { problem } = migrateBlockToAgentsMd(cwd, { version: 1, files: {} }, { dryRun: true });
+  return problem === null ? null : `${problem.replace(/\.$/, "")}. Nothing else was reconciled \u2014 resolve this by hand, then re-run.`;
+}
 function hasDependency(cwd, pkgName) {
   try {
     const pkg = JSON.parse(readFileSync(resolve(cwd, "package.json"), "utf8"));
@@ -397,15 +485,15 @@ function managedFiles(peers, placement = ROOT_PLACEMENT) {
     source: `agent/skills/${name}/SKILL.md`,
     render: (ctx) => readSource(ctx.pkgRoot, `agent/skills/${name}/SKILL.md`)
   }));
-  const claudeBlock = {
-    dest: "CLAUDE.md",
+  const agentsBlock = {
+    dest: AGENTS_MD,
     mode: "managed",
     markers: true,
-    source: "agent/templates/CLAUDE-block.md.tpl",
+    source: "agent/templates/AGENTS-block.md.tpl",
     // With markers, render() returns the fully-rendered region INCLUDING its begin/end markers.
-    // The writer splices it into the consumer's host CLAUDE.md at apply time.
+    // The writer splices it into the consumer's host AGENTS.md at apply time.
     render: (ctx) => {
-      const tpl = readSource(ctx.pkgRoot, "agent/templates/CLAUDE-block.md.tpl");
+      const tpl = readSource(ctx.pkgRoot, "agent/templates/AGENTS-block.md.tpl");
       if (tpl === null) return null;
       return fillTemplate(tpl, ctx.vars).trim();
     }
@@ -498,7 +586,7 @@ pre-commit:
   if (peers.hasQuery && placement.relocatedQueryClient === null) scaffolds.push(queryClient);
   if (peers.hasRouter && peers.hasQuery) scaffolds.push(rootRoute);
   const rootTooling = placement.isPackageRepoRoot ? [lefthook, ci] : [];
-  return [...rules, ...skills, claudeBlock, design, oxfmt, ...rootTooling, oxlintrc, ...scaffolds];
+  return [...rules, ...skills, agentsBlock, design, oxfmt, ...rootTooling, oxlintrc, ...scaffolds];
 }
 function placementNotices(cwd, placement) {
   const out = [];
@@ -558,6 +646,14 @@ Retired but locally edited, so left in place \u2014 your agent still loads them.
 ` + pruned.drifted.map((dest) => `  \xB7 ${dest}`).join("\n")
   );
 }
+function reportBlockMigration(migration, command) {
+  if (!migration.pending) return;
+  const tail = migration.deletedHost ? `${LEGACY_BLOCK_HOST} held nothing else and was deleted.` : `the rest of ${LEGACY_BLOCK_HOST} is yours; while it exists Claude Code loads it INSTEAD of ${AGENTS_MD} unless it imports @${AGENTS_MD} \u2014 move your content over and delete it.`;
+  console.log(
+    `
+basalt-ui ${command}: moved the basalt block from ${LEGACY_BLOCK_HOST} to ${AGENTS_MD} \u2014 ${tail}`
+  );
+}
 function pruneRetiredManagedFiles(cwd, manifest, files, opts = {}) {
   const result = { removed: [], drifted: [] };
   for (const dest of retiredManagedDests(manifest, files)) {
@@ -944,6 +1040,8 @@ function run(argv, cwd = process.cwd()) {
   }
 }
 export {
+  AGENTS_MD,
+  LEGACY_BLOCK_HOST,
   MANIFEST_PATH,
   OXLINT_FILES,
   OXLINT_NO_BIN,
@@ -954,6 +1052,7 @@ export {
   SKIP,
   basaltBinCommand,
   basaltPresetEntry,
+  blockMigrationProblem,
   checkTheme,
   classify,
   conflictingProfileFlags,
@@ -966,11 +1065,15 @@ export {
   fontsCss,
   guardHook,
   hasBasaltKey,
+  hasManagedBlock,
+  importsAgentsMd,
   init,
   inspectLefthookGate,
+  isAgentsImportLine,
   isStringArray,
   managedFiles,
   mergeOxlintExtends,
+  migrateBlockToAgentsMd,
   namesShipped,
   normalizeColorFunctions,
   normalizeForLedger,
@@ -989,6 +1092,7 @@ export {
   reconcileRoots,
   relativePosix,
   renderContext,
+  reportBlockMigration,
   reportPrune,
   resolveGuardConfig,
   resolvePeerFlags,
@@ -997,6 +1101,8 @@ export {
   retiredManagedDests,
   rootsNotices,
   run,
+  sameFile,
+  scanBlock,
   scannableFiles,
   sha256,
   shippedAssetPath,

package/dist/cli/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/cli/init.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAmB,aAAa,EAAE,MAAM,SAAS,CAAA;AA2C7D,yGAAyG;AACzG,wBAAgB,IAAI,CAAC,GAAG,GAAE,MAAsB,EAAE,aAAa,GAAE,aAAkB,GAAG,MAAM,CA4K3F"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/cli/init.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAmB,aAAa,EAAE,MAAM,SAAS,CAAA;AA8C7D,yGAAyG;AACzG,wBAAgB,IAAI,CAAC,GAAG,GAAE,MAAsB,EAAE,aAAa,GAAE,aAAkB,GAAG,MAAM,CAuL3F"}

package/dist/cli/init.js

@@ -3,9 +3,11 @@ import { resolve } from "node:path";
 import { deriveSpacing } from "../tokens/index.js";
 import {
   MANIFEST_PATH,
+  blockMigrationProblem,
   findBasaltInstall,
   managedFiles,
   mergeOxlintExtends,
+  migrateBlockToAgentsMd,
   normalizeForLedger,
   patchPackageJson,
   placementNotices,
@@ -13,6 +15,7 @@ import {
   readManifest,
   reconcileRoots,
   renderContext,
+  reportBlockMigration,
   reportPrune,
   resolvePeerFlags,
   resolvePlacement,
@@ -31,6 +34,11 @@ const KEPT_FILE_COST = {
   "DESIGN.md": "the design brief Claude reads is yours, not the seeded one."
 };
 function init(cwd = process.cwd(), scaffoldFlags = {}) {
+  const blockProblem = blockMigrationProblem(cwd);
+  if (blockProblem !== null) {
+    console.error(`\u2716 basalt-ui init: ${blockProblem}`);
+    return 1;
+  }
   const install = findBasaltInstall(cwd);
   if (install.dir === null) {
     console.error(
@@ -50,6 +58,7 @@ function init(cwd = process.cwd(), scaffoldFlags = {}) {
   const peers = resolvePeerFlags(cwd, scaffoldFlags);
   const placement = resolvePlacement(cwd);
   const files = managedFiles(peers, placement);
+  const migration = migrateBlockToAgentsMd(cwd, manifest);
   const writtenFiles = [];
   const keptFiles = [];
   const missingSources = [];
@@ -79,6 +88,7 @@ function init(cwd = process.cwd(), scaffoldFlags = {}) {
     `basalt-ui init: ${writtenFiles.length} written, ${keptFiles.length} kept, manifest at ${MANIFEST_PATH}`
   );
   reportPrune(pruned);
+  reportBlockMigration(migration, "init");
   if (missingSources.length > 0) {
     console.log(
       `basalt-ui init: ${missingSources.length} shipped asset(s) not present, skipped: ${missingSources.join(", ")}`

package/dist/cli/sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/cli/sync.ts"],"names":[],"mappings":"AA8CA,gGAAgG;AAChG,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAGjE;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,mGAAmG;IACnG,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC1B,CAAA;AAED;;;;;;;;;GASG;AACH;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAKrF;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQ5D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,IAAI,CAAC,IAAI,GAAE,WAAgB,EAAE,aAAa,GAAE,MAAsB,GAAG,MAAM,CAoM1F"}
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/cli/sync.ts"],"names":[],"mappings":"AAmDA,gGAAgG;AAChG,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAGjE;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,mGAAmG;IACnG,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC1B,CAAA;AAED;;;;;;;;;GASG;AACH;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAKrF;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQ5D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,IAAI,CAAC,IAAI,GAAE,WAAgB,EAAE,aAAa,GAAE,MAAsB,GAAG,MAAM,CAsN1F"}

package/dist/cli/sync.js

@@ -10,8 +10,12 @@ import {
   diffSummary,
   findBasaltInstall,
   inspectLefthookGate,
+  AGENTS_MD,
+  blockMigrationProblem,
   isStringArray,
+  LEGACY_BLOCK_HOST,
   managedFiles,
+  migrateBlockToAgentsMd,
   normalizeForLedger,
   noteRelocation,
   OXLINT_FILES,
@@ -25,6 +29,7 @@ import {
   reconcileRoots,
   relativePosix,
   renderContext,
+  reportBlockMigration,
   reportPrune,
   resolvePeerFlags,
   resolvePlacement,
@@ -72,12 +77,18 @@ function sync(opts = {}, invocationCwd = process.cwd()) {
     );
     return 1;
   }
+  const blockProblem = blockMigrationProblem(cwd);
+  if (blockProblem !== null) {
+    console.error(`\u2716 basalt-ui sync: ${blockProblem}`);
+    return 1;
+  }
   const rootsState = reconcileRoots(cwd, { write: opts.check !== true });
   const ctx = renderContext(cwd);
   const manifest = readManifest(cwd);
   const peers = resolvePeerFlags(cwd, {});
   const placement = resolvePlacement(cwd);
   const files = managedFiles(peers, placement);
+  const migration = migrateBlockToAgentsMd(cwd, manifest, { dryRun: opts.check === true });
   let updated = 0;
   let created = 0;
   let recreated = 0;
@@ -155,10 +166,15 @@ function sync(opts = {}, invocationCwd = process.cwd()) {
         `basalt-ui sync --check: ${retired.length} retired rule/skill file(s) still present: ${retired.join(", ")} \u2014 run \`basalt-ui sync\`.`
       );
     }
+    if (migration.pending) {
+      console.error(
+        `basalt-ui sync --check: the basalt block is still in ${LEGACY_BLOCK_HOST} \u2014 it now lives in ${AGENTS_MD}. Run \`basalt-ui sync\` to move it.`
+      );
+    }
     if (staleForCheck > 0) {
       console.error(`basalt-ui sync --check: ${staleForCheck} managed file(s) out of date.`);
-      return 1;
     }
+    if (staleForCheck > 0 || migration.pending) return 1;
     const n = placementSkips.length;
     const skips = n === 0 ? "" : ` (${n} permanent placement skip(s) \u2014 --verbose for detail)`;
     console.log(`\u2713 basalt-ui sync --check: all managed files current.${skips}`);
@@ -172,6 +188,7 @@ function sync(opts = {}, invocationCwd = process.cwd()) {
     `basalt-ui sync: ${updated} updated, ${created} created, ${recreated} recreated, ${skippedDrift} skipped (drift), ${pruned.removed.length} retired.`
   );
   reportPrune(pruned);
+  reportBlockMigration(migration, "sync");
   if (driftLines.length > 0) {
     console.log("Locally-edited files were skipped (run with --force to overwrite):");
     for (const l of driftLines) console.log(l);

package/dist/content/copy-action.d.ts

@@ -6,7 +6,7 @@
  *
  * The check + tooltip are the entire success signal — no notification (docs/CONTENT-SPEC.md §7).
  * `color="teal"` resolves through the bridged Mantine family, so it stays on the token layer in
- * both schemes (see the package CLAUDE.md on `cssVariablesResolver`).
+ * both schemes (see the package MAINTAINING.md on `cssVariablesResolver`).
  *
  * Not part of the public surface — reach it through `CodeBlock` / `HeadingAnchor`.
  */

package/dist/content/glyphs.d.ts

@@ -4,7 +4,7 @@
  * hand-drawn ones that drift apart.
  *
  * Inline SVG rather than an icon dep: the framework takes icons as `ReactNode` from the consumer
- * (see the package CLAUDE.md) and ships none, but these are internal chrome of a shipped component,
+ * (see the package MAINTAINING.md) and ships none, but these are internal chrome of a shipped component,
  * not a consumer-facing slot. `currentColor` + `1em`-agnostic sizing keeps them steerable from CSS
  * — the heading anchor sizes its glyph as an optical ratio of whatever step the heading lands on
  * (docs/DESIGN-SPEC.md §3), while the code-block chrome pins a fixed 14px.

package/dist/data/virtual-list.d.ts

@@ -103,7 +103,7 @@ export type BasaltVirtualListHandle = {
     /**
      * The underlying `@tanstack/react-virtual` instance — the full escape hatch. Returns the RAW
      * `@tanstack/react-virtual` `Virtualizer`, so a future major of that library reaching this shape
-     * ships here as a plain `feat:` under the no-majors doctrine (`../../CLAUDE.md` "Commit type
+     * ships here as a plain `feat:` under the no-majors doctrine (root `AGENTS.md` "Commit type
      * discipline"), not a silent break.
      */
     getVirtualizer: () => Virtualizer<HTMLDivElement, Element>;

package/llms.txt

@@ -1,4 +1,4 @@
-# basalt-ui v1.40.3
+# basalt-ui v1.41.0
 # Opinionated framework for Mantine-based React apps — theme, app shell, visx charts, toolchain presets
 #
 # basalt-ui is an opinionated framework for Mantine-based React apps.
@@ -19,7 +19,7 @@
 # ./tokens.css subpath. Guide: docs/FRAMEWORK-FREE.md in the repo.
 
 Package: basalt-ui
-Version: 1.40.3
+Version: 1.41.0
 
 ## basalt-ui
 Import: import { ... } from 'basalt-ui'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "basalt-ui",
-  "version": "1.40.3",
+  "version": "1.41.0",
   "description": "Opinionated framework for Mantine-based React apps — theme, app shell, visx charts, toolchain presets",
   "keywords": [
     "charts",

package/src/agent/foreign.ts

@@ -97,8 +97,9 @@ export type PartRenderContext<TPart = ForeignPart> = {
 export type PartRenderer<TPart = ForeignPart> = (ctx: PartRenderContext<TPart>) => ReactNode
 
 /**
- * Canonical const-generic factory (`packages/basalt-ui/CLAUDE.md`, "Canonical token-factory
- * contract") — identity passthrough, exact-keyed return, no builder, no config bag. Mirrors
+ * Canonical const-generic factory (`packages/basalt-ui/MAINTAINING.md` § "Token system — the
+ * derived palette", "Series color is consumer data") — identity passthrough, exact-keyed return,
+ * no builder, no config bag. Mirrors
  * `defineSeries` (`tokens/index.ts:648-650`) and `defineNotifications`
  * (`notifications/define-notifications.ts:112-115`).
  *

package/src/charts/index.ts

@@ -166,8 +166,8 @@ export {
 } from './sparklines'
 
 // ── Re-exported visx primitives ──────────────────────────────────────────
-// Bespoke charts (genuinely unique compositions per CLAUDE.md) need raw
-// visx primitives. Re-exporting them keeps the dependency declared in one
+// Bespoke charts (genuinely unique compositions, per `agent/rules/basalt-charts.md` "Adding a
+// chart") need raw visx primitives. Re-exporting them keeps the dependency declared in one
 // place and preserves the rule that consumers only import from `basalt-ui/charts`.
 export { Group } from '@visx/group'
 export { GridRows, GridColumns } from '@visx/grid'

package/src/cli/doctor.ts

@@ -8,6 +8,8 @@ import { relative, resolve } from 'node:path'
 
 import type { BasaltConfig } from './config'
 import {
+  AGENTS_MD,
+  LEGACY_BLOCK_HOST,
   MANIFEST_PATH,
   basaltBinCommand,
   basaltPresetEntry,
@@ -15,6 +17,7 @@ import {
   declaredProfile,
   findBasaltInstall,
   findRepoRoot,
+  importsAgentsMd,
   inspectLefthookGate,
   OXLINT_FILES,
   OXLINT_NO_BIN,
@@ -24,12 +27,23 @@ import {
   readIfExists,
   readManifest,
   resolveProjectDir,
+  sameFile,
   scannableFiles,
+  scanBlock,
   shippedAssetPath,
 } from './index'
 import { resolveRoots } from './config'
 import { findManifestAbove, parentInstallAdvice } from './sync'
 
+/** `sameFile`, but doctor never crashes: a path that cannot be inspected is "not provably the same". */
+function isSameFile(a: string, b: string): boolean {
+  try {
+    return sameFile(a, b)
+  } catch {
+    return false
+  }
+}
+
 export type DoctorResult = {
   /** Number of hard failures (exit non-zero). */
   hardFailures: number
@@ -108,7 +122,7 @@ 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}). Six checks, numbered in
+ * no ascend/descend project discovery (see {@link resolveProjectDir}). Seven checks, numbered in
  * the order they run and print:
  *
  * Hard failures (exit non-zero):
@@ -122,7 +136,7 @@ function resolveAiMajorSkewReason(cfg: BasaltConfig): {
  *      preset AND that path resolves (warns when no `oxlint` bin does). `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.
- *   6. `ai-major-parity`: within THIS package.json, `dependencies`/`devDependencies`/
+ *   7. `ai-major-parity`: within THIS package.json, `dependencies`/`devDependencies`/
  *      `peerDependencies` agree on the `ai` package's major — the shape `basalt/ai-sdk-major` (per
  *      linted FILE) cannot see. A skew is exempt-able via `basalt.aiMajorSkewReason` (a non-empty
  *      reason, not a bare `true`); a declared reason when the majors agree warns it is stale.
@@ -134,6 +148,9 @@ function resolveAiMajorSkewReason(cfg: BasaltConfig): {
  *      gate elsewhere); a config that resolves but wires no guard command warns; a config lefthook
  *      dump could not read at all (binary missing, or the dump failed) warns and says so, rather
  *      than inventing a verdict.
+ *   6. `claude-md`: a project-root `CLAUDE.md` that does not import `@AGENTS.md` suppresses
+ *      `AGENTS.md` (and with it the managed block); one that still carries a basalt block — or a
+ *      malformed one — says so. A `CLAUDE.md` symlinked to `AGENTS.md` is one file and passes.
  *
  * Returns the exit code: 0 = all good, 1 = one or more hard failures.
  */
@@ -193,7 +210,7 @@ export function doctor(invocationCwd: string = process.cwd(), flags: string[] =
 
   const install = findBasaltInstall(cwd)
 
-  // ── Hard check 2: install matches the manifest, and doctor says WHERE (the CLAUDE-block's claim)
+  // ── Hard check 2: install matches the manifest, and doctor says WHERE (the AGENTS-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) {
@@ -300,7 +317,33 @@ export function doctor(invocationCwd: string = process.cwd(), flags: string[] =
     )
   }
 
-  // ── Hard check 6: ai package major version parity within THIS package.json ─
+  // ── Warn check 6: a project-root CLAUDE.md that shadows AGENTS.md ───────────
+  // The managed block lives in AGENTS.md. Claude Code loads a repo-root AGENTS.md directly, but ANY
+  // CLAUDE.md in or above the cwd suppresses it unless that file imports `@AGENTS.md` — so a
+  // leftover CLAUDE.md means the block (and the rest of AGENTS.md) is not loaded, whether or not it
+  // still carries a block. A symlink to AGENTS.md is one file and is fine. Warn only: `sync`
+  // migrates the block, `sync --check` is the gate, and what else CLAUDE.md holds is the consumer's.
+  const legacyHost = resolve(cwd, LEGACY_BLOCK_HOST)
+  const legacy = profile === 'tokens-only' ? null : readIfExists(legacyHost)
+  if (legacy !== null && !isSameFile(legacyHost, resolve(cwd, AGENTS_MD))) {
+    const scan = scanBlock(legacy)
+    const issues: string[] = []
+    if (scan.problem !== null) {
+      issues.push(`has a malformed basalt block (${scan.problem}) — fix it by hand, then \`sync\``)
+    } else if (scan.region !== null) {
+      issues.push(`still carries a stale basalt block — run \`basalt-ui sync\` to move it`)
+    }
+    if (!importsAgentsMd(legacy)) {
+      issues.push(
+        `does not import \`@${AGENTS_MD}\`, so Claude Code loads it INSTEAD of ${AGENTS_MD} and the ` +
+          `basalt block never reaches the agent — move its content into ${AGENTS_MD} and delete it, ` +
+          `or add \`@${AGENTS_MD}\``,
+      )
+    }
+    if (issues.length > 0) warn(`${LEGACY_BLOCK_HOST} ${issues.join('; and ')}.`)
+  }
+
+  // ── Hard check 7: 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/