@contentful/experience-design-system-cli 2.34.5-dev-build-fcf31517.0 → 2.34.5-dev-build-ea694b2.0

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-cli",
-  "version": "2.34.5-dev-build-fcf31517.0",
+  "version": "2.34.5-dev-build-ea694b2.0",
   "description": "Contentful Experiences design system import CLI",
   "license": "MIT",
   "type": "module",

package/dist/src/analyze/composition/interchange-schema.d.ts

@@ -1,17 +1,11 @@
 /**
  * The CLI-owned composition interchange format (spec T1).
  *
- * Two views of the same data:
- *  - `InterchangeMap` — the human-authored / on-disk `{ version, groups }`
- *    shape (parent → children), consumed by the composition-map option.
- *    `--composition-map` consumes and the resolver can emit.
- *  - `CompositionEdge[]` — the flat internal runtime view, one edge per
- *    parent→child relationship, carrying optional `slot` (T7), `confidence`,
- *    and `provenance`. Easier to merge/dedupe across sources (T2).
- *
- * This module owns both shapes and the converters between them.
+ * `CompositionEdge[]` is the flat internal runtime view, one edge per
+ * parent→child relationship, carrying optional `slot` (T7), `confidence`,
+ * and `provenance`. It is easier to merge and dedupe across sources (T2).
  */
-export type EdgeProvenance = 'user' | 'typed-slot' | 'structural' | 'manifest' | 'doc' | `adapter:${string}` | 'agent';
+export type EdgeProvenance = 'typed-slot' | 'structural' | 'manifest' | 'doc' | `adapter:${string}` | 'agent';
 export type CompositionEdge = {
     parent: string;
     child: string;
@@ -21,17 +15,3 @@ export type CompositionEdge = {
     confidence?: number;
     provenance: EdgeProvenance;
 };
-export type InterchangeMap = {
-    version: 1;
-    groups: Record<string, string[]>;
-};
-export type ValidateResult = {
-    valid: true;
-    map: InterchangeMap;
-} | {
-    valid: false;
-    errors: string[];
-};
-export declare function validateInterchangeMap(input: unknown): ValidateResult;
-export declare function groupsToEdges(map: InterchangeMap, provenance: EdgeProvenance): CompositionEdge[];
-export declare function edgesToGroups(edges: CompositionEdge[]): InterchangeMap;

package/dist/src/analyze/composition/resolve-mapping-cli.d.ts

@@ -1,18 +1,7 @@
-import { type InterchangeMap } from './interchange-schema.js';
 export type CompositionCliOptions = {
-    /** `--composition-map <path>` — hand-authored interchange file. */
-    compositionMap?: string;
     /** `--composition-refresh` — force edge emission to run even over resolved residue. */
     compositionRefresh?: boolean;
 };
-export type LoadUserMapResult = {
-    ok: true;
-    map: InterchangeMap;
-} | {
-    ok: false;
-    error: string;
-};
-export declare function loadUserMap(path: string): Promise<LoadUserMapResult>;
 export type ResolvedCompositionSources = {
     forceAgent: boolean;
 };

package/dist/src/analyze/composition/resolve-mapping.d.ts

@@ -1,9 +1,8 @@
 import type { RawComponentDefinition } from '../../types.js';
-import { type CompositionEdge, type InterchangeMap } from './interchange-schema.js';
+import type { CompositionEdge } from './interchange-schema.js';
 import { type EdgeConflict } from './merge-edges.js';
 export type ResolveMappingResult = {
     components: RawComponentDefinition[];
-    userMap?: InterchangeMap;
     edges: CompositionEdge[];
     conflicts: EdgeConflict[];
     warnings: string[];
@@ -11,9 +10,9 @@ export type ResolveMappingResult = {
 /**
  * Orchestrate composition-edge acquisition and enrichment.
  *
- * Sources by rank: user map (1) > typed-slot / "code slots" (2) > structural
- * usage evidence (3) > manifest (4) > doc (5) > adapter-resolved / extraEdges
- * (6) > edge-emitting agent (7). Manifest/doc edges are computed deterministically outside
+ * Sources by rank: typed-slot / "code slots" (2) > structural usage evidence
+ * (3) > manifest (4) > doc (5) > adapter-resolved / extraEdges (6) >
+ * edge-emitting agent (7). Manifest/doc edges are computed deterministically outside
  * this function (see manifest-doc-evidence.ts) and joined via `extraEdges`.
  * ALL sources — including the code slots already on the incoming components —
  * are fed into one ranked merge and unioned; non-conflicting edges from every
@@ -28,7 +27,6 @@ export type ResolveMappingResult = {
  */
 export declare function resolveMapping(input: {
     components: RawComponentDefinition[];
-    userMap?: InterchangeMap;
     forceAgent?: boolean;
     files: Array<{
         path: string;
@@ -55,7 +53,7 @@ export declare function resolveMapping(input: {
     /**
      * Pre-resolved edges from an external source (e.g. manifest or documentation)
      * path). They join the ranked merge at their own provenance rank alongside
-     * code slots and the user map.
+     * code slots and other automatic mapping sources.
      */
     extraEdges?: CompositionEdge[];
 }): Promise<ResolveMappingResult>;

package/dist/src/import/agent-model-resolve.d.ts

@@ -1,11 +1,11 @@
 /**
- * Resolution chain for `--agent` and `--model` overrides on `experiences import`.
+ * Resolution chain for the combined `--agent` override on `experiences import`.
  *
  * The wizard path previously hard-defaulted `--agent` to `'claude'` at the
  * commander layer, which (a) shadowed the stored `credentials.json` value when
  * the user passed no flag, and (b) made it impossible to distinguish "user
- * explicitly passed --agent claude" from "user passed nothing". `--model` was
- * registered but never threaded into the wizard subprocesses at all.
+ * explicitly passed --agent claude" from "user passed nothing". The combined
+ * flag accepts either `agent:model` or `agent model`.
  *
  * These helpers produce the resolved values to feed into `WizardApp` /
  * the import wizard:
@@ -15,9 +15,13 @@
  *      `experiences setup`) is used.
  *   3. Otherwise, the built-in default (currently `'claude'`) is used for
  *      the agent. Model has no default — agents pick a small/fast model
- *      themselves when `--model` is omitted.
+ *      themselves when no model is included in `--agent`.
  */
 /** Built-in fallback agent when neither a flag nor a stored preference is set. */
 export declare const DEFAULT_AGENT = "claude";
+export declare function parseAgentModel(value: string | undefined): {
+    agent?: string;
+    model?: string;
+};
 export declare function resolveAgent(flagValue: string | undefined, storedValue: string | undefined): string;
 export declare function resolveModel(flagValue: string | undefined, storedValue: string | undefined): string | undefined;

package/dist/src/import/composition-options.d.ts

@@ -1,9 +1,7 @@
 export type CompositionOptionInput = {
-    compositionMap?: string;
     prompt?: string[];
 };
 export type CompositionForwardingOptions = {
-    compositionMap?: string;
     promptOverrides?: string[];
 };
 export declare function buildCompositionForwardingOptions(options: CompositionOptionInput): CompositionForwardingOptions;

package/dist/src/import/tui/WizardApp.d.ts

@@ -17,6 +17,7 @@ export declare function buildGenerateTokensArgs(opts: {
     model?: string;
     bedrock?: boolean;
     noCache?: boolean;
+    promptOverrides?: string[];
 }): string[];
 export declare function buildMapTokensArgs(opts: {
     sessionId: string;
@@ -24,6 +25,7 @@ export declare function buildMapTokensArgs(opts: {
     model?: string;
     noCache?: boolean;
     skipAgent?: boolean;
+    promptOverrides?: string[];
     existingEntitiesPath?: string;
 }): string[];
 export declare function shouldRunMapTokens(opts: {
@@ -51,7 +53,6 @@ export type WizardAppProps = {
     bedrock?: boolean;
     initialProjectPath?: string;
     host?: string;
-    compositionMap?: string;
     promptOverrides?: string[];
     noCache?: boolean;
     livePreview?: boolean;
@@ -59,4 +60,4 @@ export type WizardAppProps = {
     skipMapTokens?: boolean;
     initialRawTokensPath?: string;
 };
-export declare function WizardApp({ initialSpaceId, initialEnvironmentId, initialCmaToken, initialHost, initialAgent, initialModel, bedrock, initialProjectPath, host, compositionMap, promptOverrides, noCache, livePreview, generatePromptPath, skipMapTokens, initialRawTokensPath, }?: WizardAppProps): React.ReactElement;
+export declare function WizardApp({ initialSpaceId, initialEnvironmentId, initialCmaToken, initialHost, initialAgent, initialModel, bedrock, initialProjectPath, host, promptOverrides, noCache, livePreview, generatePromptPath, skipMapTokens, initialRawTokensPath, }?: WizardAppProps): React.ReactElement;

package/dist/src/import/tui/run-selection-agent.d.ts

@@ -0,0 +1,8 @@
+import { type AgentName } from '@contentful/experience-design-system-generation';
+export declare function runSelectionAgent(options: {
+    sessionId: string;
+    agent: AgentName;
+    model?: string;
+    promptText?: string;
+    promptPath?: string;
+}): Promise<void>;

package/dist/src/index.js

@@ -4146,12 +4146,17 @@ var init_persistence = __esm({
 
 // packages/experience-design-system-cli/src/lib/agent-model-options.ts
 function addAgentModelOptions(cmd, config = {}) {
-  const { agentDescription = AGENT_DESCRIPTION, includeModel = true, modelDescription = MODEL_DESCRIPTION } = config;
+  const {
+    agentDescription = AGENT_DESCRIPTION,
+    includeModel = true,
+    includeBedrock = true,
+    modelDescription = MODEL_DESCRIPTION
+  } = config;
   cmd.option("--agent <name>", agentDescription);
   if (includeModel) {
     cmd.option("--model <name>", modelDescription);
   }
-  cmd.option("--bedrock", BEDROCK_DESCRIPTION);
+  if (includeBedrock) cmd.option("--bedrock", BEDROCK_DESCRIPTION);
   return cmd;
 }
 var AGENT_DESCRIPTION, MODEL_DESCRIPTION, BEDROCK_AGENTS, BEDROCK_DESCRIPTION;
@@ -4910,7 +4915,8 @@ async function runGenerateSkill(skill, opts, verbose = false) {
   const { overrides: promptOverrides, errors: promptErrors } = parsePromptOverrides(opts.prompt ?? []);
   if (promptErrors.length > 0) die(`Error: ${promptErrors.join("; ")}`);
   let generatePrompt;
-  const generateOverride = promptOverrides.get("generate");
+  const promptStage = skill === "tokens" ? "tokens" : "generate";
+  const generateOverride = promptOverrides.get(promptStage);
   if (generateOverride) {
     try {
       generatePrompt = await resolvePromptOverride(generateOverride);
@@ -5260,7 +5266,12 @@ function registerInternalGenerateCommand(program) {
   addAgentFlags(componentsCmd).action(async (opts) => {
     await runGenerateSkill("components", opts, opts.verbose ?? false);
   });
-  const tokensCmd = generate.command("tokens").description("Invoke a coding agent to produce tokens.json from raw token data").option("--raw-tokens <path>", "Path to raw token input file");
+  const tokensCmd = generate.command("tokens").description("Invoke a coding agent to produce tokens.json from raw token data").option("--raw-tokens <path>", "Path to raw token input file").option(
+    "--prompt <stage=value>",
+    "Override a stage prompt (repeatable). Used here for the tokens stage.",
+    (v, acc) => [...acc, v],
+    []
+  );
   addAgentFlags(tokensCmd).action(async (opts) => {
     await runGenerateSkill("tokens", opts, opts.verbose ?? false);
   });
@@ -7532,7 +7543,7 @@ function buildApplyOutput(operation, spaceId, environmentId, host) {
   };
 }
 function registerApplyCommand(program) {
-  const applyCmd = program.command("apply").description("Write component types and design tokens to Contentful ExO").argument("<file>", "CDF file containing all component and design token definitions");
+  const applyCmd = program.command("apply").description("Write component types and design tokens to Contentful ExO").helpOption(false).argument("<file>", "CDF file containing all component and design token definitions");
   applyCmd.action(async (file) => {
     const isTTY = getInteractiveTerminalSupport().supported;
     const inputs = await resolveSharedInputsOrDie(file);
@@ -8480,6 +8491,20 @@ async function runMapTokens(opts) {
     );
   }
   const resultAgent = configuredAgent ?? "skipped";
+  const { overrides: promptOverrides, errors: promptErrors } = parsePromptOverrides(opts.prompt ?? []);
+  if (promptErrors.length > 0) die(`Error: ${promptErrors.join("; ")}`);
+  const mapPromptOverride = promptOverrides.get("map-tokens");
+  let mapPromptText;
+  let mapPromptPath;
+  if (mapPromptOverride?.kind === "text") mapPromptText = mapPromptOverride.value;
+  if (mapPromptOverride?.kind === "path") {
+    mapPromptPath = resolve8(mapPromptOverride.value);
+    try {
+      await resolvePromptOverride(mapPromptOverride);
+    } catch (error) {
+      die(`Error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
   const db = openPipelineDb();
   try {
     const sessionId2 = opts.session ?? findLatestSessionForCommand(db, "generate components");
@@ -8582,16 +8607,19 @@ ${defaultDiagnostics.map((diagnostic) => `  ${diagnostic}`).join("\n")}
         );
       }
     }
+    const buildMapPrompt = () => buildPrompt({
+      skill: "map-tokens",
+      mode: "autonomous",
+      generatedCdf,
+      tokenTree,
+      componentSourceRefs,
+      outDir: process.cwd(),
+      existingTokensInline,
+      ...mapPromptText !== void 0 ? { skillContentOverride: mapPromptText } : {},
+      ...mapPromptText === void 0 && mapPromptPath ? { skillPathOverride: mapPromptPath } : {}
+    });
     if (opts.printPrompt) {
-      const prompt2 = await buildPrompt({
-        skill: "map-tokens",
-        mode: "autonomous",
-        generatedCdf,
-        tokenTree,
-        componentSourceRefs,
-        outDir: process.cwd(),
-        existingTokensInline
-      });
+      const prompt2 = await buildMapPrompt();
       process.stdout.write(prompt2 + "\n");
       await exitWithAnalytics(0);
       return;
@@ -8613,7 +8641,8 @@ ${defaultDiagnostics.map((diagnostic) => `  ${diagnostic}`).join("\n")}
       agent,
       model,
       void 0,
-      existingTokensInline ? [hashContent(existingTokensInline)] : []
+      existingTokensInline ? [hashContent(existingTokensInline)] : [],
+      mapPromptText
     );
     const inputHash = computeMapTokensInputHash(db, sessionId2, componentSourceRefs);
     if (!noCache) {
@@ -8635,15 +8664,7 @@ Install it, choose another agent with --agent, or use --print-prompt to run the
       );
     }
     const stepId = createStep(db, sessionId2, "map tokens", { agent, model: model ?? "" });
-    const prompt = await buildPrompt({
-      skill: "map-tokens",
-      mode: "autonomous",
-      generatedCdf,
-      tokenTree,
-      componentSourceRefs,
-      outDir: process.cwd(),
-      existingTokensInline
-    });
+    const prompt = await buildMapPrompt();
     const invoker2 = createLocalCliAgentInvoker();
     const result = await invoker2.invoke({ agent, model, prompt, timeoutMs: DEFAULT_TIMEOUT_MS2 });
     if (result.timedOut || result.exitCode !== 0) {
@@ -8669,7 +8690,12 @@ ${warnings.map((w) => `  ${w}`).join("\n")}
 }
 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("--no-cache", "Bypass the map-tokens cache and force a re-run").option("--token-map <path>", "Path to token-name-map.json sidecar").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],
+    []
+  ).option("--token-map <path>", "Path to token-name-map.json sidecar").option(
     "--existing-entities-path <path>",
     "Path to the .existing-entities.json file written after CMA credentials are supplied. When present, the agent gets a list of the space's existing design tokens so it can prefer binding to them. Missing/malformed files are treated as no-op."
   );
@@ -8694,6 +8720,7 @@ var init_command4 = __esm({
     init_MapTokensView();
     init_resolve_defaults();
     init_cli_errors();
+    init_prompt_overrides();
     DEFAULT_TIMEOUT_MS2 = Number(process.env.EDS_AGENT_TIMEOUT_MS ?? 5 * 60 * 1e3);
   }
 });
@@ -8722,6 +8749,19 @@ var init_path_utils = __esm({
 });
 
 // packages/experience-design-system-cli/src/import/agent-model-resolve.ts
+function parseAgentModel(value) {
+  if (!value?.trim()) return {};
+  const trimmed = value.trim();
+  const separator = trimmed.indexOf(":");
+  if (separator >= 0) {
+    return {
+      agent: trimmed.slice(0, separator).trim() || void 0,
+      model: trimmed.slice(separator + 1).trim() || void 0
+    };
+  }
+  const [agent, ...modelParts] = trimmed.split(/\s+/);
+  return { agent, ...modelParts.length > 0 ? { model: modelParts.join(" ") } : {} };
+}
 function resolveAgent(flagValue, storedValue) {
   if (flagValue && flagValue.length > 0) return flagValue;
   if (storedValue && storedValue.length > 0) return storedValue;
@@ -8743,7 +8783,6 @@ var init_agent_model_resolve = __esm({
 // packages/experience-design-system-cli/src/import/composition-options.ts
 function buildCompositionForwardingOptions(options) {
   return {
-    ...options.compositionMap ? { compositionMap: options.compositionMap } : {},
     ...options.prompt && options.prompt.length > 0 ? { promptOverrides: options.prompt } : {}
   };
 }
@@ -26650,6 +26689,70 @@ var init_wizard_state_transitions = __esm({
   }
 });
 
+// packages/experience-design-system-cli/src/import/tui/run-selection-agent.ts
+async function runSelectionAgent(options) {
+  const db = openPipelineDb();
+  let components;
+  try {
+    components = loadRawComponents(db, options.sessionId);
+  } finally {
+    db.close();
+  }
+  if (components.length === 0) return;
+  const invoker2 = createLocalCliAgentInvoker({
+    onDebugEvent: (name, payload) => getDebugLogger().event("agent", name, payload)
+  });
+  const prompt = await buildPrompt({
+    skill: "select",
+    mode: "autonomous",
+    rawComponentsInline: JSON.stringify(components, null, 2),
+    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 { calls, warnings } = parseSelectToolCallLines(result.stdout);
+  for (const warning of warnings) process.stderr.write(`Warning: selection agent: ${warning}
+`);
+  const byName = new Map(calls.map((call) => [call.name, call]));
+  const writeDb = openPipelineDb();
+  try {
+    const update = writeDb.prepare(
+      `UPDATE raw_components SET status = ?, reject_reason = ? WHERE session_id = ? AND component_id = ?`
+    );
+    for (const component of components) {
+      const call = byName.get(component.name);
+      if (!call) continue;
+      const rejected = call.tool === "reject_component";
+      update.run(
+        rejected ? "rejected" : "accepted",
+        rejected ? call.reason ?? null : null,
+        options.sessionId,
+        component.component_id
+      );
+    }
+  } finally {
+    writeDb.close();
+  }
+}
+var DEFAULT_TIMEOUT_MS4;
+var init_run_selection_agent = __esm({
+  "packages/experience-design-system-cli/src/import/tui/run-selection-agent.ts"() {
+    "use strict";
+    init_src();
+    init_debug_logger();
+    init_agent_output();
+    init_db();
+    DEFAULT_TIMEOUT_MS4 = Number(process.env.EDS_AGENT_TIMEOUT_MS ?? 5 * 60 * 1e3);
+  }
+});
+
 // packages/experience-design-system-cli/src/import/tui/WizardApp.tsx
 var WizardApp_exports = {};
 __export(WizardApp_exports, {
@@ -26688,6 +26791,7 @@ function buildGenerateTokensArgs(opts) {
   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) {
@@ -26695,6 +26799,7 @@ function buildMapTokensArgs(opts) {
   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);
   return args;
 }
@@ -26770,7 +26875,6 @@ function WizardApp({
   bedrock = false,
   initialProjectPath,
   host,
-  compositionMap,
   promptOverrides,
   noCache = false,
   livePreview = true,
@@ -26940,7 +27044,8 @@ If you are using AWS Bedrock, run:
       agent: state.agent,
       ...state.agentModel ? { model: state.agentModel } : {},
       ...state.bedrock ? { bedrock: true } : {},
-      noCache: effectiveNoCache
+      noCache: effectiveNoCache,
+      promptOverrides
     });
     const result = await runSpawnedCli(tokenArgs);
     if (result.exitCode !== 0) {
@@ -27020,6 +27125,7 @@ If you are using AWS Bedrock, run:
       ...state.agentModel ? { model: state.agentModel } : {},
       noCache: effectiveNoCache,
       skipAgent: skipMapTokens,
+      promptOverrides,
       ...state.existingEntitiesPath ? { existingEntitiesPath: state.existingEntitiesPath } : {}
     });
     const result = await runCli(args);
@@ -27038,7 +27144,6 @@ If you are using AWS Bedrock, run:
     update({ step: "extracting", outDir, extractProgress: null, compositionPhase: null });
     const extractArgs = [findCliPath(), "__extract", "--project", projectPath];
     if (noCache) extractArgs.push("--composition-refresh");
-    if (compositionMap) extractArgs.push("--composition-map", compositionMap);
     for (const p of promptOverrides ?? []) extractArgs.push("--prompt", p);
     if (state.agent) extractArgs.push("--agent", state.agent);
     if (state.bedrock) extractArgs.push("--bedrock");
@@ -27103,6 +27208,34 @@ Make sure this path contains TypeScript/React/Vue component files (.tsx, .ts, .v
       });
       return;
     }
+    try {
+      const { overrides, errors } = parsePromptOverrides(promptOverrides ?? []);
+      if (errors.length > 0) throw new Error(errors.join("; "));
+      const selectOverride = overrides.get("select");
+      let promptText;
+      let promptPath;
+      if (selectOverride?.kind === "text") promptText = selectOverride.value;
+      if (selectOverride?.kind === "path") {
+        promptPath = resolve17(selectOverride.value);
+        await resolvePromptOverride(selectOverride);
+      }
+      if (state.agent) {
+        await runSelectionAgent({
+          sessionId: extractSessionId ?? "",
+          agent: state.agent,
+          ...state.agentModel ? { model: state.agentModel } : {},
+          ...promptText !== void 0 ? { promptText } : {},
+          ...promptPath ? { promptPath } : {}
+        });
+      }
+    } catch (error) {
+      update({
+        step: "error",
+        errorStep: "selection agent",
+        errorMessage: error instanceof Error ? error.message : String(error)
+      });
+      return;
+    }
     update({
       step: "scope-gate",
       extractSessionId
@@ -28349,6 +28482,8 @@ var init_WizardApp = __esm({
     init_fetch_and_persist_existing_contentful_entities();
     init_wizard_state_transitions();
     init_cli_path();
+    init_prompt_overrides();
+    init_run_selection_agent();
     WIZARD_LOG = join20(tmpdir(), "experiences-import-wizard.log");
   }
 });
@@ -28356,80 +28491,71 @@ var init_WizardApp = __esm({
 // packages/experience-design-system-cli/src/import/command.ts
 function registerImportCommand(program) {
   const cmd = program.command("import").description("Run the full pipeline: analyze \u2192 select \u2192 generate \u2192 push").option("--project <path>", "Path to the project root to analyze", ".");
-  addAgentModelOptions(cmd, {
-    agentDescription: 'Agent to use for generate components (overrides credentials.json; falls back to "claude")',
-    modelDescription: "Model to use for generate components (defaults to a lightweight per-agent model; override with EDS_AGENT_MODEL_<AGENT>)"
-  }).option(
-    "--raw-tokens <path>",
+  cmd.option(
+    "--tokens <path>",
     "Path to a raw token source file (SCSS, CSS variables, JS/TS, Style Dictionary, etc.) to classify and import alongside components. Bypasses the interactive token prompt."
-  ).option(
-    "--skip-map-tokens",
-    "Skip agentic token restrictions while still resolving deterministic token-default paths"
-  ).option("--no-cache", "Re-run all steps even if output already exists");
-  cmd.option("--composition-map <path>", "Consume a hand-authored parent\u2192children interchange map").option(
+  );
+  addAgentModelOptions(cmd, {
+    agentDescription: 'Agent and optional model as agent:model or "agent model" (overrides credentials.json; falls back to "claude")',
+    includeModel: false,
+    includeBedrock: false
+  });
+  cmd.option(
     "--prompt <stage=value>",
-    "Override a stage prompt (repeatable). value is a file path or literal text, e.g. --prompt composition=./p.md",
+    "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) => {
-      const interactiveTerminalSupported = getInteractiveTerminalSupport().supported;
-      if (opts.rawTokens !== void 0) {
-        const { access: access9 } = await import("node:fs/promises");
-        try {
-          await access9(normalizePath(opts.rawTokens));
-        } catch {
-          process.stderr.write(`Error: --raw-tokens: file not found: ${opts.rawTokens}
-`);
-          process.exit(1);
-          return;
-        }
-      }
-      if (!interactiveTerminalSupported) {
-        requireInteractiveTerminal({
-          alternative: "run experiences import in an interactive terminal"
-        });
-      }
-      {
-        const { render: render5 } = await import("ink");
-        const { createElement: createElement6 } = await import("react");
-        const { WizardApp: WizardApp2 } = await Promise.resolve().then(() => (init_WizardApp(), WizardApp_exports));
-        const creds = await readExperiencesCredentials();
-        const resolvedAgent = resolveAgent(opts.agent, creds.agent);
-        const resolvedModel = resolveModel(opts.model, creds.agentModel);
-        if (opts.bedrock && !(isAgentName(resolvedAgent) && agentSupportsBedrock(resolvedAgent))) {
-          process.stderr.write(`Error: --bedrock is not supported for --agent ${resolvedAgent}
+  ).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");
+      try {
+        await access9(normalizePath(opts.tokens));
+      } catch {
+        process.stderr.write(`Error: --tokens: file not found: ${opts.tokens}
 `);
-          process.exit(1);
-        }
-        const { waitUntilExit } = render5(
-          createElement6(WizardApp2, {
-            initialSpaceId: creds.spaceId,
-            initialEnvironmentId: creds.environmentId || "master",
-            initialCmaToken: creds.cmaToken,
-            initialHost: toConfiguredHost(creds.host) ?? DEFAULT_CONFIGURED_HOST,
-            initialAgent: resolvedAgent,
-            ...resolvedModel ? { initialModel: resolvedModel } : {},
-            ...opts.bedrock ? { bedrock: true } : {},
-            initialProjectPath: opts.project !== "." ? normalizePath(opts.project) : void 0,
-            ...buildCompositionForwardingOptions(opts),
-            noCache: opts.cache === false,
-            skipMapTokens: opts.skipMapTokens ?? false,
-            livePreview: true,
-            generatePromptPath: creds.generatePromptPath,
-            ...opts.rawTokens ? { initialRawTokensPath: normalizePath(opts.rawTokens) } : {}
-          })
-        );
-        await waitUntilExit();
+        process.exit(1);
         return;
       }
     }
-  );
+    if (!interactiveTerminalSupported) {
+      requireInteractiveTerminal({
+        alternative: "run experiences import in an interactive terminal"
+      });
+    }
+    {
+      const { render: render5 } = await import("ink");
+      const { createElement: createElement6 } = await import("react");
+      const { WizardApp: WizardApp2 } = await Promise.resolve().then(() => (init_WizardApp(), WizardApp_exports));
+      const creds = await readExperiencesCredentials();
+      const parsedAgentModel = parseAgentModel(opts.agent);
+      const resolvedAgent = resolveAgent(parsedAgentModel.agent, creds.agent);
+      const resolvedModel = resolveModel(parsedAgentModel.model, creds.agentModel);
+      const { waitUntilExit } = render5(
+        createElement6(WizardApp2, {
+          initialSpaceId: creds.spaceId,
+          initialEnvironmentId: creds.environmentId || "master",
+          initialCmaToken: creds.cmaToken,
+          initialHost: toConfiguredHost(creds.host) ?? DEFAULT_CONFIGURED_HOST,
+          initialAgent: resolvedAgent,
+          ...resolvedModel ? { initialModel: resolvedModel } : {},
+          initialProjectPath: opts.project !== "." ? normalizePath(opts.project) : void 0,
+          ...buildCompositionForwardingOptions(opts),
+          noCache: opts.cache === false,
+          skipMapTokens: false,
+          livePreview: true,
+          generatePromptPath: creds.generatePromptPath,
+          ...opts.tokens ? { initialRawTokensPath: normalizePath(opts.tokens) } : {}
+        })
+      );
+      await waitUntilExit();
+      return;
+    }
+  });
 }
 var init_command6 = __esm({
   "packages/experience-design-system-cli/src/import/command.ts"() {
     "use strict";
-    init_src();
     init_path_utils();
     init_agent_model_resolve();
     init_agent_model_options();
@@ -28742,7 +28868,7 @@ var init_checks2 = __esm({
 });
 
 // packages/experience-design-system-cli/src/doctor/command.ts
-async function runChecks(opts) {
+async function runChecks() {
   const pkgRoot = findPkgRoot();
   const results = [];
   const record = (name, passed, required = true) => {
@@ -28751,13 +28877,11 @@ async function runChecks(opts) {
   };
   if (record("Node.js version", await reportNode())) {
     const pnpmOk = record("pnpm", await reportPnpm(pkgRoot));
-    if (opts.skipBuild) {
-      info("\nSkipping install + build (--skip-build)");
-    } else if (pnpmOk && record("dependencies", await reportDependencies(pkgRoot))) {
+    if (pnpmOk && record("dependencies", await reportDependencies(pkgRoot))) {
       record("build", await reportBuild(pkgRoot));
     }
   }
-  if (!opts.skipAgent) record("coding agent", await reportAgent(), false);
+  record("coding agent", await reportAgent(), false);
   return results;
 }
 function printSummary(results) {
@@ -28797,13 +28921,13 @@ ${c.red(c.bold(`\u2717 ${requiredFailed} required check${requiredFailed === 1 ?
 `);
   return 1;
 }
-async function runDoctor(opts) {
+async function runDoctor() {
   process.stderr.write(`${c.bold("experiences doctor")} \u2014 checking your environment
 `);
-  process.exitCode = printSummary(await runChecks(opts));
+  process.exitCode = printSummary(await runChecks());
 }
 function registerDoctorCommand(program) {
-  program.command("doctor").description("Check prerequisites so experiences import runs without errors").option("--skip-build", "Skip the pnpm install + build step (useful if already built)").option("--skip-agent", "Skip the coding agent check").action((opts) => runDoctor(opts));
+  program.command("doctor").description("Check prerequisites so experiences import runs without errors").helpOption(false).action(() => runDoctor());
 }
 var init_command7 = __esm({
   "packages/experience-design-system-cli/src/doctor/command.ts"() {
@@ -29943,7 +30067,7 @@ async function runSetup(opts) {
   process.exit(finished.exitCode);
 }
 function registerSetupCommand(program) {
-  program.command("setup").description("Interactive setup: installs prerequisites and configures credentials for experiences import").option("--skip-build", "Skip the pnpm install + build step").option("--skip-agent", "Skip the coding agent check").option("--skip-credentials", "Skip the Contentful credentials step").option("--skip-optional", "Skip optional quality-of-life extras").action((opts) => runSetup(opts));
+  program.command("setup").description("Interactive setup: installs prerequisites and configures credentials for experiences import").helpOption(false).action(() => runSetup({}));
 }
 var SETUP_REQUIRES_TTY_MESSAGE;
 var init_command8 = __esm({
@@ -29955,57 +30079,14 @@ var init_command8 = __esm({
   }
 });
 
-// packages/experience-design-system-cli/src/analyze/composition/interchange-schema.ts
-function validateInterchangeMap(input) {
-  const errors = [];
-  if (typeof input !== "object" || input === null || Array.isArray(input)) {
-    return { valid: false, errors: ["interchange map must be a JSON object"] };
-  }
-  const obj = input;
-  if (obj.version !== 1) {
-    errors.push(`unsupported interchange version: expected 1, got ${JSON.stringify(obj.version)}`);
-  }
-  if (typeof obj.groups !== "object" || obj.groups === null || Array.isArray(obj.groups)) {
-    errors.push("interchange map must have a `groups` object");
-    return { valid: false, errors };
-  }
-  const groups = obj.groups;
-  for (const [parent, children] of Object.entries(groups)) {
-    if (!Array.isArray(children) || !children.every((c2) => typeof c2 === "string")) {
-      errors.push(`groups["${parent}"] must be an array of strings`);
-    }
-  }
-  if (errors.length > 0) return { valid: false, errors };
-  return { valid: true, map: { version: 1, groups } };
-}
-function groupsToEdges(map, provenance) {
-  const seen = /* @__PURE__ */ new Set();
-  const edges = [];
-  for (const [parent, children] of Object.entries(map.groups)) {
-    for (const child of children) {
-      const key = `${parent}::${child}`;
-      if (seen.has(key)) continue;
-      seen.add(key);
-      edges.push({ parent, child, provenance });
-    }
-  }
-  return edges;
-}
-var init_interchange_schema = __esm({
-  "packages/experience-design-system-cli/src/analyze/composition/interchange-schema.ts"() {
-    "use strict";
-  }
-});
-
 // packages/experience-design-system-cli/src/analyze/composition/merge-edges.ts
 function rank(p) {
-  if (p === "user") return 1;
-  if (p === "typed-slot") return 2;
-  if (p === "structural") return 3;
-  if (p === "manifest") return 4;
-  if (p === "doc") return 5;
-  if (p.startsWith("adapter:")) return 6;
-  return 7;
+  if (p === "typed-slot") return 1;
+  if (p === "structural") return 2;
+  if (p === "manifest") return 3;
+  if (p === "doc") return 4;
+  if (p.startsWith("adapter:")) return 5;
+  return 6;
 }
 function mergeEdges(all) {
   const byKey = /* @__PURE__ */ new Map();
@@ -30111,7 +30192,7 @@ function applyMapping(components, edges) {
     }))
   }));
   const byName = new Map(cloned.map((c2) => [c2.name, c2]));
-  const isHighTrust = (p) => p === "user" || p === "typed-slot" || p.startsWith("adapter:");
+  const isHighTrust = (p) => p === "typed-slot" || p.startsWith("adapter:");
   const addAllowed = (slot, child) => {
     const set = new Set(slot.allowedComponents ?? []);
     set.add(child);
@@ -30210,7 +30291,6 @@ async function resolveMapping(input) {
       }
     }
   }
-  if (input.userMap) collected.push(...groupsToEdges(input.userMap, "user"));
   if (input.extraEdges) {
     collected.push(...input.extraEdges);
   }
@@ -30258,7 +30338,6 @@ ${f.content}`).join("\n\n");
 var init_resolve_mapping = __esm({
   "packages/experience-design-system-cli/src/analyze/composition/resolve-mapping.ts"() {
     "use strict";
-    init_interchange_schema();
     init_merge_edges();
     init_parse_map_edges();
     init_apply_mapping();
@@ -30267,24 +30346,6 @@ var init_resolve_mapping = __esm({
 });
 
 // packages/experience-design-system-cli/src/analyze/composition/resolve-mapping-cli.ts
-import { readFile as readFile18 } from "node:fs/promises";
-async function loadUserMap(path) {
-  let text;
-  try {
-    text = await readFile18(path, "utf8");
-  } catch {
-    return { ok: false, error: `--composition-map: file not found: ${path}` };
-  }
-  let parsed;
-  try {
-    parsed = JSON.parse(text);
-  } catch {
-    return { ok: false, error: `--composition-map: not valid JSON: ${path}` };
-  }
-  const result = validateInterchangeMap(parsed);
-  if (!result.valid) return { ok: false, error: `--composition-map: ${result.errors.join("; ")}` };
-  return { ok: true, map: result.map };
-}
 function resolveCompositionSources(opts) {
   return {
     forceAgent: !!opts.compositionRefresh
@@ -30293,7 +30354,6 @@ function resolveCompositionSources(opts) {
 var init_resolve_mapping_cli = __esm({
   "packages/experience-design-system-cli/src/analyze/composition/resolve-mapping-cli.ts"() {
     "use strict";
-    init_interchange_schema();
   }
 });
 
@@ -30455,7 +30515,7 @@ var init_manifest_doc_evidence = __esm({
 });
 
 // packages/experience-design-system-cli/src/analyze/extract-command.ts
-import { mkdir as mkdir6, readdir as readdir3, readFile as readFile19, stat as stat6 } from "node:fs/promises";
+import { mkdir as mkdir6, readdir as readdir3, readFile as readFile18, stat as stat6 } from "node:fs/promises";
 import { isAbsolute as isAbsolute2, join as join25, relative as relative2, resolve as resolve19 } from "node:path";
 function isDenylistedNoiseFile(name) {
   return DENYLISTED_EXACT_FILE_NAMES.has(name) || DENYLISTED_FILE_NAME_PATTERNS.some((pattern) => pattern.test(name));
@@ -30522,7 +30582,7 @@ async function readCandidateFiles(components, extraFiles = []) {
   await Promise.all(
     [...paths].map(async (p) => {
       try {
-        const content = await readFile19(p, "utf8");
+        const content = await readFile18(p, "utf8");
         out.push({ path: p, content });
       } catch {
       }
@@ -30535,7 +30595,7 @@ function registerInternalExtractCommand(program) {
     "--resolve-unreachable <mode>",
     "Retry pass for unresolved Svelte Props types: 'auto' (default), 'always', or 'never'",
     "auto"
-  ).option("--composition-refresh", "Force the mapping agent to run even where deterministic sources answered").option("--composition-map <path>", "Consume a hand-authored parent\u2192children interchange map").option(
+  ).option("--composition-refresh", "Force the mapping agent to run even where deterministic sources answered").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],
@@ -30651,16 +30711,6 @@ function registerInternalExtractCommand(program) {
     let validatedComponents = validateExtractedComponents(filteredComponents);
     {
       const sources = resolveCompositionSources(opts);
-      let userMap;
-      if (opts.compositionMap) {
-        const loaded = await loadUserMap(opts.compositionMap);
-        if (!loaded.ok) {
-          process.stderr.write(`Error: ${loaded.error}
-`);
-          process.exit(1);
-        }
-        userMap = loaded.map;
-      }
       const { overrides: promptOverrides, errors: promptErrors } = parsePromptOverrides(opts.prompt ?? []);
       for (const err of promptErrors) {
         process.stderr.write(`Error: ${err}
@@ -30722,7 +30772,6 @@ function registerInternalExtractCommand(program) {
         });
         const result = await resolveMapping({
           components: validatedComponents,
-          ...userMap ? { userMap } : {},
           ...extraEdges.length > 0 ? { extraEdges } : {},
           forceAgent: sources.forceAgent,
           files: promptFiles,
@@ -30929,7 +30978,7 @@ function resolveBedrockFromAncestors(actionCommand) {
   return false;
 }
 function registerImportV2Command(program) {
-  program.command("importv2").description("Launch the v2 import TUI (experience-design-system-cli-v2)").action(async () => {
+  program.command("importv2").description("Launch the v2 import TUI (experience-design-system-cli-v2)").helpOption(false).action(async () => {
     const { render: render5 } = await import("ink");
     const { createElement: createElement6 } = await import("react");
     const { App } = await import("@contentful/experience-design-system-cli-v2/app");
@@ -30938,7 +30987,7 @@ function registerImportV2Command(program) {
   });
 }
 function registerBuildCommand(program) {
-  program.command("build").description("Rebuild from source and re-link exo/experiences binaries to this build").action(async () => {
+  program.command("build").description("Rebuild from source and re-link exo/experiences binaries to this build").helpOption(false).action(async () => {
     const pkgRoot = resolve20(dirname13(fileURLToPath4(import.meta.url)), "..", "..");
     process.stderr.write("\u2699  Building from source...\n");
     const { exitCode } = await runBuild({
@@ -30948,32 +30997,35 @@ function registerBuildCommand(program) {
     process.exit(exitCode);
   });
 }
+function configureRootHelpOrder(program) {
+  const order = ["build", "help", "import", "apply", "importv2", "setup", "doctor"];
+  const rank2 = new Map(order.map((name, index) => [name, index]));
+  program.configureHelp({
+    visibleCommands(command) {
+      const internals = command;
+      const visible = command.commands.filter((entry) => !entry._hidden);
+      const helpCommand = internals._getHelpCommand?.();
+      if (helpCommand && !helpCommand._hidden) visible.push(helpCommand);
+      if (command !== program) return visible;
+      return visible.sort((a, b) => (rank2.get(a.name()) ?? order.length) - (rank2.get(b.name()) ?? order.length));
+    }
+  });
+}
 function createProgram() {
   const program = new Command().name("experience-design-system-cli").description("Static analysis, validation, generation, and import of Contentful design system artifacts").version(pkg3.version, "--version", "Print version number");
   registerInternalGenerateCommand(program);
   registerInternalExtractCommand(program);
   registerPrintCommand(program);
   registerMapTokensCommand(program);
-  registerApplyCommand(program);
+  registerBuildCommand(program);
+  program.helpCommand("help [command]", "display help for command");
   registerImportCommand(program);
+  registerApplyCommand(program);
   registerImportV2Command(program);
-  registerDoctorCommand(program);
   registerSetupCommand(program);
-  registerBuildCommand(program);
-  program.option(
-    "--debug",
-    "Write a JSONL trace of every decision to ~/.contentful/experience-design-system-cli/debug/"
-  );
-  program.option("--no-debug", "Force debug logging off (overrides EDSI_DEBUG and persisted setup preference)");
+  registerDoctorCommand(program);
+  configureRootHelpOrder(program);
   program.hook("preAction", async (_thisCommand, actionCommand) => {
-    let debug;
-    for (let c2 = actionCommand; c2; c2 = c2.parent) {
-      const opts = c2.opts();
-      if (opts.debug !== void 0) {
-        debug = opts.debug;
-        break;
-      }
-    }
     if (resolveBedrockFromAncestors(actionCommand)) {
       process.env.EDS_BEDROCK = "1";
     }
@@ -30983,7 +31035,7 @@ function createProgram() {
     const { analyticsDisabled } = await readExperiencesCredentials();
     setPersistedAnalyticsDisabled(analyticsDisabled ?? false);
     noteCommandStart(commandChain);
-    await beginCommand(commandChain, { ...debug !== void 0 ? { debug } : {} });
+    await beginCommand(commandChain, {});
   });
   program.hook("postAction", async () => {
     await completeActiveCommand();

package/dist/src/lib/agent-model-options.d.ts

@@ -4,12 +4,12 @@ export declare const MODEL_DESCRIPTION = "Model to use (defaults to a lightweigh
 export interface AgentModelOptionsConfig {
     agentDescription?: string;
     includeModel?: boolean;
+    includeBedrock?: boolean;
     modelDescription?: string;
 }
 /**
- * Register --agent, --bedrock, and optional --model flags with a Commander
- * command. Pass includeModel: false to omit --model only — --bedrock is
- * independent of model selection (it's a routing switch, not a model choice)
- * and is always registered alongside --agent.
+ * Register --agent plus optional --model and --bedrock flags with a Commander
+ * command. The optional flags can be omitted for commands with a narrower
+ * public surface.
  */
 export declare function addAgentModelOptions(cmd: Command, config?: AgentModelOptionsConfig): Command;

package/dist/src/lib/debug-logger.d.ts

@@ -29,9 +29,8 @@ export declare function __resetDebugLoggerForTest(): void;
  * Resolve effective debug-mode setting from three sources.
  *
  * Precedence (highest first):
- *   1. `--debug` / `--no-debug` CLI flag
- *   2. `EDSI_DEBUG` env var (truthy: 1, true, yes, on)
- *   3. Persisted `debug` field in credentials.json
+ *   1. `EDSI_DEBUG` env var (truthy: 1, true, yes, on)
+ *   2. Persisted `debug` field in credentials.json
  *   4. Default: OFF
  */
 export declare function resolveDebugMode(opts: {

package/dist/src/program.d.ts

@@ -17,7 +17,7 @@ export declare function runBuild(opts: {
 }>;
 /**
  * Walks `actionCommand` and its ancestors for a truthy `--bedrock`. --bedrock
- * is registered per-subcommand (not at program scope, unlike --debug), so a
+ * is registered per-subcommand, so a
  * root-level or subcommand-level setting can each carry it.
  */
 export declare function resolveBedrockFromAncestors(actionCommand: Command): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-cli",
-  "version": "2.34.5-dev-build-fcf31517.0",
+  "version": "2.34.5-dev-build-ea694b2.0",
   "description": "Contentful Experiences design system import CLI",
   "license": "MIT",
   "type": "module",
@@ -41,8 +41,8 @@
     "svelte": "^5.56.4",
     "ts-morph": "^27.0.2",
     "typescript": "^5.9.3",
-    "@contentful/experience-design-system-cli-v2": "2.34.5-dev-build-fcf31517.0",
-    "@contentful/experience-design-system-types": "2.34.5-dev-build-fcf31517.0"
+    "@contentful/experience-design-system-cli-v2": "2.34.5-dev-build-ea694b2.0",
+    "@contentful/experience-design-system-types": "2.34.5-dev-build-ea694b2.0"
   },
   "devDependencies": {
     "@tsconfig/node24": "^24.0.4",
@@ -54,9 +54,9 @@
     "ink-testing-library": "^4.0.0",
     "typescript-eslint": "^8.67.0",
     "vitest": "^4.0.16",
-    "@contentful/experience-design-system-client": "2.34.5-dev-build-fcf31517.0",
-    "@contentful/experience-design-system-extraction": "2.34.5-dev-build-fcf31517.0",
-    "@contentful/experience-design-system-generation": "2.34.5-dev-build-fcf31517.0"
+    "@contentful/experience-design-system-extraction": "2.34.5-dev-build-ea694b2.0",
+    "@contentful/experience-design-system-generation": "2.34.5-dev-build-ea694b2.0",
+    "@contentful/experience-design-system-client": "2.34.5-dev-build-ea694b2.0"
   },
   "repository": {
     "type": "git",