@spectrabrain/eds 0.0.4 → 0.1.1

package/consumer/register-scripts.mjs

@@ -0,0 +1,129 @@
+import fs from "node:fs";
+import path from "node:path";
+import { cliCommand, detectIndent, detectPackageManager, runnerCommand } from "./paths.mjs";
+
+export const syncCommand = "eds sync";
+export const doctorCommand = "eds doctor";
+export const syncScriptName = "sync:eds";
+export const doctorScriptName = "eds:doctor";
+
+const legacyRunnerCommand = "node --input-type=module -e \"import('@spectrabrain/eds/consumer-sync.mjs')\"";
+const requiredScripts = {
+  [syncScriptName]: syncCommand,
+  [doctorScriptName]: doctorCommand,
+};
+const legacyScripts = {
+  [syncScriptName]: [
+    "npm run update:eds-agent-context && npm run generate:eds-tailwind",
+    "npm run update:eds-agent-context && npm run generate-eds-tailwind",
+  ],
+  "update:eds-agent-context": [legacyRunnerCommand],
+  "generate:eds-tailwind": [legacyRunnerCommand],
+};
+const hookScripts = [
+  { name: "pretypecheck", target: "typecheck" },
+  { name: "prebuild", target: "build" },
+];
+
+export function writeConsumerPackageJson(packagePath, source, consumerPackage) {
+  const trailingNewline = source.endsWith("\n") ? "\n" : "";
+  fs.writeFileSync(packagePath, JSON.stringify(consumerPackage, null, detectIndent(source)) + trailingNewline);
+}
+
+// A consumer may wrap the EDS command (for example `cross-env EDS_DOCTOR=warn eds doctor`). Any script that
+// still runs the EDS command counts as registered; only scripts that do not run it are reported.
+export function isCompatibleCommand(value, command) {
+  if (typeof value !== "string") {
+    return false;
+  }
+  const escaped = command.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp("(^|[\\s&|;(])" + escaped + "($|[\\s&|;)])").test(value);
+}
+
+export function registerConsumerScripts(
+  consumerRoot,
+  { log = console.log, dryRun = false, packageManager = detectPackageManager(consumerRoot) } = {},
+) {
+  const packagePath = path.join(consumerRoot, "package.json");
+  const source = fs.readFileSync(packagePath, "utf8");
+  const consumerPackage = JSON.parse(source);
+  const scripts = { ...(consumerPackage.scripts ?? {}) };
+  const result = { changed: false, added: [], migrated: [], removed: [], skippedHooks: [], conflicts: [], syncRunCommand: null };
+
+  for (const [name, command] of Object.entries(requiredScripts)) {
+    if (isCompatibleCommand(scripts[name], command)) {
+      continue;
+    }
+    if (scripts[name] === undefined) {
+      scripts[name] = command;
+      result.added.push(name);
+      continue;
+    }
+    if (legacyScripts[name]?.includes(scripts[name])) {
+      scripts[name] = command;
+      result.migrated.push(name);
+      continue;
+    }
+    // Never fail the install over a consumer-owned script: leave it alone and let doctor report it.
+    result.conflicts.push(name);
+    log(
+      `[EDS] package.json script ${name} runs ${JSON.stringify(scripts[name])}; left unchanged. ` +
+        `eds doctor reports it until the script runs "${command}".`,
+    );
+  }
+
+  for (const [name, commands] of Object.entries(legacyScripts)) {
+    if (requiredScripts[name] === undefined && commands.includes(scripts[name])) {
+      delete scripts[name];
+      result.removed.push(name);
+    }
+  }
+
+  const hookTargets = [];
+  for (const hook of hookScripts) {
+    if (scripts[hook.target] === undefined) {
+      continue;
+    }
+    hookTargets.push(hook.target);
+    if (isCompatibleCommand(scripts[hook.name], doctorCommand)) {
+      continue;
+    }
+    if (scripts[hook.name] === undefined) {
+      scripts[hook.name] = doctorCommand;
+      result.added.push(hook.name);
+      continue;
+    }
+    result.skippedHooks.push(hook.name);
+    log(
+      `[EDS] ${hook.name} already runs ${JSON.stringify(scripts[hook.name])}; left unchanged. Change it to ` +
+        `${JSON.stringify(doctorCommand + " && " + scripts[hook.name])} so ${doctorCommand} gates ${hook.target}.`,
+    );
+  }
+
+  result.changed = result.added.length > 0 || result.migrated.length > 0 || result.removed.length > 0;
+  // When sync:eds belongs to the consumer, point at the CLI instead of their script. The caller prints the next
+  // step: init runs sync right away, postinstall tells the consumer to run it.
+  result.syncRunCommand = result.conflicts.includes(syncScriptName) ? cliCommand(packageManager, "sync") : runnerCommand(packageManager, syncScriptName);
+  if (result.changed && dryRun) {
+    log("[EDS] would update package.json scripts: " + [...result.added, ...result.migrated, ...result.removed].join(", "));
+  } else if (result.changed) {
+    consumerPackage.scripts = scripts;
+    writeConsumerPackageJson(packagePath, source, consumerPackage);
+    log("[EDS] Added the EDS scripts to package.json: " + [...result.added, ...result.migrated].join(", ") +
+      (result.removed.length > 0 ? " (removed " + result.removed.join(", ") + ")" : "") + ".");
+  } else if (result.conflicts.length === 0) {
+    log("[EDS] The EDS scripts are already registered.");
+  } else {
+    log("[EDS] The EDS scripts were left unchanged.");
+  }
+
+  // Yarn berry (2+) does not run pre/post lifecycle hooks, so the doctor gate must be inlined by the consumer.
+  if (packageManager?.name === "yarn" && packageManager.berry && hookTargets.length > 0) {
+    log(
+      "[EDS] Yarn 2+ does not run pretypecheck/prebuild hooks. Prepend \"" + doctorCommand +
+        " && \" to your " + hookTargets.join(" and ") + " script" + (hookTargets.length > 1 ? "s" : "") +
+        " to keep the doctor gate (this tool does not edit them).",
+    );
+  }
+  return result;
+}

package/consumer/scan-classes.mjs

@@ -0,0 +1,71 @@
+import { relativeTo } from "./paths.mjs";
+
+// Tailwind utilities that take a color. A class such as hover:bg-eds-bg-brand-primary/80 is one token here. Token names keep
+// their case (stroke-focusRing), so a miscased class is reported instead of skipped.
+const colorUtility = "(?:text|bg|border|ring|outline|fill|stroke|decoration|divide|from|to|via|accent|caret|shadow|placeholder|inset-ring)";
+const variantPrefix = "(?:[a-z0-9-]+:)*";
+const boundaryBefore = "(?<![\\w-])";
+const boundaryAfter = "(?![\\w-])";
+const opacity = "(?:/[0-9]{1,3})?";
+
+const edsColorClass = new RegExp(boundaryBefore + variantPrefix + colorUtility + "-eds-([A-Za-z0-9-]+)" + opacity + boundaryAfter, "g");
+const edsTypographyClass = new RegExp(boundaryBefore + variantPrefix + "eds-typography-([A-Za-z0-9-]+)" + boundaryAfter, "g");
+const rawColorClass = new RegExp(
+  boundaryBefore + variantPrefix + colorUtility +
+    "-(?:(?:slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-[0-9]{2,3}|white|black|\\[(?:#|rgba?\\(|hsla?\\(|oklch\\(|oklab\\(|color\\()[^\\]]*\\])" +
+    opacity + boundaryAfter,
+  "g",
+);
+
+// The public class names are derived exactly like eds sync derives the Tailwind aliases from tokens.json.
+export function publicClassNames(manifest) {
+  const colors = new Set();
+  const typography = new Set();
+  for (const name of Object.keys(manifest.tokens ?? {})) {
+    if (name.startsWith("color-")) {
+      colors.add("eds-" + name.slice("color-".length));
+      continue;
+    }
+    const match = name.match(/^typography-(.+)-(?:fontFamily|fontWeight|fontSize|lineHeight|letterSpacing)$/);
+    if (match) {
+      typography.add(match[1]);
+    }
+  }
+  return { colors, typography };
+}
+
+// files: [{ path, contents }] as readSources() lists them (the generated eds-tokens.css is not among them).
+// unknown: eds-* classes that no public token backs (always a mistake, Tailwind silently drops them).
+// raw: Tailwind palette, white/black and arbitrary color classes that bypass the EDS tokens (informational).
+export function scanClassNames({ consumerRoot, manifest, files }) {
+  const { colors, typography } = publicClassNames(manifest);
+  const unknown = [];
+  const raw = [];
+  for (const file of files) {
+    const relativePath = relativeTo(consumerRoot, file.path);
+    file.contents.split(/\r?\n/).forEach((line, index) => {
+      const location = relativePath + ":" + (index + 1);
+      for (const match of line.matchAll(edsColorClass)) {
+        // "bg-eds-bg-" + name is composed at runtime; the scan cannot judge it.
+        if (match[1].endsWith("-")) {
+          continue;
+        }
+        if (!colors.has("eds-" + match[1])) {
+          unknown.push({ location, className: match[0] });
+        }
+      }
+      for (const match of line.matchAll(edsTypographyClass)) {
+        if (match[1].endsWith("-")) {
+          continue;
+        }
+        if (!typography.has(match[1])) {
+          unknown.push({ location, className: match[0] });
+        }
+      }
+      for (const match of line.matchAll(rawColorClass)) {
+        raw.push({ location, className: match[0] });
+      }
+    });
+  }
+  return { unknown, raw };
+}

package/consumer/sync.mjs

@@ -0,0 +1,155 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  consumerConfigField,
+  findTailwindRoot,
+  findTailwindV3File,
+  planCssRootImports,
+  planLegacyJsImportCleanup,
+  readSources,
+  tailwindRootConfigKey,
+  tailwindRootEnvironmentVariable,
+  tailwindV3Advice,
+} from "./css-root.mjs";
+import { planTailwind } from "./generate-tailwind.mjs";
+import { cliCommand, createExitError, detectPackageManager, generatedCssRelativePath, normalizeEol, readPackageJson, resolvePackage, runnerCommand, toPosix } from "./paths.mjs";
+import { doctorCommand, doctorScriptName, isCompatibleCommand, writeConsumerPackageJson } from "./register-scripts.mjs";
+import { planAgentContext, planClaudeImport, planDeliveryNotes, planGeminiImport } from "./update-agent-context.mjs";
+
+export const syncTargets = new Set(["tailwind", "agents"]);
+const skippedWiring = "skipped " + toPosix(generatedCssRelativePath) + " and the CSS imports.";
+export const noTailwindNote =
+  "No Tailwind root CSS found (no @import \"tailwindcss\"); " + skippedWiring + " Without Tailwind, import @spectrabrain/eds/styles.css " +
+  "in the app entry. To use Tailwind CSS v4, add @import \"tailwindcss\"; to the app's global CSS and run sync again; set " +
+  tailwindRootEnvironmentVariable + "=<file> once only when that file is not detected (sync records it in package.json " +
+  consumerConfigField + "." + tailwindRootConfigKey + ").";
+
+// The line sync and doctor print when there is no Tailwind root: a Tailwind CSS v3 repository gets its own advice.
+export function describeMissingTailwindRoot(plans) {
+  return plans.tailwindV3File === null
+    ? noTailwindNote
+    : "Tailwind CSS v3 detected (@tailwind directives in " + plans.tailwindV3File + "); " + skippedWiring + " " + tailwindV3Advice;
+}
+
+export function collectPlans({ consumerRoot, env = process.env }) {
+  const pkg = resolvePackage(consumerRoot);
+  const packageManager = detectPackageManager(consumerRoot, env);
+  const sources = readSources(consumerRoot);
+  const root = findTailwindRoot(consumerRoot, env, sources, packageManager);
+  // No Tailwind root: the Tailwind wiring is skipped entirely (no generated CSS, no root edits).
+  const tailwind = root === null ? null : planTailwind({ consumerRoot, pkg });
+  const cssRoot = root === null ? null : planCssRootImports({ consumerRoot, root, sources });
+  const legacyImports = root === null ? [] : planLegacyJsImportCleanup({ consumerRoot });
+  const tailwindV3File = root === null ? findTailwindV3File(consumerRoot, sources) : null;
+  const errors = [];
+  let agents = null;
+  try {
+    agents = planAgentContext({ consumerRoot, pkg, packageManager });
+  } catch (error) {
+    errors.push(error);
+  }
+  const claude = planClaudeImport({ consumerRoot });
+  const gemini = planGeminiImport({ consumerRoot });
+  const deliveryNotes = planDeliveryNotes({ consumerRoot, agents, packageManager });
+  return { consumerRoot, pkg, packageManager, sources, root, tailwindV3File, tailwind, cssRoot, legacyImports, agents, claude, gemini, deliveryNotes, errors };
+}
+
+export function planSync({ consumerRoot, env = process.env, only = null }) {
+  if (only !== null && !syncTargets.has(only)) {
+    throw createExitError("Unknown --only target: " + only + " (use tailwind or agents).", 2);
+  }
+  const plans = collectPlans({ consumerRoot, env });
+  if (plans.errors.length > 0) {
+    // Same wording as the doctor line, so the CONSUMER_AGENT.md table applies to both.
+    plans.errors[0].message = "invalid: " + plans.errors[0].message;
+    throw plans.errors[0];
+  }
+
+  const writes = [];
+  if ((only === null || only === "tailwind") && plans.root !== null) {
+    writes.push(plans.tailwind, plans.cssRoot, ...plans.legacyImports);
+  }
+  if (only === null || only === "agents") {
+    writes.push(plans.agents);
+    if (plans.claude) {
+      writes.push(plans.claude);
+    }
+    if (plans.gemini) {
+      writes.push(plans.gemini);
+    }
+  }
+  // Like doctor, an EOL-only difference (an autocrlf checkout of the LF generated CSS) is already synced.
+  return { ...plans, only, writes: writes.filter((write) => normalizeEol(write.before) !== normalizeEol(write.after)) };
+}
+
+// EDS_TAILWIND_ROOT is a one-time choice: sync records it as package.json "eds": { "tailwindRoot" } so
+// doctor and the pretypecheck/prebuild hooks resolve the same root without the environment variable.
+function persistTailwindRoot(plan, { dryRun, log }) {
+  if (plan.root?.source !== "env" || plan.only === "agents") {
+    return false;
+  }
+  const packagePath = path.join(plan.consumerRoot, "package.json");
+  const source = fs.readFileSync(packagePath, "utf8");
+  const consumerPackage = JSON.parse(source);
+  const existing = consumerPackage[consumerConfigField];
+  if (existing !== undefined && (typeof existing !== "object" || existing === null || Array.isArray(existing))) {
+    log("[EDS] package.json \"" + consumerConfigField + "\" is not an object, so " + tailwindRootEnvironmentVariable + " was not recorded. " +
+      "With several Tailwind CSS candidates, doctor and the pretypecheck/prebuild hooks exit 2 again. Check what uses the existing \"" +
+      consumerConfigField + "\" value and move it so \"" + consumerConfigField + "\" can be an object, or set " + tailwindRootEnvironmentVariable + " on every run.");
+    return false;
+  }
+  const value = plan.root.relativePath;
+  const label = consumerConfigField + "." + tailwindRootConfigKey + " = " + JSON.stringify(value);
+  if (existing?.[tailwindRootConfigKey] === value) {
+    return false;
+  }
+  if (dryRun) {
+    log("[EDS] would write " + label + " to package.json");
+    return false;
+  }
+  consumerPackage[consumerConfigField] = { ...(existing ?? {}), [tailwindRootConfigKey]: value };
+  writeConsumerPackageJson(packagePath, source, consumerPackage);
+  log("[EDS] wrote " + label + " to package.json; doctor, sync and the hooks now use this Tailwind root without " + tailwindRootEnvironmentVariable + ".");
+  return true;
+}
+
+export function applySync(plan, { dryRun = false, log = console.log } = {}) {
+  const version = "@spectrabrain/eds@" + plan.pkg.version;
+  if (plan.root === null && plan.only !== "agents") {
+    log("[EDS] " + describeMissingTailwindRoot(plan));
+  } else if (plan.root?.warning) {
+    log("[EDS] " + plan.root.warning);
+  }
+  persistTailwindRoot(plan, { dryRun, log });
+  for (const note of plan.deliveryNotes) {
+    log("[EDS] note: " + note);
+  }
+  if (plan.writes.length === 0) {
+    log("[EDS] Already synced with " + version + ".");
+    return [];
+  }
+  for (const write of plan.writes) {
+    if (dryRun) {
+      log("[EDS] would write " + write.relativePath);
+      continue;
+    }
+    fs.mkdirSync(path.dirname(write.path), { recursive: true });
+    fs.writeFileSync(write.path, write.after);
+    log("[EDS] wrote " + write.relativePath);
+  }
+  if (!dryRun) {
+    // Like doctor's footer: the eds:doctor script only when it runs eds doctor, the CLI otherwise.
+    const scripts = readPackageJson(plan.consumerRoot)?.scripts ?? {};
+    const doctorRun = isCompatibleCommand(scripts[doctorScriptName], doctorCommand)
+      ? runnerCommand(plan.packageManager, doctorScriptName)
+      : cliCommand(plan.packageManager, "doctor");
+    log("[EDS] Synced with " + version + ". Include the files written above in your change, then run " + doctorRun + ".");
+  }
+  return plan.writes.map((write) => write.relativePath);
+}
+
+export function runSync({ consumerRoot, env = process.env, only = null, dryRun = false, log = console.log }) {
+  const plan = planSync({ consumerRoot, env, only });
+  applySync(plan, { dryRun, log });
+  return 0;
+}

package/consumer/update-agent-context.mjs

@@ -0,0 +1,143 @@
+import fs from "node:fs";
+import path from "node:path";
+import { applyBlock, locateBlock, maskFencedBlocks, readBlockVersion, readTemplateBlock, renderBlock } from "./managed-block.mjs";
+import { detectEol, findGitRoot, readTextIfExists, realpathOrNull, relativeTo, toPosix, withEol } from "./paths.mjs";
+
+export const claudeBeginMarker = "<!-- EDS:CLAUDE:BEGIN -->";
+export const claudeEndMarker = "<!-- EDS:CLAUDE:END -->";
+export const claudeImportLine = "@AGENTS.md";
+export const claudeNestedImportLine = "@../AGENTS.md";
+export const geminiBeginMarker = "<!-- EDS:GEMINI:BEGIN -->";
+export const geminiEndMarker = "<!-- EDS:GEMINI:END -->";
+// Gemini CLI documents its import syntax with an explicit relative path.
+export const geminiImportLine = "@./AGENTS.md";
+
+// Claude Code and Gemini CLI accept `@AGENTS.md`, `@./AGENTS.md` and (from .claude/) `@../AGENTS.md` and ignore fenced
+// code blocks.
+const importPattern = /^[ \t]*@(?:\.\.?\/)?AGENTS\.md[ \t]*$/m;
+const endMarkerText = "<!-- EDS:END -->";
+
+export function planAgentContext({ consumerRoot, pkg, packageManager = null }) {
+  const filePath = path.join(consumerRoot, "AGENTS.md");
+  const before = readTextIfExists(filePath);
+  // The block is rendered with the target file's dominant line ending; a new file uses LF.
+  const eol = before === null ? "\n" : detectEol(before);
+  const block = withEol(renderBlock(readTemplateBlock(pkg.packageRoot), pkg.version, packageManager), eol);
+  const located = before === null ? null : locateBlock(before);
+  return {
+    label: "agents",
+    path: filePath,
+    relativePath: relativeTo(consumerRoot, filePath),
+    before,
+    after: applyBlock(before, block, eol),
+    block,
+    existingBlock: located?.block ?? null,
+    existingVersion: located ? readBlockVersion(located.block) : null,
+  };
+}
+
+function hasImport(contents, beginMarker, endMarker) {
+  const visible = maskFencedBlocks(contents);
+  if (visible.includes(beginMarker) && visible.includes(endMarker)) {
+    return true;
+  }
+  return importPattern.test(visible);
+}
+
+// Returns null when the file does not exist, or when it and AGENTS.md are the same file (a symlink in either
+// direction): the managed block already lives in that file and an import would point at itself.
+function planImportFile({ consumerRoot, fileName, label, beginMarker, endMarker, importLine }) {
+  const filePath = path.join(consumerRoot, fileName);
+  const before = readTextIfExists(filePath);
+  if (before === null) {
+    return null;
+  }
+  const realPath = realpathOrNull(filePath);
+  const agentsRealPath = realpathOrNull(path.join(consumerRoot, "AGENTS.md"));
+  if (realPath !== null && realPath === agentsRealPath) {
+    return null;
+  }
+  const eol = detectEol(before);
+  const block = [beginMarker, importLine, endMarker].join(eol);
+  const trimmed = before.replace(/\s*$/, "");
+  const after = hasImport(before, beginMarker, endMarker)
+    ? before
+    : (trimmed ? trimmed + eol + eol + block + eol : block + eol);
+  return { label, path: filePath, relativePath: relativeTo(consumerRoot, filePath), importLine, before, after };
+}
+
+// Claude Code reads CLAUDE.md or .claude/CLAUDE.md instead of AGENTS.md when either exists, so the import goes into
+// whichever the consumer has (CLAUDE.md first). Imports resolve relative to the importing file.
+export function planClaudeImport({ consumerRoot }) {
+  const nested = !fs.existsSync(path.join(consumerRoot, "CLAUDE.md")) && fs.existsSync(path.join(consumerRoot, ".claude", "CLAUDE.md"));
+  return planImportFile({
+    consumerRoot,
+    fileName: nested ? path.join(".claude", "CLAUDE.md") : "CLAUDE.md",
+    label: "claude",
+    beginMarker: claudeBeginMarker,
+    endMarker: claudeEndMarker,
+    importLine: nested ? claudeNestedImportLine : claudeImportLine,
+  });
+}
+
+// Gemini CLI reads GEMINI.md by default and AGENTS.md only with a context.fileName setting, so it gets the same import.
+export function planGeminiImport({ consumerRoot }) {
+  return planImportFile({
+    consumerRoot,
+    fileName: "GEMINI.md",
+    label: "gemini",
+    beginMarker: geminiBeginMarker,
+    endMarker: geminiEndMarker,
+    importLine: geminiImportLine,
+  });
+}
+
+const codexBudgetBytes = 32 * 1024;
+
+// Where the block may not reach an agent even though AGENTS.md is synced. Notes never change an exit code.
+export function planDeliveryNotes({ consumerRoot, agents, packageManager = null }) {
+  const notes = [];
+  if (packageManager?.pnp) {
+    notes.push(
+      "Yarn Plug'n'Play detected: the EDS docs the AGENTS.md block points to are not in node_modules/@spectrabrain/eds, " +
+        "and EDS support for Plug'n'Play is undecided. Ask the repository owner before changing nodeLinker.",
+    );
+  }
+  const exists = (relativePath) => fs.existsSync(path.join(consumerRoot, relativePath));
+  const hasClaude = exists("CLAUDE.md") || exists(path.join(".claude", "CLAUDE.md"));
+  if (!hasClaude && exists("CLAUDE.local.md")) {
+    notes.push("CLAUDE.local.md exists but CLAUDE.md does not, so Claude Code reads CLAUDE.local.md instead of AGENTS.md; add a CLAUDE.md and run sync again (sync adds the import).");
+  } else {
+    // Claude Code is named whenever it has no file. Gemini CLI only rides along then: a repository that set up
+    // CLAUDE.md and no GEMINI.md most likely does not use Gemini, and a note on every run would be noise.
+    const missing = hasClaude ? [] : ["Claude Code (CLAUDE.md)", ...(exists("GEMINI.md") ? [] : ["Gemini CLI (GEMINI.md)"])];
+    if (missing.length > 0) {
+      notes.push(
+        "no instruction file for " + missing.join(" or ") + " here, so " + (missing.length > 1 ? "they" : "it") +
+          " may not load the EDS block in AGENTS.md (Codex reads AGENTS.md). If the team uses " + (missing.length > 1 ? "them" : "it") +
+          ", create that file and run sync again; sync adds the import.",
+      );
+    }
+  }
+  if (exists("AGENTS.override.md")) {
+    notes.push("AGENTS.override.md exists; Codex reads it instead of AGENTS.md, so copy or import the EDS block there.");
+  }
+  const endIndex = agents?.after?.indexOf(endMarkerText) ?? -1;
+  if (endIndex >= 0 && Buffer.byteLength(agents.after.slice(0, endIndex), "utf8") > codexBudgetBytes) {
+    notes.push("the EDS block in AGENTS.md ends after the first 32 KiB, where Codex truncates by default; move the block toward the top (sync keeps it where it is).");
+  }
+  const gitRoot = findGitRoot(consumerRoot);
+  const packageRelative = gitRoot === null ? "" : toPosix(path.relative(gitRoot, consumerRoot));
+  if (packageRelative !== "") {
+    const pointer = packageRelative + "/AGENTS.md";
+    const rootMentions = ["AGENTS.md", "CLAUDE.md"].some((fileName) => (readTextIfExists(path.join(gitRoot, fileName)) ?? "").includes(pointer));
+    if (!rootMentions) {
+      notes.push(
+        "this package is " + packageRelative + " inside the repository; agents started at the repository root do not load " + pointer +
+          " by default. Add to the root AGENTS.md or CLAUDE.md: \"Before working in " + packageRelative + ", read " + pointer +
+          " and run its commands from " + packageRelative + ".\"",
+      );
+    }
+  }
+  return notes;
+}

package/consumer-postinstall.mjs

@@ -0,0 +1,60 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { registerConsumerScripts } from "./consumer/register-scripts.mjs";
+
+const packageRoot = path.dirname(fileURLToPath(import.meta.url));
+const consumerRoot = process.env.INIT_CWD;
+
+if (!consumerRoot || path.resolve(consumerRoot) === packageRoot) {
+  process.exit(0);
+}
+
+const consumerPackagePath = path.join(consumerRoot, "package.json");
+if (!fs.existsSync(consumerPackagePath)) {
+  console.log("[EDS] Consumer package.json was not found; run npx @spectrabrain/eds init in the package that depends on @spectrabrain/eds.");
+  process.exit(0);
+}
+
+function realpathOrNull(filePath) {
+  try {
+    return fs.realpathSync(filePath);
+  } catch {
+    return null;
+  }
+}
+
+const installedPath = realpathOrNull(path.join(consumerRoot, "node_modules", "@spectrabrain", "eds"));
+if (installedPath === null || installedPath !== realpathOrNull(packageRoot)) {
+  console.log("[EDS] Skipping consumer setup: this install is not the consumer's node_modules/@spectrabrain/eds. Run npx @spectrabrain/eds init in the package that depends on @spectrabrain/eds.");
+  process.exit(0);
+}
+
+// pnpm rewrites the consumer package.json after dependency lifecycle scripts, so edits made here are lost.
+if (String(process.env.npm_config_user_agent ?? "").startsWith("pnpm/")) {
+  console.log("[EDS] pnpm discards package.json edits made during install; run pnpm exec eds init to register the EDS scripts.");
+  process.exit(0);
+}
+
+let consumerPackage;
+try {
+  consumerPackage = JSON.parse(fs.readFileSync(consumerPackagePath, "utf8"));
+} catch (error) {
+  console.log("[EDS] Consumer package.json could not be parsed (" + error.message + "); run npx @spectrabrain/eds init after fixing it.");
+  process.exit(0);
+}
+
+// A workspaces root hoists the package but is not the app that uses it: registering the scripts and hooks
+// there would make the root build look for src/styles/eds-tokens.css and AGENTS.md in the wrong place.
+if (consumerPackage.workspaces !== undefined) {
+  console.log("[EDS] Skipping consumer setup: package.json declares workspaces. Run npx @spectrabrain/eds init inside the app package that depends on @spectrabrain/eds.");
+  process.exit(0);
+}
+
+// The install must never fail because of this setup step; anything unexpected is reported and left to eds doctor.
+try {
+  const result = registerConsumerScripts(consumerRoot);
+  console.log("[EDS] Run " + result.syncRunCommand + " to finish setup.");
+} catch (error) {
+  console.log("[EDS] Consumer setup was skipped (" + (error instanceof Error ? error.message : String(error)) + "). Run npx @spectrabrain/eds init to register the EDS scripts.");
+}

package/dist/base.css

@@ -0,0 +1,4 @@
+/* This file is generated by scripts/build-tokens.ts. Do not edit directly. */
+:where(html) {
+  font-family: var(--eds-typography-body1-fontFamily);
+}