@spectrabrain/eds 0.3.1 → 0.6.0

package/consumer/css-root.mjs

@@ -149,7 +149,7 @@ export function findTailwindRoot(
       "Could not identify one Tailwind root CSS file (found " + found.length + ": " + found.join(", ") + "). " +
         "Ask the user which of these is the app's Tailwind root, then run " + tailwindRootEnvironmentVariable + "=<that file> " +
         runnerCommand(packageManager, "sync:eds") + " once. sync records the choice in package.json as \"" + consumerConfigField +
-        "\": { \"" + tailwindRootConfigKey + "\": \"<that file>\" } so doctor and the hooks reuse it.",
+        "\": { \"" + tailwindRootConfigKey + "\": \"<that file>\" } so doctor and sync reuse it.",
       2,
     );
   }

package/consumer/generate-tailwind.mjs

@@ -11,10 +11,6 @@ const propertyNames = [
 
 export const fontSansStyleName = "body1";
 
-function safeTailwindAlias(name) {
-  return "eds-" + name.replace(/\./g, "-");
-}
-
 function cssVariableForToken(manifest, name) {
   const cssVariable = manifest.tokens?.[name]?.$extensions?.eds?.cssVariable;
   if (typeof cssVariable === "string") {
@@ -24,27 +20,9 @@ function cssVariableForToken(manifest, name) {
   return "--eds-" + name.replace(/\./g, "\\.");
 }
 
-function collectDimensionAliases(manifest, prefix) {
-  const aliases = new Map();
-
-  for (const name of Object.keys(manifest.tokens ?? {}).filter((entry) => entry.startsWith(prefix))) {
-    const alias = safeTailwindAlias(name);
-    const existing = aliases.get(alias);
-    if (existing !== undefined && existing !== name) {
-      throw new Error(`Tailwind alias collision: ${existing} and ${name} both map to ${alias}.`);
-    }
-
-    aliases.set(alias, name);
-  }
-
-  return [...aliases.entries()].sort(([left], [right]) => left.localeCompare(right));
-}
-
 export function renderTailwindCss(manifest, version) {
   const tokens = Object.keys(manifest.tokens ?? {});
   const colorNames = tokens.filter((name) => name.startsWith("color-"));
-  const spacingAliases = collectDimensionAliases(manifest, "spacing-");
-  const radiusAliases = collectDimensionAliases(manifest, "radius-");
   const typography = new Map();
 
   for (const name of tokens.filter((entry) => entry.startsWith("typography-"))) {
@@ -74,12 +52,6 @@ export function renderTailwindCss(manifest, version) {
   const colorAliases = colorNames
     .map((name) => `  --color-eds-${name.slice("color-".length)}: var(${cssVariableForToken(manifest, name)});`)
     .join("\n");
-  const spacingThemeAliases = spacingAliases
-    .map(([alias, name]) => `  --spacing-${alias}: var(${cssVariableForToken(manifest, name)});`)
-    .join("\n");
-  const radiusThemeAliases = radiusAliases
-    .map(([alias, name]) => `  --radius-${alias}: var(${cssVariableForToken(manifest, name)});`)
-    .join("\n");
   // Last line of the @theme block: Tailwind's default font family becomes the EDS body font.
   const fontSans = `  --font-sans: var(--eds-typography-${fontSansStyleName}-fontFamily);`;
   const typographyUtilities = [...typography.keys()].sort().map((styleName) => [
@@ -96,8 +68,6 @@ export function renderTailwindCss(manifest, version) {
     `/* Generated from @spectrabrain/eds@${version}. Do not edit manually. */`,
     "@theme inline {",
     colorAliases,
-    spacingThemeAliases,
-    radiusThemeAliases,
     fontSans,
     "}",
     "",

package/consumer/init.mjs

@@ -77,7 +77,7 @@ export function renderCiSnippet(target, packageManager) {
 }
 
 // npm 12+ blocks dependency install scripts unless package.json allows them. A name-only entry keeps
-// the EDS postinstall running on later installs and upgrades without re-approval.
+// the EDS postinstall available for script maintenance and first-sync bootstrap.
 function writeAllowScripts(consumerRoot, { log, dryRun }) {
   const packagePath = path.join(consumerRoot, "package.json");
   const source = fs.readFileSync(packagePath, "utf8");
@@ -98,7 +98,7 @@ function writeAllowScripts(consumerRoot, { log, dryRun }) {
   }
   consumerPackage[allowScriptsField] = { ...(existing ?? {}), [packageName]: true };
   writeConsumerPackageJson(packagePath, source, consumerPackage);
-  log("[EDS] wrote " + allowScriptsField + "[\"" + packageName + "\"] = true to package.json so npm " + minimumAllowScriptsNpmMajor + "+ runs the EDS postinstall on later installs.");
+  log("[EDS] wrote " + allowScriptsField + "[\"" + packageName + "\"] = true to package.json so npm " + minimumAllowScriptsNpmMajor + "+ can run the EDS postinstall on later installs.");
   return true;
 }
 
@@ -113,24 +113,23 @@ function printInstallScriptGuidance(consumerRoot, packageManager, { log, dryRun,
       }
     } else if (major === null) {
       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 + ".");
+        "+, run " + approveCommand + ", or rerun " + cliCommand(packageManager, "init") + " so init can enable the EDS postinstall.");
     }
     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.
+  // Install hooks are optional in package managers that require dependency build approval.
   if (name === "pnpm") {
-    log("[EDS] pnpm: the scripts are registered, so the EDS postinstall needs no build approval. After upgrading EDS, run " +
-      runnerCommand(packageManager, syncScriptName) + ".");
+    log("[EDS] pnpm: postinstall can sync EDS files but does not persist package.json script edits. The coding agent registers them with " +
+      cliCommand(packageManager, "sync") + " at the start of its next UI task.");
     return;
   }
   if (name === "bun") {
-    log("[EDS] Optional (bun): to let the EDS postinstall re-register the scripts on later installs, add \"trustedDependencies\": [\"" +
+    log("[EDS] Optional (bun): to let the EDS postinstall bootstrap files and maintain scripts, 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] Optional (Yarn 2+): to let the EDS postinstall re-register the scripts on later installs, keep enableScripts: true in .yarnrc.yml " +
+    log("[EDS] Optional (Yarn 2+): to let the EDS postinstall bootstrap files and maintain scripts, keep enableScripts: true in .yarnrc.yml " +
       "or add \"dependenciesMeta\": { \"" + packageName + "\": { \"built\": true } } to package.json.");
   }
 }
@@ -159,7 +158,7 @@ export function runInit({
       1,
     );
   }
-  // A workspace root or a parent folder can resolve a hoisted EDS; the scripts, hooks and AGENTS.md belong to the
+  // A workspace root or a parent folder can resolve a hoisted EDS; the scripts 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);
@@ -182,5 +181,5 @@ export function runInit({
     log("[EDS] Run " + registered.syncRunCommand + " to finish setup.");
     return 0;
   }
-  return runSync({ consumerRoot, env, dryRun, log });
+  return runSync({ consumerRoot, env, dryRun, ensureScripts: false, log });
 }

package/consumer/managed-block.mjs

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { renderRunnerCommands } from "./paths.mjs";
+import { renderRunnerCommands, runnerCommand } from "./paths.mjs";
 
 export const beginMarker = "<!-- EDS:BEGIN -->";
 export const endMarker = "<!-- EDS:END -->";
@@ -21,13 +21,19 @@ export function readTemplateBlock(packageRoot) {
 
 // The template is written for npm; the rendered block uses the consumer's package-manager runner
 // (pnpm, yarn, bun run) so the commands an agent reads work in that repository.
-export function renderBlock(template, version, packageManager = null) {
+export function renderBlock(template, version, packageManager = null, commands = null) {
   const versionLine = "<!-- EDS:VERSION " + version + " -->";
   const withoutVersion = template.replace(/^<!-- EDS:VERSION \S+ -->\r?\n/m, "");
   if (!withoutVersion.startsWith(beginMarker)) {
     throw new Error("CONSUMER_AGENT.md managed block must start with " + beginMarker + ".");
   }
-  const body = renderRunnerCommands(withoutVersion.slice(beginMarker.length), packageManager);
+  let body = renderRunnerCommands(withoutVersion.slice(beginMarker.length), packageManager);
+  if (commands?.sync) {
+    body = body.replaceAll(runnerCommand(packageManager, "sync:eds"), commands.sync);
+  }
+  if (commands?.doctor) {
+    body = body.replaceAll(runnerCommand(packageManager, "eds:doctor"), commands.doctor);
+  }
   return beginMarker + "\n" + versionLine + body;
 }
 

package/consumer/register-scripts.mjs

@@ -20,10 +20,9 @@ const legacyScripts = {
   "update:eds-agent-context": [legacyRunnerCommand],
   "generate:eds-tailwind": [legacyRunnerCommand],
 };
-const hookScripts = [
-  { name: "pretypecheck", target: "typecheck" },
-  { name: "prebuild", target: "build" },
-];
+const obsoleteDoctorHooks = new Set(["pretypecheck", "prebuild"]);
+const doctorPrefix = doctorCommand + " && ";
+const doctorLifecycleScripts = ["pretypecheck", "prebuild", "typecheck", "build"];
 
 export function writeConsumerPackageJson(packagePath, source, consumerPackage) {
   const trailingNewline = source.endsWith("\n") ? "\n" : "";
@@ -40,15 +39,22 @@ export function isCompatibleCommand(value, command) {
   return new RegExp("(^|[\\s&|;(])" + escaped + "($|[\\s&|;)])").test(value);
 }
 
+export function canUseConsumerScript(scripts, name, command, { willRegister = false } = {}) {
+  if (isCompatibleCommand(scripts[name], command)) {
+    return true;
+  }
+  return willRegister && (scripts[name] === undefined || legacyScripts[name]?.includes(scripts[name]) === true);
+}
+
 export function registerConsumerScripts(
   consumerRoot,
-  { log = console.log, dryRun = false, packageManager = detectPackageManager(consumerRoot) } = {},
+  { log = console.log, dryRun = false, logNoop = true, 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 };
+  const result = { changed: false, added: [], migrated: [], removed: [], cleanedDoctorScripts: [], conflicts: [], syncRunCommand: null };
 
   for (const [name, command] of Object.entries(requiredScripts)) {
     if (isCompatibleCommand(scripts[name], command)) {
@@ -79,51 +85,47 @@ export function registerConsumerScripts(
     }
   }
 
-  const hookTargets = [];
-  for (const hook of hookScripts) {
-    if (scripts[hook.target] === undefined) {
-      continue;
-    }
-    hookTargets.push(hook.target);
-    if (isCompatibleCommand(scripts[hook.name], doctorCommand)) {
+  // Previous EDS versions ran Doctor as an npm lifecycle hook, or told Yarn Berry users to prefix these
+  // commands. Remove that automatic check while preserving any command that followed the Doctor prefix.
+  for (const name of doctorLifecycleScripts) {
+    if (obsoleteDoctorHooks.has(name) && scripts[name] === doctorCommand) {
+      delete scripts[name];
+      result.cleanedDoctorScripts.push(name);
       continue;
     }
-    if (scripts[hook.name] === undefined) {
-      scripts[hook.name] = doctorCommand;
-      result.added.push(hook.name);
-      continue;
+    if (typeof scripts[name] === "string" && scripts[name].startsWith(doctorPrefix)) {
+      const remainingCommand = scripts[name].slice(doctorPrefix.length).trimStart();
+      if (remainingCommand.length > 0) {
+        scripts[name] = remainingCommand;
+        result.cleanedDoctorScripts.push(name);
+      }
     }
-    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.changed = result.added.length > 0 || result.migrated.length > 0 || result.removed.length > 0 || result.cleanedDoctorScripts.length > 0;
+  // When sync:eds belongs to the consumer, point at the CLI instead of their script. The caller uses this when it
+  // cannot safely ensure that the package script has been registered.
   result.syncRunCommand = result.conflicts.includes(syncScriptName) ? cliCommand(packageManager, "sync") : runnerCommand(packageManager, syncScriptName);
+  const changedScripts = [
+    ...result.added,
+    ...result.migrated,
+    ...result.removed.map((name) => "removed " + name),
+    ...result.cleanedDoctorScripts.map((name) => "removed Doctor from " + name),
+  ];
   if (result.changed && dryRun) {
-    log("[EDS] would update package.json scripts: " + [...result.added, ...result.migrated, ...result.removed].join(", "));
+    log("[EDS] would update package.json scripts: " + changedScripts.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] Updated package.json scripts: " + changedScripts.join(", ") + ".");
+    if (result.cleanedDoctorScripts.length > 0) {
+      log("[EDS] Doctor runs before committing; it is no longer attached to typecheck or build.");
+    }
+  } else if (result.conflicts.length === 0 && logNoop) {
     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

@@ -10,9 +10,10 @@ 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 dimensionUtility = "(?:p|px|py|ps|pe|pt|pr|pb|pl|m|mx|my|ms|me|mt|mr|mb|ml|gap|gap-x|gap-y|space-x|space-y|inset|inset-x|inset-y|start|end|top|right|bottom|left|w|min-w|max-w|h|min-h|max-h|size|basis|scroll-m|scroll-p)";
-const edsSpacingClass = new RegExp(boundaryBefore + variantPrefix + dimensionUtility + "-eds-(spacing-[A-Za-z0-9-]+)" + boundaryAfter, "g");
-const edsRadiusClass = new RegExp(boundaryBefore + variantPrefix + "rounded(?:-(?:s|e|t|r|b|l|ss|se|ee|es|tl|tr|br|bl))?-eds-(radius-[A-Za-z0-9-]+)" + boundaryAfter, "g");
+const retiredDimensionClass = new RegExp(
+  boundaryBefore + variantPrefix + "-?[A-Za-z0-9-]+-eds-(?:spacing|radius)-[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\\()[^\\]]*\\])" +
@@ -20,11 +21,10 @@ const rawColorClass = new RegExp(
   "g",
 );
 
-// The public class names are derived exactly like eds sync derives the Tailwind aliases from tokens.json.
+// EDS publishes color and typography utilities. Spacing and radius use Tailwind CSS v4 defaults.
 export function publicClassNames(manifest) {
   const colors = new Set();
   const typography = new Set();
-  const dimensions = new Set();
   for (const name of Object.keys(manifest.tokens ?? {})) {
     if (name.startsWith("color-")) {
       colors.add("eds-" + name.slice("color-".length));
@@ -35,18 +35,15 @@ export function publicClassNames(manifest) {
       typography.add(match[1]);
       continue;
     }
-    if (name.startsWith("spacing-") || name.startsWith("radius-")) {
-      dimensions.add("eds-" + name.replace(/\./g, "-"));
-    }
   }
-  return { colors, typography, dimensions };
+  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, dimensions } = publicClassNames(manifest);
+  const { colors, typography } = publicClassNames(manifest);
   const unknown = [];
   const raw = [];
   for (const file of files) {
@@ -70,15 +67,8 @@ export function scanClassNames({ consumerRoot, manifest, files }) {
           unknown.push({ location, className: match[0] });
         }
       }
-      for (const match of line.matchAll(edsSpacingClass)) {
-        if (match[1] !== undefined && !dimensions.has("eds-" + match[1])) {
-          unknown.push({ location, className: match[0] });
-        }
-      }
-      for (const match of line.matchAll(edsRadiusClass)) {
-        if (match[1] !== undefined && !dimensions.has("eds-" + match[1])) {
-          unknown.push({ location, className: match[0] });
-        }
+      for (const match of line.matchAll(retiredDimensionClass)) {
+        unknown.push({ location, className: match[0] });
       }
       for (const match of line.matchAll(rawColorClass)) {
         raw.push({ location, className: match[0] });

package/consumer/sync.mjs

@@ -13,7 +13,7 @@ import {
 } 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 { canUseConsumerScript, doctorCommand, doctorScriptName, isCompatibleCommand, registerConsumerScripts, syncCommand, syncScriptName, writeConsumerPackageJson } from "./register-scripts.mjs";
 import { planAgentContext, planClaudeImport, planDeliveryNotes, planGeminiImport } from "./update-agent-context.mjs";
 
 export const syncTargets = new Set(["tailwind", "agents"]);
@@ -31,9 +31,18 @@ export function describeMissingTailwindRoot(plans) {
     : "Tailwind CSS v3 detected (@tailwind directives in " + plans.tailwindV3File + "); " + skippedWiring + " " + tailwindV3Advice;
 }
 
-export function collectPlans({ consumerRoot, env = process.env }) {
+export function collectPlans({ consumerRoot, env = process.env, ensureScripts = false }) {
   const pkg = resolvePackage(consumerRoot);
   const packageManager = detectPackageManager(consumerRoot, env);
+  const scripts = readPackageJson(consumerRoot)?.scripts ?? {};
+  const commands = {
+    sync: canUseConsumerScript(scripts, syncScriptName, syncCommand, { willRegister: ensureScripts })
+      ? runnerCommand(packageManager, syncScriptName)
+      : cliCommand(packageManager, "sync"),
+    doctor: canUseConsumerScript(scripts, doctorScriptName, doctorCommand, { willRegister: ensureScripts })
+      ? runnerCommand(packageManager, doctorScriptName)
+      : cliCommand(packageManager, "doctor"),
+  };
   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).
@@ -44,7 +53,7 @@ export function collectPlans({ consumerRoot, env = process.env }) {
   const errors = [];
   let agents = null;
   try {
-    agents = planAgentContext({ consumerRoot, pkg, packageManager });
+    agents = planAgentContext({ consumerRoot, pkg, packageManager, commands });
   } catch (error) {
     errors.push(error);
   }
@@ -54,11 +63,11 @@ export function collectPlans({ consumerRoot, env = process.env }) {
   return { consumerRoot, pkg, packageManager, sources, root, tailwindV3File, tailwind, cssRoot, legacyImports, agents, claude, gemini, deliveryNotes, errors };
 }
 
-export function planSync({ consumerRoot, env = process.env, only = null }) {
+export function planSync({ consumerRoot, env = process.env, only = null, ensureScripts = true }) {
   if (only !== null && !syncTargets.has(only)) {
     throw createExitError("Unknown --only target: " + only + " (use tailwind or agents).", 2);
   }
-  const plans = collectPlans({ consumerRoot, env });
+  const plans = collectPlans({ consumerRoot, env, ensureScripts: ensureScripts && only === null });
   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;
@@ -83,7 +92,7 @@ export function planSync({ consumerRoot, env = process.env, only = null }) {
 }
 
 // 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.
+// later sync and doctor runs resolve the same root without the environment variable.
 function persistTailwindRoot(plan, { dryRun, log }) {
   if (plan.root?.source !== "env" || plan.only === "agents") {
     return false;
@@ -94,7 +103,7 @@ function persistTailwindRoot(plan, { dryRun, log }) {
   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 \"" +
+      "With several Tailwind CSS candidates, doctor and sync 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;
   }
@@ -109,7 +118,7 @@ function persistTailwindRoot(plan, { dryRun, log }) {
   }
   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 + ".");
+  log("[EDS] wrote " + label + " to package.json; doctor and sync now use this Tailwind root without " + tailwindRootEnvironmentVariable + ".");
   return true;
 }
 
@@ -143,13 +152,17 @@ export function applySync(plan, { dryRun = false, log = console.log } = {}) {
     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 + ".");
+    log("[EDS] Synced with " + version + ". Include the files written above in your change; before committing, 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 });
+export function runSync({ consumerRoot, env = process.env, only = null, dryRun = false, ensureScripts = true, log = console.log }) {
+  const plan = planSync({ consumerRoot, env, only, ensureScripts });
+  // Keep script setup and cleanup in the same one-time task-start command, including package managers that skip postinstall.
+  if (ensureScripts && only === null) {
+    registerConsumerScripts(consumerRoot, { log, dryRun, logNoop: false, packageManager: plan.packageManager });
+  }
   applySync(plan, { dryRun, log });
   return 0;
 }

package/consumer/update-agent-context.mjs

@@ -17,12 +17,12 @@ export const geminiImportLine = "@./AGENTS.md";
 const importPattern = /^[ \t]*@(?:\.\.?\/)?AGENTS\.md[ \t]*$/m;
 const endMarkerText = "<!-- EDS:END -->";
 
-export function planAgentContext({ consumerRoot, pkg, packageManager = null }) {
+export function planAgentContext({ consumerRoot, pkg, packageManager = null, commands = 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 block = withEol(renderBlock(readTemplateBlock(pkg.packageRoot), pkg.version, packageManager, commands), eol);
   const located = before === null ? null : locateBlock(before);
   return {
     label: "agents",

package/consumer-postinstall.mjs

@@ -1,7 +1,10 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { locateBlock, readBlockVersion } from "./consumer/managed-block.mjs";
+import { cliCommand, detectPackageManager, resolvePackage } from "./consumer/paths.mjs";
 import { registerConsumerScripts } from "./consumer/register-scripts.mjs";
+import { runSync } from "./consumer/sync.mjs";
 
 const packageRoot = path.dirname(fileURLToPath(import.meta.url));
 const consumerRoot = process.env.INIT_CWD;
@@ -12,7 +15,7 @@ if (!consumerRoot || path.resolve(consumerRoot) === packageRoot) {
 
 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.");
+  console.log("[EDS] Consumer package.json was not found; the coding agent should run EDS setup in the app package that depends on EDS.");
   process.exit(0);
 }
 
@@ -26,35 +29,90 @@ function realpathOrNull(filePath) {
 
 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.");
+  console.log("[EDS] Skipping consumer setup: this is not the app package's direct EDS install. The coding agent should set up EDS in the app package that depends on it.");
   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.");
+let consumerPackage;
+try {
+  consumerPackage = JSON.parse(fs.readFileSync(consumerPackagePath, "utf8"));
+} catch (error) {
+  console.log("[EDS] Consumer package.json could not be parsed (" + error.message + "); the coding agent should run EDS setup after fixing it.");
   process.exit(0);
 }
 
-let consumerPackage;
+let packageManager;
+let packageJson;
 try {
-  consumerPackage = JSON.parse(fs.readFileSync(consumerPackagePath, "utf8"));
+  packageManager = detectPackageManager(consumerRoot);
+  packageJson = resolvePackage(consumerRoot);
 } catch (error) {
-  console.log("[EDS] Consumer package.json could not be parsed (" + error.message + "); run npx @spectrabrain/eds init after fixing it.");
+  console.log("[EDS] Consumer setup was skipped (" + (error instanceof Error ? error.message : String(error)) + ").");
   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.
+const initCommand = cliCommand(packageManager, "init");
 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.");
+  console.log("[EDS] Skipping consumer setup at the workspaces root. The coding agent should run " + initCommand + " inside the app package that depends on EDS.");
+  process.exit(0);
+}
+
+const agentsPath = path.join(consumerRoot, "AGENTS.md");
+let existingManagedBlock = null;
+let markerVersion = null;
+try {
+  if (fs.existsSync(agentsPath)) {
+    const block = locateBlock(fs.readFileSync(agentsPath, "utf8"));
+    existingManagedBlock = block?.block ?? null;
+    markerVersion = existingManagedBlock === null ? null : readBlockVersion(existingManagedBlock);
+  }
+} catch (error) {
+  console.log(
+    "[EDS] Initial sync was skipped (" + (error instanceof Error ? error.message : String(error)) + "); " +
+      "the coding agent should repair the EDS markers before syncing.",
+  );
   process.exit(0);
 }
 
-// The install must never fail because of this setup step; anything unexpected is reported and left to eds doctor.
+const pnpmInstall = String(process.env.npm_config_user_agent ?? "").startsWith("pnpm/");
+if (!pnpmInstall) {
+  try {
+    registerConsumerScripts(consumerRoot, { packageManager });
+  } catch (error) {
+    console.log("[EDS] Script maintenance was skipped (" + (error instanceof Error ? error.message : String(error)) + ").");
+  }
+}
+
+if (existingManagedBlock !== null && markerVersion === null) {
+  console.log(
+    "[EDS] The existing AGENTS.md EDS block has no version marker; scripts were maintained without changing files, and the coding agent will read the installed version's CHANGELOG.md actions and sync at the start of the next UI task.",
+  );
+  process.exit(0);
+}
+
+if (markerVersion !== null) {
+  if (markerVersion !== packageJson.version) {
+    console.log(
+      "[EDS] Installed EDS version " + packageJson.version + " differs from the AGENTS.md marker " + markerVersion + "; " +
+        "the coding agent will read the version's CHANGELOG.md actions and sync at the start of the next UI task.",
+    );
+  } else {
+    console.log("[EDS] The AGENTS.md version marker matches; the coding agent will check generated files with its next task-start sync.");
+  }
+  process.exit(0);
+}
+
+// pnpm restores package.json after dependency lifecycle scripts, so sync its initial managed files now but let the agent
+// register scripts with its first task-start sync. Other package managers keep both scripts and files.
 try {
-  const result = registerConsumerScripts(consumerRoot);
-  console.log("[EDS] Run " + result.syncRunCommand + " to finish setup.");
+  runSync({ consumerRoot, ensureScripts: false });
+  if (pnpmInstall) {
+    console.log("[EDS] pnpm leaves package.json scripts to the coding agent's first task-start sync.");
+  }
+  console.log("[EDS] Initial EDS sync is ready; the managed instructions tell the coding agent when to sync on later tasks.");
 } 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.");
+  console.log(
+    "[EDS] Initial sync was skipped (" + (error instanceof Error ? error.message : String(error)) + "); " +
+      "the coding agent should resolve the finding and run " + cliCommand(packageManager, "sync") + ".",
+  );
 }

package/dist/components/Button/README.md

@@ -65,10 +65,8 @@ Layout은 prop으로 지정하지 않고 슬롯 조합에서 추론합니다.
 | `iconBoth` | `children`과 앞·뒤 아이콘을 모두 지정합니다. | 양쪽 아이콘이 모두 의미를 더하는 명확한 경우에만 사용합니다. |
 | `iconOnly` | `children` 없이 `icon` 또는 `iconName`과 `aria-label`을 지정합니다. | |
 
-- 이름 슬롯(`iconName`·`startIconName`·`endIconName`)은 승인된 아이콘 목록의 lucide PascalCase 전체 이름만 받습니다. `ButtonIconName`이 이 목록과 같은 union이라 목록에 없는 이름은 TypeScript 오류이고, 런타임에 전달되면 render 오류입니다. 전체 목록은 설치된 패키지 `spec.json`의 `api.iconNames`에 있습니다.
-- 목록은 `lucide-react`의 canonical 이름만 포함하며 `AlertCircle`처럼 deprecated된 alias는 허용하지 않습니다.
-- 목록 밖 아이콘은 `icon`, `startIcon`, `endIcon`에 `ReactElement`로 전달하며, 같은 슬롯에 이름과 custom element를 함께 지정하지 않습니다. `lucide-react`에서 직접 import할 때는 EDS package root `package.json`의 `dependencies["lucide-react"]`와 같은 exact 버전을 소비처 `package.json`에 선언합니다. pnpm처럼 엄격한 node_modules에서는 선언 없이 resolve되지 않고, 버전이 다르면 아이콘 코드가 두 벌 번들됩니다. custom lucide 아이콘은 lucide 기본 stroke를 그대로 써서 이름으로 지정한 아이콘과 맞춥니다.
-- 목록 밖 아이콘을 `ReactElement`로 썼다면 완료 보고에 아이콘 이름과 사용 파일을 allowlist 추가 후보로 적습니다.
+- 이름 슬롯(`iconName`·`startIconName`·`endIconName`)은 설치된 `lucide-react`의 실제 아이콘 component 이름과 alias를 모두 받습니다. `ButtonIconName`이 이 목록을 자동완성하며, 전체 이름은 `spec.json`의 `api.iconNames`에 있습니다. 잘못된 이름은 TypeScript 오류이고 런타임에도 render 오류입니다.
+- custom 아이콘은 `icon`·`startIcon`·`endIcon`에 `ReactElement`로 전달합니다. 같은 슬롯에 이름과 custom element를 함께 지정하지 않습니다. `lucide-react`에서 직접 import할 때는 EDS package root `package.json`의 `dependencies["lucide-react"]`와 같은 exact 버전을 소비처 `package.json`에 선언합니다. pnpm처럼 엄격한 node_modules에서는 선언 없이 resolve되지 않고, 버전이 다르면 아이콘 코드가 두 벌 번들됩니다. 이름 슬롯은 설치된 아이콘 크기와 stroke를 사용합니다.
 
 ### State