@contentful/experience-design-system-cli 2.12.0 → 2.12.1-dev-build-bae15c7.0

package/dist/src/credentials-store.js

@@ -16,6 +16,9 @@ export async function readExperiencesCredentials() {
             ...(host ? { host } : {}),
             ...(parsed.agent ? { agent: parsed.agent } : {}),
             ...(parsed.agentModel ? { agentModel: parsed.agentModel } : {}),
+            ...(parsed.selectPromptPath ? { selectPromptPath: parsed.selectPromptPath } : {}),
+            ...(parsed.generatePromptPath ? { generatePromptPath: parsed.generatePromptPath } : {}),
+            ...(typeof parsed.autoFilter === 'boolean' ? { autoFilter: parsed.autoFilter } : {}),
         };
     }
     catch {
@@ -29,7 +32,7 @@ export async function readExperiencesCredentials() {
     }
 }
 export async function writeExperiencesCredentials(creds) {
-    const { host: _host, agent, agentModel, ...rest } = creds;
+    const { host: _host, agent, agentModel, selectPromptPath, generatePromptPath, autoFilter, ...rest } = creds;
     const host = toConfiguredHost(creds.host);
     await mkdir(CREDENTIALS_DIR, { recursive: true });
     await writeFile(CREDENTIALS_PATH, JSON.stringify({
@@ -37,6 +40,9 @@ export async function writeExperiencesCredentials(creds) {
         ...(host ? { host } : {}),
         ...(agent ? { agent } : {}),
         ...(agentModel ? { agentModel } : {}),
+        ...(selectPromptPath ? { selectPromptPath } : {}),
+        ...(generatePromptPath ? { generatePromptPath } : {}),
+        ...(typeof autoFilter === 'boolean' ? { autoFilter } : {}),
     }, null, 2) + '\n', { mode: 0o600 });
 }
 export function experiencesCredentialsPath() {

package/dist/src/generate/agent-runner.d.ts

@@ -15,6 +15,8 @@ export interface ClassifyPropCall {
     required?: boolean;
     description?: string;
     default?: string | boolean;
+    /** Internal LLM rationale; not customer-facing. Persisted to raw_props.rationale. */
+    reason?: string;
 }
 export interface ExcludePropCall {
     tool: 'exclude_prop';
@@ -24,6 +26,16 @@ export interface ExcludePropCall {
 export interface ClassifyComponentCall {
     tool: 'classify_component';
     description?: string;
+    /**
+     * Component-level rationale strings. Surfaced by the `I` ComponentRationalePanel.
+     * Each field is optional; missing fields leave existing DB values untouched
+     * (sparse update semantics in applyToolCalls).
+     */
+    rationale?: {
+        description?: string;
+        props?: string;
+        slots?: string;
+    };
 }
 export interface ClassifySlotCall {
     tool: 'classify_slot';
@@ -31,6 +43,8 @@ export interface ClassifySlotCall {
     required?: boolean;
     allowed_components?: string[];
     description?: string;
+    /** Per-slot rationale; persisted to raw_slots.rationale. */
+    rationale?: string;
 }
 export type ToolCall = ClassifyPropCall | ExcludePropCall | ClassifyComponentCall | ClassifySlotCall;
 export interface SelectComponentCall {

package/dist/src/generate/agent-runner.js

@@ -99,6 +99,8 @@ export function parseToolCallLines(stdout) {
                 call.description = rec.description;
             if (typeof rec.default === 'string' || typeof rec.default === 'boolean')
                 call.default = rec.default;
+            if (typeof rec.reason === 'string')
+                call.reason = rec.reason;
             calls.push(call);
         }
         else if (tool === 'exclude_prop') {
@@ -116,6 +118,18 @@ export function parseToolCallLines(stdout) {
             const call = { tool: 'classify_component' };
             if (typeof rec.description === 'string')
                 call.description = rec.description;
+            if (typeof rec.rationale === 'object' && rec.rationale !== null) {
+                const r = rec.rationale;
+                const rationale = {};
+                if (typeof r.description === 'string')
+                    rationale.description = r.description;
+                if (typeof r.props === 'string')
+                    rationale.props = r.props;
+                if (typeof r.slots === 'string')
+                    rationale.slots = r.slots;
+                if (Object.keys(rationale).length > 0)
+                    call.rationale = rationale;
+            }
             calls.push(call);
         }
         else if (tool === 'classify_slot') {
@@ -131,6 +145,8 @@ export function parseToolCallLines(stdout) {
             }
             if (typeof rec.description === 'string')
                 call.description = rec.description;
+            if (typeof rec.rationale === 'string')
+                call.rationale = rec.rationale;
             calls.push(call);
         }
     }

package/dist/src/generate/command.d.ts

@@ -1,2 +1,8 @@
 import type { Command } from 'commander';
+/**
+ * Feature 8: render the warning banner shown when a custom skill prompt is
+ * active. Always cites the bundled invariants that the override bypasses so
+ * the operator cannot miss it.
+ */
+export declare function formatCustomPromptBanner(skill: 'components' | 'select', path: string): string;
 export declare function registerGenerateCommand(program: Command): void;

package/dist/src/generate/command.js

@@ -6,10 +6,12 @@ import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { parseToolCallLines, parseTokenToolCallLines, resolveBinary, runAgent, } from './agent-runner.js';
 import { OutputFormatter, c } from '../output/format.js';
+import { formatGenerateProgressLine } from './progress.js';
 import { buildPrompt, resolveSkillPath } from './prompt-builder.js';
 import { GenerateView } from './tui/GenerateView.js';
 import { registerGenerateEditCommand } from './edit/command.js';
 import { openPipelineDb, loadRawComponents, applyToolCalls, applyTokenToolCalls, computeComponentInputHash, computeTokenInputHash, lookupCache, lookupCacheByEntity, storeCache, copyComponentFromCache, copyTokensFromCache, renameEmptySlots, } from '../session/db.js';
+import { hashPromptForSkill } from '../session/cache-keys.js';
 import { getRefineArtifactsRoot, getRefineSessionPaths } from '../analyze/select/persistence.js';
 import { readExperiencesCredentials } from '../credentials-store.js';
 const execFileAsync = promisify(execFile);
@@ -17,6 +19,16 @@ const VALID_AGENTS = new Set(['claude', 'codex', 'opencode', 'cursor']);
 const DEFAULT_TIMEOUT_MS = Number(process.env.EDS_AGENT_TIMEOUT_MS ?? 3 * 60 * 1000);
 const DEFAULT_COMPONENT_CONCURRENCY = 10;
 const RETRY_BACKOFF_MS = Number(process.env.EDS_RETRY_BACKOFF_MS ?? 5_000);
+/**
+ * Feature 8: render the warning banner shown when a custom skill prompt is
+ * active. Always cites the bundled invariants that the override bypasses so
+ * the operator cannot miss it.
+ */
+export function formatCustomPromptBanner(skill, path) {
+    return (`WARNING: Custom prompt active for ${skill}: ${path}\n` +
+        `  Bundled invariants (utility-wrapper rejection, description content rules) do NOT apply.\n` +
+        `  You are responsible for the prompt's correctness.\n`);
+}
 function die(message) {
     process.stderr.write(`${message}\n`);
     process.exit(1);
@@ -104,11 +116,11 @@ 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');
 }
-async function runOneComponent(agent, model, db, sessionId, component, tokensInline, tokenMapInline, index, total, verbose, noCache) {
+async function runOneComponent(agent, model, db, sessionId, component, tokensInline, tokenMapInline, index, total, verbose, noCache, skillPathOverride, promptHash) {
     const pos = c.dim(`[${index + 1}/${total}]`);
     if (!noCache) {
         const inputHash = computeComponentInputHash(component);
-        const cached = lookupCache(db, inputHash, 'component', component.component_id);
+        const cached = lookupCache(db, inputHash, 'component', component.component_id, promptHash);
         if (cached) {
             copyComponentFromCache(db, cached.sourceSessionId, sessionId, component.component_id);
             process.stderr.write(`  ${pos}  ${c.bold(component.name)}  ${c.green('cached')}\n`);
@@ -168,6 +180,7 @@ async function runOneComponent(agent, model, db, sessionId, component, tokensInl
         tokenMapInline,
         outDir: process.cwd(),
         componentName: component.name,
+        skillPathOverride,
     });
     const maxAttempts = 2;
     let lastError = '';
@@ -215,7 +228,7 @@ async function runOneComponent(agent, model, db, sessionId, component, tokensInl
         const applied = applyToolCalls(db, sessionId, component.component_id, component.name, calls, warnings);
         if (!noCache) {
             const inputHash = computeComponentInputHash(component);
-            storeCache(db, inputHash, 'component', component.component_id, sessionId, false);
+            storeCache(db, inputHash, 'component', component.component_id, sessionId, false, promptHash);
         }
         return {
             componentName: component.name,
@@ -238,17 +251,20 @@ async function runOneComponent(agent, model, db, sessionId, component, tokensInl
         renamedSlotsCount: renames.length,
     };
 }
-async function runAllComponents(agent, model, db, sessionId, components, tokensInline, tokenMapInline, verbose, noCache) {
+async function runAllComponents(agent, model, db, sessionId, components, tokensInline, tokenMapInline, verbose, noCache, skillPathOverride, promptHash) {
     const concurrency = Number(process.env.EDS_GENERATE_CONCURRENCY ?? DEFAULT_COMPONENT_CONCURRENCY);
     process.stderr.write(`Categorizing ${c.bold(String(components.length))} component${components.length === 1 ? '' : 's'}` +
         c.dim(`  (concurrency: ${concurrency})`) +
         '\n');
     const results = new Array(components.length);
     let next = 0;
+    let completed = 0;
     async function worker() {
         while (next < components.length) {
             const i = next++;
-            results[i] = await runOneComponent(agent, model, db, sessionId, components[i], tokensInline, tokenMapInline, i, components.length, verbose, noCache);
+            results[i] = await runOneComponent(agent, model, db, sessionId, components[i], tokensInline, tokenMapInline, i, components.length, verbose, noCache, skillPathOverride, promptHash);
+            completed += 1;
+            process.stderr.write(`${formatGenerateProgressLine(completed, components.length, results[i].componentName)}\n`);
         }
     }
     await Promise.all(Array.from({ length: Math.min(concurrency, components.length) }, worker));
@@ -300,6 +316,19 @@ async function runGenerateSkill(skill, opts, verbose = false) {
         die(`Error: no agent configured. Pass --agent <name> or run experiences setup. Accepted values: claude, codex, opencode, cursor`);
     }
     const agent = agentName;
+    // Feature 8: resolve custom-prompt path for `components` (flag wins over
+    // saved credentials), validate, and emit the warning banner once at action
+    // entry.
+    const generatePromptPath = skill === 'components' ? (opts.generatePromptPath ?? savedCreds.generatePromptPath) : undefined;
+    if (generatePromptPath) {
+        if (!(await pathExists(resolve(generatePromptPath)))) {
+            die(`Error: custom prompt path not found: ${resolve(generatePromptPath)}`);
+        }
+        if (!generatePromptPath.toLowerCase().endsWith('.md')) {
+            process.stderr.write(`WARNING: custom prompt path does not end in .md (${generatePromptPath}) — proceeding anyway.\n`);
+        }
+        process.stderr.write(formatCustomPromptBanner('components', resolve(generatePromptPath)));
+    }
     if (skill === 'tokens' && !opts.rawTokens) {
         die('Error: --raw-tokens is required when using generate tokens');
     }
@@ -373,6 +402,7 @@ async function runGenerateSkill(skill, opts, verbose = false) {
             tokensInline,
             tokenMapInline,
             outDir: process.cwd(),
+            skillPathOverride: generatePromptPath,
         });
         process.stdout.write(prompt + '\n');
         process.exit(0);
@@ -390,7 +420,8 @@ async function runGenerateSkill(skill, opts, verbose = false) {
         const db = openPipelineDb();
         let componentResults;
         try {
-            componentResults = await runAllComponents(agent, model, db, sessionId, allComponents, tokensInline, tokenMapInline, verbose, opts.cache === false || process.env.EDS_NO_CACHE === '1');
+            const promptHash = await hashPromptForSkill('components', generatePromptPath);
+            componentResults = await runAllComponents(agent, model, db, sessionId, allComponents, tokensInline, tokenMapInline, verbose, opts.cache === false || process.env.EDS_NO_CACHE === '1', generatePromptPath, promptHash);
         }
         finally {
             db.close();
@@ -449,9 +480,10 @@ async function runGenerateSkill(skill, opts, verbose = false) {
                     resolvedSessionId = newId;
                 }
             }
+            const tokenPromptHash = await hashPromptForSkill('tokens');
             // Check cache before invoking agent
             if (!noCache) {
-                const tokenCached = lookupCache(db, tokenInputHash, 'token_set', '__tokens__');
+                const tokenCached = lookupCache(db, tokenInputHash, 'token_set', '__tokens__', tokenPromptHash);
                 if (tokenCached) {
                     copyTokensFromCache(db, tokenCached.sourceSessionId, resolvedSessionId);
                     sessionId = resolvedSessionId;
@@ -508,7 +540,7 @@ async function runGenerateSkill(skill, opts, verbose = false) {
             }
             applyTokenToolCalls(db, resolvedSessionId, tokenCalls, []);
             if (!noCache) {
-                storeCache(db, tokenInputHash, 'token_set', '__tokens__', resolvedSessionId, false);
+                storeCache(db, tokenInputHash, 'token_set', '__tokens__', resolvedSessionId, false, tokenPromptHash);
             }
             sessionId = resolvedSessionId;
             const groupCount = tokenCalls.filter((tc) => tc.tool === 'set_group').length;
@@ -541,7 +573,9 @@ function addAgentFlags(cmd) {
         .option('--model <name>', 'Model to use (defaults to a small/fast model per agent)')
         .option('--verbose', 'Show full agent output including reasoning text')
         .option('--dry-run', 'Print the prompt without invoking the agent')
-        .option('--no-cache', 'Bypass generation cache and force AI re-generation');
+        .option('--no-cache', 'Bypass ALL fine-grained caches (extract, select, generate) and force AI re-run. ' +
+        'Cache keys now factor in prompt content — 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.');
 }
 export function registerGenerateCommand(program) {
     const generate = program.command('generate').description('Generate CDF/DTCG artifacts or correct generation output');
@@ -551,7 +585,8 @@ export function registerGenerateCommand(program) {
         .description('Invoke a coding agent to produce components.json from raw analysis output')
         .option('--session <id>', 'Session ID from analyze extract (defaults to most recent)')
         .option('--tokens <path>', 'Path to tokens.json for token-linked prop resolution')
-        .option('--token-map <path>', 'Path to token-name-map.json sidecar');
+        .option('--token-map <path>', 'Path to token-name-map.json sidecar')
+        .option('--generate-prompt-path <path>', 'Path to a custom .md skill prompt for components generation (bypasses bundled prompt invariants)');
     addAgentFlags(componentsCmd).action(async (opts) => {
         await runGenerateSkill('components', opts, opts.verbose ?? false);
     });

package/dist/src/generate/progress.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Formats a structured generation-progress line for the wizard parser.
+ *
+ * Emitted at terminal completion of each component (success, cache hit,
+ * pinned hit, or final failure). `done` represents the count of completed
+ * components, which is monotonically non-decreasing — unlike the legacy
+ * `[index+1/total]` line, which reports input position.
+ */
+export declare function formatGenerateProgressLine(done: number, total: number, name: string): string;

package/dist/src/generate/progress.js

@@ -0,0 +1,11 @@
+/**
+ * Formats a structured generation-progress line for the wizard parser.
+ *
+ * Emitted at terminal completion of each component (success, cache hit,
+ * pinned hit, or final failure). `done` represents the count of completed
+ * components, which is monotonically non-decreasing — unlike the legacy
+ * `[index+1/total]` line, which reports input position.
+ */
+export function formatGenerateProgressLine(done, total, name) {
+    return `progress=generate:${done}/${total}:${name}`;
+}

package/dist/src/generate/prompt-builder.d.ts

@@ -13,6 +13,14 @@ export interface PromptOptions {
     outDir: string;
     /** For components skill only: the single component's name (used in error messages). */
     componentName?: string;
+    /**
+     * Feature 8: custom prompt path override. When set, this absolute or relative
+     * `.md` path is read in place of the bundled skill file. The bundled-prompt
+     * invariants (utility-wrapper rejection, description content rules, etc.) do
+     * NOT apply under an override — callers are responsible for showing the
+     * appropriate warning banner.
+     */
+    skillPathOverride?: string;
 }
 export declare function buildPrompt(options: PromptOptions): Promise<string>;
 export declare function resolveSkillPath(skill: Skill): string;

package/dist/src/generate/prompt-builder.js

@@ -13,7 +13,7 @@ const OUTPUT_FILES = {
     select: 'select.json',
 };
 export async function buildPrompt(options) {
-    const skillContent = await readSkillFile(options.skill);
+    const skillContent = await readSkillFile(options.skill, options.skillPathOverride);
     const preamble = buildPreamble(options);
     return `${preamble}\n\nSkill instructions follow:\n---\n${skillContent}`;
 }
@@ -34,7 +34,16 @@ export function resolveSkillPath(skill) {
         dir = parent;
     }
 }
-async function readSkillFile(skill) {
+async function readSkillFile(skill, override) {
+    if (override) {
+        const skillPath = resolve(override);
+        try {
+            return await readFile(skillPath, 'utf8');
+        }
+        catch {
+            throw new Error(`custom prompt file not found (skill: ${skill}, path: ${skillPath})`);
+        }
+    }
     const skillPath = resolveSkillPath(skill);
     try {
         return await readFile(skillPath, 'utf8');
@@ -123,13 +132,13 @@ Do NOT write any files or emit any JSON blobs. Instead, emit one JSON object per
 The four tool calls you may emit are:
 
 \`\`\`
-{"tool":"classify_component","description":"<optional component-level description>"}
+{"tool":"classify_component","description":"<optional component-level description>","rationale":{"description":"<why this component is classified the way it is>","props":"<why these props were chosen>","slots":"<why these slots were chosen>"}}
 
-{"tool":"classify_prop","prop":"<propName>","cdf_type":"<type>","cdf_category":"<category>","required":<bool>,"description":"<reason>","values":["a","b"],"token_kind":"color","default":"<value>"}
+{"tool":"classify_prop","prop":"<propName>","cdf_type":"<type>","cdf_category":"<category>","required":<bool>,"description":"<short customer-facing description>","reason":"<full internal rationale; not customer-facing>","values":["a","b"],"token_kind":"color","default":"<value>"}
 
 {"tool":"exclude_prop","prop":"<propName>","reason":"<why excluded>"}
 
-{"tool":"classify_slot","slot":"<slotName>","required":<bool>,"allowed_components":["ComponentName"],"description":"<reason>"}
+{"tool":"classify_slot","slot":"<slotName>","required":<bool>,"allowed_components":["ComponentName"],"description":"<reason>","rationale":"<why this slot was kept in the catalog>"}
 \`\`\`
 
 Rules:
@@ -143,12 +152,14 @@ Rules:
 - href and URL props → cdf_type "string", cdf_category "content". Do NOT use cdf_type "link" — it is not valid.
 - Framework internals (ref, event handlers, test IDs) → exclude_prop.
 - CSS design props (className, style, styles, positional/geometric props: top, bottom, left, right, rotation, offset, etc.) → classify_prop, cdf_type: "string", cdf_category: "design".
+- On classify_component, "rationale" fields are operator-facing (read-only) but may surface in customer-facing exports. The "rationale.description" field is subject to the description content rules in the skill prompt (no internal initiative names). "rationale.props" and "rationale.slots" describe your reasoning about scope; "classify_slot.rationale" explains why each slot was kept.
+- On classify_prop, "reason" is REQUIRED and is the LLM's internal rationale — shown to the developer reviewing the import, never to end-users. "description" is the customer-facing copy and is subject to the description content rules in the skill prompt. Keep them distinct: "description" is short and customer-facing; "reason" explains your reasoning in detail.
 - You may emit prose lines (not starting with {) anywhere — they are ignored by the parser and serve as your reasoning log.`;
 }
 function buildSelectAutonomousPreamble(inputBlock) {
     return `You are running as part of the experience-design-system-cli import pipeline in AUTONOMOUS mode. The developer is not present to answer questions.
 
-Your task: review the single component provided below and decide whether it belongs in Contentful Experience Orchestration as a Component Type. Apply all judgment calls yourself — do not pause to ask for confirmation. Include a brief "reason" to document your reasoning.
+Your task: review the components provided below and decide whether each belongs in Contentful Experience Orchestration as a Component Type. The input is a JSON array — you may receive 1–N components in a single message. Emit one tool call per input component, named after the component. Apply all judgment calls yourself — do not pause to ask for confirmation. Include a brief "reason" to document your reasoning for each decision.
 
 Key rule: accept any component that renders visible UI — atoms, molecules, and organisms are all valid Component Types in Contentful Experience Orchestration. Reject only components that produce zero visual output: React hooks, pure context providers, A/B testing or variant-routing wrappers, analytics trackers, and security utilities. Do NOT reject a component because it has few props, is low-level, or has some A/B testing or personalization-related props mixed in — those props are handled in the generate step.
 
@@ -156,9 +167,9 @@ All input data is provided inline below — do not read any additional files.${i
 
 ## Output protocol
 
-Do NOT write any files or emit any JSON blobs. Instead, emit one JSON object on a single line to stdout. The CLI reads your stdout line by line.
+Do NOT write any files or emit any JSON blobs. Instead, emit JSON tool calls one per line to stdout. The CLI reads your stdout line by line.
 
-The two tool calls — emit exactly one:
+The two tool calls — emit exactly one per input component:
 
 \`\`\`
 {"tool":"select_component","name":"<ComponentName>","reason":"<brief reason>"}
@@ -167,9 +178,9 @@ The two tool calls — emit exactly one:
 \`\`\`
 
 Rules:
-- Emit exactly one JSON object, on one line. No multi-line JSON. No markdown fences.
-- The name must match the component name in the input exactly.
-- You may emit prose lines (not starting with {) to reason before the final tool call — they are ignored by the parser.`;
+- Emit exactly one JSON object per line. No multi-line JSON. No markdown fences.
+- Emit exactly one tool call per input component. The "name" field must match a component name from the input array exactly. Tool calls may appear in any order.
+- You may emit prose lines (not starting with {) to reason before each tool call — they are ignored by the parser.`;
 }
 function buildTokensAutonomousPreamble(inputBlock) {
     return `You are running as part of the experience-design-system-cli generate pipeline in AUTONOMOUS mode. The developer is not present to answer questions.

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

@@ -0,0 +1,23 @@
+/**
+ * Resolution chain for `--agent` and `--model` overrides 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.
+ *
+ * These helpers produce the resolved values to feed into `WizardApp` /
+ * `runPipeline`:
+ *
+ *   1. CLI flag wins when provided.
+ *   2. Otherwise, the value persisted in `credentials.json` (written by
+ *      `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.
+ */
+/** Built-in fallback agent when neither a flag nor a stored preference is set. */
+export declare const DEFAULT_AGENT = "claude";
+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/agent-model-resolve.js

@@ -0,0 +1,35 @@
+/**
+ * Resolution chain for `--agent` and `--model` overrides 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.
+ *
+ * These helpers produce the resolved values to feed into `WizardApp` /
+ * `runPipeline`:
+ *
+ *   1. CLI flag wins when provided.
+ *   2. Otherwise, the value persisted in `credentials.json` (written by
+ *      `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.
+ */
+/** Built-in fallback agent when neither a flag nor a stored preference is set. */
+export const DEFAULT_AGENT = 'claude';
+export function resolveAgent(flagValue, storedValue) {
+    if (flagValue && flagValue.length > 0)
+        return flagValue;
+    if (storedValue && storedValue.length > 0)
+        return storedValue;
+    return DEFAULT_AGENT;
+}
+export function resolveModel(flagValue, storedValue) {
+    if (flagValue && flagValue.length > 0)
+        return flagValue;
+    if (storedValue && storedValue.length > 0)
+        return storedValue;
+    return undefined;
+}

package/dist/src/import/auto-filter-resolve.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Resolve the effective auto-filter setting from a CLI flag plus the persisted
+ * config preference.
+ *
+ * Precedence (highest first):
+ *   1. CLI flag (`--auto-filter` or `--no-auto-filter`) — wins when set
+ *   2. Config (`credentials.json` `autoFilter` field) — used when flag absent
+ *   3. Default ON — when neither is set
+ */
+export declare function resolveAutoFilter(opts: {
+    autoFilter?: boolean;
+}, configAutoFilter?: boolean): boolean;

package/dist/src/import/auto-filter-resolve.js

@@ -0,0 +1,16 @@
+/**
+ * Resolve the effective auto-filter setting from a CLI flag plus the persisted
+ * config preference.
+ *
+ * Precedence (highest first):
+ *   1. CLI flag (`--auto-filter` or `--no-auto-filter`) — wins when set
+ *   2. Config (`credentials.json` `autoFilter` field) — used when flag absent
+ *   3. Default ON — when neither is set
+ */
+export function resolveAutoFilter(opts, configAutoFilter) {
+    if (opts.autoFilter !== undefined)
+        return opts.autoFilter;
+    if (configAutoFilter !== undefined)
+        return configAutoFilter;
+    return true;
+}