basalt-ui 1.40.3 → 1.41.0

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/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