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

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,6 +651,57 @@ 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("");
@@ -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,8 +745,13 @@ 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 fields = (itemObj.nestedData || []).map((f) => f.key || f.name || "?").slice(0, 8);
+                            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 });
                         }
                     }
@@ -638,59 +768,67 @@ 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("");
+    // Custom Data Decisions — append-only log the LLM fills as it makes per-section decisions
+    parts.push(`## Custom Data Decisions`);
+    parts.push("");
+    parts.push(`> Log each customData enum-vs-component decision here as you encounter it during section migration. Format: \`- \\\`<CustomDataName>\\\` → enum/component \\\`<target name>\\\` (YYYY-MM-DD) — reasoning\`.`);
     parts.push("");
-    // Usage section
-    parts.push(`## Per-Section Usage`);
+    parts.push(`<!-- Example: \`- SlideData → component \\\`hero-slide\\\` (2026-05-11) — structured record {image,link,title}; LIST_OF_LINK would drop the image\` -->`);
     parts.push("");
-    parts.push(`Once the Foundation is complete, for each section above:`);
+    // Known Environmental Issues (agents fill in during work)
+    parts.push(`## Known Environmental Issues`);
     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(`_Record any non-component build/TS errors here so future sessions don't waste time diagnosing them._`);
+    parts.push("");
+    parts.push(`- [ ] _(none recorded yet)_`);
     parts.push("");
-    // 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;
@@ -709,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));
             }
         }
@@ -726,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 {
@@ -740,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);
@@ -748,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);
                 }
@@ -811,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();
@@ -827,27 +982,38 @@ 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}`);
@@ -893,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("");
@@ -939,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);
@@ -947,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);
@@ -958,7 +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 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 || [])) {
@@ -969,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);
@@ -985,10 +1169,14 @@ 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({
@@ -1017,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);
@@ -1032,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;
@@ -1040,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);
@@ -1049,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);
@@ -1057,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)`);
@@ -1077,7 +1404,10 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
             existing.usedByProps.push(ch.propName);
         }
         else {
-            uniqueChildren.set(ch.childName, { child: ch, usedByProps: [ch.propName] });
+            uniqueChildren.set(ch.childName, {
+                child: ch,
+                usedByProps: [ch.propName],
+            });
         }
     }
     if (uniqueChildren.size > 0) {
@@ -1090,7 +1420,7 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
         for (const { child: ch, usedByProps } of uniqueChildren.values()) {
             parts.push(`### \`${ch.childName}\``);
             const propsLabel = usedByProps.length > 1
-                ? `Used by parent props: ${usedByProps.map(p => `\`${p}\``).join(", ")} (${usedByProps.length}×)`
+                ? `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}"`);
@@ -1136,12 +1466,15 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
         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");
@@ -1168,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`);
@@ -1199,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"))
@@ -1208,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)`);
@@ -1222,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`);
+    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`);
     }
-    if (target.isHeader || target.isFooter) {
-        parts.push(`- \`get_framework_guide("header-footer-patterns")\` — header/footer specifics`);
-    }
-    parts.push(`- \`get_framework_guide("common-pitfalls")\` — observer rules, common mistakes`);
     parts.push("");
     // Completion
     parts.push(`## ${nextStep + 2}. Mark Complete`);
     parts.push("");
-    parts.push(`Once the section builds cleanly with \`npx ikas-component build\`:`);
-    parts.push(`1. Edit \`MIGRATION.md\` at the project root`);
-    parts.push(`2. Change the checkbox for \`${sectionId}\` from \`[ ]\` to \`[x]\``);
-    parts.push(`3. Also mark each child component as \`[x]\``);
-    parts.push(`4. Append an entry to the **Session Log** section of \`MIGRATION.md\` noting: libraries replaced, any props added beyond the generated plan, the actual folder name the CLI created (in case it differs from the name you passed — e.g., \`FAQ\` → \`Faq/\`), and any other decisions a future agent should know.`);
+    parts.push(`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,21 +1610,80 @@ 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 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;
+        const typeScore = fn.parameterTypes?.some((t) => matchScore(t, query) > 0)
+            ? 8
+            : 0;
         return {
             fn,
-            score: nameScore + displayNameScore + descScore + catScore + paramScore + sigScore + typeScore,
+            score: nameScore +
+                displayNameScore +
+                descScore +
+                catScore +
+                paramScore +
+                sigScore +
+                typeScore,
         };
     })
         .filter((item) => item.score > 0)
@@ -1299,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);
@@ -1314,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)
@@ -1356,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 = {}) {
@@ -1398,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}\``);
             }
@@ -1407,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");
 }
@@ -1425,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 one section (`add_sections_to_page` places MANY at once and can set their props in the same call — fastest way to build a page); `list_page_sections` → the sections placed on a page (LEAN roster: per-placement `elementId`, `componentId`, `propCount`, which props are filled — NO schema/values, so it never truncates); `get_component_props` → a component's prop blueprint (types, ENUM valid `options`, COMPONENT_LIST `allowedComponentIds`) for any section OR child id; `get_section_values` → one section's current prop values (for read-modify-write); `get_page_by_type` → a theme page id by pageType (e.g. CATEGORY), to build PAGE links to entities (`create_page` adds that page if it does not exist yet, so you never guess a slug); `update_section_prop` → change a single prop value of a placed section (`update_page_sections` fills MANY sections/props of a page in ONE call — strongly prefer it to cut round-trips when filling content); `upload_image` → upload one image (file or URL) and get an image id (`upload_images` uploads many in one call — prefer it for several); `search_products` / `list_categories` / `list_brands` / `list_blogs` / `list_blog_categories` → find real entity ids for PRODUCT/CATEGORY/BRAND/BLOG/BLOG_CATEGORY prop values; `publish_theme` → publish the theme LIVE and get back the preview URL to review (guarded — needs `confirm:true`, and `confirm_production:true` for the main theme; only call it when the user explicitly asks to publish). For the full end-to-end process (placing a section and filling its content, with per-prop value shapes and COMPONENT_LIST rules), call `get_editor_workflow` first.\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 }) => {
@@ -1466,13 +1884,20 @@ 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();
     // Phase 1: canonical-name match wins. A real function name always outranks
     // any displayName alias so aliases can never shadow the function they're
@@ -1480,7 +1905,9 @@ server.tool("get_function_doc", "Get full documentation for a specific storefron
     // [BP-DISPLAY-NAME: hasCustomer] alias).
     const byName = storefrontData.functions.find((f) => f.name.toLowerCase() === nameLower);
     if (byName) {
-        return { content: [{ type: "text", text: formatFunctionDoc(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);
@@ -1488,7 +1915,9 @@ server.tool("get_function_doc", "Get full documentation for a specific storefron
         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) }],
+            content: [
+                { type: "text", text: note + formatFunctionDoc(fn) },
+            ],
         };
     }
     if (byAlias.length > 1) {
@@ -1506,7 +1935,9 @@ server.tool("get_function_doc", "Get full documentation for a specific storefron
         (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})` : "";
+            const alias = f.displayName && f.displayName !== f.name
+                ? ` (alias: ${f.displayName})`
+                : "";
             return `  - ${f.name}${alias}`;
         });
         return {
@@ -1519,7 +1950,12 @@ server.tool("get_function_doc", "Get full documentation for a specific storefron
         };
     }
     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. Use \`list_functions()\` to see all available functions.`,
+            },
+        ],
     };
 });
 // Tool: list_functions
@@ -1569,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();
@@ -1601,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);
@@ -1621,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: [
                 {
@@ -1644,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, "```", "");
         }
@@ -1665,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);
@@ -1729,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)
@@ -1745,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));
@@ -1770,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();
@@ -1797,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) {
@@ -1828,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"])
@@ -1839,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();
@@ -1866,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`];
@@ -1974,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`];
@@ -2044,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();
@@ -2083,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
@@ -2141,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.`,
                 },
             ],
         };
@@ -2180,7 +2738,8 @@ server.tool("get_section_template", "Get the root files of a starter section tem
     // 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)) {
+        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.`, "");
@@ -2304,7 +2863,10 @@ server.tool("get_section_template", "Get the root files of a starter section tem
                     try {
                         const childSnippet = JSON.parse(fs.readFileSync(childSnippetPath, "utf-8"));
                         const childProps = (childSnippet.props || []).map((p) => {
-                            const out = { name: p.name, type: p.type };
+                            const out = {
+                                name: p.name,
+                                type: p.type,
+                            };
                             if (p.displayName)
                                 out.displayName = p.displayName;
                             if (p.required)
@@ -2377,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()
@@ -2543,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);
@@ -2551,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);
@@ -2656,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"
@@ -2686,42 +3316,870 @@ 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, 
+        // Large editor responses (e.g. list_categories on a big store, or
+        // add_sections_to_page echoing many sections) easily exceed Node's default
+        // 1MB stdout buffer, which truncates output mid-JSON and yields a
+        // "no parseable JSON" error. Give it generous headroom.
+        { cwd: projectRoot, windowsHide: true, maxBuffer: 64 * 1024 * 1024 }, (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;
+    // Fast path: the CLI prints exactly one JSON object on stdout.
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        // Fallback: if anything leaked onto stdout before/after the JSON, scan the
+        // lines and return the last one that parses as JSON.
+        const lines = trimmed
+            .split("\n")
+            .map((l) => l.trim())
+            .filter(Boolean);
+        for (let i = lines.length - 1; i >= 0; i--) {
+            try {
+                return JSON.parse(lines[i]);
+            }
+            catch {
+                // keep scanning
+            }
+        }
+        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 a SINGLE already-imported section-type code component on a page. Use this ONLY when adding exactly one section. If you are adding more than one section — or building/populating a page — call `add_sections_to_page` instead: it places them all AND fills their props in ONE call. Calling this tool repeatedly (one section per call) is the slow path and should be avoided. 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` / `update_page_sections` (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: add_sections_to_page
+server.tool("add_sections_to_page", "Place MANY sections on a page in a SINGLE call — and optionally set each section's prop values AT placement time, so you skip the separate fill step. The fastest way to build a page: one round-trip instead of one add (and one fill) per section. Pass `sections`, each `{ component_id, index?, updates?: [{ prop_name|prop_id, value }] }`; values use the same per-type shapes as update_section_prop / get_editor_workflow. Returns the new `elementId` for each placement (plus written prop results). Built-but-unimported section AND child code components are auto-imported. All update values are validated before anything is placed. Use `list_editor_pages` for page ids and `list_imported_sections` for component 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`)."),
+    sections: z
+        .array(z.object({
+        component_id: z.string().describe("Imported (or built) section-type code component id."),
+        index: z
+            .number()
+            .int()
+            .nonnegative()
+            .optional()
+            .describe("Zero-based insertion index; appends when omitted."),
+        updates: z
+            .array(z.object({
+            prop_id: z.string().optional().describe("Blueprint prop id (provide this or prop_name)."),
+            prop_name: z.string().optional().describe("Blueprint prop name (alternative to prop_id)."),
+            value: z.any().describe("Prop value, same shape update_section_prop expects for that type."),
+        }))
+            .optional()
+            .describe("Optional prop values to set on this section right after placing it."),
+    }))
+        .describe("Non-empty array of sections to place (in order), each with its componentId and optional prop updates."),
+    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, page_id, sections, port }) => {
+    const normalized = (sections || []).map(s => ({
+        componentId: s.component_id,
+        ...(typeof s.index === "number" ? { index: s.index } : {}),
+        ...(s.updates
+            ? {
+                updates: s.updates.map(u => ({
+                    ...(u.prop_id ? { propId: u.prop_id } : {}),
+                    ...(u.prop_name ? { propName: u.prop_name } : {}),
+                    value: u.value,
+                })),
+            }
+            : {}),
+    }));
+    const args = [
+        "add-sections-to-page",
+        "--page-id",
+        page_id,
+        "--sections",
+        JSON.stringify(normalized),
+        ...(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 — a LEAN ROSTER that never truncates: per-placement `elementId` (the identity of THIS placement — there can be multiple of the same section), `sectionId`, `componentId`, `name`, `propCount`, and `setPropNames` (which props already have a value). It deliberately omits the prop SCHEMA and the prop VALUES (both can be large — Header alone can have ~80 props). To get a section's prop schema (types, ENUM options, allowed children) call `get_component_props(componentId)`; to read its current values call `get_section_values(element_id)`. Use the returned `elementId` with `update_section_prop` / `update_page_sections`. Use `list_editor_pages` for 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: get_component_props
+server.tool("get_component_props", "Get prop blueprints straight from the editor (the source of truth) for one or MANY components in a single call — for any section OR child code component ids. Returns `{ components: [...] }`, each prop carrying its `id`, `name`, `type`, `required`, `default`, and crucially: a ready-to-use `writeExample` (the EXACT value shape to pass to update_section_prop / update_page_sections — e.g. PRODUCT_LIST, BLOG_LIST, COMPONENT_LIST, LINK) plus a `writeNote` for variants, so you do NOT have to guess or trial-write the JSON; for ENUM props the `options` (valid `value`s); and for COMPONENT/COMPONENT_LIST props the `allowedComponentIds` (which children the slot permits — when empty, an `allowedComponentsNote` says any imported code component is allowed). Use this (its `writeExample`/`options`/`allowedComponentIds`) instead of guessing or reading ikas.config.json. Pass ALL the section/child ids you need at once (batch). Child component ids come from a parent prop's `allowedComponentIds` (or get_section_template).", {
+    project_root: z.string().describe("Absolute path to the code-component project."),
+    component_ids: z
+        .array(z.string())
+        .describe("Section/child code-component ids to resolve (batch). From list_imported_sections or a COMPONENT_LIST prop's allowedComponentIds."),
+    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, component_ids, port }) => {
+    const args = [
+        "get-component-props",
+        "--component-ids",
+        (component_ids || []).join(","),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: get_section_values
+server.tool("get_section_values", "Get the CURRENT prop values of one or MANY placed sections (each with its full `propValues` plus blueprint `props` — every prop carrying a `writeExample`/`writeNote` for the exact value shape, plus ENUM `options` and COMPONENT_LIST `allowedComponentIds`). `list_page_sections` is lean and omits values to avoid truncation; use this to read sections' values — needed for read-modify-write of a COMPONENT_LIST, or to inspect the exact stored shape of an existing value. Returns `{ sections: [...] }`. Pass all the elementIds you need at once (batch).", {
+    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_ids: z
+        .array(z.string())
+        .describe("Placed-section elementIds to read (batch). From `list_page_sections`."),
+    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, page_id, element_ids, port }) => {
+    const args = [
+        "get-section-values",
+        "--page-id",
+        page_id,
+        "--element-ids",
+        (element_ids || []).join(","),
+        ...(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 (full catalog in `get_editor_workflow`): IMAGE = `{ "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`); IMAGE_LIST = `{ "images": [ <image>, ... ] }`; VIDEO = `{ "video": { "id": "<asset-id>" }, "thumbnailImage"?: { "id": "..." }, "autoplay"?: false, "controls"?: true, "loop"?: false, "muted"?: false }` (NOT a bare `{ "id": ... }`); SVG = `{ "value": "<svg markup>" }` (value-wrapped, like a scalar); SVG_LIST = `{ "svgs": [ "<svg>", ... ] }`; entity props PRODUCT/CATEGORY/BRAND/BLOG/BLOG_CATEGORY/RAFFLE = `{ "<entity>Id": "...", "usePageData"?: false }` (e.g. `{ "categoryId": "..." }`) — get real ids from `search_products` (PRODUCT), `list_categories`, `list_brands`, `list_blogs`, `list_blog_categories`; list/collection props are typed objects keyed by a `<entity>ListType` discriminator: PRODUCT_LIST = `{ "id": "<unique>", "productListType": "STATIC", "productIds": [ { "productId": "...", "variantId": "..." } ], "initialLimit"?: 12 }` — note productIds is an array of {productId, variantId} PAIRS (from search_products), not bare ids; productListType ∈ ALL|STATIC|DISCOUNTED|RECOMMENDED|CATEGORY|SEARCH|LAST_VIEWED|RELATED_PRODUCTS|VIEWED_TOGETHER|PURCHASED_TOGETHER, and for a dynamic type use e.g. `{ "id": "<unique>", "productListType": "CATEGORY", "category": "<categoryId>" }` (no productIds) or `"ALL"` (no ids). CATEGORY_LIST = `{ "categoryListType": "STATIC", "categoryIds": ["..."] }` or `{ "categoryListType": "ALL" }`. BRAND_LIST = `{ "brandListType": "STATIC", "brandIds": ["..."] }` or ALL. BLOG_LIST = `{ "blogListType": "STATIC", "blogIds": ["..."] }`, `{ "blogListType": "CATEGORY", "categoryId": "..." }`, or ALL. BLOG_CATEGORY_LIST = `{ "blogCategoryListType": "STATIC", "blogCategoryIds": ["..."] }` or ALL. (Get the entity ids from search_products / list_*; you can also read an existing value with `get_section_values` to copy its exact shape.) 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": [] }`. To link to an ENTITY (category/brand/blog/blog-category) do NOT guess a slug — get the entity id from `list_categories`/`list_brands`/`list_blogs`/`list_blog_categories` and the page id from `get_page_by_type("<TYPE>")`, then build `{ "id": "<unique>", "linkType": "PAGE", "label": "...", "pageId": <pageId>, "pageType": "<TYPE>", "itemId": <entityId>, "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 (deeply, including nested COMPONENT_LIST children): wrong shapes AND wrong semantics are REJECTED with an explanatory error instead of being silently stored. This includes: a `{ "value": [...] }` wrapper for a COMPONENT_LIST; a `{ "value": ... }`-wrapped IMAGE; `props` instead of `propValues`; a missing/duplicate entry `id`; a child referenced by the wrong key (a code component MUST use `codeComponentId`, a theme component `componentId`) or by an id that does not exist (child ids are opaque — take them from `get_section_template` / `list_imported_sections`, never invent them); and any `propValues` key that is not a real prop of that child component (the error lists the valid prop names). Auto-import: a referenced child code component that has been BUILT but not yet imported into the theme is imported automatically before the value is set (the response lists any such ids under `autoImported`); only children that are not built at all fail with a "no imported code component" error — build them first (`ikas-component build`/`dev`). For any prop type you are unsure about, inspect the existing value with `get_section_values` 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 `get_section_values`, 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 — call `get_component_props(parentComponentId)` to read the COMPONENT_LIST prop\'s `allowedComponentIds`, then `get_component_props(childId)` to learn that child\'s props (names, types, ENUM `options`/valid values) instead of guessing or reading ikas.config.json. The allowed set 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 value from `get_section_values` 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);
+});
+// Tool: update_page_sections
+server.tool("update_page_sections", "Fill MANY placed sections of a page in a SINGLE call — the fastest way to populate a whole page (one round-trip for the entire page instead of one call per section/prop). Takes `sections`, each `{ element_id, updates: [{ prop_name|prop_id, value }] }`; values use the same per-type shapes as update_section_prop / get_editor_workflow. All-or-nothing across the whole page: every value is resolved and deeply validated (and built-but-unimported child code components auto-imported) before anything is written — one invalid value rejects the entire page update. Prefer this over many update_section_prop(s) calls.", {
+    project_root: z.string().describe("Absolute path to the code-component project."),
+    page_id: z.string().describe("Target page id (from list_editor_pages)."),
+    sections: z
+        .array(z.object({
+        element_id: z.string().describe("Placed-section elementId (from list_page_sections)."),
+        updates: z
+            .array(z.object({
+            prop_id: z.string().optional().describe("Blueprint prop id (provide this or prop_name)."),
+            prop_name: z.string().optional().describe("Blueprint prop name (alternative to prop_id)."),
+            value: z.any().describe("Prop value, same shape update_section_prop expects for that type."),
+        }))
+            .describe("Non-empty array of prop updates for this section."),
+    }))
+        .describe("Non-empty array of sections to fill, each with its elementId and prop updates."),
+    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, page_id, sections, port }) => {
+    const normalized = (sections || []).map(s => ({
+        elementId: s.element_id,
+        updates: (s.updates || []).map(u => ({
+            ...(u.prop_id ? { propId: u.prop_id } : {}),
+            ...(u.prop_name ? { propName: u.prop_name } : {}),
+            value: u.value,
+        })),
+    }));
+    const args = [
+        "update-page-sections",
+        "--page-id",
+        page_id,
+        "--sections",
+        JSON.stringify(normalized),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: upload_images
+server.tool("upload_images", "Upload MANY images in one call (batch upload_image) and get their ids back in order — the host uploads them all in a single round-trip. Pass `images`, each `{ file_path?, image_url?, alt_text? }`. Returns an array of { id, fileName, altText, isVideo } in the same order; use each id in an IMAGE prop value. Prefer this over multiple upload_image calls when a section/page needs several images. Supported: png/jpg/jpeg/webp/gif, max 10MB each. Requires the editor embedded in the ikas admin panel.", {
+    project_root: z.string().describe("Absolute path to the code-component project."),
+    images: z
+        .array(z.object({
+        file_path: z.string().optional().describe("Local image file path (provide this or image_url)."),
+        image_url: z.string().optional().describe("Image URL to fetch (alternative to file_path)."),
+        alt_text: z.string().optional().describe("Alt text for this image."),
+    }))
+        .describe("Non-empty array of images to upload."),
+    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, images, port }) => {
+    const manifest = (images || []).map(im => ({
+        ...(im.file_path ? { file: im.file_path } : {}),
+        ...(im.image_url ? { url: im.image_url } : {}),
+        ...(im.alt_text ? { alt: im.alt_text } : {}),
+    }));
+    const args = [
+        "upload-images",
+        "--manifest",
+        JSON.stringify(manifest),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: search_products
+server.tool("search_products", "Search the connected store's products to obtain a real productId (and first variantId) for a PRODUCT prop value. Returns products with productId, variantId, name, slug, variantCount, and `imageSrc` (the full-resolution CDN URL of the product's main image). To use that product image in an IMAGE prop, you CANNOT reuse a product image id directly (it is not a theme asset) — pass the `imageSrc` URL to `upload_image(image_url: <imageSrc>)` (or `upload_images`), then use the returned id in the IMAGE value. This gives real product imagery instead of external/placeholder URLs. Use the result in update_section_prop as `{ \"productId\": \"<productId>\", \"variantId\": \"<variantId>\" }`. Pass `query` for free-text search, or `product_ids` to resolve specific ids. Requires the editor embedded in the ikas admin panel (the admin panel runs the search; a standalone editor cannot).", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    query: z.string().optional().describe("Free-text product search (name, sku, barcode)."),
+    product_ids: z
+        .array(z.string())
+        .optional()
+        .describe("Specific product ids to resolve directly (alternative to `query`)."),
+    per_page: z.number().optional().describe("Results per page."),
+    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, query, product_ids, per_page, port }) => {
+    const args = [
+        "search-products",
+        ...(query ? ["--query", query] : []),
+        ...(product_ids && product_ids.length ? ["--ids", product_ids.join(",")] : []),
+        ...(typeof per_page === "number" ? ["--per-page", String(per_page)] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: list_categories
+server.tool("list_categories", "List the store's product categories and their ids, to fill a CATEGORY prop value `{ \"categoryId\": \"<id>\" }`. Returns categoryId, name, slug, parentId for each. Returns all categories (no query). To link to a category from a LINK prop, also call `get_page_by_type(\"CATEGORY\")` for the page id, then build `{ \"linkType\": \"PAGE\", \"pageId\": <pageId>, \"pageType\": \"CATEGORY\", \"itemId\": <categoryId>, \"id\": <unique>, \"label\": \"...\" }`. Requires the editor embedded in the ikas admin panel.", {
+    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-entities", "--kind", "category", ...(port ? ["--port", String(port)] : [])];
+    return callEditorAction(project_root, args);
+});
+// Tool: list_brands
+server.tool("list_brands", "List the store's product brands and their ids, to fill a BRAND prop value `{ \"brandId\": \"<id>\" }`. Returns brandId, name, slug for each. Returns all brands (no query). To link to a brand from a LINK prop, also call `get_page_by_type(\"BRAND\")` for the page id, then build `{ \"linkType\": \"PAGE\", \"pageId\": <pageId>, \"pageType\": \"BRAND\", \"itemId\": <brandId>, \"id\": <unique>, \"label\": \"...\" }`. Requires the editor embedded in the ikas admin panel.", {
+    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-entities", "--kind", "brand", ...(port ? ["--port", String(port)] : [])];
+    return callEditorAction(project_root, args);
+});
+// Tool: list_blogs
+server.tool("list_blogs", "List the store's blogs and their ids, to fill a BLOG prop value `{ \"blogId\": \"<id>\" }`. Returns blogId, name, slug for each. Accepts an optional `query` for free-text search. To link to a blog from a LINK prop, also call `get_page_by_type(\"BLOG\")` for the page id, then build `{ \"linkType\": \"PAGE\", \"pageId\": <pageId>, \"pageType\": \"BLOG\", \"itemId\": <blogId>, \"id\": <unique>, \"label\": \"...\" }`. Requires the editor embedded in the ikas admin panel.", {
+    project_root: z.string().describe("Absolute path to the code-component project."),
+    query: z.string().optional().describe("Free-text blog search."),
+    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, query, port }) => {
+    const args = [
+        "list-entities",
+        "--kind",
+        "blog",
+        ...(query ? ["--query", query] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: list_blog_categories
+server.tool("list_blog_categories", "List the store's blog categories and their ids, to fill a BLOG_CATEGORY prop value `{ \"blogCategoryId\": \"<id>\" }`. Returns blogCategoryId, name, slug for each. Accepts an optional `query` for free-text search. To link to a blog category from a LINK prop, also call `get_page_by_type(\"BLOG_CATEGORY\")` for the page id, then build `{ \"linkType\": \"PAGE\", \"pageId\": <pageId>, \"pageType\": \"BLOG_CATEGORY\", \"itemId\": <blogCategoryId>, \"id\": <unique>, \"label\": \"...\" }`. Requires the editor embedded in the ikas admin panel.", {
+    project_root: z.string().describe("Absolute path to the code-component project."),
+    query: z.string().optional().describe("Free-text blog-category search."),
+    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, query, port }) => {
+    const args = [
+        "list-entities",
+        "--kind",
+        "blog-category",
+        ...(query ? ["--query", query] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: get_page_by_type
+server.tool("get_page_by_type", "Resolve a theme page's id from its pageType (CATEGORY, PRODUCT, BRAND, BLOG, BLOG_CATEGORY, INDEX, …). Use this to get the `pageId` needed to build a PAGE link to an entity: pair it with the entity id from list_categories/list_brands/list_blogs/list_blog_categories — `{ linkType:\"PAGE\", pageId:<this pageId>, pageType:<type>, itemId:<entityId>, id:<unique>, label:... }`. Returns `pageId: null` (with a note) if no page of that type exists yet — in that case call `create_page(page_type)` to add it, then use the returned pageId (do not guess a slug/EXTERNAL URL).", {
+    project_root: z.string().describe("Absolute path to the code-component project."),
+    page_type: z
+        .string()
+        .describe("Page type to resolve, e.g. CATEGORY, PRODUCT, BRAND, BLOG, BLOG_CATEGORY, INDEX."),
+    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, page_type, port }) => {
+    const args = [
+        "get-page-by-type",
+        "--page-type",
+        page_type,
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: create_page
+server.tool("create_page", "Create a theme page of a given pageType in the connected editor. Use this when get_page_by_type returns `pageId: null` for a dynamic page (CATEGORY/PRODUCT/BRAND/BLOG/BLOG_CATEGORY) you need to link to: create the page, then build a PAGE link `{ linkType:\"PAGE\", pageId:<this pageId>, pageType:<type>, itemId:<entityId>, id:<unique>, label:... }` — do NOT guess a slug/EXTERNAL URL. Non-CUSTOM page types are unique per theme: if one already exists it is returned unchanged (`alreadyExisted: true`). CUSTOM pages require `name` and a unique `slug`. Account sub-pages (ADDRESSES/ORDERS/ORDER_DETAIL/FAVORITE_PRODUCTS/RAFFLE_ACCOUNT) need an ACCOUNT page first. Returns `{ pageType, pageId, name, slug }`. Requires `ikas-component dev` running with the editor connected.", {
+    project_root: z.string().describe("Absolute path to the code-component project."),
+    page_type: z
+        .string()
+        .describe("Page type to create, e.g. CATEGORY, PRODUCT, BRAND, BLOG, BLOG_CATEGORY, INDEX, CUSTOM."),
+    name: z.string().optional().describe("Page name. Required for CUSTOM pages; ignored otherwise."),
+    slug: z.string().optional().describe("Page slug. Required (and unique) for CUSTOM pages; ignored otherwise."),
+    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, page_type, name, slug, port }) => {
+    const args = [
+        "create-page",
+        "--page-type",
+        page_type,
+        ...(name ? ["--name", name] : []),
+        ...(slug ? ["--slug", slug] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: publish_theme
+server.tool("publish_theme", "Publish the current theme LIVE — the same action as the editor's Publish button (uploads the whole project to the storefront). This is REAL and customer-facing: the published site changes. SAFETY: it publishes nothing unless `confirm: true` is passed; if you omit it you get a dry-run with the `previewUrl` and a warning describing the impact. The MAIN/production theme additionally requires `confirm_production: true` (its URL is the live customer-facing domain). Use this when the user explicitly asks to publish/go live — do NOT publish on your own initiative. On success returns `{ published: true, previewUrl, isMainTheme }`; open `previewUrl` to review the result. Requires `ikas-component dev` running with the editor connected.", {
+    project_root: z.string().describe("Absolute path to the code-component project."),
+    confirm: z
+        .boolean()
+        .optional()
+        .describe("Set true to actually publish. Omitted/false = dry-run (returns previewUrl + warning, publishes nothing)."),
+    confirm_production: z
+        .boolean()
+        .optional()
+        .describe("Required IN ADDITION to confirm when the target is the MAIN/production theme (live customer-facing site)."),
+    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, confirm, confirm_production, port }) => {
+    const args = [
+        "publish-theme",
+        ...(confirm ? ["--confirm"] : []),
+        ...(confirm_production ? ["--confirm-production"] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: get_editor_workflow
+const EDITOR_WORKFLOW_GUIDE = [
+    "# Editor workflow: placing sections and filling their content on a page",
+    "",
+    "Use this when the user wants to add a section to a page and/or fill in its content (heading, text, image, link, slides, etc.) in the live editor. These are LIVE-EDITOR actions and require `ikas-component dev` running with the editor connected; image upload additionally requires the editor to be embedded in the ikas admin panel (the admin panel performs the upload — a standalone editor cannot upload).",
+    "",
+    "## Two distinct jobs — do not confuse them",
+    "- (A) DEFINE props / author component code — changing WHICH props a component has. Edits component source/config (config add-prop/add-component, index.tsx) and needs a rebuild. Do this ONLY when a needed prop does not exist yet, or the user explicitly asks to build/modify the component.",
+    "- (B) SET prop VALUES / fill content — giving values to props that ALREADY exist on a placed section. Pure data entry via list_page_sections + update_section_prop (+ upload_image). No code, no rebuild.",
+    "When the user says 'fill this section', 'set the title/text/image/link', 'populate', 'change the content' → that is JOB (B). Do NOT write a component or add a prop to fill a value the section already supports.",
+    "",
+    "## Step-by-step (JOB B — fill content)",
+    "1. list_editor_pages → choose the target page_id.",
+    "2. list_page_sections(page_id) → for each placed section: its per-placement elementId, blueprint props (id, name, type), and setPropNames (which props already have a value). It is LEAN — no prop VALUES, so it never truncates. To read a section's current values (e.g. to read-modify-write a COMPONENT_LIST), call get_section_values(page_id, element_id). (If the section is not on the page yet, see 'Placing a section' below.)",
+    "3. To set props (fewest round-trips = fastest): update_page_sections(page_id, sections:[{element_id, updates:[{prop_name,value}]}]) fills the WHOLE page (or one section, or just one prop — it scales to all cases) in ONE call (best). update_section_prop sets a single prop, for quick one-offs. Pass each value as a parsed JSON object/array, NEVER a JSON string.",
+    "4. For image props: upload_images(images:[{file_path|image_url, alt_text}]) uploads many in ONE call (preferred); upload_image for a single one. Use the returned id(s) in IMAGE values. Do uploads BEFORE the update call so you have the ids.",
+    "Speed tip: each tool call is a round-trip — gather first (one list_page_sections), batch your uploads (upload_images) and your writes (update_page_sections), rather than calling per-prop/per-image.",
+    "",
+    "## Building a whole page fast (placing + filling)",
+    "- add_sections_to_page(page_id, sections:[{component_id, index?, updates:[{prop_name,value}]}]) places MANY sections AND sets their props in ONE call, returning each new elementId. This is the fastest path — prefer it over add_section_to_page per section followed by separate fills. Built-but-unimported section/child components are auto-imported.",
+    "- For a single section: list_imported_sections (confirm imported; else import_section, after building) → add_section_to_page(component_id, page_id, index?) → then list_page_sections to get its elementId.",
+    "",
+    "## Value shapes by prop type (what to pass as `value`)",
+    "- Scalars are WRAPPED: TEXT/RICH_TEXT { \"value\": \"...\" }, BOOLEAN { \"value\": true }, NUMBER { \"value\": 12 }, COLOR { \"value\": \"#FF0000\" }, ENUM { \"value\": \"<key>\" }, DATE { \"value\": ... }.",
+    "- SVG is value-wrapped: { \"value\": \"<svg markup>\" }. NUMBER_RANGE: { \"value\": <number>, \"unit\": \"px\"|null }.",
+    "- Object props are NOT wrapped (no { \"value\": ... }):",
+    "  - IMAGE: { \"id\": \"<asset-id>\", \"altText\"?: \"...\", \"isVideo\"?: false } — get the id from upload_image. Same shape at section level AND nested in a component list. IMAGE_LIST: { \"images\": [ <image>, ... ] }.",
+    "  - VIDEO: { \"video\": { \"id\": \"<asset-id>\" }, \"thumbnailImage\"?: { \"id\": \"...\" }, \"autoplay\"?: false, \"controls\"?: true, \"loop\"?: false, \"muted\"?: false } — NOT a bare { \"id\": ... }. SVG_LIST: { \"svgs\": [ \"<svg>\", ... ] }.",
+    "  - LINK: { \"id\": \"<unique>\", \"linkType\": \"PAGE\"|\"EXTERNAL\"|\"FILE\", \"label\": \"...\", \"subLinks\": [] } plus target — for a static page: pageId + pageType (from list_editor_pages); for EXTERNAL: externalLink. To link to a CATEGORY/BRAND/BLOG/BLOG_CATEGORY entity, do NOT guess a slug — get the entity id from list_categories/list_brands/list_blogs/list_blog_categories and the page id from get_page_by_type('<TYPE>'), then build { id, linkType:'PAGE', label, pageId:<pageId>, pageType:'<TYPE>', itemId:<entityId>, subLinks:[] }. LIST_OF_LINK = { \"links\": [ <link>, ... ] }.",
+    "  - Entity props PRODUCT/CATEGORY/BRAND/BLOG/BLOG_CATEGORY/RAFFLE: { \"<entity>Id\": \"...\", \"usePageData\"?: false } — e.g. { \"productId\": \"...\", \"variantId\"?: \"...\" }, { \"categoryId\": \"...\" }. Get real ids (never invent them) from: search_products (PRODUCT), list_categories (CATEGORY), list_brands (BRAND), list_blogs (BLOG), list_blog_categories (BLOG_CATEGORY). (RAFFLE has no lookup tool yet — read an existing value or ask the user.)",
+    "  - List/collection props (PRODUCT_LIST/CATEGORY_LIST/BRAND_LIST/BLOG_LIST/…): complex typed objects (a <entity>ListType plus initialSort/initialLimit and static ids). Do NOT build from scratch — read the current value with get_section_values and edit it.",
+    "  - COMPONENT_LIST: { \"components\": [ { \"id\": \"<unique>\", \"codeComponentId\": \"<child-id>\", \"propValues\": { \"<childProp>\": <value>, ... } }, ... ] }. A single COMPONENT prop is one such entry. childProp values use these same per-type shapes, recursively.",
+    "",
+    "## COMPONENT_LIST rules (the part most often gotten wrong)",
+    "- READ-MODIFY-WRITE: update_section_prop REPLACES the whole prop value. To add/edit/remove one child, take the CURRENT { components: [...] } from get_section_values, edit it, and resend the ENTIRE array (with all existing entries and their ids). Sending only your new entry wipes the rest.",
+    "- Each entry needs a UNIQUE id (a short string you generate; it does not need to match anything). Do not reuse another entry's id.",
+    "- Reference a code component with \"codeComponentId\" and a built-in theme component with \"componentId\" — not the other way around. Use \"propValues\" (not \"props\").",
+    "- Child ids are opaque — take them from get_section_template / list_imported_sections; never invent them.",
+    "- Auto-import: a referenced child that is BUILT but not yet imported is imported automatically (returned under autoImported). A child that is not built at all errors — build it first.",
+    "",
+    "## Reading prop schemas (avoid guessing)",
+    "- get_component_props(componentId) → a component's props with types, required, default, ENUM `options` (the valid values to set), and COMPONENT_LIST `allowedComponentIds` (valid children). Works for any section OR child id. Use it BEFORE filling — to know prop names, enum values, and which children a slot allows — instead of guessing or reading ikas.config.json.",
+    "- For a COMPONENT_LIST: get_component_props(parent) → its allowedComponentIds → get_component_props(child) → the child's props/enums. Then build the components array.",
+    "- get_section_values(element_id) → one placed section's current values (read-modify-write of a COMPONENT_LIST, or to copy an existing value's exact shape).",
+    "- Real entity ids/images: search_products returns productId + variantId + imageSrc (the product image URL). To use that image in an IMAGE prop, you can't reuse a product image id — upload it: upload_image(image_url: imageSrc) → use the returned id. list_categories/list_brands/list_blogs/list_blog_categories return the entity ids; to LINK to one, also call get_page_by_type('<TYPE>') for the page id and build a PAGE link { linkType:'PAGE', pageId, pageType, itemId:<entityId>, id, label }. IMPORTANT: if get_page_by_type returns pageId:null, that dynamic page does NOT exist in the theme yet — do NOT guess a slug/EXTERNAL URL. Call create_page('<TYPE>') to add it (non-CUSTOM types are unique and returned as-is if already present), then use the returned pageId to build the PAGE link. Always have a real pageId before building a PAGE link.",
+    "",
+    "## Validation",
+    "Values are validated server-side (deeply, including nested children). Wrong shape or wrong semantics (double-encoded string, { value } wrapper on an object prop, props vs propValues, missing/duplicate id, wrong reference key, nonexistent component id, unknown prop name) are REJECTED with an explanatory error instead of being stored silently. Read the error and fix the value; if unsure of a shape, read it with get_section_values and match it.",
+].join("\n");
+server.tool("get_editor_workflow", "Read this FIRST when the user wants to place a section on a page or fill/edit a section's content (text, image, link, slides, component lists) in the live editor. Returns the complete step-by-step workflow for the live-editor tools (list_editor_pages, list_imported_sections, import_section, add_section_to_page, list_page_sections, update_section_prop, upload_image), the per-prop-type value shapes, the COMPONENT_LIST read-modify-write rules, and how validation/auto-import behave. Use it to avoid the common mistake of writing component code to set a value a section already supports.", {}, async () => {
+    return { content: [{ type: "text", text: EDITOR_WORKFLOW_GUIDE }] };
+});
+// Tool: list_theme_globals
+server.tool("list_theme_globals", "List the theme's global settings from the connected editor: global variables (Theme Settings) and design tokens (colors, typography, breakpoints, keyframes, color schemes). Call this BEFORE generating sections/components so you reuse the theme's existing variables and tokens (read them in component code via `getThemeSetting`/`getThemeColors`/... from `@ikas/bp-storefront`). Includes items created manually in the editor UI. Requires `ikas-component dev` running with the editor connected.", {
+    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-theme-globals", ...(port ? ["--port", String(port)] : [])];
+    return callEditorAction(project_root, args);
+});
+// Tool: create_theme_global
+server.tool("create_theme_global", "Create a theme global setting in the connected editor. `kind` selects what to create:\n" +
+    "- globalVariable: requires display_name + type (TEXT|RICH_TEXT|IMAGE|COLOR|NUMBER|BOOLEAN|BORDER|SHADOW); value optional. Value shapes — TEXT/COLOR: string; RICH_TEXT: HTML string; NUMBER: number; BOOLEAN: boolean; IMAGE: { url } object; BORDER: { width: { value, unit }, style, color }; SHADOW: { x, y, blur, spread, color, position: \"outside\"|\"inside\" }.\n" +
+    "- color: requires name + value (hex, e.g. \"#ff0000\").\n" +
+    "- typography: requires name + at least one of font_family/font_size/font_weight/line_height/letter_spacing.\n" +
+    "- breakpoint: requires name + width (px).\n" +
+    "- keyframe: requires name + points (array of { point, styles? }) where each style is { property, value } using a CSS property name (opacity, transform, filter, background, color, …); keyframe_type defaults to \"keyframe\". Use the keyframe's `ref` as a CSS animation-name and set timing (duration/iteration) where you apply it.\n" +
+    "- colorScheme: requires name + colors (array of { key, value }) — `key` is the color slot name (e.g. Background, Text, Primary); slots are created automatically if missing.\n" +
+    "Read created items back with `list_theme_globals`. Requires `ikas-component dev` running with the editor connected.", {
+    project_root: z.string().describe("Absolute path to the code-component project."),
+    kind: z
+        .enum(["globalVariable", "color", "typography", "breakpoint", "keyframe", "colorScheme"])
+        .describe("What to create."),
+    name: z.string().optional().describe("Name (design tokens)."),
+    display_name: z.string().optional().describe("Human label (globalVariable)."),
+    type: z.string().optional().describe("globalVariable value type."),
+    value: z.any().optional().describe("globalVariable default value (shape depends on type — see tool description), or color hex string."),
+    font_family: z.string().optional(),
+    font_size: z.string().optional(),
+    font_weight: z.string().optional(),
+    line_height: z.string().optional(),
+    letter_spacing: z.string().optional(),
+    width: z.number().optional().describe("breakpoint width in px."),
+    keyframe_type: z.enum(["keyframe", "transition"]).optional(),
+    points: z.any().optional().describe("keyframe points array."),
+    colors: z.any().optional().describe("colorScheme colors: array of { key, value } (key = color slot name)."),
+    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+}, async (input) => {
+    const p = input.port ? ["--port", String(input.port)] : [];
+    let args;
+    switch (input.kind) {
+        case "globalVariable":
+            args = [
+                "create-global-variable",
+                "--display-name",
+                String(input.display_name ?? ""),
+                "--type",
+                String(input.type ?? ""),
+                ...(input.value !== undefined ? ["--value", JSON.stringify(input.value)] : []),
+                ...p,
+            ];
+            break;
+        case "color":
+            args = ["create-color", "--name", String(input.name ?? ""), "--value", String(input.value ?? ""), ...p];
+            break;
+        case "typography":
+            args = [
+                "create-text-style",
+                "--name",
+                String(input.name ?? ""),
+                ...(input.font_family ? ["--font-family", input.font_family] : []),
+                ...(input.font_size ? ["--font-size", input.font_size] : []),
+                ...(input.font_weight ? ["--font-weight", input.font_weight] : []),
+                ...(input.line_height ? ["--line-height", input.line_height] : []),
+                ...(input.letter_spacing ? ["--letter-spacing", input.letter_spacing] : []),
+                ...p,
+            ];
+            break;
+        case "breakpoint":
+            args = ["create-breakpoint", "--name", String(input.name ?? ""), "--width", String(input.width ?? ""), ...p];
+            break;
+        case "keyframe":
+            args = [
+                "create-keyframe",
+                "--name",
+                String(input.name ?? ""),
+                ...(input.keyframe_type ? ["--type", input.keyframe_type] : []),
+                "--points",
+                JSON.stringify(input.points ?? []),
+                ...p,
+            ];
+            break;
+        case "colorScheme":
+            args = [
+                "create-color-scheme",
+                "--name",
+                String(input.name ?? ""),
+                "--colors",
+                JSON.stringify(input.colors ?? []),
+                ...p,
+            ];
+            break;
+        default:
+            return { content: [{ type: "text", text: `Error: unknown kind "${input.kind}"` }] };
+    }
+    return callEditorAction(input.project_root, args);
+});
+// Tool: update_theme_global
+server.tool("update_theme_global", "Update an existing global variable in the connected editor (e.g. fix its value or change its type). Identify it by `name` (the runtime key from `list_theme_globals`). Only the fields you pass are changed. Value shapes follow `create_theme_global`.", {
+    project_root: z.string().describe("Absolute path to the code-component project."),
+    name: z.string().describe("The variable's runtime key (from `list_theme_globals`)."),
+    display_name: z.string().optional().describe("New label."),
+    type: z.string().optional().describe("New value type (TEXT|RICH_TEXT|IMAGE|COLOR|NUMBER|BOOLEAN|BORDER|SHADOW)."),
+    value: z.any().optional().describe("New value (shape depends on type)."),
+    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, name, display_name, type, value, port }) => {
+    const args = [
+        "update-global-variable",
+        "--name",
+        name,
+        ...(display_name !== undefined ? ["--display-name", display_name] : []),
+        ...(type !== undefined ? ["--type", type] : []),
+        ...(value !== undefined ? ["--value", JSON.stringify(value)] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: delete_theme_global
+server.tool("delete_theme_global", "Delete a theme global setting from the connected editor. For `kind: globalVariable` pass `name` (the runtime key); for design-token kinds (color | typography | breakpoint | keyframe | colorScheme) pass the token `id`. Get names/ids from `list_theme_globals`.", {
+    project_root: z.string().describe("Absolute path to the code-component project."),
+    kind: z
+        .enum(["globalVariable", "color", "typography", "breakpoint", "keyframe", "colorScheme"])
+        .describe("What to delete."),
+    name: z.string().optional().describe("globalVariable runtime key (from `list_theme_globals`)."),
+    id: z.string().optional().describe("design-token id (from `list_theme_globals`)."),
+    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, kind, name, id, port }) => {
+    const p = port ? ["--port", String(port)] : [];
+    const args = kind === "globalVariable"
+        ? ["delete-global-variable", "--name", String(name ?? ""), ...p]
+        : ["delete-design-token", "--token-type", kind, "--id", String(id ?? ""), ...p];
+    return callEditorAction(project_root, args);
+});
 // --- Start server ---
 async function main() {
     const transport = new StdioServerTransport();