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

package/dist/index.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { execFile } from "child_process";
 import * as fs from "fs";
+import * as os from "os";
 import * as path from "path";
 import { fileURLToPath } from "url";
 import { z } from "zod";
@@ -15,6 +17,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 = [
@@ -43,9 +98,16 @@ function loadStorefrontTypes() {
     }
     return null;
 }
-const SUBTREE_KINDS = ["children", "components", "sub-components"];
+const SUBTREE_KINDS = [
+    "children",
+    "components",
+    "sub-components",
+];
 function normalizeName(value) {
-    return value.trim().replace(/^`+|`+$/g, "").trim();
+    return value
+        .trim()
+        .replace(/^`+|`+$/g, "")
+        .trim();
 }
 const storefrontData = loadStorefrontData();
 const frameworkData = loadJsonFile("../data/framework.json");
@@ -206,7 +268,11 @@ function searchMigrationTopics(query) {
         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 };
+        return {
+            key,
+            topic,
+            score: titleScore + descScore + contentScore + tagScore,
+        };
     })
         .filter((item) => item.score > 0)
         .sort((a, b) => b.score - a.score);
@@ -233,7 +299,7 @@ function analyzeOldTheme(themeJson) {
     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(`- **Custom Data Definitions:** ${customData.filter((cd) => cd.isRoot).length}`);
     parts.push(`- **Prop Groups:** ${groups.length}`);
     // Component analysis
     parts.push(`\n## Components (${components.length})\n`);
@@ -272,7 +338,11 @@ function analyzeOldTheme(themeJson) {
         const typesSummary = Object.entries(propTypeCounts)
             .map(([t, c]) => `${t}×${c}`)
             .join(", ");
-        const headerFooter = comp.isHeader ? " [HEADER]" : comp.isFooter ? " [FOOTER]" : "";
+        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`);
@@ -287,7 +357,7 @@ function analyzeOldTheme(themeJson) {
         parts.push("");
     }
     // Custom data analysis
-    const rootCustomData = customData.filter(cd => cd.isRoot);
+    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) {
@@ -297,7 +367,9 @@ function analyzeOldTheme(themeJson) {
                 const describeNested = (items, indent) => {
                     const lines = [];
                     for (const item of items) {
-                        const key = item.key ? `\`${item.key}\`` : item.typescriptName || item.name || "unnamed";
+                        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 + "  "));
@@ -309,7 +381,7 @@ function analyzeOldTheme(themeJson) {
                 parts.push(...describeNested(cd.nestedData, "  "));
             }
             if (cd.enumOptions && cd.enumOptions.length > 0) {
-                parts.push(`- **Enum options:** ${cd.enumOptions.map(o => `"${o.value}"`).join(", ")}`);
+                parts.push(`- **Enum options:** ${cd.enumOptions.map((o) => `"${o.value}"`).join(", ")}`);
             }
             // Find which components reference this customData
             const referencingComponents = [];
@@ -391,7 +463,9 @@ function scanSharedSubcomponents(sourceDir) {
     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("."))
+                if (entry.name === "node_modules" ||
+                    entry.name === "__generated__" ||
+                    entry.name.startsWith("."))
                     continue;
                 walk(path.join(dir, entry.name));
             }
@@ -426,10 +500,14 @@ function scanSharedSubcomponents(sourceDir) {
             if (!importPath.startsWith("."))
                 continue;
             // Skip imports of generated types, utils, hooks
-            if (importPath.includes("__generated__") || importPath.includes("/utils") || importPath.includes("/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 !== "..");
+            const pathSegments = importPath
+                .split("/")
+                .filter((s) => s && s !== "." && s !== "..");
             if (pathSegments.length === 0)
                 continue;
             const lastSegment = pathSegments[pathSegments.length - 1];
@@ -440,7 +518,10 @@ function scanSharedSubcomponents(sourceDir) {
                 continue;
             seenInFile.add(key);
             if (!importUsage.has(key)) {
-                importUsage.set(key, { usingComponents: new Set(), rawImportPath: importPath });
+                importUsage.set(key, {
+                    usingComponents: new Set(),
+                    rawImportPath: importPath,
+                });
             }
             importUsage.get(key).usingComponents.add(componentDir);
         }
@@ -449,7 +530,7 @@ function scanSharedSubcomponents(sourceDir) {
     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);
+        const users = [...usingComponents].filter((c) => c !== name);
         if (users.length >= 3) {
             shared.push({ name, usedBy: users.sort(), importPaths: [rawImportPath] });
         }
@@ -466,7 +547,7 @@ function toKebabCase(s) {
 }
 function classifyComplexity(comp, customDataMap) {
     const props = comp.props || [];
-    const customCount = props.filter(p => p.type === "CUSTOM").length;
+    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)
@@ -477,7 +558,9 @@ function classifyComplexity(comp, customDataMap) {
             if (cd?.nestedData) {
                 const hasNested = (items) => {
                     for (const item of items) {
-                        if (item.type === "DYNAMIC_LIST" || item.type === "STATIC_LIST" || item.customDataId)
+                        if (item.type === "DYNAMIC_LIST" ||
+                            item.type === "STATIC_LIST" ||
+                            item.customDataId)
                             return true;
                         if (item.nestedData && hasNested(item.nestedData))
                             return true;
@@ -506,18 +589,23 @@ function generateMigrationPlan(theme, projectName, oldSourceDir) {
     }
     const sharedSubs = oldSourceDir ? scanSharedSubcomponents(oldSourceDir) : [];
     const parts = [];
-    parts.push(`# Theme Migration Plan`);
+    parts.push(`# Theme Migration Plan — \`${projectName}\``);
     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(`**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(`> ## 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("");
@@ -537,27 +625,9 @@ function generateMigrationPlan(theme, projectName, oldSourceDir) {
         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("");
-    }
+    // (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/\`)`);
@@ -581,10 +651,61 @@ function generateMigrationPlan(theme, projectName, oldSourceDir) {
         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(`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(`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: [],
@@ -610,7 +731,11 @@ function generateMigrationPlan(theme, projectName, oldSourceDir) {
             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 headerFooter = comp.isHeader
+                ? " **[HEADER]**"
+                : comp.isFooter
+                    ? " **[FOOTER]**"
+                    : "";
             const propCount = (comp.props || []).length;
             // Detect children from CUSTOM DYNAMIC_LIST props
             const children = [];
@@ -620,11 +745,14 @@ function generateMigrationPlan(theme, projectName, oldSourceDir) {
                     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 });
+                            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 });
                         }
                     }
                 }
@@ -634,65 +762,73 @@ function generateMigrationPlan(theme, projectName, oldSourceDir) {
             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(`    - [ ] \`${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`);
+    // Source Code Analysis — placeholder for the LLM to fill in
+    parts.push(`## Source Code Analysis`);
     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(`> **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(`- [ ] _(none recorded yet)_`);
+    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("");
-    // Usage section
-    parts.push(`## Per-Section Usage`);
+    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(`Once the Foundation is complete, for each section above:`);
+    parts.push(`_Record any non-component build/TS errors here so future sessions don't waste time diagnosing them._`);
     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(`- [ ] _(none recorded yet)_`);
     parts.push("");
-    // Session Log — agents append notes here
-    parts.push(`## Session Log`);
+    // Notes — append-only log for decisions not captured elsewhere
+    parts.push(`## Notes`);
     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(`_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(`_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(`<!-- Example: \`- [2026-04-15] ${projectName}-footer: swapped react-hot-toast for inline status text; CLI created Footer/ as expected\` -->`);
     parts.push("");
-    // Cross-references
+    // 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(`Essential MCP tools to call during migration:`);
+    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(`- \`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(`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",
+    "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;
@@ -711,7 +847,8 @@ function scanSectionSource(componentDir, propNames) {
     // 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"))) {
+            if (entry.isFile() &&
+                (entry.name.endsWith(".tsx") || entry.name.endsWith(".ts"))) {
                 result.sourceFiles.push(path.join(componentDir, entry.name));
             }
         }
@@ -728,7 +865,18 @@ function scanSectionSource(componentDir, propNames) {
     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"]);
+    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 {
@@ -742,7 +890,7 @@ function scanSectionSource(componentDir, propNames) {
         while ((m = importRegex.exec(content)) !== null) {
             const p = m[1];
             if (p.startsWith(".")) {
-                const segs = p.split("/").filter(s => s && s !== "." && s !== "..");
+                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);
@@ -750,7 +898,9 @@ function scanSectionSource(componentDir, propNames) {
             }
             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];
+                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);
                 }
@@ -813,7 +963,10 @@ function scanSectionSource(componentDir, propNames) {
             }
         }
     }
-    result.importedSubComponents = [...subCompSet.entries()].map(([name, p]) => ({ name, path: p }));
+    result.importedSubComponents = [...subCompSet.entries()].map(([name, p]) => ({
+        name,
+        path: p,
+    }));
     result.importedLibraries = [...libSet].sort();
     result.importedUnknownLibraries = [...unknownLibSet].sort();
     result.reactPackageUsage = [...reactSet].sort();
@@ -829,34 +982,45 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
             customDataMap.set(cd.id, cd);
     }
     // Find the component — try match by dir, displayName, id, or new-id
-    const target = components.find(c => {
+    const target = components.find((c) => {
         if (!c)
             return false;
-        if (c.dir === sectionName || c.displayName === sectionName || c.id === sectionName)
+        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(", ");
+        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("");
+    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)
+    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}\``);
+    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)
@@ -895,7 +1059,7 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
         }
         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).`);
+            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("");
@@ -941,7 +1105,11 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
         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" };
+            const prop = {
+                name: newName,
+                displayName: p.displayName || newName,
+                type: "NUMBER",
+            };
             if (p.isRequired)
                 prop.required = true;
             parentPropsJson.push(prop);
@@ -949,7 +1117,11 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
         else if (oldType === "PRODUCT_DETAIL") {
             newType = "PRODUCT";
             notes = "Renamed — PRODUCT_DETAIL → PRODUCT";
-            const prop = { name: newName, displayName: p.displayName || newName, type: "PRODUCT" };
+            const prop = {
+                name: newName,
+                displayName: p.displayName || newName,
+                type: "PRODUCT",
+            };
             if (p.isRequired)
                 prop.required = true;
             parentPropsJson.push(prop);
@@ -960,9 +1132,10 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
                 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 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 || [])) {
@@ -973,11 +1146,18 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
                             fType = "NUMBER";
                         else if (fType === "PRODUCT_DETAIL")
                             fType = "PRODUCT";
-                        else if (fType === "CUSTOM" || fType === "DYNAMIC_LIST" || fType === "STATIC_LIST" || fType === "OBJECT") {
+                        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 };
+                        const prop = {
+                            name: f.key,
+                            displayName: f.name || f.key,
+                            type: fType,
+                        };
                         if (f.isRequired)
                             prop.required = true;
                         childProps.push(prop);
@@ -989,26 +1169,29 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
                     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" });
+                            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.`;
+                            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}\`.`;
+                    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: [childId],
+                        filteredComponentIds: [`<id-of-${childName}>`],
                     };
                     parentPropsJson.push(prop);
                 }
@@ -1022,7 +1205,11 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
                             let fType = f.type;
                             if (fType === "SLIDER")
                                 fType = "NUMBER";
-                            const prop = { name: f.key, displayName: f.name || f.key, type: fType };
+                            const prop = {
+                                name: f.key,
+                                displayName: f.name || f.key,
+                                type: fType,
+                            };
                             if (f.isRequired)
                                 prop.required = true;
                             parentPropsJson.push(prop);
@@ -1037,7 +1224,8 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
                 }
                 else if (cd.type === "ENUM") {
                     newType = "ENUM";
-                    const enumName = cd.typescriptName || (cd.name ? cd.name.replace(/[^a-zA-Z0-9]/g, "") : "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;
@@ -1045,7 +1233,12 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
                     }, {});
                     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}>` };
+                    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);
@@ -1054,7 +1247,11 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
         }
         else {
             // Direct mapping
-            const prop = { name: newName, displayName: p.displayName || newName, type: newType };
+            const prop = {
+                name: newName,
+                displayName: p.displayName || newName,
+                type: newType,
+            };
             if (p.isRequired)
                 prop.required = true;
             parentPropsJson.push(prop);
@@ -1062,6 +1259,131 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
         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)`);
@@ -1074,15 +1396,18 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
         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)
+    // 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.childId);
+        const existing = uniqueChildren.get(ch.childName);
         if (existing) {
             existing.usedByProps.push(ch.propName);
         }
         else {
-            uniqueChildren.set(ch.childId, { child: ch, usedByProps: [ch.propName] });
+            uniqueChildren.set(ch.childName, {
+                child: ch,
+                usedByProps: [ch.propName],
+            });
         }
     }
     if (uniqueChildren.size > 0) {
@@ -1090,17 +1415,19 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
         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.childId}\` (\`${ch.childName}\`)`);
+            parts.push(`### \`${ch.childName}\``);
             const propsLabel = usedByProps.length > 1
-                ? `Used by parent props: ${usedByProps.map(p => `\`${p}\``).join(", ")} (${usedByProps.length}×)`
+                ? `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("");
         }
@@ -1116,6 +1443,10 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
     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;
@@ -1132,15 +1463,18 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
     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.`);
+        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");
+    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(`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");
@@ -1167,9 +1501,22 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
         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 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));
+    const isLikelyFormPage = formKeywords.some((kw) => lowerDir.includes(kw));
     if (isLikelyFormPage) {
         parts.push("");
         parts.push(`### Form Page Pattern`);
@@ -1198,7 +1545,9 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
         // Fallback heuristic only when source scan unavailable
         const heuristicLibs = [];
         const lowerName = oldName.toLowerCase();
-        if (lowerName.includes("slider") || lowerName.includes("carousel") || lowerName.includes("banner")) {
+        if (lowerName.includes("slider") ||
+            lowerName.includes("carousel") ||
+            lowerName.includes("banner")) {
             heuristicLibs.push("swiper");
         }
         if (lowerName.includes("marquee"))
@@ -1207,7 +1556,9 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
             heuristicLibs.push("react-player");
         if (lowerName.includes("chart"))
             heuristicLibs.push("recharts");
-        if (lowerName.includes("star") || lowerName.includes("rating") || lowerName.includes("review"))
+        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)`);
@@ -1221,30 +1572,19 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
             parts.push("");
         }
     }
-    // Relevant guides
-    parts.push(`## ${nextStep + 1}. Relevant Guides (call these for details)`);
+    // 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("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_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(`- \`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(`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");
 }
@@ -1270,18 +1610,81 @@ 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);
+        }
+        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 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)
             ? 2
             : 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 };
+        const typeScore = fn.parameterTypes?.some((t) => matchScore(t, query) > 0)
+            ? 8
+            : 0;
+        return {
+            fn,
+            score: nameScore +
+                displayNameScore +
+                descScore +
+                catScore +
+                paramScore +
+                sigScore +
+                typeScore,
+        };
     })
         .filter((item) => item.score > 0)
         .sort((a, b) => b.score - a.score);
@@ -1294,7 +1697,11 @@ function searchFrameworkTopics(query) {
         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 };
+        return {
+            key,
+            topic,
+            score: titleScore + descScore + contentScore + tagScore,
+        };
     })
         .filter((item) => item.score > 0)
         .sort((a, b) => b.score - a.score);
@@ -1309,7 +1716,9 @@ function searchTypes(query) {
         const propScore = td.properties?.some((p) => matchScore(p.name, query) > 0 || matchScore(p.type, query) > 0)
             ? 4
             : 0;
-        const enumScore = td.enumValues?.some((v) => matchScore(v, query) > 0) ? 4 : 0;
+        const enumScore = td.enumValues?.some((v) => matchScore(v, query) > 0)
+            ? 4
+            : 0;
         return { td, score: nameScore + domainScore + propScore + enumScore };
     })
         .filter((item) => item.score > 0)
@@ -1351,8 +1760,12 @@ function formatFunctionDoc(fn) {
     return lines.join("\n");
 }
 function formatFunctionSummary(fn) {
-    const desc = fn.description ? fn.description.split(".")[0] + "." : "No description.";
-    const alias = fn.displayName && fn.displayName !== fn.name ? ` (alias: ${fn.displayName})` : "";
+    const desc = fn.description
+        ? fn.description.split(".")[0] + "."
+        : "No description.";
+    const alias = fn.displayName && fn.displayName !== fn.name
+        ? ` (alias: ${fn.displayName})`
+        : "";
     return `- \`${fn.name}\`${alias} - ${desc}`;
 }
 function formatTypeDefinition(td, opts = {}) {
@@ -1393,7 +1806,9 @@ function formatTypeDefinition(td, opts = {}) {
             const fn = storefrontData.functions.find((f) => f.name === fnName);
             if (fn) {
                 const desc = fn.description ? fn.description.split(".")[0] + "." : "";
-                const alias = fn.displayName && fn.displayName !== fn.name ? ` (alias: ${fn.displayName})` : "";
+                const alias = fn.displayName && fn.displayName !== fn.name
+                    ? ` (alias: ${fn.displayName})`
+                    : "";
                 lines.push(`- **\`${fn.name}\`**${alias} — ${desc}`);
                 lines.push(`  \`${fn.signature}\``);
             }
@@ -1402,7 +1817,9 @@ function formatTypeDefinition(td, opts = {}) {
             }
         }
         lines.push("");
-        lines.push("Use `get_functions_for_type(\"" + td.name + "\")` for full documentation of these functions.");
+        lines.push('Use `get_functions_for_type("' +
+            td.name +
+            '")` for full documentation of these functions.');
     }
     return lines.join("\n");
 }
@@ -1420,7 +1837,13 @@ const server = new McpServer({
     name: "ikas-code-components",
     version: "0.1.0",
 }, {
-    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.",
+    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.\n\n" +
+        "Live-editor actions (require `ikas-component dev` running with the editor connected): `list_editor_pages` → page ids; `list_imported_sections` → imported component ids; `import_section` → import a built component; `add_section_to_page` → place a section on a page; `list_page_sections` → the sections already placed on a page, each with its per-placement `elementId`, current `propValues`, and blueprint `props`; `update_section_prop` → change a single prop value of a placed section; `upload_image` → upload an image (file or URL) and get an image id to use in an IMAGE prop value.\n\n" +
+        "To CHANGE/EDIT a prop value (text, color, boolean, number, etc.) of a section that is already on a page, this IS supported: call `list_page_sections(page_id)` to get the placement `elementId` and the prop names/ids, then `update_section_prop(page_id, element_id, prop_name|prop_id, value)`. Do not assume prop editing is unavailable.\n\n" +
+        "TWO DISTINCT JOBS — do not confuse them, and do not jump to writing code for the second one:\n" +
+        "(A) DEFINING props / authoring a component = changing which props a component HAS. This edits the component source/config (types.ts via `ikas-component config add-prop`/`add-component`, JSX in index.tsx, etc.) and requires a rebuild. Use this ONLY when the needed prop does not exist yet, or the user explicitly asks to build/modify the component's code or prop schema.\n" +
+        "(B) SETTING prop VALUES / filling content = giving values to props that ALREADY exist on a section placed on a page. This is pure data entry via `list_page_sections` + `update_section_prop` (and `upload_image` for images). It writes NO code and needs NO rebuild.\n" +
+        "When the user says things like 'fill this section', 'set the heading/title/text/image/link', 'populate', 'change the content/value', or 'enter this data', that is JOB (B): use `update_section_prop`. First call `list_page_sections` and check the existing `props` — if the prop is already there (it usually is), just set its value. Only fall back to JOB (A) if the required prop genuinely does not exist in that section's `props`. Writing a new component or adding a prop to fill in a value the section already supports is the wrong move.",
 });
 // Tool: search_docs
 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 }) => {
@@ -1461,39 +1884,79 @@ server.tool("search_docs", "Search across all ikas storefront API docs, framewor
         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) {
+    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") }] };
 });
 // 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 }) => {
+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.", {
@@ -1542,7 +2005,7 @@ server.tool("list_functions", "List storefront API functions. Without a `categor
         if (uncategorized > 0) {
             lines.push(`- \`Other\` (${uncategorized})`);
         }
-        lines.push("", "Call `list_functions(category: \"<name>\")` to see one-line summaries for a category.");
+        lines.push("", 'Call `list_functions(category: "<name>")` to see one-line summaries for a category.');
         return { content: [{ type: "text", text: lines.join("\n") }] };
     }
     const catLower = category.toLowerCase();
@@ -1574,7 +2037,11 @@ server.tool("list_functions", "List storefront API functions. Without a `categor
     return { content: [{ type: "text", text: parts.join("\n") }] };
 });
 // Tool: get_code_example
-server.tool("get_code_example", "Get an API usage reference for a specific task. Shows correct function calls, imports, and data-handling patterns from a real production theme. The JSX layout and CSS are illustrative only — create your own original visual design. Call `list_examples()` to see available example IDs.", { task: z.string().describe("Task description or example ID (call `list_examples()` for the full list)") }, async ({ task }) => {
+server.tool("get_code_example", "Get an API usage reference for a specific task. Shows correct function calls, imports, and data-handling patterns from a real production theme. The JSX layout and CSS are illustrative only — create your own original visual design. Call `list_examples()` to see available example IDs.", {
+    task: z
+        .string()
+        .describe("Task description or example ID (call `list_examples()` for the full list)"),
+}, async ({ task }) => {
     const taskLower = task.toLowerCase();
     // Try exact ID match first
     let example = storefrontData.codeExamples.find((e) => e.id === taskLower);
@@ -1594,7 +2061,9 @@ server.tool("get_code_example", "Get an API usage reference for a specific task.
         }
     }
     if (!example) {
-        const available = storefrontData.codeExamples.map((e) => `  - \`${e.id}\` - ${e.title}`).join("\n");
+        const available = storefrontData.codeExamples
+            .map((e) => `  - \`${e.id}\` - ${e.title}`)
+            .join("\n");
         return {
             content: [
                 {
@@ -1617,14 +2086,24 @@ server.tool("get_code_example", "Get an API usage reference for a specific task.
     if (example.files && example.files.length > 0) {
         for (const file of example.files) {
             const ext = file.filename.split(".").pop() || "text";
-            const lang = ext === "tsx" || ext === "ts" ? "typescript" : ext === "css" ? "css" : ext === "json" ? "json" : "text";
+            const lang = ext === "tsx" || ext === "ts"
+                ? "typescript"
+                : ext === "css"
+                    ? "css"
+                    : ext === "json"
+                        ? "json"
+                        : "text";
             // Add inline originality comments to CSS and TSX files
             let content = file.content;
             if (ext === "css") {
-                content = "/* EXAMPLE STYLING — create your own original CSS with different class names and design */\n" + content;
+                content =
+                    "/* EXAMPLE STYLING — create your own original CSS with different class names and design */\n" +
+                        content;
             }
             else if (ext === "tsx") {
-                content = "// EXAMPLE COMPONENT — use the API patterns but create your own JSX structure and layout\n" + content;
+                content =
+                    "// EXAMPLE COMPONENT — use the API patterns but create your own JSX structure and layout\n" +
+                        content;
             }
             parts.push(`### ${file.filename}`, "", `\`\`\`${lang}`, content, "```", "");
         }
@@ -1638,63 +2117,88 @@ server.tool("get_code_example", "Get an API usage reference for a specific task.
     return { content: [{ type: "text", text: parts.join("\n") }] };
 });
 // Tool: get_framework_guide
-server.tool("get_framework_guide", "Get a framework guide on a specific topic (e.g. 'ai-workflow', 'common-pitfalls', 'prop-types', 'css-scoping', 'form-handling'). Call `list_topics()` to see all available topic keys.", { topic: z.string().describe("Topic key or keyword (call `list_topics()` for the full list)") }, async ({ topic }) => {
+server.tool("get_framework_guide", "Get a framework guide on a specific topic (e.g. 'ai-workflow', 'common-pitfalls', 'prop-types', 'css-scoping', 'form-handling'). Call `list_topics()` to see all available topic keys.", {
+    topic: z
+        .string()
+        .describe("Topic key or keyword (call `list_topics()` for the full list)"),
+}, async ({ topic }) => {
     const topicLower = topic.toLowerCase().replace(/\s+/g, "-");
     // Alias mapping for common alternative topic names
     const topicAliases = {
         "form-handling": "form-patterns",
-        "forms": "form-patterns",
+        forms: "form-patterns",
         "data-fetching": "async-data-patterns",
-        "async": "async-data-patterns",
-        "loading": "async-data-patterns",
+        async: "async-data-patterns",
+        loading: "async-data-patterns",
         "sub-components": "sub-component-patterns",
-        "subcomponents": "sub-component-patterns",
-        "routing": "navigation-patterns",
-        "router": "navigation-patterns",
-        "observer": "component-structure",
-        "reactivity": "component-structure",
-        "pitfalls": "common-pitfalls",
-        "gotchas": "common-pitfalls",
-        "mistakes": "common-pitfalls",
-        "header": "header-footer-patterns",
-        "footer": "header-footer-patterns",
-        "blog": "blog-patterns",
-        "cart": "cart-patterns",
-        "account": "account-patterns",
+        subcomponents: "sub-component-patterns",
+        routing: "navigation-patterns",
+        router: "navigation-patterns",
+        observer: "component-structure",
+        reactivity: "component-structure",
+        pitfalls: "common-pitfalls",
+        gotchas: "common-pitfalls",
+        mistakes: "common-pitfalls",
+        header: "header-footer-patterns",
+        footer: "header-footer-patterns",
+        blog: "blog-patterns",
+        cart: "cart-patterns",
+        account: "account-patterns",
         "product-detail": "product-detail-patterns",
         "product-list": "product-list-patterns",
-        "filtering": "product-list-patterns",
-        "reviews": "review-patterns",
-        "slider": "slider-overlay-patterns",
-        "overlay": "slider-overlay-patterns",
-        "modal": "slider-overlay-patterns",
-        "architecture": "real-world-architecture",
-        "theme": "real-world-architecture",
+        filtering: "product-list-patterns",
+        reviews: "review-patterns",
+        slider: "slider-overlay-patterns",
+        overlay: "slider-overlay-patterns",
+        modal: "slider-overlay-patterns",
+        architecture: "real-world-architecture",
+        theme: "real-world-architecture",
         "global-styles": "global-css",
-        "global": "global-css",
+        global: "global-css",
         "css-variables": "global-css",
         "custom-properties": "global-css",
     };
     const resolvedTopic = topicAliases[topicLower] || topicLower;
     // Topics that involve MobX store reads get a reminder about root reactivity
     const storeTopics = new Set([
-        "product-detail-patterns", "product-list-patterns", "cart-patterns",
-        "account-patterns", "header-footer-patterns", "review-patterns",
-        "blog-patterns", "form-handling", "async-data-patterns",
-        "component-structure", "imports",
+        "product-detail-patterns",
+        "product-list-patterns",
+        "cart-patterns",
+        "account-patterns",
+        "header-footer-patterns",
+        "review-patterns",
+        "blog-patterns",
+        "form-handling",
+        "async-data-patterns",
+        "component-structure",
+        "imports",
     ]);
     const observerReminder = "> **IMPORTANT: Do NOT use `observer()` on root component exports.** The ikas runtime wraps root renders in MobX `autorun()`, making them automatically reactive. All store reads (`cartStore`, `customerStore`, etc.) in root components are tracked automatically. Only use `observer()` on extracted sub-components.\n\n";
     // Try exact key match (with alias resolution)
     if (frameworkData.topics[resolvedTopic]) {
         const t = frameworkData.topics[resolvedTopic];
         const prefix = storeTopics.has(resolvedTopic) ? observerReminder : "";
-        return { content: [{ type: "text", text: `## ${t.title}\n\n${prefix}${t.content}` }] };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `## ${t.title}\n\n${prefix}${t.content}`,
+                },
+            ],
+        };
     }
     // Try original topic key (without alias) in case it's a direct key
     if (resolvedTopic !== topicLower && frameworkData.topics[topicLower]) {
         const t = frameworkData.topics[topicLower];
         const prefix = storeTopics.has(topicLower) ? observerReminder : "";
-        return { content: [{ type: "text", text: `## ${t.title}\n\n${prefix}${t.content}` }] };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `## ${t.title}\n\n${prefix}${t.content}`,
+                },
+            ],
+        };
     }
     // Try keyword search
     const matches = searchFrameworkTopics(topic);
@@ -1702,7 +2206,12 @@ server.tool("get_framework_guide", "Get a framework guide on a specific topic (e
         const best = matches[0];
         const prefix = storeTopics.has(best.key) ? observerReminder : "";
         return {
-            content: [{ type: "text", text: `## ${best.topic.title}\n\n${prefix}${best.topic.content}` }],
+            content: [
+                {
+                    type: "text",
+                    text: `## ${best.topic.title}\n\n${prefix}${best.topic.content}`,
+                },
+            ],
         };
     }
     const available = Object.entries(frameworkData.topics)
@@ -1718,16 +2227,27 @@ server.tool("get_framework_guide", "Get a framework guide on a specific topic (e
     };
 });
 // Tool: get_type_definition
-server.tool("get_type_definition", "Get the full definition of a storefront type or enum by name (e.g. 'IkasProduct', 'IkasOrderStatus'). Shows all properties with types, extends, or enum values.", { name: z.string().describe("Type or enum name (e.g. 'IkasProduct', 'IkasOrderStatus')") }, async ({ name }) => {
+server.tool("get_type_definition", "Get the full definition of a storefront type or enum by name (e.g. 'IkasProduct', 'IkasOrderStatus'). Shows all properties with types, extends, or enum values.", {
+    name: z
+        .string()
+        .describe("Type or enum name (e.g. 'IkasProduct', 'IkasOrderStatus')"),
+}, async ({ name }) => {
     if (!typesData) {
         return {
-            content: [{ type: "text", text: "Type data not available. Run 'npm run docs:generate' in storefront-docs first." }],
+            content: [
+                {
+                    type: "text",
+                    text: "Type data not available. Run 'npm run docs:generate' in storefront-docs first.",
+                },
+            ],
         };
     }
     const nameLower = name.toLowerCase();
     const td = typesData.types.find((t) => t.name.toLowerCase() === nameLower);
     if (td) {
-        return { content: [{ type: "text", text: formatTypeDefinition(td) }] };
+        return {
+            content: [{ type: "text", text: formatTypeDefinition(td) }],
+        };
     }
     // Fuzzy match
     const matches = typesData.types.filter((t) => t.name.toLowerCase().includes(nameLower));
@@ -1743,14 +2263,28 @@ server.tool("get_type_definition", "Get the full definition of a storefront type
         };
     }
     return {
-        content: [{ type: "text", text: `Type "${name}" not found. Use \`list_types()\` to see all available types.` }],
+        content: [
+            {
+                type: "text",
+                text: `Type "${name}" not found. Use \`list_types()\` to see all available types.`,
+            },
+        ],
     };
 });
 // Tool: get_functions_for_type
-server.tool("get_functions_for_type", "Get full documentation for all utility functions that operate on a given storefront type. For example, get_functions_for_type('IkasImage') returns getSrc, getDefaultSrc, getThumbnailSrc, createMediaSrcset with full signatures, descriptions, and examples.", { typeName: z.string().describe("Type name (e.g. 'IkasImage', 'IkasProduct', 'IkasOrder')") }, async ({ typeName }) => {
+server.tool("get_functions_for_type", "Get full documentation for all utility functions that operate on a given storefront type. For example, get_functions_for_type('IkasImage') returns getSrc, getDefaultSrc, getThumbnailSrc, createMediaSrcset with full signatures, descriptions, and examples.", {
+    typeName: z
+        .string()
+        .describe("Type name (e.g. 'IkasImage', 'IkasProduct', 'IkasOrder')"),
+}, async ({ typeName }) => {
     if (!typesData) {
         return {
-            content: [{ type: "text", text: "Type data not available. Run 'npm run docs:generate' in storefront-docs first." }],
+            content: [
+                {
+                    type: "text",
+                    text: "Type data not available. Run 'npm run docs:generate' in storefront-docs first.",
+                },
+            ],
         };
     }
     const nameLower = typeName.toLowerCase();
@@ -1770,7 +2304,12 @@ server.tool("get_functions_for_type", "Get full documentation for all utility fu
             };
         }
         return {
-            content: [{ type: "text", text: `Type "${typeName}" not found. Use \`list_types()\` to see all available types.` }],
+            content: [
+                {
+                    type: "text",
+                    text: `Type "${typeName}" not found. Use \`list_types()\` to see all available types.`,
+                },
+            ],
         };
     }
     if (!td.relatedFunctions || td.relatedFunctions.length === 0) {
@@ -1801,7 +2340,10 @@ server.tool("get_functions_for_type", "Get full documentation for all utility fu
 });
 // Tool: get_model_guide
 server.tool("get_model_guide", "Get an overview of a storefront model type. By default returns the type definition, related function names with one-line summaries, matching example titles/IDs, and related type summaries. Pass `mode: 'full'` to inline full function docs and example code.", {
-    model: z.string().optional().describe("Model type name (e.g. 'IkasImage', 'IkasProduct', 'IkasOrder')"),
+    model: z
+        .string()
+        .optional()
+        .describe("Model type name (e.g. 'IkasImage', 'IkasProduct', 'IkasOrder')"),
     name: z.string().optional().describe("Alias for 'model'"),
     mode: z
         .enum(["summary", "full"])
@@ -1812,12 +2354,22 @@ server.tool("get_model_guide", "Get an overview of a storefront model type. By d
     const model = modelParam || nameParam;
     if (!model) {
         return {
-            content: [{ type: "text", text: "Please provide a model name (e.g. 'IkasProduct', 'IkasOrder'). Use the 'model' or 'name' parameter." }],
+            content: [
+                {
+                    type: "text",
+                    text: "Please provide a model name (e.g. 'IkasProduct', 'IkasOrder'). Use the 'model' or 'name' parameter.",
+                },
+            ],
         };
     }
     if (!typesData) {
         return {
-            content: [{ type: "text", text: "Type data not available. Run 'npm run docs:generate' in storefront-docs first." }],
+            content: [
+                {
+                    type: "text",
+                    text: "Type data not available. Run 'npm run docs:generate' in storefront-docs first.",
+                },
+            ],
         };
     }
     const modelLower = model.toLowerCase();
@@ -1839,7 +2391,12 @@ server.tool("get_model_guide", "Get an overview of a storefront model type. By d
             };
         }
         return {
-            content: [{ type: "text", text: `Model "${model}" not found. Use \`list_types()\` to see all available types.` }],
+            content: [
+                {
+                    type: "text",
+                    text: `Model "${model}" not found. Use \`list_types()\` to see all available types.`,
+                },
+            ],
         };
     }
     const parts = [`# Model Guide: ${td.name}\n`];
@@ -1947,13 +2504,23 @@ server.tool("get_model_guide", "Get an overview of a storefront model type. By d
 server.tool("search_types", "Search storefront types and enums by keyword (e.g. 'price', 'address', 'status'). Returns top matches ranked by relevance.", { query: z.string().describe("Search keyword or phrase") }, async ({ query }) => {
     if (!typesData) {
         return {
-            content: [{ type: "text", text: "Type data not available. Run 'npm run docs:generate' in storefront-docs first." }],
+            content: [
+                {
+                    type: "text",
+                    text: "Type data not available. Run 'npm run docs:generate' in storefront-docs first.",
+                },
+            ],
         };
     }
     const results = searchTypes(query).slice(0, 15);
     if (results.length === 0) {
         return {
-            content: [{ type: "text", text: `No types found matching "${query}". Use \`list_types()\` to see all available types.` }],
+            content: [
+                {
+                    type: "text",
+                    text: `No types found matching "${query}". Use \`list_types()\` to see all available types.`,
+                },
+            ],
         };
     }
     const parts = [`## Type Search Results for "${query}"\n`];
@@ -2017,7 +2584,7 @@ server.tool("list_types", "List storefront types and enums. Use `domain` and/or
         for (const [d, count] of sorted) {
             lines.push(`- \`${d}\` (${count})`);
         }
-        lines.push("", "Call `list_types(domain: \"<name>\")` to see summaries for a domain.");
+        lines.push("", 'Call `list_types(domain: "<name>")` to see summaries for a domain.');
         return { content: [{ type: "text", text: lines.join("\n") }] };
     }
     const domainLower = domain.toLowerCase();
@@ -2056,15 +2623,25 @@ server.tool("list_types", "List storefront types and enums. Use `domain` and/or
     return { content: [{ type: "text", text: parts.join("\n") }] };
 });
 // Tool: get_prop_types
-server.tool("get_prop_types", "Get all available ikas.config.json prop types with descriptions, TypeScript types, and examples. Tip: Use `npx ikas-component config add-component --props '[...]'` to create a component with all props in one command, or `add-prop` to add props incrementally. NEVER manually edit types.ts — it is auto-generated by the CLI.", {}, async () => {
+server.tool("get_prop_types", "Get all available ikas.config.json prop types with descriptions, TypeScript types, and examples. NOTE: these are the TypeScript prop-definition types for authoring a component — they are NOT the runtime JSON value shapes you write via `update_section_prop` (e.g. a TEXT prop is typed `string` here but written as `{ \"value\": \"...\" }`, and an IMAGE is `IkasImage | null` here but written as `{ \"id\": \"...\" }`). For the value shapes to pass to `update_section_prop`, see that tool's description. Tip: Use `npx ikas-component config add-component --props '[...]'` to create a component with all props in one command, or `add-prop` to add props incrementally. NEVER manually edit types.ts — it is auto-generated by the CLI.", {}, async () => {
     const propTypesTopic = frameworkData.topics["prop-types"];
     if (propTypesTopic) {
         return {
-            content: [{ type: "text", text: `## ${propTypesTopic.title}\n\n${propTypesTopic.content}` }],
+            content: [
+                {
+                    type: "text",
+                    text: `## ${propTypesTopic.title}\n\n${propTypesTopic.content}`,
+                },
+            ],
         };
     }
     return {
-        content: [{ type: "text", text: "Prop types documentation not available." }],
+        content: [
+            {
+                type: "text",
+                text: "Prop types documentation not available.",
+            },
+        ],
     };
 });
 // Tool: get_section_template
@@ -2072,7 +2649,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)"),
@@ -2114,11 +2691,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.`,
                 },
             ],
         };
@@ -2147,6 +2732,19 @@ 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.", "");
     }
@@ -2215,7 +2813,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 {
@@ -2223,26 +2824,105 @@ 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
@@ -2259,10 +2939,7 @@ server.tool("get_section_child", "Fetch one item's files from a section's childr
         .string()
         .optional()
         .describe("The item name as listed in `get_section_template`'s response (Children/Components/Sub-components)"),
-    child: z
-        .string()
-        .optional()
-        .describe("Alias for `name`"),
+    child: z.string().optional().describe("Alias for `name`"),
     kind: z
         .enum(["children", "components", "sub-components"])
         .optional()
@@ -2425,7 +3102,11 @@ server.tool("list_section_types", "List all available `get_section_template` sec
 });
 // --- 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 }) => {
+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);
@@ -2433,102 +3114,162 @@ server.tool("analyze_old_theme", "Analyze an old ikas storefront theme.json and
     }
     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.` }],
+            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",
+    overview: "migration-overview",
+    migrate: "migration-overview",
+    custom: "custom-data-conversion",
     "custom-data": "custom-data-conversion",
-    "customdata": "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",
+    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",
+    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",
+    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 }) => {
+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." }] };
+        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}` }] };
+        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}` }] };
+        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}` }] };
+        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}` }] };
+        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}` }],
+        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 }) => {
+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." }] };
+            return {
+                content: [
+                    { type: "text", text: "No migration examples available." },
+                ],
+            };
         }
-        const list = migrationExampleNames.map((name) => {
+        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}` }] };
+            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);
@@ -2538,19 +3279,26 @@ server.tool("get_migration_example", `Get a concrete before/after migration exam
     if (!exName) {
         const available = migrationExampleNames.join(", ");
         return {
-            content: [{ type: "text", text: `Migration example "${example}" not found. Available: ${available}` }],
+            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}".` }] };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Failed to load migration example "${exName}".`,
+                },
+            ],
+        };
     }
-    const parts = [
-        `## ${ex.title}`,
-        "",
-        ex.description,
-        "",
-    ];
+    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"
@@ -2568,42 +3316,407 @@ server.tool("get_migration_example", `Get a concrete before/after migration exam
     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 }) => {
+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 = JSON.parse(theme_json);
+        const parsed = resolveThemeJson(theme_json, theme_json_path);
         const projectName = project_name || "my-theme";
         const plan = generateMigrationPlan(parsed, projectName, old_source_dir);
-        return { content: [{ type: "text", text: plan }] };
+        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)}. Make sure theme_json is valid JSON.` }],
+            content: [
+                {
+                    type: "text",
+                    text: `Error: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
         };
     }
 });
 // 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 }) => {
+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 = JSON.parse(theme_json);
+        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)}. Make sure theme_json is valid JSON.` }],
+            content: [
+                {
+                    type: "text",
+                    text: `Error: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
         };
     }
 });
+// =============================================================================
+// Editor-action tools — drive the connected editor over the dev server's WS
+// (port 5201) by shelling out to `ikas-component <cmd>`. The CLI is the
+// canonical implementation; these tools are thin advertisements for the LLM.
+// =============================================================================
+function resolveIkasComponentBinary(projectRoot) {
+    if (!path.isAbsolute(projectRoot)) {
+        throw new Error(`project_root must be absolute: ${projectRoot}`);
+    }
+    if (!fs.existsSync(projectRoot) || !fs.statSync(projectRoot).isDirectory()) {
+        throw new Error(`project_root is not a directory: ${projectRoot}`);
+    }
+    const binDir = path.join(projectRoot, "node_modules", ".bin");
+    const candidates = os.platform() === "win32"
+        ? ["ikas-component.cmd", "ikas-component.exe", "ikas-component"]
+        : ["ikas-component"];
+    for (const name of candidates) {
+        const full = path.join(binDir, name);
+        if (fs.existsSync(full))
+            return full;
+    }
+    throw new Error(`ikas-component CLI not found at ${binDir}. Run \`npm install\` (or \`pnpm install\`) in ${projectRoot} first.`);
+}
+async function runIkasComponentCli(projectRoot, args) {
+    const bin = resolveIkasComponentBinary(projectRoot);
+    return new Promise((resolve) => {
+        execFile(bin, args, { cwd: projectRoot, windowsHide: true }, (err, stdout, stderr) => {
+            const exitCode = err && typeof err.code === "number"
+                ? err.code
+                : err
+                    ? 1
+                    : 0;
+            resolve({
+                stdout: stdout?.toString() ?? "",
+                stderr: stderr?.toString() ?? "",
+                exitCode,
+            });
+        });
+    });
+}
+function parseCliJson(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed)
+        return null;
+    // CLI prints exactly one JSON object on stdout; if multiple lines appeared
+    // (e.g., warnings on stderr leaked), take the last non-empty line.
+    const last = trimmed
+        .split("\n")
+        .map((l) => l.trim())
+        .filter(Boolean)
+        .pop();
+    if (!last)
+        return null;
+    try {
+        return JSON.parse(last);
+    }
+    catch {
+        return null;
+    }
+}
+async function callEditorAction(projectRoot, args) {
+    try {
+        const { stdout, stderr, exitCode } = await runIkasComponentCli(projectRoot, args);
+        const parsed = parseCliJson(stdout);
+        if (parsed) {
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(parsed, null, 2) },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `CLI exited with code ${exitCode} and produced no parseable JSON.\n` +
+                        `stdout:\n${stdout || "(empty)"}\nstderr:\n${stderr || "(empty)"}`,
+                },
+            ],
+        };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+        };
+    }
+}
+//
+// Tool: list_editor_pages
+server.tool("list_editor_pages", "List pages in the connected editor's project. Returns id, name, pageType, slug for each page. Requires `ikas-component dev` to be running with the editor connected. Use the returned `id`s as the `pageId` argument to `add_section_to_page`.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project (where `node_modules/.bin/ikas-component` lives)."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, port }) => {
+    const args = ["list-pages", ...(port ? ["--port", String(port)] : [])];
+    return callEditorAction(project_root, args);
+});
+// Tool: list_imported_sections
+server.tool("list_imported_sections", "List section-type code components already imported into the editor's project (theme.codeComponents, filtered to type=section). Use to confirm a component is ready to be placed on a page. The component must be built (`ikas-component build`/`dev`) and imported (`import_section`) before it can be added to a page. The returned `id` is the editor's id for the imported component — normally identical to the id in `ikas.config.json`, but it can differ if the dev component was deleted and re-scaffolded after a previous import. Always use the `id` from this tool, not from `ikas.config.json`, when calling `add_section_to_page`.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, port }) => {
+    const args = [
+        "list-imported",
+        "--sections-only",
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: import_section
+server.tool("import_section", "Import a built section-type code component into the editor's project. This copies the compiled JS/CSS/props into `theme.codeComponents` and auto-creates the wrapper section needed to place it on a page. Idempotent: re-running updates the existing entry in place. Required before `add_section_to_page`. The component must have been built (`ikas-component build`/`dev`).", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    component_id: z
+        .string()
+        .describe("Component id from `ikas.config.json` (strict — no name resolution)."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, component_id, port }) => {
+    const args = [
+        "import",
+        "--id",
+        component_id,
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: add_section_to_page
+server.tool("add_section_to_page", 'Place an already-imported section-type code component on a page in the editor. Equivalent to right-clicking the section in the dev-components panel and choosing "Add to Page". Errors if the component is not imported, is not section-type, or the page id is unknown. Use `list_editor_pages` to discover page ids and `list_imported_sections` to discover component ids. After placing, change the section\'s prop values with `update_section_prop` (use `list_page_sections` to get the placement\'s `elementId` and prop names).', {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    component_id: z
+        .string()
+        .describe("Imported code component id from `list_imported_sections` — NOT the id in `ikas.config.json` (the two are usually the same but can diverge after a rescaffold)."),
+    page_id: z.string().describe("Target page id (from `list_editor_pages`)."),
+    index: z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe("Zero-based insertion index in the page; appends when omitted."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, component_id, page_id, index, port }) => {
+    const args = [
+        "add-to-page",
+        "--component-id",
+        component_id,
+        "--page-id",
+        page_id,
+        ...(typeof index === "number" ? ["--index", String(index)] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: list_page_sections
+server.tool("list_page_sections", "List the sections placed on a page. Each entry includes the per-placement `elementId` (the identity of THIS placement — there can be multiple placements of the same section), `sectionId`, `componentId`, `name`, the current `propValues`, and the blueprint `props` (each with `id`, `name`, `type`). Use the returned `elementId` plus a prop `id`/`name` with `update_section_prop` to change a prop value of that specific placement. Use `list_editor_pages` to discover page ids.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    page_id: z.string().describe("Target page id (from `list_editor_pages`)."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, page_id, port }) => {
+    const args = [
+        "list-page-sections",
+        "--page-id",
+        page_id,
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: update_section_prop
+server.tool("update_section_prop", 'Change a single prop value of a section placed on a page. This is the tool for FILLING/SETTING content (heading, text, image, link, etc.) on an existing section — it is pure data entry: it writes NO component code and needs NO rebuild. Do not author a new prop or component to set a value the section already supports; first check the section\'s existing `props` via `list_page_sections`. Target the specific placement by its `element_id` (from `list_page_sections`) and the prop by `prop_id` or `prop_name` (also from `list_page_sections`). `value` is the prop value object as stored by the editor — for scalar props it is wrapped as `{ "value": <scalar> }` (e.g. `{ "value": "Hello" }` for TEXT, `{ "value": true }` for BOOLEAN, `{ "value": 12 }` for NUMBER, `{ "value": "#FF0000" }` for COLOR, `{ "value": "<enum-key>" }` for ENUM). Richer object prop types use their own object shape and are NOT `{ "value": ... }`-wrapped: IMAGE/VIDEO/SVG = `{ "id": "<asset-id>", "altText"?: "<alt>", "isVideo"?: false }` (the `id` MUST reference an already-uploaded asset — call `upload_image` with a `file_path`/`image_url` to get one, or reuse an existing `id` from another section\'s `propValues`); LINK = a single link object `{ "id": "<unique-short-id>", "linkType": "PAGE"|"EXTERNAL"|"FILE", "label": "...", "openInNewTab"?: false, "subLinks": [] }` plus the target for its type — for PAGE add `"pageId"` AND `"pageType"` (both from `list_editor_pages`, e.g. pageType "INDEX"; for dynamic page types like PRODUCT/CATEGORY/BLOG also add the target `"itemId"`), for EXTERNAL add `"externalLink": "https://..."`. Examples: PAGE → `{ "id": "k3p9x", "linkType": "PAGE", "label": "Home", "pageId": "<page-id>", "pageType": "INDEX", "openInNewTab": false, "subLinks": [] }`; EXTERNAL → `{ "id": "m7q2z", "linkType": "EXTERNAL", "label": "Docs", "externalLink": "https://example.com", "openInNewTab": true, "subLinks": [] }`. LIST_OF_LINK = `{ "links": [ <link>, ... ] }` (each item is a link object as above). PRODUCT = `{ "productId": "...", "variantId"?: "..." }`. This SAME unwrapped shape applies whether the prop sits at section level OR nested inside a COMPONENT_LIST entry\'s `propValues` — there is no section-vs-nested difference. IMPORTANT: pass `value` as the parsed JSON object/array itself, NEVER as a JSON string (a stringified value is double-encoded and stored as a useless string). Values are validated server-side: a wrong shape (e.g. `{ "value": [...] }` for a COMPONENT_LIST, a `{ "value": ... }`-wrapped IMAGE, `componentId`+`props` instead of `codeComponentId`+`propValues`, or a missing entry `id`) is now REJECTED with an explanatory error instead of being silently stored. For any prop type you are unsure about, inspect the existing entry in `list_page_sections` `propValues` and match its exact shape. The change is applied with undo support.\n\n' +
+    'COMPONENT_LIST / COMPONENT props: the value is NOT wrapped in `{ "value": ... }`. A COMPONENT_LIST value is `{ "components": [ <entry>, ... ] }`; a single COMPONENT value is one `<entry>`. Each entry = `{ "id": "<unique-id>", "codeComponentId": "<child-id>" | "componentId": "<child-id>", "propValues": { "<childPropName>": <wrapped-value>, ... } }`. Rules: (1) `id` is a unique short alphanumeric string identifying THIS entry — generate a fresh one per new entry and NEVER reuse an existing entry\'s id. (2) Use `codeComponentId` for code components, `componentId` for built-in theme components. (3) `propValues` is keyed by the CHILD component\'s prop NAMES, each using the same scalar wrappers as above (nesting is recursive — a child may itself hold a COMPONENT_LIST). (4) `update_section_prop` REPLACES the whole prop value — there is NO partial/deep merge. ALWAYS send the COMPLETE, fully-nested value for the prop: every existing entry (with its id), every nested `propValues`, and every nested COMPONENT_LIST at every depth. To change anything (even one deeply-nested scalar, or to add/remove/reorder a child), READ-MODIFY-WRITE: take the current `{ "components": [...] }` from `list_page_sections`, edit it in place (preserving all other entries, ids, and nested structures), then send the ENTIRE updated object back. Sending only the changed part — a single entry, or a child without its siblings — wipes everything you omitted. (5) You can only add child component types the prop permits; the allowed set is the blueprint prop\'s `filteredComponentIds`, which for container sections (Header, Footer, ProductDetail, …) is wired at build/config time per the `get_section_template` setup recipe (`config update-prop`), not here.\n\n' +
+    'Example — a full COMPONENT_LIST `value` with two children, where the second child itself nests another COMPONENT_LIST (note: scalar leaves are `{ "value": ... }`-wrapped, COMPONENT_LIST values are `{ "components": [...] }` and are NOT wrapped, every entry has a unique `id`, and this is the COMPLETE value you would send even to change just one field): ' +
+    `{ "components": [ { "id": "a1b2c", "codeComponentId": "7ojrigep-Eml9n5sN3i", "propValues": { "heading": { "value": "Featured" }, "visible": { "value": true } } }, { "id": "d3e4f", "codeComponentId": "x2plk9zq-Qw8rt", "propValues": { "title": { "value": "Sub group" }, "cards": { "components": [ { "id": "g5h6i", "codeComponentId": "card01ab-Zz12", "propValues": { "label": { "value": "Card 1" } } }, { "id": "j7k8l", "codeComponentId": "card01ab-Zz12", "propValues": { "label": { "value": "Card 2" } } } ] } } } ] }`, {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    page_id: z.string().describe("Target page id (from `list_editor_pages`)."),
+    element_id: z
+        .string()
+        .describe("Placed-section elementId identifying THIS placement on the page (from `list_page_sections`)."),
+    prop_id: z
+        .string()
+        .optional()
+        .describe("Blueprint prop id to update (from `list_page_sections`). Provide this or `prop_name`."),
+    prop_name: z
+        .string()
+        .optional()
+        .describe("Blueprint prop name to update (alternative to `prop_id`)."),
+    value: z
+        .any()
+        .describe('The prop value object to store, e.g. `{ "value": "Hello" }`. Match the shape of the existing entry in `list_page_sections` propValues for non-scalar prop types.'),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, page_id, element_id, prop_id, prop_name, value, port }) => {
+    const args = [
+        "update-section-prop",
+        "--page-id",
+        page_id,
+        "--element-id",
+        element_id,
+        ...(prop_id ? ["--prop-id", prop_id] : []),
+        ...(prop_name ? ["--prop-name", prop_name] : []),
+        "--value",
+        // The CLI JSON.parses --value. If `value` is already a JSON string, pass
+        // it through verbatim — re-stringifying it would double-encode it and the
+        // editor would store a string instead of the object/array.
+        typeof value === "string" ? value : JSON.stringify(value),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: upload_image
+server.tool("upload_image", "Upload an image to the connected editor's project and get back its image `id`. Provide the image via `file_path` (a local path) OR `image_url`. Use the returned `id` as the `id` of an IMAGE prop value passed to `update_section_prop` (e.g. `{ \"id\": \"<returned-id>\", \"altText\": \"...\", \"isVideo\": false }`). This is the way to set an image prop — `update_section_prop` does not upload, it only references an existing image id. Supported types: png, jpg, jpeg, webp, gif; max 10MB. Requires the editor to be embedded in the ikas admin panel (the admin panel performs the actual upload; a standalone editor cannot upload and will error/time out).", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    file_path: z
+        .string()
+        .optional()
+        .describe("Local image file path (.png, .jpg, .jpeg, .webp, .gif). Provide this or `image_url`."),
+    image_url: z
+        .string()
+        .optional()
+        .describe("Image URL to fetch and upload (alternative to `file_path`)."),
+    alt_text: z.string().optional().describe("Alt text to store with the image."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, file_path, image_url, alt_text, port }) => {
+    const args = [
+        "upload-image",
+        ...(file_path ? ["--file", file_path] : []),
+        ...(image_url ? ["--url", image_url] : []),
+        ...(alt_text ? ["--alt", alt_text] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
 // --- Start server ---
 async function main() {
     const transport = new StdioServerTransport();