@contentful/experience-design-system-cli 2.7.3 → 2.7.4-dev-build-595febb.0

package/dist/package.json

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

package/dist/src/analyze/command.js

@@ -1,15 +1,16 @@
 import { createElement } from 'react';
 import { render } from 'ink';
 import { mkdir, readdir, stat } from 'node:fs/promises';
-import { isAbsolute, join, resolve } from 'node:path';
+import { isAbsolute, join, relative, resolve } from 'node:path';
 import { extractComponents } from './extract/pipeline.js';
 import { AnalyzeView } from './tui/AnalyzeView.js';
 import { registerAnalyzeEditCommand } from './select/command.js';
 import { registerAnalyzeSelectAgentCommand } from './select-agent/command.js';
-import { openPipelineDb, getOrCreateSession, createStep, updateStep, storeRawComponents } from '../session/db.js';
+import { openPipelineDb, getOrCreateSession, createStep, updateStep, storeRawComponents, storeScannedFiles, } from '../session/db.js';
 import { preClassifyComponent } from './pre-classify.js';
 import { isNonAuthorableComponent } from './extract/non-authorable-filter.js';
 import { computeExtractionScore, deriveNeedsReview } from './extract/scoring.js';
+import { describeReviewReasons, inspectComponentSource } from './extract/source-inspection.js';
 const SCANNED_FILE_EXTENSIONS = new Set(['.astro', '.js', '.jsx', '.ts', '.tsx', '.vue']);
 const IGNORED_DIRECTORY_NAMES = new Set([
     '.git',
@@ -46,6 +47,13 @@ function pluralize(count, singular, plural = `${singular}s`) {
 function resolveFromProjectRoot(projectRoot, inputPath) {
     return isAbsolute(inputPath) ? inputPath : resolve(projectRoot, inputPath);
 }
+function wrapperConfidenceToIssueCount(confidence) {
+    if (confidence >= 4)
+        return 2;
+    if (confidence === 3)
+        return 1;
+    return 0;
+}
 async function pathExists(path) {
     return Boolean(await stat(path).catch(() => null));
 }
@@ -121,25 +129,47 @@ export function registerAnalyzeCommand(program) {
             inputPath: projectRoot,
             outDir,
         });
-        const stepId = createStep(db, sessionId, 'analyze extract', { project: projectRoot });
+        const stepId = createStep(db, sessionId, 'analyze extract', {
+            project: projectRoot,
+        });
         const classifiedComponents = extraction.components.map(preClassifyComponent);
+        const inspectedComponents = await Promise.all(classifiedComponents.map(async (component) => ({
+            component,
+            inspection: await inspectComponentSource(component),
+        })));
         const filteredComponents = [];
         const filterWarnings = [];
-        for (const component of classifiedComponents) {
+        for (const { component, inspection } of inspectedComponents) {
             const verdict = isNonAuthorableComponent(component);
-            if (verdict.skip) {
+            const keepDespiteZeroSurface = verdict.skip && verdict.reason === 'component has no props and no slots' && inspection.keepDespiteZeroSurface;
+            if (verdict.skip && !keepDespiteZeroSurface) {
                 filterWarnings.push(`Skipped non-authorable component: ${component.name} (${verdict.reason})`);
                 continue;
             }
-            const { confidence, reasons } = computeExtractionScore(component);
+            if (keepDespiteZeroSurface) {
+                filterWarnings.push(`${component.name}: retained despite 0 props/slots because the source renders visible or compositional UI`);
+            }
+            if (inspection.reviewReasons.length > 0) {
+                const reviewNotes = describeReviewReasons(inspection.reviewReasons)
+                    .filter((note) => note !== 'high-confidence data-fetch wrapper')
+                    .join('; ');
+                if (reviewNotes) {
+                    filterWarnings.push(`${component.name}: ${reviewNotes}`);
+                }
+            }
+            const { confidence, reasons } = computeExtractionScore(component, {
+                additionalIssueCount: wrapperConfidenceToIssueCount(inspection.wrapperConfidence),
+                additionalReasons: inspection.reviewReasons,
+            });
             filteredComponents.push({
                 ...component,
                 extractionConfidence: confidence,
                 reviewReasons: reasons,
-                needsReview: deriveNeedsReview(confidence),
+                needsReview: deriveNeedsReview(confidence) || inspection.wrapperConfidence >= 4 || inspection.keepDespiteZeroSurface,
             });
         }
         storeRawComponents(db, sessionId, filteredComponents);
+        storeScannedFiles(db, sessionId, sourceFiles.map((f) => relative(projectRoot, f)));
         updateStep(db, stepId, 'complete', { sessionId });
         db.close();
         const allWarnings = [...extraction.warnings, ...filterWarnings];

package/dist/src/analyze/extract/scoring.d.ts

@@ -4,5 +4,9 @@ export type ExtractionScore = {
     confidence: ExtractionConfidence;
     reasons: string[];
 };
-export declare function computeExtractionScore(component: RawComponentDefinition): ExtractionScore;
+export interface ExtractionScoreOptions {
+    additionalIssueCount?: number;
+    additionalReasons?: string[];
+}
+export declare function computeExtractionScore(component: RawComponentDefinition, options?: ExtractionScoreOptions): ExtractionScore;
 export declare function deriveNeedsReview(confidence: ExtractionConfidence): boolean;

package/dist/src/analyze/extract/scoring.js

@@ -44,7 +44,7 @@ function isWidePrimitiveUnion(type) {
     return baseCount >= 3 || (baseCount >= 2 && nullabilityCount > 0 && baseCount + nullabilityCount >= 3);
 }
 // Count the number of issues found for scoring
-function countIssues(component) {
+function countIssues(component, options = {}) {
     let count = 0;
     const reasons = [];
     if (component.props.length === 0 && component.slots.length === 0) {
@@ -72,6 +72,10 @@ function countIssues(component) {
             break;
         }
     }
+    count += options.additionalIssueCount ?? 0;
+    if (options.additionalReasons && options.additionalReasons.length > 0) {
+        reasons.push(...options.additionalReasons);
+    }
     return { count, reasons: [...new Set(reasons)] };
 }
 // Maps issue count to a 1–5 confidence scale:
@@ -91,8 +95,8 @@ function issueCountToConfidence(count) {
         return 2;
     return 1;
 }
-export function computeExtractionScore(component) {
-    const { count, reasons } = countIssues(component);
+export function computeExtractionScore(component, options = {}) {
+    const { count, reasons } = countIssues(component, options);
     return {
         confidence: issueCountToConfidence(count),
         reasons,

package/dist/src/analyze/extract/source-inspection.d.ts

@@ -0,0 +1,13 @@
+import type { RawComponentDefinition } from '../../types.js';
+export declare const HIGH_CONFIDENCE_DATA_FETCH_WRAPPER_REASON = "data-fetch-wrapper";
+export declare const POSSIBLE_DATA_FETCH_WRAPPER_REASON = "possible-data-fetch-wrapper";
+export declare const ZERO_SURFACE_RENDERED_UI_REASON = "zero-surface:rendered-ui";
+export interface ComponentSourceInspection {
+    wrapperConfidence: 0 | 1 | 2 | 3 | 4 | 5;
+    reviewReasons: string[];
+    keepDespiteZeroSurface: boolean;
+}
+export declare function inspectComponentSource(component: RawComponentDefinition): Promise<ComponentSourceInspection>;
+export declare function isDataWrapperReviewReason(reason: string): boolean;
+export declare function describeReviewReason(reason: string): string;
+export declare function describeReviewReasons(reasons: string[]): string[];

package/dist/src/analyze/extract/source-inspection.js

@@ -0,0 +1,189 @@
+import { readFile } from 'node:fs/promises';
+export const HIGH_CONFIDENCE_DATA_FETCH_WRAPPER_REASON = 'data-fetch-wrapper';
+export const POSSIBLE_DATA_FETCH_WRAPPER_REASON = 'possible-data-fetch-wrapper';
+export const ZERO_SURFACE_RENDERED_UI_REASON = 'zero-surface:rendered-ui';
+const DATA_WRAPPER_REASON_PREFIX = 'data-wrapper:';
+const INFRA_PROP_NAMES = new Set(['id', 'locale', 'preview', 'slug', 'topic', 'previousComponent', '__typename']);
+const VISIBLE_UI_TAG_PATTERN = /<(?:[A-Z][A-Za-z0-9_.]*|div|span|section|main|article|header|footer|nav|aside|img|video|p|h[1-6]|ul|ol|li|button|input|textarea|select|form|label|table|tbody|thead|tr|td|th)\b/;
+const GENERATED_IMPORT_PATTERN = /from\s+['"][^'"]*__generated[^'"]*['"]/;
+const GENERATED_QUERY_HOOK_PATTERN = /\buse[A-Z][A-Za-z0-9]*(?:Lazy|Suspense)?Query\s*\(/;
+const GQL_FILENAME_PATTERN = /(?:-gql|-ggl)\.[cm]?[jt]sx?$/i;
+const LOADING_NULL_GUARD_PATTERN = /if\s*\([^)]*(?:isLoading|loading|!data|!\w+Collection|!\w+Item|!\w+)\s*[^)]*\)\s*return\s+null\b/;
+const IMPORT_PATTERN = /import\s+(?:type\s+)?(.+?)\s+from\s+['"]([^'"]+)['"]/g;
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function parseImportedNames(importClause) {
+    const trimmed = importClause.trim();
+    if (!trimmed)
+        return [];
+    const names = [];
+    const defaultAndNamed = trimmed.split(',').map((part) => part.trim());
+    for (const part of defaultAndNamed) {
+        if (!part)
+            continue;
+        if (part.startsWith('{') && part.endsWith('}')) {
+            for (const named of part
+                .slice(1, -1)
+                .split(',')
+                .map((item) => item.trim())
+                .filter(Boolean)) {
+                const [local] = named.split(/\s+as\s+/i);
+                if (local)
+                    names.push(local.trim());
+            }
+            continue;
+        }
+        const [local] = part.split(/\s+as\s+/i);
+        if (local)
+            names.push(local.trim());
+    }
+    return names;
+}
+function collectSiblingRendererImports(sourceText) {
+    const names = new Set();
+    for (const match of sourceText.matchAll(IMPORT_PATTERN)) {
+        const importClause = match[1]?.trim() ?? '';
+        const importPath = match[2]?.trim() ?? '';
+        if (!importPath.startsWith('./'))
+            continue;
+        if (importPath.includes('__generated'))
+            continue;
+        if (/-g(?:ql|gl)(?:$|\.)/i.test(importPath))
+            continue;
+        for (const name of parseImportedNames(importClause)) {
+            if (name)
+                names.add(name);
+        }
+    }
+    return [...names];
+}
+function hasSiblingForwardRender(sourceText, siblingImports) {
+    return siblingImports.some((name) => {
+        const renderPattern = new RegExp(`<${escapeRegExp(name)}\\b[\\s\\S]*?(?:/>|</${escapeRegExp(name)}>)`);
+        if (!renderPattern.test(sourceText))
+            return false;
+        const siblingSpreadPattern = new RegExp(`<${escapeRegExp(name)}\\b[^>]*\\{\\.\\.\\.(?!props\\b)[^}]+\\}`);
+        const propsPlusSiblingSpreadPattern = new RegExp(`<${escapeRegExp(name)}\\b[^>]*\\{\\.\\.\\.props\\}[^>]*\\{\\.\\.\\.(?!props\\b)[^}]+\\}`);
+        return siblingSpreadPattern.test(sourceText) || propsPlusSiblingSpreadPattern.test(sourceText);
+    });
+}
+function hasVisibleUiRender(sourceText) {
+    return /return\s*(?:\(|<)/.test(sourceText) && VISIBLE_UI_TAG_PATTERN.test(sourceText);
+}
+function infraPropNames(component) {
+    const props = component.props.map((prop) => prop.name);
+    return props.length > 0 && props.every((prop) => INFRA_PROP_NAMES.has(prop)) ? props : [];
+}
+function scoreToConfidence(score) {
+    if (score <= 0)
+        return 0;
+    if (score <= 2)
+        return 2;
+    if (score <= 4)
+        return 3;
+    if (score <= 6)
+        return 4;
+    return 5;
+}
+function dedupeReasons(reasons) {
+    return [...new Set(reasons)];
+}
+export async function inspectComponentSource(component) {
+    let sourceText = '';
+    try {
+        sourceText = await readFile(component.source, 'utf8');
+    }
+    catch {
+        return {
+            wrapperConfidence: 0,
+            reviewReasons: [],
+            keepDespiteZeroSurface: false,
+        };
+    }
+    const reviewReasons = [];
+    let wrapperScore = 0;
+    const hasGeneratedQueryHook = GENERATED_IMPORT_PATTERN.test(sourceText) && GENERATED_QUERY_HOOK_PATTERN.test(sourceText);
+    const infraProps = infraPropNames(component);
+    const siblingImports = collectSiblingRendererImports(sourceText);
+    if (GQL_FILENAME_PATTERN.test(component.source)) {
+        reviewReasons.push('data-wrapper:gql-filename');
+        wrapperScore += 1;
+    }
+    if (hasGeneratedQueryHook) {
+        reviewReasons.push('data-wrapper:generated-query-hook');
+        wrapperScore += 3;
+    }
+    // Require corroboration from a stronger signal before counting sibling imports —
+    // otherwise any composed component that imports two sub-components scores +1 here.
+    if (siblingImports.length > 0 && (hasGeneratedQueryHook || infraProps.length > 0)) {
+        reviewReasons.push('data-wrapper:sibling-renderer-import');
+        wrapperScore += 1;
+    }
+    if (hasSiblingForwardRender(sourceText, siblingImports)) {
+        reviewReasons.push('data-wrapper:fetch-forward-render');
+        wrapperScore += 3;
+    }
+    if (sourceText.includes('useContentfulLiveUpdates(') || sourceText.includes('useContentfulContext(')) {
+        reviewReasons.push('data-wrapper:contentful-runtime');
+        wrapperScore += 1;
+    }
+    if (infraProps.length > 0) {
+        reviewReasons.push('data-wrapper:infra-props');
+        wrapperScore += 2;
+    }
+    if (LOADING_NULL_GUARD_PATTERN.test(sourceText)) {
+        reviewReasons.push('data-wrapper:loading-null-guard');
+        wrapperScore += 1;
+    }
+    const wrapperConfidence = scoreToConfidence(wrapperScore);
+    if (wrapperConfidence >= 4) {
+        reviewReasons.unshift(HIGH_CONFIDENCE_DATA_FETCH_WRAPPER_REASON);
+    }
+    else if (wrapperConfidence === 3) {
+        reviewReasons.unshift(POSSIBLE_DATA_FETCH_WRAPPER_REASON);
+    }
+    const keepDespiteZeroSurface = component.props.length === 0 && component.slots.length === 0 && hasVisibleUiRender(sourceText);
+    if (keepDespiteZeroSurface) {
+        reviewReasons.push(ZERO_SURFACE_RENDERED_UI_REASON);
+    }
+    return {
+        wrapperConfidence,
+        reviewReasons: dedupeReasons(reviewReasons),
+        keepDespiteZeroSurface,
+    };
+}
+export function isDataWrapperReviewReason(reason) {
+    return (reason === HIGH_CONFIDENCE_DATA_FETCH_WRAPPER_REASON ||
+        reason === POSSIBLE_DATA_FETCH_WRAPPER_REASON ||
+        reason.startsWith(DATA_WRAPPER_REASON_PREFIX));
+}
+export function describeReviewReason(reason) {
+    switch (reason) {
+        case HIGH_CONFIDENCE_DATA_FETCH_WRAPPER_REASON:
+            return 'high-confidence data-fetch wrapper';
+        case POSSIBLE_DATA_FETCH_WRAPPER_REASON:
+            return 'possible data-fetch wrapper';
+        case 'data-wrapper:gql-filename':
+            return 'source file follows a gql wrapper naming pattern';
+        case 'data-wrapper:generated-query-hook':
+            return 'imports and calls a generated query hook';
+        case 'data-wrapper:sibling-renderer-import':
+            return 'imports a sibling renderer from the same folder';
+        case 'data-wrapper:fetch-forward-render':
+            return 'forwards fetched data into a sibling renderer';
+        case 'data-wrapper:contentful-runtime':
+            return 'uses Contentful runtime hooks';
+        case 'data-wrapper:infra-props':
+            return 'only exposes infra-fetch props';
+        case 'data-wrapper:loading-null-guard':
+            return 'returns early while loading or when fetched data is missing';
+        case ZERO_SURFACE_RENDERED_UI_REASON:
+            return 'source renders visible/compositional UI despite zero extracted props and slots';
+        default:
+            return reason;
+    }
+}
+export function describeReviewReasons(reasons) {
+    return dedupeReasons(reasons.map(describeReviewReason));
+}

package/dist/src/analyze/select-agent/command.js

@@ -1,9 +1,11 @@
-import { openPipelineDb, loadRawComponents, createStep, updateStep } from '../../session/db.js';
-import { getRefineArtifactsRoot, ensureRefineSession, getRefineSessionPaths, saveReviewState, } from '../select/persistence.js';
+import { openPipelineDb, loadRawComponents, loadScannedFiles, createStep, updateStep } from '../../session/db.js';
+import { appendReviewEvent, getRefineArtifactsRoot, ensureRefineSession, getRefineSessionPaths, saveReviewState, } from '../select/persistence.js';
 import { loadReviewInput } from '../select/parser.js';
 import { buildPrompt } from '../../generate/prompt-builder.js';
 import { parseSelectToolCallLines, runAgent } from '../../generate/agent-runner.js';
 import { OutputFormatter, c } from '../../output/format.js';
+import { buildRepoContextIndex, buildSelectionContext } from './context-builder.js';
+import { isAbsolute, resolve } from 'node:path';
 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_CONCURRENCY = 5;
@@ -30,8 +32,12 @@ function resolveSessionId(sessionFlag) {
         db.close();
     }
 }
-function buildComponentData(component) {
-    return {
+function componentKey(component) {
+    return `${component.name}::${component.source}`;
+}
+function buildComponentData(candidate) {
+    const { component, selectionContext } = candidate;
+    const payload = {
         name: component.name,
         source: component.source,
         framework: component.framework,
@@ -40,13 +46,47 @@ function buildComponentData(component) {
         propNames: component.props.slice(0, 8).map((p) => p.name),
         props: component.props,
         slots: component.slots,
+        extractionConfidence: component.extractionConfidence ?? null,
+        needsReview: component.needsReview ?? false,
     };
+    if (component.reviewReasons && component.reviewReasons.length > 0) {
+        payload.reviewReasons = component.reviewReasons;
+    }
+    if (selectionContext) {
+        payload.selectionContext = selectionContext;
+    }
+    return payload;
+}
+function resolveProjectRoot(sessionId, projectRootFlag) {
+    if (projectRootFlag)
+        return resolve(projectRootFlag);
+    const db = openPipelineDb();
+    try {
+        const row = db
+            .prepare(`SELECT inputs FROM steps
+         WHERE session_id = ?
+           AND command = 'analyze extract'
+         ORDER BY started_at DESC
+         LIMIT 1`)
+            .get(sessionId);
+        if (!row?.inputs)
+            return null;
+        const parsed = JSON.parse(row.inputs);
+        return parsed.project ? resolve(parsed.project) : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        db.close();
+    }
 }
-async function selectOneComponent(agent, model, component, index, total, verbose) {
+async function selectOneComponent(agent, model, candidate, index, total, verbose) {
+    const { component } = candidate;
     const prompt = await buildPrompt({
         skill: 'select',
         mode: 'autonomous',
-        rawComponentsInline: JSON.stringify([buildComponentData(component)], null, 2),
+        rawComponentsInline: JSON.stringify([buildComponentData(candidate)], null, 2),
         outDir: process.cwd(),
     });
     const pos = c.dim(`[${index + 1}/${total}]`);
@@ -63,34 +103,53 @@ async function selectOneComponent(agent, model, component, index, total, verbose
         onOutput: (chunk) => formatter.push(chunk),
     });
     formatter.flush();
-    process.stderr.write(`  ${pos}  ${c.bold(component.name)}\n${outputBuf}`);
+    if (verbose) {
+        process.stderr.write(`  ${pos}  ${c.bold(component.name)}\n${outputBuf}`);
+    }
     if (result.timedOut) {
-        return { componentName: component.name, decision: null, failed: true, error: 'timed out' };
+        process.stderr.write(`  ${pos}  ${c.bold(component.name)}  ${c.yellow('timed out')}\n`);
+        return {
+            componentKey: componentKey(component),
+            componentName: component.name,
+            decision: null,
+            failed: true,
+        };
     }
     if (result.exitCode !== 0) {
+        process.stderr.write(`  ${pos}  ${c.bold(component.name)}  ${c.red(`agent exited with code ${result.exitCode}`)}\n`);
         return {
+            componentKey: componentKey(component),
             componentName: component.name,
             decision: null,
             failed: true,
-            error: `agent exited with code ${result.exitCode}`,
         };
     }
     const { calls, warnings } = parseSelectToolCallLines(result.stdout);
     if (warnings.length > 0) {
-        for (const w of warnings)
-            process.stderr.write(`  ${c.yellow('⚠')}  ${component.name}: ${w}\n`);
+        for (const warning of warnings) {
+            process.stderr.write(`  ${c.yellow('⚠')}  ${component.name}: ${warning}\n`);
+        }
     }
-    const call = calls.find((call) => call.name === component.name) ?? calls[0];
+    const call = calls.find((toolCall) => toolCall.name === component.name) ?? calls[0];
     if (!call) {
+        process.stderr.write(`  ${pos}  ${c.bold(component.name)}  ${c.yellow('no tool call')}\n`);
         return {
+            componentKey: componentKey(component),
             componentName: component.name,
             decision: null,
             failed: true,
-            error: 'agent produced no tool call for this component',
         };
     }
     const decision = call.tool === 'select_component' ? 'accepted' : 'rejected';
-    return { componentName: component.name, decision, reason: call.reason, failed: false };
+    const finalColor = decision === 'accepted' ? c.green : c.red;
+    process.stderr.write(`  ${pos}  ${c.bold(component.name)}  ${finalColor(decision)}${call.reason ? `  ${c.dim(call.reason)}` : ''}\n`);
+    return {
+        componentKey: componentKey(component),
+        componentName: component.name,
+        decision,
+        reason: call.reason,
+        failed: false,
+    };
 }
 async function selectAllComponents(agent, model, components, verbose) {
     const concurrency = Number(process.env.EDS_GENERATE_CONCURRENCY ?? DEFAULT_CONCURRENCY);
@@ -126,10 +185,13 @@ export function registerAnalyzeSelectAgentCommand(program) {
         }
         const agent = opts.agent;
         const sessionId = resolveSessionId(opts.session);
+        const selectionRoot = resolveProjectRoot(sessionId, opts.projectRoot);
         const db = openPipelineDb();
         let rawComponents;
+        let scannedFiles = [];
         try {
             rawComponents = loadRawComponents(db, sessionId);
+            scannedFiles = loadScannedFiles(db, sessionId);
         }
         finally {
             db.close();
@@ -139,8 +201,25 @@ export function registerAnalyzeSelectAgentCommand(program) {
             process.exit(1);
             return;
         }
+        if (selectionRoot && scannedFiles.length > 0) {
+            scannedFiles = scannedFiles.map((f) => (isAbsolute(f) ? f : resolve(selectionRoot, f)));
+        }
+        if (selectionRoot && scannedFiles.length === 0 && rawComponents.length > 0) {
+            process.stderr.write('warn: session has no scanned-files index (likely extracted on an older CLI version). ' +
+                'Re-run `analyze extract` to enable data-fetch wrapper detection during selection.\n');
+        }
+        let selectionCandidates = rawComponents.map((component) => ({ component }));
+        if (selectionRoot && scannedFiles.length > 0) {
+            const repoIndex = await buildRepoContextIndex(selectionRoot, scannedFiles).catch(() => null);
+            if (repoIndex) {
+                selectionCandidates = rawComponents.map((component) => ({
+                    component,
+                    selectionContext: buildSelectionContext(repoIndex, component),
+                }));
+            }
+        }
         if (opts.dryRun) {
-            const first = rawComponents[0];
+            const first = selectionCandidates[0];
             const prompt = await buildPrompt({
                 skill: 'select',
                 mode: 'autonomous',
@@ -151,20 +230,16 @@ export function registerAnalyzeSelectAgentCommand(program) {
             process.exit(0);
             return;
         }
-        const selectResults = await selectAllComponents(agent, opts.model, rawComponents, opts.verbose ?? false);
-        // Build decision map from results
+        const selectResults = await selectAllComponents(agent, opts.model, selectionCandidates, opts.verbose ?? false);
         const decisions = new Map();
         for (const r of selectResults) {
-            if (!r.failed && r.decision) {
-                decisions.set(r.componentName, r.decision);
-            }
+            decisions.set(r.componentKey, r.decision);
         }
-        // Load existing snapshot and apply decisions
         const artifactsRoot = getRefineArtifactsRoot();
         let snapshot;
         try {
             snapshot = await loadReviewInput(rawComponents, {
-                reviewRoot: opts.projectRoot,
+                reviewRoot: selectionRoot ?? undefined,
             });
             snapshot = await ensureRefineSession(sessionId, artifactsRoot, snapshot);
         }
@@ -177,25 +252,38 @@ export function registerAnalyzeSelectAgentCommand(program) {
         const updated = {
             ...snapshot,
             components: snapshot.components.map((comp) => {
-                const decision = decisions.get(comp.name);
+                const key = componentKey(comp.originalProposal);
+                const decision = decisions.get(key);
                 if (!decision)
                     return comp;
                 return { ...comp, status: decision };
             }),
         };
         await saveReviewState(paths.statePath, updated);
+        await Promise.all(updated.components
+            .filter((component) => component.status === 'accepted' || component.status === 'rejected')
+            .map((component) => appendReviewEvent(paths.eventsPath, {
+            type: 'select_agent_decision',
+            payload: {
+                component: component.name,
+                source: component.originalProposal.source,
+                status: component.status,
+            },
+        })));
         const accepted = updated.components.filter((comp) => comp.status === 'accepted');
         const rejected = updated.components.filter((comp) => comp.status === 'rejected');
+        const unresolved = updated.components.filter((comp) => comp.status === 'needs-review');
         const failed = selectResults.filter((r) => r.failed);
         if (failed.length > 0) {
             process.stderr.write(c.red(`Failed (${failed.length}/${selectResults.length}):`) + '\n');
             for (const f of failed) {
-                process.stderr.write(`  ${c.red('✗')}  ${f.componentName}  ${c.dim(f.error ?? 'unknown error')}\n`);
+                process.stderr.write(`  ${c.red('✗')}  ${f.componentName}\n`);
             }
         }
-        // Write step to DB
         const stepDb = openPipelineDb();
-        const stepId = createStep(stepDb, sessionId, 'analyze select', { sessionId });
+        const stepId = createStep(stepDb, sessionId, 'analyze select', {
+            sessionId,
+        });
         try {
             const status = failed.length === selectResults.length ? 'failed' : 'complete';
             updateStep(stepDb, stepId, status, { sessionId });
@@ -203,6 +291,6 @@ export function registerAnalyzeSelectAgentCommand(program) {
         finally {
             stepDb.close();
         }
-        process.stderr.write(`Accepted: ${accepted.length}  Rejected: ${rejected.length}\n`);
+        process.stderr.write(`Accepted: ${accepted.length}  Rejected: ${rejected.length}  Needs review: ${unresolved.length}\n`);
     });
 }

package/dist/src/analyze/select-agent/context-builder.d.ts

@@ -0,0 +1,50 @@
+import type { RawComponentDefinition } from '../../types.js';
+export type SelectionContextSummary = {
+    boundaryRoot: string;
+    siblingFileCount: number;
+    resolverReferenceCount: number;
+    hasParentUsageSite: boolean;
+};
+export type SelectionImportSummary = {
+    source: string;
+    names: string[];
+    local: boolean;
+    resolvedPath?: string;
+};
+export type SelectionFileSummary = {
+    path: string;
+    exports: string[];
+    codeSnippet: string;
+};
+export type SelectionReference = {
+    path: string;
+    snippet: string;
+};
+export type SelectionContext = {
+    boundaryRoot: string;
+    componentFile: {
+        path: string;
+        code: string;
+    };
+    imports: SelectionImportSummary[];
+    exports: string[];
+    siblingFiles: SelectionFileSummary[];
+    resolverReferences: SelectionReference[];
+    parentUsageSite?: SelectionReference;
+};
+type IndexedFile = {
+    absolutePath: string;
+    relativePath: string;
+    directory: string;
+    text: string;
+};
+export type RepoContextIndex = {
+    root: string;
+    files: IndexedFile[];
+    byDirectory: Map<string, IndexedFile[]>;
+    filePaths: Set<string>;
+};
+export declare function buildRepoContextIndex(root: string, filePaths: string[]): Promise<RepoContextIndex | null>;
+export declare function buildSelectionContext(index: RepoContextIndex, component: RawComponentDefinition): SelectionContext | undefined;
+export declare function summarizeSelectionContext(context: SelectionContext | undefined): SelectionContextSummary | undefined;
+export {};

package/dist/src/analyze/select-agent/context-builder.js

@@ -0,0 +1,197 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+const SCANNED_FILE_EXTENSIONS = new Set(['.astro', '.js', '.jsx', '.ts', '.tsx', '.vue']);
+const IMPORT_PATTERN = /import\s+(?:type\s+)?(.+?)\s+from\s+['"]([^'"]+)['"]/g;
+const EXPORT_NAMED_PATTERN = /export\s+(?:const|function|class|type|interface|enum)\s+([A-Za-z0-9_]+)/g;
+const EXPORT_DEFAULT_PATTERN = /export\s+default\s+([A-Za-z0-9_]+)/g;
+const EXPORT_LIST_PATTERN = /export\s*\{([^}]+)\}/g;
+const RESOLVER_HINT_PATTERN = /(resolver|registry|componentmap|component-map|componentresolver|resolvecomponent)/i;
+const MAX_COMPONENT_SOURCE_CHARS = 8_000;
+const MAX_SIBLING_FILES = 5;
+const MAX_SIBLING_SNIPPET_CHARS = 1_200;
+const MAX_REFERENCE_SNIPPETS = 3;
+const MAX_REFERENCE_CHARS = 800;
+function truncateText(text, maxChars) {
+    if (text.length <= maxChars)
+        return text;
+    return text.slice(0, maxChars) + '\n/* truncated */';
+}
+function isWithinRoot(path, root) {
+    const relativePath = relative(root, path);
+    return relativePath !== '..' && !relativePath.startsWith(`..${sep}`) && !isAbsolute(relativePath);
+}
+function parseImportedNames(importClause) {
+    const names = [];
+    const parts = importClause.split(',').map((part) => part.trim());
+    for (const part of parts) {
+        if (!part)
+            continue;
+        if (part.startsWith('{') && part.endsWith('}')) {
+            for (const named of part
+                .slice(1, -1)
+                .split(',')
+                .map((item) => item.trim())
+                .filter(Boolean)) {
+                const [local] = named.split(/\s+as\s+/i);
+                if (local)
+                    names.push(local.trim());
+            }
+            continue;
+        }
+        const [local] = part.split(/\s+as\s+/i);
+        if (local)
+            names.push(local.trim());
+    }
+    return [...new Set(names)];
+}
+function resolveLocalImportPath(source, componentDirectory, root, filePaths) {
+    const basePath = resolve(componentDirectory, source);
+    const candidates = [
+        basePath,
+        ...[...SCANNED_FILE_EXTENSIONS].map((extension) => `${basePath}${extension}`),
+        ...[...SCANNED_FILE_EXTENSIONS].map((extension) => join(basePath, `index${extension}`)),
+    ];
+    for (const candidate of candidates) {
+        if (filePaths.has(candidate) && isWithinRoot(candidate, root)) {
+            return relative(root, candidate);
+        }
+    }
+    if (isWithinRoot(basePath, root)) {
+        return relative(root, basePath);
+    }
+    return undefined;
+}
+function parseImports(sourceText, componentDirectory, root, filePaths) {
+    const imports = [];
+    for (const match of sourceText.matchAll(IMPORT_PATTERN)) {
+        const importClause = match[1]?.trim() ?? '';
+        const source = match[2]?.trim() ?? '';
+        const local = source.startsWith('.');
+        const names = parseImportedNames(importClause);
+        const record = { source, names, local };
+        if (local) {
+            record.resolvedPath = resolveLocalImportPath(source, componentDirectory, root, filePaths);
+        }
+        imports.push(record);
+    }
+    return imports;
+}
+function parseExports(sourceText) {
+    const exports = new Set();
+    for (const match of sourceText.matchAll(EXPORT_NAMED_PATTERN)) {
+        if (match[1])
+            exports.add(match[1]);
+    }
+    for (const match of sourceText.matchAll(EXPORT_DEFAULT_PATTERN)) {
+        if (match[1])
+            exports.add(`default:${match[1]}`);
+    }
+    for (const match of sourceText.matchAll(EXPORT_LIST_PATTERN)) {
+        const items = match[1]
+            ?.split(',')
+            .map((item) => item.trim())
+            .filter(Boolean) ?? [];
+        for (const item of items)
+            exports.add(item);
+    }
+    return [...exports];
+}
+function extractSnippet(text, token, maxChars) {
+    const index = text.indexOf(token);
+    if (index === -1)
+        return truncateText(text, maxChars);
+    const start = Math.max(0, text.lastIndexOf('\n', Math.max(0, index - Math.floor(maxChars / 2))) + 1);
+    const endBoundary = text.indexOf('\n', index + Math.floor(maxChars / 2));
+    const end = endBoundary === -1 ? text.length : endBoundary;
+    return truncateText(text.slice(start, end).trim(), maxChars);
+}
+function summarizeSiblingFiles(root, files, currentFile) {
+    return files
+        .filter((file) => file.absolutePath !== currentFile)
+        .slice(0, MAX_SIBLING_FILES)
+        .map((file) => ({
+        path: relative(root, file.absolutePath),
+        exports: parseExports(file.text),
+        codeSnippet: truncateText(file.text, MAX_SIBLING_SNIPPET_CHARS),
+    }));
+}
+function findResolverReferences(root, files, componentName, currentFile) {
+    return files
+        .filter((file) => file.absolutePath !== currentFile)
+        .filter((file) => file.text.includes(componentName))
+        .filter((file) => RESOLVER_HINT_PATTERN.test(file.absolutePath) || RESOLVER_HINT_PATTERN.test(file.text))
+        .slice(0, MAX_REFERENCE_SNIPPETS)
+        .map((file) => ({
+        path: relative(root, file.absolutePath),
+        snippet: extractSnippet(file.text, componentName, MAX_REFERENCE_CHARS),
+    }));
+}
+function findParentUsageSite(root, files, componentName, currentFile) {
+    const usagePattern = new RegExp(`<${componentName}\\b|\\b${componentName}\\s*[),}]|\\b${componentName}\\s*:`);
+    const candidates = files.filter((file) => file.absolutePath !== currentFile &&
+        usagePattern.test(file.text) &&
+        !file.text.startsWith('// stub') &&
+        !RESOLVER_HINT_PATTERN.test(file.absolutePath) &&
+        !RESOLVER_HINT_PATTERN.test(file.text));
+    const match = candidates[0];
+    if (!match)
+        return undefined;
+    return {
+        path: relative(root, match.absolutePath),
+        snippet: extractSnippet(match.text, componentName, MAX_REFERENCE_CHARS),
+    };
+}
+export async function buildRepoContextIndex(root, filePaths) {
+    if (filePaths.length === 0)
+        return null;
+    const resolvedRoot = resolve(root);
+    const files = await Promise.all(filePaths.map(async (absolutePath) => ({
+        absolutePath,
+        relativePath: relative(resolvedRoot, absolutePath),
+        directory: dirname(absolutePath),
+        text: await readFile(absolutePath, 'utf8').catch(() => ''),
+    })));
+    const byDirectory = new Map();
+    for (const file of files) {
+        const bucket = byDirectory.get(file.directory) ?? [];
+        bucket.push(file);
+        byDirectory.set(file.directory, bucket);
+    }
+    return {
+        root: resolvedRoot,
+        files,
+        byDirectory,
+        filePaths: new Set(files.map((file) => file.absolutePath)),
+    };
+}
+export function buildSelectionContext(index, component) {
+    const absolutePath = isAbsolute(component.source) ? component.source : resolve(index.root, component.source);
+    if (!isWithinRoot(absolutePath, index.root))
+        return undefined;
+    const componentFile = index.files.find((file) => file.absolutePath === absolutePath);
+    if (!componentFile)
+        return undefined;
+    const siblings = index.byDirectory.get(componentFile.directory) ?? [];
+    return {
+        boundaryRoot: index.root,
+        componentFile: {
+            path: componentFile.relativePath,
+            code: truncateText(componentFile.text, MAX_COMPONENT_SOURCE_CHARS),
+        },
+        imports: parseImports(componentFile.text, componentFile.directory, index.root, index.filePaths),
+        exports: parseExports(componentFile.text),
+        siblingFiles: summarizeSiblingFiles(index.root, siblings, componentFile.absolutePath),
+        resolverReferences: findResolverReferences(index.root, index.files, component.name, componentFile.absolutePath),
+        parentUsageSite: findParentUsageSite(index.root, index.files, component.name, componentFile.absolutePath),
+    };
+}
+export function summarizeSelectionContext(context) {
+    if (!context)
+        return undefined;
+    return {
+        boundaryRoot: context.boundaryRoot,
+        siblingFileCount: context.siblingFiles.length,
+        resolverReferenceCount: context.resolverReferences.length,
+        hasParentUsageSite: Boolean(context.parentUsageSite),
+    };
+}

package/dist/src/session/db.d.ts

@@ -106,6 +106,8 @@ export declare function computeTokenInputHash(rawTokenContent: string): string;
 export declare function lookupCache(db: DatabaseSync, inputHash: string, entityType: 'component' | 'token_set', entityId: string): CacheEntry | null;
 export declare function lookupCacheByEntity(db: DatabaseSync, entityType: 'component' | 'token_set', entityId: string): CacheEntry | null;
 export declare function storeCache(db: DatabaseSync, inputHash: string, entityType: 'component' | 'token_set', entityId: string, sourceSessionId: string, humanEdited: boolean): void;
+export declare function storeScannedFiles(db: DatabaseSync, sessionId: string, filePaths: string[]): void;
+export declare function loadScannedFiles(db: DatabaseSync, sessionId: string): string[];
 export declare function markCacheHumanEdited(db: DatabaseSync, entityType: 'component' | 'token_set', entityId: string): void;
 export declare function copyComponentFromCache(db: DatabaseSync, sourceSessionId: string, targetSessionId: string, componentId: string): void;
 export declare function copyTokensFromCache(db: DatabaseSync, sourceSessionId: string, targetSessionId: string): void;

package/dist/src/session/db.js

@@ -127,6 +127,12 @@ CREATE TABLE IF NOT EXISTS generation_cache (
   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,
+  PRIMARY KEY (session_id, path)
+);
+
 CREATE INDEX IF NOT EXISTS idx_steps_session            ON steps(session_id);
 CREATE INDEX IF NOT EXISTS idx_steps_command            ON steps(session_id, command);
 CREATE INDEX IF NOT EXISTS idx_raw_components_session   ON raw_components(session_id);
@@ -136,6 +142,7 @@ 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);
 `;
 export function getPipelineDbPath() {
     if (process.env.EDS_PIPELINE_DB_PATH) {
@@ -1067,6 +1074,25 @@ export function storeCache(db, inputHash, entityType, entityId, sourceSessionId,
        human_edited = CASE WHEN generation_cache.human_edited = 1 THEN 1 ELSE excluded.human_edited END,
        updated_at = excluded.updated_at`).run(inputHash, entityType, entityId, sourceSessionId, humanEdited ? 1 : 0, now, now);
 }
+export function storeScannedFiles(db, sessionId, filePaths) {
+    db.exec('BEGIN');
+    try {
+        db.prepare('DELETE FROM scanned_files WHERE session_id = ?').run(sessionId);
+        const insert = db.prepare('INSERT INTO scanned_files (session_id, path) VALUES (?, ?)');
+        for (const path of filePaths) {
+            insert.run(sessionId, path);
+        }
+        db.exec('COMMIT');
+    }
+    catch (e) {
+        db.exec('ROLLBACK');
+        throw e;
+    }
+}
+export function loadScannedFiles(db, sessionId) {
+    const rows = db.prepare('SELECT path FROM scanned_files WHERE session_id = ? ORDER BY path').all(sessionId);
+    return rows.map((r) => r.path);
+}
 export function markCacheHumanEdited(db, entityType, entityId) {
     const now = new Date().toISOString();
     db.prepare(`UPDATE generation_cache SET human_edited = 1, updated_at = ? WHERE entity_type = ? AND entity_id = ?`).run(now, entityType, entityId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-cli",
-  "version": "2.7.3",
+  "version": "2.7.4-dev-build-595febb.0",
   "description": "Contentful Experiences design system import CLI",
   "license": "MIT",
   "type": "module",
@@ -36,7 +36,7 @@
     "react-dom": "^18.3.1",
     "ts-morph": "^27.0.2",
     "typescript": "^5.9.3",
-    "@contentful/experience-design-system-types": "2.7.3"
+    "@contentful/experience-design-system-types": "2.7.4-dev-build-595febb.0"
   },
   "devDependencies": {
     "@tsconfig/node24": "^24.0.3",

package/skills/select-components.md

@@ -20,14 +20,16 @@ The entity being defined — a **Component Type** — is the schema that tells C
 
 ---
 
-## The one rule: does it render visible UI?
+## The one rule: is this the author-facing UI component?
 
-**Accept** the component if it renders visible UI — regardless of whether it is an atom, molecule, or organism, and regardless of whether it has many or few configurable props. A footer icon with two props (`icon`, `label`) is just as valid as a parallax hero with fifteen props.
+**Accept** the component if it is the component that directly defines the author-facing UI surface — regardless of whether it is an atom, molecule, or organism, and regardless of whether it has many or few configurable props. A footer icon with two props (`icon`, `label`) is just as valid as a parallax hero with fifteen props.
+
+**Reject** the component if its primary purpose is framework or data-loading infrastructure rather than the author-facing UI surface:
 
-**Reject** the component only if its primary purpose produces zero visual output:
 - It is a React hook (name starts `use` or `Use`)
 - It is a pure context provider with no visual output
 - It is a Ninetailed/personalization platform wrapper (its job is routing to variants, not rendering content)
+- It is a data-fetch wrapper that loads data for a sibling renderer and then forwards that data into the sibling renderer
 - It is an analytics/event-tracking component (fires events, renders nothing)
 - It is a security or infrastructure utility (no UI at all)
 
@@ -37,29 +39,49 @@ The entity being defined — a **Component Type** — is the schema that tells C
 
 These are **not** valid reasons to reject a component:
 
-| Invalid reason | Why it is wrong |
-|---|---|
-| "Only atoms/low-level" | Atoms are first-class Component Types in Contentful Experience Orchestration |
-| "Tightly coupled to a parent component" | Contentful Experience Orchestration handles composition at the experience layer |
+| Invalid reason                                     | Why it is wrong                                                                                                           |
+| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| "Only atoms/low-level"                             | Atoms are first-class Component Types in Contentful Experience Orchestration                                              |
+| "Tightly coupled to a parent component"            | Contentful Experience Orchestration handles composition at the experience layer                                           |
 | "Has A/B testing or personalization-related props" | These props are classified as `state` or excluded in the generate step — their presence does not disqualify the component |
-| "Has no marketer-configurable props" | Marketers are not the only users; designers and developers configure components too |
-| "Domain-specific or feature-level" | Press releases, newsrooms, search — all valid content components |
-| "Server-side or SSR" | Server components that render visible UI are valid |
-| "Few configurable props" | One or two props is fine |
+| "Has no marketer-configurable props"               | Marketers are not the only users; designers and developers configure components too                                       |
+| "Domain-specific or feature-level"                 | Press releases, newsrooms, search — all valid content components                                                          |
+| "Server-side or SSR"                               | Server components that render visible UI are valid                                                                        |
+| "Few configurable props"                           | One or two props is fine                                                                                                  |
 
 ---
 
 ## Reject only these categories
 
-| Category | Why |
-|---|---|
-| **React hooks** | `useXxx` / `UseXxx` — functions, not renderable components. Zero visual output. |
-| **Pure context providers** | Wrap children to pass context but render no UI themselves |
-| **A/B testing or personalization wrappers** | Components whose *entire purpose* is routing users to content variants or tracking experiment participation — they render no UI of their own |
-| **Analytics and event tracking** | Components that only fire analytics events and render nothing visible |
-| **Security utilities** | Non-visual security primitives with no rendered output |
+| Category                                    | Why                                                                                                                                                                 |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **React hooks**                             | `useXxx` / `UseXxx` — functions, not renderable components. Zero visual output.                                                                                     |
+| **Pure context providers**                  | Wrap children to pass context but render no UI themselves                                                                                                           |
+| **A/B testing or personalization wrappers** | Components whose _entire purpose_ is routing users to content variants or tracking experiment participation — they render no UI of their own                        |
+| **Data-fetch wrappers**                     | Components whose job is to load or resolve data for a sibling renderer. Even if they eventually return visible UI, the sibling renderer is the real Component Type. |
+| **Analytics and event tracking**            | Components that only fire analytics events and render nothing visible                                                                                               |
+| **Security utilities**                      | Non-visual security primitives with no rendered output                                                                                                              |
+
+> **Variant routing rule**: Reject a component if its entire purpose is deciding _which_ content variant to show — that is framework infrastructure, not a Component Type. Do **not** reject a component merely because it _contains_ some A/B testing or personalization-related props — those props are handled as `state` in the generate step.
+
+> **Data-fetch wrapper rule**: Reject a component if it imports or calls a generated query hook, loads data, and then forwards that data into a sibling renderer. The sibling renderer is the Component Type; the data-loader wrapper is not.
+
+## Using `selectionContext`
+
+If the input includes `selectionContext`, treat it as the only repo-level context you may use. It is already bounded to the customer-provided project files and may include:
+
+- the component source file
+- sibling files in the same folder
+- import/export summaries
+- resolver or registry references
+- one likely parent usage site
 
-> **Variant routing rule**: Reject a component if its entire purpose is deciding *which* content variant to show — that is framework infrastructure, not a Component Type. Do **not** reject a component merely because it *contains* some A/B testing or personalization-related props — those props are handled as `state` in the generate step.
+Use that bounded context to distinguish the author-facing renderer from infrastructure wrappers. In particular:
+
+- If the component imports a sibling renderer and mainly forwards fetched data into it, reject the wrapper and prefer the sibling renderer.
+- If sibling files show a presentation-focused renderer with the real authoring props, that renderer is the Component Type.
+- Resolver or parent-usage references help show how the repo treats the component, but they do not override the renderer-vs-wrapper rule.
+- Do not assume access to any files outside `selectionContext`.
 
 ---
 
@@ -76,6 +98,7 @@ Emit one JSON object on a single line. Lines not starting with `{` are ignored b
 ```
 
 **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.
 - `reason` is a brief phrase documenting your decision.
@@ -136,6 +159,12 @@ Providers — React context provider with no visual output
 {"tool":"reject_component","name":"Providers","reason":"pure context provider — no visual output"}
 ```
 
+```
+HeroBannerGql — fetch wrapper that loads data and forwards it into HeroBanner
+It may eventually return visible UI, but the author-facing component is HeroBanner, not HeroBannerGql.
+{"tool":"reject_component","name":"HeroBannerGql","reason":"data-fetch wrapper — loads data for a sibling renderer rather than defining the author-facing UI surface"}
+```
+
 ```
 FooterIcon — atom: renders an icon with optional label in the footer
 {"tool":"select_component","name":"FooterIcon","reason":"UI atom — renders icon with configurable icon and label"}