@contentful/experience-design-system-cli 2.35.1-dev-build-a2149178.0 → 2.35.1-dev-build-925d6206.0

package/legacy/dist/src/index.js

@@ -164,11 +164,12 @@ var init_render_with_goodbye = __esm({
 function isAgentName(value) {
   return AGENT_NAMES.includes(value);
 }
-var AGENT_NAMES, AGENT_BINARIES;
+var AGENT_NAMES, DEFAULT_AGENT_NAME, AGENT_BINARIES;
 var init_agent_names = __esm({
   "packages/experience-design-system-generation/dist/src/agent-names.js"() {
     "use strict";
     AGENT_NAMES = ["claude", "codex", "opencode", "cursor", "copilot"];
+    DEFAULT_AGENT_NAME = "claude";
     AGENT_BINARIES = {
       claude: "claude",
       codex: "codex",
@@ -180,6 +181,23 @@ var init_agent_names = __esm({
 });
 
 // packages/experience-design-system-generation/dist/src/controller/helpers/validate-generation-request.js
+function validateGenerationRequest(request2) {
+  if (request2 === null || typeof request2 !== "object") {
+    throw new TypeError("createGenerationEndpoint requires a request object");
+  }
+  if (!isAgentName(request2.agent)) {
+    throw new TypeError(`createGenerationEndpoint requires agent to be a valid agent name, got: ${String(request2.agent)}`);
+  }
+  if (typeof request2.timeoutMs !== "number" || request2.timeoutMs <= 0) {
+    throw new TypeError("createGenerationEndpoint requires timeoutMs to be a positive number");
+  }
+  if (request2.promptOptions === null || typeof request2.promptOptions !== "object") {
+    throw new TypeError("createGenerationEndpoint requires promptOptions to be an object");
+  }
+  if (request2.onOutput !== void 0 && typeof request2.onOutput !== "function") {
+    throw new TypeError("createGenerationEndpoint requires onOutput to be a function when provided");
+  }
+}
 var init_validate_generation_request = __esm({
   "packages/experience-design-system-generation/dist/src/controller/helpers/validate-generation-request.js"() {
     "use strict";
@@ -238,7 +256,6 @@ var init_resolve_skill_file = __esm({
       components: "generate-components.md",
       tokens: "generate-tokens.md",
       select: "select-components.md",
-      "debate-select": "debate-select.md",
       "map-tokens": "map-tokens.md"
     };
   }
@@ -500,31 +517,6 @@ Rules:
 - Emit set_group calls before the set_token calls that fall under them.
 - You may emit prose lines (not starting with {) anywhere \u2014 they are ignored by the parser and serve as your reasoning log.`;
 }
-function buildDebateSelectAutonomousPreamble(inputBlock, debateRole, disagreementInline) {
-  const role = debateRole ?? "for";
-  return [
-    "You are the " + role.toUpperCase() + " participant in an adversarial review of one component-selection disagreement. This is an automatic escalation stage; do not ask the developer for confirmation.",
-    "",
-    "Your role is to argue the " + role.toUpperCase() + " position on the exact disagreement below. Address the claim literally, cite the supplied component evidence, and do not substitute a nearby component or field. The opposing participant is evaluating the same evidence independently.",
-    "",
-    "Component and source data:" + inputBlock,
-    "",
-    "Disagreement under review (JSON):",
-    "~~~json",
-    disagreementInline ?? "{}",
-    "~~~",
-    "",
-    "## Output protocol",
-    "",
-    "Emit exactly one JSON object on one line and do not write files:",
-    "",
-    "~~~json",
-    '{"role":"' + role + '","disagreement_id":"<id>","argument":"<position and reasoning>","evidence":[{"source":"<path>","line":"<line-or-range>","quote":"<verbatim evidence>"}]}',
-    "~~~",
-    "",
-    "The role and disagreement_id must match the values in this prompt. Use an empty evidence array only when the supplied context contains no citable source evidence."
-  ].join("\n");
-}
 var init_build_skill_preambles = __esm({
   "packages/experience-design-system-generation/dist/src/services/prompts/helpers/build-skill-preambles.js"() {
     "use strict";
@@ -533,7 +525,7 @@ var init_build_skill_preambles = __esm({
 
 // packages/experience-design-system-generation/dist/src/services/prompts/helpers/build-preamble.js
 function buildPreamble(options) {
-  const { skill, rawComponentsInline, propBucketsInline, rawTokensInline, rawTokensFilename, tokensInline, tokenMapInline, generatedCdf, tokenTree, componentSourceRefs, existingComponentsInline, existingTokensInline, componentAllowlistInline, debateRole, disagreementInline } = options;
+  const { skill, rawComponentsInline, propBucketsInline, rawTokensInline, rawTokensFilename, tokensInline, tokenMapInline, generatedCdf, tokenTree, componentSourceRefs, existingComponentsInline, existingTokensInline, componentAllowlistInline } = options;
   const sections = [];
   if (existingComponentsInline) {
     sections.push(`Existing components in the target Contentful space (JSON) \u2014 use for alignment, not as a hard filter:
@@ -605,8 +597,6 @@ ${sections.join("\n\n")}` : "";
     return buildComponentsAutonomousPreamble(inputBlock);
   if (skill === "select")
     return buildSelectAutonomousPreamble(inputBlock);
-  if (skill === "debate-select")
-    return buildDebateSelectAutonomousPreamble(inputBlock, debateRole, disagreementInline);
   if (skill === "map-tokens")
     return buildMapTokensAutonomousPreamble(inputBlock);
   return buildTokensAutonomousPreamble(inputBlock);
@@ -640,6 +630,17 @@ var init_build_prompt = __esm({
 });
 
 // packages/experience-design-system-generation/dist/src/orchestrator/execute-generation-orchestrator.js
+async function executeGenerationOrchestrator(request2) {
+  const prompt = await buildPrompt(request2.promptOptions);
+  return request2.invoker.invoke({
+    agent: request2.agent,
+    model: request2.model,
+    bedrock: request2.bedrock,
+    prompt,
+    timeoutMs: request2.timeoutMs,
+    onOutput: request2.onOutput
+  });
+}
 var init_execute_generation_orchestrator = __esm({
   "packages/experience-design-system-generation/dist/src/orchestrator/execute-generation-orchestrator.js"() {
     "use strict";
@@ -740,6 +741,22 @@ var init_describe_agent_failure = __esm({
 });
 
 // packages/experience-design-system-generation/dist/src/services/agent/helpers/extract-sentinel-output.js
+function extractSentinelOutput(stdout) {
+  const START = "<<<EDS_OUTPUT_START>>>";
+  const END = "<<<EDS_OUTPUT_END>>>";
+  const startIdx = stdout.indexOf(START);
+  const endIdx = stdout.indexOf(END);
+  if (startIdx === -1 || endIdx === -1 || endIdx <= startIdx)
+    return null;
+  const secondStart = stdout.indexOf(START, startIdx + START.length);
+  if (secondStart !== -1 && secondStart < endIdx)
+    return "multiple";
+  const afterStart = stdout.indexOf(END, startIdx);
+  const secondEnd = stdout.indexOf(END, afterStart + END.length);
+  if (secondEnd !== -1)
+    return "multiple";
+  return stdout.slice(startIdx + START.length, endIdx).trim();
+}
 var init_extract_sentinel_output = __esm({
   "packages/experience-design-system-generation/dist/src/services/agent/helpers/extract-sentinel-output.js"() {
     "use strict";
@@ -764,7 +781,7 @@ async function runAgent(options) {
     promptLen: prompt.length,
     promptHead: prompt.slice(0, 500)
   });
-  return new Promise((resolve20) => {
+  return new Promise((resolve22) => {
     const bedrockEnv = bedrock ? BEDROCK_ENV_BY_AGENT[agent] : void 0;
     const child = spawn(binary, args, {
       stdio: ["pipe", "pipe", "pipe"],
@@ -813,7 +830,7 @@ async function runAgent(options) {
         stderrLen: stderr.length,
         stderrTail: stderr.slice(-1e3)
       });
-      resolve20(result);
+      resolve22(result);
     });
   });
 }
@@ -830,7 +847,7 @@ var init_run_agent = __esm({
 // packages/experience-design-system-generation/dist/src/services/agent/helpers/check-claude-auth.js
 import { spawn as spawn2 } from "node:child_process";
 function checkClaudeAuth(binary) {
-  return new Promise((resolve20) => {
+  return new Promise((resolve22) => {
     const child = spawn2(binary, ["auth", "status", "--json"], {
       stdio: ["ignore", "pipe", "pipe"]
     });
@@ -840,7 +857,7 @@ function checkClaudeAuth(binary) {
       if (!done) {
         done = true;
         child.kill("SIGTERM");
-        resolve20("unauthenticated");
+        resolve22("unauthenticated");
       }
     }, 5e3);
     child.stdout?.on("data", (chunk) => {
@@ -852,14 +869,14 @@ function checkClaudeAuth(binary) {
       done = true;
       clearTimeout(timer);
       if (code !== 0) {
-        resolve20("unauthenticated");
+        resolve22("unauthenticated");
         return;
       }
       try {
         const status = JSON.parse(stdout);
-        resolve20(status.loggedIn ? "ok" : "unauthenticated");
+        resolve22(status.loggedIn ? "ok" : "unauthenticated");
       } catch {
-        resolve20("unauthenticated");
+        resolve22("unauthenticated");
       }
     });
   });
@@ -874,13 +891,13 @@ var init_check_claude_auth = __esm({
 import { spawn as spawn3 } from "node:child_process";
 async function checkAgentAuth(agent) {
   const binary = resolveAgentBinary(agent);
-  const binaryExists2 = await new Promise((resolve20) => {
+  const binaryExists2 = await new Promise((resolve22) => {
     if (binary.startsWith("/")) {
-      import("node:fs/promises").then((fs2) => fs2.access(binary).then(() => resolve20(true), () => resolve20(false)));
+      import("node:fs/promises").then((fs2) => fs2.access(binary).then(() => resolve22(true), () => resolve22(false)));
       return;
     }
     const child = spawn3(process.platform === "win32" ? "where" : "which", [binary], { stdio: "ignore" });
-    child.on("close", (code) => resolve20(code === 0));
+    child.on("close", (code) => resolve22(code === 0));
   });
   if (!binaryExists2)
     return "not-found";
@@ -917,6 +934,20 @@ var init_local_cli_agent_invoker = __esm({
 });
 
 // packages/experience-design-system-generation/dist/src/controller/create-generation-endpoint.js
+function createGenerationEndpoint(options = {}) {
+  const invoker2 = createLocalCliAgentInvoker({
+    onDebugEvent: options.onDebugEvent
+  });
+  return {
+    async run(request2) {
+      validateGenerationRequest(request2);
+      return executeGenerationOrchestrator({ ...request2, invoker: invoker2 });
+    },
+    checkAuth(agent) {
+      return invoker2.checkAuth(agent);
+    }
+  };
+}
 var init_create_generation_endpoint = __esm({
   "packages/experience-design-system-generation/dist/src/controller/create-generation-endpoint.js"() {
     "use strict";
@@ -1301,6 +1332,32 @@ var init_progress = __esm({
 });
 
 // packages/experience-design-system-generation/dist/src/index.js
+var src_exports = {};
+__export(src_exports, {
+  AGENT_BINARIES: () => AGENT_BINARIES,
+  AGENT_NAMES: () => AGENT_NAMES,
+  DEFAULT_AGENT_NAME: () => DEFAULT_AGENT_NAME,
+  agentSupportsBedrock: () => agentSupportsBedrock,
+  buildArgs: () => buildAgentArgs,
+  buildPrompt: () => buildPrompt,
+  checkAgentAuth: () => checkAgentAuth,
+  createGenerationEndpoint: () => createGenerationEndpoint,
+  createLocalCliAgentInvoker: () => createLocalCliAgentInvoker,
+  describeAgentFailure: () => describeAgentFailure,
+  executeGenerationOrchestrator: () => executeGenerationOrchestrator,
+  extractSentinelOutput: () => extractSentinelOutput,
+  formatCustomPromptBanner: () => formatCustomPromptBanner,
+  formatGenerateProgressLine: () => formatGenerateProgressLine,
+  isAgentName: () => isAgentName,
+  parseMapTokenPropToolCallLines: () => parseMapTokenPropToolCallLines,
+  parseSelectToolCallLines: () => parseSelectToolCallLines,
+  parseTokenToolCallLines: () => parseTokenToolCallLines,
+  parseToolCallLines: () => parsePropToolCallLines,
+  resolveAgentModel: () => resolveAgentModel,
+  resolveBinary: () => resolveAgentBinary,
+  resolveSkillPath: () => resolveSkillPath,
+  runAgent: () => runAgent
+});
 var init_src = __esm({
   "packages/experience-design-system-generation/dist/src/index.js"() {
     "use strict";
@@ -10308,6 +10365,41 @@ var init_read3 = __esm({
   }
 });
 
+// packages/experience-design-system-cli-legacy/src/session/core/components/hash-component-shape.ts
+import { createHash as createHash2 } from "node:crypto";
+function hashComponentShape(component) {
+  const payload = {
+    framework: component.framework,
+    name: component.name,
+    source: component.source,
+    props: component.props.map((p) => ({
+      name: p.name,
+      type: p.type
+    })),
+    slots: component.slots.map((s) => ({
+      name: s.name,
+      isDefault: s.isDefault
+    }))
+  };
+  return createHash2("sha256").update(JSON.stringify(payload)).digest("hex");
+}
+var init_hash_component_shape = __esm({
+  "packages/experience-design-system-cli-legacy/src/session/core/components/hash-component-shape.ts"() {
+    "use strict";
+  }
+});
+
+// packages/experience-design-system-cli-legacy/src/session/core/tokens/hash-token-content.ts
+import { createHash as createHash3 } from "node:crypto";
+function hashTokenContent(rawTokenContent) {
+  return createHash3("sha256").update(rawTokenContent.trim()).digest("hex");
+}
+var init_hash_token_content = __esm({
+  "packages/experience-design-system-cli-legacy/src/session/core/tokens/hash-token-content.ts"() {
+    "use strict";
+  }
+});
+
 // packages/experience-design-system-cli-legacy/src/session/repositories/tokens/write.ts
 function deleteRawTokensForSession(db, sessionId2) {
   db.prepare("DELETE FROM raw_token_groups WHERE session_id = ?").run(sessionId2);
@@ -10471,17 +10563,47 @@ var init_replace_raw_prop_token_paths = __esm({
   }
 });
 
+// packages/experience-design-system-cli-legacy/src/session/cache-keys.ts
+var cache_keys_exports = {};
+__export(cache_keys_exports, {
+  hashContent: () => hashContent,
+  hashFile: () => hashFile,
+  hashPromptForSkill: () => hashPromptForSkill
+});
+import { createHash as createHash4 } from "node:crypto";
+import { readFile as readFile7 } from "node:fs/promises";
+import { resolve as resolve8 } from "node:path";
+function hashContent(content) {
+  return createHash4("sha256").update(content).digest("hex");
+}
+async function hashFile(filePath) {
+  const content = await readFile7(filePath, "utf8");
+  return hashContent(content);
+}
+async function hashPromptForSkill(skill, agent, model, skillPathOverride, extraInputs = [], skillContentOverride) {
+  const promptHash = skillContentOverride ? hashContent(skillContentOverride) : skillPathOverride ? await hashFile(resolve8(skillPathOverride)) : await hashFile(resolveSkillPath(skill));
+  const extraSegment = extraInputs.length > 0 ? `|${extraInputs.join("|")}` : "";
+  return hashContent(`${promptHash}|${agent}|${model ?? ""}${extraSegment}`);
+}
+var init_cache_keys = __esm({
+  "packages/experience-design-system-cli-legacy/src/session/cache-keys.ts"() {
+    "use strict";
+    init_src();
+  }
+});
+
 // packages/experience-design-system-cli-legacy/src/session/db.ts
 import { DatabaseSync } from "node:sqlite";
 import { mkdirSync as mkdirSync2, readFileSync as readFileSync5 } from "node:fs";
-import { readFile as readFile7 } from "node:fs/promises";
+import { readFile as readFile8 } from "node:fs/promises";
+import { createHash as createHash5 } from "node:crypto";
 import { homedir as homedir3 } from "node:os";
-import { dirname as dirname14, resolve as resolve8 } from "node:path";
+import { dirname as dirname14, resolve as resolve9 } from "node:path";
 function getPipelineDbPath() {
   if (process.env.EDS_PIPELINE_DB_PATH) {
-    return resolve8(process.env.EDS_PIPELINE_DB_PATH);
+    return resolve9(process.env.EDS_PIPELINE_DB_PATH);
   }
-  return resolve8(homedir3(), ".contentful", "experience-design-system-cli", "pipeline.db");
+  return resolve9(homedir3(), ".contentful", "experience-design-system-cli", "pipeline.db");
 }
 function openPipelineDb(dbPath) {
   const path = dbPath ?? getPipelineDbPath();
@@ -10615,8 +10737,134 @@ function applyDbMigrations(db) {
   if (!rawSlotColsForRationale.some((c2) => c2.name === "rationale")) {
     db.exec("ALTER TABLE raw_slots ADD COLUMN rationale TEXT");
   }
-  for (const table of REMOVED_CACHE_TABLES) {
-    db.exec(`DROP TABLE IF EXISTS ${table}`);
+  const hasExtractCache = db.prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name='extract_cache'`).all();
+  if (hasExtractCache.length === 0) {
+    db.exec(`
+      CREATE TABLE extract_cache (
+        file_path        TEXT NOT NULL,
+        file_hash        TEXT NOT NULL,
+        cli_version      TEXT NOT NULL,
+        created_at       TEXT NOT NULL,
+        updated_at       TEXT NOT NULL,
+        components_json  TEXT NOT NULL,
+        PRIMARY KEY (file_hash, cli_version)
+      );
+      CREATE INDEX idx_extract_cache_file ON extract_cache(file_path);
+    `);
+  }
+  const hasSelectCache = db.prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name='select_cache'`).all();
+  if (hasSelectCache.length === 0) {
+    db.exec(`
+      CREATE TABLE select_cache (
+        component_hash TEXT NOT NULL,
+        prompt_hash    TEXT NOT NULL,
+        cli_version    TEXT NOT NULL,
+        decision       TEXT NOT NULL CHECK (decision IN ('accepted','rejected')),
+        reason         TEXT,
+        created_at     TEXT NOT NULL,
+        updated_at     TEXT NOT NULL,
+        PRIMARY KEY (component_hash, prompt_hash, cli_version)
+      );
+    `);
+  }
+  const tables = db.prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name='generation_cache'`).all();
+  if (tables.length === 0) {
+    db.exec(`
+      CREATE TABLE generation_cache (
+        input_hash        TEXT NOT NULL,
+        entity_type       TEXT NOT NULL CHECK (entity_type IN ('component', 'token_set', 'token_mapping')),
+        entity_id         TEXT NOT NULL,
+        source_session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+        human_edited      INTEGER NOT NULL DEFAULT 0 CHECK (human_edited IN (0, 1)),
+        created_at        TEXT NOT NULL,
+        updated_at        TEXT NOT NULL,
+        PRIMARY KEY (input_hash, entity_type, entity_id)
+      );
+      CREATE INDEX idx_generation_cache_entity ON generation_cache(entity_type, entity_id);
+      CREATE INDEX idx_generation_cache_session ON generation_cache(source_session_id);
+    `);
+  }
+  const genCacheCols = db.prepare(`PRAGMA table_info(generation_cache)`).all();
+  const hasPromptHash = genCacheCols.some((c2) => c2.name === "prompt_hash");
+  const oldPkCols = genCacheCols.filter((c2) => c2.pk > 0).map((c2) => c2.name);
+  const promptHashInPk = oldPkCols.includes("prompt_hash");
+  if (!hasPromptHash) {
+    db.exec(`ALTER TABLE generation_cache ADD COLUMN prompt_hash TEXT NOT NULL DEFAULT ''`);
+  }
+  if (!promptHashInPk) {
+    db.exec("BEGIN");
+    try {
+      db.exec(`
+        CREATE TABLE generation_cache__new (
+          input_hash        TEXT NOT NULL,
+          entity_type       TEXT NOT NULL CHECK (entity_type IN ('component', 'token_set', 'token_mapping')),
+          entity_id         TEXT NOT NULL,
+          source_session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+          human_edited      INTEGER NOT NULL DEFAULT 0 CHECK (human_edited IN (0, 1)),
+          created_at        TEXT NOT NULL,
+          updated_at        TEXT NOT NULL,
+          prompt_hash       TEXT NOT NULL DEFAULT '',
+          PRIMARY KEY (input_hash, prompt_hash, entity_type, entity_id)
+        );
+        INSERT INTO generation_cache__new
+          (input_hash, entity_type, entity_id, source_session_id, human_edited, created_at, updated_at, prompt_hash)
+          SELECT input_hash, entity_type, entity_id, source_session_id, human_edited, created_at, updated_at, prompt_hash
+          FROM generation_cache;
+        DROP TABLE generation_cache;
+        ALTER TABLE generation_cache__new RENAME TO generation_cache;
+        CREATE INDEX IF NOT EXISTS idx_generation_cache_entity  ON generation_cache(entity_type, entity_id);
+        CREATE INDEX IF NOT EXISTS idx_generation_cache_session ON generation_cache(source_session_id);
+      `);
+      db.exec("COMMIT");
+    } catch (e) {
+      db.exec("ROLLBACK");
+      throw e;
+    }
+  }
+  const genCacheTableSql = db.prepare(`SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'generation_cache'`).get();
+  const hasTokenMappingEntityType = genCacheTableSql?.sql.includes("'token_mapping'") ?? true;
+  if (!hasTokenMappingEntityType) {
+    db.exec("BEGIN");
+    try {
+      db.exec(`
+        CREATE TABLE generation_cache__new2 (
+          input_hash        TEXT NOT NULL,
+          entity_type       TEXT NOT NULL CHECK (entity_type IN ('component', 'token_set', 'token_mapping')),
+          entity_id         TEXT NOT NULL,
+          source_session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+          human_edited      INTEGER NOT NULL DEFAULT 0 CHECK (human_edited IN (0, 1)),
+          created_at        TEXT NOT NULL,
+          updated_at        TEXT NOT NULL,
+          prompt_hash       TEXT NOT NULL DEFAULT '',
+          PRIMARY KEY (input_hash, prompt_hash, entity_type, entity_id)
+        );
+        INSERT INTO generation_cache__new2
+          (input_hash, entity_type, entity_id, source_session_id, human_edited, created_at, updated_at, prompt_hash)
+          SELECT input_hash, entity_type, entity_id, source_session_id, human_edited, created_at, updated_at, prompt_hash
+          FROM generation_cache;
+        DROP TABLE generation_cache;
+        ALTER TABLE generation_cache__new2 RENAME TO generation_cache;
+        CREATE INDEX IF NOT EXISTS idx_generation_cache_entity  ON generation_cache(entity_type, entity_id);
+        CREATE INDEX IF NOT EXISTS idx_generation_cache_session ON generation_cache(source_session_id);
+      `);
+      db.exec("COMMIT");
+    } catch (e) {
+      db.exec("ROLLBACK");
+      throw e;
+    }
+  }
+  const hasCompositionCache = db.prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name='composition_cache'`).all();
+  if (hasCompositionCache.length === 0) {
+    db.exec(`
+      CREATE TABLE composition_cache (
+        input_hash   TEXT NOT NULL,
+        cli_version  TEXT NOT NULL,
+        agent_output TEXT NOT NULL,
+        created_at   TEXT NOT NULL,
+        updated_at   TEXT NOT NULL,
+        PRIMARY KEY (input_hash, cli_version)
+      );
+    `);
   }
 }
 function loadComponentReviewMetadata(db, sessionId2, componentName) {
@@ -11156,16 +11404,16 @@ function extractRelativeImportPaths(sourceText) {
   return [...specifiers];
 }
 async function resolveRelativeImport(specifier, fromDir) {
-  const basePath = resolve8(fromDir, specifier);
+  const basePath = resolve9(fromDir, specifier);
   const candidates = [
     basePath,
     ...rewrittenSourcePaths(basePath),
     ...SIBLING_FILE_EXTENSIONS.map((ext) => `${basePath}${ext}`),
-    ...SIBLING_FILE_EXTENSIONS.map((ext) => resolve8(basePath, `index${ext}`))
+    ...SIBLING_FILE_EXTENSIONS.map((ext) => resolve9(basePath, `index${ext}`))
   ];
   for (const candidate of candidates) {
     try {
-      await readFile7(candidate, "utf8");
+      await readFile8(candidate, "utf8");
       return candidate;
     } catch {
     }
@@ -11181,7 +11429,7 @@ async function resolveImportSpecifiers(sourceText, fromDir) {
   return resolvedPaths;
 }
 async function loadSiblingFiles(sourceText, sourcePath, propNames, candidateTypeNames = []) {
-  const visited = /* @__PURE__ */ new Set([resolve8(sourcePath)]);
+  const visited = /* @__PURE__ */ new Set([resolve9(sourcePath)]);
   const discovered = [];
   let frontier = [{ text: sourceText, dir: dirname14(sourcePath) }];
   for (let hop = 0; hop < MAX_SIBLING_DEPTH && discovered.length < MAX_SIBLING_CANDIDATES_EXPLORED; hop++) {
@@ -11195,7 +11443,7 @@ async function loadSiblingFiles(sourceText, sourcePath, propNames, candidateType
         if (discovered.length >= MAX_SIBLING_CANDIDATES_EXPLORED) break;
         let content;
         try {
-          content = await readFile7(resolvedPath, "utf8");
+          content = await readFile8(resolvedPath, "utf8");
         } catch {
           continue;
         }
@@ -11232,7 +11480,7 @@ async function loadComponentSourceRef(name, sourcePath, propNames = [], propType
   let truncatedSiblingCount = 0;
   const usesNotShown = /* @__PURE__ */ new Set();
   try {
-    const rawText = await readFile7(sourcePath, "utf8");
+    const rawText = await readFile8(sourcePath, "utf8");
     let siblingUsesNotShown;
     let declaredTypeNames;
     ({
@@ -11668,6 +11916,108 @@ function backfillUnclassifiedProps(db, sessionId2) {
   ).run(sessionId2, sessionId2);
   return Number(withCategory.changes) + Number(withoutCategory.changes);
 }
+function computeMapTokensInputHash(db, sessionId2, componentSourceRefs = []) {
+  const props = db.prepare(
+    `SELECT rc.name AS component_name, rp.name AS prop_name, rp.cdf_token_kind, rp.default_value
+       FROM raw_props rp
+       JOIN raw_components rc ON rc.session_id = rp.session_id AND rc.component_id = rp.component_id
+       WHERE rp.session_id = ? AND rp.cdf_type = 'token' AND rp.cdf_category = 'design'
+       ORDER BY rc.name, rp.name`
+  ).all(sessionId2);
+  const tokens = db.prepare(`SELECT path, type FROM raw_tokens WHERE session_id = ? ORDER BY path`).all(sessionId2);
+  const defaultMappings = db.prepare("SELECT raw_name, path, source FROM raw_token_name_paths WHERE session_id = ? ORDER BY raw_name").all(sessionId2);
+  const payload = {
+    props: props.map((p) => ({
+      component: p.component_name,
+      prop: p.prop_name,
+      tokenKind: p.cdf_token_kind,
+      rawDefault: p.default_value
+    })),
+    tokens,
+    defaultMappings,
+    // The agent's evidence, not just its inputs: a comment or allowlist edit
+    // in a source file (or a sibling it reads) changes the correct answer
+    // without touching props or tokens, so it must invalidate the cache too.
+    sourceRefs: [...componentSourceRefs].sort((a, b) => a.component.localeCompare(b.component)).map((ref) => ({
+      component: ref.component,
+      content: ref.content,
+      siblingFiles: (ref.siblingFiles ?? []).map((s) => ({ path: s.path, content: s.content })).sort((a, b) => a.path.localeCompare(b.path)),
+      usesNotShown: [...ref.usesNotShown ?? []].sort()
+    }))
+  };
+  return createHash5("sha256").update(JSON.stringify(payload)).digest("hex");
+}
+function lookupCache(db, inputHash, entityType, entityId, promptHash = "") {
+  const row = db.prepare(
+    `SELECT input_hash, entity_type, entity_id, source_session_id, human_edited, created_at, updated_at, prompt_hash
+       FROM generation_cache
+       WHERE input_hash = ? AND entity_type = ? AND entity_id = ? AND prompt_hash = ?`
+  ).get(inputHash, entityType, entityId, promptHash);
+  if (!row) return null;
+  return {
+    inputHash: row.input_hash,
+    entityType: row.entity_type,
+    entityId: row.entity_id,
+    sourceSessionId: row.source_session_id,
+    humanEdited: row.human_edited === 1,
+    promptHash: row.prompt_hash,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at
+  };
+}
+function lookupCacheByEntity(db, entityType, entityId) {
+  const row = db.prepare(
+    `SELECT input_hash, entity_type, entity_id, source_session_id, human_edited, created_at, updated_at, prompt_hash
+       FROM generation_cache
+       WHERE entity_type = ? AND entity_id = ?
+       ORDER BY updated_at DESC LIMIT 1`
+  ).get(entityType, entityId);
+  if (!row) return null;
+  return {
+    inputHash: row.input_hash,
+    entityType: row.entity_type,
+    entityId: row.entity_id,
+    sourceSessionId: row.source_session_id,
+    humanEdited: row.human_edited === 1,
+    promptHash: row.prompt_hash,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at
+  };
+}
+function storeCache(db, inputHash, entityType, entityId, sourceSessionId, humanEdited, promptHash = "") {
+  storeCaches(db, [{ inputHash, entityType, entityId, sourceSessionId, humanEdited, promptHash }]);
+}
+function storeCaches(db, entries) {
+  if (entries.length === 0) return;
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const insert = db.prepare(
+    `INSERT INTO generation_cache (input_hash, entity_type, entity_id, source_session_id, human_edited, created_at, updated_at, prompt_hash)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(input_hash, prompt_hash, entity_type, entity_id) DO UPDATE SET
+       source_session_id = excluded.source_session_id,
+       human_edited = CASE WHEN generation_cache.human_edited = 1 THEN 1 ELSE excluded.human_edited END,
+       updated_at = excluded.updated_at`
+  );
+  db.exec("BEGIN");
+  try {
+    for (const entry of entries) {
+      insert.run(
+        entry.inputHash,
+        entry.entityType,
+        entry.entityId,
+        entry.sourceSessionId,
+        entry.humanEdited ? 1 : 0,
+        now,
+        now,
+        entry.promptHash ?? ""
+      );
+    }
+    db.exec("COMMIT");
+  } catch (e) {
+    db.exec("ROLLBACK");
+    throw e;
+  }
+}
 function storeScannedFiles(db, sessionId2, filePaths) {
   db.exec("BEGIN");
   try {
@@ -11750,7 +12100,105 @@ function filterUnknownSlotAllowedComponents(db, sessionId2, allowedComponentName
   }
   return unknown;
 }
-function copyTokensBetweenSessions(db, sourceSessionId, targetSessionId) {
+function copyComponentFromCache(db, sourceSessionId, targetSessionId, componentId, manageTransaction = true, options = {}) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  if (manageTransaction) db.exec("BEGIN");
+  try {
+    const srcComp = db.prepare(
+      `SELECT description, status, component_description_rationale, props_rationale, slots_rationale
+         FROM raw_components WHERE session_id = ? AND component_id = ?`
+    ).get(sourceSessionId, componentId);
+    if (srcComp) {
+      db.prepare(
+        `UPDATE raw_components
+         SET description = ?, status = ?, component_description_rationale = ?, props_rationale = ?, slots_rationale = ?, extracted_at = ?
+         WHERE session_id = ? AND component_id = ?`
+      ).run(
+        srcComp.description,
+        srcComp.status,
+        srcComp.component_description_rationale,
+        srcComp.props_rationale,
+        srcComp.slots_rationale,
+        now,
+        targetSessionId,
+        componentId
+      );
+    }
+    const srcProps = db.prepare(
+      `SELECT name, cdf_type, cdf_category, cdf_token_kind, required, description, default_value, rationale
+         FROM raw_props WHERE session_id = ? AND component_id = ?`
+    ).all(sourceSessionId, componentId);
+    for (const p of srcProps) {
+      db.prepare(
+        `UPDATE raw_props SET cdf_type = ?, cdf_category = ?, cdf_token_kind = ?, required = ?, description = ?, default_value = ?, rationale = ?
+         WHERE session_id = ? AND component_id = ? AND name = ?`
+      ).run(
+        p.cdf_type,
+        p.cdf_category,
+        p.cdf_token_kind,
+        p.required,
+        p.description,
+        p.default_value,
+        p.rationale,
+        targetSessionId,
+        componentId,
+        p.name
+      );
+    }
+    db.prepare(`DELETE FROM raw_prop_allowed_values WHERE session_id = ? AND component_id = ?`).run(
+      targetSessionId,
+      componentId
+    );
+    const srcAV = db.prepare(
+      `SELECT prop_name, position, value FROM raw_prop_allowed_values WHERE session_id = ? AND component_id = ?`
+    ).all(sourceSessionId, componentId);
+    const insertAV = db.prepare(
+      `INSERT INTO raw_prop_allowed_values (session_id, component_id, prop_name, position, value) VALUES (?, ?, ?, ?, ?)`
+    );
+    for (const av of srcAV) {
+      insertAV.run(targetSessionId, componentId, av.prop_name, av.position, av.value);
+    }
+    const srcSlots = db.prepare(`SELECT name, required, description, rationale FROM raw_slots WHERE session_id = ? AND component_id = ?`).all(sourceSessionId, componentId);
+    for (const s of srcSlots) {
+      db.prepare(
+        `UPDATE raw_slots SET required = ?, description = ?, rationale = ? WHERE session_id = ? AND component_id = ? AND name = ?`
+      ).run(s.required, s.description, s.rationale, targetSessionId, componentId, s.name);
+    }
+    db.prepare(`DELETE FROM raw_slot_allowed_components WHERE session_id = ? AND component_id = ?`).run(
+      targetSessionId,
+      componentId
+    );
+    const srcSAC = db.prepare(
+      `SELECT slot_name, position, allowed_component FROM raw_slot_allowed_components WHERE session_id = ? AND component_id = ?`
+    ).all(sourceSessionId, componentId);
+    const insertSAC = db.prepare(
+      `INSERT INTO raw_slot_allowed_components (session_id, component_id, slot_name, allowed_component, position) VALUES (?, ?, ?, ?, ?)`
+    );
+    const allowedSAC = options.allowedComponentNames ? srcSAC.filter((sac) => options.allowedComponentNames.has(sac.allowed_component)) : srcSAC;
+    for (const sac of allowedSAC) {
+      insertSAC.run(targetSessionId, componentId, sac.slot_name, sac.allowed_component, sac.position);
+    }
+    db.prepare("UPDATE sessions SET updated_at = ? WHERE id = ?").run(now, targetSessionId);
+    if (manageTransaction) db.exec("COMMIT");
+  } catch (e) {
+    if (manageTransaction) db.exec("ROLLBACK");
+    throw e;
+  }
+}
+function copyComponentsFromCache(db, entries, options = {}) {
+  if (entries.length === 0) return;
+  db.exec("BEGIN");
+  try {
+    for (const entry of entries) {
+      copyComponentFromCache(db, entry.sourceSessionId, entry.targetSessionId, entry.componentId, false, options);
+    }
+    db.exec("COMMIT");
+  } catch (e) {
+    db.exec("ROLLBACK");
+    throw e;
+  }
+}
+function copyTokensFromCache(db, sourceSessionId, targetSessionId) {
   const now = (/* @__PURE__ */ new Date()).toISOString();
   db.exec("BEGIN");
   try {
@@ -11771,7 +12219,153 @@ function copyTokensBetweenSessions(db, sourceSessionId, targetSessionId) {
     throw e;
   }
 }
-var SCHEMA, REMOVED_CACHE_TABLES, MAX_COMPONENT_SOURCE_CHARS, MAX_SIBLING_FILES, MAX_SIBLING_SNIPPET_CHARS, MAX_TYPE_DECLARING_SIBLING_CHARS, MAX_ENLARGED_SIBLINGS, MAX_SIBLING_DEPTH, MAX_SIBLING_CANDIDATES_EXPLORED, RELATIVE_IMPORT_PATTERN, SIBLING_FILE_EXTENSIONS, TS_ESM_EXTENSION_REWRITES, IDENTIFIER_PATTERN;
+function copyMapTokensFromCache(db, sourceSessionId, targetSessionId) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  let copiedCount = 0;
+  db.exec("BEGIN");
+  try {
+    const sourceRows = db.prepare(
+      `SELECT rc.name AS component_name, rptp.prop_name, rptp.source, rptp.position, rptp.path
+         FROM raw_prop_token_paths rptp
+         JOIN raw_components rc ON rc.session_id = rptp.session_id AND rc.component_id = rptp.component_id
+         WHERE rptp.session_id = ?
+         ORDER BY rc.name, rptp.prop_name, rptp.position`
+    ).all(sourceSessionId);
+    const targetComponents = db.prepare(`SELECT component_id, name FROM raw_components WHERE session_id = ?`).all(targetSessionId);
+    const targetIdByName = new Map(targetComponents.map((c2) => [c2.name, c2.component_id]));
+    const targetProps = new Set(
+      db.prepare(`SELECT component_id, name FROM raw_props WHERE session_id = ?`).all(targetSessionId).map((p) => `${p.component_id}::${p.name}`)
+    );
+    const insertPath = db.prepare(
+      `INSERT INTO raw_prop_token_paths (session_id, component_id, prop_name, source, position, path)
+       VALUES (?, ?, ?, ?, ?, ?)`
+    );
+    const clearedProps = /* @__PURE__ */ new Set();
+    const copiedProps = /* @__PURE__ */ new Set();
+    for (const row of sourceRows) {
+      const targetComponentId = targetIdByName.get(row.component_name);
+      if (!targetComponentId) continue;
+      if (!targetProps.has(`${targetComponentId}::${row.prop_name}`)) continue;
+      const propKey = `${targetComponentId}::${row.prop_name}`;
+      if (!clearedProps.has(propKey)) {
+        clearedProps.add(propKey);
+        db.prepare(`DELETE FROM raw_prop_token_paths WHERE session_id = ? AND component_id = ? AND prop_name = ?`).run(
+          targetSessionId,
+          targetComponentId,
+          row.prop_name
+        );
+      }
+      insertPath.run(targetSessionId, targetComponentId, row.prop_name, row.source, row.position, row.path);
+      copiedProps.add(propKey);
+    }
+    copiedCount = copiedProps.size;
+    db.prepare("UPDATE sessions SET updated_at = ? WHERE id = ?").run(now, targetSessionId);
+    db.exec("COMMIT");
+  } catch (e) {
+    db.exec("ROLLBACK");
+    throw e;
+  }
+  return copiedCount;
+}
+async function getCliCacheVersion() {
+  if (_cliCacheVersionCache) return _cliCacheVersionCache;
+  try {
+    const { hashContent: hashContent2 } = await Promise.resolve().then(() => (init_cache_keys(), cache_keys_exports));
+    const { resolveSkillPath: resolveSkillPath2 } = await Promise.resolve().then(() => (init_src(), src_exports));
+    const skills = ["components", "tokens", "select"];
+    const parts = [];
+    for (const s of skills) {
+      try {
+        const p = resolveSkillPath2(s);
+        parts.push(readFileSync5(p, "utf8"));
+      } catch {
+        parts.push(`<missing:${s}>`);
+      }
+    }
+    _cliCacheVersionCache = hashContent2(parts.join("\n---\n"));
+    return _cliCacheVersionCache;
+  } catch {
+    _cliCacheVersionCache = "fallback";
+    return _cliCacheVersionCache;
+  }
+}
+function storeExtractCache(db, filePath, fileHash, cliVersion2, components) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const componentsJson = JSON.stringify(components);
+  db.prepare(
+    `INSERT INTO extract_cache (file_path, file_hash, cli_version, created_at, updated_at, components_json)
+     VALUES (?, ?, ?, ?, ?, ?)
+     ON CONFLICT(file_hash, cli_version) DO UPDATE SET
+       file_path = excluded.file_path,
+       updated_at = excluded.updated_at,
+       components_json = excluded.components_json`
+  ).run(filePath, fileHash, cliVersion2, now, now, componentsJson);
+}
+function lookupExtractCache(db, fileHash, cliVersion2) {
+  const row = db.prepare(
+    `SELECT file_path, file_hash, cli_version, created_at, updated_at, components_json
+       FROM extract_cache
+       WHERE file_hash = ? AND cli_version = ?`
+  ).get(fileHash, cliVersion2);
+  if (!row) return null;
+  let components = [];
+  try {
+    components = JSON.parse(row.components_json);
+  } catch {
+    return null;
+  }
+  return {
+    filePath: row.file_path,
+    fileHash: row.file_hash,
+    cliVersion: row.cli_version,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+    components
+  };
+}
+function storeCompositionCache(db, inputHash, cliVersion2, agentOutput) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  db.prepare(
+    `INSERT INTO composition_cache (input_hash, cli_version, agent_output, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?)
+     ON CONFLICT(input_hash, cli_version) DO UPDATE SET
+       agent_output = excluded.agent_output,
+       updated_at = excluded.updated_at`
+  ).run(inputHash, cliVersion2, agentOutput, now, now);
+}
+function lookupCompositionCache(db, inputHash, cliVersion2) {
+  const row = db.prepare(`SELECT agent_output FROM composition_cache WHERE input_hash = ? AND cli_version = ?`).get(inputHash, cliVersion2);
+  return row ? row.agent_output : null;
+}
+function storeSelectCache(db, componentHash, promptHash, cliVersion2, decision, reason) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  db.prepare(
+    `INSERT INTO select_cache (component_hash, prompt_hash, cli_version, decision, reason, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(component_hash, prompt_hash, cli_version) DO UPDATE SET
+       decision = excluded.decision,
+       reason = excluded.reason,
+       updated_at = excluded.updated_at`
+  ).run(componentHash, promptHash, cliVersion2, decision, reason, now, now);
+}
+function lookupSelectCache(db, componentHash, promptHash, cliVersion2) {
+  const row = db.prepare(
+    `SELECT component_hash, prompt_hash, cli_version, decision, reason, created_at, updated_at
+       FROM select_cache
+       WHERE component_hash = ? AND prompt_hash = ? AND cli_version = ?`
+  ).get(componentHash, promptHash, cliVersion2);
+  if (!row) return null;
+  return {
+    componentHash: row.component_hash,
+    promptHash: row.prompt_hash,
+    cliVersion: row.cli_version,
+    decision: row.decision,
+    reason: row.reason,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at
+  };
+}
+var SCHEMA, MAX_COMPONENT_SOURCE_CHARS, MAX_SIBLING_FILES, MAX_SIBLING_SNIPPET_CHARS, MAX_TYPE_DECLARING_SIBLING_CHARS, MAX_ENLARGED_SIBLINGS, MAX_SIBLING_DEPTH, MAX_SIBLING_CANDIDATES_EXPLORED, RELATIVE_IMPORT_PATTERN, SIBLING_FILE_EXTENSIONS, TS_ESM_EXTENSION_REWRITES, IDENTIFIER_PATTERN, _cliCacheVersionCache;
 var init_db = __esm({
   "packages/experience-design-system-cli-legacy/src/session/db.ts"() {
     "use strict";
@@ -11785,6 +12379,8 @@ var init_db = __esm({
     init_write2();
     init_session_resolver();
     init_read3();
+    init_hash_component_shape();
+    init_hash_token_content();
     init_read3();
     init_store_dtcg_tokens();
     init_apply_tool_calls();
@@ -11908,6 +12504,17 @@ CREATE TABLE IF NOT EXISTS raw_tokens (
   FOREIGN KEY (session_id) REFERENCES sessions(id) ON DELETE CASCADE
 );
 
+CREATE TABLE IF NOT EXISTS generation_cache (
+  input_hash        TEXT NOT NULL,
+  entity_type       TEXT NOT NULL CHECK (entity_type IN ('component', 'token_set', 'token_mapping')),
+  entity_id         TEXT NOT NULL,
+  source_session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+  human_edited      INTEGER NOT NULL DEFAULT 0 CHECK (human_edited IN (0, 1)),
+  created_at        TEXT NOT NULL,
+  updated_at        TEXT NOT NULL,
+  PRIMARY KEY (input_hash, entity_type, entity_id)
+);
+
 CREATE TABLE IF NOT EXISTS scanned_files (
   session_id  TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
   path        TEXT NOT NULL,
@@ -11953,9 +12560,10 @@ CREATE INDEX IF NOT EXISTS idx_raw_props_session        ON raw_props(session_id,
 CREATE INDEX IF NOT EXISTS idx_raw_slots_session        ON raw_slots(session_id, component_id);
 CREATE INDEX IF NOT EXISTS idx_raw_tokens_session       ON raw_tokens(session_id);
 CREATE INDEX IF NOT EXISTS idx_raw_token_groups_session ON raw_token_groups(session_id);
+CREATE INDEX IF NOT EXISTS idx_generation_cache_entity  ON generation_cache(entity_type, entity_id);
+CREATE INDEX IF NOT EXISTS idx_generation_cache_session ON generation_cache(source_session_id);
 CREATE INDEX IF NOT EXISTS idx_scanned_files_session    ON scanned_files(session_id);
 `;
-    REMOVED_CACHE_TABLES = ["generation_cache", "extract_cache", "composition_cache", "select_cache"];
     MAX_COMPONENT_SOURCE_CHARS = 8e3;
     MAX_SIBLING_FILES = 5;
     MAX_SIBLING_SNIPPET_CHARS = 1200;
@@ -11972,15 +12580,16 @@ CREATE INDEX IF NOT EXISTS idx_scanned_files_session    ON scanned_files(session
       [".cjs", [".cts", ".cjs"]]
     ];
     IDENTIFIER_PATTERN = /[A-Za-z_$][A-Za-z0-9_$]*/g;
+    _cliCacheVersionCache = null;
   }
 });
 
 // packages/experience-design-system-cli-legacy/src/helpers/read-existing-contentful-entities-from-session.ts
-import { readFile as readFile8 } from "node:fs/promises";
+import { readFile as readFile9 } from "node:fs/promises";
 async function readExistingContentfulEntitiesFromSession(path) {
   if (!path) return void 0;
   try {
-    const raw = await readFile8(path, "utf8");
+    const raw = await readFile9(path, "utf8");
     const parsed = JSON.parse(raw);
     if (!Array.isArray(parsed.components) || !Array.isArray(parsed.tokens)) return void 0;
     return parsed;
@@ -12104,21 +12713,21 @@ var init_resolve_session_id = __esm({
 });
 
 // packages/experience-design-system-cli-legacy/src/analyze/select/persistence.ts
-import { access, appendFile, mkdir as mkdir2, readFile as readFile9, writeFile as writeFile2 } from "node:fs/promises";
+import { access, appendFile, mkdir as mkdir2, readFile as readFile10, writeFile as writeFile2 } from "node:fs/promises";
 import { homedir as homedir4 } from "node:os";
-import { resolve as resolve9 } from "node:path";
+import { resolve as resolve10 } from "node:path";
 function getRefineArtifactsRoot() {
   if (process.env.EDS_REVIEW_ARTIFACTS_DIR) {
-    return resolve9(process.env.EDS_REVIEW_ARTIFACTS_DIR);
+    return resolve10(process.env.EDS_REVIEW_ARTIFACTS_DIR);
   }
-  return resolve9(homedir4(), ".contentful", "experience-design-system-cli", "reviews");
+  return resolve10(homedir4(), ".contentful", "experience-design-system-cli", "reviews");
 }
 async function getRefineSessionPaths(sessionId2, artifactsRoot) {
-  const sessionDir = resolve9(artifactsRoot, sessionId2);
+  const sessionDir = resolve10(artifactsRoot, sessionId2);
   return {
     sessionDir,
-    eventsPath: resolve9(sessionDir, "events.jsonl"),
-    statePath: resolve9(sessionDir, "current-review-state.json")
+    eventsPath: resolve10(sessionDir, "events.jsonl"),
+    statePath: resolve10(sessionDir, "current-review-state.json")
   };
 }
 async function saveReviewState(statePath, session) {
@@ -12129,7 +12738,7 @@ async function ensureRefineSession(sessionId2, artifactsRoot, initialSnapshot) {
   await mkdir2(paths.sessionDir, { recursive: true });
   try {
     await access(paths.statePath);
-    const savedState = await readFile9(paths.statePath, "utf8");
+    const savedState = await readFile10(paths.statePath, "utf8");
     return JSON.parse(savedState);
   } catch {
     await writeFile2(paths.statePath, JSON.stringify(initialSnapshot, null, 2), "utf8");
@@ -12614,8 +13223,8 @@ var init_path_exists = __esm({
 });
 
 // packages/experience-design-system-cli-legacy/src/lib/prompt-overrides.ts
-import { readFile as readFile10 } from "node:fs/promises";
-import { resolve as resolve10 } from "node:path";
+import { readFile as readFile11 } from "node:fs/promises";
+import { resolve as resolve11 } from "node:path";
 function looksLikePath(value) {
   if (value.includes("/") || value.includes("\\")) return true;
   if (value.startsWith("~")) return true;
@@ -12647,9 +13256,9 @@ function parsePromptOverrides(inputs) {
 }
 async function resolvePromptOverride(override) {
   if (override.kind === "text") return override.value;
-  const abs = resolve10(override.value);
+  const abs = resolve11(override.value);
   try {
-    return await readFile10(abs, "utf8");
+    return await readFile11(abs, "utf8");
   } catch {
     throw new Error(`--prompt: could not read prompt file: ${abs}`);
   }
@@ -12664,21 +13273,21 @@ var init_prompt_overrides = __esm({
 
 // packages/experience-design-system-cli-legacy/src/generate/command.ts
 import { createElement } from "react";
-import { readFile as readFile11, readdir, stat } from "node:fs/promises";
-import { join as join14, resolve as resolve11 } from "node:path";
+import { readFile as readFile12, readdir, stat } from "node:fs/promises";
+import { join as join14, resolve as resolve12 } from "node:path";
 async function assertFileExists(flag, p) {
   if (!await pathExists(p)) die(`Error: file not found: ${p} (from ${flag})`);
 }
 async function readFileInline(path) {
   if (!path) return void 0;
-  const resolved = resolve11(path);
+  const resolved = resolve12(path);
   let s;
   try {
     s = await stat(resolved);
   } catch {
     return void 0;
   }
-  if (!s.isDirectory()) return readFile11(resolved, "utf8");
+  if (!s.isDirectory()) return readFile12(resolved, "utf8");
   const files = [];
   async function walk(dir) {
     let entries;
@@ -12704,7 +13313,7 @@ async function readFileInline(path) {
   }
   await walk(resolved);
   if (files.length === 0) return void 0;
-  const parts = await Promise.all(files.map((f) => readFile11(f, "utf8").catch(() => "")));
+  const parts = await Promise.all(files.map((f) => readFile12(f, "utf8").catch(() => "")));
   return parts.filter(Boolean).join("\n\n");
 }
 function printFallbackInstructions(options) {
@@ -12726,6 +13335,23 @@ function printFallbackInstructions(options) {
   lines.push(`  Re-run the generate command with the agent available, or use --dry-run to inspect the prompt.`);
   process.stderr.write(lines.join("\n") + "\n");
 }
+function createCachedComponentResult(componentName, warnings = []) {
+  return {
+    componentName,
+    classified: 0,
+    excluded: 0,
+    slots: 0,
+    warnings,
+    failed: false,
+    cached: true,
+    renamedSlotsCount: 0
+  };
+}
+function writeCachedComponentStatus(position, componentName, pinned) {
+  const status = pinned ? c.cyan("pinned (human-edited)") : c.green("cached");
+  process.stderr.write(`  ${position}  ${c.bold(componentName)}  ${status}
+`);
+}
 async function showGenerateView(result) {
   if (process.stdout.isTTY) {
     const { waitUntilExit } = renderWithGoodbye(
@@ -12746,6 +13372,29 @@ session=${result.sessionId}
   );
   await exitWithAnalytics(0);
 }
+function normalizeComponentForCache(component) {
+  const slots = component.slots.map((slot, index, allSlots) => ({
+    ...slot,
+    name: slot.name.trim() || (allSlots.length === 1 ? "children" : `slot_${index}`)
+  }));
+  return { ...component, slots };
+}
+function lookupComponentCache(db, component, promptHash) {
+  const normalized = normalizeComponentForCache(component);
+  const inputHash = hashComponentShape(normalized);
+  const cached = lookupCache(db, inputHash, "component", component.component_id, promptHash);
+  if (cached) return cached;
+  const legacyInputHash = hashComponentShape(component);
+  return legacyInputHash === inputHash ? null : lookupCache(db, legacyInputHash, "component", component.component_id, promptHash);
+}
+function resolveComponentCache(db, component, promptHash, allowedComponentNames2) {
+  const cached = lookupComponentCache(db, component, promptHash);
+  if (cached && findUnknownSlotAllowedComponents(db, cached.sourceSessionId, allowedComponentNames2, component.component_id).length === 0) {
+    return { entry: cached, humanEdited: cached.humanEdited };
+  }
+  const pinned = lookupCacheByEntity(db, "component", component.component_id);
+  return pinned?.humanEdited && findUnknownSlotAllowedComponents(db, pinned.sourceSessionId, allowedComponentNames2, component.component_id).length === 0 ? { entry: pinned, humanEdited: true } : null;
+}
 async function runOneComponent(options, component, index, total) {
   const {
     agent,
@@ -12755,10 +13404,13 @@ async function runOneComponent(options, component, index, total) {
     tokensInline,
     tokenMapInline,
     verbose,
+    noCache,
     skillPathOverride,
     skillContentOverride,
+    promptHash,
     existingContentfulEntities,
     existingTokensInline,
+    precomputedCachedNames,
     allowedComponentNames: allowedComponentNames2
   } = options;
   const pos = c.dim(`[${index + 1}/${total}]`);
@@ -12783,6 +13435,40 @@ async function runOneComponent(options, component, index, total) {
       allowedComponents: slot.allowedComponents.filter((name) => allowedComponentNames2.has(name))
     };
   });
+  const cacheComponent = normalizeComponentForCache(component);
+  if (!noCache && precomputedCachedNames.has(component.name)) {
+    writeCachedComponentStatus(pos, component.name, false);
+    return createCachedComponentResult(component.name);
+  }
+  if (!noCache) {
+    const inputHash = hashComponentShape(cacheComponent);
+    const resolution = resolveComponentCache(db, component, promptHash, allowedComponentNames2);
+    if (resolution && !resolution.humanEdited) {
+      copyComponentFromCache(db, resolution.entry.sourceSessionId, sessionId2, component.component_id, true, {
+        allowedComponentNames: allowedComponentNames2
+      });
+      storeCache(
+        db,
+        inputHash,
+        "component",
+        component.component_id,
+        resolution.entry.sourceSessionId,
+        resolution.entry.humanEdited,
+        promptHash
+      );
+      writeCachedComponentStatus(pos, component.name, false);
+      return createCachedComponentResult(component.name);
+    }
+    if (resolution?.humanEdited) {
+      copyComponentFromCache(db, resolution.entry.sourceSessionId, sessionId2, component.component_id, true, {
+        allowedComponentNames: allowedComponentNames2
+      });
+      writeCachedComponentStatus(pos, component.name, true);
+      return createCachedComponentResult(`${component.name}`, [
+        `${component.name}: source changed but human edits preserved`
+      ]);
+    }
+  }
   const componentBuckets = bucketComponentProps(component);
   getDebugLogger().event("analyze", "prop-buckets.generate", { ...componentBuckets });
   const rawComponentsInline = JSON.stringify(
@@ -12857,6 +13543,10 @@ ${outputBuf}`);
     const applied = applyToolCalls(db, sessionId2, component.component_id, component.name, calls, warnings, {
       allowedComponentNames: allowedComponentNames2
     });
+    if (!noCache) {
+      const inputHash = hashComponentShape(cacheComponent);
+      storeCache(db, inputHash, "component", component.component_id, sessionId2, false, promptHash);
+    }
     return {
       componentName: component.name,
       classified: applied.classified,
@@ -12908,7 +13598,7 @@ async function loadAcceptedNames(sessionId2) {
   try {
     const artifactsRoot = getRefineArtifactsRoot();
     const paths = await getRefineSessionPaths(sessionId2, artifactsRoot);
-    const raw = await readFile11(paths.statePath, "utf8");
+    const raw = await readFile12(paths.statePath, "utf8");
     const snapshot = JSON.parse(raw);
     const accepted = snapshot.components.filter((c2) => c2.status === "accepted").map((c2) => c2.name);
     if (accepted.length === 0) return null;
@@ -12917,6 +13607,15 @@ async function loadAcceptedNames(sessionId2) {
     return null;
   }
 }
+function parsePrecomputedCachedNames(value) {
+  if (!value) return /* @__PURE__ */ new Set();
+  try {
+    const parsed = JSON.parse(value);
+    return new Set(Array.isArray(parsed) ? parsed.filter((name) => typeof name === "string") : []);
+  } catch {
+    return /* @__PURE__ */ new Set();
+  }
+}
 async function runGenerateSkill(skill, opts, verbose = false) {
   const savedCreds = await readExperiencesCredentials();
   const agentName = opts.agent ?? savedCreds.agent;
@@ -12945,8 +13644,8 @@ async function runGenerateSkill(skill, opts, verbose = false) {
   }
   const generatePromptPath = generatePrompt === void 0 ? configuredGeneratePromptPath : void 0;
   if (generatePromptPath) {
-    if (!await pathExists(resolve11(generatePromptPath))) {
-      die(`Error: custom prompt path not found: ${resolve11(generatePromptPath)}`);
+    if (!await pathExists(resolve12(generatePromptPath))) {
+      die(`Error: custom prompt path not found: ${resolve12(generatePromptPath)}`);
     }
     if (!generatePromptPath.toLowerCase().endsWith(".md")) {
       process.stderr.write(
@@ -12954,7 +13653,7 @@ async function runGenerateSkill(skill, opts, verbose = false) {
 `
       );
     }
-    process.stderr.write(formatCustomPromptBanner("components", resolve11(generatePromptPath)));
+    process.stderr.write(formatCustomPromptBanner("components", resolve12(generatePromptPath)));
   }
   if (skill === "tokens" && !opts.rawTokens) {
     die("Error: --raw-tokens is required when using generate tokens");
@@ -12970,7 +13669,7 @@ async function runGenerateSkill(skill, opts, verbose = false) {
   let existingContentfulEntities;
   let existingTokensInline;
   if (opts.existingEntitiesPath) {
-    existingContentfulEntities = await readExistingContentfulEntitiesFromSession(resolve11(opts.existingEntitiesPath));
+    existingContentfulEntities = await readExistingContentfulEntitiesFromSession(resolve12(opts.existingEntitiesPath));
     if (existingContentfulEntities) {
       existingTokensInline = JSON.stringify(summarizeForMapTokens(existingContentfulEntities));
     } else {
@@ -13071,7 +13770,7 @@ async function runGenerateSkill(skill, opts, verbose = false) {
       rawComponentsInline: sampleInline ?? rawTokensInline,
       propBucketsInline: sampleBuckets ? JSON.stringify(sampleBuckets) : void 0,
       rawTokensInline: skill === "tokens" ? rawTokensInline : void 0,
-      rawTokensFilename: opts.rawTokens ? resolve11(opts.rawTokens).split("/").pop() : void 0,
+      rawTokensFilename: opts.rawTokens ? resolve12(opts.rawTokens).split("/").pop() : void 0,
       tokensInline,
       tokenMapInline,
       outDir: process.cwd(),
@@ -13097,7 +13796,64 @@ async function runGenerateSkill(skill, opts, verbose = false) {
   if (skill === "components" && allComponents && sessionId2) {
     const db = openPipelineDb();
     let componentResults;
+    const precomputedCachedNames = parsePrecomputedCachedNames(opts.cachedComponents);
     try {
+      const existingContentfulEntitiesHashInputs = [];
+      if (existingTokensInline) existingContentfulEntitiesHashInputs.push(hashContent(existingTokensInline));
+      const promptHash = await hashPromptForSkill(
+        "components",
+        agent,
+        model,
+        generatePromptPath,
+        existingContentfulEntitiesHashInputs,
+        generatePrompt
+      );
+      if (opts.cacheStatus) {
+        const cacheEnabled = opts.cache !== false && process.env.EDS_NO_CACHE !== "1";
+        const cachedComponents = cacheEnabled ? allComponents.flatMap((component) => {
+          const resolution = resolveComponentCache(db, component, promptHash, allowedComponentNames2);
+          return resolution ? [{ component, resolution }] : [];
+        }) : [];
+        if (cacheEnabled && opts.restoreCache) {
+          const restorations = [];
+          const rekeyed = [];
+          const componentStatus = db.prepare(
+            "SELECT status FROM raw_components WHERE session_id = ? AND component_id = ?"
+          );
+          for (const { component, resolution } of cachedComponents) {
+            const current = componentStatus.get(sessionId2, component.component_id);
+            if (current?.status === "generated") continue;
+            renameEmptySlots(db, sessionId2, component.component_id, component.name, component.slots.length);
+            restorations.push({
+              sourceSessionId: resolution.entry.sourceSessionId,
+              targetSessionId: sessionId2,
+              componentId: component.component_id
+            });
+            rekeyed.push({ component, cached: resolution.entry });
+          }
+          copyComponentsFromCache(db, restorations, { allowedComponentNames: allowedComponentNames2 });
+          storeCaches(
+            db,
+            rekeyed.map(({ component, cached }) => ({
+              inputHash: hashComponentShape(normalizeComponentForCache(component)),
+              entityType: "component",
+              entityId: component.component_id,
+              sourceSessionId: cached.sourceSessionId,
+              humanEdited: cached.humanEdited,
+              promptHash
+            }))
+          );
+        }
+        const fullyCached = cacheEnabled && cachedComponents.length === allComponents.length;
+        process.stdout.write(`cache-status=${fullyCached ? "hit" : "miss"}
+`);
+        process.stdout.write(
+          `cache-components=${JSON.stringify(cachedComponents.map(({ component }) => component.name))}
+`
+        );
+        await exitWithAnalytics(0);
+        return;
+      }
       componentResults = await runAllComponents(
         {
           agent,
@@ -13107,10 +13863,13 @@ async function runGenerateSkill(skill, opts, verbose = false) {
           tokensInline,
           tokenMapInline,
           verbose,
+          noCache: opts.cache === false || process.env.EDS_NO_CACHE === "1",
           skillPathOverride: generatePromptPath,
           skillContentOverride: generatePrompt,
+          promptHash,
           existingContentfulEntities,
           existingTokensInline,
+          precomputedCachedNames,
           allowedComponentNames: allowedComponentNames2
         },
         allComponents
@@ -13119,7 +13878,8 @@ async function runGenerateSkill(skill, opts, verbose = false) {
       db.close();
     }
     const failed = componentResults.filter((r) => r.failed);
-    const generated = componentResults.filter((r) => !r.failed);
+    const cachedResults = componentResults.filter((r) => r.cached);
+    const generated = componentResults.filter((r) => !r.failed && !r.cached);
     const allWarnings = componentResults.flatMap((r) => r.warnings.map((w) => `  ${r.componentName}: ${w}`));
     if (allWarnings.length > 0) {
       process.stderr.write(c.yellow("Warnings:") + "\n" + allWarnings.join("\n") + "\n");
@@ -13135,17 +13895,21 @@ async function runGenerateSkill(skill, opts, verbose = false) {
     const totalExcluded = generated.reduce((s, r) => s + r.excluded, 0);
     const totalRenamedSlots = componentResults.reduce((s, r) => s + r.renamedSlotsCount, 0);
     const allOk = failed.length === 0;
+    const cachedNote = cachedResults.length > 0 ? c.dim(`  (${cachedResults.length} cached)`) : "";
     process.stderr.write(
-      (allOk ? c.green("\u2713") : c.yellow("\u26A0")) + `  ${generated.length}/${componentResults.length} components` + c.dim(`  ${totalClassified} classified, ${totalExcluded} unattached`) + "\n"
+      (allOk ? c.green("\u2713") : c.yellow("\u26A0")) + `  ${generated.length + cachedResults.length}/${componentResults.length} components` + cachedNote + c.dim(`  ${totalClassified} classified, ${totalExcluded} unattached`) + "\n"
     );
     process.stdout.write(`renamed-slots: ${totalRenamedSlots}
 `);
-    if (generated.length === 0) {
+    if (generated.length === 0 && cachedResults.length === 0) {
       die(
         `Error: all ${componentResults.length} component(s) failed to generate \u2014 see the per-component errors above.`
       );
     }
   } else if (skill === "tokens") {
+    const noCache = opts.cache === false || process.env.EDS_NO_CACHE === "1";
+    const tokenInputContent = rawTokensInline ?? "";
+    const tokenInputHash = hashTokenContent(tokenInputContent);
     const db = openPipelineDb();
     try {
       let resolvedSessionId = opts.session;
@@ -13172,11 +13936,26 @@ async function runGenerateSkill(skill, opts, verbose = false) {
       }
       sessionId2 = resolvedSessionId;
       await bindAnalyticsSessionId(resolvedSessionId);
+      const tokenPromptHash = await hashPromptForSkill("tokens", agent, model);
+      if (!noCache) {
+        const tokenCached = lookupCache(db, tokenInputHash, "token_set", "__tokens__", tokenPromptHash);
+        if (tokenCached) {
+          copyTokensFromCache(db, tokenCached.sourceSessionId, resolvedSessionId);
+          sessionId2 = resolvedSessionId;
+          process.stderr.write(
+            `Done: tokens reused from cache ${c.dim(`(source: ${tokenCached.sourceSessionId.slice(0, 12)})`)}
+`
+          );
+          db.close();
+          await showGenerateView({ skill, agent, sessionId: sessionId2 ?? "" });
+          return;
+        }
+      }
       const prompt = await buildPrompt({
         skill,
         mode: "autonomous",
         rawTokensInline,
-        rawTokensFilename: opts.rawTokens ? resolve11(opts.rawTokens).split("/").pop() : void 0,
+        rawTokensFilename: opts.rawTokens ? resolve12(opts.rawTokens).split("/").pop() : void 0,
         tokensInline,
         tokenMapInline,
         outDir: process.cwd()
@@ -13213,6 +13992,9 @@ ${tokenWarnings.map((w) => `  ${w}`).join("\n")}
 `);
       }
       applyTokenToolCalls(db, resolvedSessionId, tokenCalls, []);
+      if (!noCache) {
+        storeCache(db, tokenInputHash, "token_set", "__tokens__", resolvedSessionId, false, tokenPromptHash);
+      }
       sessionId2 = resolvedSessionId;
       const groupCount = tokenCalls.filter((tc) => tc.tool === "set_group").length;
       process.stderr.write(`Done: ${tokenCount} tokens, ${groupCount} groups stored
@@ -13224,7 +14006,10 @@ ${tokenWarnings.map((w) => `  ${w}`).join("\n")}
   await showGenerateView({ skill, agent, sessionId: sessionId2 ?? "" });
 }
 function addAgentFlags(cmd) {
-  return addAgentModelOptions(cmd).option("--verbose", "Show full agent output including reasoning text").option("--dry-run", "Print the prompt without invoking the agent");
+  return addAgentModelOptions(cmd).option("--verbose", "Show full agent output including reasoning text").option("--dry-run", "Print the prompt without invoking the agent").option(
+    "--no-cache",
+    "Bypass ALL fine-grained caches (extract, select, generate) and force AI re-run. Cache keys now factor in prompt content \u2014 changing the prompt file via --generate-prompt-path or --select-prompt-path will already bust the corresponding stage. Use --no-cache to force a full re-run."
+  );
 }
 function registerInternalGenerateCommand(program) {
   const generate = program.command("__generate", { hidden: true }).description("Internal import pipeline generation command");
@@ -13240,6 +14025,12 @@ function registerInternalGenerateCommand(program) {
     "--existing-entities-path <path>",
     "Path to the .existing-entities.json file written after CMA credentials are supplied. When present, per-component prompts include a summary of the target space so classifications can align to existing prop names/tokens. Missing/malformed files are treated as no-op."
   );
+  componentsCmd.option("--cache-status", "Check whether all selected component definitions are cached");
+  componentsCmd.option("--restore-cache", "Restore cached component definitions into the current session");
+  componentsCmd.option(
+    "--cached-components <json>",
+    "Component names already restored by a prior cache-status lookup; skip per-component cache lookup"
+  );
   addAgentFlags(componentsCmd).action(async (opts) => {
     await runGenerateSkill("components", opts, opts.verbose ?? false);
   });
@@ -13265,6 +14056,7 @@ var init_command = __esm({
     init_agent_output();
     init_GenerateView();
     init_db();
+    init_cache_keys();
     init_read_existing_contentful_entities_from_session();
     init_summarize_existing_contentful_entities();
     init_resolve_session_id();
@@ -13980,7 +14772,7 @@ var init_user_agent = __esm({
 // packages/experience-design-system-cli-legacy/src/apply/api-client.ts
 import { parseCDFComponents } from "@contentful/experience-design-system-types";
 function defaultSleep(delayMs) {
-  return new Promise((resolve20) => setTimeout(resolve20, delayMs));
+  return new Promise((resolve22) => setTimeout(resolve22, delayMs));
 }
 function isTransientStatus(status) {
   return status >= 500 && status <= 599;
@@ -14370,7 +15162,7 @@ ${trimmed}`;
             const progress = maxAttempts > 1 ? attempt / (maxAttempts - 1) : 0;
             const baseDelay = intervalMs + (maxIntervalMs - intervalMs) * progress;
             const jitter = Math.random() * baseDelay * 0.15;
-            await new Promise((resolve20) => setTimeout(resolve20, baseDelay + jitter));
+            await new Promise((resolve22) => setTimeout(resolve22, baseDelay + jitter));
           }
         }
         throw new Error(`Operation ${operationId} timed out after ${maxAttempts} attempts`);
@@ -15180,7 +15972,7 @@ var init_terminal_capabilities = __esm({
 
 // packages/experience-design-system-cli-legacy/src/apply/command.ts
 import { createElement as createElement2 } from "react";
-import { readFile as readFile12, readdir as readdir2, stat as stat2 } from "node:fs/promises";
+import { readFile as readFile13, readdir as readdir2, stat as stat2 } from "node:fs/promises";
 import { join as join16 } from "node:path";
 import {
   validateCDF,
@@ -15201,7 +15993,7 @@ function dieWithApiError(error) {
 async function readJsonFile(flag, p) {
   let text;
   try {
-    text = await readFile12(p, "utf8");
+    text = await readFile13(p, "utf8");
   } catch {
     return await die2(`Error: file not found: ${p} (from ${flag})`);
   }
@@ -15255,7 +16047,7 @@ async function readTokensFromPath(flag, p) {
     for (const file of files.sort()) {
       let text;
       try {
-        text = await readFile12(file, "utf8");
+        text = await readFile13(file, "utf8");
       } catch {
         continue;
       }
@@ -15624,11 +16416,11 @@ var init_command2 = __esm({
 });
 
 // packages/experience-design-system-cli-legacy/src/print/validate/validators/read-json-file.ts
-import { readFile as readFile13 } from "node:fs/promises";
+import { readFile as readFile14 } from "node:fs/promises";
 async function readJsonFile2(filePath) {
   let content;
   try {
-    content = await readFile13(filePath, "utf-8");
+    content = await readFile14(filePath, "utf-8");
   } catch (err) {
     return {
       ok: false,
@@ -16039,7 +16831,7 @@ var init_ValidateView = __esm({
 // packages/experience-design-system-cli-legacy/src/print/command.ts
 import { createElement as createElement3 } from "react";
 import { access as access3, mkdir as mkdir3, stat as stat3, writeFile as writeFile3 } from "node:fs/promises";
-import { basename as basename5, resolve as resolve12 } from "node:path";
+import { basename as basename5, resolve as resolve13 } from "node:path";
 import { CDF_SCHEMA_URL } from "@contentful/experience-design-system-types";
 async function die3(message) {
   process.stderr.write(`${message}
@@ -16106,7 +16898,7 @@ function registerPrintCommand(program) {
     "--allow-empty",
     "Write an empty-but-present CDF file when no components are accepted (a subsequent push then removes ALL components from the target space). Without this, an empty accepted set is an error."
   ).action(async (opts) => {
-    const outPath = resolve12(opts.out);
+    const outPath = resolve13(opts.out);
     await assertOutIsNotDirectory(outPath);
     const sessionId2 = await resolveSession(opts.session, "generate components");
     await bindAnalyticsSessionId(sessionId2);
@@ -16154,7 +16946,7 @@ function registerPrintCommand(program) {
 `
       );
     }
-    await mkdir3(resolve12(outPath, ".."), { recursive: true });
+    await mkdir3(resolve13(outPath, ".."), { recursive: true });
     await writeFile3(outPath, `${JSON.stringify(cdfObj, null, 2)}
 `);
     process.stdout.write(
@@ -16163,7 +16955,7 @@ function registerPrintCommand(program) {
     );
   });
   print.command("tokens").description("Write generated tokens to a DTCG JSON file").option("--session <id>", "Session ID to print from (default: most recent generate tokens session)").option("--out <path>", "Output file path", "tokens.json").action(async (opts) => {
-    const outPath = resolve12(opts.out);
+    const outPath = resolve13(opts.out);
     await assertOutIsNotDirectory(outPath);
     const sessionId2 = await resolveSession(opts.session, "generate tokens");
     await bindAnalyticsSessionId(sessionId2);
@@ -16178,7 +16970,7 @@ function registerPrintCommand(program) {
       await die3(`Error: no generated tokens in session '${sessionId2}'. Run generate tokens first.`);
     }
     const tree = rebuildDTCGTree(result.groups, result.tokens);
-    await mkdir3(resolve12(outPath, ".."), { recursive: true });
+    await mkdir3(resolve13(outPath, ".."), { recursive: true });
     await writeFile3(outPath, `${JSON.stringify(tree, null, 2)}
 `);
     process.stdout.write(
@@ -16327,7 +17119,7 @@ function MapTokensView({ result, onExit }) {
     const timer = setTimeout(onExit, 100);
     return () => clearTimeout(timer);
   }, [onExit]);
-  const summary = `${result.applied} mapping${result.applied === 1 ? "" : "s"} applied`;
+  const summary = result.cached ? "reused from cache" : `${result.applied} mapping${result.applied === 1 ? "" : "s"} applied`;
   return /* @__PURE__ */ jsx8(
     CommandCompletionView,
     {
@@ -16461,8 +17253,8 @@ var init_resolve_defaults = __esm({
 
 // packages/experience-design-system-cli-legacy/src/map-tokens/command.ts
 import { createElement as createElement4 } from "react";
-import { readFile as readFile14 } from "node:fs/promises";
-import { resolve as resolve13 } from "node:path";
+import { readFile as readFile15 } from "node:fs/promises";
+import { resolve as resolve14 } from "node:path";
 async function renderResult(result) {
   if (process.stdout.isTTY) {
     const { waitUntilExit } = renderWithGoodbye(
@@ -16470,13 +17262,12 @@ async function renderResult(result) {
     );
     await waitUntilExit();
   } else {
-    process.stdout.write(
-      `map tokens complete
+    const summary = result.cached ? "cached" : `${result.applied} mapping(s) applied`;
+    process.stdout.write(`map tokens complete
 agent: ${result.agent}
 session=${result.sessionId}
-${result.applied} mapping(s) applied
-`
-    );
+${summary}
+`);
     await exitWithAnalytics(0);
   }
 }
@@ -16498,7 +17289,7 @@ async function runMapTokens(opts) {
   let mapPromptPath;
   if (mapPromptOverride?.kind === "text") mapPromptText = mapPromptOverride.value;
   if (mapPromptOverride?.kind === "path") {
-    mapPromptPath = resolve13(mapPromptOverride.value);
+    mapPromptPath = resolve14(mapPromptOverride.value);
     try {
       await resolvePromptOverride(mapPromptOverride);
     } catch (error) {
@@ -16518,7 +17309,7 @@ async function runMapTokens(opts) {
     const knownTokenPaths = new Set(tokenLeaves.map((t) => t.path));
     const tokenMapDiagnostics = [];
     if (opts.tokenMap) {
-      const fileMappings = JSON.parse(await readFile14(opts.tokenMap, "utf8"));
+      const fileMappings = JSON.parse(await readFile15(opts.tokenMap, "utf8"));
       const validMappings = {};
       for (const [rawName, path] of Object.entries(fileMappings)) {
         if (knownTokenPaths.has(path)) {
@@ -16596,7 +17387,7 @@ ${defaultDiagnostics.map((diagnostic) => `  ${diagnostic}`).join("\n")}
     let existingTokensInline;
     if (opts.existingEntitiesPath) {
       const existingContentfulEntities = await readExistingContentfulEntitiesFromSession(
-        resolve13(opts.existingEntitiesPath)
+        resolve14(opts.existingEntitiesPath)
       );
       if (existingContentfulEntities) {
         existingTokensInline = JSON.stringify(summarizeForMapTokens(existingContentfulEntities));
@@ -16631,10 +17422,30 @@ ${defaultDiagnostics.map((diagnostic) => `  ${diagnostic}`).join("\n")}
         skipAgent: "true"
       });
       updateStep(db, stepId2, "complete", { applied: "0", skipAgent: "true" });
-      await renderResult({ agent: resultAgent, sessionId: sessionId2, applied: 0 });
+      await renderResult({ agent: resultAgent, sessionId: sessionId2, applied: 0, cached: false });
       return;
     }
     const agent = configuredAgent;
+    const noCache = opts.cache === false || process.env.EDS_NO_CACHE === "1";
+    const promptHash = await hashPromptForSkill(
+      "map-tokens",
+      agent,
+      model,
+      void 0,
+      existingTokensInline ? [hashContent(existingTokensInline)] : [],
+      mapPromptText
+    );
+    const inputHash = computeMapTokensInputHash(db, sessionId2, componentSourceRefs);
+    if (!noCache) {
+      const cached = lookupCache(db, inputHash, "token_mapping", "__map_tokens__", promptHash);
+      if (cached) {
+        const appliedFromCache = copyMapTokensFromCache(db, cached.sourceSessionId, sessionId2);
+        const stepId2 = createStep(db, sessionId2, "map tokens", { agent, model: model ?? "" });
+        updateStep(db, stepId2, "complete", { cached: "true", applied: String(appliedFromCache) });
+        await renderResult({ agent, sessionId: sessionId2, applied: appliedFromCache, cached: true });
+        return;
+      }
+    }
     const binary = resolveAgentBinary(agent);
     if (!await assertBinaryInPath(binary)) {
       die(
@@ -16654,20 +17465,23 @@ Install it, choose another agent with --agent, or use --print-prompt to run the
     }
     const { calls, warnings: parseWarnings } = parseMapTokenPropToolCallLines(result.stdout);
     const { applied, warnings } = applyMapTokenPropCalls(db, sessionId2, calls, parseWarnings);
+    if (!noCache) {
+      storeCache(db, inputHash, "token_mapping", "__map_tokens__", sessionId2, false, promptHash);
+    }
     updateStep(db, stepId, "complete", { applied: String(applied), warnings: String(warnings.length) });
     if (warnings.length > 0) {
       process.stderr.write(`Warnings:
 ${warnings.map((w) => `  ${w}`).join("\n")}
 `);
     }
-    await renderResult({ agent, sessionId: sessionId2, applied });
+    await renderResult({ agent, sessionId: sessionId2, applied, cached: false });
   } finally {
     db.close();
   }
 }
 function registerMapTokensCommand(program) {
   const map = program.command("map", { hidden: true }).description("Suggest token restrictions for generated design-token props");
-  const tokensCmd = map.command("tokens").description("Invoke a coding agent to suggest $token.allowed for design-category token props").option("--session <id>", "Session ID from generate components (defaults to most recent)").option("--print-prompt", "Print the prompt without invoking the agent").option("--skip-agent", "Resolve token defaults without agentic $token.allowed inference").option(
+  const tokensCmd = map.command("tokens").description("Invoke a coding agent to suggest $token.allowed for design-category token props").option("--session <id>", "Session ID from generate components (defaults to most recent)").option("--print-prompt", "Print the prompt without invoking the agent").option("--skip-agent", "Resolve token defaults without agentic $token.allowed inference").option("--no-cache", "Bypass the map-tokens cache and force a re-run").option(
     "--prompt <stage=value>",
     "Override a stage prompt (repeatable). Used here for the map-tokens stage.",
     (v, acc) => [...acc, v],
@@ -16687,6 +17501,7 @@ var init_command4 = __esm({
     init_render_with_goodbye();
     init_src();
     init_db();
+    init_cache_keys();
     init_read_existing_contentful_entities_from_session();
     init_summarize_existing_contentful_entities();
     init_command3();
@@ -16703,7 +17518,7 @@ var init_command4 = __esm({
 });
 
 // packages/experience-design-system-cli-legacy/src/import/path-utils.ts
-import { resolve as resolve14 } from "node:path";
+import { resolve as resolve15 } from "node:path";
 import { homedir as homedir5 } from "node:os";
 function expandTilde(input) {
   if (input === "~" || input.startsWith("~/") || input.startsWith("~\\")) {
@@ -16717,7 +17532,7 @@ function normalizePath(input) {
     p = p.slice(1, -1);
   }
   p = expandTilde(p);
-  return resolve14(p);
+  return resolve15(p);
 }
 var init_path_utils = __esm({
   "packages/experience-design-system-cli-legacy/src/import/path-utils.ts"() {
@@ -16942,7 +17757,7 @@ var init_save_path_resolver = __esm({
 });
 
 // packages/experience-design-system-cli-legacy/src/runs/store.ts
-import { readFile as readFile15, writeFile as writeFile4, mkdir as mkdir4, rename } from "node:fs/promises";
+import { readFile as readFile16, writeFile as writeFile4, mkdir as mkdir4, rename } from "node:fs/promises";
 import { join as join20 } from "node:path";
 import { homedir as homedir6 } from "node:os";
 import { randomBytes as randomBytes2 } from "node:crypto";
@@ -16982,7 +17797,7 @@ function migrateRecord(rec) {
 }
 async function readFileMaybe() {
   try {
-    const raw = await readFile15(RUNS_PATH, "utf8");
+    const raw = await readFile16(RUNS_PATH, "utf8");
     const parsed = JSON.parse(raw);
     if (!READABLE_VERSIONS.has(parsed.version)) {
       throw new Error(
@@ -17046,15 +17861,15 @@ var init_store = __esm({
 });
 
 // packages/experience-design-system-cli-legacy/src/runs/fingerprint.ts
-import { createHash as createHash2 } from "node:crypto";
-import { readFile as readFile16, stat as stat4 } from "node:fs/promises";
-import { resolve as resolve15 } from "node:path";
+import { createHash as createHash6 } from "node:crypto";
+import { readFile as readFile17, stat as stat4 } from "node:fs/promises";
+import { resolve as resolve16 } from "node:path";
 function rowField(row, key) {
   const v = row[key];
   return typeof v === "string" ? v : null;
 }
 function sha256Hex(buf) {
-  return createHash2("sha256").update(buf).digest("hex");
+  return createHash6("sha256").update(buf).digest("hex");
 }
 async function buildSourceFingerprint(opts) {
   const rows = opts.db.prepare("SELECT name, source_path FROM raw_components WHERE session_id = ?").all(opts.extractSessionId);
@@ -17064,7 +17879,7 @@ async function buildSourceFingerprint(opts) {
     const sourcePath = rowField(row, "source_path");
     const name = rowField(row, "name");
     if (!sourcePath) continue;
-    const abs = resolve15(sourcePath);
+    const abs = resolve16(sourcePath);
     if (seen.has(abs)) continue;
     seen.add(abs);
     try {
@@ -17079,10 +17894,10 @@ async function buildSourceFingerprint(opts) {
   let rawTokensMtime = null;
   let rawTokensContentHash = null;
   if (opts.rawTokensPath) {
-    const abs = resolve15(opts.rawTokensPath);
+    const abs = resolve16(opts.rawTokensPath);
     rawTokensPath = abs;
     try {
-      const [st, buf] = await Promise.all([stat4(abs), readFile16(abs)]);
+      const [st, buf] = await Promise.all([stat4(abs), readFile17(abs)]);
       rawTokensMtime = st.mtime.toISOString();
       rawTokensContentHash = sha256Hex(buf);
     } catch {
@@ -18837,11 +19652,11 @@ var init_slot_graph = __esm({
 });
 
 // packages/experience-design-system-cli-legacy/src/analyze/select/parser.ts
-import { createHash as createHash3 } from "node:crypto";
+import { createHash as createHash7 } from "node:crypto";
 import { access as access5 } from "node:fs/promises";
-import { isAbsolute, relative, resolve as resolve16 } from "node:path";
+import { isAbsolute, relative, resolve as resolve17 } from "node:path";
 function createComponentId(name, resolvedSourcePath) {
-  const sourceHash = createHash3("sha256").update(`${name}:${resolvedSourcePath}`).digest("hex").slice(0, 12);
+  const sourceHash = createHash7("sha256").update(`${name}:${resolvedSourcePath}`).digest("hex").slice(0, 12);
   return `${name}-${sourceHash}`;
 }
 async function resolveComponentSourcePath(source, reviewRoot) {
@@ -18853,7 +19668,7 @@ async function resolveComponentSourcePath(source, reviewRoot) {
       throw new Error(`Unable to access component source at ${source}`);
     }
   }
-  const candidate = resolve16(reviewRoot, source);
+  const candidate = resolve17(reviewRoot, source);
   const relativeToRoot = relative(reviewRoot, candidate);
   if (relativeToRoot.startsWith("..") || relativeToRoot === ".." || isAbsolute(relativeToRoot)) {
     throw new Error(
@@ -18868,7 +19683,7 @@ async function resolveComponentSourcePath(source, reviewRoot) {
   }
 }
 async function loadReviewInput(components, options = {}) {
-  const reviewRoot = resolve16(options.reviewRoot ?? process.cwd());
+  const reviewRoot = resolve17(options.reviewRoot ?? process.cwd());
   const records = await Promise.all(
     components.map(async (component) => {
       let resolvedSourcePath;
@@ -18899,7 +19714,7 @@ var init_parser = __esm({
 });
 
 // packages/experience-design-system-cli-legacy/src/analyze/select/command.ts
-import { access as access6, readFile as readFile17 } from "node:fs/promises";
+import { access as access6, readFile as readFile18 } from "node:fs/promises";
 async function loadAndValidateForReview(sessionId2, projectRoot) {
   const db = openPipelineDb();
   let rawComponents;
@@ -18917,7 +19732,7 @@ async function patchReviewStateWithValidationErrors(sessionId2, errors, opts = {
   let snapshot;
   try {
     await access6(paths.statePath);
-    snapshot = JSON.parse(await readFile17(paths.statePath, "utf8"));
+    snapshot = JSON.parse(await readFile18(paths.statePath, "utf8"));
   } catch {
     snapshot = await loadAndValidateForReview(sessionId2, void 0);
     snapshot = await ensureRefineSession(sessionId2, artifactsRoot, snapshot);
@@ -18968,7 +19783,7 @@ async function rejectComponentsByName(sessionId2, names, opts = {}) {
   const nameSet = new Set(names);
   let snapshot;
   try {
-    snapshot = JSON.parse(await readFile17(paths.statePath, "utf8"));
+    snapshot = JSON.parse(await readFile18(paths.statePath, "utf8"));
   } catch {
     return;
   }
@@ -19067,9 +19882,9 @@ function spawnGenerateChild(opts) {
     stderr += chunk;
     opts.onStderr?.(chunk);
   });
-  const donePromise = new Promise((resolve20) => {
+  const donePromise = new Promise((resolve22) => {
     child.on("close", (code, signal) => {
-      resolve20({
+      resolve22({
         exitCode: code ?? 0,
         signal: signal ?? null,
         stdout,
@@ -19077,7 +19892,7 @@ function spawnGenerateChild(opts) {
       });
     });
     child.on("error", (err) => {
-      resolve20({
+      resolve22({
         exitCode: 1,
         signal: null,
         stdout,
@@ -27215,6 +28030,9 @@ function shouldGenerateAfterCredentialsValidated(opts) {
 function shouldSkipFinalReviewAfterCredentials(state) {
   return state.finalReviewPassed && state.generateSessionId != null;
 }
+function resolveNoCacheForGenerate(opts) {
+  return opts.cliNoCache;
+}
 function shouldBypassPreview(state) {
   return state.credentialsSkipped === true;
 }
@@ -27241,43 +28059,70 @@ var init_wizard_state_transitions = __esm({
 async function runSelectionAgent(options) {
   const db = openPipelineDb();
   let components;
+  const cachedDecisions = /* @__PURE__ */ new Map();
+  const cliVersion2 = await getCliCacheVersion();
+  const promptHash = await hashPromptForSkill(
+    "select",
+    options.agent,
+    options.model,
+    options.promptPath,
+    [SELECT_PAYLOAD_FORMAT],
+    options.promptText
+  );
   try {
     components = loadRawComponents(db, options.sessionId);
+    if (!options.noCache) {
+      for (const component of components) {
+        const componentHash = hashComponentShape(component);
+        const cached = lookupSelectCache(db, componentHash, promptHash, cliVersion2);
+        if (cached) {
+          cachedDecisions.set(component.name, {
+            decision: cached.decision,
+            reason: cached.reason
+          });
+        }
+      }
+    }
   } finally {
     db.close();
   }
   if (components.length === 0) return;
-  const invoker2 = createLocalCliAgentInvoker({
-    onDebugEvent: (name, payload) => getDebugLogger().event("agent", name, payload)
-  });
-  const selectBuckets = bucketComponentsProps(components);
-  for (const assignment of selectBuckets) {
-    getDebugLogger().event("analyze", "prop-buckets.select", { ...assignment });
-  }
-  const prompt = await buildPrompt({
-    skill: "select",
-    mode: "autonomous",
-    rawComponentsInline: JSON.stringify(
-      components.map((component) => ({ ...component, props: component.props.map(stripPropProvenance) })),
-      null,
-      2
-    ),
-    propBucketsInline: JSON.stringify(selectBuckets),
-    outDir: process.cwd(),
-    ...options.promptText !== void 0 ? { skillContentOverride: options.promptText } : {},
-    ...options.promptText === void 0 && options.promptPath ? { skillPathOverride: options.promptPath } : {}
-  });
-  const { result } = await invokeAgentWithOutput(
-    invoker2,
-    { agent: options.agent, model: options.model, prompt, timeoutMs: DEFAULT_TIMEOUT_MS4 },
-    false
-  );
-  if (result.timedOut) throw new Error("selection agent timed out");
-  if (result.exitCode !== 0) throw new Error(`selection agent exited with code ${result.exitCode}`);
-  const parsed = parseSelectToolCallLines(result.stdout);
-  for (const warning of parsed.warnings) process.stderr.write(`Warning: selection agent: ${warning}
+  const componentsToRun = components.filter((component) => !cachedDecisions.has(component.name));
+  let calls = [];
+  if (componentsToRun.length > 0) {
+    const invoker2 = createLocalCliAgentInvoker({
+      onDebugEvent: (name, payload) => getDebugLogger().event("agent", name, payload)
+    });
+    const selectBuckets = bucketComponentsProps(componentsToRun);
+    for (const assignment of selectBuckets) {
+      getDebugLogger().event("analyze", "prop-buckets.select", { ...assignment });
+    }
+    const prompt = await buildPrompt({
+      skill: "select",
+      mode: "autonomous",
+      rawComponentsInline: JSON.stringify(
+        componentsToRun.map((component) => ({ ...component, props: component.props.map(stripPropProvenance) })),
+        null,
+        2
+      ),
+      propBucketsInline: JSON.stringify(selectBuckets),
+      outDir: process.cwd(),
+      ...options.promptText !== void 0 ? { skillContentOverride: options.promptText } : {},
+      ...options.promptText === void 0 && options.promptPath ? { skillPathOverride: options.promptPath } : {}
+    });
+    const { result } = await invokeAgentWithOutput(
+      invoker2,
+      { agent: options.agent, model: options.model, prompt, timeoutMs: DEFAULT_TIMEOUT_MS4 },
+      false
+    );
+    if (result.timedOut) throw new Error("selection agent timed out");
+    if (result.exitCode !== 0) throw new Error(`selection agent exited with code ${result.exitCode}`);
+    const parsed = parseSelectToolCallLines(result.stdout);
+    for (const warning of parsed.warnings) process.stderr.write(`Warning: selection agent: ${warning}
 `);
-  const byName = new Map(parsed.calls.map((call) => [call.name, call]));
+    calls = parsed.calls;
+  }
+  const byName = new Map(calls.map((call) => [call.name, call]));
   const writeDb = openPipelineDb();
   try {
     writeDb.exec("BEGIN");
@@ -27285,15 +28130,27 @@ async function runSelectionAgent(options) {
       `UPDATE raw_components SET status = ?, reject_reason = ? WHERE session_id = ? AND component_id = ?`
     );
     for (const component of components) {
+      const cached = cachedDecisions.get(component.name);
       const call = byName.get(component.name);
-      if (!call) continue;
-      const rejected = call.tool === "reject_component";
+      if (!cached && !call) continue;
+      const rejected = cached ? cached.decision === "rejected" : call.tool === "reject_component";
+      const reason = cached ? cached.reason : call.reason ?? null;
       update.run(
         rejected ? "rejected" : "accepted",
-        rejected ? call.reason ?? null : null,
+        rejected ? reason : null,
         options.sessionId,
         component.component_id
       );
+      if (!cached) {
+        storeSelectCache(
+          writeDb,
+          hashComponentShape(component),
+          promptHash,
+          cliVersion2,
+          rejected ? "rejected" : "accepted",
+          rejected ? reason : null
+        );
+      }
     }
     writeDb.exec("COMMIT");
   } catch (error) {
@@ -27303,7 +28160,7 @@ async function runSelectionAgent(options) {
     writeDb.close();
   }
 }
-var DEFAULT_TIMEOUT_MS4;
+var SELECT_PAYLOAD_FORMAT, DEFAULT_TIMEOUT_MS4;
 var init_run_selection_agent = __esm({
   "packages/experience-design-system-cli-legacy/src/import/tui/run-selection-agent.ts"() {
     "use strict";
@@ -27312,6 +28169,8 @@ var init_run_selection_agent = __esm({
     init_debug_logger();
     init_agent_output();
     init_db();
+    init_cache_keys();
+    SELECT_PAYLOAD_FORMAT = "prop-buckets-v1";
     DEFAULT_TIMEOUT_MS4 = Number(process.env.EDS_AGENT_TIMEOUT_MS ?? 5 * 60 * 1e3);
   }
 });
@@ -27330,7 +28189,7 @@ __export(WizardApp_exports, {
 });
 import { useEffect as useEffect15, useRef as useRef10, useState as useState23 } from "react";
 import { Box as Box42, Text as Text46 } from "ink";
-import { join as join23, resolve as resolve17 } from "node:path";
+import { join as join23, resolve as resolve18 } from "node:path";
 import { appendFileSync as appendFileSync2, writeFileSync } from "node:fs";
 import { access as access7, stat as stat5, writeFile as writeFile6 } from "node:fs/promises";
 import { tmpdir } from "node:os";
@@ -27343,21 +28202,28 @@ function buildGenerateComponentsArgs(opts) {
   if (opts.tokensPath) args.push("--tokens", opts.tokensPath);
   if (opts.model) args.push("--model", opts.model);
   if (opts.bedrock) args.push("--bedrock");
+  if (opts.noCache) args.push("--no-cache");
   if (opts.generatePromptPath) args.push("--generate-prompt-path", opts.generatePromptPath);
   for (const prompt of opts.promptOverrides ?? []) args.push("--prompt", prompt);
   if (opts.existingEntitiesPath) args.push("--existing-entities-path", opts.existingEntitiesPath);
+  if (opts.restoreCache) args.push("--restore-cache");
+  if (opts.cachedComponents && opts.cachedComponents.length > 0) {
+    args.push("--cached-components", JSON.stringify(opts.cachedComponents));
+  }
   return args;
 }
 function buildGenerateTokensArgs(opts) {
   const args = [findCliPath(), "__generate", "tokens", "--agent", opts.agent, "--raw-tokens", opts.rawTokensPath];
   if (opts.model) args.push("--model", opts.model);
   if (opts.bedrock) args.push("--bedrock");
+  if (opts.noCache) args.push("--no-cache");
   for (const prompt of opts.promptOverrides ?? []) args.push("--prompt", prompt);
   return args;
 }
 function buildMapTokensArgs(opts) {
   const args = ["map", "tokens", "--session", opts.sessionId, "--agent", opts.agent];
   if (opts.model) args.push("--model", opts.model);
+  if (opts.noCache) args.push("--no-cache");
   if (opts.skipAgent) args.push("--skip-agent");
   for (const prompt of opts.promptOverrides ?? []) args.push("--prompt", prompt);
   if (opts.existingEntitiesPath) args.push("--existing-entities-path", opts.existingEntitiesPath);
@@ -27449,6 +28315,7 @@ function WizardApp({
   initialProjectPath,
   host,
   promptOverrides,
+  noCache = false,
   livePreview = true,
   generatePromptPath,
   skipMapTokens = false,
@@ -27473,6 +28340,7 @@ function WizardApp({
   });
   const allowEmptyDeleteAllRef = useRef10(false);
   const generateChildRef = useRef10(null);
+  const generationCachePreflightRef = useRef10(null);
   const selectionToReviewStartedAtRef = useRef10(null);
   const credentialsValidationIdRef = useRef10(0);
   const pendingCredentialValidationRef = useRef10(null);
@@ -27487,8 +28355,9 @@ function WizardApp({
   const existingEntitiesPromiseRef = useRef10(null);
   const generatePromiseRef = useRef10(null);
   const rawTokensEntryReady = !!initialRawTokensPath;
+  const effectiveNoCache = resolveNoCacheForGenerate({ cliNoCache: noCache });
   const initialStepResolved = rawTokensEntryReady ? initialProjectPath ? "path-validation" : "credentials" : initialProjectPath ? "token-input" : "welcome";
-  const initialOutDir = initialProjectPath ? join23(resolve17(initialProjectPath), ".contentful") : "";
+  const initialOutDir = initialProjectPath ? join23(resolve18(initialProjectPath), ".contentful") : "";
   const [state, setState] = useState23({
     step: initialStepResolved,
     agent: initialAgent ?? "claude",
@@ -27664,13 +28533,14 @@ If you are using AWS Bedrock, run:
     if (!deferStep) update({ step: nextStep });
     return true;
   };
-  const runGenerateTokens = async (rawTokensPath, outDir) => {
+  const runGenerateTokens = async (rawTokensPath, outDir, forceRegenerate = false) => {
     update({ tokenGenerationStatus: "running" });
     const tokenArgs = buildGenerateTokensArgs({
       rawTokensPath,
       agent: state.agent,
       ...state.agentModel ? { model: state.agentModel } : {},
       ...state.bedrock ? { bedrock: true } : {},
+      noCache: effectiveNoCache || forceRegenerate,
       promptOverrides
     });
     const result = await runSpawnedCli(tokenArgs);
@@ -27719,6 +28589,7 @@ If you are using AWS Bedrock, run:
     const timer = startWizardTimer("token-mapping", {
       sessionId: sessionId2,
       silent,
+      noCache: effectiveNoCache,
       skipAgent: skipMapTokens
     });
     let mappablePropCount = 0;
@@ -27727,7 +28598,7 @@ If you are using AWS Bedrock, run:
       const db = openPipelineDb();
       try {
         if (state.tokenSessionId && state.tokenSessionId !== sessionId2) {
-          copyTokensBetweenSessions(db, state.tokenSessionId, sessionId2);
+          copyTokensFromCache(db, state.tokenSessionId, sessionId2);
         } else if (!state.tokenSessionId && state.tokensPath) {
           const tokens = await readTokensFromPath("tokens", state.tokensPath);
           storeDtcgTokens(db, sessionId2, [], tokens);
@@ -27767,6 +28638,7 @@ If you are using AWS Bedrock, run:
       sessionId: sessionId2,
       agent: state.agent,
       ...state.agentModel ? { model: state.agentModel } : {},
+      noCache: effectiveNoCache,
       skipAgent: skipMapTokens,
       promptOverrides,
       ...state.existingEntitiesPath ? { existingEntitiesPath: state.existingEntitiesPath } : {}
@@ -27846,7 +28718,7 @@ If you are using AWS Bedrock, run:
     return promise;
   };
   const runExtract = async (projectPath, showProgress = true) => {
-    const outDir = join23(resolve17(projectPath), ".contentful");
+    const outDir = join23(resolve18(projectPath), ".contentful");
     const existingEntitiesExpected = !state.credentialsSkipped && Boolean(state.spaceId && state.environmentId && state.cmaToken && projectPath);
     update({
       ...showProgress ? { step: "extracting" } : {},
@@ -27861,6 +28733,10 @@ If you are using AWS Bedrock, run:
     });
     const existingEntitiesPromise = startExistingEntitiesFetch(projectPath, outDir);
     const extractArgs = [findCliPath(), "__extract", "--project", projectPath];
+    if (effectiveNoCache) extractArgs.push("--composition-refresh", "--no-cache");
+    for (const p of promptOverrides ?? []) extractArgs.push("--prompt", p);
+    if (state.agent) extractArgs.push("--agent", state.agent);
+    if (state.bedrock) extractArgs.push("--bedrock");
     let selectionPromptText;
     let selectionPromptPath;
     try {
@@ -27869,7 +28745,7 @@ If you are using AWS Bedrock, run:
       const selectOverride = overrides.get("select");
       if (selectOverride?.kind === "text") selectionPromptText = selectOverride.value;
       if (selectOverride?.kind === "path") {
-        selectionPromptPath = resolve17(selectOverride.value);
+        selectionPromptPath = resolve18(selectOverride.value);
         await resolvePromptOverride(selectOverride);
       }
     } catch (error) {
@@ -27893,7 +28769,8 @@ If you are using AWS Bedrock, run:
           agent: state.agent,
           ...state.agentModel ? { model: state.agentModel } : {},
           ...selectionPromptText !== void 0 ? { promptText: selectionPromptText } : {},
-          ...selectionPromptPath ? { promptPath: selectionPromptPath } : {}
+          ...selectionPromptPath ? { promptPath: selectionPromptPath } : {},
+          noCache: effectiveNoCache
         });
       })().catch((error) => {
         selectionError = error;
@@ -28038,17 +28915,136 @@ Make sure this path contains TypeScript/React/Vue component files (.tsx, .ts, .v
       generateProgress: null
     }));
   };
-  const buildGenerateOptions = (extractSessionId, tokensPath, generatePromptPath2) => ({
+  const buildGenerateOptions = (extractSessionId, tokensPath, generatePromptPath2, cachedComponents) => ({
     sessionId: extractSessionId,
     tokensPath,
     agent: state.agent,
     ...state.agentModel ? { model: state.agentModel } : {},
     ...state.bedrock ? { bedrock: true } : {},
+    noCache: effectiveNoCache,
     ...state.existingEntitiesPath ? { existingEntitiesPath: state.existingEntitiesPath } : {},
     ...generatePromptPath2 ? { generatePromptPath: generatePromptPath2 } : {},
-    promptOverrides
+    promptOverrides,
+    ...cachedComponents && cachedComponents.length > 0 ? { cachedComponents } : {}
   });
-  const buildGenerateArgs = (extractSessionId, tokensPath, generatePromptPath2) => buildGenerateProcessArgs(buildGenerateOptions(extractSessionId, tokensPath, generatePromptPath2));
+  const buildGenerateArgs = (extractSessionId, tokensPath, generatePromptPath2, cachedComponents) => buildGenerateProcessArgs(buildGenerateOptions(extractSessionId, tokensPath, generatePromptPath2, cachedComponents));
+  const buildGenerateCliArgs = (extractSessionId, tokensPath, generatePromptPath2, cachedComponents) => buildGenerateComponentsArgs(
+    buildGenerateOptions(extractSessionId, tokensPath, generatePromptPath2, cachedComponents)
+  );
+  const checkGenerateCache = async (extractSessionId, tokensPath) => {
+    const timer = startWizardTimer("generation-cache-status", {
+      sessionId: extractSessionId,
+      noCache: effectiveNoCache
+    });
+    if (effectiveNoCache) {
+      finishWizardTimer("generation-cache-status", timer, { status: "skipped" });
+      return false;
+    }
+    const result = await runCli([...buildGenerateCliArgs(extractSessionId, tokensPath), "--cache-status"]);
+    const hit = result.exitCode === 0 && /^cache-status=hit$/m.test(result.stdout);
+    finishWizardTimer("generation-cache-status", timer, {
+      status: hit ? "hit" : "miss",
+      exitCode: result.exitCode,
+      ...result.exitCode !== 0 ? { stderrTail: result.stderr.trim().slice(-500) } : {}
+    });
+    return hit;
+  };
+  const checkGenerateCacheComponents = async (extractSessionId, tokensPath, restoreCache = false) => {
+    const timer = startWizardTimer("generation-cache-components", {
+      sessionId: extractSessionId,
+      restoreCache,
+      noCache: effectiveNoCache
+    });
+    if (effectiveNoCache) {
+      finishWizardTimer("generation-cache-components", timer, { status: "skipped" });
+      return /* @__PURE__ */ new Set();
+    }
+    const args = [...buildGenerateCliArgs(extractSessionId, tokensPath), "--cache-status"];
+    if (restoreCache) args.push("--restore-cache");
+    const result = await runCli(args);
+    if (result.exitCode !== 0) {
+      finishWizardTimer("generation-cache-components", timer, {
+        status: "error",
+        exitCode: result.exitCode,
+        stderrTail: result.stderr.trim().slice(-500)
+      });
+      return /* @__PURE__ */ new Set();
+    }
+    const line = /^cache-components=(.+)$/m.exec(result.stdout)?.[1];
+    if (!line) {
+      finishWizardTimer("generation-cache-components", timer, {
+        status: "missing-output",
+        exitCode: result.exitCode,
+        cachedCount: 0
+      });
+      return /* @__PURE__ */ new Set();
+    }
+    try {
+      const names = JSON.parse(line);
+      const cachedNames = new Set(
+        Array.isArray(names) ? names.filter((name) => typeof name === "string") : []
+      );
+      finishWizardTimer("generation-cache-components", timer, {
+        status: "complete",
+        exitCode: result.exitCode,
+        cachedCount: cachedNames.size
+      });
+      return cachedNames;
+    } catch {
+      finishWizardTimer("generation-cache-components", timer, {
+        status: "invalid-output",
+        exitCode: result.exitCode,
+        cachedCount: 0
+      });
+      return /* @__PURE__ */ new Set();
+    }
+  };
+  useEffect15(() => {
+    if (state.step !== "extracting" && state.step !== "scope-gate" || !state.extractSessionId || state.existingEntitiesStatus === "running" || state.existingEntitiesStatus === "idle" || state.selectionAgentStatus !== "complete" || state.compositionPhase !== "done" && state.compositionPhase !== "cache-hit" || state.rawTokensPath && state.tokenGenerationStatus !== "complete" || effectiveNoCache) {
+      return;
+    }
+    const sessionId2 = state.extractSessionId;
+    if (generationCachePreflightRef.current?.sessionId === sessionId2) return;
+    const timer = startWizardTimer("generation-cache-preflight", { sessionId: sessionId2 });
+    const db = openPipelineDb();
+    let generatedNames = null;
+    try {
+      const rows = db.prepare("SELECT name, status FROM raw_components WHERE session_id = ?").all(sessionId2);
+      if (rows.length > 0 && rows.every((row) => row.status === "generated")) {
+        generatedNames = new Set(rows.map((row) => row.name));
+      }
+    } finally {
+      db.close();
+    }
+    if (generatedNames) {
+      generationCachePreflightRef.current = { sessionId: sessionId2, promise: Promise.resolve(generatedNames) };
+      finishWizardTimer("generation-cache-preflight", timer, {
+        status: "complete",
+        source: "session-db",
+        cachedCount: generatedNames.size
+      });
+      return;
+    }
+    const promise = checkGenerateCacheComponents(sessionId2, state.tokensPath, true);
+    generationCachePreflightRef.current = { sessionId: sessionId2, promise };
+    void promise.then((cachedNames) => {
+      finishWizardTimer("generation-cache-preflight", timer, {
+        status: "complete",
+        source: "cache-status",
+        cachedCount: cachedNames.size
+      });
+    });
+  }, [
+    state.step,
+    state.extractSessionId,
+    state.tokensPath,
+    state.rawTokensPath,
+    state.tokenGenerationStatus,
+    state.selectionAgentStatus,
+    state.compositionPhase,
+    state.existingEntitiesStatus,
+    state.existingEntitiesPath
+  ]);
   const startGeneratePrefetch = (extractSessionId, tokensPath) => {
     const args = buildGenerateArgs(extractSessionId, tokensPath);
     let progressCursor = null;
@@ -28103,13 +29099,14 @@ Make sure this path contains TypeScript/React/Vue component files (.tsx, .ts, .v
     });
     return donePromise;
   };
-  const runGenerate = async (extractSessionId, tokensPath, acceptedCount, suppressScreen = false) => {
+  const runGenerate = async (extractSessionId, tokensPath, acceptedCount, suppressScreen = false, cachedComponents = []) => {
     const timer = startWizardTimer("component-generation", {
       sessionId: extractSessionId,
       acceptedCount,
-      suppressScreen
+      suppressScreen,
+      noCache: effectiveNoCache
     });
-    const args = buildGenerateArgs(extractSessionId, tokensPath, generatePromptPath);
+    const args = buildGenerateArgs(extractSessionId, tokensPath, generatePromptPath, cachedComponents);
     let progressCursor = state.generateProgress;
     const { donePromise } = spawnGenerateChild({
       command: "node",
@@ -28179,6 +29176,25 @@ Make sure this path contains TypeScript/React/Vue component files (.tsx, .ts, .v
       finishSelectionToReviewTimer("error");
     }
   };
+  const finishCachedGeneration = async (sessionId2, acceptedCount) => {
+    if (await runMapTokens2(sessionId2, true)) {
+      finishSelectionToReviewTimer("cached");
+      update(
+        {
+          acceptedCount,
+          autoRejectedCount: 0,
+          generateSessionId: sessionId2,
+          generatedCount: acceptedCount,
+          generateProgress: null,
+          mapTokensStatus: "complete",
+          step: "final-review"
+        },
+        { clearScreen: false }
+      );
+    } else {
+      finishSelectionToReviewTimer("error");
+    }
+  };
   const advanceToPushFlow = (generatedAcceptedCount) => {
     update({ generatedAcceptedCount });
     void runSaveAndPush();
@@ -28363,8 +29379,14 @@ Make sure this path contains TypeScript/React/Vue component files (.tsx, .ts, .v
         }
       }
       if (await runAgentAuthCheck("generating", true)) {
-        update({ step: "generating" });
-        void runGenerate(sid, state.tokensPath, state.acceptedCount);
+        const cacheHit = await checkGenerateCache(sid, state.tokensPath);
+        if (cacheHit) {
+          update({ step: "generating" });
+          void finishCachedGeneration(sid, state.acceptedCount);
+        } else {
+          update({ step: "generating" });
+          void runGenerate(sid, state.tokensPath, state.acceptedCount);
+        }
       }
       return;
     }
@@ -28728,7 +29750,7 @@ If using a custom host configuration, make sure the space exists on that host.`
       });
       return { ok: false };
     }
-    await new Promise((resolve20) => setTimeout(resolve20, SAVE_CONFIRMATION_DELAY_MS));
+    await new Promise((resolve22) => setTimeout(resolve22, SAVE_CONFIRMATION_DELAY_MS));
     update(nextStateAfterPrint({ skipGate: opts.skipGate, componentsPath }));
     return { ok: true };
   };
@@ -28805,6 +29827,12 @@ If using a custom host configuration, make sure the space exists on that host.`
       tokenReuseChecked.current = true;
       const tokenNextStep = state.projectPath ? "path-validation" : "credentials";
       const existingTokensPath = join23(state.outDir, "tokens.json");
+      if (effectiveNoCache) {
+        tokenGenerationPromiseRef.current = runAgentAuthCheck(tokenNextStep).then(
+          (ok2) => ok2 ? runGenerateTokens(state.rawTokensPath, state.outDir) : false
+        );
+        return;
+      }
       (async () => {
         try {
           await access7(existingTokensPath);
@@ -28888,7 +29916,7 @@ If using a custom host configuration, make sure the space exists on that host.`
               const tokenNextStep = state.projectPath ? "path-validation" : "credentials";
               update({ step: tokenNextStep });
               if (await runAgentAuthCheck(tokenNextStep)) {
-                tokenGenerationPromiseRef.current = runGenerateTokens(state.rawTokensPath, state.outDir);
+                tokenGenerationPromiseRef.current = runGenerateTokens(state.rawTokensPath, state.outDir, true);
               }
             },
             onQuit: () => process.exit(0)
@@ -28922,7 +29950,7 @@ If using a custom host configuration, make sure the space exists on that host.`
         );
       case "extracting": {
         const ep = state.extractProgress;
-        const compositionComplete = state.compositionPhase === "done";
+        const compositionComplete = state.compositionPhase === "done" || state.compositionPhase === "cache-hit";
         const tokenGenerationComplete = !state.rawTokensPath || state.tokenGenerationStatus === "complete";
         const extractionTasksComplete = ep !== null && ep.totalFiles > 0 && compositionComplete && state.selectionAgentStatus === "complete" && tokenGenerationComplete && state.existingEntitiesStatus !== "running";
         if (extractionTasksComplete) return null;
@@ -28937,7 +29965,7 @@ If using a custom host configuration, make sure the space exists on that host.`
           extractDetail = "Scanning files...";
         }
         const selectionDetail = state.selectionAgentStatus === "complete" ? "Selection agent complete" : `Filtering component selection via ${state.agent}...`;
-        const compositionDetail = compositionComplete ? "Composition mapping complete" : "Mapping composition from source call sites...";
+        const compositionDetail = state.compositionPhase === "cache-hit" ? "Composition mapping (cached)" : compositionComplete ? "Composition mapping complete" : state.compositionPhase?.startsWith("agent:") ? `Mapping composition via ${state.compositionPhase.slice("agent:".length)}...` : `Mapping composition via ${state.agent}...`;
         return /* @__PURE__ */ jsx50(
           RunningStep,
           {
@@ -28987,6 +30015,29 @@ If using a custom host configuration, make sure the space exists on that host.`
                   acceptedCount: decisions.accepted.length,
                   rejectedCount: decisions.rejected.length
                 }) : null;
+                const preflight = generationCachePreflightRef.current;
+                const cachePromise = preflight?.sessionId === sessionId2 ? preflight.promise : checkGenerateCacheComponents(sessionId2, state.tokensPath, true);
+                if (!preflight || preflight.sessionId !== sessionId2) {
+                  generationCachePreflightRef.current = { sessionId: sessionId2, promise: cachePromise };
+                }
+                const cacheWaitStartedAt = startWizardTimer("selection-cache-restoration-wait", {
+                  sessionId: sessionId2,
+                  preflight: Boolean(preflight?.sessionId === sessionId2)
+                });
+                try {
+                  const cachedNames = await cachePromise;
+                  finishWizardTimer("selection-cache-restoration-wait", cacheWaitStartedAt, {
+                    status: "complete",
+                    cachedCount: cachedNames.size
+                  });
+                } catch (error) {
+                  finishWizardTimer("selection-cache-restoration-wait", cacheWaitStartedAt, {
+                    status: "error",
+                    error: error instanceof Error ? error.message : String(error)
+                  });
+                  finishSelectionToReviewTimer("error");
+                  throw error;
+                }
                 await runScopeGate({
                   sessionId: sessionId2,
                   decisions,
@@ -28995,12 +30046,35 @@ If using a custom host configuration, make sure the space exists on that host.`
                     if (shouldGenerateAfterScopeGate({ acceptedCount })) {
                       const authPromise = runAgentAuthCheck("generating", true);
                       if (await authPromise) {
-                        update({
-                          step: "generating",
-                          generateProgress: null,
-                          acceptedCount
+                        const comparisonStartedAt = startWizardTimer("generation-cache-set-comparison", {
+                          sessionId: sid,
+                          acceptedCount: decisions?.accepted.length ?? 0
+                        });
+                        let cachedNames = await cachePromise;
+                        const acceptedNames = decisions?.accepted ?? [];
+                        let cacheHit = !effectiveNoCache && acceptedNames.length > 0 && acceptedNames.every((name) => cachedNames.has(name));
+                        if (!cacheHit && !effectiveNoCache && acceptedNames.length > 0) {
+                          cachedNames = await checkGenerateCacheComponents(sid, state.tokensPath, true);
+                          cacheHit = acceptedNames.every((name) => cachedNames.has(name));
+                        }
+                        finishWizardTimer("generation-cache-set-comparison", comparisonStartedAt, {
+                          status: "complete",
+                          cacheHit,
+                          cachedCount: cachedNames.size,
+                          acceptedCount: acceptedNames.length
                         });
-                        void runGenerate(sid, state.tokensPath, acceptedCount);
+                        if (cacheHit) {
+                          void finishCachedGeneration(sid, acceptedCount);
+                        } else {
+                          const acceptedNameSet = new Set(acceptedNames);
+                          const restoredCachedNames = [...cachedNames].filter((name) => acceptedNameSet.has(name));
+                          update({
+                            step: "generating",
+                            generateProgress: null,
+                            acceptedCount
+                          });
+                          void runGenerate(sid, state.tokensPath, acceptedCount, false, restoredCachedNames);
+                        }
                       } else {
                         finishSelectionToReviewTimer("error");
                       }
@@ -29366,7 +30440,7 @@ function registerImportCommand(program) {
     "Override a composition, selection, token, generation, or token-mapping prompt (repeatable). value is a file path or literal text, e.g. --prompt select=./p.md",
     (v, acc) => [...acc, v],
     []
-  ).action(async (opts) => {
+  ).option("--no-cache", "Re-run all steps even if output already exists").action(async (opts) => {
     const interactiveTerminalSupported = getInteractiveTerminalSupport().supported;
     if (opts.tokens !== void 0) {
       const { access: access9 } = await import("node:fs/promises");
@@ -29403,6 +30477,7 @@ function registerImportCommand(program) {
           ...resolvedModel ? { initialModel: resolvedModel } : {},
           initialProjectPath: opts.project !== "." ? normalizePath(opts.project) : void 0,
           ...buildCompositionForwardingOptions(opts),
+          noCache: opts.cache === false,
           skipMapTokens: false,
           livePreview: true,
           generatePromptPath: creds.generatePromptPath,
@@ -29490,7 +30565,7 @@ async function pathExists3(path) {
   return access8(path).then(() => true).catch(() => false);
 }
 function runSpawn(cmd, args, opts = {}) {
-  return new Promise((resolve20) => {
+  return new Promise((resolve22) => {
     const child = spawn6(cmd, args, {
       cwd: opts.cwd,
       env: opts.env ?? process.env,
@@ -29502,7 +30577,7 @@ function runSpawn(cmd, args, opts = {}) {
     const settle = (result) => {
       if (settled) return;
       settled = true;
-      resolve20(result);
+      resolve22(result);
     };
     child.on("error", (err) => settle({ exitCode: 1, stdout: "", stderr: err.message }));
     child.stdout.on("data", (d) => {
@@ -30703,13 +31778,13 @@ function PrerequisitesScreen({
     const driver = {
       ...base,
       emit: (event) => setEvents((current) => [...current, event]),
-      confirm: (question, defaultYes = true) => new Promise((resolve20) => {
+      confirm: (question, defaultYes = true) => new Promise((resolve22) => {
         setConfirm({
           question,
           defaultYes,
           resolve: (answer) => {
             setConfirm(null);
-            resolve20(answer);
+            resolve22(answer);
           }
         });
       })
@@ -30784,8 +31859,8 @@ function SetupScreen({
   useEffect21(() => {
     if (startedRef.current) return;
     startedRef.current = true;
-    const runScreen = (build) => new Promise((resolve20) => {
-      setScreen(build(resolve20));
+    const runScreen = (build) => new Promise((resolve22) => {
+      setScreen(build(resolve22));
     });
     void (async () => {
       const results = [];
@@ -30963,9 +32038,9 @@ var init_command8 = __esm({
 function rank(p) {
   if (p === "typed-slot") return 1;
   if (p === "structural") return 2;
-  if (p === "call-site") return 3;
-  if (p === "manifest") return 4;
-  if (p === "doc") return 5;
+  if (p === "manifest") return 3;
+  if (p === "doc") return 4;
+  if (p.startsWith("adapter:")) return 5;
   return 6;
 }
 function mergeEdges(all) {
@@ -31001,6 +32076,65 @@ var init_merge_edges = __esm({
   }
 });
 
+// packages/experience-design-system-cli-legacy/src/analyze/composition/parse-map-edges.ts
+function parseMapEdges(raw, opts) {
+  const edges = [];
+  const warnings = [];
+  const { componentNames } = opts;
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("{")) continue;
+    let obj;
+    try {
+      obj = JSON.parse(trimmed);
+    } catch {
+      warnings.push(`unparseable line: ${trimmed.slice(0, 120)}`);
+      continue;
+    }
+    if (typeof obj !== "object" || obj === null || !("tool" in obj)) continue;
+    const rec = obj;
+    if (!VALID_MAP_TOOL_NAMES.has(rec.tool)) {
+      warnings.push(`unknown tool: ${String(rec.tool)}`);
+      continue;
+    }
+    if (typeof rec.parent !== "string" || !rec.parent || typeof rec.child !== "string" || !rec.child) {
+      warnings.push("map_edge missing parent/child \u2014 skipped");
+      continue;
+    }
+    const { parent, child } = rec;
+    if (!componentNames.has(parent)) {
+      warnings.push(`map_edge names unknown component (parent): ${parent} \u2014 skipped`);
+      continue;
+    }
+    if (!componentNames.has(child)) {
+      warnings.push(`map_edge names unknown component (child): ${child} \u2014 skipped`);
+      continue;
+    }
+    const edge = { parent, child, provenance: "agent" };
+    if (typeof rec.slot === "string" && rec.slot) {
+      edge.slot = rec.slot;
+    }
+    if (rec.confidence !== void 0) {
+      if (typeof rec.confidence === "number" && rec.confidence >= 1 && rec.confidence <= 5) {
+        edge.confidence = rec.confidence;
+      } else {
+        warnings.push(
+          `map_edge (${parent}\u2192${child}): invalid confidence ${String(rec.confidence)} \u2014 edge kept without confidence`
+        );
+      }
+    }
+    edges.push(edge);
+  }
+  return { edges, warnings };
+}
+var VALID_MAP_TOOL_NAMES;
+var init_parse_map_edges = __esm({
+  "packages/experience-design-system-cli-legacy/src/analyze/composition/parse-map-edges.ts"() {
+    "use strict";
+    VALID_MAP_TOOL_NAMES = /* @__PURE__ */ new Set(["map_edge"]);
+  }
+});
+
 // packages/experience-design-system-cli-legacy/src/analyze/composition/apply-mapping.ts
 function applyMapping(components, edges) {
   const warnings = [];
@@ -31060,9 +32194,44 @@ var init_apply_mapping = __esm({
   }
 });
 
+// packages/experience-design-system-cli-legacy/src/analyze/composition/prompt-loader.ts
+import { existsSync as existsSync10, readFileSync as readFileSync10 } from "node:fs";
+import { dirname as dirname17, join as join27, resolve as resolve19 } from "node:path";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
+function resolvePromptPath(fileName) {
+  const thisDir = dirname17(fileURLToPath3(import.meta.url));
+  let dir = thisDir;
+  for (; ; ) {
+    const candidate = join27(dir, "prompts");
+    if (existsSync10(candidate)) return join27(candidate, fileName);
+    const parent = resolve19(dir, "..");
+    if (parent === dir) {
+      throw new Error(
+        `prompt file missing from CLI installation (could not locate prompts/ directory from: ${thisDir})`
+      );
+    }
+    dir = parent;
+  }
+}
+function loadPrompt(fileName) {
+  const path = resolvePromptPath(fileName);
+  try {
+    return readFileSync10(path, "utf8");
+  } catch {
+    throw new Error(`prompt file missing from CLI installation \u2014 try reinstalling the CLI (looked for: ${path})`);
+  }
+}
+var init_prompt_loader = __esm({
+  "packages/experience-design-system-cli-legacy/src/analyze/composition/prompt-loader.ts"() {
+    "use strict";
+  }
+});
+
 // packages/experience-design-system-cli-legacy/src/analyze/composition/resolve-mapping.ts
-function resolveMapping(input) {
+async function resolveMapping(input) {
+  const componentNames = new Set(input.components.map((c2) => c2.name));
   const collected = [];
+  const agentWarnings = [];
   for (const c2 of input.components) {
     for (const slot of c2.slots) {
       for (const child of slot.allowedComponents ?? []) {
@@ -31080,41 +32249,17 @@ function resolveMapping(input) {
   if (input.extraEdges) {
     collected.push(...input.extraEdges);
   }
-  for (const evidence of input.sourceCallSiteEvidence ?? []) {
-    collected.push({
-      parent: evidence.parent,
-      child: evidence.child,
-      ...evidence.slot ? { slot: evidence.slot } : {},
-      citation: { sourcePath: evidence.sourcePath, startLine: evidence.startLine, endLine: evidence.endLine },
-      provenance: "call-site"
-    });
-  }
   const coveredParents = new Set(collected.map((e) => e.parent));
   const residueParents = input.components.map((c2) => c2.name).filter((n) => !coveredParents.has(n));
-  const debug = getDebugLogger();
-  const countByProvenance = (edges) => {
-    const counts = {};
-    for (const edge of edges) counts[edge.provenance] = (counts[edge.provenance] ?? 0) + 1;
-    return counts;
-  };
-  debug.event("analyze", "composition.pre-merge", {
-    edgeCountsByProvenance: countByProvenance(collected),
-    coveredParents: [...coveredParents].sort(),
-    residueParents,
-    sourceCallSiteAccepted: input.sourceCallSiteEvidence?.length ?? 0,
-    sourceCallSiteRejected: input.sourceCallSiteRejections?.length ?? 0
-  });
+  const shouldRunAgent = input.forceAgent || residueParents.length > 0 && input.files.length > 0;
+  if (shouldRunAgent) {
+    const prompt = input.buildPrompt ? input.buildPrompt(input.files, [...componentNames]) : defaultPrompt(input.files, [...componentNames], input.promptOverride);
+    const raw = await input.runAgentFn({ prompt, files: input.files }) ?? "";
+    const parsed = parseMapEdges(raw, { componentNames });
+    collected.push(...parsed.edges);
+    agentWarnings.push(...parsed.warnings);
+  }
   const merged = mergeEdges(collected);
-  debug.event("analyze", "composition.merged", {
-    edgeCountsByProvenance: countByProvenance(merged.edges),
-    conflicts: merged.conflicts,
-    edges: merged.edges.map((edge) => ({
-      parent: edge.parent,
-      child: edge.child,
-      slot: edge.slot ?? null,
-      provenance: edge.provenance
-    }))
-  });
   const base = input.components.map((c2) => ({
     ...c2,
     slots: c2.slots.map((s) => {
@@ -31123,32 +32268,127 @@ function resolveMapping(input) {
     })
   }));
   const applied = applyMapping(base, merged.edges);
-  debug.event("analyze", "composition.applied", {
-    slots: applied.components.flatMap(
-      (component) => component.slots.filter((slot) => (slot.allowedComponents?.length ?? 0) > 0).map((slot) => ({ component: component.name, slot: slot.name, allowedComponents: slot.allowedComponents }))
-    ),
-    warnings: applied.warnings
-  });
   return {
     components: applied.components,
     edges: merged.edges,
     conflicts: merged.conflicts,
-    warnings: applied.warnings,
-    sourceCallSiteEvidence: [...input.sourceCallSiteEvidence ?? []],
-    sourceCallSiteRejections: [...input.sourceCallSiteRejections ?? []]
+    warnings: [...agentWarnings, ...applied.warnings]
   };
 }
+function defaultPrompt(files, componentNames, promptOverride) {
+  const fileBlocks = files.map((f) => `--- ${f.path} ---
+${f.content}`).join("\n\n");
+  const instruction = promptOverride?.trim() ? promptOverride.trim() : loadPrompt("composition-edges.md").trim();
+  return [
+    instruction,
+    "",
+    'Emit one JSON object per line, each: {"tool":"map_edge","parent":"<Name>","child":"<Name>","slot"?:"<slot>","confidence"?:1-5,"reason":"<cite the file + declaration>"}.',
+    "Use ONLY these exact component names (an edge naming anything else is dropped):",
+    componentNames.join(", "),
+    "",
+    "Candidate files:",
+    fileBlocks
+  ].join("\n");
+}
 var init_resolve_mapping = __esm({
   "packages/experience-design-system-cli-legacy/src/analyze/composition/resolve-mapping.ts"() {
     "use strict";
     init_merge_edges();
+    init_parse_map_edges();
     init_apply_mapping();
-    init_debug_logger();
+    init_prompt_loader();
+  }
+});
+
+// packages/experience-design-system-cli-legacy/src/analyze/composition/resolve-mapping-cli.ts
+function resolveCompositionSources(opts) {
+  return {
+    forceAgent: opts.compositionRefresh === true || opts.noCache === true
+  };
+}
+var init_resolve_mapping_cli = __esm({
+  "packages/experience-design-system-cli-legacy/src/analyze/composition/resolve-mapping-cli.ts"() {
+    "use strict";
+  }
+});
+
+// packages/experience-design-system-cli-legacy/src/analyze/composition/candidate-files.ts
+function matchReason(file) {
+  const segments = file.path.split("/").filter((s) => s !== "");
+  for (const pattern of CANDIDATE_NAME_PATTERNS) {
+    if (segments.some((seg) => pattern.test(seg))) {
+      return `name:${pattern.source.toLowerCase()}`;
+    }
+  }
+  for (const marker of CANDIDATE_CONTENT_MARKERS) {
+    if (file.content.includes(marker)) return `content:${marker}`;
+  }
+  return void 0;
+}
+function selectCandidateFiles(files) {
+  const selected = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const file of files) {
+    if (seen.has(file.path)) continue;
+    const reason = matchReason(file);
+    if (reason === void 0) continue;
+    seen.add(file.path);
+    selected.push({ path: file.path, content: file.content, reason });
+  }
+  return selected;
+}
+function capCandidatesToPromptBudget(files, budget = PROMPT_CANDIDATE_TOKEN_BUDGET) {
+  const ordered = [...files].sort((a, b) => a.content.length - b.content.length || a.path.localeCompare(b.path));
+  const kept = [];
+  const dropped = [];
+  let spent = 0;
+  for (const file of ordered) {
+    const cost = tokenCost(file);
+    if (spent + cost > budget) {
+      dropped.push(file);
+      continue;
+    }
+    kept.push(file);
+    spent += cost;
+  }
+  return { kept, dropped };
+}
+function tokenCost(file) {
+  return Math.ceil(file.content.length / CHARS_PER_TOKEN);
+}
+var CANDIDATE_NAME_PATTERNS, CANDIDATE_CONTENT_MARKERS, PROMPT_CANDIDATE_TOKEN_BUDGET, CHARS_PER_TOKEN;
+var init_candidate_files = __esm({
+  "packages/experience-design-system-cli-legacy/src/analyze/composition/candidate-files.ts"() {
+    "use strict";
+    CANDIDATE_NAME_PATTERNS = [/mapping/i, /meta/i, /registry/i, /schema/i, /composition/i];
+    CANDIDATE_CONTENT_MARKERS = [
+      "requiredParent",
+      "withParentType",
+      "allowedTagNames",
+      "createContext",
+      "MappingContext",
+      "allowedComponents"
+    ];
+    PROMPT_CANDIDATE_TOKEN_BUDGET = 8e4;
+    CHARS_PER_TOKEN = 4;
+  }
+});
+
+// packages/experience-design-system-cli-legacy/src/analyze/composition/composition-cache-key.ts
+function buildCompositionInputHash(input) {
+  const fileDigest = input.files.map((f) => `${f.path} ${hashContent(f.content)}`).sort().join("");
+  return hashContent(`agent:${input.agent}
+${fileDigest}`);
+}
+var init_composition_cache_key = __esm({
+  "packages/experience-design-system-cli-legacy/src/analyze/composition/composition-cache-key.ts"() {
+    "use strict";
+    init_cache_keys();
   }
 });
 
 // packages/experience-design-system-cli-legacy/src/analyze/composition/manifest-doc-evidence.ts
-import { dirname as dirname17 } from "node:path";
+import { dirname as dirname18 } from "node:path";
 function kebabToPascal2(name) {
   return name.split("-").filter(Boolean).map((seg) => seg.charAt(0).toUpperCase() + seg.slice(1)).join("");
 }
@@ -31198,8 +32438,8 @@ function collectAgentsDocEdges(files, components, componentNames) {
   const seen = /* @__PURE__ */ new Set();
   for (const file of files) {
     if (!file.path.endsWith("AGENTS.md")) continue;
-    const docDir = dirname17(file.path);
-    const parent = components.find((c2) => c2.sourcePath && dirname17(c2.sourcePath) === docDir)?.name;
+    const docDir = dirname18(file.path);
+    const parent = components.find((c2) => c2.sourcePath && dirname18(c2.sourcePath) === docDir)?.name;
     if (!parent || !componentNames.has(parent)) continue;
     for (const line of file.content.split("\n")) {
       const lower = line.toLowerCase();
@@ -31229,172 +32469,12 @@ var init_manifest_doc_evidence = __esm({
   }
 });
 
-// packages/experience-design-system-cli-legacy/src/analyze/composition/source-call-site-evidence.ts
-import { Node as Node49, Project as Project11, SyntaxKind as SyntaxKind15 } from "ts-morph";
-function collectSourceCallSiteEvidence(files, components) {
-  const componentNames = new Set(components.map((component) => component.name));
-  const componentsBySource = /* @__PURE__ */ new Map();
-  for (const component of components) {
-    const sourcePath = component.sourcePath ?? component.source;
-    const siblings = componentsBySource.get(sourcePath) ?? [];
-    siblings.push(component);
-    componentsBySource.set(sourcePath, siblings);
-  }
-  const project = new Project11({
-    compilerOptions: { jsx: 1, target: 99, module: 99, moduleResolution: 100, skipLibCheck: true, allowJs: true },
-    skipAddingFilesFromTsConfig: true
-  });
-  const sourceFiles = new Map(
-    files.map((file) => [file.path, project.createSourceFile(file.path, file.content, { overwrite: true })])
-  );
-  const accepted = [];
-  const rejected = [];
-  for (const [sourcePath, parents] of componentsBySource) {
-    const sourceFile = sourceFiles.get(sourcePath);
-    if (!sourceFile) continue;
-    const boundNames = collectBoundNames(sourceFile);
-    for (const parent of parents) {
-      for (const jsxElement of [
-        ...sourceFile.getDescendantsOfKind(SyntaxKind15.JsxSelfClosingElement),
-        ...sourceFile.getDescendantsOfKind(SyntaxKind15.JsxElement)
-      ]) {
-        const tagName = Node49.isJsxSelfClosingElement(jsxElement) ? jsxElement.getTagNameNode().getText() : jsxElement.getOpeningElement().getTagNameNode().getText();
-        const candidate = tagName.split(".").at(-1) ?? tagName;
-        if (candidate === parent.name || isIntrinsicTag(candidate)) continue;
-        const lines = sourceExcerpt(sourceFile, jsxElement);
-        if (!componentNames.has(candidate)) {
-          rejected.push({ parent: parent.name, candidate, ...lines, reason: "unknown-component" });
-          continue;
-        }
-        if (!boundNames.has(tagName) && !boundNames.has(candidate)) {
-          rejected.push({ parent: parent.name, candidate, ...lines, reason: "unbound-component" });
-          continue;
-        }
-        accepted.push({ parent: parent.name, child: candidate, ...lines, kind: "jsx-render" });
-      }
-    }
-  }
-  for (const sourceFile of sourceFiles.values()) {
-    collectCallerSlotEvidence(sourceFile, componentNames, collectBoundNames(sourceFile), accepted, rejected);
-  }
-  const verifiedPairs = new Set(accepted.map((evidence) => `${evidence.parent}\0${evidence.child}`));
-  for (const component of components) {
-    const candidates = component.slots.flatMap((slot) => [
-      ...slot.allowedComponents ?? [],
-      ...slot.structuralAllowedComponents ?? []
-    ]);
-    for (const candidate of candidates) {
-      if (verifiedPairs.has(`${component.name}\0${candidate}`)) continue;
-      rejected.push({
-        parent: component.name,
-        candidate,
-        sourcePath: component.sourcePath ?? component.source,
-        reason: "no-call-site"
-      });
-    }
-  }
-  return {
-    accepted: dedupeEvidence(accepted),
-    rejected: dedupeRejections(rejected)
-  };
-}
-function collectCallerSlotEvidence(sourceFile, componentNames, boundNames, accepted, rejected) {
-  for (const parentElement of sourceFile.getDescendantsOfKind(SyntaxKind15.JsxElement)) {
-    const parentTag = parentElement.getOpeningElement().getTagNameNode().getText();
-    const parent = parentTag.split(".").at(-1) ?? parentTag;
-    if (!componentNames.has(parent) || !boundNames.has(parentTag)) continue;
-    for (const childNode of parentElement.getJsxChildren()) {
-      if (!Node49.isJsxElement(childNode) && !Node49.isJsxSelfClosingElement(childNode)) {
-        if (Node49.isJsxText(childNode) && childNode.getText().trim()) {
-          const lines2 = sourceExcerpt(sourceFile, childNode);
-          rejected.push({ parent, candidate: "<text>", ...lines2, reason: "text-only-child" });
-        }
-        continue;
-      }
-      const childTag = Node49.isJsxElement(childNode) ? childNode.getOpeningElement().getTagNameNode().getText() : childNode.getTagNameNode().getText();
-      const child = childTag.split(".").at(-1) ?? childTag;
-      if (isIntrinsicTag(child)) continue;
-      const lines = sourceExcerpt(sourceFile, childNode);
-      if (!componentNames.has(child)) {
-        rejected.push({ parent, candidate: child, ...lines, reason: "unknown-component" });
-        continue;
-      }
-      if (!boundNames.has(childTag) && !boundNames.has(child)) {
-        rejected.push({ parent, candidate: child, ...lines, reason: "unbound-component" });
-        continue;
-      }
-      const slotAttribute = Node49.isJsxElement(childNode) ? childNode.getOpeningElement().getAttribute("slot") : childNode.getAttribute("slot");
-      const slotValue = slotAttribute && Node49.isJsxAttribute(slotAttribute) ? slotAttribute.getInitializer() : void 0;
-      const slot = slotValue && Node49.isStringLiteral(slotValue) ? slotValue.getLiteralValue() : void 0;
-      accepted.push({ parent, child, ...slot ? { slot } : {}, ...lines, kind: "jsx-render" });
-    }
-  }
-}
-function collectBoundNames(sourceFile) {
-  const names = /* @__PURE__ */ new Set();
-  for (const declaration of sourceFile.getImportDeclarations()) {
-    const defaultImport = declaration.getDefaultImport();
-    if (defaultImport) names.add(defaultImport.getText());
-    const namespaceImport = declaration.getNamespaceImport();
-    if (namespaceImport) names.add(namespaceImport.getText());
-    for (const namedImport of declaration.getNamedImports()) {
-      names.add((namedImport.getAliasNode() ?? namedImport.getNameNode()).getText());
-    }
-  }
-  for (const declaration of sourceFile.getVariableDeclarations()) names.add(declaration.getName());
-  for (const declaration of sourceFile.getFunctions()) {
-    if (declaration.getName()) names.add(declaration.getName());
-  }
-  for (const declaration of sourceFile.getClasses()) {
-    if (declaration.getName()) names.add(declaration.getName());
-  }
-  return names;
-}
-function sourceExcerpt(sourceFile, node) {
-  const startLine = node.getStartLineNumber();
-  const endLine = node.getEndLineNumber();
-  const lines = sourceFile.getFullText().split("\n");
-  return {
-    sourcePath: sourceFile.getFilePath(),
-    startLine,
-    endLine,
-    excerpt: lines.slice(startLine - 1, endLine).join("\n").trim()
-  };
-}
-function isIntrinsicTag(tagName) {
-  return /^[a-z]/.test(tagName) || tagName.includes("-");
-}
-function dedupeEvidence(evidence) {
-  const seen = /* @__PURE__ */ new Set();
-  return evidence.filter((item) => {
-    const key = `${item.parent}\0${item.child}\0${item.slot ?? ""}\0${item.sourcePath}\0${item.startLine}`;
-    if (seen.has(key)) return false;
-    seen.add(key);
-    return true;
-  }).sort(
-    (left, right) => `${left.parent}\0${left.child}\0${left.sourcePath}\0${left.startLine}`.localeCompare(
-      `${right.parent}\0${right.child}\0${right.sourcePath}\0${right.startLine}`
-    )
-  );
-}
-function dedupeRejections(rejections) {
-  const seen = /* @__PURE__ */ new Set();
-  return rejections.filter((item) => {
-    const key = `${item.parent}\0${item.candidate}\0${item.sourcePath}\0${item.startLine}`;
-    if (seen.has(key)) return false;
-    seen.add(key);
-    return true;
-  });
-}
-var init_source_call_site_evidence = __esm({
-  "packages/experience-design-system-cli-legacy/src/analyze/composition/source-call-site-evidence.ts"() {
-    "use strict";
-  }
-});
-
 // packages/experience-design-system-cli-legacy/src/analyze/extract-command.ts
-import { mkdir as mkdir6, readdir as readdir3, readFile as readFile18, stat as stat6 } from "node:fs/promises";
-import { isAbsolute as isAbsolute2, join as join27, relative as relative2, resolve as resolve18 } from "node:path";
+import { mkdir as mkdir6, readdir as readdir3, readFile as readFile19, stat as stat6 } from "node:fs/promises";
+import { isAbsolute as isAbsolute2, join as join28, relative as relative2, resolve as resolve20 } from "node:path";
+function resolveExtractNoCache(opts) {
+  return opts.noCache === true || opts.cache === false;
+}
 function isDenylistedNoiseFile(name) {
   return DENYLISTED_EXACT_FILE_NAMES.has(name) || DENYLISTED_FILE_NAME_PATTERNS.some((pattern) => pattern.test(name));
 }
@@ -31408,12 +32488,12 @@ async function retryDatabaseWrite(operation, attempts = 8) {
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       if (!/database is locked|database is busy/i.test(message) || attempt >= attempts) throw error;
-      await new Promise((resolve20) => setTimeout(resolve20, Math.min(250 * attempt, 2e3)));
+      await new Promise((resolve22) => setTimeout(resolve22, Math.min(250 * attempt, 2e3)));
     }
   }
 }
 function resolveFromProjectRoot(projectRoot, inputPath) {
-  return isAbsolute2(inputPath) ? inputPath : resolve18(projectRoot, inputPath);
+  return isAbsolute2(inputPath) ? inputPath : resolve20(projectRoot, inputPath);
 }
 async function pathExists4(path) {
   return Boolean(await stat6(path).catch(() => null));
@@ -31424,7 +32504,7 @@ async function collectSourceFiles(directory, onProgress) {
     const entries = await readdir3(currentDirectory, { withFileTypes: true });
     const subdirs = [];
     for (const entry of entries) {
-      const fullPath = join27(currentDirectory, entry.name);
+      const fullPath = join28(currentDirectory, entry.name);
       if (entry.isDirectory()) {
         if (!IGNORED_DIRECTORY_NAMES.has(entry.name)) {
           subdirs.push(fullPath);
@@ -31451,6 +32531,12 @@ async function collectSourceFiles(directory, onProgress) {
   await visit(directory);
   return files.sort();
 }
+function resolveCompositionAgentName(flagValue) {
+  if (flagValue && isAgentName(flagValue)) return flagValue;
+  const env = process.env["EDS_COMPOSITION_AGENT"];
+  if (env && isAgentName(env)) return env;
+  return DEFAULT_AGENT_NAME;
+}
 async function readCandidateFiles(components, extraFiles = []) {
   const paths = new Set(extraFiles);
   for (const c2 of components) {
@@ -31460,7 +32546,7 @@ async function readCandidateFiles(components, extraFiles = []) {
   await Promise.all(
     [...paths].map(async (p) => {
       try {
-        const content = await readFile18(p, "utf8");
+        const content = await readFile19(p, "utf8");
         out.push({ path: p, content });
       } catch {
       }
@@ -31469,11 +32555,21 @@ async function readCandidateFiles(components, extraFiles = []) {
   return out;
 }
 function registerInternalExtractCommand(program) {
-  program.command("__extract", { hidden: true }).description("Extract component definitions from a project").requiredOption("--project <path>", "Path to the project root").option("--dir <path>", "Path to the component source directory relative to the project root").option(
+  const extractCmd = program.command("__extract", { hidden: true }).description("Extract component definitions from a project").requiredOption("--project <path>", "Path to the project root").option("--dir <path>", "Path to the component source directory relative to the project root").option(
     "--resolve-unreachable <mode>",
     "Retry pass for unresolved Svelte Props types: 'auto' (default), 'always', or 'never'",
     "auto"
-  ).action(async (opts) => {
+  ).option("--composition-refresh", "Force the mapping agent to run even where deterministic sources answered").option("--no-cache", "Re-run extraction even when all source files are unchanged").option(
+    "--prompt <stage=value>",
+    "Override a stage prompt (repeatable). value is a file path or literal text, e.g. --prompt composition=./p.md",
+    (v, acc) => [...acc, v],
+    []
+  );
+  addAgentModelOptions(extractCmd, {
+    includeModel: false,
+    agentDescription: "Coding agent for composition mapping resolution (claude|codex|opencode|cursor)"
+  }).action(async (opts) => {
+    const noCache = resolveExtractNoCache(opts);
     const resolveUnreachable = (() => {
       const v = opts.resolveUnreachable ?? "auto";
       if (v !== "auto" && v !== "always" && v !== "never") {
@@ -31483,8 +32579,16 @@ function registerInternalExtractCommand(program) {
       }
       return v;
     })();
-    const projectRoot = resolve18(opts.project);
-    const outDir = join27(projectRoot, ".contentful");
+    if (opts.bedrock) {
+      const bedrockAgent = resolveCompositionAgentName(opts.agent);
+      if (!agentSupportsBedrock(bedrockAgent)) {
+        process.stderr.write(`Error: --bedrock is not supported for --agent ${bedrockAgent}
+`);
+        process.exit(1);
+      }
+    }
+    const projectRoot = resolve20(opts.project);
+    const outDir = join28(projectRoot, ".contentful");
     let sourceDirectory;
     if (opts.dir !== void 0) {
       sourceDirectory = resolveFromProjectRoot(projectRoot, opts.dir);
@@ -31507,16 +32611,50 @@ function registerInternalExtractCommand(program) {
       process.stderr.write(`progress=scan-done:${sourceFiles.length}
 `);
     }
-    const extraction = await extractComponents(
-      sourceFiles,
-      ({ filesProcessed, componentsFound }) => {
+    const extractionCacheDb = openPipelineDb();
+    let extraction;
+    let extractionCacheHits = 0;
+    try {
+      const cacheVersion = await getCliCacheVersion();
+      const cachedByPath = /* @__PURE__ */ new Map();
+      if (!noCache && sourceFiles.length > 0) {
+        const hashes = await Promise.all(
+          sourceFiles.map(async (filePath) => [filePath, await hashFile(filePath)])
+        );
+        for (const [filePath, fileHash] of hashes) {
+          cachedByPath.set(filePath, lookupExtractCache(extractionCacheDb, fileHash, cacheVersion));
+        }
+      }
+      const allFilesCached = !noCache && sourceFiles.length > 0 && sourceFiles.every((filePath) => cachedByPath.get(filePath) !== null);
+      if (allFilesCached) {
+        const cachedComponents = sourceFiles.flatMap((filePath) => cachedByPath.get(filePath).components);
+        extractionCacheHits = sourceFiles.length;
+        extraction = { components: cachedComponents, warnings: [], exclusions: [] };
         if (!process.stdout.isTTY) {
-          process.stderr.write(`progress=extract:${filesProcessed}/${sourceFiles.length}:${componentsFound}
-`);
+          process.stderr.write(
+            `progress=extract:${sourceFiles.length}/${sourceFiles.length}:${cachedComponents.length}
+`
+          );
         }
-      },
-      { resolveUnreachable, projectRoot }
-    );
+        getDebugLogger().event("analyze", "extract.cache-hit", {
+          files: sourceFiles.length,
+          components: cachedComponents.length
+        });
+      } else {
+        extraction = await extractComponents(
+          sourceFiles,
+          ({ filesProcessed, componentsFound }) => {
+            if (!process.stdout.isTTY) {
+              process.stderr.write(`progress=extract:${filesProcessed}/${sourceFiles.length}:${componentsFound}
+`);
+            }
+          },
+          { resolveUnreachable, projectRoot }
+        );
+      }
+    } finally {
+      extractionCacheDb.close();
+    }
     await mkdir6(outDir, { recursive: true });
     const db = openPipelineDb();
     const { sessionId: sessionId2 } = getOrCreateSession(db, void 0, void 0, {
@@ -31531,6 +32669,25 @@ function registerInternalExtractCommand(program) {
     const stepId = createStep(db, sessionId2, "analyze extract", {
       project: projectRoot
     });
+    if (extractionCacheHits === 0 && !noCache) {
+      const cacheVersion = await getCliCacheVersion();
+      const componentsBySourcePath = /* @__PURE__ */ new Map();
+      for (const component of extraction.components) {
+        if (!component.sourcePath) continue;
+        const components = componentsBySourcePath.get(component.sourcePath) ?? [];
+        components.push(component);
+        componentsBySourcePath.set(component.sourcePath, components);
+      }
+      for (const filePath of sourceFiles) {
+        storeExtractCache(
+          db,
+          filePath,
+          await hashFile(filePath),
+          cacheVersion,
+          componentsBySourcePath.get(filePath) ?? []
+        );
+      }
+    }
     const classifiedComponents = extraction.components.map(preClassifyComponent);
     for (const exclusion of extraction.exclusions ?? []) {
       getDebugLogger().event("filter", "extract.excluded", { ...exclusion });
@@ -31554,9 +32711,28 @@ function registerInternalExtractCommand(program) {
     storeRawComponents(db, sessionId2, validatedComponents);
     process.stdout.write(`session=${sessionId2}
 `);
-    let sourceCallSiteEvidence = [];
-    let sourceCallSiteRejections = [];
     {
+      const sources = resolveCompositionSources({
+        ...opts,
+        noCache
+      });
+      const { overrides: promptOverrides, errors: promptErrors } = parsePromptOverrides(opts.prompt ?? []);
+      for (const err of promptErrors) {
+        process.stderr.write(`Error: ${err}
+`);
+        process.exit(1);
+      }
+      let compositionPrompt;
+      const compositionOverride = promptOverrides.get("composition");
+      if (compositionOverride) {
+        try {
+          compositionPrompt = await resolvePromptOverride(compositionOverride);
+        } catch (e) {
+          process.stderr.write(`Error: ${e instanceof Error ? e.message : String(e)}
+`);
+          process.exit(1);
+        }
+      }
       {
         const emitCompositionProgress = (phase) => {
           if (!process.stdout.isTTY) process.stderr.write(`progress=composition:${phase}
@@ -31564,18 +32740,62 @@ function registerInternalExtractCommand(program) {
         };
         emitCompositionProgress("resolving");
         const allFiles = await readCandidateFiles(validatedComponents, sourceFiles);
+        const selectedCandidates = selectCandidateFiles(allFiles).map((c2) => ({ path: c2.path, content: c2.content }));
+        const capped = capCandidatesToPromptBudget(selectedCandidates);
+        const promptFiles = capped.kept;
+        if (capped.dropped.length > 0) {
+          process.stderr.write(
+            `Warning: composition \u2014 ${capped.dropped.length} candidate file(s) omitted from the agent prompt to fit the context budget; resolution runs on the ${promptFiles.length} highest-value files.
+`
+          );
+        }
         const runtimeFiles = allFiles.map((c2) => ({ path: c2.path, content: c2.content }));
+        const resolverAgent = resolveCompositionAgentName(opts.agent);
         const componentNameSet = new Set(validatedComponents.map((c2) => c2.name));
+        const cacheVersion = await getCliCacheVersion();
+        let lastAgentExitCode = 0;
+        const spawnAgent = async (prompt) => {
+          const res = await runAgent({
+            agent: resolverAgent,
+            prompt,
+            timeoutMs: 12e4,
+            promptViaStdin: true,
+            onDebugEvent: (name, payload) => getDebugLogger().event("agent", name, payload)
+          });
+          lastAgentExitCode = res.exitCode;
+          if (res.exitCode !== 0 && res.stderr.trim()) {
+            process.stderr.write(`Warning: composition \u2014 agent exited ${res.exitCode}: ${res.stderr.trim()}
+`);
+          }
+          return res.stdout;
+        };
         const manifestDocEdges = collectManifestDocEdges(runtimeFiles, validatedComponents, componentNameSet);
         const extraEdges = manifestDocEdges;
-        const sourceCallSites = collectSourceCallSiteEvidence(runtimeFiles, validatedComponents);
-        sourceCallSiteEvidence = sourceCallSites.accepted;
-        sourceCallSiteRejections = sourceCallSites.rejected;
-        const result = resolveMapping({
+        const agentCacheKey = buildCompositionInputHash({
+          files: promptFiles,
+          agent: resolverAgent
+        });
+        const result = await resolveMapping({
           components: validatedComponents,
           ...extraEdges.length > 0 ? { extraEdges } : {},
-          sourceCallSiteEvidence,
-          sourceCallSiteRejections
+          forceAgent: sources.forceAgent,
+          files: promptFiles,
+          ...compositionPrompt ? { promptOverride: compositionPrompt } : {},
+          runAgentFn: async ({ prompt }) => {
+            if (!noCache && !opts.compositionRefresh) {
+              const cached = lookupCompositionCache(db, agentCacheKey, cacheVersion);
+              if (cached !== null) {
+                emitCompositionProgress("cache-hit");
+                return cached;
+              }
+            }
+            emitCompositionProgress(`agent:${resolverAgent}`);
+            const stdout = await spawnAgent(prompt);
+            if (lastAgentExitCode === 0) {
+              storeCompositionCache(db, agentCacheKey, cacheVersion, stdout);
+            }
+            return stdout;
+          }
         });
         emitCompositionProgress("done");
         for (const w of result.warnings) process.stderr.write(`Warning: composition \u2014 ${w}
@@ -31605,13 +32825,7 @@ function registerInternalExtractCommand(program) {
       sessionId2,
       sourceFiles.map((f) => relative2(projectRoot, f))
     );
-    await retryDatabaseWrite(
-      () => updateStep(db, stepId, "complete", {
-        sessionId: sessionId2,
-        compositionEvidence: JSON.stringify(sourceCallSiteEvidence),
-        compositionRejections: JSON.stringify(sourceCallSiteRejections)
-      })
-    );
+    await retryDatabaseWrite(() => updateStep(db, stepId, "complete", { sessionId: sessionId2 }));
     enrichCommandResult({ extracted_component_count: validatedComponents.length });
     db.close();
     const allWarnings = [...extraction.warnings, ...filterWarnings];
@@ -31633,12 +32847,18 @@ var SCANNED_FILE_EXTENSIONS, DENYLIST_GATED_EXTENSIONS, DENYLISTED_EXACT_FILE_NA
 var init_extract_command = __esm({
   "packages/experience-design-system-cli-legacy/src/analyze/extract-command.ts"() {
     "use strict";
+    init_agent_model_options();
     init_src2();
     init_db();
+    init_cache_keys();
     init_cycle_detection();
     init_resolve_mapping();
+    init_resolve_mapping_cli();
+    init_candidate_files();
+    init_composition_cache_key();
     init_manifest_doc_evidence();
-    init_source_call_site_evidence();
+    init_prompt_overrides();
+    init_src();
     init_analytics();
     init_debug_logger();
     SCANNED_FILE_EXTENSIONS = /* @__PURE__ */ new Set([".astro", ".js", ".jsx", ".svelte", ".ts", ".tsx", ".vue"]);
@@ -31732,9 +32952,9 @@ __export(program_exports, {
   runBuild: () => runBuild
 });
 import { spawn as spawn7 } from "node:child_process";
-import { fileURLToPath as fileURLToPath3 } from "node:url";
-import { dirname as dirname18, join as join28, resolve as resolve19 } from "node:path";
-import { readFileSync as readFileSync10 } from "node:fs";
+import { fileURLToPath as fileURLToPath4 } from "node:url";
+import { dirname as dirname19, join as join29, resolve as resolve21 } from "node:path";
+import { readFileSync as readFileSync11 } from "node:fs";
 import { Command } from "commander";
 async function runBuild(opts) {
   return new Promise((resolvePromise) => {
@@ -31763,7 +32983,7 @@ function resolveBedrockFromAncestors(actionCommand) {
 }
 function registerBuildCommand(program) {
   program.command("build").description("Rebuild from source and re-link exo/experiences binaries to this build").helpOption(false).action(async () => {
-    const pkgRoot = resolve19(dirname18(fileURLToPath3(import.meta.url)), "..", "..");
+    const pkgRoot = resolve21(dirname19(fileURLToPath4(import.meta.url)), "..", "..");
     process.stderr.write("\u2699  Building from source...\n");
     const { exitCode } = await runBuild({
       spawnFn: () => spawn7("pnpm", ["build"], { cwd: pkgRoot, stdio: "inherit" }),
@@ -31833,7 +33053,7 @@ var init_program = __esm({
     init_analytics();
     init_credentials_store();
     init_cli_path();
-    pkg3 = JSON.parse(readFileSync10(join28(findPkgRoot(), "package.json"), "utf8"));
+    pkg3 = JSON.parse(readFileSync11(join29(findPkgRoot(), "package.json"), "utf8"));
   }
 });