basalt-ui 1.40.2 → 1.41.0

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/

package/src/cli/index.ts

@@ -14,6 +14,7 @@ import {
   readFileSync,
   rmdirSync,
   statSync,
+  realpathSync,
   unlinkSync,
   writeFileSync,
 } from 'node:fs'
@@ -338,7 +339,7 @@ export function resolveProjectDir(cwd: string): ProjectResolution {
 /**
  * Which shape of consumer a project-scoped command is looking at — DECLARED, never inferred
  * (`--tokens-only`, or `"basalt": { "profile": "tokens-only" }`), because the answer switches the
- * Mantine-remedy guard kinds off. Why that direction: package CLAUDE.md § CLI.
+ * Mantine-remedy guard kinds off. Why that direction: package MAINTAINING.md § CLI.
  */
 export function declaredProfile(cfg: BasaltConfig, flags: readonly string[]): DoctorProfile {
   if (flags.includes('--tokens-only')) return 'tokens-only'
@@ -452,7 +453,7 @@ export function waiverHintFor(relPath: string, profile: DoctorProfile): string {
  *
  * - `managed` : basalt owns it. sync refreshes it to the shipped version; a local edit is skipped
  *               and reported (`--force` overwrites); `--check` exits 1 on drift. Applies to exactly
- *               what Claude reads (.claude/rules/*, .claude/skills/*, the CLAUDE.md block) —
+ *               what Claude reads (.claude/rules/*, .claude/skills/*, the AGENTS.md block) —
  *               Claude Code cannot load rules or skills from node_modules, and that platform limit
  *               is the only reason anything is copied at all. The sync diff is the review gate.
  * - `seed`    : written once if absent, then owned entirely by the consumer. sync never overwrites
@@ -462,7 +463,7 @@ export function waiverHintFor(relPath: string, profile: DoctorProfile): string {
  *               the package while the consumer still owns the file.
  *
  * A managed file with `markers: true` is spliced as a `<!-- basalt:begin -->…<!-- basalt:end -->`
- * region inside a host file the consumer otherwise owns (CLAUDE.md) — not a third mode, just
+ * region inside a host file the consumer otherwise owns (AGENTS.md) — not a third mode, just
  * managed ownership scoped to a region.
  */
 type Mode = 'managed' | 'seed'
@@ -518,11 +519,15 @@ type TemplateVars = {
   BASALT_BIN: string
 }
 
-// The block markers the CLAUDE.md template emits. The begin marker carries the framework version
+// The block markers the AGENTS.md template emits. The begin marker carries the framework version
 // (`<!-- basalt:begin 1.0.0 -->`), so the region is matched by the begin PREFIX, not an exact string.
 const BLOCK_BEGIN_PREFIX = '<!-- basalt:begin'
 const BLOCK_END = '<!-- basalt:end -->'
 export const MANIFEST_PATH = '.basalt/manifest.json'
+/** The host file the managed block is spliced into (and its manifest key). */
+export const AGENTS_MD = 'AGENTS.md'
+/** Where the block lived before it moved to {@link AGENTS_MD} — read only to migrate out of it. */
+export const LEGACY_BLOCK_HOST = 'CLAUDE.md'
 
 export function sha256(text: string): string {
   return createHash('sha256').update(text, 'utf8').digest('hex')
@@ -633,6 +638,156 @@ function applyBlock(host: string, block: string): string {
   return base.length === 0 ? `${block.trim()}\n` : `${base}\n\n${block.trim()}\n`
 }
 
+/** True when both paths resolve to one file (a symlinked pair). A missing path is simply "no". */
+export function sameFile(a: string, b: string): boolean {
+  try {
+    return realpathSync(a) === realpathSync(b)
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false
+    throw error
+  }
+}
+
+/** True when the host text carries a managed block (begin marker present). */
+export function hasManagedBlock(host: string | null): boolean {
+  return host !== null && host.includes(BLOCK_BEGIN_PREFIX)
+}
+
+/**
+ * The block region of a host, or why it cannot be read: duplicate begin markers, or a begin marker
+ * with no end. The ONE detector `migrateBlockToAgentsMd` and `doctor` share, so they cannot disagree
+ * about whether a `CLAUDE.md` is well-formed.
+ */
+export function scanBlock(host: string): {
+  region: { start: number; end: number } | null
+  problem: string | null
+} {
+  const begin = hasManagedBlock(host)
+  if (!begin && !host.includes(BLOCK_END)) return { region: null, problem: null }
+  const bad = (problem: string): { region: null; problem: string } => ({ region: null, problem })
+  if (!begin) return bad(`\`${BLOCK_END}\` with no \`${BLOCK_BEGIN_PREFIX}\``)
+  let region: { start: number; end: number } | null
+  try {
+    region = findBlockRegion(host)
+  } catch (error) {
+    return bad((error as Error).message)
+  }
+  if (region === null) return bad(`\`${BLOCK_BEGIN_PREFIX}\` has no matching \`${BLOCK_END}\``)
+  // Exactly one end marker, after the begin: an orphan or extra one means the region is a guess.
+  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 }
+}
+
+/** One line that is exactly the `@AGENTS.md` import — not a prose or code-span mention, not `.bak`. */
+export function isAgentsImportLine(line: string): boolean {
+  return line.trim() === `@${AGENTS_MD}`
+}
+
+/** Whether a `CLAUDE.md` imports `AGENTS.md`, so Claude Code still loads it. */
+export function importsAgentsMd(text: string): boolean {
+  return text.split(/\r?\n/).some(isAgentsImportLine)
+}
+
+export type BlockMigration = {
+  /** The legacy host (`CLAUDE.md`) carried a managed block that has to move. */
+  pending: boolean
+  /** The legacy host was left empty (or `@AGENTS.md` only) and removed. */
+  deletedHost: boolean
+  /** Why nothing was moved and the run must fail: malformed markers, or two differing blocks. */
+  problem: string | null
+}
+
+/**
+ * Move the managed block out of `CLAUDE.md` into `AGENTS.md` (an install from before the move).
+ * Idempotent: a second run finds nothing and returns `pending: false`.
+ *  1. The ledger entry is re-keyed `CLAUDE.md` → `AGENTS.md` in memory (the caller persists it), so
+ *     an unedited legacy block classifies `unchanged`, not untracked.
+ *  2. The region is cut out of `CLAUDE.md` and — unless `AGENTS.md` already has one — spliced into
+ *     `AGENTS.md` AS IT IS, not as the new rendering: the normal three-way classify then sees a
+ *     hand-edit and skips it like any drifted unit. The rest of `CLAUDE.md` is consumer-owned and
+ *     stays, except the file is deleted when nothing but whitespace or `@AGENTS.md` is left.
+ *  3. Nothing is discarded silently: if `AGENTS.md` already has a block that differs (normalized,
+ *     as the ledger compares) from the legacy one, or either file's markers are malformed, BOTH
+ *     files are left byte-identical and `problem` says what to resolve by hand.
+ * `dryRun` (`sync --check`) writes nothing but still reports `pending` and `problem`.
+ */
+export function migrateBlockToAgentsMd(
+  cwd: string,
+  manifest: Manifest,
+  opts: { dryRun?: boolean } = {},
+): BlockMigration {
+  const legacyHash = manifest.files[LEGACY_BLOCK_HOST]
+  if (legacyHash !== undefined) {
+    manifest.files[AGENTS_MD] ??= legacyHash
+    delete manifest.files[LEGACY_BLOCK_HOST]
+  }
+  const none: BlockMigration = { 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
+  // A symlinked pair is one file: cutting the block out of "CLAUDE.md" would cut AGENTS.md too.
+  // Fail closed when that cannot be proven (EACCES, ELOOP, …) — and say so, not a stack trace.
+  try {
+    if (sameFile(legacyAbs, agentsAbs)) return none
+  } catch (error) {
+    const why = (error as NodeJS.ErrnoException).code ?? (error as 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 — ` +
+        `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}\n\n${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()}\n`)
+  return { pending: true, deletedHost, problem: null }
+}
+
+/**
+ * The refusal `init` and `sync` run BEFORE any side effect (roots patch, package.json script,
+ * manifest): a dry-run migration against a scratch manifest, so a block that cannot be moved
+ * safely stops the command with nothing written. Null = safe to proceed.
+ */
+export function blockMigrationProblem(cwd: string): string | null {
+  const { problem } = migrateBlockToAgentsMd(cwd, { version: 1, files: {} }, { dryRun: true })
+  return problem === null
+    ? null
+    : `${problem.replace(/\.$/, '')}. Nothing else was reconciled — resolve this by hand, then re-run.`
+}
+
 /**
  * Explicit `--with-router` / `--with-query` CLI flags force-include a router/query scaffold even
  * when the peer isn't detected in the consumer's package.json yet (e.g. it's about to be added).
@@ -809,15 +964,17 @@ export function managedFiles(
     render: (ctx: RenderContext) => readSource(ctx.pkgRoot, `agent/skills/${name}/SKILL.md`),
   }))
 
-  const claudeBlock: ManagedFile = {
-    dest: 'CLAUDE.md',
+  // AGENTS.md, not CLAUDE.md: Claude Code loads a repo-root AGENTS.md directly, but ANY CLAUDE.md
+  // in or above the cwd suppresses it — so the block must not be the reason a CLAUDE.md exists.
+  const agentsBlock: ManagedFile = {
+    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()
     },
@@ -946,7 +1103,7 @@ export function managedFiles(
   // lefthook/CI config, and writing over or beside it is worse than not writing at all.
   const rootTooling: ManagedFile[] = placement.isPackageRepoRoot ? [lefthook, ci] : []
 
-  return [...rules, ...skills, claudeBlock, design, oxfmt, ...rootTooling, oxlintrc, ...scaffolds]
+  return [...rules, ...skills, agentsBlock, design, oxfmt, ...rootTooling, oxlintrc, ...scaffolds]
 }
 
 /**
@@ -1086,6 +1243,18 @@ export function reportPrune(pruned: PruneResult): void {
   )
 }
 
+/** Name what {@link migrateBlockToAgentsMd} did — a file leaving a consumer's tree is never silent. */
+export function reportBlockMigration(migration: BlockMigration, command: 'init' | 'sync'): void {
+  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} — move your content over and delete it.`
+  console.log(
+    `\nbasalt-ui ${command}: moved the basalt block from ${LEGACY_BLOCK_HOST} to ${AGENTS_MD} — ${tail}`,
+  )
+}
+
 /**
  * Delete the managed rule/skill files this basalt version retired, and drop their manifest entries.
  *
@@ -1194,7 +1363,7 @@ type Classification = 'unchanged' | 'drifted' | 'missing' | 'current'
  *  - Blank out the per-release `BASALT_VERSION` token in a marker's begin line
  *    (`<!-- basalt:begin 1.0.1 -->` → `<!-- basalt:begin -->`). It changes on every release and is
  *    the only per-release variable that lands INSIDE the hashed region (the rest of
- *    `CLAUDE-block.md.tpl` has no other `{{…}}` placeholders today), so stripping it is what lets
+ *    `AGENTS-block.md.tpl` has no other `{{…}}` placeholders today), so stripping it is what lets
  *    one normalized rendering stand in for every version of a given template body instead of
  *    needing one ledger entry per release. If a future marker template interpolates another
  *    per-release var inside its region, extend this normalization the same way.

package/src/cli/init.ts

@@ -10,9 +10,11 @@ import { deriveSpacing } from '../tokens'
 import type { MergeLintResult, ScaffoldFlags } from './index'
 import {
   MANIFEST_PATH,
+  blockMigrationProblem,
   findBasaltInstall,
   managedFiles,
   mergeOxlintExtends,
+  migrateBlockToAgentsMd,
   normalizeForLedger,
   patchPackageJson,
   placementNotices,
@@ -20,6 +22,7 @@ import {
   readManifest,
   reconcileRoots,
   renderContext,
+  reportBlockMigration,
   reportPrune,
   resolvePeerFlags,
   resolvePlacement,
@@ -52,6 +55,13 @@ const KEPT_FILE_COST: Record<string, string> = {
 
 /** Scaffold all managed files into the consumer repo, then write the manifest. Idempotent. Returns 0. */
 export function init(cwd: string = process.cwd(), scaffoldFlags: ScaffoldFlags = {}): number {
+  // First, before anything is written: a block that cannot be moved safely refuses the whole run.
+  const blockProblem = blockMigrationProblem(cwd)
+  if (blockProblem !== null) {
+    console.error(`✖ basalt-ui init: ${blockProblem}`)
+    return 1
+  }
+
   // ── Describe the repo BEFORE rendering anything ───────────────────────────
   // Every roots-derived seed (the CI oxfmt globs, DESIGN.md's series path, the default scan
   // exemption) renders from `basalt.roots`, so the key has to exist first. Writing it is what
@@ -86,6 +96,9 @@ export function init(cwd: string = process.cwd(), scaffoldFlags: ScaffoldFlags =
   const placement = resolvePlacement(cwd)
   const files = managedFiles(peers, placement)
 
+  // Before the loop: an install from before the move carries the block in CLAUDE.md.
+  const migration = migrateBlockToAgentsMd(cwd, manifest)
+
   const writtenFiles: string[] = []
   const keptFiles: string[] = []
   const missingSources: string[] = []
@@ -131,6 +144,7 @@ export function init(cwd: string = process.cwd(), scaffoldFlags: 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/src/cli/sync.ts

@@ -17,8 +17,12 @@ import {
   diffSummary,
   findBasaltInstall,
   inspectLefthookGate,
+  AGENTS_MD,
+  blockMigrationProblem,
   isStringArray,
+  LEGACY_BLOCK_HOST,
   managedFiles,
+  migrateBlockToAgentsMd,
   normalizeForLedger,
   noteRelocation,
   OXLINT_FILES,
@@ -32,6 +36,7 @@ import {
   reconcileRoots,
   relativePosix,
   renderContext,
+  reportBlockMigration,
   reportPrune,
   resolvePeerFlags,
   resolvePlacement,
@@ -149,6 +154,13 @@ export function sync(opts: SyncOptions = {}, invocationCwd: string = process.cwd
     return 1
   }
 
+  // A block that cannot be moved safely refuses the whole run BEFORE reconcileRoots writes anything.
+  const blockProblem = blockMigrationProblem(cwd)
+  if (blockProblem !== null) {
+    console.error(`✖ basalt-ui sync: ${blockProblem}`)
+    return 1
+  }
+
   // Before renderContext, which reads `basalt.roots` for the roots-derived template variables.
   const rootsState = reconcileRoots(cwd, { write: opts.check !== true })
   const ctx = renderContext(cwd)
@@ -157,6 +169,10 @@ export function sync(opts: SyncOptions = {}, invocationCwd: string = process.cwd
   const placement = resolvePlacement(cwd)
   const files = managedFiles(peers, placement)
 
+  // Before the loop: the block moved from CLAUDE.md to AGENTS.md, and the loop reads AGENTS.md.
+  // `--check` only reports it (and stays red until a real sync moves it).
+  const migration = migrateBlockToAgentsMd(cwd, manifest, { dryRun: opts.check === true })
+
   let updated = 0
   // `created` and `recreated` were one counter, and `0 updated, 20 recreated` is what a full
   // scaffold printed — a word that means "it was here, it went missing, I put it back" describing
@@ -272,10 +288,16 @@ export function sync(opts: SyncOptions = {}, invocationCwd: string = process.cwd
           `${retired.join(', ')} — run \`basalt-ui sync\`.`,
       )
     }
+    if (migration.pending) {
+      console.error(
+        `basalt-ui sync --check: the basalt block is still in ${LEGACY_BLOCK_HOST} — 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) — --verbose for detail)`
     console.log(`✓ basalt-ui sync --check: all managed files current.${skips}`)
@@ -291,6 +313,7 @@ export function sync(opts: SyncOptions = {}, invocationCwd: string = process.cwd
       `${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/src/commands/shortcut-format.ts

@@ -9,7 +9,7 @@
  * parseShortcut('Mod+S', false)  // ['Ctrl', 'S']
  *
  * // Single display string for Spotlight description:
- * formatShortcutDisplay('Mod+S', true)   // '⌘ S' on mac
+ * formatShortcutDisplay('Mod+S', true)   // '⌘S' on mac
  * formatShortcutDisplay('Mod+S', false)  // 'Ctrl+S' on windows
  */
 
@@ -30,19 +30,54 @@ export function detectMac(): boolean {
 
 // ── parseShortcut ─────────────────────────────────────────────────────────────
 
+/** Named keys → [mac glyph, other-platform word]. Keys are the lower-cased shortcut token. */
+const NAMED_KEYS: Record<string, readonly [mac: string, other: string]> = {
+  backspace: ['⌫', 'Backspace'],
+  delete: ['⌦', 'Delete'],
+  del: ['⌦', 'Delete'],
+  arrowleft: ['←', 'Left'],
+  arrowright: ['→', 'Right'],
+  arrowup: ['↑', 'Up'],
+  arrowdown: ['↓', 'Down'],
+  left: ['←', 'Left'],
+  right: ['→', 'Right'],
+  up: ['↑', 'Up'],
+  down: ['↓', 'Down'],
+  escape: ['⎋', 'Esc'],
+  esc: ['⎋', 'Esc'],
+  enter: ['↩', 'Enter'],
+  return: ['↩', 'Enter'],
+  tab: ['⇥', 'Tab'],
+  space: ['␣', 'Space'],
+  home: ['↖', 'Home'],
+  end: ['↘', 'End'],
+  pageup: ['⇞', 'PgUp'],
+  pagedown: ['⇟', 'PgDn'],
+}
+
+/** A key that is not a modifier or a named key: a single character upper-cases (`s` → `S`), any
+ * other word title-cases (`f5` → `F5`, `insert` → `Insert`). */
+function plainKey(key: string): string {
+  return key.length === 1 ? key.toUpperCase() : key.charAt(0).toUpperCase() + key.slice(1)
+}
+
 /**
  * Convert a shortcut string to a list of Kbd-friendly tokens.
  * 'Mod+S' → ['⌘', 'S'] (mac) or ['Ctrl', 'S'] (other).
  * 'Shift+Mod+P' → ['⇧', '⌘', 'P'] (mac) or ['Shift', 'Ctrl', 'P'] (other).
+ * Named keys read as glyphs on mac and Title-case words elsewhere:
+ * 'Mod+Backspace' → ['⌘', '⌫'] (mac) or ['Ctrl', 'Backspace'] (other).
  * isMac is the post-mount platform flag; defaults false on SSR / first render.
  *
  * @example
  * parseShortcut('Mod+S', true)         // ['⌘', 'S']
  * parseShortcut('Shift+Mod+P', false)  // ['Shift', 'Ctrl', 'P']
+ * parseShortcut('ArrowLeft', true)     // ['←']
  */
 export function parseShortcut(shortcut: string, isMac: boolean): string[] {
   return shortcut.split('+').map((key) => {
-    switch (key.toLowerCase()) {
+    const lower = key.toLowerCase()
+    switch (lower) {
       case 'mod':
         return isMac ? '⌘' : 'Ctrl'
       case 'shift':
@@ -52,9 +87,12 @@ export function parseShortcut(shortcut: string, isMac: boolean): string[] {
       case 'meta':
         return isMac ? '⌘' : 'Meta'
       case 'ctrl':
-        return isMac ? '^' : 'Ctrl'
-      default:
-        return key.toUpperCase()
+        return isMac ? '⌃' : 'Ctrl'
+      default: {
+        const named = NAMED_KEYS[lower]
+        if (named !== undefined) return isMac ? named[0] : named[1]
+        return plainKey(key)
+      }
     }
   })
 }
@@ -63,7 +101,8 @@ export function parseShortcut(shortcut: string, isMac: boolean): string[] {
 
 /**
  * Format a shortcut string for inline display (e.g. Spotlight action description).
- * Returns a compact string like '⌘ S' (mac) or 'Ctrl+S' (windows).
+ * Returns a compact string like '⌘S' / '⌘⌫' (mac, glyphs with no separator) or 'Ctrl+S' /
+ * 'Ctrl+Backspace' (elsewhere, Title-case words joined with '+').
  *
  * isMac is the post-mount platform flag. Pass false on SSR / first client render.
  *
@@ -72,12 +111,12 @@ export function parseShortcut(shortcut: string, isMac: boolean): string[] {
  * always-on and produces the same tokens via parseShortcut.
  *
  * @example
- * formatShortcutDisplay('Mod+S', true)         // '⌘ S'
+ * formatShortcutDisplay('Mod+S', true)          // '⌘S'
+ * formatShortcutDisplay('Mod+Backspace', true)  // '⌘⌫'
  * formatShortcutDisplay('Mod+S', false)         // 'Ctrl+S'
- * formatShortcutDisplay('Shift+Mod+P', true)    // '⇧ ⌘ P'
+ * formatShortcutDisplay('Shift+Mod+P', true)    // '⇧⌘P'
  */
 export function formatShortcutDisplay(shortcut: string, isMac: boolean): string {
   const tokens = parseShortcut(shortcut, isMac)
-  // Mac uses space-separated symbols (⌘ S); windows uses + (Ctrl+S)
-  return isMac ? tokens.join(' ') : tokens.join('+')
+  return tokens.join(isMac ? '' : '+')
 }

package/src/content/copy-action.tsx

@@ -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/src/content/glyphs.tsx

@@ -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/src/data/virtual-list.tsx

@@ -146,7 +146,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/src/guard/index.ts

@@ -788,7 +788,7 @@ function insideHostTag(codeText: string, offset: number): boolean {
  *
  * KEBAB and PascalCase both count, because a repo picks one file-naming law and the convention has
  * to survive either: `edit-session-modal.tsx`, and `CbbiPanel.tsx` in a repo mandating
- * `PascalCase.tsx` for component files (basalt's own root `CLAUDE.md` included). Each needs the
+ * `PascalCase.tsx` for component files (basalt's own root `AGENTS.md` included). Each needs the
  * leading SUBJECT — a bare `modal.tsx` / `Panel.tsx` is a page module, not the convention.
  *
  * The trade is that a whole file goes unscanned on a naming convention — the same bargain