@3fn/core 14.1.0 → 15.0.0

package/dist/mcp/application-mcp.js

@@ -2982,7 +2982,7 @@ var require_compile = __commonJS({
       const schOrFunc = root.refs[ref];
       if (schOrFunc)
         return schOrFunc;
-      let _sch = resolve3.call(this, root, ref);
+      let _sch = resolve5.call(this, root, ref);
       if (_sch === void 0) {
         const schema2 = (_a = root.localRefs) === null || _a === void 0 ? void 0 : _a[ref];
         const { schemaId } = this.opts;
@@ -3009,7 +3009,7 @@ var require_compile = __commonJS({
     function sameSchemaEnv(s1, s2) {
       return s1.schema === s2.schema && s1.root === s2.root && s1.baseId === s2.baseId;
     }
-    function resolve3(root, ref) {
+    function resolve5(root, ref) {
       let sch;
       while (typeof (sch = this.refs[ref]) == "string")
         ref = sch;
@@ -3227,8 +3227,8 @@ var require_utils = __commonJS({
       }
       return ind;
     }
-    function removeDotSegments(path10) {
-      let input = path10;
+    function removeDotSegments(path11) {
+      let input = path11;
       const output = [];
       let nextSlash = -1;
       let len = 0;
@@ -3480,8 +3480,8 @@ var require_schemes = __commonJS({
         wsComponent.secure = void 0;
       }
       if (wsComponent.resourceName) {
-        const [path10, query] = wsComponent.resourceName.split("?");
-        wsComponent.path = path10 && path10 !== "/" ? path10 : void 0;
+        const [path11, query] = wsComponent.resourceName.split("?");
+        wsComponent.path = path11 && path11 !== "/" ? path11 : void 0;
         wsComponent.query = query;
         wsComponent.resourceName = void 0;
       }
@@ -3640,7 +3640,7 @@ var require_fast_uri = __commonJS({
       }
       return uri;
     }
-    function resolve3(baseURI, relativeURI, options) {
+    function resolve5(baseURI, relativeURI, options) {
       const schemelessOptions = options ? Object.assign({ scheme: "null" }, options) : { scheme: "null" };
       const resolved = resolveComponent(parse3(baseURI, schemelessOptions), parse3(relativeURI, schemelessOptions), schemelessOptions, true);
       schemelessOptions.skipEscape = true;
@@ -3898,7 +3898,7 @@ var require_fast_uri = __commonJS({
     var fastUri = {
       SCHEMES,
       normalize,
-      resolve: resolve3,
+      resolve: resolve5,
       resolveComponent,
       equal,
       serialize,
@@ -6874,12 +6874,12 @@ var require_dist = __commonJS({
         throw new Error(`Unknown format "${name}"`);
       return f;
     };
-    function addFormats(ajv, list, fs12, exportName) {
+    function addFormats(ajv, list, fs14, exportName) {
       var _a;
       var _b;
       (_a = (_b = ajv.opts.code).formats) !== null && _a !== void 0 ? _a : _b.formats = (0, codegen_1._)`require("ajv-formats/dist/formats").${exportName}`;
       for (const f of list)
-        ajv.addFormat(f, fs12[f]);
+        ajv.addFormat(f, fs14[f]);
     }
     module2.exports = exports2 = formatsPlugin;
     Object.defineProperty(exports2, "__esModule", { value: true });
@@ -6923,11 +6923,11 @@ var require_resolvePackageRoot = __commonJS({
       resolvePackageRoot: () => resolvePackageRoot2
     });
     module2.exports = __toCommonJS2(resolvePackageRoot_exports);
-    var path10 = __toESM2(require("path"));
-    var fs12 = __toESM2(require("fs"));
+    var path11 = __toESM2(require("path"));
+    var fs14 = __toESM2(require("fs"));
     function resolvePackageRoot2(fromDir) {
-      const fromCli = path10.resolve(fromDir, "../..");
-      if (fs12.existsSync(path10.join(fromCli, "package.json"))) {
+      const fromCli = path11.resolve(fromDir, "../..");
+      if (fs14.existsSync(path11.join(fromCli, "package.json"))) {
         return fromCli;
       }
       console.error(
@@ -6971,51 +6971,452 @@ var require_mcpDataRoots = __commonJS({
     var __toCommonJS2 = (mod) => __copyProps2(__defProp2({}, "__esModule", { value: true }), mod);
     var mcpDataRoots_exports = {};
     __export2(mcpDataRoots_exports, {
+      resolveComponentRoots: () => resolveComponentRoots,
       resolveConsumerOwnedRoot: () => resolveConsumerOwnedRoot,
       resolvePackageOwnedRoot: () => resolvePackageOwnedRoot,
-      resolvePackageRoot: () => import_resolvePackageRoot.resolvePackageRoot
+      resolvePackageRoot: () => import_resolvePackageRoot.resolvePackageRoot,
+      resolveProductRoot: () => resolveProductRoot,
+      resolveTokenIndexRoot: () => resolveTokenIndexRoot
     });
     module2.exports = __toCommonJS2(mcpDataRoots_exports);
-    var path10 = __toESM2(require("path"));
-    var fs12 = __toESM2(require("fs"));
+    var path11 = __toESM2(require("path"));
+    var fs14 = __toESM2(require("fs"));
     var import_resolvePackageRoot = require_resolvePackageRoot();
     function resolvePackageOwnedRoot(opts) {
       if (opts.envValue) {
-        return { path: path10.resolve(opts.envValue), source: "env" };
+        return { path: path11.resolve(opts.envValue), source: "env" };
       }
-      return { path: path10.resolve(opts.packageRoot, opts.relPath), source: "package" };
+      return { path: path11.resolve(opts.packageRoot, opts.relPath), source: "package" };
     }
     function resolveConsumerOwnedRoot(opts) {
       if (opts.envValue) {
-        return { path: path10.resolve(opts.envValue), source: "env" };
+        return { path: path11.resolve(opts.envValue), source: "env" };
       }
-      const cwdPath = path10.resolve(process.cwd(), opts.relPath);
+      const cwdPath = path11.resolve(process.cwd(), opts.relPath);
       if (existsNonEmpty(cwdPath)) {
         return { path: cwdPath, source: "cwd" };
       }
       if (opts.packageRoot) {
-        return { path: path10.resolve(opts.packageRoot, opts.relPath), source: "package" };
+        return { path: path11.resolve(opts.packageRoot, opts.relPath), source: "package" };
       }
       return { path: cwdPath, source: "cwd" };
     }
     function existsNonEmpty(p) {
       try {
-        const stat = fs12.statSync(p);
+        const stat = fs14.statSync(p);
         if (stat.isDirectory()) {
-          return fs12.readdirSync(p).length > 0;
+          return fs14.readdirSync(p).length > 0;
         }
         return stat.size > 0;
       } catch {
         return false;
       }
     }
+    function isAbsentOrEmptyDir(p) {
+      try {
+        const stat = fs14.statSync(p);
+        if (stat.isDirectory()) {
+          return fs14.readdirSync(p).length === 0;
+        }
+        return false;
+      } catch {
+        return true;
+      }
+    }
+    function resolveComponentRoots(opts) {
+      const roots = [];
+      const sources = [];
+      if (opts.envValue) {
+        roots.push(path11.resolve(opts.envValue));
+        sources.push("env");
+      } else if (opts.dsRoot.state === "born" && opts.dsRoot.root) {
+        roots.push(path11.join(opts.dsRoot.root, "src", "components"));
+        sources.push("cwd");
+      }
+      roots.push(path11.resolve(opts.packageRoot, "src", "components", "core"));
+      sources.push("package");
+      return { roots, sources };
+    }
+    function resolveTokenIndexRoot(opts) {
+      if (opts.envValue !== void 0) {
+        if (opts.envValue === "") {
+          return { ok: false, reason: "empty-env-value" };
+        }
+        const resolved = path11.resolve(opts.envValue);
+        if (isAbsentOrEmptyDir(resolved)) {
+          return { ok: false, reason: "empty-env-value" };
+        }
+        return { ok: true, path: resolved, source: "env" };
+      }
+      switch (opts.dsRoot.state) {
+        case "born": {
+          const indexPath = path11.join(opts.dsRoot.root, "token-index");
+          if (isAbsentOrEmptyDir(indexPath)) return { ok: false, reason: "run-generate" };
+          return { ok: true, path: indexPath, source: "cwd" };
+        }
+        case "package-mode": {
+          const indexPath = path11.join(opts.dsRoot.root, "token-index");
+          if (isAbsentOrEmptyDir(indexPath)) return { ok: false, reason: "run-generate" };
+          return { ok: true, path: indexPath, source: "cwd", tokenOrigin: "designerpunk-package-mode" };
+        }
+        case "partial":
+          return { ok: false, reason: "partial", partialCase: opts.dsRoot.partialCase };
+        case "unborn":
+        default:
+          return {
+            ok: true,
+            path: path11.resolve(opts.packageRoot, "token-index"),
+            source: "package-consume",
+            tokenOrigin: "designerpunk-reference"
+          };
+      }
+    }
+    function resolveProductRoot(opts) {
+      if (opts.envValue) {
+        return { path: path11.resolve(opts.envValue), source: "env" };
+      }
+      if (opts.dsRoot.state !== "unborn" && opts.dsRoot.root) {
+        return { path: path11.join(opts.dsRoot.root, "product"), source: "cwd" };
+      }
+      return { path: path11.resolve(opts.cwd, "product"), source: "cwd" };
+    }
+  }
+});
+
+// dist/cli/shared/bornRepo.js
+var require_bornRepo = __commonJS({
+  "dist/cli/shared/bornRepo.js"(exports2, module2) {
+    "use strict";
+    var __create2 = Object.create;
+    var __defProp2 = Object.defineProperty;
+    var __getOwnPropDesc2 = Object.getOwnPropertyDescriptor;
+    var __getOwnPropNames2 = Object.getOwnPropertyNames;
+    var __getProtoOf2 = Object.getPrototypeOf;
+    var __hasOwnProp2 = Object.prototype.hasOwnProperty;
+    var __export2 = (target, all) => {
+      for (var name in all)
+        __defProp2(target, name, { get: all[name], enumerable: true });
+    };
+    var __copyProps2 = (to, from, except, desc) => {
+      if (from && typeof from === "object" || typeof from === "function") {
+        for (let key of __getOwnPropNames2(from))
+          if (!__hasOwnProp2.call(to, key) && key !== except)
+            __defProp2(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc2(from, key)) || desc.enumerable });
+      }
+      return to;
+    };
+    var __toESM2 = (mod, isNodeMode, target) => (target = mod != null ? __create2(__getProtoOf2(mod)) : {}, __copyProps2(
+      // If the importer is in node compatibility mode or this is not an ESM
+      // file that has been converted to a CommonJS file using a Babel-
+      // compatible transform (i.e. "__esModule" has not been set), then set
+      // "default" to the CommonJS "module.exports" for node compatibility.
+      isNodeMode || !mod || !mod.__esModule ? __defProp2(target, "default", { value: mod, enumerable: true }) : target,
+      mod
+    ));
+    var __toCommonJS2 = (mod) => __copyProps2(__defProp2({}, "__esModule", { value: true }), mod);
+    var bornRepo_exports = {};
+    __export2(bornRepo_exports, {
+      findDesignSystemRoot: () => findDesignSystemRoot,
+      isDesignerPunkTier: () => isDesignerPunkTier
+    });
+    module2.exports = __toCommonJS2(bornRepo_exports);
+    var path11 = __toESM2(require("path"));
+    var fs14 = __toESM2(require("fs"));
+    var import_resolvePackageRoot = require_resolvePackageRoot();
+    var CONFIG_FILE = "designerpunk.config.ts";
+    var MANIFEST_FILE = "designerpunk.manifest.json";
+    var LEGACY_MANIFEST_RELPATH = path11.join(".kiro", "sync-manifest.json");
+    var TOKEN_SOURCE_RELPATH = path11.join("src", "tokens");
+    var GIT_MARKER = ".git";
+    function hasNodeModulesSegment(dir) {
+      return dir.split(path11.sep).includes("node_modules");
+    }
+    function isGitBoundary(dir) {
+      return fs14.existsSync(path11.join(dir, GIT_MARKER));
+    }
+    function exportsTextually(source, exportName) {
+      const escaped = exportName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      const functionForm = new RegExp(`export\\s+(?:async\\s+)?function\\s*\\*?\\s*${escaped}\\b`);
+      const constLetForm = new RegExp(`export\\s+(?:const|let)\\s+${escaped}\\b`);
+      const reExportForm = new RegExp(`export\\s*\\{[^}]*\\b${escaped}\\b[^}]*\\}\\s*from\\s*['"\`]`);
+      return functionForm.test(source) || constLetForm.test(source) || reExportForm.test(source);
+    }
+    function readFileTextSafe(filePath) {
+      try {
+        const text = fs14.readFileSync(filePath, "utf8");
+        return typeof text === "string" ? text : null;
+      } catch {
+        return null;
+      }
+    }
+    function isDesignerPunkTier(dir) {
+      const indexText = readFileTextSafe(path11.join(dir, "index.ts"));
+      if (indexText === null || !exportsTextually(indexText, "getAllPrimitiveTokens")) return false;
+      const semanticIndexText = readFileTextSafe(path11.join(dir, "semantic", "index.ts"));
+      if (semanticIndexText === null || !exportsTextually(semanticIndexText, "getAllSemanticTokens")) return false;
+      return true;
+    }
+    function readConfigTokenSource(configPath) {
+      const text = readFileTextSafe(configPath);
+      if (text === null) return { present: false };
+      const uncommented = text.split("\n").filter((line) => !/^\s*\/\//.test(line)).join("\n");
+      const literalMatch = uncommented.match(/\btokenSource\s*:\s*['"`]([^'"`]+)['"`]/);
+      if (literalMatch) return { present: true, literal: true, value: literalMatch[1] };
+      if (/\btokenSource\s*:/.test(uncommented)) return { present: true, literal: false };
+      return { present: false };
+    }
+    function readManifestPosture(manifestPath) {
+      const text = readFileTextSafe(manifestPath);
+      if (text === null) return null;
+      try {
+        const parsed = JSON.parse(text);
+        return typeof parsed.posture === "string" ? parsed.posture : null;
+      } catch {
+        return null;
+      }
+    }
+    function evaluateDirectory(dir, packageRoot) {
+      const configPath = path11.join(dir, CONFIG_FILE);
+      const hasConfig = fs14.existsSync(configPath);
+      const tokenSourceRead = hasConfig ? readConfigTokenSource(configPath) : { present: false };
+      const hasTokenSource = tokenSourceRead.present;
+      const localTierDir = path11.join(dir, TOKEN_SOURCE_RELPATH);
+      const localBarrelIsTier = isDesignerPunkTier(localTierDir);
+      const tokenSourceRoot = tokenSourceRead.present && tokenSourceRead.literal ? path11.resolve(dir, tokenSourceRead.value) : null;
+      const tierPresentAtTokenSource = tokenSourceRoot !== null && isDesignerPunkTier(tokenSourceRoot);
+      const packageOwnedTierDir = path11.resolve(packageRoot, TOKEN_SOURCE_RELPATH);
+      const manifestPath = path11.join(dir, MANIFEST_FILE);
+      const manifestExists = fs14.existsSync(manifestPath);
+      const manifestPosture = manifestExists ? readManifestPosture(manifestPath) : null;
+      const manifestSignal = manifestExists && manifestPosture !== "consume";
+      const legacyManifestSignal = fs14.existsSync(path11.join(dir, LEGACY_MANIFEST_RELPATH));
+      const isSteward = path11.resolve(dir) === path11.resolve(packageRoot);
+      let state;
+      let partialCase;
+      let tierDir = null;
+      if (hasConfig && hasTokenSource) {
+        if (tierPresentAtTokenSource) {
+          state = "born";
+          tierDir = tokenSourceRoot;
+        } else {
+          state = "partial";
+          partialCase = "config-no-tier";
+        }
+      } else if (hasConfig) {
+        if (localBarrelIsTier && !isSteward) {
+          state = "partial";
+          partialCase = "unused-local-tier";
+        } else {
+          state = "package-mode";
+          tierDir = packageOwnedTierDir;
+        }
+      } else if (localBarrelIsTier) {
+        state = "partial";
+        partialCase = "tier-no-config";
+      } else if (manifestSignal) {
+        state = "partial";
+        partialCase = "manifest-only";
+      } else {
+        state = "unborn";
+      }
+      const anySignal = hasConfig || localBarrelIsTier || manifestSignal;
+      const tierSignal = localBarrelIsTier || tierPresentAtTokenSource;
+      const attemptedTokenSource = partialCase === "config-no-tier" && tokenSourceRoot !== null ? tokenSourceRoot : void 0;
+      return {
+        anySignal,
+        state,
+        partialCase,
+        tierDir,
+        attemptedTokenSource,
+        signals: {
+          config: hasConfig,
+          tier: tierSignal,
+          manifest: manifestSignal,
+          legacyManifest: legacyManifestSignal
+        }
+      };
+    }
+    function resolveOwnPackageRoot() {
+      let dir = __dirname;
+      while (true) {
+        if (fs14.existsSync(path11.join(dir, "package.json"))) return dir;
+        const parent = path11.dirname(dir);
+        if (parent === dir) return (0, import_resolvePackageRoot.resolvePackageRoot)(path11.dirname(__dirname));
+        dir = parent;
+      }
+    }
+    var UNBORN_RESULT = {
+      state: "unborn",
+      root: null,
+      tierDir: null,
+      signals: { config: false, tier: false, manifest: false, legacyManifest: false }
+    };
+    function findDesignSystemRoot(startDir) {
+      const packageRoot = resolveOwnPackageRoot();
+      let dir = path11.resolve(startDir);
+      while (true) {
+        if (!hasNodeModulesSegment(dir)) {
+          const evaluation = evaluateDirectory(dir, packageRoot);
+          if (evaluation.anySignal) {
+            return {
+              state: evaluation.state,
+              root: dir,
+              tierDir: evaluation.tierDir,
+              partialCase: evaluation.partialCase,
+              attemptedTokenSource: evaluation.attemptedTokenSource,
+              signals: evaluation.signals
+            };
+          }
+        }
+        if (isGitBoundary(dir)) {
+          break;
+        }
+        const parent = path11.dirname(dir);
+        if (parent === dir) {
+          break;
+        }
+        dir = parent;
+      }
+      return UNBORN_RESULT;
+    }
+  }
+});
+
+// dist/cli/shared/errorCatalog.js
+var require_errorCatalog = __commonJS({
+  "dist/cli/shared/errorCatalog.js"(exports2, module2) {
+    "use strict";
+    var __defProp2 = Object.defineProperty;
+    var __getOwnPropDesc2 = Object.getOwnPropertyDescriptor;
+    var __getOwnPropNames2 = Object.getOwnPropertyNames;
+    var __hasOwnProp2 = Object.prototype.hasOwnProperty;
+    var __export2 = (target, all) => {
+      for (var name in all)
+        __defProp2(target, name, { get: all[name], enumerable: true });
+    };
+    var __copyProps2 = (to, from, except, desc) => {
+      if (from && typeof from === "object" || typeof from === "function") {
+        for (let key of __getOwnPropNames2(from))
+          if (!__hasOwnProp2.call(to, key) && key !== except)
+            __defProp2(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc2(from, key)) || desc.enumerable });
+      }
+      return to;
+    };
+    var __toCommonJS2 = (mod) => __copyProps2(__defProp2({}, "__esModule", { value: true }), mod);
+    var errorCatalog_exports = {};
+    __export2(errorCatalog_exports, {
+      attachUnbornRepoMessage: () => attachUnbornRepoMessage,
+      bornIndexAbsentMessage: () => bornIndexAbsentMessage,
+      cloneHatchMessage: () => cloneHatchMessage,
+      componentTokenFamilyMismatchMessage: () => componentTokenFamilyMismatchMessage,
+      componentTokenFileLoadFailedMessage: () => componentTokenFileLoadFailedMessage,
+      consumerDegradationMessage: () => consumerDegradationMessage,
+      existingMcpEntryMessage: () => existingMcpEntryMessage,
+      explicitTokenIndexMissingMessage: () => explicitTokenIndexMissingMessage,
+      initBornRepoMessage: () => initBornRepoMessage,
+      jestConfigCollisionMessage: () => jestConfigCollisionMessage,
+      managedRegionEditedInsideMessage: () => managedRegionEditedInsideMessage,
+      managedRegionMarkersMissingMessage: () => managedRegionMarkersMissingMessage,
+      packageModeIndexAbsentMessage: () => packageModeIndexAbsentMessage,
+      partialCaseMessage: () => partialCaseMessage,
+      partialConfigNoTierMessage: () => partialConfigNoTierMessage,
+      partialManifestOnlyMessage: () => partialManifestOnlyMessage,
+      partialTierNoConfigMessage: () => partialTierNoConfigMessage,
+      partialUnusedLocalTierMessage: () => partialUnusedLocalTierMessage,
+      personalNoteNamingMessage: () => personalNoteNamingMessage,
+      restartLineNowMessage: () => restartLineNowMessage,
+      restartLineSequencedMessage: () => restartLineSequencedMessage
+    });
+    module2.exports = __toCommonJS2(errorCatalog_exports);
+    function partialConfigNoTierMessage(root, tokenSource) {
+      const tokenSourceSlot = tokenSource ?? "(a non-literal tokenSource value in designerpunk.config.ts)";
+      return `found designerpunk.config.ts at ${root} but no DesignerPunk token tier at ${tokenSourceSlot} \u2014 this repo looks partly initialized. Refusing rather than guessing. Inspect it, or complete it deliberately: npx designerpunk init --re-scaffold`;
+    }
+    function partialUnusedLocalTierMessage(root) {
+      return `found a token tier at ${root}/src/tokens but your config omits tokenSource, so generate would use DesignerPunk's tokens, not yours. Add tokenSource: './src/tokens' to designerpunk.config.ts. (Refusing to generate until then.)`;
+    }
+    function partialTierNoConfigMessage(root) {
+      return `found a DesignerPunk token tier at ${root}/src/tokens but no designerpunk.config.ts \u2014 refusing to generate or serve DesignerPunk's reference index as yours. Restore the config, or run: npx designerpunk init --re-scaffold`;
+    }
+    function partialManifestOnlyMessage(root) {
+      return `found designerpunk.manifest.json at ${root} but no config or token tier \u2014 the design system files are missing. Restore them from version control, or run: npx designerpunk init --re-scaffold`;
+    }
+    function partialCaseMessage(root, partialCase, attemptedTokenSource) {
+      switch (partialCase) {
+        case "config-no-tier":
+          return partialConfigNoTierMessage(root, attemptedTokenSource);
+        case "unused-local-tier":
+          return partialUnusedLocalTierMessage(root);
+        case "tier-no-config":
+          return partialTierNoConfigMessage(root);
+        case "manifest-only":
+          return partialManifestOnlyMessage(root);
+      }
+    }
+    function packageModeIndexAbsentMessage() {
+      return `this repo runs in package mode (designerpunk.config.ts has no tokenSource), so its token index is DesignerPunk's tokens \u2014 run 'npx designerpunk generate' to build it. To make a design system of your own: npx designerpunk init --re-scaffold`;
+    }
+    function bornIndexAbsentMessage(root) {
+      return `no token index in this design system (${root}/token-index is absent or empty) \u2014 run 'npx designerpunk generate'`;
+    }
+    function explicitTokenIndexMissingMessage(explicitPath) {
+      return `TOKEN_INDEX_DIR is set to ${explicitPath}, which is absent or empty \u2014 unset it, or run generate`;
+    }
+    function initBornRepoMessage(root) {
+      return `this repo already has a design system (${root}) \u2014 init is the birth event and runs once. To join it: npm install \u2192 npx designerpunk generate \u2192 fill in .designerpunk/personal-note.local.md (generate creates it) \u2192 restart your agent session (approve DesignerPunk's MCP servers if asked). Using a different agent tool than this repo was set up for? Also run: npx designerpunk attach --target=<cc|kiro> to attach a harness (agents + MCP config + approvals). To deliberately re-scaffold: npx designerpunk init --re-scaffold`;
+    }
+    function restartLineSequencedMessage() {
+      return `when the steps above are done, restart your agent session \u2014 DesignerPunk's MCP servers and your personal note load when a session starts, so this session cannot see them yet (approve the servers if your tool asks)`;
+    }
+    function cloneHatchMessage() {
+      return `want to own the engine too? Clone github.com/3fn/DesignerPunk \u2014 init already made the token language yours; the clone adds the engine and the components`;
+    }
+    function personalNoteNamingMessage() {
+      return `fill in .designerpunk/personal-note.local.md \u2014 who you are and how you want to be worked with; your agents read it every session (it stays on your machine)`;
+    }
+    function jestConfigCollisionMessage() {
+      return `skipped: jest.config.js (already exists) \u2014 the DesignerPunk jest preset is not applied; to test your own forked components with @3fn/core/testing, add ...require('@3fn/core/jest-preset') to your config`;
+    }
+    function consumerDegradationMessage(member, where, consequence) {
+      return `warning: ${member} is missing from the installed @3fn/core (${where}) \u2014 ${consequence}. Generation continued without it. If a clean reinstall (remove node_modules, then npm install) does not restore it, the package you installed does not contain it.`;
+    }
+    function managedRegionMarkersMissingMessage(file) {
+      return `the DesignerPunk-managed region in ${file} is missing its markers \u2014 not rewriting the file. Restore the markers (see install doc \xA7 "Your agent layer") or re-run attach`;
+    }
+    function managedRegionEditedInsideMessage(file) {
+      return `you edited inside the DesignerPunk-managed region of ${file} \u2014 those edits will be replaced. Move them outside the region; not applying without --apply`;
+    }
+    function attachUnbornRepoMessage() {
+      return `no design system here. To create one: npx designerpunk init. Only reading DesignerPunk's docs and components? No init needed: npx designerpunk attach --target=<cc|kiro> --reference`;
+    }
+    function restartLineNowMessage() {
+      return `restart your agent session now \u2014 DesignerPunk's MCP servers load when a session starts, so this session cannot see them yet (approve them if your tool asks)`;
+    }
+    function existingMcpEntryMessage(configFile, key, target) {
+      return `${configFile} already has '${key}' entry; left unchanged. If it is outdated, delete the entry and re-run: npx designerpunk attach --target=${target} \u2014 or update it by hand.`;
+    }
+    function componentTokenFamilyMismatchMessage(file, guardMessage) {
+      let alternative = "";
+      if (file.startsWith("src/tokens/")) {
+        alternative = ` Or, if an earlier DesignerPunk init copied this file, replace it with the package's version at node_modules/@3fn/core/${file} and change its '../../build/tokens' import to '@3fn/core/build'.`;
+      } else if (file.startsWith("src/components/core/")) {
+        alternative = ` Or, if this is an unedited copy an earlier DesignerPunk init made, delete it \u2014 its component tokens then leave your generated ComponentTokens.* files.`;
+      }
+      return `generate stopped \u2014 ${file} declares a component token in the wrong family's defineComponentTokens() call. ${guardMessage} To fix it, split that file's defineComponentTokens() into one call per token family.${alternative} Nothing was written.`;
+    }
+    function componentTokenFileLoadFailedMessage(file, reason) {
+      const firstLine = reason.split(/\r?\n/, 1)[0].trim();
+      return `generate stopped \u2014 ${file} could not be loaded: ${firstLine} Fix the file and run generate again. Nothing was written.`;
+    }
   }
 });
 
 // application-mcp-server/src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  createTestableServer: () => createTestableServer
+  createTestableServer: () => createTestableServer,
+  resolveTokenIndexUnavailableMessage: () => resolveTokenIndexUnavailableMessage,
+  tools: () => tools
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -7214,10 +7615,10 @@ function assignProp(target, prop, value) {
     configurable: true
   });
 }
-function getElementAtPath(obj, path10) {
-  if (!path10)
+function getElementAtPath(obj, path11) {
+  if (!path11)
     return obj;
-  return path10.reduce((acc, key) => acc?.[key], obj);
+  return path11.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject(promisesObj) {
   const keys = Object.keys(promisesObj);
@@ -7537,11 +7938,11 @@ function aborted(x, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues(path10, issues) {
+function prefixIssues(path11, issues) {
   return issues.map((iss) => {
     var _a;
     (_a = iss).path ?? (_a.path = []);
-    iss.path.unshift(path10);
+    iss.path.unshift(path11);
     return iss;
   });
 }
@@ -12859,7 +13260,7 @@ var Protocol = class {
           return;
         }
         const pollInterval = task2.pollInterval ?? this._options?.defaultTaskPollInterval ?? 1e3;
-        await new Promise((resolve3) => setTimeout(resolve3, pollInterval));
+        await new Promise((resolve5) => setTimeout(resolve5, pollInterval));
         options?.signal?.throwIfAborted();
       }
     } catch (error2) {
@@ -12876,7 +13277,7 @@ var Protocol = class {
    */
   request(request, resultSchema, options) {
     const { relatedRequestId, resumptionToken, onresumptiontoken, task, relatedTask } = options ?? {};
-    return new Promise((resolve3, reject) => {
+    return new Promise((resolve5, reject) => {
       const earlyReject = (error2) => {
         reject(error2);
       };
@@ -12954,7 +13355,7 @@ var Protocol = class {
           if (!parseResult.success) {
             reject(parseResult.error);
           } else {
-            resolve3(parseResult.data);
+            resolve5(parseResult.data);
           }
         } catch (error2) {
           reject(error2);
@@ -13215,12 +13616,12 @@ var Protocol = class {
       }
     } catch {
     }
-    return new Promise((resolve3, reject) => {
+    return new Promise((resolve5, reject) => {
       if (signal.aborted) {
         reject(new McpError(ErrorCode.InvalidRequest, "Request cancelled"));
         return;
       }
-      const timeoutId = setTimeout(resolve3, interval);
+      const timeoutId = setTimeout(resolve5, interval);
       signal.addEventListener("abort", () => {
         clearTimeout(timeoutId);
         reject(new McpError(ErrorCode.InvalidRequest, "Request cancelled"));
@@ -14090,20 +14491,20 @@ var StdioServerTransport = class {
     this.onclose?.();
   }
   send(message) {
-    return new Promise((resolve3) => {
+    return new Promise((resolve5) => {
       const json2 = serializeMessage(message);
       if (this._stdout.write(json2)) {
-        resolve3();
+        resolve5();
       } else {
-        this._stdout.once("drain", resolve3);
+        this._stdout.once("drain", resolve5);
       }
     });
   }
 };
 
 // application-mcp-server/src/indexer/ComponentIndexer.ts
-var fs8 = __toESM(require("fs"));
-var path7 = __toESM(require("path"));
+var fs11 = __toESM(require("fs"));
+var path9 = __toESM(require("path"));
 
 // application-mcp-server/src/indexer/parsers.ts
 var fs = __toESM(require("fs"));
@@ -17511,8 +17912,8 @@ var LayoutTemplateIndexer = class {
 };
 
 // application-mcp-server/src/indexer/TokenIndexer.ts
-var fs6 = __toESM(require("fs"));
-var path5 = __toESM(require("path"));
+var fs8 = __toESM(require("fs"));
+var path6 = __toESM(require("path"));
 
 // application-mcp-server/src/indexer/TokenRefResolver.ts
 var fs5 = __toESM(require("fs"));
@@ -17643,7 +18044,80 @@ var TokenRefResolver = class {
   }
 };
 
+// application-mcp-server/src/indexer/SemanticOverrideReader.ts
+var fs6 = __toESM(require("fs"));
+var KEY_PATTERN = /^\s*'([^']+)':\s*\{\s*primitiveReferences:/gm;
+var REF_PAIR_PATTERN = /(?:'([^']+)'|([A-Za-z_$][\w$]*))\s*:\s*'([^']*)'/g;
+function extractBalancedBlock(content, openIndex) {
+  if (content[openIndex] !== "{") return null;
+  let depth = 0;
+  for (let i = openIndex; i < content.length; i++) {
+    const ch = content[i];
+    if (ch === "{") depth++;
+    else if (ch === "}") {
+      depth--;
+      if (depth === 0) return content.slice(openIndex + 1, i);
+    }
+  }
+  return null;
+}
+function parseRefs(block) {
+  const refs = {};
+  REF_PAIR_PATTERN.lastIndex = 0;
+  let match;
+  while ((match = REF_PAIR_PATTERN.exec(block)) !== null) {
+    const key = match[1] ?? match[2];
+    refs[key] = match[3];
+  }
+  return refs;
+}
+function parseSemanticOverrides(overridesPath) {
+  const overrides = /* @__PURE__ */ new Map();
+  if (!fs6.existsSync(overridesPath)) return { overrides, fileFound: false };
+  let content;
+  try {
+    content = fs6.readFileSync(overridesPath, "utf-8");
+  } catch {
+    return { overrides, fileFound: false };
+  }
+  KEY_PATTERN.lastIndex = 0;
+  let match;
+  while ((match = KEY_PATTERN.exec(content)) !== null) {
+    const name = match[1];
+    const braceIndex = content.indexOf("{", match.index + match[0].length - 1);
+    const block = braceIndex === -1 ? null : extractBalancedBlock(content, braceIndex);
+    overrides.set(name, block === null ? {} : parseRefs(block));
+  }
+  return { overrides, fileFound: true };
+}
+
+// application-mcp-server/src/indexer/resolveThemeTierRoot.ts
+var fs7 = __toESM(require("fs"));
+var path5 = __toESM(require("path"));
+function resolveThemeTierRoot(tokenIndexDir, explicitTierDir, projectRoot) {
+  if (tokenIndexDir) {
+    try {
+      const raw = fs7.readFileSync(path5.join(tokenIndexDir, "meta.json"), "utf8");
+      const meta = JSON.parse(raw);
+      if (typeof meta.tierDir === "string" && meta.tierDir.length > 0) {
+        const recorded = path5.isAbsolute(meta.tierDir) ? meta.tierDir : path5.resolve(tokenIndexDir, meta.tierDir);
+        if (fs7.existsSync(recorded)) return recorded;
+      }
+    } catch {
+    }
+  }
+  if (explicitTierDir) return explicitTierDir;
+  return path5.join(projectRoot, "src", "tokens");
+}
+
 // application-mcp-server/src/indexer/TokenIndexer.ts
+function extractDarkModeValue(value) {
+  if (!value || typeof value !== "object") return null;
+  const dark = value.dark;
+  if (!dark || typeof dark !== "object") return null;
+  const base = dark.base;
+  return typeof base === "string" || typeof base === "number" ? base : null;
+}
 var TokenIndexer = class {
   constructor() {
     this.primitives = /* @__PURE__ */ new Map();
@@ -17651,20 +18125,38 @@ var TokenIndexer = class {
     this.componentTokens = /* @__PURE__ */ new Map();
     this.consumerIndex = /* @__PURE__ */ new Map();
     this.warnings = [];
+    // Level 2 dark overrides, text-parsed from src/tokens/themes/dark/SemanticOverrides.ts
+    // (issue 2026-09-12). Empty map = no overrides loaded; see the ThemeResolutions contract.
+    this.darkOverrides = /* @__PURE__ */ new Map();
   }
-  async indexTokens(tokenIndexDir) {
+  /**
+   * @param tokenIndexDir Directory holding primitives/semantics/components.yaml. Also where
+   *                      `meta.json`'s `tierDir` is read from (Spec 123 Task 1.5, DD24) —
+   *                      the AUTHORITATIVE theme-root source when present.
+   * @param projectRoot   LEGACY fallback used only when neither `meta.json` nor
+   *                      `explicitTierDir` resolves a tier. Defaults to the token index's
+   *                      parent (`<root>/token-index` is the standard layout).
+   * @param explicitTierDir The caller's own resolved tier (e.g. `DesignSystemRoot.tierDir`),
+   *                      used when `meta.json` is absent (a pre-1.5 index) — second
+   *                      precedence, per `resolveThemeTierRoot`.
+   */
+  async indexTokens(tokenIndexDir, projectRoot, explicitTierDir) {
     this.primitives.clear();
     this.semantics.clear();
     this.componentTokens.clear();
     this.consumerIndex.clear();
+    this.darkOverrides.clear();
     this.warnings = [];
-    if (!fs6.existsSync(tokenIndexDir)) {
+    this.loadThemeOverrides(
+      resolveThemeTierRoot(tokenIndexDir, explicitTierDir, projectRoot ?? path6.resolve(tokenIndexDir, ".."))
+    );
+    if (!fs8.existsSync(tokenIndexDir)) {
       this.warnings.push(`Token index directory not found: ${tokenIndexDir}`);
       return;
     }
-    this.loadTier(path5.join(tokenIndexDir, "primitives.yaml"), "primitive", this.primitives);
-    this.loadTier(path5.join(tokenIndexDir, "semantics.yaml"), "semantic", this.semantics);
-    this.loadTier(path5.join(tokenIndexDir, "components.yaml"), "component", this.componentTokens);
+    this.loadTier(path6.join(tokenIndexDir, "primitives.yaml"), "primitive", this.primitives);
+    this.loadTier(path6.join(tokenIndexDir, "semantics.yaml"), "semantic", this.semantics);
+    this.loadTier(path6.join(tokenIndexDir, "components.yaml"), "component", this.componentTokens);
     this.resolver = new TokenRefResolver(tokenIndexDir);
     this.resolver.load();
     this.buildConsumerIndex();
@@ -17690,7 +18182,8 @@ var TokenIndexer = class {
   getDetails(name) {
     const entry = this.primitives.get(name) || this.semantics.get(name) || this.componentTokens.get(name) || null;
     if (!entry) return null;
-    return { ...entry, ...this.resolveTriple(name) };
+    const triple = this.resolveTriple(name);
+    return { ...entry, ...triple, themeResolutions: this.resolveThemeResolutions(name, triple) };
   }
   /**
    * Map TokenRefResolver's ResolvedRef → the resolved-value triple (Req 2 null-contract, verbatim):
@@ -17710,6 +18203,80 @@ var TokenIndexer = class {
       resolutionDepth: resolved.depth
     };
   }
+  /**
+   * Build the theme-scoped resolutions for a token (issue 2026-09-12).
+   * Currently one theme: `dark`. See the ThemeResolutions doc for the null contract and for
+   * why wcag/dark-wcag are deliberately not resolved here.
+   *
+   * @param baseTriple the token's base resolution — used only as the unitType fallback, so the
+   *                   theme branch and the base branch agree on unit typing without
+   *                   duplicating TokenRefResolver's category→unit table.
+   */
+  resolveThemeResolutions(name, baseTriple) {
+    const refs = this.darkOverrides.get(name);
+    if (!refs) return { dark: null };
+    return { dark: this.resolveOverride(name, refs, baseTriple) };
+  }
+  /**
+   * Resolve one override's primitiveReferences through the same chain the base triple uses.
+   * Primary-ref extraction mirrors TokenRefResolver.extractPrimaryRef exactly (single key →
+   * that key; multi-key with `value` → `value`; otherwise composite → partial).
+   */
+  resolveOverride(name, refs, baseTriple) {
+    const keys = Object.keys(refs);
+    const primaryRef = keys.length === 1 ? refs[keys[0]] : "value" in refs ? refs.value : null;
+    if (primaryRef == null) {
+      return {
+        primitiveReferences: { ...refs },
+        resolvedValue: name,
+        resolvedUnitType: baseTriple.resolvedUnitType,
+        resolutionDepth: "partial",
+        modeValue: null
+      };
+    }
+    const resolved = this.resolver?.resolve(primaryRef) ?? null;
+    if (!resolved) {
+      return {
+        primitiveReferences: { ...refs },
+        resolvedValue: primaryRef,
+        resolvedUnitType: baseTriple.resolvedUnitType,
+        resolutionDepth: "partial",
+        modeValue: null
+      };
+    }
+    return {
+      primitiveReferences: { ...refs },
+      resolvedValue: resolved.value,
+      resolvedUnitType: resolved.unitType,
+      resolutionDepth: resolved.depth,
+      modeValue: extractDarkModeValue(resolved.value)
+    };
+  }
+  /**
+   * Load theme override files. Text-parsed — no coupling to the token pipeline.
+   * A missing file is WARNED (not silent): without it every token reports `dark: null`,
+   * which is indistinguishable from "no override" at the field level.
+   *
+   * @param tierRoot The resolved theme TIER ROOT (`resolveThemeTierRoot`'s return) — NOT a
+   *   project root. `themes/dark/SemanticOverrides.ts` is read directly under it (Spec 123
+   *   Task 1.5, DD24).
+   */
+  loadThemeOverrides(tierRoot) {
+    const darkPath = path6.join(tierRoot, "themes/dark/SemanticOverrides.ts");
+    const { overrides, fileFound } = parseSemanticOverrides(darkPath);
+    if (!fileFound) {
+      this.warnings.push(
+        `Dark theme overrides not found: ${darkPath} \u2014 get_token_details will report themeResolutions.dark = null for every token`
+      );
+      return;
+    }
+    if (overrides.size === 0) {
+      this.warnings.push(
+        `Dark theme overrides parsed to 0 entries: ${darkPath} \u2014 the file exists but no override entries matched (parser may be stale)`
+      );
+    }
+    this.darkOverrides = overrides;
+  }
   getFamily(family) {
     const f = family.toLowerCase();
     const results = [];
@@ -17738,9 +18305,9 @@ var TokenIndexer = class {
   }
   // --- Private ---
   loadTier(filePath, tier, map2) {
-    if (!fs6.existsSync(filePath)) return;
+    if (!fs8.existsSync(filePath)) return;
     try {
-      const content = fs6.readFileSync(filePath, "utf-8");
+      const content = fs8.readFileSync(filePath, "utf-8");
       const data = load(content);
       if (!data?.tokens) return;
       for (const [name, entry] of Object.entries(data.tokens)) {
@@ -17779,8 +18346,8 @@ var TokenIndexer = class {
 };
 
 // application-mcp-server/src/indexer/ModeClassifier.ts
-var fs7 = __toESM(require("fs"));
-var path6 = __toESM(require("path"));
+var fs9 = __toESM(require("fs"));
+var path7 = __toESM(require("path"));
 var MODE_INVARIANT_TOKENS = /* @__PURE__ */ new Set([
   "color.scrim.standard",
   "color.print.default",
@@ -17797,15 +18364,7 @@ function isColorToken(name) {
   return COLOR_PREFIXES.some((p) => name.startsWith(p));
 }
 function extractOverrideKeys(overridesPath) {
-  const keys = /* @__PURE__ */ new Set();
-  if (!fs7.existsSync(overridesPath)) return keys;
-  const content = fs7.readFileSync(overridesPath, "utf-8");
-  const keyPattern = /^\s*'([^']+)':\s*\{\s*primitiveReferences:/gm;
-  let match;
-  while ((match = keyPattern.exec(content)) !== null) {
-    keys.add(match[1]);
-  }
-  return keys;
+  return new Set(parseSemanticOverrides(overridesPath).overrides.keys());
 }
 var ModeClassifier = class {
   constructor() {
@@ -17814,12 +18373,26 @@ var ModeClassifier = class {
   }
   /**
    * Load classification data from the project's SemanticOverrides file.
-   * @param projectRoot Absolute path to the project root
+   *
+   * Spec 123 Task 1.5 (DD24 — "the theme root travels with the index"): the theme
+   * root is resolved via `resolveThemeTierRoot` (meta.json's `tierDir` → the
+   * caller's explicit tier → the legacy `<projectRoot>/src/tokens` default), NOT
+   * hardcoded to `<projectRoot>/src/tokens` — that hardcoding is wrong for
+   * package-mode consumers, whose live tier is the PACKAGE's `src/tokens`.
+   *
+   * @param projectRoot Absolute path to the project root (the LEGACY fallback tier
+   *   base — kept as the third-precedence source; unchanged callers see identical
+   *   behavior when neither `tokenIndexDir` nor `explicitTierDir` is passed).
+   * @param tokenIndexDir The served token-index directory, so `meta.json`'s
+   *   recorded `tierDir` can be read (optional — omit when unknown).
+   * @param explicitTierDir The caller's own resolved tier (e.g.
+   *   `DesignSystemRoot.tierDir`), used when `meta.json` is absent (optional).
    */
-  load(projectRoot) {
-    const overridesPath = path6.join(projectRoot, "src/tokens/themes/dark/SemanticOverrides.ts");
+  load(projectRoot, tokenIndexDir, explicitTierDir) {
+    const tierRoot = resolveThemeTierRoot(tokenIndexDir, explicitTierDir, projectRoot);
+    const overridesPath = path7.join(tierRoot, "themes/dark/SemanticOverrides.ts");
     this.level2Keys = extractOverrideKeys(overridesPath);
-    if (!fs7.existsSync(overridesPath)) {
+    if (!fs9.existsSync(overridesPath)) {
       this.warnings.push("SemanticOverrides.ts not found \u2014 mode classification unavailable");
     }
   }
@@ -17844,7 +18417,95 @@ var ModeClassifier = class {
   }
 };
 
+// application-mcp-server/src/staleness/StalenessGate.ts
+var fs10 = __toESM(require("fs"));
+var path8 = __toESM(require("path"));
+var StalenessGate = class {
+  constructor(config2) {
+    this.lastCheckTime = 0;
+    this.lastIndexTime = 0;
+    this.dataDirs = config2.dataDirs;
+    this.fileExtensions = new Set(config2.fileExtensions);
+    this.thresholdMs = config2.thresholdMs ?? 3e4;
+    this.isImmutable = config2.isImmutable ?? false;
+    this.onRebuild = config2.onRebuild;
+  }
+  /**
+   * Call before every data-returning tool.
+   * Returns true if a rebuild was triggered.
+   */
+  async checkAndRebuildIfNeeded() {
+    if (this.isImmutable) return false;
+    const now = Date.now();
+    if (now - this.lastCheckTime < this.thresholdMs) return false;
+    this.lastCheckTime = now;
+    const staleFiles = this.getStaleFiles();
+    if (staleFiles.length === 0) return false;
+    console.error("\u26A0\uFE0F Index stale \u2014 rebuilding...");
+    await this.onRebuild();
+    this.markIndexed();
+    return true;
+  }
+  /** Update lastIndexTime after successful index/rebuild. */
+  markIndexed() {
+    this.lastIndexTime = Date.now();
+  }
+  /** Get files newer than lastIndexTime. */
+  getStaleFiles() {
+    if (this.isImmutable) return [];
+    if (this.lastIndexTime === 0) return [];
+    const stale = [];
+    for (const dir of this.dataDirs) {
+      if (!fs10.existsSync(dir)) continue;
+      this.scanDir(dir, stale);
+    }
+    return stale;
+  }
+  scanDir(dir, stale) {
+    let entries;
+    try {
+      entries = fs10.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const fullPath = path8.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        this.scanDir(fullPath, stale);
+      } else if (this.fileExtensions.has(path8.extname(entry.name))) {
+        try {
+          const mtime = fs10.statSync(fullPath).mtimeMs;
+          if (mtime > this.lastIndexTime) {
+            stale.push(fullPath);
+          }
+        } catch {
+        }
+      }
+    }
+  }
+};
+function isImmutableContext(dataPath) {
+  return dataPath.includes("/node_modules/");
+}
+
 // application-mcp-server/src/indexer/ComponentIndexer.ts
+function mutableComponentRoots(roots) {
+  return roots.filter((r) => !isImmutableContext(r));
+}
+function normalizeRoots(componentsDir) {
+  const list = Array.isArray(componentsDir) ? componentsDir : [componentsDir];
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const r of list) {
+    if (!r) continue;
+    const abs = path9.resolve(r);
+    if (seen.has(abs)) continue;
+    seen.add(abs);
+    out.push(abs);
+  }
+  return out;
+}
+var LEGACY_LEVEL_DIR = "core";
 function tokenizeString(input) {
   if (!input) return [];
   const dehyphenated = input.replace(/[-_]+/g, " ");
@@ -17860,6 +18521,12 @@ var ComponentIndexer = class {
     this.layoutTemplateIndexer = new LayoutTemplateIndexer();
     this.tokenIndexer = new TokenIndexer();
     this.modeClassifier = new ModeClassifier();
+    /** The pass-1 root set, precedence order (consumer first, package last). */
+    this.componentRoots = [];
+    /** Declared component name → the precedence winner's source (Spec 123 C3: precedence keys on the DECLARED name). */
+    this.ownerByDeclaredName = /* @__PURE__ */ new Map();
+    /** Component directory → the index key (schema name) it produced — lets a reindex remove exactly its own entry. */
+    this.indexKeyByDir = /* @__PURE__ */ new Map();
     this.lastIndexTime = "";
     this.lastIndexTimeMs = 0;
     this.indexWarnings = [];
@@ -17868,44 +18535,72 @@ var ComponentIndexer = class {
     this.keywordIndex = /* @__PURE__ */ new Map();
   }
   /**
-   * Scan component directories and build initial index.
+   * Scan the component root set and build the index.
+   *
+   * `componentsDir` is the pass-1 ROOT SET in precedence order — consumer root first, package
+   * root last (Spec 123 C3; `resolveComponentRoots` produces it). A single string is the legacy
+   * single-root form. The union is applied AT PASS 1: the contracts cache is filled from every
+   * root before any component is assembled, so a consumer fork inheriting a package parent
+   * resolves (Req 2.5). Precedence keys on the DECLARED component name (the contracts
+   * `component` field; the schema `name` when a component has no contracts), never the
+   * directory name.
    */
-  async indexComponents(componentsDir, patternsDir, templatesDir, guidanceDir, tokenIndexDir) {
+  async indexComponents(componentsDir, patternsDir, templatesDir, guidanceDir, tokenIndexDir, options = {}) {
     this.index.clear();
     this.contractsCache.clear();
     this.keywordIndex.clear();
+    this.ownerByDeclaredName.clear();
+    this.indexKeyByDir.clear();
     this.indexWarnings = [];
-    this.dataDirs = [componentsDir, patternsDir, templatesDir, guidanceDir, tokenIndexDir].filter(Boolean);
-    if (!fs8.existsSync(componentsDir)) {
-      this.indexWarnings.push(`Components directory not found: ${componentsDir}`);
+    const roots = normalizeRoots(componentsDir);
+    this.componentRoots = roots;
+    const packageComponentsRoot = roots[roots.length - 1] ?? path9.resolve(String(componentsDir));
+    const legacyProjectRoot = path9.resolve(packageComponentsRoot, "..", "..", "..");
+    const projectRoot = options.projectRoot ? path9.resolve(options.projectRoot) : legacyProjectRoot;
+    this.bornRoot = projectRoot;
+    this.explicitTierDir = options.tierDir;
+    this.dataDirs = [...mutableComponentRoots(roots), patternsDir, templatesDir, guidanceDir, tokenIndexDir].filter(Boolean);
+    const existingRoots = roots.filter((r) => fs11.existsSync(r));
+    if (existingRoots.length === 0) {
+      for (const r of roots) this.indexWarnings.push(`Components directory not found: ${r}`);
       this.lastIndexTime = (/* @__PURE__ */ new Date()).toISOString();
       return;
     }
-    const dirs = fs8.readdirSync(componentsDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
-    for (const dir of dirs) {
-      const contractsPath = path7.join(componentsDir, dir, "contracts.yaml");
-      const contractsResult = parseContractsYaml(contractsPath);
+    const winners = [];
+    for (const source of this.collectComponentSources(roots)) {
+      const owner = this.ownerByDeclaredName.get(source.declaredName);
+      if (owner) {
+        if (owner.rank === source.rank) {
+          this.indexWarnings.push(
+            `Duplicate declared component name ${source.declaredName}: ${source.dirPath} is shadowed by ${owner.dirPath}`
+          );
+        }
+        continue;
+      }
+      this.ownerByDeclaredName.set(source.declaredName, { dirPath: source.dirPath, rank: source.rank });
+      winners.push(source);
+      const contractsResult = parseContractsYaml(path9.join(source.dirPath, "contracts.yaml"));
       if (contractsResult.data) {
         this.contractsCache.set(contractsResult.data.component, contractsResult.data);
       }
     }
-    const projectRoot = path7.resolve(componentsDir, "..", "..", "..");
-    this.modeClassifier.load(projectRoot);
-    for (const dir of dirs) {
-      this.assembleComponent(componentsDir, dir);
+    this.modeClassifier.load(projectRoot, tokenIndexDir, options.tierDir);
+    for (const source of winners) {
+      const key = this.assembleComponent(source.dirPath);
+      if (key) this.indexKeyByDir.set(source.dirPath, key);
     }
     this.resolveComposedTokens();
-    const effectivePatternsDir = patternsDir || path7.resolve(componentsDir, "..", "..", "..", "experience-patterns");
+    const effectivePatternsDir = patternsDir || path9.join(legacyProjectRoot, "experience-patterns");
     await this.patternIndexer.indexPatterns(effectivePatternsDir);
-    const effectiveTemplatesDir = templatesDir || path7.resolve(componentsDir, "..", "..", "..", "layout-templates");
+    const effectiveTemplatesDir = templatesDir || path9.join(legacyProjectRoot, "layout-templates");
     await this.layoutTemplateIndexer.indexTemplates(effectiveTemplatesDir);
-    const effectiveGuidanceDir = guidanceDir || path7.resolve(componentsDir, "..", "..", "..", "family-guidance");
+    const effectiveGuidanceDir = guidanceDir || path9.join(legacyProjectRoot, "family-guidance");
     await this.guidanceIndexer.indexGuidance(effectiveGuidanceDir);
     const componentNames = new Set(Array.from(this.index.keys()));
     const patternNames = new Set(this.patternIndexer.getCatalog().map((p) => p.name));
     this.guidanceIndexer.validateCrossReferences(componentNames, patternNames, projectRoot);
     if (tokenIndexDir) {
-      await this.tokenIndexer.indexTokens(tokenIndexDir);
+      await this.tokenIndexer.indexTokens(tokenIndexDir, projectRoot, options.tierDir);
     }
     this.lastIndexTime = (/* @__PURE__ */ new Date()).toISOString();
     this.lastIndexTimeMs = this.computeMaxMtime();
@@ -17914,7 +18609,7 @@ var ComponentIndexer = class {
   computeMaxMtime() {
     let max = 0;
     for (const dir of this.dataDirs) {
-      if (!fs8.existsSync(dir)) continue;
+      if (!fs11.existsSync(dir)) continue;
       this.walkMaxMtime(dir, (mtime) => {
         if (mtime > max) max = mtime;
       });
@@ -17924,41 +18619,55 @@ var ComponentIndexer = class {
   walkMaxMtime(dir, cb) {
     let entries;
     try {
-      entries = fs8.readdirSync(dir, { withFileTypes: true });
+      entries = fs11.readdirSync(dir, { withFileTypes: true });
     } catch {
       return;
     }
     for (const entry of entries) {
-      const fullPath = path7.join(dir, entry.name);
+      const fullPath = path9.join(dir, entry.name);
       if (entry.isDirectory()) {
         this.walkMaxMtime(fullPath, cb);
       } else {
         try {
-          cb(fs8.statSync(fullPath).mtimeMs);
+          cb(fs11.statSync(fullPath).mtimeMs);
         } catch {
         }
       }
     }
   }
   /**
-   * Re-index a single component after file change.
+   * Re-index a single component after a file change (watcher path).
+   *
+   * Precedence-aware (Spec 123 C3): a directory whose declared name is owned by a
+   * higher-precedence source is shadowed and left out; a consumer component ADDED over a
+   * package one of the same declared name replaces it. Only the entry this directory
+   * produced is removed first (the pre-123 removal loop deleted an arbitrary first entry —
+   * `path.basename(componentDir) === dir` was always true).
    */
   async reindexComponent(componentDir) {
-    const dir = path7.basename(componentDir);
-    const componentsDir = path7.dirname(componentDir);
-    const contractsPath = path7.join(componentDir, "contracts.yaml");
-    const contractsResult = parseContractsYaml(contractsPath);
+    const dirPath = path9.resolve(componentDir);
+    const rank = this.rankOf(dirPath);
+    const declaredName = this.declaredNameOf(dirPath);
+    const owner = this.ownerByDeclaredName.get(declaredName);
+    if (owner && owner.dirPath !== dirPath && owner.rank <= rank && fs11.existsSync(owner.dirPath)) {
+      return;
+    }
+    const oldKey = this.indexKeyByDir.get(dirPath);
+    if (oldKey !== void 0) {
+      this.index.delete(oldKey);
+      this.keywordIndex.delete(oldKey);
+      this.indexKeyByDir.delete(dirPath);
+    }
+    for (const [name, src] of this.ownerByDeclaredName) {
+      if (src.dirPath === dirPath) this.ownerByDeclaredName.delete(name);
+    }
+    const contractsResult = parseContractsYaml(path9.join(dirPath, "contracts.yaml"));
     if (contractsResult.data) {
       this.contractsCache.set(contractsResult.data.component, contractsResult.data);
     }
-    for (const [name, meta] of this.index) {
-      if (meta.name === dir || path7.basename(componentDir) === dir) {
-        this.index.delete(name);
-        this.keywordIndex.delete(name);
-        break;
-      }
-    }
-    this.assembleComponent(componentsDir, dir);
+    this.ownerByDeclaredName.set(declaredName, { dirPath, rank });
+    const key = this.assembleComponent(dirPath);
+    if (key) this.indexKeyByDir.set(dirPath, key);
     this.resolveComposedTokens();
     this.lastIndexTime = (/* @__PURE__ */ new Date()).toISOString();
   }
@@ -17980,9 +18689,19 @@ var ComponentIndexer = class {
     this.lastIndexTime = (/* @__PURE__ */ new Date()).toISOString();
     this.lastIndexTimeMs = this.computeMaxMtime();
   }
-  /** Re-index token data from the given directory. */
+  /**
+   * Re-index token data from the given directory (file-watcher path).
+   * Anchors on `bornRoot` — the explicit anchor the last full index was given (C3
+   * `projectRoot = bornRoot`) — so theme overrides resolve from the same place a full reindex
+   * uses (issue 2026-09-12). Never re-derived from a component root (Spec 123 Task 1.4 (iv)).
+   *
+   * Spec 123 Task 1.5 (DD24): `indexTokens` re-reads `<tokenIndexDir>/meta.json` on EVERY
+   * call (including this one), so a `generate` re-run that changes the recorded `tierDir`
+   * is picked up here too — the theme root "follows the served index," never a stale
+   * snapshot from the last full index.
+   */
   async reindexTokens(tokenIndexDir) {
-    await this.tokenIndexer.indexTokens(tokenIndexDir);
+    await this.tokenIndexer.indexTokens(tokenIndexDir, this.bornRoot, this.explicitTierDir);
     this.lastIndexTime = (/* @__PURE__ */ new Date()).toISOString();
     this.lastIndexTimeMs = this.computeMaxMtime();
   }
@@ -18043,7 +18762,7 @@ var ComponentIndexer = class {
     if (this.lastIndexTimeMs === 0) return [];
     const stale = [];
     for (const dir of this.dataDirs) {
-      if (!fs8.existsSync(dir)) continue;
+      if (!fs11.existsSync(dir)) continue;
       this.scanForStaleFiles(dir, stale);
     }
     return stale;
@@ -18051,17 +18770,17 @@ var ComponentIndexer = class {
   scanForStaleFiles(dir, stale) {
     let entries;
     try {
-      entries = fs8.readdirSync(dir, { withFileTypes: true });
+      entries = fs11.readdirSync(dir, { withFileTypes: true });
     } catch {
       return;
     }
     for (const entry of entries) {
-      const fullPath = path7.join(dir, entry.name);
+      const fullPath = path9.join(dir, entry.name);
       if (entry.isDirectory()) {
         this.scanForStaleFiles(fullPath, stale);
       } else if (entry.name.endsWith(".yaml") || entry.name.endsWith(".md") || entry.name.endsWith(".ts")) {
         try {
-          if (fs8.statSync(fullPath).mtimeMs > this.lastIndexTimeMs) {
+          if (fs11.statSync(fullPath).mtimeMs > this.lastIndexTimeMs) {
             stale.push(fullPath);
           }
         } catch {
@@ -18108,20 +18827,99 @@ var ComponentIndexer = class {
   // ---------------------------------------------------------------------------
   // Private
   // ---------------------------------------------------------------------------
-  assembleComponent(componentsDir, dir) {
-    const dirPath = path7.join(componentsDir, dir);
-    const schemaFile = fs8.readdirSync(dirPath).find((f) => f.endsWith(".schema.yaml"));
+  /**
+   * Collect every component directory across the root set, in precedence order.
+   * Under a root, a `core/` directory that holds component directories is recognized as ONE
+   * legacy level (L-D8 — the pre-123 copy layout), with a named warning on each load; its
+   * components rank with that root. A legacy level that IS another root in the set (the steward
+   * repo: `src/components/core` is the package root) is left to that root.
+   */
+  collectComponentSources(roots) {
+    const sources = [];
+    const rootSet = new Set(roots);
+    roots.forEach((root, rank) => {
+      if (!fs11.existsSync(root)) return;
+      const children = fs11.readdirSync(root, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
+      const legacyDirs = [];
+      for (const dir of children) {
+        const dirPath = path9.join(root, dir);
+        if (dir === LEGACY_LEVEL_DIR && !rootSet.has(dirPath)) {
+          const nested = fs11.readdirSync(dirPath, { withFileTypes: true }).filter((d) => d.isDirectory() && this.isComponentDir(path9.join(dirPath, d.name))).map((d) => d.name);
+          if (nested.length > 0 && !this.isComponentDir(dirPath)) {
+            legacyDirs.push(...nested);
+            continue;
+          }
+        }
+        if (dir === LEGACY_LEVEL_DIR && rootSet.has(dirPath)) continue;
+        sources.push({ dirPath, dir, rank, declaredName: this.declaredNameOf(dirPath) });
+      }
+      if (legacyDirs.length > 0) {
+        const legacyRoot = path9.join(root, LEGACY_LEVEL_DIR);
+        this.indexWarnings.push(
+          `Legacy component level: ${legacyRoot} holds ${legacyDirs.length} component(s) in the pre-123 'core/' layout \u2014 indexed as one legacy level; move them up to ${root}`
+        );
+        for (const dir of legacyDirs) {
+          const dirPath = path9.join(legacyRoot, dir);
+          sources.push({ dirPath, dir, rank, declaredName: this.declaredNameOf(dirPath) });
+        }
+      }
+    });
+    return sources;
+  }
+  /** A component directory holds a `*.schema.yaml` or a `contracts.yaml`. */
+  isComponentDir(dirPath) {
+    try {
+      const files = fs11.readdirSync(dirPath);
+      return files.some((f) => f.endsWith(".schema.yaml")) || files.includes("contracts.yaml");
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * The DECLARED component name of a directory — the contracts `component` field; the schema
+   * `name` when there are no contracts; the directory name only as a last resort (so the
+   * assembly step still reports the directory's own warning).
+   */
+  declaredNameOf(dirPath) {
+    const contracts = parseContractsYaml(path9.join(dirPath, "contracts.yaml")).data;
+    if (contracts?.component) return contracts.component;
+    try {
+      const schemaFile = fs11.readdirSync(dirPath).find((f) => f.endsWith(".schema.yaml"));
+      if (schemaFile) {
+        const schema2 = parseSchemaYaml(path9.join(dirPath, schemaFile)).data;
+        if (schema2?.name) return schema2.name;
+      }
+    } catch {
+    }
+    return path9.basename(dirPath);
+  }
+  /** Precedence rank of a component directory: the index of the longest root containing it. */
+  rankOf(dirPath) {
+    let best = -1;
+    let bestLen = -1;
+    this.componentRoots.forEach((root, i) => {
+      if ((dirPath === root || dirPath.startsWith(root + path9.sep)) && root.length > bestLen) {
+        best = i;
+        bestLen = root.length;
+      }
+    });
+    return best === -1 ? 0 : best;
+  }
+  /** Assemble one component directory into the index; returns its index key (schema name) or null. */
+  assembleComponent(dirPath) {
+    const dir = path9.basename(dirPath);
+    const schemaFile = fs11.readdirSync(dirPath).find((f) => f.endsWith(".schema.yaml"));
     if (!schemaFile) {
       this.indexWarnings.push(`Component directory has no schema.yaml: ${dir}`);
-      return;
+      return null;
     }
-    const schemaResult = parseSchemaYaml(path7.join(dirPath, schemaFile));
+    const schemaResult = parseSchemaYaml(path9.join(dirPath, schemaFile));
     if (!schemaResult.data) {
       if (schemaResult.warning) this.indexWarnings.push(schemaResult.warning);
-      return;
+      return null;
     }
     const schema2 = schemaResult.data;
-    const contractsResult = parseContractsYaml(path7.join(dirPath, "contracts.yaml"));
+    const contractsResult = parseContractsYaml(path9.join(dirPath, "contracts.yaml"));
     let contracts;
     const warnings = [];
     if (contractsResult.data) {
@@ -18138,7 +18936,7 @@ var ComponentIndexer = class {
       if (contractsResult.warning) warnings.push(contractsResult.warning);
       contracts = { inheritsFrom: null, active: {}, excluded: {}, own: [], inherited: [] };
     }
-    const metaResult = parseComponentMetaYaml(path7.join(dirPath, "component-meta.yaml"));
+    const metaResult = parseComponentMetaYaml(path9.join(dirPath, "component-meta.yaml"));
     if (schema2.omits.length > 0) {
       const parentName = contracts.inheritsFrom;
       const parentMeta = parentName ? this.index.get(parentName) : null;
@@ -18177,6 +18975,7 @@ var ComponentIndexer = class {
     };
     this.index.set(schema2.name, metadata);
     this.buildKeywordEntry(schema2.name, metadata);
+    return schema2.name;
   }
   /**
    * Build the per-component keyword index entry.
@@ -18227,9 +19026,9 @@ var ComponentIndexer = class {
    * Design Decision 4 (Spec 086).
    */
   derivePlatformReadiness(componentDir, schemaReadiness) {
-    const hasSchema = fs8.readdirSync(componentDir).some((f) => f.endsWith(".schema.yaml"));
-    const hasContracts = fs8.existsSync(path7.join(componentDir, "contracts.yaml"));
-    const hasTypes = fs8.existsSync(path7.join(componentDir, "types.ts"));
+    const hasSchema = fs11.readdirSync(componentDir).some((f) => f.endsWith(".schema.yaml"));
+    const hasContracts = fs11.existsSync(path9.join(componentDir, "contracts.yaml"));
+    const hasTypes = fs11.existsSync(path9.join(componentDir, "types.ts"));
     const baselineComplete = hasSchema && hasContracts && hasTypes;
     const platforms = [
       { key: "web", implPattern: /\.web\.ts$/, testPatterns: [/\.test\.ts$/] },
@@ -18245,10 +19044,10 @@ var ComponentIndexer = class {
         result[p.key] = { status: "not-applicable", reason: naReason, reviewed: false, hasImplementation: false, hasTests: false };
         continue;
       }
-      const platformDir = path7.join(componentDir, "platforms", p.key);
-      const hasImpl = fs8.existsSync(platformDir) && fs8.readdirSync(platformDir).some((f) => p.implPattern.test(f));
-      const testsDir = path7.join(componentDir, "__tests__");
-      const hasTests = fs8.existsSync(platformDir) && fs8.readdirSync(platformDir).some((f) => p.testPatterns.some((tp) => tp.test(f))) || fs8.existsSync(testsDir) && fs8.readdirSync(testsDir).some((f) => p.testPatterns.some((tp) => tp.test(f)));
+      const platformDir = path9.join(componentDir, "platforms", p.key);
+      const hasImpl = fs11.existsSync(platformDir) && fs11.readdirSync(platformDir).some((f) => p.implPattern.test(f));
+      const testsDir = path9.join(componentDir, "__tests__");
+      const hasTests = fs11.existsSync(platformDir) && fs11.readdirSync(platformDir).some((f) => p.testPatterns.some((tp) => tp.test(f))) || fs11.existsSync(testsDir) && fs11.readdirSync(testsDir).some((f) => p.testPatterns.some((tp) => tp.test(f)));
       let status;
       if (!hasImpl) {
         status = "not-started";
@@ -18712,17 +19511,17 @@ var AssemblyValidator = class {
       accessibility
     };
   }
-  walk(node, path10, errors, warnings) {
+  walk(node, path11, errors, warnings) {
     const meta = this.indexer.getComponent(node.component);
     if (!meta) {
-      errors.push({ path: path10, component: node.component, message: `Component "${node.component}" not found in catalog` });
+      errors.push({ path: path11, component: node.component, message: `Component "${node.component}" not found in catalog` });
       return;
     }
     const children = node.children ?? [];
     const index = this.indexer.getIndex();
     for (let i = 0; i < children.length; i++) {
       const child = children[i];
-      const childPath = `${path10}.children[${i}]`;
+      const childPath = `${path11}.children[${i}]`;
       const result = checkComposition(meta, child.component, index, node.props);
       if (!result.allowed) {
         errors.push({ path: childPath, component: child.component, message: result.reason });
@@ -18731,31 +19530,30 @@ var AssemblyValidator = class {
     const childNames = children.map((c) => c.component);
     const req = validateRequires(meta, childNames);
     if (!req.complete) {
-      errors.push({ path: path10, component: node.component, message: `Missing required children: ${req.missing.join(", ")}` });
+      errors.push({ path: path11, component: node.component, message: `Missing required children: ${req.missing.join(", ")}` });
     }
     const comp = meta.composition;
     if (comp?.children && children.length > 0) {
       if (comp.children.minCount !== void 0 && children.length < comp.children.minCount) {
-        errors.push({ path: path10, component: node.component, message: `Requires at least ${comp.children.minCount} children, found ${children.length}` });
+        errors.push({ path: path11, component: node.component, message: `Requires at least ${comp.children.minCount} children, found ${children.length}` });
       }
       if (comp.children.maxCount !== void 0 && children.length > comp.children.maxCount) {
-        errors.push({ path: path10, component: node.component, message: `Allows at most ${comp.children.maxCount} children, found ${children.length}` });
+        errors.push({ path: path11, component: node.component, message: `Allows at most ${comp.children.maxCount} children, found ${children.length}` });
       }
     }
     for (let i = 0; i < children.length; i++) {
-      this.walk(children[i], `${path10}.children[${i}]`, errors, warnings);
+      this.walk(children[i], `${path11}.children[${i}]`, errors, warnings);
     }
   }
 };
 
 // application-mcp-server/src/watcher/FileWatcher.ts
-var fs9 = __toESM(require("fs"));
-var path8 = __toESM(require("path"));
+var fs12 = __toESM(require("fs"));
+var path10 = __toESM(require("path"));
 var COMPONENT_FILES = /* @__PURE__ */ new Set(["contracts.yaml", "component-meta.yaml"]);
 var FileWatcher = class {
   constructor(indexer, componentsDir, patternsDir, templatesDir, guidanceDir, tokenIndexDir, debounceMs = 100) {
     this.indexer = indexer;
-    this.componentsDir = componentsDir;
     this.patternsDir = patternsDir;
     this.templatesDir = templatesDir;
     this.guidanceDir = guidanceDir;
@@ -18763,20 +19561,26 @@ var FileWatcher = class {
     this.debounceMs = debounceMs;
     this.watchers = [];
     this.debounceTimers = /* @__PURE__ */ new Map();
+    this.componentsDirs = (Array.isArray(componentsDir) ? componentsDir : [componentsDir]).filter(Boolean);
+  }
+  /** The component roots this watcher watches (the mutable set it was given). */
+  getWatchedComponentRoots() {
+    return [...this.componentsDirs];
   }
   start() {
     this.stop();
-    const configs = [
-      { dir: this.componentsDir, handler: (f) => this.handleComponentChange(f) }
-    ];
+    const configs = this.componentsDirs.map((root) => ({
+      dir: root,
+      handler: (f) => this.handleComponentChange(root, f)
+    }));
     if (this.patternsDir) configs.push({ dir: this.patternsDir, handler: () => this.debounceReindex("patterns", () => this.indexer.reindexPatterns(this.patternsDir)) });
     if (this.templatesDir) configs.push({ dir: this.templatesDir, handler: () => this.debounceReindex("templates", () => this.indexer.reindexTemplates(this.templatesDir)) });
     if (this.guidanceDir) configs.push({ dir: this.guidanceDir, handler: () => this.debounceReindex("guidance", () => this.indexer.reindexGuidance(this.guidanceDir)) });
     if (this.tokenIndexDir) configs.push({ dir: this.tokenIndexDir, handler: () => this.debounceReindex("tokens", () => this.indexer.reindexTokens(this.tokenIndexDir)) });
     for (const config2 of configs) {
-      if (!fs9.existsSync(config2.dir)) continue;
+      if (!fs12.existsSync(config2.dir)) continue;
       try {
-        const watcher = fs9.watch(config2.dir, { recursive: true }, (_event, filename) => {
+        const watcher = fs12.watch(config2.dir, { recursive: true }, (_event, filename) => {
           if (filename && filename.endsWith(".yaml")) config2.handler(filename);
         });
         watcher.on("error", (err) => console.error(`FileWatcher error (${config2.dir}): ${err.message}`));
@@ -18796,10 +19600,10 @@ var FileWatcher = class {
   isWatching() {
     return this.watchers.length > 0;
   }
-  handleComponentChange(filename) {
-    const base = path8.basename(filename);
+  handleComponentChange(root, filename) {
+    const base = path10.basename(filename);
     if (!base.endsWith(".schema.yaml") && !COMPONENT_FILES.has(base)) return;
-    const componentDir = path8.join(this.componentsDir, path8.dirname(filename));
+    const componentDir = path10.join(root, path10.dirname(filename));
     this.debounceReindex(componentDir, () => this.indexer.reindexComponent(componentDir));
   }
   debounceReindex(key, action) {
@@ -18819,7 +19623,7 @@ var FileWatcher = class {
 };
 
 // application-mcp-server/src/indexer/DesignPhilosophyIndexer.ts
-var fs10 = __toESM(require("fs"));
+var fs13 = __toESM(require("fs"));
 var DesignPhilosophyIndexer = class {
   constructor() {
     this.data = null;
@@ -18828,12 +19632,12 @@ var DesignPhilosophyIndexer = class {
   async index(filePath) {
     this.data = null;
     this.warnings = [];
-    if (!fs10.existsSync(filePath)) {
+    if (!fs13.existsSync(filePath)) {
       this.warnings.push(`Design philosophy file not found: ${filePath}`);
       return;
     }
     try {
-      const content = fs10.readFileSync(filePath, "utf-8");
+      const content = fs13.readFileSync(filePath, "utf-8");
       this.data = load(content);
       this.validate();
     } catch (err) {
@@ -18880,77 +19684,6 @@ var DesignPhilosophyIndexer = class {
   }
 };
 
-// application-mcp-server/src/staleness/StalenessGate.ts
-var fs11 = __toESM(require("fs"));
-var path9 = __toESM(require("path"));
-var StalenessGate = class {
-  constructor(config2) {
-    this.lastCheckTime = 0;
-    this.lastIndexTime = 0;
-    this.dataDirs = config2.dataDirs;
-    this.fileExtensions = new Set(config2.fileExtensions);
-    this.thresholdMs = config2.thresholdMs ?? 3e4;
-    this.isImmutable = config2.isImmutable ?? false;
-    this.onRebuild = config2.onRebuild;
-  }
-  /**
-   * Call before every data-returning tool.
-   * Returns true if a rebuild was triggered.
-   */
-  async checkAndRebuildIfNeeded() {
-    if (this.isImmutable) return false;
-    const now = Date.now();
-    if (now - this.lastCheckTime < this.thresholdMs) return false;
-    this.lastCheckTime = now;
-    const staleFiles = this.getStaleFiles();
-    if (staleFiles.length === 0) return false;
-    console.error("\u26A0\uFE0F Index stale \u2014 rebuilding...");
-    await this.onRebuild();
-    this.markIndexed();
-    return true;
-  }
-  /** Update lastIndexTime after successful index/rebuild. */
-  markIndexed() {
-    this.lastIndexTime = Date.now();
-  }
-  /** Get files newer than lastIndexTime. */
-  getStaleFiles() {
-    if (this.isImmutable) return [];
-    if (this.lastIndexTime === 0) return [];
-    const stale = [];
-    for (const dir of this.dataDirs) {
-      if (!fs11.existsSync(dir)) continue;
-      this.scanDir(dir, stale);
-    }
-    return stale;
-  }
-  scanDir(dir, stale) {
-    let entries;
-    try {
-      entries = fs11.readdirSync(dir, { withFileTypes: true });
-    } catch {
-      return;
-    }
-    for (const entry of entries) {
-      const fullPath = path9.join(dir, entry.name);
-      if (entry.isDirectory()) {
-        this.scanDir(fullPath, stale);
-      } else if (this.fileExtensions.has(path9.extname(entry.name))) {
-        try {
-          const mtime = fs11.statSync(fullPath).mtimeMs;
-          if (mtime > this.lastIndexTime) {
-            stale.push(fullPath);
-          }
-        } catch {
-        }
-      }
-    }
-  }
-};
-function isImmutableContext(dataPath) {
-  return dataPath.includes("/node_modules/");
-}
-
 // application-mcp-server/src/index.ts
 var SERVER_NAME = "mcp-component-server";
 var SERVER_VERSION = "0.1.0";
@@ -18959,11 +19692,13 @@ var DEFAULT_TOKEN_INDEX_DIR = "token-index";
 var tools = [
   {
     name: "get_component_catalog",
+    annotations: { readOnlyHint: true },
     description: "Get lightweight catalog of all components with name, type, family, purpose, and readiness. ~50 tokens per component.",
     inputSchema: { type: "object", properties: {} }
   },
   {
     name: "get_component_summary",
+    annotations: { readOnlyHint: true },
     description: "Get component summary: identity, contract categories, token count, annotations. ~200 tokens.",
     inputSchema: {
       type: "object",
@@ -18973,6 +19708,7 @@ var tools = [
   },
   {
     name: "get_component_full",
+    annotations: { readOnlyHint: true },
     description: "Get complete assembled metadata including all contracts, composition rules, and token relationships.",
     inputSchema: {
       type: "object",
@@ -18982,6 +19718,7 @@ var tools = [
   },
   {
     name: "find_components",
+    annotations: { readOnlyHint: true },
     description: 'Find components by category, concept, platform, purpose keyword, or usage context. Returns ApplicationSummary with promoted selection guidance (purpose, whenToUse, whenNotToUse, alternatives, contexts). All parameters optional and combinable (conjunctive). Use `keyword` for natural-language tokenized discovery (e.g. "primary action button", "login", "text input field").',
     inputSchema: {
       type: "object",
@@ -18998,6 +19735,7 @@ var tools = [
   },
   {
     name: "check_composition",
+    annotations: { readOnlyHint: true },
     description: "Check if a parent component can contain a child component, with optional prop context.",
     inputSchema: {
       type: "object",
@@ -19011,21 +19749,25 @@ var tools = [
   },
   {
     name: "get_component_health",
+    annotations: { readOnlyHint: true },
     description: "Get index health: status, component count, pattern count, warnings, gaps.",
     inputSchema: { type: "object", properties: {} }
   },
   {
     name: "rebuild_index",
+    annotations: { readOnlyHint: false },
     description: "Rebuild the component index from scratch. Use when index is stale or out of sync. Returns new health status after reindex.",
     inputSchema: { type: "object", properties: {} }
   },
   {
     name: "list_experience_patterns",
+    annotations: { readOnlyHint: true },
     description: "List all experience patterns with name, description, category, tags, step count, and component count.",
     inputSchema: { type: "object", properties: {} }
   },
   {
     name: "get_experience_pattern",
+    annotations: { readOnlyHint: true },
     description: "Get full experience pattern by name: steps, components with roles and hints, accessibility notes, and alternatives.",
     inputSchema: {
       type: "object",
@@ -19035,11 +19777,13 @@ var tools = [
   },
   {
     name: "list_layout_templates",
+    annotations: { readOnlyHint: true },
     description: "List all layout templates with name, description, category, tags, and region count.",
     inputSchema: { type: "object", properties: {} }
   },
   {
     name: "get_layout_template",
+    annotations: { readOnlyHint: true },
     description: "Get full layout template by name: regions with grid behavior per breakpoint, stacking rules, and token references.",
     inputSchema: {
       type: "object",
@@ -19049,6 +19793,7 @@ var tools = [
   },
   {
     name: "validate_assembly",
+    annotations: { readOnlyHint: true },
     description: "Validate a component tree. Checks component existence, parent-child composition rules, requires/count constraints, and assembly-level accessibility (form labels, submit actions, page headings). Returns errors, warnings, and accessibility issues with paths.",
     inputSchema: {
       type: "object",
@@ -19063,6 +19808,7 @@ var tools = [
   },
   {
     name: "get_prop_guidance",
+    annotations: { readOnlyHint: true },
     description: "Get prop selection and family member guidance for a component or family. Returns whenToUse, whenNotToUse, selectionRules (scenario\u2192recommendation with optional props), accessibilityNotes, and family-scoped patterns. Query by component name (returns its family guidance) or family name.",
     inputSchema: {
       type: "object",
@@ -19076,6 +19822,7 @@ var tools = [
   // Token query tools (Spec 096)
   {
     name: "search_tokens",
+    annotations: { readOnlyHint: true },
     description: "Search tokens by family, tier (primitive/semantic/component), or name. All parameters optional and combinable.",
     inputSchema: {
       type: "object",
@@ -19088,6 +19835,7 @@ var tools = [
   },
   {
     name: "get_token_details",
+    annotations: { readOnlyHint: true },
     description: "Get full details for a token: value, family, tier, platform names, formula, theme-varying status, consumers.",
     inputSchema: {
       type: "object",
@@ -19099,6 +19847,7 @@ var tools = [
   },
   {
     name: "get_token_family",
+    annotations: { readOnlyHint: true },
     description: "Get all tokens in a family across all tiers.",
     inputSchema: {
       type: "object",
@@ -19110,6 +19859,7 @@ var tools = [
   },
   {
     name: "get_token_consumers",
+    annotations: { readOnlyHint: true },
     description: "Get all components that reference a token.",
     inputSchema: {
       type: "object",
@@ -19121,16 +19871,19 @@ var tools = [
   },
   {
     name: "get_design_philosophy",
+    annotations: { readOnlyHint: true },
     description: "Get the design system's creative north star, aesthetic philosophy, and key characteristics.",
     inputSchema: { type: "object", properties: {} }
   },
   {
     name: "get_design_rules",
+    annotations: { readOnlyHint: true },
     description: "Get named design rules as structured data (name, constraint, rationale).",
     inputSchema: { type: "object", properties: {} }
   },
   {
     name: "get_design_guidance",
+    annotations: { readOnlyHint: true },
     description: "Get design do's and don'ts as categorized directives. Optionally filter by category.",
     inputSchema: {
       type: "object",
@@ -19141,6 +19894,7 @@ var tools = [
   },
   {
     name: "get_color_strategy",
+    annotations: { readOnlyHint: true },
     description: "Get color strategy vocabulary (Restrained/Committed/Full/Drenched) with usage guidance. Optionally filter by tier.",
     inputSchema: {
       type: "object",
@@ -19154,54 +19908,52 @@ var STALENESS_EXEMPT_TOOLS = /* @__PURE__ */ new Set([
   "get_component_health",
   "rebuild_index"
 ]);
-function createTestableServer(paths) {
-  const server = new ComponentMCPServer(paths);
+function createTestableServer(paths, options = {}) {
+  const server = new ComponentMCPServer(paths, options);
   return {
-    initialize: () => server.indexer.indexComponents(
-      paths.componentsDir,
-      paths.patternsDir,
-      paths.templatesDir,
-      paths.guidanceDir,
-      paths.tokenIndexDir
-    ),
-    callTool: (name, args) => server.handleTool(name, args)
+    initialize: async () => {
+      await server.fullIndex();
+      server.markIndexed();
+    },
+    callTool: (name, args) => server.handleTool(name, args),
+    startWatching: () => server.startWatching(),
+    stopWatching: () => server.stopWatching(),
+    getWatchedDirs: () => server.getWatchedDirs()
   };
 }
 var ComponentMCPServer = class {
-  constructor(paths) {
+  constructor(paths, options = {}) {
     this.paths = paths;
     this.server = new Server({ name: SERVER_NAME, version: SERVER_VERSION }, { capabilities: { tools: {} } });
     this.indexer = new ComponentIndexer();
     this.queryEngine = new ComponentQueryEngine(this.indexer);
     this.assemblyValidator = new AssemblyValidator(this.indexer);
+    const componentRoots = Array.isArray(this.paths.componentsDir) ? this.paths.componentsDir : [this.paths.componentsDir];
+    this.watchedComponentRoots = mutableComponentRoots(componentRoots);
     this.fileWatcher = new FileWatcher(
       this.indexer,
-      this.paths.componentsDir,
+      this.watchedComponentRoots,
       this.paths.patternsDir,
       this.paths.templatesDir,
       this.paths.guidanceDir,
       this.paths.tokenIndexDir
     );
     this.philosophyIndexer = new DesignPhilosophyIndexer();
-    const dataDirs = [
-      this.paths.componentsDir,
+    const otherDirs = [
       this.paths.patternsDir,
       this.paths.templatesDir,
       this.paths.guidanceDir,
       this.paths.tokenIndexDir
-    ].filter(Boolean);
+    ].filter((d) => Boolean(d) && !isImmutableContext(d));
+    this.stalenessDataDirs = [...this.watchedComponentRoots, ...otherDirs];
     this.stalenessGate = new StalenessGate({
-      dataDirs,
+      dataDirs: this.stalenessDataDirs,
       fileExtensions: [".yaml", ".ts", ".md"],
-      isImmutable: isImmutableContext(this.paths.componentsDir),
+      thresholdMs: options.stalenessThresholdMs,
+      // Nothing mutable to scan (e.g. an unborn consumer: everything is package data) → skip all checks.
+      isImmutable: this.stalenessDataDirs.length === 0,
       onRebuild: async () => {
-        await this.indexer.indexComponents(
-          this.paths.componentsDir,
-          this.paths.patternsDir,
-          this.paths.templatesDir,
-          this.paths.guidanceDir,
-          this.paths.tokenIndexDir
-        );
+        await this.fullIndex();
         if (this.paths.designLanguagePath) {
           await this.philosophyIndexer.index(this.paths.designLanguagePath);
         }
@@ -19209,14 +19961,38 @@ var ComponentMCPServer = class {
     });
     this.registerHandlers();
   }
-  async start() {
+  /** Full index over the component root set, anchored on `projectRoot` (C3 `projectRoot = bornRoot`). */
+  async fullIndex() {
     await this.indexer.indexComponents(
       this.paths.componentsDir,
       this.paths.patternsDir,
       this.paths.templatesDir,
       this.paths.guidanceDir,
-      this.paths.tokenIndexDir
+      this.paths.tokenIndexDir,
+      { projectRoot: this.paths.projectRoot }
     );
+  }
+  /** @internal Test seam (Spec 123 Task 1.4). */
+  markIndexed() {
+    this.stalenessGate.markIndexed();
+  }
+  /** @internal Test seam (Spec 123 Task 1.4). */
+  startWatching() {
+    this.fileWatcher.start();
+  }
+  /** @internal Test seam (Spec 123 Task 1.4). */
+  stopWatching() {
+    this.fileWatcher.stop();
+  }
+  /** @internal Test seam (Spec 123 Task 1.4). */
+  getWatchedDirs() {
+    return {
+      stalenessDataDirs: [...this.stalenessDataDirs],
+      watchedComponentRoots: this.fileWatcher.getWatchedComponentRoots()
+    };
+  }
+  async start() {
+    await this.fullIndex();
     this.fileWatcher.start();
     if (this.paths.tokenIndexDir) {
       const th = this.indexer.getTokenIndexer().getHealth();
@@ -19224,9 +20000,6 @@ var ComponentMCPServer = class {
     }
     const health = this.indexer.getHealth();
     console.error(`[${SERVER_NAME}] Indexed ${health.componentsIndexed} components (${health.warnings.length} warnings)`);
-    if (!this.paths.tokenIndexDir) {
-      console.error(`[${SERVER_NAME}] Token index not available (Spec 096 pending)`);
-    }
     if (this.paths.designLanguagePath) {
       await this.philosophyIndexer.index(this.paths.designLanguagePath);
       const pw = this.philosophyIndexer.getWarnings();
@@ -19300,13 +20073,7 @@ var ComponentMCPServer = class {
       case "get_component_health":
         return this.queryEngine.getHealth();
       case "rebuild_index":
-        await this.indexer.indexComponents(
-          this.paths.componentsDir,
-          this.paths.patternsDir,
-          this.paths.templatesDir,
-          this.paths.guidanceDir,
-          this.paths.tokenIndexDir
-        );
+        await this.fullIndex();
         if (this.paths.designLanguagePath) {
           await this.philosophyIndexer.index(this.paths.designLanguagePath);
         }
@@ -19364,6 +20131,16 @@ var ComponentMCPServer = class {
     });
   }
 };
+function resolveTokenIndexUnavailableMessage(reason, dsRoot, packageRoot, errorCatalog, explicitTokenIndexDirEnv) {
+  switch (reason) {
+    case "empty-env-value":
+      return errorCatalog.explicitTokenIndexMissingMessage(explicitTokenIndexDirEnv ?? "");
+    case "run-generate":
+      return dsRoot.state === "package-mode" ? errorCatalog.packageModeIndexAbsentMessage() : errorCatalog.bornIndexAbsentMessage(dsRoot.root ?? packageRoot);
+    case "partial":
+      return dsRoot.partialCase ? errorCatalog.partialCaseMessage(dsRoot.root ?? packageRoot, dsRoot.partialCase, dsRoot.attemptedTokenSource) : `token index unavailable: partial state with no named sub-case`;
+  }
+}
 if (require.main === module) {
   const logRoot = (label, root, note = "") => {
     console.error(`[${SERVER_NAME}] Data root ${label}: ${root.path} (source: ${root.source})${note}`);
@@ -19371,15 +20148,19 @@ if (require.main === module) {
   let dataPaths;
   try {
     const shared = require_mcpDataRoots();
+    const bornRepo = require_bornRepo();
+    const errorCatalog = require_errorCatalog();
     const packageRoot = shared.resolvePackageRoot(__dirname);
-    const components = shared.resolveConsumerOwnedRoot({
-      envValue: process.env.COMPONENTS_DIR,
-      relPath: DEFAULT_COMPONENTS_DIR,
+    const dsRoot = bornRepo.findDesignSystemRoot(process.cwd());
+    const componentRoots = shared.resolveComponentRoots({
+      envValue: process.env.COMPONENTS_DIR || process.env.COMPONENT_DIR,
+      dsRoot,
       packageRoot
     });
-    const tokenIndex = shared.resolveConsumerOwnedRoot({
+    const projectRoot = dsRoot.root ?? packageRoot;
+    const tokenIndex = shared.resolveTokenIndexRoot({
       envValue: process.env.TOKEN_INDEX_DIR,
-      relPath: DEFAULT_TOKEN_INDEX_DIR,
+      dsRoot,
       packageRoot
     });
     const patterns = shared.resolvePackageOwnedRoot({
@@ -19407,24 +20188,42 @@ if (require.main === module) {
       packageRoot,
       relPath: "design-language/design-philosophy.yaml"
     });
-    logRoot("components", components);
-    logRoot(
-      "token-index",
-      tokenIndex,
-      tokenIndex.source === "package" ? " \u2014 package token snapshot in use; if this project customizes tokens, run 'npx designerpunk generate' to build a local token-index" : ""
+    console.error(`[${SERVER_NAME}] Design-system root: ${dsRoot.state}${dsRoot.partialCase ? ` (${dsRoot.partialCase})` : ""}`);
+    console.error(
+      `[${SERVER_NAME}] Project root: ${projectRoot} (source: ${dsRoot.root ? dsRoot.state : "unborn \u2192 package"})`
     );
+    componentRoots.roots.forEach((root, i) => {
+      logRoot(`components[${i}]`, { path: root, source: componentRoots.sources[i] });
+    });
+    if (tokenIndex.ok) {
+      logRoot(
+        "token-index",
+        { path: tokenIndex.path, source: tokenIndex.source },
+        tokenIndex.tokenOrigin ? ` (tokenOrigin: ${tokenIndex.tokenOrigin})` : ""
+      );
+    } else {
+      const tokenIndexMessage = resolveTokenIndexUnavailableMessage(
+        tokenIndex.reason,
+        dsRoot,
+        packageRoot,
+        errorCatalog,
+        process.env.TOKEN_INDEX_DIR
+      );
+      console.error(`[${SERVER_NAME}] ${tokenIndexMessage}`);
+    }
     logRoot("experience-patterns", patterns);
     logRoot("layout-templates", templates);
     logRoot("family-guidance", guidance);
     logRoot("family-registry", registry2);
     logRoot("design-language", designLanguage);
     dataPaths = {
-      componentsDir: components.path,
+      componentsDir: componentRoots.roots,
+      projectRoot,
       patternsDir: patterns.path,
       templatesDir: templates.path,
       guidanceDir: guidance.path,
       registryPath: registry2.path,
-      tokenIndexDir: tokenIndex.path,
+      tokenIndexDir: tokenIndex.ok ? tokenIndex.path : void 0,
       designLanguagePath: designLanguage.path
     };
   } catch {
@@ -19449,7 +20248,9 @@ if (require.main === module) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  createTestableServer
+  createTestableServer,
+  resolveTokenIndexUnavailableMessage,
+  tools
 });
 /*! Bundled license information: