@ikas/code-components-mcp 1.4.0-beta.4 → 1.4.0-beta.6

package/dist/index.js

@@ -15,6 +15,59 @@ function loadJsonFile(relativePath) {
     }
     return JSON.parse(fs.readFileSync(filePath, "utf-8"));
 }
+// Resolve theme.json from either raw string or absolute file path.
+// Exactly one of the two must be provided.
+function resolveThemeJson(themeJson, themeJsonPath) {
+    const hasInline = typeof themeJson === "string" && themeJson.length > 0;
+    const hasPath = typeof themeJsonPath === "string" && themeJsonPath.length > 0;
+    if (hasInline === hasPath) {
+        throw new Error("Provide exactly one of `theme_json` (raw JSON string) or `theme_json_path` (absolute path to theme.json).");
+    }
+    let raw;
+    if (hasPath) {
+        if (!path.isAbsolute(themeJsonPath)) {
+            throw new Error(`theme_json_path must be absolute: ${themeJsonPath}`);
+        }
+        if (!fs.existsSync(themeJsonPath)) {
+            throw new Error(`theme_json_path not found: ${themeJsonPath}`);
+        }
+        try {
+            raw = fs.readFileSync(themeJsonPath, "utf-8");
+        }
+        catch (e) {
+            throw new Error(`Failed to read theme_json_path "${themeJsonPath}": ${e.message}`);
+        }
+    }
+    else {
+        raw = themeJson;
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`Invalid JSON in theme.json: ${e.message}`);
+    }
+}
+// Atomic file write: temp file in same dir, then rename. Same-fs rename is atomic on POSIX.
+function writeFileAtomic(targetPath, content) {
+    const dir = path.dirname(targetPath);
+    const base = path.basename(targetPath);
+    const tmp = path.join(dir, `.${base}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 8)}`);
+    try {
+        fs.writeFileSync(tmp, content, "utf-8");
+        fs.renameSync(tmp, targetPath);
+    }
+    catch (e) {
+        try {
+            if (fs.existsSync(tmp))
+                fs.unlinkSync(tmp);
+        }
+        catch {
+            // ignore cleanup failure
+        }
+        throw e;
+    }
+}
 // Try multiple paths for storefront data (generated output or local data dir)
 function loadStorefrontData() {
     const paths = [
@@ -506,18 +559,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("");
-    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 +595,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,6 +621,51 @@ 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("");
@@ -638,49 +723,43 @@ function generateMigrationPlan(theme, projectName, oldSourceDir) {
         }
         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("");
-    // Usage section
-    parts.push(`## Per-Section Usage`);
+    // Custom Data Decisions — append-only log the LLM fills as it makes per-section decisions
+    parts.push(`## Custom Data Decisions`);
     parts.push("");
-    parts.push(`Once the Foundation is complete, for each section above:`);
+    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(`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(`<!-- Example: \`- SlideData → component \\\`hero-slide\\\` (2026-05-11) — structured record {image,link,title}; LIST_OF_LINK would drop the image\` -->`);
     parts.push("");
-    // Session Log — agents append notes here
-    parts.push(`## Session Log`);
+    // Known Environmental Issues (agents fill in during work)
+    parts.push(`## Known Environmental Issues`);
     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(`_Record any non-component build/TS errors here so future sessions don't waste time diagnosing them._`);
     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(`- [ ] _(none recorded yet)_`);
     parts.push("");
-    // Cross-references
+    // Notes — append-only log for decisions not captured elsewhere
+    parts.push(`## Notes`);
+    parts.push("");
+    parts.push(`_Append a bullet after completing work — library swaps, ad-hoc props, CLI folder-name oddities, user-approved feature drops, etc. Format: \`- [YYYY-MM-DD] <section-id>: <brief note>\`._`);
+    parts.push("");
+    parts.push(`<!-- Example: \`- [2026-04-15] ${projectName}-footer: swapped react-hot-toast for inline status text; CLI created Footer/ as expected\` -->`);
+    parts.push("");
+    // Cross-references — keep terse; LLM can call `get_migration_guide("list")` or `get_framework_guide("list")` for more
     parts.push(`## Cross-References`);
     parts.push("");
-    parts.push(`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");
 }
@@ -1057,6 +1136,101 @@ 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") {
+                parts.push(`**Default: component + COMPONENT_LIST.** Multiple fields per item — a single enum value cannot carry this structure.`);
+                parts.push("");
+                if (fieldDescriptions.length > 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("");
+                }
+                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");
+                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)`);
@@ -1222,30 +1396,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");
 }
@@ -1271,6 +1434,54 @@ function matchScore(text, query) {
     }
     return score;
 }
+// Levenshtein edit distance — small DP, fine for the 28 short kebab-case section template names.
+function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    const m = a.length;
+    const n = b.length;
+    const prev = new Array(n + 1);
+    const curr = new Array(n + 1);
+    for (let j = 0; j <= n; j++)
+        prev[j] = j;
+    for (let i = 1; i <= m; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= n; j++) {
+            const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+            curr[j] = Math.min(curr[j - 1] + 1, // insertion
+            prev[j] + 1, // deletion
+            prev[j - 1] + cost // substitution
+            );
+        }
+        for (let j = 0; j <= n; j++)
+            prev[j] = curr[j];
+    }
+    return prev[n];
+}
+// Suggest up to `max` closest candidates for an unknown input.
+// Primary: matchScore (substring/word). Fallback: Levenshtein when nothing scores well.
+function suggestClosestNames(input, candidates, opts) {
+    const min = opts?.min ?? 8;
+    const max = opts?.max ?? 3;
+    const scored = candidates
+        .map((c) => ({ name: c, score: matchScore(c, input) }))
+        .filter((s) => s.score >= min)
+        .sort((a, b) => b.score - a.score);
+    if (scored.length > 0)
+        return scored.slice(0, max).map((s) => s.name);
+    // Levenshtein fallback — tolerate up to ceil(len/3) edits.
+    const maxDistance = Math.max(1, Math.ceil(input.length / 3));
+    const lower = input.toLowerCase();
+    const edits = candidates
+        .map((c) => ({ name: c, d: levenshtein(lower, c.toLowerCase()) }))
+        .filter((s) => s.d <= maxDistance)
+        .sort((a, b) => a.d - b.d);
+    return edits.slice(0, max).map((s) => s.name);
+}
 function searchFunctions(query) {
     const scored = storefrontData.functions
         .map((fn) => {
@@ -2141,11 +2352,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.`,
                 },
             ],
         };
@@ -2602,7 +2821,7 @@ const migrationTopicAliases = {
 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." }] };
     }
@@ -2686,39 +2905,95 @@ 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"),
+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, section_name, project_name, old_source_dir }) => {
+}, 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)}` }],
         };
     }
 });