@contentful/experience-design-system-cli 2.7.3-dev-build-a02165e.0 → 2.7.3-dev-build-2a7c81e.0

package/dist/package.json

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

package/dist/src/analyze/command.js

@@ -10,6 +10,7 @@ import { openPipelineDb, getOrCreateSession, createStep, updateStep, storeRawCom
 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,22 +129,43 @@ 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);

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,186 @@
+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;
+    if (GQL_FILENAME_PATTERN.test(component.source)) {
+        reviewReasons.push('data-wrapper:gql-filename');
+        wrapperScore += 1;
+    }
+    if (GENERATED_IMPORT_PATTERN.test(sourceText) && GENERATED_QUERY_HOOK_PATTERN.test(sourceText)) {
+        reviewReasons.push('data-wrapper:generated-query-hook');
+        wrapperScore += 3;
+    }
+    const siblingImports = collectSiblingRendererImports(sourceText);
+    if (siblingImports.length > 0) {
+        reviewReasons.push('data-wrapper:sibling-renderer-import');
+        wrapperScore += 2;
+    }
+    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;
+    }
+    const infraProps = infraPropNames(component);
+    if (infraProps.length > 0) {
+        reviewReasons.push('data-wrapper:infra-props');
+        wrapperScore += 2;
+    }
+    if (LOADING_NULL_GUARD_PATTERN.test(sourceText) || /return\s+null\b/.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/tui/components/TopBar.js

@@ -1,10 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { createRequire } from 'node:module';
 import { Box, Text } from 'ink';
-// createRequire is needed because this is an ESM package — require() doesn't
-// exist natively, but it's the simplest way to read a JSON file at runtime.
-const _require = createRequire(import.meta.url);
-const VERSION = _require('../../../../../package.json').version;
 export function TopBar({ subcommand, hints }) {
-    return (_jsxs(Box, { justifyContent: "space-between", children: [_jsx(Text, { bold: true, children: 'experience-design-system-cli  ' + subcommand }), _jsxs(Text, { dimColor: true, children: [hints.map((h) => `[${h.key}] ${h.label}`).join('  '), '  v' + VERSION] })] }));
+    return (_jsxs(Box, { justifyContent: "space-between", children: [_jsx(Text, { bold: true, children: 'experience-design-system-cli  ' + subcommand }), _jsx(Text, { dimColor: true, children: hints.map((h) => `[${h.key}] ${h.label}`).join('  ') })] }));
 }

package/dist/src/analyze/select/types.d.ts

@@ -1,4 +1,5 @@
 import type { RawComponentDefinition } from '../../types.js';
+import type { SelectionAudit } from '../select-agent/consensus.js';
 export type PreviewAnnotation = 'new' | 'changed' | 'removed' | 'breaking';
 export type ReviewComponentStatus = 'needs-review' | 'reviewed' | 'accepted' | 'rejected';
 export type ReviewComponentRecord = {
@@ -9,6 +10,7 @@ export type ReviewComponentRecord = {
     originalProposal: RawComponentDefinition;
     editedProposal: RawComponentDefinition;
     status: ReviewComponentStatus;
+    selectionAudit?: SelectionAudit;
 };
 export type ReviewComponentDetail = {
     id: string;
@@ -16,6 +18,7 @@ export type ReviewComponentDetail = {
     originalProposal: RawComponentDefinition;
     editedProposal: RawComponentDefinition;
     status: ReviewComponentStatus;
+    selectionAudit?: SelectionAudit;
 };
 export type ReviewComponentSummary = {
     id: string;

package/dist/src/analyze/select/types.js

@@ -17,6 +17,7 @@ export function createReviewSessionDetail(session) {
             originalProposal: component.originalProposal,
             editedProposal: component.editedProposal,
             status: component.status,
+            selectionAudit: component.selectionAudit,
         })),
     };
 }

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

@@ -1,12 +1,17 @@
 import { openPipelineDb, loadRawComponents, createStep, updateStep } from '../../session/db.js';
-import { getRefineArtifactsRoot, ensureRefineSession, getRefineSessionPaths, saveReviewState, } from '../select/persistence.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 { DEFAULT_REVIEW_VOTE_COUNT, summarizeSelectionVotes, } from './consensus.js';
+import { buildRepoContextIndex, buildSelectionContext, summarizeSelectionContext, } from './context-builder.js';
+import { 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;
+const REVIEW_VOTE_COUNT = Math.max(1, Number(process.env.EDS_SELECT_VOTE_COUNT ?? DEFAULT_REVIEW_VOTE_COUNT));
+const SINGLE_PASS_VOTE_COUNT = 1;
 function resolveSessionId(sessionFlag) {
     if (sessionFlag)
         return sessionFlag;
@@ -30,8 +35,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,57 +49,126 @@ 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 getSelectionVoteCount(component) {
+    if (component.needsReview === true) {
+        return REVIEW_VOTE_COUNT;
+    }
+    if (typeof component.extractionConfidence === 'number' && component.extractionConfidence <= 3) {
+        return REVIEW_VOTE_COUNT;
+    }
+    return SINGLE_PASS_VOTE_COUNT;
 }
-async function selectOneComponent(agent, model, component, index, total, verbose) {
+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, candidate, index, total, verbose) {
+    const { component, selectionContext } = candidate;
+    const voteCount = getSelectionVoteCount(component);
     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}]`);
-    let outputBuf = '';
-    const formatter = new OutputFormatter(verbose, (s) => {
-        outputBuf += s;
-    });
-    const result = await runAgent({
-        agent,
-        model,
-        prompt,
-        interactive: false,
-        timeoutMs: DEFAULT_TIMEOUT_MS,
-        onOutput: (chunk) => formatter.push(chunk),
-    });
-    formatter.flush();
-    process.stderr.write(`  ${pos}  ${c.bold(component.name)}\n${outputBuf}`);
-    if (result.timedOut) {
-        return { componentName: component.name, decision: null, failed: true, error: 'timed out' };
-    }
-    if (result.exitCode !== 0) {
-        return {
-            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`);
-    }
-    const call = calls.find((call) => call.name === component.name) ?? calls[0];
-    if (!call) {
-        return {
-            componentName: component.name,
-            decision: null,
-            failed: true,
-            error: 'agent produced no tool call for this component',
-        };
+    const votes = [];
+    const contextSummary = summarizeSelectionContext(selectionContext);
+    for (let attempt = 1; attempt <= voteCount; attempt++) {
+        let outputBuf = '';
+        const formatter = new OutputFormatter(verbose, (s) => {
+            outputBuf += s;
+        });
+        const result = await runAgent({
+            agent,
+            model,
+            prompt,
+            interactive: false,
+            timeoutMs: DEFAULT_TIMEOUT_MS,
+            onOutput: (chunk) => formatter.push(chunk),
+        });
+        formatter.flush();
+        if (verbose) {
+            process.stderr.write(`  ${pos}  ${c.bold(component.name)}  ${c.dim(`vote ${attempt}/${voteCount}`)}\n${outputBuf}`);
+        }
+        if (result.timedOut) {
+            votes.push({ attempt, decision: null, error: 'timed out' });
+            continue;
+        }
+        if (result.exitCode !== 0) {
+            votes.push({
+                attempt,
+                decision: null,
+                error: `agent exited with code ${result.exitCode}`,
+            });
+            continue;
+        }
+        const { calls, warnings } = parseSelectToolCallLines(result.stdout);
+        if (warnings.length > 0) {
+            for (const warning of warnings) {
+                process.stderr.write(`  ${c.yellow('⚠')}  ${component.name}: ${warning}\n`);
+            }
+        }
+        const call = calls.find((toolCall) => toolCall.name === component.name) ?? calls[0];
+        if (!call) {
+            votes.push({
+                attempt,
+                decision: null,
+                error: 'agent produced no tool call for this component',
+            });
+            continue;
+        }
+        votes.push({
+            attempt,
+            decision: call.tool === 'select_component' ? 'accepted' : 'rejected',
+            reason: call.reason,
+            confidence: call.confidence,
+        });
     }
-    const decision = call.tool === 'select_component' ? 'accepted' : 'rejected';
-    return { componentName: component.name, decision, reason: call.reason, failed: false };
+    const consensus = summarizeSelectionVotes(votes, contextSummary);
+    const finalColor = consensus.decision === 'accepted' ? c.green : consensus.decision === 'rejected' ? c.red : c.yellow;
+    const finalLabel = consensus.decision === 'accepted' ? 'accepted' : consensus.decision === 'rejected' ? 'rejected' : 'needs review';
+    const detail = consensus.audit.winningReason;
+    process.stderr.write(`  ${pos}  ${c.bold(component.name)}  ${finalColor(finalLabel)}${detail ? `  ${c.dim(detail)}` : ''}\n`);
+    return {
+        componentKey: componentKey(component),
+        componentName: component.name,
+        decision: consensus.decision,
+        audit: consensus.audit,
+        reason: consensus.audit.winningReason,
+        failed: consensus.failed,
+    };
 }
 async function selectAllComponents(agent, model, components, verbose) {
     const concurrency = Number(process.env.EDS_GENERATE_CONCURRENCY ?? DEFAULT_CONCURRENCY);
@@ -126,6 +204,7 @@ export function registerAnalyzeSelectAgentCommand(program) {
         }
         const agent = opts.agent;
         const sessionId = resolveSessionId(opts.session);
+        const selectionRoot = resolveProjectRoot(sessionId, opts.projectRoot);
         const db = openPipelineDb();
         let rawComponents;
         try {
@@ -139,8 +218,18 @@ export function registerAnalyzeSelectAgentCommand(program) {
             process.exit(1);
             return;
         }
+        let selectionCandidates = rawComponents.map((component) => ({ component }));
+        if (selectionRoot) {
+            const repoIndex = await buildRepoContextIndex(selectionRoot).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 +240,20 @@ export function registerAnalyzeSelectAgentCommand(program) {
             process.exit(0);
             return;
         }
-        const selectResults = await selectAllComponents(agent, opts.model, rawComponents, opts.verbose ?? false);
+        const selectResults = await selectAllComponents(agent, opts.model, selectionCandidates, opts.verbose ?? false);
         // Build decision map from results
         const decisions = new Map();
+        const audits = new Map();
         for (const r of selectResults) {
-            if (!r.failed && r.decision) {
-                decisions.set(r.componentName, r.decision);
-            }
+            decisions.set(r.componentKey, r.decision);
+            audits.set(r.componentKey, r.audit);
         }
         // 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 +266,42 @@ 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);
+                const selectionAudit = audits.get(key);
                 if (!decision)
                     return comp;
-                return { ...comp, status: decision };
+                const status = decision === 'needs-review' ? 'needs-review' : decision;
+                return { ...comp, status, selectionAudit };
             }),
         };
         await saveReviewState(paths.statePath, updated);
+        await Promise.all(updated.components
+            .filter((component) => component.selectionAudit)
+            .map((component) => appendReviewEvent(paths.eventsPath, {
+            type: 'select_agent_decision',
+            payload: {
+                component: component.name,
+                source: component.originalProposal.source,
+                status: component.status,
+                selectionAudit: component.selectionAudit,
+            },
+        })));
         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}  ${c.dim('all votes failed')}\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 +309,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/consensus.d.ts

@@ -0,0 +1,32 @@
+export type SelectionDecision = 'accepted' | 'rejected' | 'needs-review';
+export type SelectionVote = {
+    attempt: number;
+    decision: 'accepted' | 'rejected' | null;
+    reason?: string;
+    confidence?: number;
+    error?: string;
+};
+export type SelectionContextSummary = {
+    boundaryRoot: string;
+    siblingFileCount: number;
+    resolverReferenceCount: number;
+    hasParentUsageSite: boolean;
+};
+export type SelectionAudit = {
+    strategy: 'single-pass' | 'multi-vote-consensus';
+    voteCount: number;
+    acceptedVotes: number;
+    rejectedVotes: number;
+    failedVotes: number;
+    finalDecision: SelectionDecision;
+    winningReason?: string;
+    votes: SelectionVote[];
+    contextSummary?: SelectionContextSummary;
+};
+export type ConsensusResult = {
+    decision: SelectionDecision;
+    audit: SelectionAudit;
+    failed: boolean;
+};
+export declare const DEFAULT_REVIEW_VOTE_COUNT = 5;
+export declare function summarizeSelectionVotes(votes: SelectionVote[], contextSummary?: SelectionContextSummary): ConsensusResult;

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

@@ -0,0 +1,60 @@
+export const DEFAULT_REVIEW_VOTE_COUNT = 5;
+function preferredReason(votes, decision) {
+    const candidates = votes.filter((vote) => vote.decision === decision && vote.reason);
+    if (candidates.length === 0)
+        return undefined;
+    const ranked = new Map();
+    for (const vote of candidates) {
+        const reason = vote.reason;
+        const entry = ranked.get(reason) ?? { count: 0, bestConfidence: 0 };
+        entry.count += 1;
+        entry.bestConfidence = Math.max(entry.bestConfidence, vote.confidence ?? 0);
+        ranked.set(reason, entry);
+    }
+    return [...ranked.entries()].sort((a, b) => {
+        if (b[1].count !== a[1].count)
+            return b[1].count - a[1].count;
+        return b[1].bestConfidence - a[1].bestConfidence;
+    })[0]?.[0];
+}
+function decideFromVotes(votes, acceptedVotes, rejectedVotes) {
+    if (votes.length === 1) {
+        if (acceptedVotes === 1)
+            return 'accepted';
+        if (rejectedVotes === 1)
+            return 'rejected';
+        return 'needs-review';
+    }
+    // A 3-2 split is still too unstable for auto-selection.
+    if (votes.length >= DEFAULT_REVIEW_VOTE_COUNT &&
+        ((acceptedVotes === 3 && rejectedVotes === 2) || (acceptedVotes === 2 && rejectedVotes === 3))) {
+        return 'needs-review';
+    }
+    if (acceptedVotes > rejectedVotes)
+        return 'accepted';
+    if (rejectedVotes > acceptedVotes)
+        return 'rejected';
+    return 'needs-review';
+}
+export function summarizeSelectionVotes(votes, contextSummary) {
+    const acceptedVotes = votes.filter((vote) => vote.decision === 'accepted').length;
+    const rejectedVotes = votes.filter((vote) => vote.decision === 'rejected').length;
+    const failedVotes = votes.filter((vote) => vote.decision === null).length;
+    const decision = decideFromVotes(votes, acceptedVotes, rejectedVotes);
+    const winningReason = decision === 'accepted' || decision === 'rejected' ? preferredReason(votes, decision) : undefined;
+    return {
+        decision,
+        failed: failedVotes === votes.length,
+        audit: {
+            strategy: votes.length === 1 ? 'single-pass' : 'multi-vote-consensus',
+            voteCount: votes.length,
+            acceptedVotes,
+            rejectedVotes,
+            failedVotes,
+            finalDecision: decision,
+            winningReason,
+            votes,
+            contextSummary,
+        },
+    };
+}

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

@@ -0,0 +1,45 @@
+import type { RawComponentDefinition } from '../../types.js';
+import type { SelectionContextSummary } from './consensus.js';
+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): 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,253 @@
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+const SCANNED_FILE_EXTENSIONS = new Set(['.astro', '.js', '.jsx', '.ts', '.tsx', '.vue']);
+const IGNORED_DIRECTORY_NAMES = new Set([
+    '.git',
+    '.next',
+    '.nuxt',
+    'build',
+    'coverage',
+    'demo',
+    'demos',
+    'dist',
+    'example',
+    'examples',
+    'node_modules',
+    'out',
+    'storybook-static',
+]);
+const IGNORED_FILE_SUFFIXES = new Set([
+    '.stories.ts',
+    '.stories.tsx',
+    '.stories.js',
+    '.stories.jsx',
+    '.story.ts',
+    '.story.tsx',
+    '.story.js',
+    '.story.jsx',
+    '.spec.ts',
+    '.spec.tsx',
+    '.test.ts',
+    '.test.tsx',
+]);
+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);
+}
+async function collectSourceFiles(directory) {
+    const files = [];
+    async function visit(currentDirectory) {
+        const entries = await readdir(currentDirectory, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = join(currentDirectory, entry.name);
+            if (entry.isDirectory()) {
+                if (!IGNORED_DIRECTORY_NAMES.has(entry.name)) {
+                    await visit(fullPath);
+                }
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            const extension = extname(entry.name);
+            if (!SCANNED_FILE_EXTENSIONS.has(extension) || entry.name.endsWith('.d.ts'))
+                continue;
+            if ([...IGNORED_FILE_SUFFIXES].some((suffix) => entry.name.endsWith(suffix)))
+                continue;
+            files.push(fullPath);
+        }
+    }
+    await visit(directory);
+    return files.sort();
+}
+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) {
+    const resolvedRoot = resolve(root);
+    const rootStats = await stat(resolvedRoot).catch(() => null);
+    if (!rootStats?.isDirectory())
+        return null;
+    const filePaths = await collectSourceFiles(resolvedRoot);
+    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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-cli",
-  "version": "2.7.3-dev-build-a02165e.0",
+  "version": "2.7.3-dev-build-2a7c81e.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-dev-build-a02165e.0"
+    "@contentful/experience-design-system-types": "2.7.3-dev-build-2a7c81e.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"}