@ikas/code-components-mcp 1.4.0-beta.1 → 1.4.0-beta.2

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 ---
@@ -50,7 +50,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 +167,1087 @@ 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`);
+    parts.push("");
+    parts.push(`**Generated:** ${new Date().toISOString().slice(0, 10)}`);
+    parts.push(`**Project ID:** \`${projectName}\``);
+    parts.push(`**Source:** ${components.length} old components, ${customData.filter(cd => cd.isRoot).length} custom data types, ${(theme.pages || []).length} pages`);
+    parts.push("");
+    parts.push(`This file is the **source of truth** for the migration. All sessions must read it before starting work.`);
+    parts.push("");
+    parts.push(`## Status Legend`);
+    parts.push(`- \`[ ]\` Not started`);
+    parts.push(`- \`[~]\` In progress`);
+    parts.push(`- \`[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
+    const enumCustomData = customData.filter(cd => cd.type === "ENUM" && cd.isRoot);
+    if (enumCustomData.length > 0) {
+        parts.push(`### Custom Enums (run these BEFORE any \`config add-component\`)`);
+        parts.push("");
+        for (const cd of enumCustomData) {
+            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;
+            }, {});
+            const optionsStr = JSON.stringify(options);
+            parts.push(`- [ ] **${enumName}**`);
+            parts.push(`  \`\`\`bash`);
+            parts.push(`  npx ikas-component config add-enum --name "${enumName}" --options '${optionsStr}'`);
+            parts.push(`  \`\`\``);
+            parts.push(`  Save the returned \`enumId\` and update this file with: \`enumId: <id>\``);
+        }
+        parts.push("");
+    }
+    // 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("");
+    }
+    // Sections queue
+    parts.push(`## Sections`);
+    parts.push("");
+    parts.push(`Canonical component IDs are listed below — **use these exactly** when running \`config add-component\` and in \`filteredComponentIds\`. Do not change them mid-migration.`);
+    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 childKebab = toKebabCase(childName);
+                            const childId = `${projectName}-${childKebab}`;
+                            const fields = (itemObj.nestedData || []).map((f) => f.key || f.name || "?").slice(0, 8);
+                            children.push({ propName: p.name || "?", childId, 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.childId}\` (\`${ch.childName}\`) — for prop \`${ch.propName}\` — fields: ${ch.fields.join(", ")}`);
+                }
+            }
+        }
+        parts.push("");
+    }
+    // Known Environmental Issues (agents fill in during work)
+    parts.push(`## Known Environmental Issues`);
+    parts.push("");
+    parts.push(`_Agents working on this migration: 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("");
+    // Usage section
+    parts.push(`## Per-Section Usage`);
+    parts.push("");
+    parts.push(`Once the Foundation is complete, for each section above:`);
+    parts.push("");
+    parts.push(`1. Find the first unchecked \`[ ]\` section (start with Simple).`);
+    parts.push(`2. Call \`get_section_migration_plan(theme_json, "<old section name>", "${projectName}")\`.`);
+    parts.push(`3. Read the old source files listed in the plan.`);
+    parts.push(`4. Run the CLI commands in the plan (they create parent + children with auto-generated types.ts).`);
+    parts.push(`5. Write \`index.tsx\` and \`styles.css\` using the patterns in the plan. DO NOT manually edit types.ts.`);
+    parts.push(`6. Mark the section \`[x]\` when it builds cleanly. Append a short note to the **Session Log** below (what libraries you replaced, any ad-hoc props you had to add, the actual folder name the CLI created if different from the name you passed).`);
+    parts.push("");
+    // Session Log — agents append notes here
+    parts.push(`## Session Log`);
+    parts.push("");
+    parts.push(`_Each agent: append a bullet after completing work. Format: \`- [YYYY-MM-DD] <section-id>: <brief note>\`. This is how future sessions learn about decisions not encoded in the plan structure._`);
+    parts.push("");
+    parts.push(`_After completing Foundation, also record which sub-components were built and which were skipped, e.g.:_`);
+    parts.push(`<!-- \`- [2026-04-15] Foundation: built Input, SubmitButton, Modal, SectionHeader, StarRating. Skipped: GoogleCaptcha (needs investigation), BlogCard, Pagination (low priority).\` -->`);
+    parts.push(`<!-- \`- [2026-04-15] ${projectName}-footer: swapped react-hot-toast for inline status text; newsletter uses form-model pattern (getNewsletterSubscriptionForm). CLI created folder as "Footer/" as expected.\` -->`);
+    parts.push("");
+    // Cross-references
+    parts.push(`## Cross-References`);
+    parts.push("");
+    parts.push(`Essential MCP tools to call during migration:`);
+    parts.push("");
+    parts.push(`- \`get_migration_guide("iterative-workflow")\` — full protocol for resumable migrations`);
+    parts.push(`- \`get_migration_guide("component-renderer-limitations")\` — critical constraints when using COMPONENT_LIST`);
+    parts.push(`- \`get_migration_guide("prop-runtime-shapes")\` — \`.data\` vs \`.links\`, \`.variant\` vs \`.product\`, etc.`);
+    parts.push(`- \`get_migration_guide("link-prop-decision-guide")\` — LINK vs LIST_OF_LINK vs COMPONENT_LIST`);
+    parts.push(`- \`get_migration_guide("library-replacements")\` — swiper, headlessui, tailwind, etc.`);
+    parts.push(`- \`get_migration_guide("react-to-preact")\` — observer rules, imports, IkasSlider removal`);
+    parts.push(`- \`get_framework_guide("component-renderer-patterns")\` — full IkasComponentRenderer usage`);
+    parts.push(`- \`get_framework_guide("common-pitfalls")\` — general gotchas`);
+    parts.push(`- \`get_framework_guide("navigation-patterns")\` — Router.navigate, Router.navigateToPage`);
+    parts.push(`- \`get_model_guide("<TypeName>")\` — IkasCart, IkasProduct, IkasCustomer shapes`);
+    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 ID:** \`${sectionId}\``);
+    parts.push(`**New section name:** \`${sectionPascal}\``);
+    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 childKebab = toKebabCase(childName);
+                    const childId = `${projectName}-${childKebab}`;
+                    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,
+                        childId,
+                        childName,
+                        childPropsJson: childProps,
+                        customDataName: cd.name || "unnamed",
+                    });
+                    newType = "COMPONENT_LIST";
+                    notes = `Was CUSTOM → ${cd.type} of ${itemObj?.typescriptName || "object"}. Create child component \`${childId}\`.`;
+                    const prop = {
+                        name: newName,
+                        displayName: p.displayName || newName,
+                        type: "COMPONENT_LIST",
+                        filteredComponentIds: [childId],
+                    };
+                    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("");
+    // 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 childId (same shape may be referenced by multiple parent props)
+    const uniqueChildren = new Map();
+    for (const ch of children) {
+        const existing = uniqueChildren.get(ch.childId);
+        if (existing) {
+            existing.usedByProps.push(ch.propName);
+        }
+        else {
+            uniqueChildren.set(ch.childId, { 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("");
+        for (const { child: ch, usedByProps } of uniqueChildren.values()) {
+            parts.push(`### \`${ch.childId}\` (\`${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(`\`\`\``);
+            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\`.`);
+    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 from a previous migration (reuse its ID in \`filteredComponentIds\`). If not, create it as a registered component.`);
+    }
+    // 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
+    parts.push(`## ${nextStep + 1}. Relevant Guides (call these for details)`);
+    parts.push("");
+    parts.push(`- \`get_migration_guide("react-to-preact")\` — code conversion patterns`);
+    parts.push(`- \`get_migration_guide("library-replacements")\` — library → vanilla Preact patterns`);
+    parts.push(`- \`get_migration_guide("prop-runtime-shapes")\` — exact runtime shapes (.data vs .links)`);
+    if (children.length > 0) {
+        parts.push(`- \`get_migration_guide("component-renderer-limitations")\` — critical COMPONENT_LIST constraints`);
+        parts.push(`- \`get_framework_guide("component-renderer-patterns")\` — full IkasComponentRenderer usage`);
+        parts.push(`- \`get_migration_example("custom-dynamic-list-to-component-list")\` — concrete example`);
+    }
+    if (target.isHeader || target.isFooter) {
+        parts.push(`- \`get_framework_guide("header-footer-patterns")\` — header/footer specifics`);
+    }
+    parts.push(`- \`get_framework_guide("common-pitfalls")\` — observer rules, common mistakes`);
+    parts.push("");
+    // Completion
+    parts.push(`## ${nextStep + 2}. Mark Complete`);
+    parts.push("");
+    parts.push(`Once the section builds cleanly with \`npx ikas-component build\`:`);
+    parts.push(`1. Edit \`MIGRATION.md\` at the project root`);
+    parts.push(`2. Change the checkbox for \`${sectionId}\` from \`[ ]\` to \`[x]\``);
+    parts.push(`3. Also mark each child component as \`[x]\``);
+    parts.push(`4. Append an entry to the **Session Log** section of \`MIGRATION.md\` noting: libraries replaced, any props added beyond the generated plan, the actual folder name the CLI created (in case it differs from the name you passed — e.g., \`FAQ\` → \`Faq/\`), and any other decisions a future agent should know.`);
+    parts.push("");
+    return parts.join("\n");
+}
 // --- Search helpers ---
 function matchScore(text, query) {
     const lower = text.toLowerCase();
@@ -334,10 +1423,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 +1453,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") }] };
@@ -1325,6 +2423,187 @@ 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.${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 a complete, resumable migration plan (MIGRATION.md) for converting an old ikas theme to the new code-component system. The LLM should save the returned markdown to <new-project-root>/MIGRATION.md as the source of truth for the entire migration. This is the FIRST tool to call for any multi-section (>5 sections) theme migration. Output includes: extracted CSS variables, font setup, custom enums with CLI commands, shared sub-components (when old_source_dir provided), and an ordered section queue grouped by complexity with canonical component IDs.", {
+    theme_json: z.string().describe("Raw JSON content of the old theme.json"),
+    project_name: z.string().optional().describe("Target new project name, used to prefix component 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."),
+}, async ({ theme_json, project_name, old_source_dir }) => {
+    try {
+        const parsed = JSON.parse(theme_json);
+        const projectName = project_name || "my-theme";
+        const plan = generateMigrationPlan(parsed, 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)}. Make sure theme_json is valid JSON.` }],
+        };
+    }
+});
+// Tool: get_section_migration_plan
+server.tool("get_section_migration_plan", "Get a concrete, actionable migration plan for a single section/component from the old theme. Returns: old source file paths to read, a prop-by-prop conversion table, CLI commands to create children and parent components (with auto-generated types.ts), library replacement hints, and cross-references to relevant framework/migration guides. Use this tool once per section in Phase C of the iterative workflow. Call after `plan_migration` has generated MIGRATION.md.", {
+    theme_json: z.string().describe("Raw JSON content of the old theme.json"),
+    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, section_name, project_name, old_source_dir }) => {
+    try {
+        const parsed = JSON.parse(theme_json);
+        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)}. Make sure theme_json is valid JSON.` }],
+        };
+    }
+});
 // --- Start server ---
 async function main() {
     const transport = new StdioServerTransport();