@spectrabrain/eds 0.1.0 → 0.1.1

package/consumer/doctor.mjs

@@ -1,17 +1,21 @@
 import { findPretendardReferences, planPackageImports, stylesImportLine, fontsImportLine } from "./css-root.mjs";
 import { readGeneratedVersion } from "./generate-tailwind.mjs";
 import { legacyVersionLabel } from "./managed-block.mjs";
-import { generatedCssRelativePath, normalizeEol, readJson, readPackageJson, runnerCommand, toPosix } from "./paths.mjs";
+import { cliCommand, generatedCssRelativePath, normalizeEol, readJson, readPackageJson, runnerCommand, toPosix } from "./paths.mjs";
 import { doctorCommand, doctorScriptName, isCompatibleCommand, syncCommand, syncScriptName } from "./register-scripts.mjs";
 import { scanClassNames } from "./scan-classes.mjs";
-import { collectPlans, noTailwindNote } from "./sync.mjs";
+import { collectPlans, describeMissingTailwindRoot } from "./sync.mjs";
 
 export const doctorEnvironmentVariable = "EDS_DOCTOR";
 
+// Without a Tailwind root, sync cannot add these imports, so each line says where they go.
 const fontGuidance = {
-  [stylesImportLine]: "missing: @spectrabrain/eds/styles.css import in CSS or JS (or tokens.css + components.css + fonts.css); EDS text styles need the bundled Pretendard font",
-  [fontsImportLine]: "missing: @spectrabrain/eds/fonts.css import next to tokens.css and components.css; EDS text styles reference the font family \"Pretendard\" from fonts.css",
+  [stylesImportLine]: "missing: @spectrabrain/eds/styles.css import (or tokens.css + components.css + fonts.css); add it to the app entry, " +
+    "for example src/main.tsx, because sync cannot add it without a Tailwind root",
+  [fontsImportLine]: "missing: @spectrabrain/eds/fonts.css import next to tokens.css and components.css; add it where they are imported, " +
+    "because EDS text styles use the font family \"Pretendard\" it declares",
 };
+const syncFixablePattern = /^(?:missing|stale|legacy): /;
 
 export function collectFindings({ consumerRoot, env = process.env }) {
   const plans = collectPlans({ consumerRoot, env });
@@ -22,25 +26,35 @@ export function collectFindings({ consumerRoot, env = process.env }) {
   let rawColors = null;
 
   const scripts = readPackageJson(consumerRoot)?.scripts ?? {};
+  const unregistered = [];
   for (const [name, command] of [[syncScriptName, syncCommand], [doctorScriptName, doctorCommand]]) {
     if (isCompatibleCommand(scripts[name], command)) {
       continue;
     }
+    if (scripts[name] === undefined) {
+      unregistered.push(name);
+      continue;
+    }
     findings.push(
-      scripts[name] === undefined
-        ? "scripts: " + name + " is not registered; run npx @spectrabrain/eds init"
-        : "scripts: " + name + " runs " + JSON.stringify(scripts[name]) + " instead of \"" + command +
-          "\"; rename that script and run npx @spectrabrain/eds init, or make it run \"" + command + "\"",
+      "scripts: " + name + " runs " + JSON.stringify(scripts[name]) + " instead of \"" + command +
+        "\"; rename that script and run " + cliCommand(plans.packageManager, "init") + ", or make it run \"" + command + "\"",
     );
   }
-  // The fix line may only point at sync:eds when that script really runs eds sync.
+  if (unregistered.length > 0) {
+    findings.unshift("scripts: " + unregistered.join(", ") + (unregistered.length === 1 ? " is" : " are") + " not registered; run " +
+      cliCommand(plans.packageManager, "init"));
+  }
+  // The fix lines may only point at sync:eds and eds:doctor when those scripts really run the EDS commands.
   const syncRegistered = isCompatibleCommand(scripts[syncScriptName], syncCommand);
+  const doctorRegistered = isCompatibleCommand(scripts[doctorScriptName], doctorCommand);
+  const nonSyncFindings = new Set();
 
   if (plans.root === null) {
-    notes.push(noTailwindNote);
+    notes.push(describeMissingTailwindRoot(plans));
     // Without a Tailwind root, sync cannot insert the imports, so doctor states the requirement directly.
     for (const line of planPackageImports(plans.sources)) {
       findings.push(fontGuidance[line]);
+      nonSyncFindings.add(fontGuidance[line]);
     }
   } else {
     if (plans.tailwind.before === null) {
@@ -72,13 +86,15 @@ export function collectFindings({ consumerRoot, env = process.env }) {
       files: [...plans.sources.scripts, ...plans.sources.css, ...plans.sources.html],
     });
     for (const hit of classScan.unknown) {
-      findings.push("unknown: " + hit.location + " " + hit.className + " is not a public EDS class; check tokens.json or " + generatedRelativePath);
+      findings.push("unknown: " + hit.location + " " + hit.className + " is not a public EDS class; use a class from " + generatedRelativePath);
     }
     rawColors = classScan.raw;
   }
 
+  notes.push(...plans.deliveryNotes);
   for (const filePath of findPretendardReferences(consumerRoot, plans.sources)) {
-    notes.push(filePath + " references Pretendard outside @spectrabrain/eds; EDS text styles use the bundled font, so the extra font source can be removed.");
+    notes.push(filePath + " references Pretendard outside @spectrabrain/eds. EDS text styles use the font from @spectrabrain/eds/fonts.css, " +
+      "so this does not affect EDS; keep it unless the user asks to remove it, because other styles may use it.");
   }
 
   for (const error of plans.errors) {
@@ -98,13 +114,13 @@ export function collectFindings({ consumerRoot, env = process.env }) {
   }
 
   if (plans.claude && normalizeEol(plans.claude.before) !== normalizeEol(plans.claude.after)) {
-    findings.push("missing: @AGENTS.md import in CLAUDE.md");
+    findings.push("missing: " + plans.claude.importLine + " import in " + plans.claude.relativePath);
   }
   if (plans.gemini && normalizeEol(plans.gemini.before) !== normalizeEol(plans.gemini.after)) {
-    findings.push("missing: @./AGENTS.md import in GEMINI.md");
+    findings.push("missing: " + plans.gemini.importLine + " import in " + plans.gemini.relativePath);
   }
 
-  return { plans, findings, notes, installed, generatedRelativePath, syncRegistered, rawColors };
+  return { plans, findings, notes, installed, generatedRelativePath, syncRegistered, doctorRegistered, nonSyncFindings, unregistered, rawColors };
 }
 
 const rawColorLineLimit = 40;
@@ -168,11 +184,21 @@ export function runDoctor({ consumerRoot, env = process.env, warn = false, scan
   for (const finding of result.findings) {
     log("[EDS] " + finding);
   }
-  const fixCommand = result.syncRegistered ? runnerCommand(result.plans.packageManager, syncScriptName) : "npx eds sync";
-  log(
-    "[EDS] Run " + fixCommand + " to fix. (" +
-      doctorEnvironmentVariable + "=warn or eds doctor --warn downgrades this to a warning.)",
-  );
-  log("[EDS] Then read the AGENTS.md managed block and QUICKSTART.md in the package root before UI work.");
+  // One next command: init when scripts are missing (it also syncs), otherwise sync when it can fix a line.
+  // unknown:, invalid:, scripts: conflicts and the imports sync cannot add carry their own fix on the line.
+  const packageManager = result.plans.packageManager;
+  const syncFixable = result.findings.some((finding) => syncFixablePattern.test(finding) && !result.nonSyncFindings.has(finding));
+  if (result.unregistered.length > 0) {
+    log("[EDS] Run " + cliCommand(packageManager, "init") + " to register the scripts; it also runs sync.");
+  } else if (syncFixable) {
+    const syncRun = result.syncRegistered ? runnerCommand(packageManager, syncScriptName) : cliCommand(packageManager, "sync");
+    log("[EDS] Run " + syncRun + " to fix the missing:, stale: and legacy: lines.");
+  }
+  if (downgrade) {
+    log("[EDS] Warn mode: the lines above are not fixed, so this exit 0 does not mean the check passed.");
+  }
+  const doctorRun = result.doctorRegistered ? runnerCommand(packageManager, doctorScriptName) : cliCommand(packageManager, "doctor");
+  // The completion line itself starts with "[EDS] synced with"; this line must not contain that text.
+  log("[EDS] Then rerun " + doctorRun + " until it reports synced; the QUICKSTART.md completion criteria in the package root list the order.");
   return downgrade ? 0 : 1;
 }

package/consumer/init.mjs

@@ -1,31 +1,34 @@
 import fs from "node:fs";
 import path from "node:path";
-import { createExitError, detectPackageManager, packageName, resolvePackage, runnerCommand } from "./paths.mjs";
+import { cliCommand, createExitError, detectPackageManager, installCommand, packageName, readPackageJson, resolvePackage, runnerCommand } from "./paths.mjs";
 import { registerConsumerScripts, syncScriptName, writeConsumerPackageJson } from "./register-scripts.mjs";
 import { runSync } from "./sync.mjs";
 
 export const ciTargets = new Set(["github", "gitlab"]);
 const allowScriptsField = "allowScripts";
 const minimumAllowScriptsNpmMajor = 12;
+// --no-allow-scripts-pin keeps the approval valid after EDS upgrades, like the name-only entry init writes.
+const approveCommand = "npm install-scripts approve --no-allow-scripts-pin " + packageName;
 
-const installCommands = {
+const ciInstallCommands = {
   npm: "npm ci",
   pnpm: "pnpm install --frozen-lockfile",
   yarn: "yarn install --frozen-lockfile",
   bun: "bun install --frozen-lockfile",
 };
 
-function installCommand(packageManager) {
+function ciInstallCommand(packageManager) {
   if (packageManager.name === "yarn" && packageManager.berry) {
     return "yarn install --immutable";
   }
-  return installCommands[packageManager.name];
+  return ciInstallCommands[packageManager.name];
 }
 
-// A CI job that fails when sync is out of date. It runs `npx eds doctor` so the consumer's own
-// package.json scripts are not required.
+// A CI job that fails when sync is out of date. It runs the EDS CLI directly with the repository's package
+// manager, so the consumer's own package.json scripts are not required.
 export function renderCiSnippet(target, packageManager) {
-  const install = installCommand(packageManager);
+  const install = ciInstallCommand(packageManager);
+  const doctor = cliCommand(packageManager, "doctor");
   if (target === "github") {
     const setup = packageManager.name === "pnpm"
       ? ["      - uses: pnpm/action-setup@v4"]
@@ -48,7 +51,7 @@ export function renderCiSnippet(target, packageManager) {
       "          node-version: 22",
       ...cache,
       "      - run: " + install,
-      "      - run: npx eds doctor",
+      "      - run: " + doctor,
       "",
     ].join("\n");
   }
@@ -66,7 +69,7 @@ export function renderCiSnippet(target, packageManager) {
       "  script:",
       ...before,
       "    - " + install,
-      "    - npx eds doctor",
+      "    - " + doctor,
       "",
     ].join("\n");
   }
@@ -81,7 +84,7 @@ function writeAllowScripts(consumerRoot, { log, dryRun }) {
   const consumerPackage = JSON.parse(source);
   const existing = consumerPackage[allowScriptsField];
   if (existing !== undefined && typeof existing !== "object") {
-    log("[EDS] package.json " + allowScriptsField + " is not an object; approve the postinstall manually with npm install-scripts approve --no-allow-scripts-pin " + packageName + ".");
+    log("[EDS] package.json " + allowScriptsField + " is not an object; left unchanged. To approve the EDS postinstall, run " + approveCommand + ".");
     return false;
   }
   const current = existing?.[packageName];
@@ -106,29 +109,29 @@ function printInstallScriptGuidance(consumerRoot, packageManager, { log, dryRun,
       if (allowScripts) {
         writeAllowScripts(consumerRoot, { log, dryRun });
       } else {
-        log("[EDS] --no-allow-scripts: not writing " + allowScriptsField + "; later installs skip the EDS postinstall until you run npm install-scripts approve " + packageName + ".");
+        log("[EDS] --no-allow-scripts: not writing " + allowScriptsField + ". Later installs skip the EDS postinstall until someone runs " + approveCommand + ".");
       }
     } else if (major === null) {
-      log("[EDS] npm " + minimumAllowScriptsNpmMajor + "+ blocks dependency install scripts by default; run npm install-scripts approve --no-allow-scripts-pin " + packageName + " there, or rerun init with npm so it can write " + allowScriptsField + ".");
+      log("[EDS] The npm version is unknown because init did not run through npm. If this project uses npm " + minimumAllowScriptsNpmMajor +
+        "+, run " + approveCommand + ", or rerun " + cliCommand(packageManager, "init") + " so init can write " + allowScriptsField + ".");
     }
     return;
   }
+  // The postinstall only re-registers the scripts init has just written, so approving it is optional everywhere
+  // except npm 12+, where init records the approval itself.
   if (name === "pnpm") {
-    log("[EDS] pnpm blocks dependency build scripts by default. Run pnpm approve-builds and select " + packageName + ", or add to package.json:");
-    log("  \"pnpm\": { \"onlyBuiltDependencies\": [\"" + packageName + "\"] }");
-    log("[EDS] Without it, rerun " + runnerCommand(packageManager, syncScriptName) + " (or npx eds init) after each install.");
+    log("[EDS] pnpm: the scripts are registered, so the EDS postinstall needs no build approval. After upgrading EDS, run " +
+      runnerCommand(packageManager, syncScriptName) + ".");
     return;
   }
   if (name === "bun") {
-    log("[EDS] bun runs dependency lifecycle scripts only for trustedDependencies. Add to package.json:");
-    log("  \"trustedDependencies\": [\"" + packageName + "\"]");
-    log("[EDS] Note: setting trustedDependencies replaces bun's default trusted list; include any other package whose install scripts you rely on.");
+    log("[EDS] Optional (bun): to let the EDS postinstall re-register the scripts on later installs, add \"trustedDependencies\": [\"" +
+      packageName + "\"] to package.json. It replaces bun's default trusted list, so this is the project owner's decision.");
     return;
   }
   if (name === "yarn" && berry) {
-    log("[EDS] Yarn 2+ skips dependency install scripts when enableScripts is false. To run the EDS postinstall, keep enableScripts: true in .yarnrc.yml, or add to package.json:");
-    log("  \"dependenciesMeta\": { \"" + packageName + "\": { \"built\": true } }");
-    log("[EDS] Otherwise rerun " + runnerCommand(packageManager, syncScriptName) + " (or npx eds init) after each install.");
+    log("[EDS] Optional (Yarn 2+): to let the EDS postinstall re-register the scripts on later installs, keep enableScripts: true in .yarnrc.yml " +
+      "or add \"dependenciesMeta\": { \"" + packageName + "\": { \"built\": true } } to package.json.");
   }
 }
 
@@ -152,20 +155,31 @@ export function runInit({
 
   if (!fs.existsSync(path.join(consumerRoot, "package.json"))) {
     throw createExitError(
-      "No package.json in " + consumerRoot + "; run npx " + packageName + " init from the consumer root.",
+      "No package.json in " + consumerRoot + "; run init in the package that depends on " + packageName + ".",
       1,
     );
   }
+  // A workspace root or a parent folder can resolve a hoisted EDS; the scripts, hooks and AGENTS.md belong to the
+  // app package that declares it.
+  const consumerPackage = readPackageJson(consumerRoot);
+  const declared = ["dependencies", "devDependencies", "optionalDependencies"].some((field) => consumerPackage?.[field]?.[packageName] !== undefined);
+  if (!declared) {
+    throw createExitError(
+      "package.json in " + consumerRoot + " does not declare " + packageName + ". Run init in the app package that uses EDS, after " +
+        installCommand(packageManager) + " there.",
+      2,
+    );
+  }
   try {
     resolvePackage(consumerRoot);
   } catch {
-    throw createExitError(packageName + " is not installed here; run npm install " + packageName + " first.", 1);
+    throw createExitError(packageName + " is declared but not installed; run " + installCommand(packageManager) + " first.", 1);
   }
 
-  registerConsumerScripts(consumerRoot, { log, dryRun, packageManager });
+  const registered = registerConsumerScripts(consumerRoot, { log, dryRun, packageManager });
   printInstallScriptGuidance(consumerRoot, packageManager, { log, dryRun, allowScripts });
   if (noSync) {
-    log("[EDS] Scripts registered. Run " + runnerCommand(packageManager, syncScriptName) + " to finish setup.");
+    log("[EDS] Run " + registered.syncRunCommand + " to finish setup.");
     return 0;
   }
   return runSync({ consumerRoot, env, dryRun, log });

package/consumer/managed-block.mjs

@@ -81,16 +81,22 @@ function lineNumberAt(text, index) {
   return text.slice(0, index).split(/\r?\n/).length;
 }
 
+const markerFix = "Keep one " + beginMarker + " line with the " + endMarker + " line after it, delete the other marker lines, " +
+  "then run sync again (sync rewrites what is between them).";
+
+function describeLines(text, positions) {
+  const lines = positions.map((position) => lineNumberAt(text, position));
+  return lines.length === 0 ? "none" : (lines.length === 1 ? "line " : "lines ") + lines.join(", ");
+}
+
 export function locateBlock(existing) {
   const masked = maskFencedBlocks(existing);
   const begins = findAll(masked, beginMarker);
   const ends = findAll(masked, endMarker);
   if (begins.length !== ends.length || begins.length > 1) {
-    const first = begins[0] ?? ends[0];
     throw new Error(
-      "AGENTS.md must contain zero or one complete EDS managed block. Found " + begins.length + " " + beginMarker +
-        " and " + ends.length + " " + endMarker + " marker" + (begins.length + ends.length === 1 ? "" : "s") +
-        " outside fenced code blocks" + (first === undefined ? "" : ", first at line " + lineNumberAt(existing, first)) + ".",
+      "AGENTS.md must contain zero or one complete EDS managed block. Outside fenced code blocks it has " + beginMarker + " at " +
+        describeLines(existing, begins) + " and " + endMarker + " at " + describeLines(existing, ends) + ". " + markerFix,
     );
   }
   if (begins.length === 0) {
@@ -102,7 +108,7 @@ export function locateBlock(existing) {
   if (endIndex < start) {
     throw new Error(
       "AGENTS.md has an invalid EDS managed block: " + endMarker + " at line " + lineNumberAt(existing, endIndex) +
-        " comes before " + beginMarker + " at line " + lineNumberAt(existing, start) + ".",
+        " comes before " + beginMarker + " at line " + lineNumberAt(existing, start) + ". " + markerFix,
     );
   }
   const end = endIndex + endMarker.length;

package/consumer/paths.mjs

@@ -28,7 +28,7 @@ export function resolvePackage(consumerRoot) {
   try {
     packageJsonPath = require.resolve(packageName + "/package.json");
   } catch {
-    throw createExitError(packageName + " is not installed here (run npm install).", 2);
+    throw createExitError(packageName + " is not installed here; install it in this package first.", 2);
   }
 
   const packageRoot = path.dirname(packageJsonPath);
@@ -175,25 +175,62 @@ function isYarnBerry(consumerRoot, major) {
   return lockfile !== null && /^__metadata:/m.test(lockfile);
 }
 
-export function detectPackageManager(consumerRoot, env = process.env) {
-  const fromAgent = parseUserAgent(env.npm_config_user_agent);
-  let name = fromAgent?.name ?? null;
-  let source = fromAgent ? "user-agent" : "lockfile";
-  if (name === null) {
-    name = lockfileManagers.find(([fileName]) => fs.existsSync(path.join(consumerRoot, fileName)))?.[1] ?? null;
+// The directory that holds .git at or above startDirectory, or null outside git.
+export function findGitRoot(startDirectory) {
+  for (let directory = path.resolve(startDirectory); ; ) {
+    if (fs.existsSync(path.join(directory, ".git"))) {
+      return directory;
+    }
+    const parent = path.dirname(directory);
+    if (parent === directory) {
+      return null;
+    }
+    directory = parent;
+  }
+}
+
+// The nearest lockfile names the package manager: this directory, then its parents up to the git root, so a
+// workspace package resolves to the repository lockfile. Outside git only this directory counts, so a stray
+// lockfile in a parent folder is never picked up.
+export function findLockfile(startDirectory) {
+  const start = path.resolve(startDirectory);
+  const directories = [start];
+  for (let directory = start; !fs.existsSync(path.join(directory, ".git")); ) {
+    const parent = path.dirname(directory);
+    if (parent === directory) {
+      directories.length = 1;
+      break;
+    }
+    directories.push(parent);
+    directory = parent;
   }
-  if (name === null) {
-    name = "npm";
-    source = "default";
+  for (const directory of directories) {
+    const found = lockfileManagers.find(([fileName]) => fs.existsSync(path.join(directory, fileName)));
+    if (found) {
+      return { directory, fileName: found[0], name: found[1] };
+    }
   }
-  const major = fromAgent?.major ?? null;
+  return null;
+}
+
+// The lockfile decides; the runner in npm_config_user_agent (npm, npx, pnpm, yarn, bun) decides only without a
+// lockfile. `npx @spectrabrain/eds init` in a pnpm repository therefore still renders pnpm commands. The runner's
+// version is kept only when the runner is that same manager (npm 12+ allowScripts, Yarn 2+).
+export function detectPackageManager(consumerRoot, env = process.env) {
+  const fromAgent = parseUserAgent(env.npm_config_user_agent);
+  const lockfile = findLockfile(consumerRoot);
+  const name = lockfile?.name ?? fromAgent?.name ?? "npm";
+  const agent = fromAgent?.name === name ? fromAgent : null;
+  const major = agent?.major ?? null;
   return {
     name,
-    version: fromAgent?.version ?? null,
+    version: agent?.version ?? null,
     major,
-    berry: name === "yarn" && isYarnBerry(consumerRoot, major),
+    berry: name === "yarn" && isYarnBerry(lockfile?.directory ?? consumerRoot, major),
+    // Yarn Plug'n'Play writes .pnp.cjs (.pnp.js before Yarn 3) next to yarn.lock and installs no node_modules.
+    pnp: name === "yarn" && [".pnp.cjs", ".pnp.js"].some((fileName) => fs.existsSync(path.join(lockfile?.directory ?? consumerRoot, fileName))),
     runner: runnerPrefixes[name],
-    source,
+    source: lockfile ? "lockfile" : fromAgent ? "user-agent" : "default",
   };
 }
 
@@ -201,6 +238,24 @@ export function runnerCommand(packageManager, scriptName) {
   return (packageManager?.runner ?? runnerPrefixes.npm) + scriptName;
 }
 
+// npx and bunx fall back to the registry when no local bin exists, and the unscoped registry name "eds" is an
+// unrelated package, so they always name @spectrabrain/eds. pnpm exec and yarn run only the local bin.
+const cliPrefixes = {
+  npm: "npx " + packageName,
+  pnpm: "pnpm exec eds",
+  yarn: "yarn eds",
+  bun: "bunx " + packageName,
+};
+const addPrefixes = { npm: "npm install", pnpm: "pnpm add", yarn: "yarn add", bun: "bun add" };
+
+export function cliCommand(packageManager, args) {
+  return (cliPrefixes[packageManager?.name] ?? cliPrefixes.npm) + " " + args;
+}
+
+export function installCommand(packageManager, names = [packageName]) {
+  return (addPrefixes[packageManager?.name] ?? addPrefixes.npm) + " " + names.join(" ");
+}
+
 export function renderRunnerCommands(text, packageManager) {
   const runner = packageManager?.runner ?? runnerPrefixes.npm;
   return runner === runnerPrefixes.npm ? text : text.replace(/\bnpm run /g, runner);

package/consumer/register-scripts.mjs

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { detectIndent, detectPackageManager, runnerCommand } from "./paths.mjs";
+import { cliCommand, detectIndent, detectPackageManager, runnerCommand } from "./paths.mjs";
 
 export const syncCommand = "eds sync";
 export const doctorCommand = "eds doctor";
@@ -48,7 +48,7 @@ export function registerConsumerScripts(
   const source = fs.readFileSync(packagePath, "utf8");
   const consumerPackage = JSON.parse(source);
   const scripts = { ...(consumerPackage.scripts ?? {}) };
-  const result = { changed: false, added: [], migrated: [], removed: [], skippedHooks: [], conflicts: [] };
+  const result = { changed: false, added: [], migrated: [], removed: [], skippedHooks: [], conflicts: [], syncRunCommand: null };
 
   for (const [name, command] of Object.entries(requiredScripts)) {
     if (isCompatibleCommand(scripts[name], command)) {
@@ -67,8 +67,8 @@ export function registerConsumerScripts(
     // Never fail the install over a consumer-owned script: leave it alone and let doctor report it.
     result.conflicts.push(name);
     log(
-      `[EVA Design System] Consumer script ${name} already exists with a different command (${JSON.stringify(scripts[name])}); ` +
-        `left unchanged. eds doctor reports it until the script runs "${command}".`,
+      `[EDS] package.json script ${name} runs ${JSON.stringify(scripts[name])}; left unchanged. ` +
+        `eds doctor reports it until the script runs "${command}".`,
     );
   }
 
@@ -94,28 +94,33 @@ export function registerConsumerScripts(
       continue;
     }
     result.skippedHooks.push(hook.name);
-    log(`[EVA Design System] ${hook.name} is already defined; add "${doctorCommand}" to it manually.`);
+    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.
-  const syncRunCommand = result.conflicts.includes(syncScriptName) ? "npx eds sync" : runnerCommand(packageManager, syncScriptName);
+  // 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("[EVA Design System] would update package.json scripts: " + [...result.added, ...result.migrated, ...result.removed].join(", "));
+    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("[EVA Design System] Added consumer setup scripts. Run " + syncRunCommand + ".");
+    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("[EVA Design System] Consumer setup scripts are already registered. Run " + syncRunCommand + ".");
+    log("[EDS] The EDS scripts are already registered.");
   } else {
-    log("[EVA Design System] Consumer setup scripts were left unchanged. Run " + syncRunCommand + ".");
+    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(
-      "[EVA Design System] Yarn 2+ does not run pretypecheck/prebuild hooks. Prepend \"" + doctorCommand +
+      "[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).",
     );

package/consumer/scan-classes.mjs

@@ -1,14 +1,15 @@
 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.
+// 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-z0-9-]+)" + opacity + boundaryAfter, "g");
-const edsTypographyClass = new RegExp(boundaryBefore + variantPrefix + "eds-typography-([a-z0-9-]+)" + boundaryAfter, "g");
+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\\()[^\\]]*\\])" +

package/consumer/sync.mjs

@@ -3,22 +3,33 @@ 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 { createExitError, detectPackageManager, generatedCssRelativePath, normalizeEol, resolvePackage, toPosix } from "./paths.mjs";
-import { writeConsumerPackageJson } from "./register-scripts.mjs";
-import { planAgentContext, planClaudeImport, planGeminiImport } from "./update-agent-context.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\"); skipped " + toPosix(generatedCssRelativePath) +
-  " and the CSS imports. Set " + tailwindRootEnvironmentVariable + "=<file> once to wire Tailwind; sync records it in package.json " +
-  consumerConfigField + "." + tailwindRootConfigKey + ".";
+  "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);
@@ -29,6 +40,7 @@ export function collectPlans({ consumerRoot, env = process.env }) {
   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 {
@@ -38,7 +50,8 @@ export function collectPlans({ consumerRoot, env = process.env }) {
   }
   const claude = planClaudeImport({ consumerRoot });
   const gemini = planGeminiImport({ consumerRoot });
-  return { consumerRoot, pkg, packageManager, sources, root, tailwind, cssRoot, legacyImports, agents, claude, gemini, errors };
+  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 }) {
@@ -47,6 +60,8 @@ export function planSync({ consumerRoot, env = process.env, only = null }) {
   }
   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];
   }
 
@@ -78,7 +93,9 @@ function persistTailwindRoot(plan, { dryRun, log }) {
   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; " + tailwindRootEnvironmentVariable + " was not recorded there.");
+    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;
@@ -99,11 +116,14 @@ function persistTailwindRoot(plan, { dryRun, log }) {
 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] " + noTailwindNote);
+    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 [];
@@ -118,10 +138,12 @@ export function applySync(plan, { dryRun = false, log = console.log } = {}) {
     log("[EDS] wrote " + write.relativePath);
   }
   if (!dryRun) {
-    log(
-      "[EDS] Synced with " + version + ". Review the diff (AGENTS.md, CSS imports, " + toPosix(generatedCssRelativePath) +
-        ") before committing; the AGENTS.md block lists the rules.",
-    );
+    // 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);
 }