@ikas/code-components-mcp 2.1.0 → 2.2.0

package/dist/index.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
 import * as fs from "fs";
 import * as path from "path";
 import { fileURLToPath } from "url";
+import { z } from "zod";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 // --- Load data ---
@@ -15,6 +15,59 @@ function loadJsonFile(relativePath) {
     }
     return JSON.parse(fs.readFileSync(filePath, "utf-8"));
 }
+// Resolve theme.json from either raw string or absolute file path.
+// Exactly one of the two must be provided.
+function resolveThemeJson(themeJson, themeJsonPath) {
+    const hasInline = typeof themeJson === "string" && themeJson.length > 0;
+    const hasPath = typeof themeJsonPath === "string" && themeJsonPath.length > 0;
+    if (hasInline === hasPath) {
+        throw new Error("Provide exactly one of `theme_json` (raw JSON string) or `theme_json_path` (absolute path to theme.json).");
+    }
+    let raw;
+    if (hasPath) {
+        if (!path.isAbsolute(themeJsonPath)) {
+            throw new Error(`theme_json_path must be absolute: ${themeJsonPath}`);
+        }
+        if (!fs.existsSync(themeJsonPath)) {
+            throw new Error(`theme_json_path not found: ${themeJsonPath}`);
+        }
+        try {
+            raw = fs.readFileSync(themeJsonPath, "utf-8");
+        }
+        catch (e) {
+            throw new Error(`Failed to read theme_json_path "${themeJsonPath}": ${e.message}`);
+        }
+    }
+    else {
+        raw = themeJson;
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`Invalid JSON in theme.json: ${e.message}`);
+    }
+}
+// Atomic file write: temp file in same dir, then rename. Same-fs rename is atomic on POSIX.
+function writeFileAtomic(targetPath, content) {
+    const dir = path.dirname(targetPath);
+    const base = path.basename(targetPath);
+    const tmp = path.join(dir, `.${base}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 8)}`);
+    try {
+        fs.writeFileSync(tmp, content, "utf-8");
+        fs.renameSync(tmp, targetPath);
+    }
+    catch (e) {
+        try {
+            if (fs.existsSync(tmp))
+                fs.unlinkSync(tmp);
+        }
+        catch {
+            // ignore cleanup failure
+        }
+        throw e;
+    }
+}
 // Try multiple paths for storefront data (generated output or local data dir)
 function loadStorefrontData() {
     const paths = [
@@ -50,7 +103,15 @@ function normalizeName(value) {
 const storefrontData = loadStorefrontData();
 const frameworkData = loadJsonFile("../data/framework.json");
 const typesData = loadStorefrontTypes();
+let migrationData = null;
+try {
+    migrationData = loadJsonFile("../data/migration.json");
+}
+catch {
+    migrationData = null;
+}
 const SECTION_TEMPLATES_DIR = path.resolve(__dirname, "../data/section-templates");
+const MIGRATION_EXAMPLES_DIR = path.resolve(__dirname, "../data/migration-examples");
 function listSectionTemplateNames() {
     try {
         return fs
@@ -159,6 +220,1216 @@ function loadSectionSubtreeItem(section, subtree, name) {
     return { files };
 }
 const sectionTemplateNames = listSectionTemplateNames();
+// --- Migration example helpers ---
+function listMigrationExampleNames() {
+    try {
+        return fs
+            .readdirSync(MIGRATION_EXAMPLES_DIR, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+function loadMigrationExample(name) {
+    const root = path.join(MIGRATION_EXAMPLES_DIR, name);
+    if (!fs.existsSync(root))
+        return null;
+    const metaPath = path.join(root, "_meta.json");
+    if (!fs.existsSync(metaPath))
+        return null;
+    const meta = JSON.parse(fs.readFileSync(metaPath, "utf-8"));
+    const files = {};
+    for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+        if (entry.name === "_meta.json" || entry.isDirectory())
+            continue;
+        files[entry.name] = fs.readFileSync(path.join(root, entry.name), "utf-8");
+    }
+    return { title: meta.title, description: meta.description, files };
+}
+const migrationExampleNames = listMigrationExampleNames();
+function searchMigrationTopics(query) {
+    if (!migrationData)
+        return [];
+    return Object.entries(migrationData.topics)
+        .map(([key, topic]) => {
+        const titleScore = matchScore(topic.title, query) * 3;
+        const descScore = matchScore(topic.description, query) * 2;
+        const contentScore = matchScore(topic.content, query);
+        const tagScore = topic.tags.some((t) => matchScore(t, query) > 0) ? 5 : 0;
+        return { key, topic, score: titleScore + descScore + contentScore + tagScore };
+    })
+        .filter((item) => item.score > 0)
+        .sort((a, b) => b.score - a.score);
+}
+function analyzeOldTheme(themeJson) {
+    const parts = [];
+    const components = themeJson.components || [];
+    const customData = themeJson.customData || [];
+    const groups = themeJson.groups || [];
+    const settings = themeJson.settings;
+    // Build customData lookup
+    const customDataMap = new Map();
+    for (const cd of customData) {
+        if (cd.id)
+            customDataMap.set(cd.id, cd);
+    }
+    // Statistics
+    let totalProps = 0;
+    let customProps = 0;
+    let sliderProps = 0;
+    let productDetailProps = 0;
+    let estimatedChildComponents = 0;
+    parts.push(`# Old Theme Analysis\n`);
+    parts.push(`> **CRITICAL:** The old system (\`@ikas/storefront\`) and the new code-component system (\`@ikas/bp-storefront\`) are **entirely different packages**. Even when type names look the same (e.g., \`IkasImage\`, \`IkasProduct\`), they are different types with different properties. The prop type systems are also completely separate — old theme.json prop types and new ikas.config.json prop types have different semantics even when names match. **Never assume old-system knowledge applies to the new system.** Always use \`get_type_definition\`, \`get_model_guide\`, and \`get_function_doc\` to look up the correct new-system APIs.\n`);
+    parts.push(`## Summary Statistics\n`);
+    parts.push(`- **Components:** ${components.length}`);
+    parts.push(`- **Custom Data Definitions:** ${customData.filter(cd => cd.isRoot).length}`);
+    parts.push(`- **Prop Groups:** ${groups.length}`);
+    // Component analysis
+    parts.push(`\n## Components (${components.length})\n`);
+    for (const comp of components) {
+        const props = comp.props || [];
+        totalProps += props.length;
+        const propTypeCounts = {};
+        const customPropDetails = [];
+        const sliderPropDetails = [];
+        for (const prop of props) {
+            const pType = prop.type || "UNKNOWN";
+            propTypeCounts[pType] = (propTypeCounts[pType] || 0) + 1;
+            if (pType === "CUSTOM" && prop.customDataId) {
+                customProps++;
+                const cd = customDataMap.get(prop.customDataId);
+                if (cd) {
+                    const cdType = cd.type || "UNKNOWN";
+                    customPropDetails.push(`  - \`${prop.name}\` → ${cd.name || "unnamed"} (${cdType})`);
+                    if (cdType === "DYNAMIC_LIST" || cdType === "STATIC_LIST") {
+                        estimatedChildComponents++;
+                    }
+                }
+                else {
+                    customPropDetails.push(`  - \`${prop.name}\` → [unresolved customDataId]`);
+                }
+            }
+            if (pType === "SLIDER") {
+                sliderProps++;
+                const sd = prop.sliderData;
+                sliderPropDetails.push(`  - \`${prop.name}\` (${sd?.min ?? "?"}–${sd?.max ?? "?"}, step ${sd?.interval ?? "?"})`);
+            }
+            if (pType === "PRODUCT_DETAIL") {
+                productDetailProps++;
+            }
+        }
+        const typesSummary = Object.entries(propTypeCounts)
+            .map(([t, c]) => `${t}×${c}`)
+            .join(", ");
+        const headerFooter = comp.isHeader ? " [HEADER]" : comp.isFooter ? " [FOOTER]" : "";
+        parts.push(`### ${comp.displayName || comp.dir || comp.id}${headerFooter}`);
+        parts.push(`- **Dir:** \`${comp.dir || "?"}\` | **Props:** ${props.length} (${typesSummary})`);
+        parts.push(`- **Recommended new type:** section`);
+        if (customPropDetails.length > 0) {
+            parts.push(`- **CUSTOM props** (→ COMPONENT_LIST):`);
+            parts.push(customPropDetails.join("\n"));
+        }
+        if (sliderPropDetails.length > 0) {
+            parts.push(`- **SLIDER props** (→ NUMBER):`);
+            parts.push(sliderPropDetails.join("\n"));
+        }
+        parts.push("");
+    }
+    // Custom data analysis
+    const rootCustomData = customData.filter(cd => cd.isRoot);
+    if (rootCustomData.length > 0) {
+        parts.push(`\n## Custom Data Definitions (${rootCustomData.length})\n`);
+        for (const cd of rootCustomData) {
+            parts.push(`### ${cd.name || cd.typescriptName || cd.id}`);
+            parts.push(`- **Type:** ${cd.type}`);
+            if (cd.nestedData && cd.nestedData.length > 0) {
+                const describeNested = (items, indent) => {
+                    const lines = [];
+                    for (const item of items) {
+                        const key = item.key ? `\`${item.key}\`` : item.typescriptName || item.name || "unnamed";
+                        lines.push(`${indent}- ${key}: ${item.type}${item.isRequired ? " (required)" : ""}`);
+                        if (item.nestedData && item.nestedData.length > 0) {
+                            lines.push(...describeNested(item.nestedData, indent + "  "));
+                        }
+                    }
+                    return lines;
+                };
+                parts.push("- **Structure:**");
+                parts.push(...describeNested(cd.nestedData, "  "));
+            }
+            if (cd.enumOptions && cd.enumOptions.length > 0) {
+                parts.push(`- **Enum options:** ${cd.enumOptions.map(o => `"${o.value}"`).join(", ")}`);
+            }
+            // Find which components reference this customData
+            const referencingComponents = [];
+            for (const comp of components) {
+                for (const prop of comp.props || []) {
+                    if (prop.type === "CUSTOM" && prop.customDataId === cd.id) {
+                        referencingComponents.push(`${comp.displayName || comp.dir || comp.id}.${prop.name}`);
+                    }
+                }
+            }
+            if (referencingComponents.length > 0) {
+                parts.push(`- **Referenced by:** ${referencingComponents.join(", ")}`);
+            }
+            parts.push("");
+        }
+    }
+    // Settings
+    if (settings) {
+        parts.push(`\n## Settings\n`);
+        if (settings.colors && settings.colors.length > 0) {
+            parts.push(`### Colors (${settings.colors.length})`);
+            for (const c of settings.colors) {
+                parts.push(`- \`${c.key}\`: ${c.color} (${c.displayName})`);
+            }
+            parts.push("");
+        }
+        if (settings.fontFamily) {
+            parts.push(`### Font: ${settings.fontFamily.name} (weights: ${settings.fontFamily.variants?.join(", ")})`);
+            parts.push("");
+        }
+    }
+    // Groups
+    if (groups.length > 0) {
+        parts.push(`\n## Prop Groups (${groups.length})\n`);
+        for (const g of groups) {
+            parts.push(`- \`${g.id}\`: ${g.name}`);
+        }
+        parts.push("");
+    }
+    // Final statistics
+    parts.push(`\n## Migration Statistics\n`);
+    parts.push(`- **Total props across all components:** ${totalProps}`);
+    parts.push(`- **CUSTOM props (need conversion):** ${customProps}`);
+    parts.push(`- **SLIDER props (→ NUMBER):** ${sliderProps}`);
+    parts.push(`- **PRODUCT_DETAIL props (→ PRODUCT):** ${productDetailProps}`);
+    parts.push(`- **Estimated child components needed:** ${estimatedChildComponents}`);
+    parts.push(`- **Total components in new system:** ~${components.length + estimatedChildComponents} (${components.length} sections + ${estimatedChildComponents} children)`);
+    parts.push(`\n## Recommended Workflow\n`);
+    const useIterative = components.length > 5;
+    if (useIterative) {
+        parts.push(`**This theme has ${components.length} sections — USE THE ITERATIVE WORKFLOW.** A single session cannot migrate this entire theme.\n`);
+        parts.push(`1. Call \`plan_migration(theme_json, old_source_dir)\` to generate MIGRATION.md (this is your resumable plan).`);
+        parts.push(`2. Save the output to \`<new-project-root>/MIGRATION.md\`.`);
+        parts.push(`3. Execute the Foundation checklist (global.css, enums, shared sub-components) in MIGRATION.md.`);
+        parts.push(`4. For each section: call \`get_section_migration_plan(theme_json, section_name)\`, implement it, and mark \`[x]\` in MIGRATION.md.`);
+        parts.push(`5. In any new session, **read MIGRATION.md first** and resume from the first \`[ ]\` item.\n`);
+        parts.push(`Read \`get_migration_guide("iterative-workflow")\` for the full protocol.`);
+    }
+    else {
+        parts.push(`This theme is small enough (${components.length} sections) for a one-pass migration.\n`);
+        parts.push(`1. Call \`get_migration_guide("migration-overview")\` for the full workflow`);
+        parts.push(`2. Call \`get_migration_guide("prop-type-mapping")\` for prop conversion details`);
+        parts.push(`3. Call \`get_migration_guide("custom-data-conversion")\` for CUSTOM → COMPONENT_LIST patterns`);
+        parts.push(`4. Call \`get_migration_guide("library-replacements")\` for replacing external libraries`);
+    }
+    parts.push(`\n## Other Key Guides\n`);
+    parts.push(`- \`get_migration_guide("component-renderer-limitations")\` — critical constraints when using COMPONENT_LIST (parent cannot read child props)`);
+    parts.push(`- \`get_migration_guide("prop-runtime-shapes")\` — exact runtime shape for each prop type (.data vs .links, etc.)`);
+    parts.push(`- \`get_migration_guide("link-prop-decision-guide")\` — when to use LINK vs LIST_OF_LINK vs COMPONENT_LIST`);
+    parts.push(`- \`get_framework_guide("common-pitfalls")\` — general gotchas (observer rules, .data access)`);
+    parts.push(`- \`get_framework_guide("component-renderer-patterns")\` — full IkasComponentRenderer usage`);
+    parts.push(`- \`get_model_guide("<TypeName>")\` — store type definitions (IkasCart, IkasProduct, etc.)`);
+    return parts.join("\n");
+}
+function scanSharedSubcomponents(sourceDir) {
+    if (!fs.existsSync(sourceDir))
+        return [];
+    const tsxFiles = [];
+    const walk = (dir) => {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (entry.isDirectory()) {
+                if (entry.name === "node_modules" || entry.name === "__generated__" || entry.name.startsWith("."))
+                    continue;
+                walk(path.join(dir, entry.name));
+            }
+            else if (entry.name.endsWith(".tsx") || entry.name.endsWith(".ts")) {
+                const componentDir = path.basename(path.dirname(path.join(dir, entry.name)));
+                tsxFiles.push({ componentDir, filePath: path.join(dir, entry.name) });
+            }
+        }
+    };
+    try {
+        walk(sourceDir);
+    }
+    catch {
+        return [];
+    }
+    // Collect imports: map from imported path/name → { usingComponents: Set, rawImportPath: string }
+    const importUsage = new Map();
+    const importRegex = /import\s+(?:{[^}]+}|\w+(?:\s*,\s*{[^}]+})?)\s+from\s+['"]([^'"]+)['"]/g;
+    for (const { componentDir, filePath } of tsxFiles) {
+        let content;
+        try {
+            content = fs.readFileSync(filePath, "utf-8");
+        }
+        catch {
+            continue;
+        }
+        const seenInFile = new Set();
+        let match;
+        while ((match = importRegex.exec(content)) !== null) {
+            const importPath = match[1];
+            // Only count relative imports (shared internal components, not npm packages)
+            if (!importPath.startsWith("."))
+                continue;
+            // Skip imports of generated types, utils, hooks
+            if (importPath.includes("__generated__") || importPath.includes("/utils") || importPath.includes("/hooks"))
+                continue;
+            // Extract base name from path
+            const pathSegments = importPath.split("/").filter(s => s && s !== "." && s !== "..");
+            if (pathSegments.length === 0)
+                continue;
+            const lastSegment = pathSegments[pathSegments.length - 1];
+            if (!lastSegment || !/^[A-Z]/.test(lastSegment))
+                continue; // PascalCase only (component-like)
+            const key = lastSegment;
+            if (seenInFile.has(key))
+                continue;
+            seenInFile.add(key);
+            if (!importUsage.has(key)) {
+                importUsage.set(key, { usingComponents: new Set(), rawImportPath: importPath });
+            }
+            importUsage.get(key).usingComponents.add(componentDir);
+        }
+    }
+    // Filter to candidates used by 3+ distinct components
+    const shared = [];
+    for (const [name, { usingComponents, rawImportPath }] of importUsage) {
+        // Don't flag the component itself (e.g., Navbar imports from ../Navbar/something)
+        const users = [...usingComponents].filter(c => c !== name);
+        if (users.length >= 3) {
+            shared.push({ name, usedBy: users.sort(), importPaths: [rawImportPath] });
+        }
+    }
+    return shared.sort((a, b) => b.usedBy.length - a.usedBy.length);
+}
+// --- Migration plan helpers ---
+function toKebabCase(s) {
+    return s
+        .replace(/([a-z])([A-Z])/g, "$1-$2")
+        .replace(/[\s_]+/g, "-")
+        .toLowerCase()
+        .replace(/[^a-z0-9-]/g, "");
+}
+function classifyComplexity(comp, customDataMap) {
+    const props = comp.props || [];
+    const customCount = props.filter(p => p.type === "CUSTOM").length;
+    if (customCount === 0 && props.length < 10)
+        return "simple";
+    // Check for deeply nested CUSTOM (customData referencing another customData)
+    let hasDeepNesting = false;
+    for (const p of props) {
+        if (p.type === "CUSTOM" && p.customDataId) {
+            const cd = customDataMap.get(p.customDataId);
+            if (cd?.nestedData) {
+                const hasNested = (items) => {
+                    for (const item of items) {
+                        if (item.type === "DYNAMIC_LIST" || item.type === "STATIC_LIST" || item.customDataId)
+                            return true;
+                        if (item.nestedData && hasNested(item.nestedData))
+                            return true;
+                    }
+                    return false;
+                };
+                if (hasNested(cd.nestedData)) {
+                    hasDeepNesting = true;
+                    break;
+                }
+            }
+        }
+    }
+    if (hasDeepNesting || props.length > 20 || customCount > 3)
+        return "complex";
+    return "medium";
+}
+function generateMigrationPlan(theme, projectName, oldSourceDir) {
+    const components = theme.components || [];
+    const customData = theme.customData || [];
+    const settings = theme.settings;
+    const customDataMap = new Map();
+    for (const cd of customData) {
+        if (cd.id)
+            customDataMap.set(cd.id, cd);
+    }
+    const sharedSubs = oldSourceDir ? scanSharedSubcomponents(oldSourceDir) : [];
+    const parts = [];
+    parts.push(`# Theme Migration Plan — \`${projectName}\``);
+    parts.push("");
+    parts.push(`**Generated:** ${new Date().toISOString().slice(0, 10)}`);
+    parts.push(`**Source:** ${components.length} old components, ${customData.filter(cd => cd.isRoot).length} custom data types, ${(theme.pages || []).length} pages`);
+    parts.push("");
+    parts.push(`> ## READ THIS FIRST`);
+    parts.push(`>`);
+    parts.push(`> This file is your responsibility from here. The MCP wrote this initial scaffold **once**. You own all updates — no MCP tool will modify this file again.`);
+    parts.push(`>`);
+    parts.push(`> 1. **Tick checkboxes** as you finish work. Use \`[~]\` for in-progress and \`[x]\` for done. Edit the file directly with your file-editing tools.`);
+    parts.push(`> 2. **theme.json is incomplete.** Atomic components (Button, Input, Card, icons, etc.) often live only in \`src/\` and are NOT referenced from theme.json. Before you start section migration, scan the old source directory and ADD entries to this file for anything the initial scan missed — list them under \`## Source Code Analysis\` and add shared ones to \`### Shared Sub-Components\`.`);
+    parts.push(`> 3. **Custom data types are NOT pre-converted.** For each customData entry used by a section, decide enum-vs-component when you migrate that section. Log every decision in \`## Custom Data Decisions\` with reasoning. See \`get_migration_guide("custom-data-conversion")\` for the heuristic.`);
+    parts.push(`> 4. **Preserve feature parity. Do NOT silently simplify or drop features.** If an old prop has richer fields than a new built-in prop type can carry (e.g. a navigation link with a per-link image), the answer is to build a child component — never to flatten and "add it later." Later doesn't come. If the user explicitly wants a feature removed, log that as an explicit decision in \`## Notes\`; otherwise migrate to functional parity.`);
+    parts.push(`> 5. **Per-section work:** call \`get_section_migration_plan({theme_json_path, section_name, project_name: "${projectName}"})\` for each section. The MCP returns concrete CLI commands and flags any customData-referencing props with a "Decide: enum or component?" callout.`);
+    parts.push(`> 6. **If you discover new shared sub-components mid-migration**, add them under \`### Shared Sub-Components\` and any notes under \`## Notes\`.`);
+    parts.push(`>`);
+    parts.push(`> Status legend: \`[ ]\` not started · \`[~]\` in progress · \`[x]\` complete.`);
+    parts.push("");
+    parts.push(`## Foundation`);
+    parts.push("");
+    // CSS variables
+    if (settings?.colors && settings.colors.length > 0) {
+        parts.push(`### Global CSS Variables (→ \`src/global.css\`)`);
+        parts.push("");
+        for (const c of settings.colors) {
+            parts.push(`- [ ] \`${c.key}: ${c.color};\` — ${c.displayName || "color"}`);
+        }
+        parts.push("");
+    }
+    // Fonts
+    if (settings?.fontFamily?.name) {
+        parts.push(`### Fonts (→ \`src/global.css\`)`);
+        parts.push("");
+        parts.push(`- [ ] ${settings.fontFamily.name} (weights: ${settings.fontFamily.variants?.join(", ") || "default"})`);
+        parts.push("");
+    }
+    // (Custom Enums foundation subsection intentionally removed — see ## Custom Data Types below.
+    // Old customData entries are NOT pre-migrated as enums; each is a per-section decision.
+    // See get_migration_guide("custom-data-conversion") for the enum-vs-component heuristic.)
+    // Shared sub-components
+    if (sharedSubs.length > 0) {
+        parts.push(`### Shared Sub-Components (→ \`src/sub-components/\`)`);
+        parts.push("");
+        parts.push(`These are reused across 3+ old sections. Build them BEFORE migrating sections. They are NOT registered in \`ikas.config.json\` — they live in \`src/sub-components/<Name>/{index.tsx,styles.css}\` and are imported by section components.`);
+        parts.push("");
+        for (const sub of sharedSubs) {
+            parts.push(`- [ ] \`${sub.name}\` — used by: ${sub.usedBy.slice(0, 8).join(", ")}${sub.usedBy.length > 8 ? `, +${sub.usedBy.length - 8} more` : ""}`);
+        }
+        parts.push("");
+    }
+    else if (oldSourceDir) {
+        parts.push(`### Shared Sub-Components`);
+        parts.push("");
+        parts.push(`No shared sub-components detected (no relative imports reused across 3+ old component files).`);
+        parts.push("");
+    }
+    else {
+        parts.push(`### Shared Sub-Components`);
+        parts.push("");
+        parts.push(`_Old source directory not provided — shared sub-components cannot be detected automatically. If you have access to the old source, call \`plan_migration\` again with \`old_source_dir\` to populate this section._`);
+        parts.push("");
+    }
+    parts.push(`> **This scan is partial.** \`scanSharedSubcomponents\` only detects relative imports used by **3 or more** old components. Atomic components used by fewer sections (often Button/Input/Card/icon primitives) will be missed. Scan \`src/\` yourself and add any others under \`## Source Code Analysis\` below.`);
+    parts.push("");
+    // Custom Data Types — deferred decisions (reference list, not checkboxes)
+    const rootCustomData = customData.filter((cd) => cd.isRoot);
+    if (rootCustomData.length > 0) {
+        // Build a usage map: which sections reference each customData type
+        const usageByCustomDataId = new Map();
+        for (const comp of components) {
+            const sectionName = comp.displayName || comp.dir || comp.id || "?";
+            for (const p of comp.props || []) {
+                if (p.type === "CUSTOM" && p.customDataId) {
+                    const list = usageByCustomDataId.get(p.customDataId) || [];
+                    if (!list.includes(sectionName))
+                        list.push(sectionName);
+                    usageByCustomDataId.set(p.customDataId, list);
+                }
+            }
+        }
+        parts.push(`### Custom Data Types — decide during section migration`);
+        parts.push("");
+        parts.push(`Each entry below is an OLD \`theme.customData[]\` type. Do **not** pre-migrate these as enums. When you migrate the section that uses one, decide:`);
+        parts.push(`- **Flat scalar set** (e.g. \`"left" | "right" | "center"\`) → new-system **enum prop** via \`config add-enum\`.`);
+        parts.push(`- **Structured record** (e.g. \`{image, link, title}\`, repeated in a list) → new-system **component** via \`config add-component\` + COMPONENT_LIST wiring on the parent.`);
+        parts.push("");
+        parts.push(`Log every decision in \`## Custom Data Decisions\` below. See \`get_migration_guide("custom-data-conversion")\` for the full heuristic and worked examples (Position, Slide, MenuItem).`);
+        parts.push("");
+        for (const cd of rootCustomData) {
+            const cdName = cd.typescriptName || cd.name || cd.id || "Unknown";
+            const cdType = cd.type || "?";
+            let shape = "";
+            if (cd.type === "ENUM") {
+                const opts = (cd.enumOptions || []).map((o) => o.value || o.displayName).filter(Boolean);
+                shape = ` — shape: \`enum {${opts.slice(0, 6).join(", ")}${opts.length > 6 ? ", ..." : ""}}\``;
+            }
+            else if (cd.nestedData && cd.nestedData.length > 0) {
+                const first = cd.nestedData[0];
+                const fields = (first?.nestedData || cd.nestedData || []).map((f) => `${f.key || f.name || "?"}: ${f.type || "?"}`).slice(0, 8);
+                shape = ` — shape: \`{${fields.join(", ")}}\``;
+            }
+            const usedBy = cd.id ? usageByCustomDataId.get(cd.id) || [] : [];
+            const usedByStr = usedBy.length > 0 ? ` — used by: ${usedBy.slice(0, 6).join(", ")}${usedBy.length > 6 ? `, +${usedBy.length - 6} more` : ""}` : ` — _not directly referenced by any section's props (may be nested inside another customData)_`;
+            parts.push(`- \`${cdName}\` (${cdType})${shape}${usedByStr}`);
+        }
+        parts.push("");
+    }
+    // Sections queue
+    parts.push(`## Sections`);
+    parts.push("");
+    parts.push(`Component **names** are listed below. The CLI auto-generates opaque \`componentId\`s when you run \`config add-component\` — capture each id from the JSON response and use it (or look it up later with \`config list\`) when wiring \`filteredComponentIds\`.`);
+    parts.push("");
+    const buckets = {
+        simple: [],
+        medium: [],
+        complex: [],
+    };
+    for (const comp of components) {
+        const complexity = classifyComplexity(comp, customDataMap);
+        buckets[complexity].push({ comp, complexity });
+    }
+    const labels = {
+        simple: "### Simple (migrate first)",
+        medium: "### Medium",
+        complex: "### Complex (migrate last)",
+    };
+    for (const key of ["simple", "medium", "complex"]) {
+        const items = buckets[key];
+        if (items.length === 0)
+            continue;
+        parts.push(labels[key]);
+        parts.push("");
+        for (const { comp } of items) {
+            const oldName = comp.displayName || comp.dir || comp.id || "Unknown";
+            const kebabName = toKebabCase(comp.dir || comp.displayName || comp.id || "unknown");
+            const newId = `${projectName}-${kebabName}`;
+            const headerFooter = comp.isHeader ? " **[HEADER]**" : comp.isFooter ? " **[FOOTER]**" : "";
+            const propCount = (comp.props || []).length;
+            // Detect children from CUSTOM DYNAMIC_LIST props
+            const children = [];
+            for (const p of comp.props || []) {
+                if (p.type === "CUSTOM" && p.customDataId) {
+                    const cd = customDataMap.get(p.customDataId);
+                    if (cd && (cd.type === "DYNAMIC_LIST" || cd.type === "STATIC_LIST")) {
+                        const itemObj = cd.nestedData?.[0];
+                        if (itemObj) {
+                            const childName = itemObj.typescriptName || (itemObj.name ? itemObj.name.replace(/[^a-zA-Z0-9]/g, "") : `${oldName}Item`);
+                            const fields = (itemObj.nestedData || []).map((f) => f.key || f.name || "?").slice(0, 8);
+                            children.push({ propName: p.name || "?", childName, fields });
+                        }
+                    }
+                }
+            }
+            parts.push(`- [ ] \`${newId}\` — **${oldName}**${headerFooter} (${propCount} props)`);
+            parts.push(`  - Old dir: \`${comp.dir || "?"}\``);
+            if (children.length > 0) {
+                parts.push(`  - Children:`);
+                for (const ch of children) {
+                    parts.push(`    - [ ] \`${ch.childName}\` — for prop \`${ch.propName}\` — fields: ${ch.fields.join(", ")}`);
+                }
+            }
+        }
+        parts.push("");
+    }
+    // Source Code Analysis — placeholder for the LLM to fill in
+    parts.push(`## Source Code Analysis`);
+    parts.push("");
+    parts.push(`> **Before starting section migration**, scan the old \`src/\` for components NOT listed above. theme.json does not see atomic primitives — buttons, inputs, cards, icon wrappers, layout helpers, etc. — that are imported by sections but never appear as theme components. Add them here, then decide which become shared sub-components vs which collapse into section bodies.`);
+    parts.push("");
+    parts.push(`<!-- Example: \`- Button (src/atoms/Button/) — used by ~all sections → promote to Shared Sub-Component\` -->`);
+    parts.push("");
+    // Custom Data Decisions — append-only log the LLM fills as it makes per-section decisions
+    parts.push(`## Custom Data Decisions`);
+    parts.push("");
+    parts.push(`> Log each customData enum-vs-component decision here as you encounter it during section migration. Format: \`- \\\`<CustomDataName>\\\` → enum/component \\\`<target name>\\\` (YYYY-MM-DD) — reasoning\`.`);
+    parts.push("");
+    parts.push(`<!-- Example: \`- SlideData → component \\\`hero-slide\\\` (2026-05-11) — structured record {image,link,title}; LIST_OF_LINK would drop the image\` -->`);
+    parts.push("");
+    // Known Environmental Issues (agents fill in during work)
+    parts.push(`## Known Environmental Issues`);
+    parts.push("");
+    parts.push(`_Record any non-component build/TS errors here so future sessions don't waste time diagnosing them._`);
+    parts.push("");
+    parts.push(`- [ ] _(none recorded yet)_`);
+    parts.push("");
+    // Notes — append-only log for decisions not captured elsewhere
+    parts.push(`## Notes`);
+    parts.push("");
+    parts.push(`_Append a bullet after completing work — library swaps, ad-hoc props, CLI folder-name oddities, user-approved feature drops, etc. Format: \`- [YYYY-MM-DD] <section-id>: <brief note>\`._`);
+    parts.push("");
+    parts.push(`<!-- Example: \`- [2026-04-15] ${projectName}-footer: swapped react-hot-toast for inline status text; CLI created Footer/ as expected\` -->`);
+    parts.push("");
+    // Cross-references — keep terse; LLM can call `get_migration_guide("list")` or `get_framework_guide("list")` for more
+    parts.push(`## Cross-References`);
+    parts.push("");
+    parts.push(`- \`get_migration_guide("iterative-workflow")\` — the full per-phase protocol`);
+    parts.push(`- \`get_migration_guide("custom-data-conversion")\` — enum-vs-component decisions`);
+    parts.push(`- \`get_migration_guide("prop-runtime-shapes")\` — runtime shapes & access patterns`);
+    parts.push(`- \`get_framework_guide("common-pitfalls")\` — gotchas & old→new property migrations`);
+    parts.push("");
+    parts.push(`Call \`get_migration_guide("list")\` or \`get_framework_guide("list")\` for the full topic catalog.`);
+    parts.push("");
+    return parts.join("\n");
+}
+// Known libraries we detect in old themes and want to flag for replacement
+const KNOWN_LIBRARIES = [
+    "swiper", "@headlessui/react", "@heroicons/react", "recharts",
+    "react-player", "react-simple-star-rating", "react-slider", "react-compound-slider",
+    "react-zoom-pan-pinch", "react-hot-toast", "react-fast-marquee",
+    "react-indiana-drag-scroll", "react-simple-typewriter", "react-timer-hook",
+    "date-fns", "slugify", "classnames", "clsx", "@react-pdf/renderer",
+];
+// Heuristic: member-access patterns on old storefront stores/singletons that likely need new-system equivalents
+const OLD_STOREFRONT_CALL_REGEX = /\b(customerStore|cartStore|productStore|categoryStore|orderStore|searchStore|favoritesStore|i18nStore|Router|useStore)\.\w+/g;
+function scanSectionSource(componentDir, propNames) {
+    if (!fs.existsSync(componentDir))
+        return null;
+    const result = {
+        sourceFiles: [],
+        importedSubComponents: [],
+        importedLibraries: [],
+        importedUnknownLibraries: [],
+        propFieldUsage: {},
+        oldStorefrontCalls: [],
+        reactPackageUsage: [],
+    };
+    // Collect all .tsx/.ts files in the component dir
+    try {
+        for (const entry of fs.readdirSync(componentDir, { withFileTypes: true })) {
+            if (entry.isFile() && (entry.name.endsWith(".tsx") || entry.name.endsWith(".ts"))) {
+                result.sourceFiles.push(path.join(componentDir, entry.name));
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    if (result.sourceFiles.length === 0)
+        return result;
+    const importRegex = /import\s+(?:type\s+)?(?:\{[^}]+\}|\w+(?:\s*,\s*\{[^}]+\})?)\s+from\s+['"]([^'"]+)['"]/g;
+    const libSet = new Set();
+    const unknownLibSet = new Set();
+    const reactSet = new Set();
+    const subCompSet = new Map();
+    const callSet = new Set();
+    // Packages we treat as "framework" and don't flag for replacement (but do note in reactPackageUsage)
+    const REACT_PACKAGES = new Set(["react", "react-dom", "next", "next/link", "next/image", "next/router", "next/head", "next/script", "mobx-react-lite", "mobx"]);
+    for (const file of result.sourceFiles) {
+        let content;
+        try {
+            content = fs.readFileSync(file, "utf-8");
+        }
+        catch {
+            continue;
+        }
+        // Parse imports
+        let m;
+        while ((m = importRegex.exec(content)) !== null) {
+            const p = m[1];
+            if (p.startsWith(".")) {
+                const segs = p.split("/").filter(s => s && s !== "." && s !== "..");
+                const last = segs[segs.length - 1];
+                if (last && /^[A-Z]/.test(last) && !last.includes("__generated__")) {
+                    subCompSet.set(last, p);
+                }
+            }
+            else if (!p.startsWith("@ikas/")) {
+                // Classify: known library, react-family, or unknown-external
+                const base = p.startsWith("@") ? p.split("/").slice(0, 2).join("/") : p.split("/")[0];
+                if (REACT_PACKAGES.has(p) || REACT_PACKAGES.has(base)) {
+                    reactSet.add(base);
+                }
+                else {
+                    let matched = false;
+                    for (const lib of KNOWN_LIBRARIES) {
+                        if (p === lib || p.startsWith(lib + "/")) {
+                            libSet.add(lib);
+                            matched = true;
+                            break;
+                        }
+                    }
+                    if (!matched) {
+                        unknownLibSet.add(base);
+                    }
+                }
+            }
+        }
+        // Generic: detect any member call on old storefront stores/singletons
+        let cm;
+        OLD_STOREFRONT_CALL_REGEX.lastIndex = 0;
+        while ((cm = OLD_STOREFRONT_CALL_REGEX.exec(content)) !== null) {
+            callSet.add(cm[0]);
+        }
+        // Detect field access for each prop
+        for (const propName of propNames) {
+            if (!propName)
+                continue;
+            // Look for patterns like: propName.map((item) => ... item.FIELD ...)
+            // or: propName[0].FIELD, propName.FIELD, destructure: const { field } = propName
+            const mapRegex = new RegExp(`\\b${propName}(?:\\?)?\\.(?:map|forEach|filter|find|reduce)\\s*\\(\\s*\\(?(\\w+)`, "g");
+            let mm;
+            const itemVars = new Set();
+            while ((mm = mapRegex.exec(content)) !== null) {
+                itemVars.add(mm[1]);
+            }
+            // Also detect destructuring in map callback: .map(({ title, image }) => ...)
+            const destructRegex = new RegExp(`\\b${propName}(?:\\?)?\\.(?:map|forEach|filter|find|reduce)\\s*\\(\\s*\\(?\\s*\\{([^}]+)\\}`, "g");
+            const fields = new Set();
+            while ((mm = destructRegex.exec(content)) !== null) {
+                for (const f of mm[1].split(",")) {
+                    const name = f.trim().split(/[:=]/)[0].trim();
+                    if (name && /^\w+$/.test(name))
+                        fields.add(name);
+                }
+            }
+            // Scan for itemVar.fieldName access
+            for (const itemVar of itemVars) {
+                const fieldRegex = new RegExp(`\\b${itemVar}(?:\\?)?\\.(\\w+)`, "g");
+                while ((mm = fieldRegex.exec(content)) !== null) {
+                    const f = mm[1];
+                    // Exclude TS/JS keywords and built-ins
+                    if (!/^(map|forEach|filter|find|reduce|length|toString|valueOf|constructor|prototype|then|catch|finally)$/.test(f)) {
+                        fields.add(f);
+                    }
+                }
+            }
+            if (fields.size > 0) {
+                result.propFieldUsage[propName] = [...fields].sort();
+            }
+        }
+    }
+    result.importedSubComponents = [...subCompSet.entries()].map(([name, p]) => ({ name, path: p }));
+    result.importedLibraries = [...libSet].sort();
+    result.importedUnknownLibraries = [...unknownLibSet].sort();
+    result.reactPackageUsage = [...reactSet].sort();
+    result.oldStorefrontCalls = [...callSet].sort();
+    return result;
+}
+function generateSectionMigrationPlan(theme, sectionName, projectName, oldSourceDir) {
+    const components = theme.components || [];
+    const customData = theme.customData || [];
+    const customDataMap = new Map();
+    for (const cd of customData) {
+        if (cd.id)
+            customDataMap.set(cd.id, cd);
+    }
+    // Find the component — try match by dir, displayName, id, or new-id
+    const target = components.find(c => {
+        if (!c)
+            return false;
+        if (c.dir === sectionName || c.displayName === sectionName || c.id === sectionName)
+            return true;
+        const kebab = toKebabCase(c.dir || c.displayName || c.id || "");
+        const newId = `${projectName}-${kebab}`;
+        return newId === sectionName;
+    });
+    if (!target) {
+        const available = components.map(c => c.dir || c.displayName || c.id).filter(Boolean).join(", ");
+        return `Section "${sectionName}" not found in theme. Available: ${available}`;
+    }
+    const parts = [];
+    const oldName = target.displayName || target.dir || target.id || "Unknown";
+    const kebabName = toKebabCase(target.dir || target.displayName || target.id || "unknown");
+    const sectionId = `${projectName}-${kebabName}`;
+    const sectionPascal = (target.dir || target.displayName || "").replace(/[^a-zA-Z0-9]/g, "") || kebabName.split("-").map(s => s[0]?.toUpperCase() + s.slice(1)).join("");
+    // Scan the old source for imports, libraries, field usage
+    const propNames = (target.props || []).map(p => p.name || "").filter(Boolean);
+    const sourceScan = (oldSourceDir && target.dir)
+        ? scanSectionSource(path.join(oldSourceDir, target.dir), propNames)
+        : null;
+    parts.push(`# Section Migration Plan: ${oldName}`);
+    parts.push("");
+    parts.push(`**Old name:** \`${oldName}\` (dir: \`${target.dir || "?"}\`)`);
+    parts.push(`**New section name:** \`${sectionPascal}\` (the CLI will assign an opaque \`componentId\` at write-time — capture it from \`config add-component\`'s JSON response)`);
+    parts.push(`**Migration checkbox label:** \`${sectionId}\` (tracking identifier in \`MIGRATION.md\` only — not the runtime component id)`);
+    if (target.isHeader)
+        parts.push(`**Flags:** HEADER (\`isHeader: true\`)`);
+    if (target.isFooter)
+        parts.push(`**Flags:** FOOTER (\`isFooter: true\`)`);
+    parts.push("");
+    parts.push(`> **CLI casing note:** \`config add-component --name "${sectionPascal}"\` will create the folder as \`src/components/${sectionPascal}/\`. If you pass all-caps names (e.g. \`FAQ\`), the CLI PascalCases them (\`Faq/\`). Use the folder name the CLI actually creates in your imports.`);
+    parts.push("");
+    // Source files
+    parts.push(`## 1. Old Source Files to Read`);
+    parts.push("");
+    if (sourceScan && sourceScan.sourceFiles.length > 0) {
+        parts.push(`Read these files from the old project (detected by scanning the directory):`);
+        for (const f of sourceScan.sourceFiles) {
+            parts.push(`- \`${f}\``);
+        }
+        if (sourceScan.importedSubComponents.length > 0) {
+            parts.push("");
+            parts.push(`**Imported sub-components** (relative PascalCase imports found in the source — read these too if you need their behavior):`);
+            for (const sub of sourceScan.importedSubComponents) {
+                parts.push(`- \`${sub.name}\` (import path: \`${sub.path}\`)`);
+            }
+        }
+        if (sourceScan.importedLibraries.length > 0) {
+            parts.push("");
+            parts.push(`**External libraries (recognized) — MUST be replaced with vanilla Preact + CSS:**`);
+            for (const lib of sourceScan.importedLibraries) {
+                parts.push(`- \`${lib}\` — see \`get_migration_guide("library-replacements")\``);
+            }
+        }
+        if (sourceScan.importedUnknownLibraries.length > 0) {
+            parts.push("");
+            parts.push(`**External libraries (unrecognized) — verify whether a replacement is needed:**`);
+            for (const lib of sourceScan.importedUnknownLibraries) {
+                parts.push(`- \`${lib}\` — this library is not in our known-replacement list. Check if the new system provides equivalent functionality via \`search_docs\` / \`list_functions\`. If not, implement in vanilla Preact. See \`get_migration_guide("finding-new-system-equivalents")\`.`);
+            }
+        }
+        if (sourceScan.reactPackageUsage.length > 0) {
+            parts.push("");
+            parts.push(`**React/Next.js framework imports detected:** ${sourceScan.reactPackageUsage.map(p => `\`${p}\``).join(", ")}. These do NOT carry over — the new system is Preact. See \`get_migration_guide("react-to-preact")\` for conversion patterns (hooks, observer, event types, routing).`);
+        }
+        if (sourceScan.oldStorefrontCalls.length > 0) {
+            parts.push("");
+            parts.push(`**Old-system API calls detected — search for new-system equivalents:**`);
+            for (const call of sourceScan.oldStorefrontCalls) {
+                parts.push(`- \`${call}\``);
+            }
+            parts.push("");
+            parts.push(`Each of these is a call on an old \`@ikas/storefront\` store or singleton. The new system (\`@ikas/bp-storefront\`) has different APIs — never assume the same method exists. Follow the discovery protocol in \`get_migration_guide("finding-new-system-equivalents")\`:`);
+            parts.push(`1. Identify the intent (e.g. "login", "add to cart", "newsletter signup", "navigate")`);
+            parts.push(`2. \`search_docs("<intent keywords>")\` to find candidates`);
+            parts.push(`3. \`list_functions("<category>")\` (Form, Cart, Customer, Navigation, ...) to see all options`);
+            parts.push(`4. \`get_function_doc("<name>")\` / \`get_model_guide("<Type>")\` for exact signatures`);
+            parts.push(`5. \`get_code_example("<task>")\` for working examples`);
+        }
+    }
+    else if (oldSourceDir && target.dir) {
+        const compDir = path.join(oldSourceDir, target.dir);
+        parts.push(`Read these files from the old project (if they exist):`);
+        parts.push(`- \`${compDir}/index.tsx\` — main component implementation`);
+        parts.push(`- \`${compDir}/*.tsx\` — any nested sub-components`);
+        parts.push(`- \`${compDir}/*.css\` / \`*.scss\` — styles`);
+    }
+    else {
+        parts.push(`Read the old component at \`src/components/${target.dir || oldName}/index.tsx\` and any files in that directory.`);
+    }
+    parts.push("");
+    // Prop conversion table
+    parts.push(`## 2. Prop Conversion Table`);
+    parts.push("");
+    parts.push(`| Old prop | Old type | → | New prop | New type | Notes |`);
+    parts.push(`|----------|----------|---|----------|----------|-------|`);
+    const children = [];
+    const enumsNeeded = [];
+    const librariesDetected = new Set();
+    const parentPropsJson = [];
+    for (const p of target.props || []) {
+        const oldName = p.name || "?";
+        const oldType = p.type || "?";
+        let newName = oldName;
+        let newType = oldType;
+        let notes = "Direct";
+        if (oldType === "SLIDER") {
+            newType = "NUMBER";
+            notes = `Was SLIDER(min=${p.sliderData?.min}, max=${p.sliderData?.max}) — replace \`.value\` access with direct number`;
+            const prop = { name: newName, displayName: p.displayName || newName, type: "NUMBER" };
+            if (p.isRequired)
+                prop.required = true;
+            parentPropsJson.push(prop);
+        }
+        else if (oldType === "PRODUCT_DETAIL") {
+            newType = "PRODUCT";
+            notes = "Renamed — PRODUCT_DETAIL → PRODUCT";
+            const prop = { name: newName, displayName: p.displayName || newName, type: "PRODUCT" };
+            if (p.isRequired)
+                prop.required = true;
+            parentPropsJson.push(prop);
+        }
+        else if (oldType === "CUSTOM" && p.customDataId) {
+            const cd = customDataMap.get(p.customDataId);
+            if (cd) {
+                if (cd.type === "DYNAMIC_LIST" || cd.type === "STATIC_LIST") {
+                    // Child component needed
+                    const itemObj = cd.nestedData?.[0];
+                    const childName = itemObj?.typescriptName || (itemObj?.name ? itemObj.name.replace(/[^a-zA-Z0-9]/g, "") : `${sectionPascal}Item`);
+                    const childProps = [];
+                    const nestedWarnings = [];
+                    for (const f of (itemObj?.nestedData || [])) {
+                        if (!f.key)
+                            continue;
+                        let fType = f.type;
+                        if (fType === "SLIDER")
+                            fType = "NUMBER";
+                        else if (fType === "PRODUCT_DETAIL")
+                            fType = "PRODUCT";
+                        else if (fType === "CUSTOM" || fType === "DYNAMIC_LIST" || fType === "STATIC_LIST" || fType === "OBJECT") {
+                            nestedWarnings.push(`\`${f.key}\` (${fType})`);
+                            fType = "COMPONENT_LIST";
+                        }
+                        const prop = { name: f.key, displayName: f.name || f.key, type: fType };
+                        if (f.isRequired)
+                            prop.required = true;
+                        childProps.push(prop);
+                    }
+                    if (nestedWarnings.length > 0) {
+                        notes = `⚠️ Child has nested structures (${nestedWarnings.join(", ")}) — these need their OWN child components. After creating this child, decompose each nested structure recursively.`;
+                    }
+                    // If customData is empty/incomplete, try to infer fields from source usage
+                    if (childProps.length === 0 && sourceScan?.propFieldUsage[oldName]) {
+                        const inferred = sourceScan.propFieldUsage[oldName];
+                        for (const fieldName of inferred) {
+                            childProps.push({ name: fieldName, displayName: fieldName, type: "TEXT" });
+                        }
+                        if (inferred.length > 0) {
+                            notes = `Was CUSTOM → ${cd.type} with empty customData. **Inferred props from source usage:** ${inferred.map(f => `\`${f}\``).join(", ")}. Verify types and required flags — default inferred type is TEXT.`;
+                        }
+                    }
+                    children.push({
+                        propName: oldName,
+                        childName,
+                        childPropsJson: childProps,
+                        customDataName: cd.name || "unnamed",
+                    });
+                    newType = "COMPONENT_LIST";
+                    notes = `Was CUSTOM → ${cd.type} of ${itemObj?.typescriptName || "object"}. Create child component \`${childName}\`; the CLI returns the opaque \`componentId\` in its JSON response — substitute it for the \`<id-of-${childName}>\` placeholder below.`;
+                    const prop = {
+                        name: newName,
+                        displayName: p.displayName || newName,
+                        type: "COMPONENT_LIST",
+                        filteredComponentIds: [`<id-of-${childName}>`],
+                    };
+                    parentPropsJson.push(prop);
+                }
+                else if (cd.type === "OBJECT") {
+                    const fieldCount = (cd.nestedData || []).length;
+                    if (fieldCount <= 3) {
+                        notes = `Was CUSTOM (OBJECT, ${fieldCount} fields) — **flatten into direct props** (${(cd.nestedData || []).map((f) => f.key || f.name).join(", ")})`;
+                        for (const f of (cd.nestedData || [])) {
+                            if (!f.key)
+                                continue;
+                            let fType = f.type;
+                            if (fType === "SLIDER")
+                                fType = "NUMBER";
+                            const prop = { name: f.key, displayName: f.name || f.key, type: fType };
+                            if (f.isRequired)
+                                prop.required = true;
+                            parentPropsJson.push(prop);
+                        }
+                        newType = "(flattened)";
+                        newName = (cd.nestedData || []).map((f) => f.key).join(", ");
+                    }
+                    else {
+                        newType = "COMPONENT_LIST";
+                        notes = `Was CUSTOM (OBJECT, ${fieldCount} fields) — too complex to flatten, use COMPONENT_LIST with single child`;
+                    }
+                }
+                else if (cd.type === "ENUM") {
+                    newType = "ENUM";
+                    const enumName = cd.typescriptName || (cd.name ? cd.name.replace(/[^a-zA-Z0-9]/g, "") : "Enum");
+                    const options = (cd.enumOptions || []).reduce((acc, o) => {
+                        if (o.displayName && o.value)
+                            acc[o.displayName] = o.value;
+                        return acc;
+                    }, {});
+                    enumsNeeded.push({ name: enumName, options });
+                    notes = `Was CUSTOM (ENUM) — create enum \`${enumName}\` via \`config add-enum\` first, then reference its enumId here`;
+                    const prop = { name: newName, displayName: p.displayName || newName, type: "ENUM", enumTypeId: `<ENUM_ID_FROM_add-enum_${enumName}>` };
+                    if (p.isRequired)
+                        prop.required = true;
+                    parentPropsJson.push(prop);
+                }
+            }
+        }
+        else {
+            // Direct mapping
+            const prop = { name: newName, displayName: p.displayName || newName, type: newType };
+            if (p.isRequired)
+                prop.required = true;
+            parentPropsJson.push(prop);
+        }
+        parts.push(`| \`${oldName}\` | ${oldType} | → | \`${newName}\` | ${newType} | ${notes} |`);
+    }
+    parts.push("");
+    // Custom Data Decision Callouts — per prop referencing a customData type
+    const customDataPropsForCallouts = (target.props || []).filter((p) => p.type === "CUSTOM" && p.customDataId && customDataMap.has(p.customDataId));
+    if (customDataPropsForCallouts.length > 0) {
+        parts.push(`## Custom Data Decisions to Make`);
+        parts.push("");
+        parts.push(`Each prop below references an old \`customData\` type. Verify the MCP's default against the actual data semantics, then run the CLI command. **Log every decision in MIGRATION.md → \`## Custom Data Decisions\`** with reasoning. See \`get_migration_guide("custom-data-conversion")\` for the heuristic and worked examples.`);
+        parts.push("");
+        for (const p of customDataPropsForCallouts) {
+            const cd = customDataMap.get(p.customDataId);
+            if (!cd)
+                continue;
+            const cdName = cd.typescriptName || cd.name || cd.id || "Unknown";
+            const cdType = cd.type || "?";
+            let shape = "";
+            let shapeKind = "unknown";
+            if (cd.type === "ENUM") {
+                const opts = (cd.enumOptions || []).map((o) => o.value || o.displayName).filter(Boolean);
+                shape = `enum {${opts.slice(0, 6).join(", ")}${opts.length > 6 ? ", ..." : ""}}`;
+                shapeKind = "enum";
+            }
+            else if (cd.type === "DYNAMIC_LIST" || cd.type === "STATIC_LIST") {
+                const first = cd.nestedData?.[0];
+                const fields = (first?.nestedData || []).map((f) => `${f.key || f.name || "?"}: ${f.type || "?"}`);
+                shape = `${cdType} of {${fields.slice(0, 6).join(", ")}}`;
+                shapeKind = "list";
+            }
+            else if (cd.type === "OBJECT") {
+                const fields = (cd.nestedData || []).map((f) => `${f.key || f.name || "?"}: ${f.type || "?"}`);
+                shape = `OBJECT {${fields.slice(0, 6).join(", ")}}`;
+                shapeKind = "record";
+            }
+            else {
+                shape = cdType;
+            }
+            // Build the field source + names list once so we can use it for the lost-fields enumeration
+            // AND for the component-path CLI template.
+            const fieldSource = cd.type === "DYNAMIC_LIST" || cd.type === "STATIC_LIST"
+                ? cd.nestedData?.[0]?.nestedData || []
+                : cd.nestedData || [];
+            const fieldDescriptions = fieldSource
+                .filter((f) => f.key)
+                .map((f) => `\`${f.key}\` (${f.type || "?"})`);
+            parts.push(`### Prop \`${p.name || "?"}\` → customData \`${cdName}\``);
+            parts.push("");
+            parts.push(`**Shape:** \`${shape}\``);
+            parts.push("");
+            if (shapeKind === "enum") {
+                parts.push(`**Default: enum prop.** Flat scalar set; use \`config add-enum\`.`);
+                parts.push("");
+                const enumName = cd.typescriptName || (cd.name ? cd.name.replace(/[^a-zA-Z0-9]/g, "") : "Enum");
+                const enumOptions = (cd.enumOptions || []).reduce((acc, o) => {
+                    if (o.displayName && o.value)
+                        acc[o.displayName] = o.value;
+                    return acc;
+                }, {});
+                parts.push("```bash");
+                parts.push(`npx ikas-component config add-enum --name "${enumName}" --options '${JSON.stringify(enumOptions)}'`);
+                parts.push("```");
+                parts.push("");
+                parts.push(`If you believe this should be a component instead (e.g. each option secretly carries richer data not visible in the customData shape), see \`get_migration_guide("custom-data-conversion")\`.`);
+                parts.push("");
+            }
+            else if (shapeKind === "list" || shapeKind === "record") {
+                const fieldCount = fieldDescriptions.length;
+                const isMinimal = fieldCount > 0 && fieldCount <= 2;
+                if (isMinimal) {
+                    parts.push(`⚠️ **This child would have only ${fieldCount} field${fieldCount === 1 ? "" : "s"}** (${fieldDescriptions.join(", ")}). \`COMPONENT_LIST\` is usually overkill at this size. **Prefer one of:**`);
+                    parts.push(`- repeated scalar props on the parent (\`title1\`/\`link1\`, \`title2\`/\`link2\`, …) for a small fixed count`);
+                    parts.push(`- a domain LIST prop type (\`LIST_OF_LINK\`, \`IMAGE_LIST\`, \`PRODUCT_LIST\`, …) when each item IS one domain object`);
+                    parts.push(`- \`COMPONENT_LIST\` (CLI command below) only if reordering in the editor is a real UX win`);
+                    parts.push("");
+                    parts.push(`See \`get_migration_guide("component-composition-decision-guide")\` for the full tree. Log your choice in MIGRATION.md → \`## Custom Data Decisions\`.`);
+                    parts.push("");
+                }
+                else {
+                    parts.push(`**Default: component + COMPONENT_LIST.** Multiple fields per item — a single enum value cannot carry this structure.`);
+                    parts.push("");
+                    if (fieldCount > 0) {
+                        parts.push(`⚠️ **Fields you would lose if you flatten this:** ${fieldDescriptions.join(", ")}. Flattening to a simpler prop type drops these from the editor UI permanently. **Do not "simplify for later"** — if the feature genuinely isn't wanted, log that explicitly in MIGRATION.md → \`## Notes\` with reasoning. Otherwise build the component.`);
+                        parts.push("");
+                    }
+                    parts.push(`> See \`get_migration_guide("component-composition-decision-guide")\` for when \`COMPONENT_LIST\` is overkill.`);
+                    parts.push("");
+                }
+                const compName = cd.typescriptName || (cd.name ? cd.name.replace(/[^a-zA-Z0-9]/g, "") : `${sectionPascal}Item`);
+                const compPropsForCli = [];
+                for (const f of fieldSource) {
+                    if (!f.key)
+                        continue;
+                    let fType = f.type;
+                    if (fType === "SLIDER")
+                        fType = "NUMBER";
+                    else if (fType === "PRODUCT_DETAIL")
+                        fType = "PRODUCT";
+                    compPropsForCli.push({ name: f.key, displayName: f.name || f.key, type: fType });
+                }
+                parts.push("```bash");
+                if (isMinimal) {
+                    parts.push(`# Fallback: COMPONENT_LIST (use only if the simpler alternatives above don't fit)`);
+                }
+                parts.push(`npx ikas-component config add-component --name "${compName}" --type component --props '${JSON.stringify(compPropsForCli)}'`);
+                parts.push(`# Then on the parent, set the prop's filteredComponentIds to the new component's id.`);
+                parts.push("```");
+                parts.push("");
+                parts.push(`If you believe this should be an enum despite the structure, see \`get_migration_guide("custom-data-conversion")\`.`);
+                parts.push("");
+            }
+            else {
+                parts.push(`**Unable to classify automatically — you decide.** See \`get_migration_guide("custom-data-conversion")\` for the enum-vs-component heuristic.`);
+                parts.push("");
+            }
+        }
+    }
+    // Enums to create first
+    if (enumsNeeded.length > 0) {
+        parts.push(`## 3. Create Enums FIRST (if not already done)`);
+        parts.push("");
+        for (const e of enumsNeeded) {
+            parts.push(`\`\`\`bash`);
+            parts.push(`npx ikas-component config add-enum --name "${e.name}" --options '${JSON.stringify(e.options)}'`);
+            parts.push(`\`\`\``);
+        }
+        parts.push(`Save the returned \`enumId\` values and substitute them in the parent config JSON below.`);
+        parts.push("");
+    }
+    // Child CLI commands — dedupe by childName (same shape may be referenced by multiple parent props)
+    const uniqueChildren = new Map();
+    for (const ch of children) {
+        const existing = uniqueChildren.get(ch.childName);
+        if (existing) {
+            existing.usedByProps.push(ch.propName);
+        }
+        else {
+            uniqueChildren.set(ch.childName, { child: ch, usedByProps: [ch.propName] });
+        }
+    }
+    if (uniqueChildren.size > 0) {
+        parts.push(`## ${enumsNeeded.length > 0 ? "4" : "3"}. Create Child Components FIRST`);
+        parts.push("");
+        parts.push(`These children are referenced by the parent's COMPONENT_LIST props. Create them before the parent.`);
+        parts.push(`**Deduped:** run each \`add-component\` command ONCE even if multiple parent props reference the same child.`);
+        parts.push(`**Capture each \`componentId\` from the CLI's JSON response** — you'll substitute these ids for the \`<id-of-{ChildName}>\` placeholders in the parent's \`filteredComponentIds\` below.`);
+        parts.push("");
+        for (const { child: ch, usedByProps } of uniqueChildren.values()) {
+            parts.push(`### \`${ch.childName}\``);
+            const propsLabel = usedByProps.length > 1
+                ? `Used by parent props: ${usedByProps.map(p => `\`${p}\``).join(", ")} (${usedByProps.length}×)`
+                : `For parent prop: \`${usedByProps[0]}\``;
+            parts.push(propsLabel);
+            parts.push(`Old customData: "${ch.customDataName}"`);
+            parts.push("");
+            parts.push(`\`\`\`bash`);
+            parts.push(`npx ikas-component config add-component --name "${ch.childName}" --type component --props '${JSON.stringify(ch.childPropsJson)}'`);
+            parts.push(`# → { "success": true, "componentId": "<capture-this>", ... }`);
+            parts.push(`\`\`\``);
+            parts.push("");
+        }
+    }
+    // Parent CLI
+    const parentStep = 3 + (enumsNeeded.length > 0 ? 1 : 0) + (children.length > 0 ? 1 : 0);
+    parts.push(`## ${parentStep}. Create Parent Section`);
+    parts.push("");
+    const isHeaderFlag = target.isHeader ? " --isHeader" : "";
+    const isFooterFlag = target.isFooter ? " --isFooter" : "";
+    parts.push(`\`\`\`bash`);
+    parts.push(`npx ikas-component config add-component --name "${sectionPascal}" --type section${isHeaderFlag}${isFooterFlag} --props '${JSON.stringify(parentPropsJson)}'`);
+    parts.push(`\`\`\``);
+    parts.push("");
+    parts.push(`**IMPORTANT:** The CLI auto-generates \`types.ts\`. DO NOT manually create or edit \`types.ts\`.`);
+    if (children.length > 0) {
+        parts.push("");
+        parts.push(`**Before running the command above:** replace each \`<id-of-{ChildName}>\` placeholder in the \`--props\` JSON with the real \`componentId\` captured from the corresponding child's \`add-component\` response (or from \`npx ikas-component config list\`). Component ids are opaque random strings — the CLI will reject any unknown id with a structured error.`);
+    }
+    parts.push("");
+    // Implementation guidance
+    const nextStep = parentStep + 1;
+    parts.push(`## ${nextStep}. Write \`index.tsx\` and \`styles.css\``);
+    parts.push("");
+    parts.push(`After running the CLI commands, write the section's \`index.tsx\`. Key rules:`);
+    parts.push("");
+    parts.push(`- **BOTH named + default export** (the CLI barrel file uses named imports — without both, build fails):`);
+    parts.push(`  \`\`\`export function ${sectionPascal}(props: Props) { ... } export default ${sectionPascal};\`\`\``);
+    parts.push(`- No \`observer()\` on root sections — only on sub-components`);
+    parts.push(`- Import from \`@ikas/bp-storefront\` (NOT \`@ikas/storefront\`)`);
+    parts.push(`- Use \`getDefaultSrc(image)\` + native \`<img>\` instead of the old \`<Image>\` component`);
+    parts.push(`- Replace \`IkasSlider\` usage (\`.value\` access) with plain \`number\``);
+    if (children.length > 0) {
+        parts.push(`- For COMPONENT_LIST props, use \`<IkasComponentRenderer id="..." components={list as any[]} parentProps={props} />\``);
+        parts.push(`- **Remember: the parent cannot read child prop values.** Any per-item logic must live in the child component.`);
+        parts.push(`- **Every COMPONENT_LIST slot needs a child component to render individual items.** A product list needs a ProductCard child, a blog list needs a BlogCard child, etc. Check if the child already exists (run \`config list\` to see all components and their opaque ids; reuse the existing id in \`filteredComponentIds\`). If not, create it as a registered component and use the \`componentId\` from the CLI's response.`);
+    }
+    // Check if the section itself has data-driven list props (PRODUCT_LIST, BLOG_LIST, CATEGORY_LIST)
+    const dataListProps = (target.props || []).filter(p => p.type === "PRODUCT_LIST" || p.type === "BLOG_LIST" || p.type === "CATEGORY_LIST" || p.type === "BRAND_LIST");
+    if (dataListProps.length > 0) {
+        parts.push("");
+        parts.push(`### Data-Driven List Rendering`);
+        parts.push("");
+        parts.push(`This section has data-driven list props: ${dataListProps.map(p => `\`${p.name}\` (${p.type})`).join(", ")}.`);
+        parts.push(`These are NOT COMPONENT_LIST — the data comes from dynamic queries (filters, categories, search), not hand-picked items. Render items **internally** by mapping over the data:`);
+        parts.push("");
+        parts.push("```tsx");
+        for (const p of dataListProps) {
+            if (p.type === "PRODUCT_LIST") {
+                parts.push(`// ${p.name}: PRODUCT_LIST — map over .data to render each product`);
+                parts.push(`{${p.name}?.data?.map((product, i) => (`);
+                parts.push(`  <ProductCard key={i} product={product} />`);
+                parts.push(`))}`);
+            }
+            else if (p.type === "BLOG_LIST") {
+                parts.push(`// ${p.name}: BLOG_LIST — map over .data to render each blog post`);
+                parts.push(`{${p.name}?.data?.map((blog, i) => (`);
+                parts.push(`  <BlogCard key={i} blog={blog} />`);
+                parts.push(`))}`);
+            }
+            else {
+                parts.push(`// ${p.name}: ${p.type} — check shape with get_model_guide, then map over items`);
+            }
+        }
+        parts.push("```");
+        parts.push("");
+        parts.push(`Use a **registered component** (e.g., ProductCard, BlogCard) to render each item. The same component can be reused in both data-driven sections (imported directly) AND COMPONENT_LIST slots (placed by the store owner). Check if it already exists — if so, import it from \`../ProductCard\`. If not, create it as a registered component.`);
+        parts.push(`See \`get_migration_guide("custom-data-conversion")\` → "Two Ways to Render Lists" for the full pattern.`);
+    }
+    // Detect form-page sections (0 or few props, name suggests a form/auth page)
+    const formKeywords = ["login", "register", "forgot", "recover", "password", "account", "email", "verification", "activate", "contact", "checkout", "address"];
+    const lowerDir = (target.dir || "").toLowerCase();
+    const isLikelyFormPage = formKeywords.some(kw => lowerDir.includes(kw));
+    if (isLikelyFormPage) {
+        parts.push("");
+        parts.push(`### Form Page Pattern`);
+        parts.push("");
+        parts.push(`This section looks like a **form/auth page**. The old system typically used imperative \`customerStore\` methods. The new system uses a form-model pattern.`);
+        parts.push(`- Call \`search_docs("<relevant keyword>")\` to find the new-system form functions (e.g., \`search_docs("forgot password")\`, \`search_docs("login")\`, \`search_docs("register")\`)`);
+        parts.push(`- Call \`get_framework_guide("form-handling")\` for the general form-model pattern`);
+        parts.push(`- Call \`get_code_example("<section-type>")\` if available (e.g., \`get_code_example("login-section")\`, \`get_code_example("register-section")\`, \`get_code_example("forgot-password-section")\`)`);
+        parts.push(`- Typical pattern: \`get<Feature>Form()\` → \`set<Feature>Form<Field>(form, value)\` → \`submit<Feature>Form(form)\``);
+        parts.push(`- Replace \`react-hot-toast\` feedback with inline status messages using TEXT props`);
+    }
+    parts.push("");
+    // Library detection — prefer source scan, fall back to heuristic
+    if (sourceScan && sourceScan.importedLibraries.length > 0) {
+        parts.push(`### Library Replacements Required (detected in source)`);
+        parts.push("");
+        parts.push(`These libraries are confirmed imports in the old source. Each MUST be replaced with vanilla Preact + CSS:`);
+        for (const lib of sourceScan.importedLibraries) {
+            parts.push(`- \`${lib}\``);
+        }
+        parts.push("");
+        parts.push(`Call \`get_migration_guide("library-replacements")\` for the specific replacement pattern for each.`);
+        parts.push("");
+    }
+    else if (!sourceScan) {
+        // Fallback heuristic only when source scan unavailable
+        const heuristicLibs = [];
+        const lowerName = oldName.toLowerCase();
+        if (lowerName.includes("slider") || lowerName.includes("carousel") || lowerName.includes("banner")) {
+            heuristicLibs.push("swiper");
+        }
+        if (lowerName.includes("marquee"))
+            heuristicLibs.push("react-fast-marquee");
+        if (lowerName.includes("video") || lowerName.includes("player"))
+            heuristicLibs.push("react-player");
+        if (lowerName.includes("chart"))
+            heuristicLibs.push("recharts");
+        if (lowerName.includes("star") || lowerName.includes("rating") || lowerName.includes("review"))
+            heuristicLibs.push("react-simple-star-rating");
+        if (heuristicLibs.length > 0) {
+            parts.push(`### Likely Library Replacements (heuristic — source not scanned)`);
+            parts.push("");
+            parts.push(`No \`old_source_dir\` was provided so libraries cannot be confirmed. Based on the component name, the old version may use:`);
+            for (const lib of heuristicLibs) {
+                parts.push(`- \`${lib}\``);
+            }
+            parts.push("");
+            parts.push(`Verify by reading the old \`index.tsx\`, then call \`get_migration_guide("library-replacements")\`.`);
+            parts.push("");
+        }
+    }
+    // Relevant guides — keep terse; LLM can call get_migration_guide("list") for the full catalog
+    parts.push(`## ${nextStep + 1}. Relevant Guides`);
+    parts.push("");
+    parts.push(`- \`get_migration_guide("react-to-preact")\` — code conversion patterns`);
+    parts.push(`- \`get_migration_guide("prop-runtime-shapes")\` — exact runtime shapes (\`.data\` vs \`.links\`, etc.)`);
+    if (children.length > 0 || target.isHeader || target.isFooter) {
+        parts.push(`- \`get_framework_guide("header-footer-patterns")\` — COMPONENT_LIST + IkasComponentRenderer wiring`);
+    }
+    parts.push("");
+    // Completion
+    parts.push(`## ${nextStep + 2}. Mark Complete`);
+    parts.push("");
+    parts.push(`Once the section builds cleanly with \`npx ikas-component build\`: edit MIGRATION.md → tick \`[x]\` for \`${sectionId}\` and each child component, log any customData decisions under \`## Custom Data Decisions\`, and append a brief entry to \`## Notes\` with anything future sessions should know.`);
+    parts.push("");
+    return parts.join("\n");
+}
 // --- Search helpers ---
 function matchScore(text, query) {
     const lower = text.toLowerCase();
@@ -181,10 +1452,59 @@ function matchScore(text, query) {
     }
     return score;
 }
+// Levenshtein edit distance — small DP, fine for the 28 short kebab-case section template names.
+function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    const m = a.length;
+    const n = b.length;
+    const prev = new Array(n + 1);
+    const curr = new Array(n + 1);
+    for (let j = 0; j <= n; j++)
+        prev[j] = j;
+    for (let i = 1; i <= m; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= n; j++) {
+            const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+            curr[j] = Math.min(curr[j - 1] + 1, // insertion
+            prev[j] + 1, // deletion
+            prev[j - 1] + cost // substitution
+            );
+        }
+        for (let j = 0; j <= n; j++)
+            prev[j] = curr[j];
+    }
+    return prev[n];
+}
+// Suggest up to `max` closest candidates for an unknown input.
+// Primary: matchScore (substring/word). Fallback: Levenshtein when nothing scores well.
+function suggestClosestNames(input, candidates, opts) {
+    const min = opts?.min ?? 8;
+    const max = opts?.max ?? 3;
+    const scored = candidates
+        .map((c) => ({ name: c, score: matchScore(c, input) }))
+        .filter((s) => s.score >= min)
+        .sort((a, b) => b.score - a.score);
+    if (scored.length > 0)
+        return scored.slice(0, max).map((s) => s.name);
+    // Levenshtein fallback — tolerate up to ceil(len/3) edits.
+    const maxDistance = Math.max(1, Math.ceil(input.length / 3));
+    const lower = input.toLowerCase();
+    const edits = candidates
+        .map((c) => ({ name: c, d: levenshtein(lower, c.toLowerCase()) }))
+        .filter((s) => s.d <= maxDistance)
+        .sort((a, b) => a.d - b.d);
+    return edits.slice(0, max).map((s) => s.name);
+}
 function searchFunctions(query) {
     const scored = storefrontData.functions
         .map((fn) => {
         const nameScore = matchScore(fn.name, query) * 3;
+        const displayNameScore = fn.displayName ? matchScore(fn.displayName, query) * 3 : 0;
         const descScore = matchScore(fn.description, query);
         const catScore = fn.categories.some((c) => matchScore(c, query) > 0) ? 5 : 0;
         const paramScore = fn.params.some((p) => matchScore(p.name, query) > 0 || matchScore(p.description, query) > 0)
@@ -192,7 +1512,10 @@ function searchFunctions(query) {
             : 0;
         const sigScore = matchScore(fn.signature, query) * 2;
         const typeScore = fn.parameterTypes?.some((t) => matchScore(t, query) > 0) ? 8 : 0;
-        return { fn, score: nameScore + descScore + catScore + paramScore + sigScore + typeScore };
+        return {
+            fn,
+            score: nameScore + displayNameScore + descScore + catScore + paramScore + sigScore + typeScore,
+        };
     })
         .filter((item) => item.score > 0)
         .sort((a, b) => b.score - a.score);
@@ -334,10 +1657,11 @@ const server = new McpServer({
     instructions: "Examples and section templates from this server are API reference only — reuse imports, function calls, and data-access patterns; create your own JSX structure, CSS class names, and visual design.",
 });
 // Tool: search_docs
-server.tool("search_docs", "Search across all ikas storefront API docs and framework guides. Returns matching functions and framework topics ranked by relevance.", { query: z.string().describe("Search keyword or phrase") }, async ({ query }) => {
+server.tool("search_docs", "Search across all ikas storefront API docs, framework guides, and migration guides. Returns matching functions, framework topics, and migration topics ranked by relevance.", { query: z.string().describe("Search keyword or phrase") }, async ({ query }) => {
     const functions = searchFunctions(query).slice(0, 10);
     const topics = searchFrameworkTopics(query).slice(0, 5);
     const types = searchTypes(query).slice(0, 5);
+    const migrationTopics = searchMigrationTopics(query).slice(0, 3);
     const parts = [];
     if (functions.length > 0) {
         parts.push("## Matching Storefront Functions\n");
@@ -363,7 +1687,15 @@ server.tool("search_docs", "Search across all ikas storefront API docs and frame
         parts.push("");
         parts.push("Use `get_type_definition(name)` to get full type details, or `search_types(query)` for more type results.");
     }
-    if (functions.length === 0 && topics.length === 0 && types.length === 0) {
+    if (migrationTopics.length > 0) {
+        parts.push("\n## Matching Migration Topics\n");
+        for (const item of migrationTopics) {
+            parts.push(`- [migration] **${item.topic.title}** (key: \`${item.key}\`) - ${item.topic.description}`);
+        }
+        parts.push("");
+        parts.push("Use `get_migration_guide(topic)` to get full content for any migration topic.");
+    }
+    if (functions.length === 0 && topics.length === 0 && types.length === 0 && migrationTopics.length === 0) {
         parts.push(`No results found for "${query}". Try different keywords or use \`list_functions()\` to see all available functions.`);
     }
     return { content: [{ type: "text", text: parts.join("\n") }] };
@@ -371,31 +1703,53 @@ server.tool("search_docs", "Search across all ikas storefront API docs and frame
 // Tool: get_function_doc
 server.tool("get_function_doc", "Get full documentation for a specific storefront API function including signature, parameters, return type, and example.", { name: z.string().describe("Function name (e.g. 'addItemToCart', 'Router.navigate')") }, async ({ name }) => {
     const nameLower = name.toLowerCase();
-    const fn = storefrontData.functions.find((f) => f.name.toLowerCase() === nameLower ||
-        (f.displayName && f.displayName.toLowerCase() === nameLower));
-    if (!fn) {
-        // Try fuzzy match
-        const matches = storefrontData.functions.filter((f) => f.name.toLowerCase().includes(nameLower) ||
-            (f.displayName && f.displayName.toLowerCase().includes(nameLower)));
-        if (matches.length > 0) {
-            const suggestions = matches.slice(0, 5).map((f) => {
-                const alias = f.displayName && f.displayName !== f.name ? ` (alias: ${f.displayName})` : "";
-                return `  - ${f.name}${alias}`;
-            });
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `Function "${name}" not found. Did you mean:\n${suggestions.join("\n")}`,
-                    },
-                ],
-            };
+    // Phase 1: canonical-name match wins. A real function name always outranks
+    // any displayName alias so aliases can never shadow the function they're
+    // named after (e.g. `hasCustomer` the function vs. `hasIkasOrderCustomer`'s
+    // [BP-DISPLAY-NAME: hasCustomer] alias).
+    const byName = storefrontData.functions.find((f) => f.name.toLowerCase() === nameLower);
+    if (byName) {
+        return { content: [{ type: "text", text: formatFunctionDoc(byName) }] };
+    }
+    // Phase 2: fall back to displayName aliases.
+    const byAlias = storefrontData.functions.filter((f) => f.displayName && f.displayName.toLowerCase() === nameLower);
+    if (byAlias.length === 1) {
+        const fn = byAlias[0];
+        const note = `> Note: "${name}" is a display alias for \`${fn.name}\`.\n\n`;
+        return {
+            content: [{ type: "text", text: note + formatFunctionDoc(fn) }],
+        };
+    }
+    if (byAlias.length > 1) {
+        const lines = [];
+        lines.push(`"${name}" is an ambiguous display alias used by ${byAlias.length} functions. Call \`get_function_doc\` again with the canonical name of the one you want:`);
+        lines.push("");
+        for (const fn of byAlias) {
+            lines.push(formatFunctionSummary(fn));
+            lines.push(`  \`${fn.signature}\``);
         }
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+    // No exact match. Try fuzzy substring match across name + displayName.
+    const matches = storefrontData.functions.filter((f) => f.name.toLowerCase().includes(nameLower) ||
+        (f.displayName && f.displayName.toLowerCase().includes(nameLower)));
+    if (matches.length > 0) {
+        const suggestions = matches.slice(0, 5).map((f) => {
+            const alias = f.displayName && f.displayName !== f.name ? ` (alias: ${f.displayName})` : "";
+            return `  - ${f.name}${alias}`;
+        });
         return {
-            content: [{ type: "text", text: `Function "${name}" not found. Use \`list_functions()\` to see all available functions.` }],
+            content: [
+                {
+                    type: "text",
+                    text: `Function "${name}" not found. Did you mean:\n${suggestions.join("\n")}`,
+                },
+            ],
         };
     }
-    return { content: [{ type: "text", text: formatFunctionDoc(fn) }] };
+    return {
+        content: [{ type: "text", text: `Function "${name}" not found. Use \`list_functions()\` to see all available functions.` }],
+    };
 });
 // Tool: list_functions
 server.tool("list_functions", "List storefront API functions. Without a `category`, returns category names + counts so you can drill in. With a `category`, returns one-line summaries for that category. Use `limit`/`offset` to paginate.", {
@@ -974,7 +2328,7 @@ server.tool("get_prop_types", "Get all available ikas.config.json prop types wit
 const sectionTemplateKeys = sectionTemplateNames.length > 0
     ? sectionTemplateNames
     : null;
-server.tool("get_section_template", "Get the root files of a starter section template (index.tsx, types.ts, styles.css, ikas-config-snippet.json). Returns ONLY the section's root files plus the NAMES of any children, components, sub-components, utilities, and hooks — their files are NOT included by default. To view one item's full implementation, call `get_section_child(section, name, kind)` where kind is 'children' (default), 'components', or 'sub-components'. To bundle subtrees inline, pass `include`. Call `list_section_types()` for available section types. Use the API patterns shown — create your own JSX structure, CSS class names, and visual design.", {
+server.tool("get_section_template", "Get the root files of a starter section template (index.tsx, types.ts, styles.css, ikas-config-snippet.json). Returns ONLY the section's root files plus the NAMES of any children, components, sub-components, utilities, and hooks — their files are NOT included by default. To view one item's full implementation, call `get_section_child(section, name, kind)` where kind is 'children' (default), 'components', or 'sub-components'. To bundle subtrees inline, pass `include`. Call `list_section_types()` for available section types. Use the API patterns shown — create your own JSX structure, CSS class names, and visual design. **Container sections** (Header, Footer, ProductDetail, etc.) host child components via a `COMPONENT_LIST` slot — the response emits a complete multi-step Setup Recipe (create children → capture ids → wire `filteredComponentIds` via `config update-prop`). Follow all steps; the parent alone produces an empty section.", {
     sectionType: z
         .string()
         .describe("The section type (call `list_section_types()` for valid values)"),
@@ -1016,11 +2370,19 @@ server.tool("get_section_template", "Get the root files of a starter section tem
     }
     const normalizedType = normalizeName(sectionType);
     if (!sectionTemplateNames.includes(normalizedType)) {
+        const suggestions = suggestClosestNames(normalizedType, sectionTemplateNames);
+        let suggestionText = "";
+        if (suggestions.length === 1) {
+            suggestionText = ` Did you mean "${suggestions[0]}"?`;
+        }
+        else if (suggestions.length > 1) {
+            suggestionText = ` Did you mean one of: ${suggestions.map((s) => `"${s}"`).join(", ")}?`;
+        }
         return {
             content: [
                 {
                     type: "text",
-                    text: `Unknown section type "${sectionType}". Call \`list_section_types()\` to see all ${sectionTemplateNames.length} valid types.`,
+                    text: `Unknown section type "${sectionType}".${suggestionText} Call \`list_section_types()\` to see all ${sectionTemplateNames.length} valid types.`,
                 },
             ],
         };
@@ -1049,6 +2411,18 @@ server.tool("get_section_template", "Get the root files of a starter section tem
         `## ${bundle.title} — API Integration Pattern Reference`,
         "",
     ];
+    // Detect container-section pattern (COMPONENT_LIST with `<id-of-X>` placeholders).
+    // Surface this BEFORE every other warning so the LLM cannot miss the wiring requirement.
+    // The full recipe (commands, captured-id placeholders, update-prop call) is appended near
+    // the end of the response in the existing recipe-builder block.
+    {
+        const snippetStrForBanner = bundle.rootFiles["ikas-config-snippet.json"];
+        if (snippetStrForBanner && /<id-of-[A-Za-z0-9_]+>/.test(snippetStrForBanner)) {
+            const childMatches = Array.from(snippetStrForBanner.matchAll(/<id-of-([A-Za-z0-9_]+)>/g));
+            const uniqueChildren = Array.from(new Set(childMatches.map((m) => m[1])));
+            parts.push(`> 🔧 **CONTAINER SECTION — required wiring.** This template hosts ${uniqueChildren.length} child component${uniqueChildren.length === 1 ? "" : "s"} (${uniqueChildren.map((n) => `\`${n}\``).join(", ")}) via a \`COMPONENT_LIST\` slot. Creating the parent alone produces an empty, unusable section. **You MUST follow the full Setup Recipe below**: create each child → capture its \`componentId\` → wire them into the parent's \`filteredComponentIds\` with \`config update-prop\`. Component ids are opaque random strings (e.g. \`7ojrigep-Eml9n5sN3i\`) — they cannot be derived from names, and the CLI rejects unknown ids.`, "");
+        }
+    }
     if (anyOutstandingSubtree) {
         parts.push("> **PARTIAL TEMPLATE — NOT A COMPLETE IMPLEMENTATION.** The files below are the section's root files only. The section also ships with child components, local components, and/or shared sub-components whose files are **not included** in this response. To view one's full implementation, call `get_section_child(section, name, kind)` for each item you need (kind = `children`, `components`, or `sub-components`). The root `index.tsx` alone is not a complete reference — its imports resolve to files that live in those subtrees.", "");
     }
@@ -1117,7 +2491,10 @@ server.tool("get_section_template", "Get the root files of a starter section tem
     renderInlineSubtree("children", bundle.childContents);
     renderInlineSubtree("components", bundle.componentContents);
     renderInlineSubtree("sub-components", bundle.subComponentContents);
-    // Generate a ready-to-run CLI command from the config snippet
+    // Generate a ready-to-run CLI recipe from the config snippet. If the parent's
+    // filteredComponentIds reference `<id-of-X>` placeholders, expand into a
+    // multi-step recipe (create children → create parent → wire filteredComponentIds)
+    // so the LLM cannot skip the wiring step.
     const configSnippetStr = bundle.rootFiles["ikas-config-snippet.json"];
     if (configSnippetStr) {
         try {
@@ -1125,26 +2502,102 @@ server.tool("get_section_template", "Get the root files of a starter section tem
             const compName = configSnippet.name || normalizedType;
             const compType = configSnippet.type || "section";
             const propsArr = configSnippet.props || [];
-            let cliCommand = `npx ikas-component config add-component --name "${compName}" --type ${compType}`;
-            if (configSnippet.isHeader)
-                cliCommand += " --isHeader";
-            if (configSnippet.isFooter)
-                cliCommand += " --isFooter";
-            if (propsArr.length > 0) {
-                const propsJson = JSON.stringify(propsArr.map((p) => {
-                    const prop = {
-                        name: p.name,
-                        type: p.type,
-                    };
-                    if (p.displayName)
-                        prop.displayName = p.displayName;
-                    if (p.required)
-                        prop.required = true;
-                    return prop;
-                }));
-                cliCommand += ` --props '${propsJson}'`;
+            // Strip filteredComponentIds for the parent's add-component call (wired
+            // separately below). Preserve name/type/displayName/required so the LLM gets the prop shape.
+            const parentPropsForAdd = propsArr.map((p) => {
+                const out = { name: p.name, type: p.type };
+                if (p.displayName)
+                    out.displayName = p.displayName;
+                if (p.required)
+                    out.required = true;
+                return out;
+            });
+            const placeholderRe = /^<id-of-(.+)>$/;
+            const slotPlans = [];
+            const allChildNames = new Set();
+            for (const p of propsArr) {
+                if ((p.type === "COMPONENT_LIST" || p.type === "COMPONENT") &&
+                    Array.isArray(p.filteredComponentIds)) {
+                    const childNames = [];
+                    for (const entry of p.filteredComponentIds) {
+                        const m = typeof entry === "string" && entry.match(placeholderRe);
+                        if (m) {
+                            childNames.push(m[1]);
+                            allChildNames.add(m[1]);
+                        }
+                    }
+                    if (childNames.length > 0) {
+                        slotPlans.push({ propName: p.name, childNames });
+                    }
+                }
+            }
+            const childPlans = [];
+            for (const childName of allChildNames) {
+                const childSnippetPath = path.join(SECTION_TEMPLATES_DIR, normalizedType, "children", childName, "ikas-config-snippet.json");
+                let propsJson = "[]";
+                let hasTemplate = false;
+                if (fs.existsSync(childSnippetPath)) {
+                    hasTemplate = true;
+                    try {
+                        const childSnippet = JSON.parse(fs.readFileSync(childSnippetPath, "utf-8"));
+                        const childProps = (childSnippet.props || []).map((p) => {
+                            const out = { name: p.name, type: p.type };
+                            if (p.displayName)
+                                out.displayName = p.displayName;
+                            if (p.required)
+                                out.required = true;
+                            return out;
+                        });
+                        propsJson = JSON.stringify(childProps);
+                    }
+                    catch {
+                        // fall through with []
+                    }
+                }
+                childPlans.push({ name: childName, propsJson, hasTemplate });
+            }
+            const baseFlags = (configSnippet.isHeader ? " --isHeader" : "") +
+                (configSnippet.isFooter ? " --isFooter" : "");
+            const parentPropsJsonStr = parentPropsForAdd.length > 0
+                ? ` --props '${JSON.stringify(parentPropsForAdd)}'`
+                : "";
+            if (slotPlans.length > 0) {
+                parts.push("---", "");
+                parts.push(`### Setup Recipe (run in order — ${childPlans.length} child component${childPlans.length === 1 ? "" : "s"} + 1 parent + wiring)`);
+                parts.push("");
+                parts.push(`> ⚠️ **This section is a CONTAINER.** It hosts child components via ${slotPlans.length === 1 ? "a COMPONENT_LIST slot" : "COMPONENT_LIST slots"} (\`${slotPlans.map((s) => s.propName).join("`, `")}\`). Creating the parent alone is **not enough** — you MUST also create the child components and wire their opaque ids into the parent's \`filteredComponentIds\`. Skipping the wiring leaves the slot empty and the section unusable.`, "");
+                parts.push("**Step 1 — Create each child component, and capture its `componentId` from the JSON response:**");
+                parts.push("", "```bash");
+                for (const ch of childPlans) {
+                    parts.push(`npx ikas-component config add-component --name "${ch.name}" --type component --props '${ch.propsJson}'`);
+                    parts.push(`# → { "success": true, "componentId": "<capture as ${ch.name.toUpperCase()}_ID>", ... }`);
+                    if (!ch.hasTemplate) {
+                        parts.push(`# (no children/${ch.name}/ template in this section bundle — \`--props '[]'\` is a stub; add real props for ${ch.name} as needed)`);
+                    }
+                }
+                parts.push("```", "");
+                parts.push("**Step 2 — Create the parent section (without `filteredComponentIds` yet — those are wired in Step 3):**");
+                parts.push("", "```bash");
+                parts.push(`npx ikas-component config add-component --name "${compName}" --type ${compType}${baseFlags}${parentPropsJsonStr}`);
+                parts.push("```", "");
+                parts.push("**Step 3 — Wire each slot to its allowed children using the ids captured in Step 1:**");
+                parts.push("", "```bash");
+                for (const slot of slotPlans) {
+                    const idsArr = slot.childNames.map((n) => `<${n.toUpperCase()}_ID>`);
+                    parts.push(`npx ikas-component config update-prop --component "${compName}" --prop ${slot.propName} \\`);
+                    parts.push(`  --filteredComponentIds '${JSON.stringify(idsArr)}'`);
+                }
+                parts.push("```", "");
+                parts.push("Replace each `<X_ID>` placeholder above with the real `componentId` from the corresponding Step 1 response (or look ids up with `config list`). The CLI rejects unknown ids with a structured error — there is no silent failure mode.");
+                parts.push("");
+                parts.push("**Do NOT manually create or edit `types.ts`** — the CLI commands above regenerate it automatically.");
+                parts.push("");
+            }
+            else {
+                // No child slots — single-step parent command (preserves previous behaviour)
+                const cliCommand = `npx ikas-component config add-component --name "${compName}" --type ${compType}${baseFlags}${parentPropsJsonStr}`;
+                parts.push("---", "", "### CLI Command (run this first)", "", "```bash", cliCommand, "```", "", "**Do NOT manually create or edit `types.ts`** — the CLI command above generates it automatically.", "");
             }
-            parts.push("---", "", "### CLI Command (run this first)", "", "```bash", cliCommand, "```", "", "**Do NOT manually create or edit `types.ts`** — the CLI command above generates it automatically.", "");
         }
         catch {
             // ignore parse errors
@@ -1325,6 +2778,243 @@ server.tool("list_section_types", "List all available `get_section_template` sec
     lines.push("", "Call `get_section_template(sectionType)` to fetch one.");
     return { content: [{ type: "text", text: lines.join("\n") }] };
 });
+// --- Migration tools ---
+// Tool: analyze_old_theme
+server.tool("analyze_old_theme", "Analyze an old ikas storefront theme.json and produce a structured migration report. Shows all components, custom data definitions, prop type breakdown, and migration recommendations. Use this as the first step when converting an old theme.", { theme_json: z.string().describe("The raw JSON content of the old theme.json file") }, async ({ theme_json }) => {
+    try {
+        const parsed = JSON.parse(theme_json);
+        const analysis = analyzeOldTheme(parsed);
+        return { content: [{ type: "text", text: analysis }] };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: `Error parsing theme.json: ${err instanceof Error ? err.message : String(err)}. Make sure you're passing valid JSON.` }],
+        };
+    }
+});
+// Tool: get_migration_guide
+const migrationTopicAliases = {
+    "overview": "migration-overview",
+    "migrate": "migration-overview",
+    "custom": "custom-data-conversion",
+    "custom-data": "custom-data-conversion",
+    "customdata": "custom-data-conversion",
+    "dynamic-list": "custom-data-conversion",
+    "component-list": "custom-data-conversion",
+    "slider": "prop-type-mapping",
+    "props": "prop-type-mapping",
+    "prop-mapping": "prop-type-mapping",
+    "types": "prop-type-mapping",
+    "react": "react-to-preact",
+    "preact": "react-to-preact",
+    "observer": "react-to-preact",
+    "libraries": "library-replacements",
+    "swiper": "library-replacements",
+    "headlessui": "library-replacements",
+    "tailwind": "library-replacements",
+    "tailwindcss": "library-replacements",
+    "recharts": "library-replacements",
+    "marquee": "library-replacements",
+    "imports": "storefront-import-mapping",
+    "storefront": "storefront-import-mapping",
+    "bp-storefront": "storefront-import-mapping",
+    "theme-json": "theme-json-anatomy",
+    "anatomy": "theme-json-anatomy",
+    "decompose": "component-decomposition-strategy",
+    "decomposition": "component-decomposition-strategy",
+    "strategy": "component-decomposition-strategy",
+    "project": "complete-project-generation",
+    "generate": "complete-project-generation",
+    "generation": "complete-project-generation",
+    "settings": "settings-conversion",
+    "colors": "settings-conversion",
+    "fonts": "settings-conversion",
+    "find": "finding-new-system-equivalents",
+    "search": "finding-new-system-equivalents",
+    "discover": "finding-new-system-equivalents",
+    "equivalent": "finding-new-system-equivalents",
+    "equivalents": "finding-new-system-equivalents",
+    "replacement": "finding-new-system-equivalents",
+};
+const migrationTopicKeys = migrationData
+    ? Object.keys(migrationData.topics)
+    : [];
+server.tool("get_migration_guide", `Get a migration guide for converting old ikas themes to the new code-component system. **Start with \`get_migration_guide("iterative-workflow")\` if you're new to this MCP** — it explains the MCP-vs-LLM responsibility split and the four phases.${migrationTopicKeys.length > 0 ? ` Available topics: ${migrationTopicKeys.join(", ")}. Also supports aliases like "custom", "slider", "react", "libraries", "imports", "settings".` : ""} Call with topic "list" to see all available topics.`, { topic: z.string().describe("Migration topic key, alias, or 'list' to see all topics") }, async ({ topic }) => {
+    if (!migrationData) {
+        return { content: [{ type: "text", text: "Migration data not available. Ensure data/migration.json exists." }] };
+    }
+    if (topic.toLowerCase() === "list") {
+        const available = Object.entries(migrationData.topics)
+            .map(([key, t]) => `- \`${key}\` — ${t.title}: ${t.description}`)
+            .join("\n");
+        return { content: [{ type: "text", text: `## Available Migration Topics\n\n${available}` }] };
+    }
+    const topicLower = topic.toLowerCase().replace(/\s+/g, "-");
+    const resolvedTopic = migrationTopicAliases[topicLower] || topicLower;
+    if (migrationData.topics[resolvedTopic]) {
+        const t = migrationData.topics[resolvedTopic];
+        return { content: [{ type: "text", text: `## ${t.title}\n\n${t.content}` }] };
+    }
+    // Try original key
+    if (resolvedTopic !== topicLower && migrationData.topics[topicLower]) {
+        const t = migrationData.topics[topicLower];
+        return { content: [{ type: "text", text: `## ${t.title}\n\n${t.content}` }] };
+    }
+    // Keyword search
+    const matches = searchMigrationTopics(topic);
+    if (matches.length > 0) {
+        const best = matches[0];
+        return { content: [{ type: "text", text: `## ${best.topic.title}\n\n${best.topic.content}` }] };
+    }
+    const available = Object.entries(migrationData.topics)
+        .map(([key, t]) => `  - \`${key}\` - ${t.title}`)
+        .join("\n");
+    return {
+        content: [{ type: "text", text: `Migration topic "${topic}" not found. Available topics:\n${available}` }],
+    };
+});
+// Tool: get_migration_example
+server.tool("get_migration_example", `Get a concrete before/after migration example showing how to convert an old theme component to the new code-component system.${migrationExampleNames.length > 0 ? ` Available examples: ${migrationExampleNames.join(", ")}.` : ""} Call with example "list" to see all examples.`, { example: z.string().describe("Example name or 'list' to see all examples") }, async ({ example }) => {
+    if (example.toLowerCase() === "list") {
+        if (migrationExampleNames.length === 0) {
+            return { content: [{ type: "text", text: "No migration examples available." }] };
+        }
+        const list = migrationExampleNames.map((name) => {
+            const ex = loadMigrationExample(name);
+            return ex ? `- \`${name}\` — ${ex.title}: ${ex.description}` : `- \`${name}\``;
+        }).join("\n");
+        return { content: [{ type: "text", text: `## Available Migration Examples\n\n${list}` }] };
+    }
+    const exampleLower = example.toLowerCase();
+    let exName = migrationExampleNames.find((n) => n === exampleLower);
+    if (!exName) {
+        exName = migrationExampleNames.find((n) => n.includes(exampleLower) || exampleLower.includes(n));
+    }
+    if (!exName) {
+        const available = migrationExampleNames.join(", ");
+        return {
+            content: [{ type: "text", text: `Migration example "${example}" not found. Available: ${available}` }],
+        };
+    }
+    const ex = loadMigrationExample(exName);
+    if (!ex) {
+        return { content: [{ type: "text", text: `Failed to load migration example "${exName}".` }] };
+    }
+    const parts = [
+        `## ${ex.title}`,
+        "",
+        ex.description,
+        "",
+    ];
+    for (const [filename, content] of Object.entries(ex.files)) {
+        const ext = filename.split(".").pop() || "text";
+        const lang = ext === "tsx" || ext === "ts"
+            ? "typescript"
+            : ext === "css"
+                ? "css"
+                : ext === "json"
+                    ? "json"
+                    : "text";
+        const isAfter = filename.startsWith("after-");
+        const isBefore = filename.startsWith("before-");
+        const label = isBefore ? "📋 BEFORE" : isAfter ? "✅ AFTER" : "";
+        parts.push(`### ${label} ${filename}`, "", `\`\`\`${lang}`, content, "```", "");
+    }
+    return { content: [{ type: "text", text: parts.join("\n") }] };
+});
+// Tool: plan_migration
+server.tool("plan_migration", "Generate the **initial** migration plan and (when `project_root` is provided) write it to <project_root>/MIGRATION.md. **This is the only time the MCP writes that file.** From here, you own it: tick checkboxes as you finish work, log custom-data decisions, scan the old source for atomic components (Button, Input, Card, etc.) that theme.json doesn't see, and append them to MIGRATION.md yourself. theme.json is incomplete by design — the MCP can only describe what's listed there. Pass `theme_json_path` for large themes (raw `theme_json` string is supported for backward compat but fails on real-world sizes).", {
+    theme_json: z.string().optional().describe("Raw JSON content of the old theme.json. EITHER this OR theme_json_path is required (not both). For real themes use theme_json_path — raw strings exceed tool/context limits at production sizes."),
+    theme_json_path: z.string().optional().describe("Absolute path to the old theme.json file on disk. Preferred for any real-world theme."),
+    project_name: z.string().optional().describe("Target new project name, used to prefix migration-tracking IDs (default: 'my-theme')"),
+    old_source_dir: z.string().optional().describe("Absolute path to the old project's src/ directory. When provided, the tool scans .tsx files to detect shared sub-components used across 3+ components. This scan is partial — atomic components used by only 1-2 sections will be missed and must be added by the LLM."),
+    project_root: z.string().optional().describe("Absolute path to the new project root. When provided, the MCP writes MIGRATION.md to <project_root>/MIGRATION.md and returns a short summary instead of the full markdown body."),
+    overwrite: z.boolean().optional().describe("If MIGRATION.md already exists at <project_root>/MIGRATION.md and is non-empty, refuse the write unless this is true. Default: false."),
+}, async ({ theme_json, theme_json_path, project_name, old_source_dir, project_root, overwrite }) => {
+    try {
+        const parsed = resolveThemeJson(theme_json, theme_json_path);
+        const projectName = project_name || "my-theme";
+        const plan = generateMigrationPlan(parsed, projectName, old_source_dir);
+        if (!project_root) {
+            return { content: [{ type: "text", text: plan }] };
+        }
+        // Write MIGRATION.md to project_root
+        if (!path.isAbsolute(project_root)) {
+            throw new Error(`project_root must be absolute: ${project_root}`);
+        }
+        if (!fs.existsSync(project_root)) {
+            throw new Error(`project_root not found: ${project_root}`);
+        }
+        if (!fs.statSync(project_root).isDirectory()) {
+            throw new Error(`project_root is not a directory: ${project_root}`);
+        }
+        const targetPath = path.join(project_root, "MIGRATION.md");
+        if (fs.existsSync(targetPath)) {
+            const existing = fs.readFileSync(targetPath, "utf-8").trim();
+            if (existing.length > 0 && !overwrite) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Refusing to overwrite existing non-empty MIGRATION.md at ${targetPath}. ` +
+                                `Pass overwrite: true to replace it, or delete the file first. ` +
+                                `If you intended to RESUME an in-progress migration, do not call plan_migration again — read the existing MIGRATION.md and continue from the first unchecked item.`,
+                        },
+                    ],
+                };
+            }
+        }
+        writeFileAtomic(targetPath, plan);
+        const components = parsed.components || [];
+        const customData = parsed.customData || [];
+        const cssVarCount = parsed.settings?.colors?.length || 0;
+        const fontCount = parsed.settings?.fontFamily?.name ? 1 : 0;
+        const customDataCount = customData.filter((cd) => cd.isRoot).length;
+        const sectionCount = components.length;
+        const summary = [
+            `Wrote initial migration plan to ${targetPath}`,
+            "",
+            `**Summary:**`,
+            `- Sections to migrate: ${sectionCount}`,
+            `- CSS variables: ${cssVarCount}`,
+            `- Fonts: ${fontCount}`,
+            `- Custom data types (deferred decisions, not pre-migrated): ${customDataCount}`,
+            "",
+            `**Next steps for the LLM:**`,
+            `1. Read \`${targetPath}\` start-to-finish. The "READ THIS FIRST" preamble explains your responsibilities.`,
+            `2. Scan the old source directory (\`${old_source_dir || "<old-src>"}\`) for atomic components (Button, Input, Card, icons, etc.) NOT referenced from theme.json. Add them to \`## Source Code Analysis\` in MIGRATION.md.`,
+            `3. Start the Foundation work (CSS variables, fonts, shared sub-components).`,
+            `4. For each section, call \`get_section_migration_plan({theme_json_path, section_name, project_name})\`. The MCP will tell you which props need enum-vs-component decisions.`,
+            `5. Log every custom-data decision in \`## Custom Data Decisions\`. Tick checkboxes as you finish.`,
+        ].join("\n");
+        return { content: [{ type: "text", text: summary }] };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }],
+        };
+    }
+});
+// Tool: get_section_migration_plan
+server.tool("get_section_migration_plan", "Returns concrete CLI commands and prop conversions for one section. For each prop that references a customData type, you'll see a 'Decide: enum or component?' callout — log your decision in MIGRATION.md under `## Custom Data Decisions`. Pass `theme_json_path` for large themes.", {
+    theme_json: z.string().optional().describe("Raw JSON content of the old theme.json. EITHER this OR theme_json_path is required (not both)."),
+    theme_json_path: z.string().optional().describe("Absolute path to the old theme.json file on disk. Preferred for any real-world theme."),
+    section_name: z.string().describe("Old component name (e.g. 'Navbar', 'ProductGrid') or dir name, OR the new section ID (e.g. 'my-theme-navbar')"),
+    project_name: z.string().optional().describe("Target new project name (must match what was used in plan_migration). Default: 'my-theme'"),
+    old_source_dir: z.string().optional().describe("Absolute path to old src/ directory (used to output exact source file paths to read)"),
+}, async ({ theme_json, theme_json_path, section_name, project_name, old_source_dir }) => {
+    try {
+        const parsed = resolveThemeJson(theme_json, theme_json_path);
+        const projectName = project_name || "my-theme";
+        const plan = generateSectionMigrationPlan(parsed, section_name, projectName, old_source_dir);
+        return { content: [{ type: "text", text: plan }] };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }],
+        };
+    }
+});
 // --- Start server ---
 async function main() {
     const transport = new StdioServerTransport();