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

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("");
-    parts.push(`This file is the **source of truth** for the migration. All sessions must read it before starting work.`);
+    parts.push(`**Source:** ${components.length} old components, ${customData.filter((cd) => cd.isRoot).length} custom data types, ${(theme.pages || []).length} pages`);
     parts.push("");
-    parts.push(`## Status Legend`);
-    parts.push(`- \`[ ]\` Not started`);
-    parts.push(`- \`[~]\` In progress`);
-    parts.push(`- \`[x]\` Complete`);
+    parts.push(`> ## READ THIS FIRST`);
+    parts.push(`>`);
+    parts.push(`> This file is your responsibility from here. The MCP wrote this initial scaffold **once**. You own all updates — no MCP tool will modify this file again.`);
+    parts.push(`>`);
+    parts.push(`> 1. **Tick checkboxes** as you finish work. Use \`[~]\` for in-progress and \`[x]\` for done. Edit the file directly with your file-editing tools.`);
+    parts.push(`> 2. **theme.json is incomplete.** Atomic components (Button, Input, Card, icons, etc.) often live only in \`src/\` and are NOT referenced from theme.json. Before you start section migration, scan the old source directory and ADD entries to this file for anything the initial scan missed — list them under \`## Source Code Analysis\` and add shared ones to \`### Shared Sub-Components\`.`);
+    parts.push(`> 3. **Custom data types are NOT pre-converted.** For each customData entry used by a section, decide enum-vs-component when you migrate that section. Log every decision in \`## Custom Data Decisions\` with reasoning. See \`get_migration_guide("custom-data-conversion")\` for the heuristic.`);
+    parts.push(`> 4. **Preserve feature parity. Do NOT silently simplify or drop features.** If an old prop has richer fields than a new built-in prop type can carry (e.g. a navigation link with a per-link image), the answer is to build a child component — never to flatten and "add it later." Later doesn't come. If the user explicitly wants a feature removed, log that as an explicit decision in \`## Notes\`; otherwise migrate to functional parity.`);
+    parts.push(`> 5. **Per-section work:** call \`get_section_migration_plan({theme_json_path, section_name, project_name: "${projectName}"})\` for each section. The MCP returns concrete CLI commands and flags any customData-referencing props with a "Decide: enum or component?" callout.`);
+    parts.push(`> 6. **If you discover new shared sub-components mid-migration**, add them under \`### Shared Sub-Components\` and any notes under \`## Notes\`.`);
+    parts.push(`>`);
+    parts.push(`> Status legend: \`[ ]\` not started · \`[~]\` in progress · \`[x]\` complete.`);
     parts.push("");
     parts.push(`## Foundation`);
     parts.push("");
@@ -537,27 +625,9 @@ function generateMigrationPlan(theme, projectName, oldSourceDir) {
         parts.push(`- [ ] ${settings.fontFamily.name} (weights: ${settings.fontFamily.variants?.join(", ") || "default"})`);
         parts.push("");
     }
-    // Custom Enums
-    const enumCustomData = customData.filter(cd => cd.type === "ENUM" && cd.isRoot);
-    if (enumCustomData.length > 0) {
-        parts.push(`### Custom Enums (run these BEFORE any \`config add-component\`)`);
-        parts.push("");
-        for (const cd of enumCustomData) {
-            const enumName = cd.typescriptName || (cd.name ? cd.name.replace(/[^a-zA-Z0-9]/g, "") : "Enum");
-            const options = (cd.enumOptions || []).reduce((acc, o) => {
-                if (o.displayName && o.value)
-                    acc[o.displayName] = o.value;
-                return acc;
-            }, {});
-            const optionsStr = JSON.stringify(options);
-            parts.push(`- [ ] **${enumName}**`);
-            parts.push(`  \`\`\`bash`);
-            parts.push(`  npx ikas-component config add-enum --name "${enumName}" --options '${optionsStr}'`);
-            parts.push(`  \`\`\``);
-            parts.push(`  Save the returned \`enumId\` and update this file with: \`enumId: <id>\``);
-        }
-        parts.push("");
-    }
+    // (Custom Enums foundation subsection intentionally removed — see ## Custom Data Types below.
+    // Old customData entries are NOT pre-migrated as enums; each is a per-section decision.
+    // See get_migration_guide("custom-data-conversion") for the enum-vs-component heuristic.)
     // Shared sub-components
     if (sharedSubs.length > 0) {
         parts.push(`### Shared Sub-Components (→ \`src/sub-components/\`)`);
@@ -581,10 +651,61 @@ function generateMigrationPlan(theme, projectName, oldSourceDir) {
         parts.push(`_Old source directory not provided — shared sub-components cannot be detected automatically. If you have access to the old source, call \`plan_migration\` again with \`old_source_dir\` to populate this section._`);
         parts.push("");
     }
+    parts.push(`> **This scan is partial.** \`scanSharedSubcomponents\` only detects relative imports used by **3 or more** old components. Atomic components used by fewer sections (often Button/Input/Card/icon primitives) will be missed. Scan \`src/\` yourself and add any others under \`## Source Code Analysis\` below.`);
+    parts.push("");
+    // Custom Data Types — deferred decisions (reference list, not checkboxes)
+    const rootCustomData = customData.filter((cd) => cd.isRoot);
+    if (rootCustomData.length > 0) {
+        // Build a usage map: which sections reference each customData type
+        const usageByCustomDataId = new Map();
+        for (const comp of components) {
+            const sectionName = comp.displayName || comp.dir || comp.id || "?";
+            for (const p of comp.props || []) {
+                if (p.type === "CUSTOM" && p.customDataId) {
+                    const list = usageByCustomDataId.get(p.customDataId) || [];
+                    if (!list.includes(sectionName))
+                        list.push(sectionName);
+                    usageByCustomDataId.set(p.customDataId, list);
+                }
+            }
+        }
+        parts.push(`### Custom Data Types — decide during section migration`);
+        parts.push("");
+        parts.push(`Each entry below is an OLD \`theme.customData[]\` type. Do **not** pre-migrate these as enums. When you migrate the section that uses one, decide:`);
+        parts.push(`- **Flat scalar set** (e.g. \`"left" | "right" | "center"\`) → new-system **enum prop** via \`config add-enum\`.`);
+        parts.push(`- **Structured record** (e.g. \`{image, link, title}\`, repeated in a list) → new-system **component** via \`config add-component\` + COMPONENT_LIST wiring on the parent.`);
+        parts.push("");
+        parts.push(`Log every decision in \`## Custom Data Decisions\` below. See \`get_migration_guide("custom-data-conversion")\` for the full heuristic and worked examples (Position, Slide, MenuItem).`);
+        parts.push("");
+        for (const cd of rootCustomData) {
+            const cdName = cd.typescriptName || cd.name || cd.id || "Unknown";
+            const cdType = cd.type || "?";
+            let shape = "";
+            if (cd.type === "ENUM") {
+                const opts = (cd.enumOptions || [])
+                    .map((o) => o.value || o.displayName)
+                    .filter(Boolean);
+                shape = ` — shape: \`enum {${opts.slice(0, 6).join(", ")}${opts.length > 6 ? ", ..." : ""}}\``;
+            }
+            else if (cd.nestedData && cd.nestedData.length > 0) {
+                const first = cd.nestedData[0];
+                const fields = (first?.nestedData || cd.nestedData || [])
+                    .map((f) => `${f.key || f.name || "?"}: ${f.type || "?"}`)
+                    .slice(0, 8);
+                shape = ` — shape: \`{${fields.join(", ")}}\``;
+            }
+            const usedBy = cd.id ? usageByCustomDataId.get(cd.id) || [] : [];
+            const usedByStr = usedBy.length > 0
+                ? ` — used by: ${usedBy.slice(0, 6).join(", ")}${usedBy.length > 6 ? `, +${usedBy.length - 6} more` : ""}`
+                : ` — _not directly referenced by any section's props (may be nested inside another customData)_`;
+            parts.push(`- \`${cdName}\` (${cdType})${shape}${usedByStr}`);
+        }
+        parts.push("");
+    }
     // Sections queue
     parts.push(`## Sections`);
     parts.push("");
-    parts.push(`Canonical component IDs are listed below — **use these exactly** when running \`config add-component\` and in \`filteredComponentIds\`. Do not change them mid-migration.`);
+    parts.push(`Component **names** are listed below. The CLI auto-generates opaque \`componentId\`s when you run \`config add-component\` — capture each id from the JSON response and use it (or look it up later with \`config list\`) when wiring \`filteredComponentIds\`.`);
     parts.push("");
     const buckets = {
         simple: [],
@@ -610,7 +731,11 @@ function generateMigrationPlan(theme, projectName, oldSourceDir) {
             const oldName = comp.displayName || comp.dir || comp.id || "Unknown";
             const kebabName = toKebabCase(comp.dir || comp.displayName || comp.id || "unknown");
             const newId = `${projectName}-${kebabName}`;
-            const headerFooter = comp.isHeader ? " **[HEADER]**" : comp.isFooter ? " **[FOOTER]**" : "";
+            const headerFooter = comp.isHeader
+                ? " **[HEADER]**"
+                : comp.isFooter
+                    ? " **[FOOTER]**"
+                    : "";
             const propCount = (comp.props || []).length;
             // Detect children from CUSTOM DYNAMIC_LIST props
             const children = [];
@@ -620,11 +745,14 @@ function generateMigrationPlan(theme, projectName, oldSourceDir) {
                     if (cd && (cd.type === "DYNAMIC_LIST" || cd.type === "STATIC_LIST")) {
                         const itemObj = cd.nestedData?.[0];
                         if (itemObj) {
-                            const childName = itemObj.typescriptName || (itemObj.name ? itemObj.name.replace(/[^a-zA-Z0-9]/g, "") : `${oldName}Item`);
-                            const childKebab = toKebabCase(childName);
-                            const childId = `${projectName}-${childKebab}`;
-                            const fields = (itemObj.nestedData || []).map((f) => f.key || f.name || "?").slice(0, 8);
-                            children.push({ propName: p.name || "?", childId, childName, fields });
+                            const childName = itemObj.typescriptName ||
+                                (itemObj.name
+                                    ? itemObj.name.replace(/[^a-zA-Z0-9]/g, "")
+                                    : `${oldName}Item`);
+                            const fields = (itemObj.nestedData || [])
+                                .map((f) => f.key || f.name || "?")
+                                .slice(0, 8);
+                            children.push({ propName: p.name || "?", childName, fields });
                         }
                     }
                 }
@@ -634,65 +762,73 @@ function generateMigrationPlan(theme, projectName, oldSourceDir) {
             if (children.length > 0) {
                 parts.push(`  - Children:`);
                 for (const ch of children) {
-                    parts.push(`    - [ ] \`${ch.childId}\` (\`${ch.childName}\`) — for prop \`${ch.propName}\` — fields: ${ch.fields.join(", ")}`);
+                    parts.push(`    - [ ] \`${ch.childName}\` — for prop \`${ch.propName}\` — fields: ${ch.fields.join(", ")}`);
                 }
             }
         }
         parts.push("");
     }
-    // Known Environmental Issues (agents fill in during work)
-    parts.push(`## Known Environmental Issues`);
+    // Source Code Analysis — placeholder for the LLM to fill in
+    parts.push(`## Source Code Analysis`);
     parts.push("");
-    parts.push(`_Agents working on this migration: record any non-component build/TS errors here so future sessions don't waste time diagnosing them._`);
+    parts.push(`> **Before starting section migration**, scan the old \`src/\` for components NOT listed above. theme.json does not see atomic primitives — buttons, inputs, cards, icon wrappers, layout helpers, etc. — that are imported by sections but never appear as theme components. Add them here, then decide which become shared sub-components vs which collapse into section bodies.`);
     parts.push("");
-    parts.push(`- [ ] _(none recorded yet)_`);
+    parts.push(`<!-- Example: \`- Button (src/atoms/Button/) — used by ~all sections → promote to Shared Sub-Component\` -->`);
+    parts.push("");
+    // Custom Data Decisions — append-only log the LLM fills as it makes per-section decisions
+    parts.push(`## Custom Data Decisions`);
     parts.push("");
-    // Usage section
-    parts.push(`## Per-Section Usage`);
+    parts.push(`> Log each customData enum-vs-component decision here as you encounter it during section migration. Format: \`- \\\`<CustomDataName>\\\` → enum/component \\\`<target name>\\\` (YYYY-MM-DD) — reasoning\`.`);
     parts.push("");
-    parts.push(`Once the Foundation is complete, for each section above:`);
+    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(`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).`);
+    // Known Environmental Issues (agents fill in during work)
+    parts.push(`## Known Environmental Issues`);
+    parts.push("");
+    parts.push(`_Record any non-component build/TS errors here so future sessions don't waste time diagnosing them._`);
+    parts.push("");
+    parts.push(`- [ ] _(none recorded yet)_`);
     parts.push("");
-    // Session Log — agents append notes here
-    parts.push(`## Session Log`);
+    // Notes — append-only log for decisions not captured elsewhere
+    parts.push(`## Notes`);
     parts.push("");
-    parts.push(`_Each agent: append a bullet after completing work. Format: \`- [YYYY-MM-DD] <section-id>: <brief note>\`. This is how future sessions learn about decisions not encoded in the plan structure._`);
+    parts.push(`_Append a bullet after completing work — library swaps, ad-hoc props, CLI folder-name oddities, user-approved feature drops, etc. Format: \`- [YYYY-MM-DD] <section-id>: <brief note>\`._`);
     parts.push("");
-    parts.push(`_After completing Foundation, also record which sub-components were built and which were skipped, e.g.:_`);
-    parts.push(`<!-- \`- [2026-04-15] Foundation: built Input, SubmitButton, Modal, SectionHeader, StarRating. Skipped: GoogleCaptcha (needs investigation), BlogCard, Pagination (low priority).\` -->`);
-    parts.push(`<!-- \`- [2026-04-15] ${projectName}-footer: swapped react-hot-toast for inline status text; newsletter uses form-model pattern (getNewsletterSubscriptionForm). CLI created folder as "Footer/" as expected.\` -->`);
+    parts.push(`<!-- Example: \`- [2026-04-15] ${projectName}-footer: swapped react-hot-toast for inline status text; CLI created Footer/ as expected\` -->`);
     parts.push("");
-    // Cross-references
+    // Cross-references — keep terse; LLM can call `get_migration_guide("list")` or `get_framework_guide("list")` for more
     parts.push(`## Cross-References`);
     parts.push("");
-    parts.push(`Essential MCP tools to call during migration:`);
+    parts.push(`- \`get_migration_guide("iterative-workflow")\` — the full per-phase protocol`);
+    parts.push(`- \`get_migration_guide("custom-data-conversion")\` — enum-vs-component decisions`);
+    parts.push(`- \`get_migration_guide("prop-runtime-shapes")\` — runtime shapes & access patterns`);
+    parts.push(`- \`get_framework_guide("common-pitfalls")\` — gotchas & old→new property migrations`);
     parts.push("");
-    parts.push(`- \`get_migration_guide("iterative-workflow")\` — full protocol for resumable migrations`);
-    parts.push(`- \`get_migration_guide("component-renderer-limitations")\` — critical constraints when using COMPONENT_LIST`);
-    parts.push(`- \`get_migration_guide("prop-runtime-shapes")\` — \`.data\` vs \`.links\`, \`.variant\` vs \`.product\`, etc.`);
-    parts.push(`- \`get_migration_guide("link-prop-decision-guide")\` — LINK vs LIST_OF_LINK vs COMPONENT_LIST`);
-    parts.push(`- \`get_migration_guide("library-replacements")\` — swiper, headlessui, tailwind, etc.`);
-    parts.push(`- \`get_migration_guide("react-to-preact")\` — observer rules, imports, IkasSlider removal`);
-    parts.push(`- \`get_framework_guide("component-renderer-patterns")\` — full IkasComponentRenderer usage`);
-    parts.push(`- \`get_framework_guide("common-pitfalls")\` — general gotchas`);
-    parts.push(`- \`get_framework_guide("navigation-patterns")\` — Router.navigate, Router.navigateToPage`);
-    parts.push(`- \`get_model_guide("<TypeName>")\` — IkasCart, IkasProduct, IkasCustomer shapes`);
+    parts.push(`Call \`get_migration_guide("list")\` or \`get_framework_guide("list")\` for the full topic catalog.`);
     parts.push("");
     return parts.join("\n");
 }
 // Known libraries we detect in old themes and want to flag for replacement
 const KNOWN_LIBRARIES = [
-    "swiper", "@headlessui/react", "@heroicons/react", "recharts",
-    "react-player", "react-simple-star-rating", "react-slider", "react-compound-slider",
-    "react-zoom-pan-pinch", "react-hot-toast", "react-fast-marquee",
-    "react-indiana-drag-scroll", "react-simple-typewriter", "react-timer-hook",
-    "date-fns", "slugify", "classnames", "clsx", "@react-pdf/renderer",
+    "swiper",
+    "@headlessui/react",
+    "@heroicons/react",
+    "recharts",
+    "react-player",
+    "react-simple-star-rating",
+    "react-slider",
+    "react-compound-slider",
+    "react-zoom-pan-pinch",
+    "react-hot-toast",
+    "react-fast-marquee",
+    "react-indiana-drag-scroll",
+    "react-simple-typewriter",
+    "react-timer-hook",
+    "date-fns",
+    "slugify",
+    "classnames",
+    "clsx",
+    "@react-pdf/renderer",
 ];
 // Heuristic: member-access patterns on old storefront stores/singletons that likely need new-system equivalents
 const OLD_STOREFRONT_CALL_REGEX = /\b(customerStore|cartStore|productStore|categoryStore|orderStore|searchStore|favoritesStore|i18nStore|Router|useStore)\.\w+/g;
@@ -711,7 +847,8 @@ function scanSectionSource(componentDir, propNames) {
     // Collect all .tsx/.ts files in the component dir
     try {
         for (const entry of fs.readdirSync(componentDir, { withFileTypes: true })) {
-            if (entry.isFile() && (entry.name.endsWith(".tsx") || entry.name.endsWith(".ts"))) {
+            if (entry.isFile() &&
+                (entry.name.endsWith(".tsx") || entry.name.endsWith(".ts"))) {
                 result.sourceFiles.push(path.join(componentDir, entry.name));
             }
         }
@@ -728,7 +865,18 @@ function scanSectionSource(componentDir, propNames) {
     const subCompSet = new Map();
     const callSet = new Set();
     // Packages we treat as "framework" and don't flag for replacement (but do note in reactPackageUsage)
-    const REACT_PACKAGES = new Set(["react", "react-dom", "next", "next/link", "next/image", "next/router", "next/head", "next/script", "mobx-react-lite", "mobx"]);
+    const REACT_PACKAGES = new Set([
+        "react",
+        "react-dom",
+        "next",
+        "next/link",
+        "next/image",
+        "next/router",
+        "next/head",
+        "next/script",
+        "mobx-react-lite",
+        "mobx",
+    ]);
     for (const file of result.sourceFiles) {
         let content;
         try {
@@ -742,7 +890,7 @@ function scanSectionSource(componentDir, propNames) {
         while ((m = importRegex.exec(content)) !== null) {
             const p = m[1];
             if (p.startsWith(".")) {
-                const segs = p.split("/").filter(s => s && s !== "." && s !== "..");
+                const segs = p.split("/").filter((s) => s && s !== "." && s !== "..");
                 const last = segs[segs.length - 1];
                 if (last && /^[A-Z]/.test(last) && !last.includes("__generated__")) {
                     subCompSet.set(last, p);
@@ -750,7 +898,9 @@ function scanSectionSource(componentDir, propNames) {
             }
             else if (!p.startsWith("@ikas/")) {
                 // Classify: known library, react-family, or unknown-external
-                const base = p.startsWith("@") ? p.split("/").slice(0, 2).join("/") : p.split("/")[0];
+                const base = p.startsWith("@")
+                    ? p.split("/").slice(0, 2).join("/")
+                    : p.split("/")[0];
                 if (REACT_PACKAGES.has(p) || REACT_PACKAGES.has(base)) {
                     reactSet.add(base);
                 }
@@ -813,7 +963,10 @@ function scanSectionSource(componentDir, propNames) {
             }
         }
     }
-    result.importedSubComponents = [...subCompSet.entries()].map(([name, p]) => ({ name, path: p }));
+    result.importedSubComponents = [...subCompSet.entries()].map(([name, p]) => ({
+        name,
+        path: p,
+    }));
     result.importedLibraries = [...libSet].sort();
     result.importedUnknownLibraries = [...unknownLibSet].sort();
     result.reactPackageUsage = [...reactSet].sort();
@@ -829,34 +982,45 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
             customDataMap.set(cd.id, cd);
     }
     // Find the component — try match by dir, displayName, id, or new-id
-    const target = components.find(c => {
+    const target = components.find((c) => {
         if (!c)
             return false;
-        if (c.dir === sectionName || c.displayName === sectionName || c.id === sectionName)
+        if (c.dir === sectionName ||
+            c.displayName === sectionName ||
+            c.id === sectionName)
             return true;
         const kebab = toKebabCase(c.dir || c.displayName || c.id || "");
         const newId = `${projectName}-${kebab}`;
         return newId === sectionName;
     });
     if (!target) {
-        const available = components.map(c => c.dir || c.displayName || c.id).filter(Boolean).join(", ");
+        const available = components
+            .map((c) => c.dir || c.displayName || c.id)
+            .filter(Boolean)
+            .join(", ");
         return `Section "${sectionName}" not found in theme. Available: ${available}`;
     }
     const parts = [];
     const oldName = target.displayName || target.dir || target.id || "Unknown";
     const kebabName = toKebabCase(target.dir || target.displayName || target.id || "unknown");
     const sectionId = `${projectName}-${kebabName}`;
-    const sectionPascal = (target.dir || target.displayName || "").replace(/[^a-zA-Z0-9]/g, "") || kebabName.split("-").map(s => s[0]?.toUpperCase() + s.slice(1)).join("");
+    const sectionPascal = (target.dir || target.displayName || "").replace(/[^a-zA-Z0-9]/g, "") ||
+        kebabName
+            .split("-")
+            .map((s) => s[0]?.toUpperCase() + s.slice(1))
+            .join("");
     // Scan the old source for imports, libraries, field usage
-    const propNames = (target.props || []).map(p => p.name || "").filter(Boolean);
-    const sourceScan = (oldSourceDir && target.dir)
+    const propNames = (target.props || [])
+        .map((p) => p.name || "")
+        .filter(Boolean);
+    const sourceScan = oldSourceDir && target.dir
         ? scanSectionSource(path.join(oldSourceDir, target.dir), propNames)
         : null;
     parts.push(`# Section Migration Plan: ${oldName}`);
     parts.push("");
     parts.push(`**Old name:** \`${oldName}\` (dir: \`${target.dir || "?"}\`)`);
-    parts.push(`**New section ID:** \`${sectionId}\``);
-    parts.push(`**New section name:** \`${sectionPascal}\``);
+    parts.push(`**New section name:** \`${sectionPascal}\` (the CLI will assign an opaque \`componentId\` at write-time — capture it from \`config add-component\`'s JSON response)`);
+    parts.push(`**Migration checkbox label:** \`${sectionId}\` (tracking identifier in \`MIGRATION.md\` only — not the runtime component id)`);
     if (target.isHeader)
         parts.push(`**Flags:** HEADER (\`isHeader: true\`)`);
     if (target.isFooter)
@@ -895,7 +1059,7 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
         }
         if (sourceScan.reactPackageUsage.length > 0) {
             parts.push("");
-            parts.push(`**React/Next.js framework imports detected:** ${sourceScan.reactPackageUsage.map(p => `\`${p}\``).join(", ")}. These do NOT carry over — the new system is Preact. See \`get_migration_guide("react-to-preact")\` for conversion patterns (hooks, observer, event types, routing).`);
+            parts.push(`**React/Next.js framework imports detected:** ${sourceScan.reactPackageUsage.map((p) => `\`${p}\``).join(", ")}. These do NOT carry over — the new system is Preact. See \`get_migration_guide("react-to-preact")\` for conversion patterns (hooks, observer, event types, routing).`);
         }
         if (sourceScan.oldStorefrontCalls.length > 0) {
             parts.push("");
@@ -941,7 +1105,11 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
         if (oldType === "SLIDER") {
             newType = "NUMBER";
             notes = `Was SLIDER(min=${p.sliderData?.min}, max=${p.sliderData?.max}) — replace \`.value\` access with direct number`;
-            const prop = { name: newName, displayName: p.displayName || newName, type: "NUMBER" };
+            const prop = {
+                name: newName,
+                displayName: p.displayName || newName,
+                type: "NUMBER",
+            };
             if (p.isRequired)
                 prop.required = true;
             parentPropsJson.push(prop);
@@ -949,7 +1117,11 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
         else if (oldType === "PRODUCT_DETAIL") {
             newType = "PRODUCT";
             notes = "Renamed — PRODUCT_DETAIL → PRODUCT";
-            const prop = { name: newName, displayName: p.displayName || newName, type: "PRODUCT" };
+            const prop = {
+                name: newName,
+                displayName: p.displayName || newName,
+                type: "PRODUCT",
+            };
             if (p.isRequired)
                 prop.required = true;
             parentPropsJson.push(prop);
@@ -960,9 +1132,10 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
                 if (cd.type === "DYNAMIC_LIST" || cd.type === "STATIC_LIST") {
                     // Child component needed
                     const itemObj = cd.nestedData?.[0];
-                    const childName = itemObj?.typescriptName || (itemObj?.name ? itemObj.name.replace(/[^a-zA-Z0-9]/g, "") : `${sectionPascal}Item`);
-                    const childKebab = toKebabCase(childName);
-                    const childId = `${projectName}-${childKebab}`;
+                    const childName = itemObj?.typescriptName ||
+                        (itemObj?.name
+                            ? itemObj.name.replace(/[^a-zA-Z0-9]/g, "")
+                            : `${sectionPascal}Item`);
                     const childProps = [];
                     const nestedWarnings = [];
                     for (const f of (itemObj?.nestedData || [])) {
@@ -973,11 +1146,18 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
                             fType = "NUMBER";
                         else if (fType === "PRODUCT_DETAIL")
                             fType = "PRODUCT";
-                        else if (fType === "CUSTOM" || fType === "DYNAMIC_LIST" || fType === "STATIC_LIST" || fType === "OBJECT") {
+                        else if (fType === "CUSTOM" ||
+                            fType === "DYNAMIC_LIST" ||
+                            fType === "STATIC_LIST" ||
+                            fType === "OBJECT") {
                             nestedWarnings.push(`\`${f.key}\` (${fType})`);
                             fType = "COMPONENT_LIST";
                         }
-                        const prop = { name: f.key, displayName: f.name || f.key, type: fType };
+                        const prop = {
+                            name: f.key,
+                            displayName: f.name || f.key,
+                            type: fType,
+                        };
                         if (f.isRequired)
                             prop.required = true;
                         childProps.push(prop);
@@ -989,26 +1169,29 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
                     if (childProps.length === 0 && sourceScan?.propFieldUsage[oldName]) {
                         const inferred = sourceScan.propFieldUsage[oldName];
                         for (const fieldName of inferred) {
-                            childProps.push({ name: fieldName, displayName: fieldName, type: "TEXT" });
+                            childProps.push({
+                                name: fieldName,
+                                displayName: fieldName,
+                                type: "TEXT",
+                            });
                         }
                         if (inferred.length > 0) {
-                            notes = `Was CUSTOM → ${cd.type} with empty customData. **Inferred props from source usage:** ${inferred.map(f => `\`${f}\``).join(", ")}. Verify types and required flags — default inferred type is TEXT.`;
+                            notes = `Was CUSTOM → ${cd.type} with empty customData. **Inferred props from source usage:** ${inferred.map((f) => `\`${f}\``).join(", ")}. Verify types and required flags — default inferred type is TEXT.`;
                         }
                     }
                     children.push({
                         propName: oldName,
-                        childId,
                         childName,
                         childPropsJson: childProps,
                         customDataName: cd.name || "unnamed",
                     });
                     newType = "COMPONENT_LIST";
-                    notes = `Was CUSTOM → ${cd.type} of ${itemObj?.typescriptName || "object"}. Create child component \`${childId}\`.`;
+                    notes = `Was CUSTOM → ${cd.type} of ${itemObj?.typescriptName || "object"}. Create child component \`${childName}\`; the CLI returns the opaque \`componentId\` in its JSON response — substitute it for the \`<id-of-${childName}>\` placeholder below.`;
                     const prop = {
                         name: newName,
                         displayName: p.displayName || newName,
                         type: "COMPONENT_LIST",
-                        filteredComponentIds: [childId],
+                        filteredComponentIds: [`<id-of-${childName}>`],
                     };
                     parentPropsJson.push(prop);
                 }
@@ -1022,7 +1205,11 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
                             let fType = f.type;
                             if (fType === "SLIDER")
                                 fType = "NUMBER";
-                            const prop = { name: f.key, displayName: f.name || f.key, type: fType };
+                            const prop = {
+                                name: f.key,
+                                displayName: f.name || f.key,
+                                type: fType,
+                            };
                             if (f.isRequired)
                                 prop.required = true;
                             parentPropsJson.push(prop);
@@ -1037,7 +1224,8 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
                 }
                 else if (cd.type === "ENUM") {
                     newType = "ENUM";
-                    const enumName = cd.typescriptName || (cd.name ? cd.name.replace(/[^a-zA-Z0-9]/g, "") : "Enum");
+                    const enumName = cd.typescriptName ||
+                        (cd.name ? cd.name.replace(/[^a-zA-Z0-9]/g, "") : "Enum");
                     const options = (cd.enumOptions || []).reduce((acc, o) => {
                         if (o.displayName && o.value)
                             acc[o.displayName] = o.value;
@@ -1045,7 +1233,12 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
                     }, {});
                     enumsNeeded.push({ name: enumName, options });
                     notes = `Was CUSTOM (ENUM) — create enum \`${enumName}\` via \`config add-enum\` first, then reference its enumId here`;
-                    const prop = { name: newName, displayName: p.displayName || newName, type: "ENUM", enumTypeId: `<ENUM_ID_FROM_add-enum_${enumName}>` };
+                    const prop = {
+                        name: newName,
+                        displayName: p.displayName || newName,
+                        type: "ENUM",
+                        enumTypeId: `<ENUM_ID_FROM_add-enum_${enumName}>`,
+                    };
                     if (p.isRequired)
                         prop.required = true;
                     parentPropsJson.push(prop);
@@ -1054,7 +1247,11 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
         }
         else {
             // Direct mapping
-            const prop = { name: newName, displayName: p.displayName || newName, type: newType };
+            const prop = {
+                name: newName,
+                displayName: p.displayName || newName,
+                type: newType,
+            };
             if (p.isRequired)
                 prop.required = true;
             parentPropsJson.push(prop);
@@ -1062,6 +1259,131 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
         parts.push(`| \`${oldName}\` | ${oldType} | → | \`${newName}\` | ${newType} | ${notes} |`);
     }
     parts.push("");
+    // Custom Data Decision Callouts — per prop referencing a customData type
+    const customDataPropsForCallouts = (target.props || []).filter((p) => p.type === "CUSTOM" &&
+        p.customDataId &&
+        customDataMap.has(p.customDataId));
+    if (customDataPropsForCallouts.length > 0) {
+        parts.push(`## Custom Data Decisions to Make`);
+        parts.push("");
+        parts.push(`Each prop below references an old \`customData\` type. Verify the MCP's default against the actual data semantics, then run the CLI command. **Log every decision in MIGRATION.md → \`## Custom Data Decisions\`** with reasoning. See \`get_migration_guide("custom-data-conversion")\` for the heuristic and worked examples.`);
+        parts.push("");
+        for (const p of customDataPropsForCallouts) {
+            const cd = customDataMap.get(p.customDataId);
+            if (!cd)
+                continue;
+            const cdName = cd.typescriptName || cd.name || cd.id || "Unknown";
+            const cdType = cd.type || "?";
+            let shape = "";
+            let shapeKind = "unknown";
+            if (cd.type === "ENUM") {
+                const opts = (cd.enumOptions || [])
+                    .map((o) => o.value || o.displayName)
+                    .filter(Boolean);
+                shape = `enum {${opts.slice(0, 6).join(", ")}${opts.length > 6 ? ", ..." : ""}}`;
+                shapeKind = "enum";
+            }
+            else if (cd.type === "DYNAMIC_LIST" || cd.type === "STATIC_LIST") {
+                const first = cd.nestedData?.[0];
+                const fields = (first?.nestedData || []).map((f) => `${f.key || f.name || "?"}: ${f.type || "?"}`);
+                shape = `${cdType} of {${fields.slice(0, 6).join(", ")}}`;
+                shapeKind = "list";
+            }
+            else if (cd.type === "OBJECT") {
+                const fields = (cd.nestedData || []).map((f) => `${f.key || f.name || "?"}: ${f.type || "?"}`);
+                shape = `OBJECT {${fields.slice(0, 6).join(", ")}}`;
+                shapeKind = "record";
+            }
+            else {
+                shape = cdType;
+            }
+            // Build the field source + names list once so we can use it for the lost-fields enumeration
+            // AND for the component-path CLI template.
+            const fieldSource = cd.type === "DYNAMIC_LIST" || cd.type === "STATIC_LIST"
+                ? cd.nestedData?.[0]?.nestedData || []
+                : cd.nestedData || [];
+            const fieldDescriptions = fieldSource
+                .filter((f) => f.key)
+                .map((f) => `\`${f.key}\` (${f.type || "?"})`);
+            parts.push(`### Prop \`${p.name || "?"}\` → customData \`${cdName}\``);
+            parts.push("");
+            parts.push(`**Shape:** \`${shape}\``);
+            parts.push("");
+            if (shapeKind === "enum") {
+                parts.push(`**Default: enum prop.** Flat scalar set; use \`config add-enum\`.`);
+                parts.push("");
+                const enumName = cd.typescriptName ||
+                    (cd.name ? cd.name.replace(/[^a-zA-Z0-9]/g, "") : "Enum");
+                const enumOptions = (cd.enumOptions || []).reduce((acc, o) => {
+                    if (o.displayName && o.value)
+                        acc[o.displayName] = o.value;
+                    return acc;
+                }, {});
+                parts.push("```bash");
+                parts.push(`npx ikas-component config add-enum --name "${enumName}" --options '${JSON.stringify(enumOptions)}'`);
+                parts.push("```");
+                parts.push("");
+                parts.push(`If you believe this should be a component instead (e.g. each option secretly carries richer data not visible in the customData shape), see \`get_migration_guide("custom-data-conversion")\`.`);
+                parts.push("");
+            }
+            else if (shapeKind === "list" || shapeKind === "record") {
+                const fieldCount = fieldDescriptions.length;
+                const isMinimal = fieldCount > 0 && fieldCount <= 2;
+                if (isMinimal) {
+                    parts.push(`⚠️ **This child would have only ${fieldCount} field${fieldCount === 1 ? "" : "s"}** (${fieldDescriptions.join(", ")}). \`COMPONENT_LIST\` is usually overkill at this size. **Prefer one of:**`);
+                    parts.push(`- repeated scalar props on the parent (\`title1\`/\`link1\`, \`title2\`/\`link2\`, …) for a small fixed count`);
+                    parts.push(`- a domain LIST prop type (\`LIST_OF_LINK\`, \`IMAGE_LIST\`, \`PRODUCT_LIST\`, …) when each item IS one domain object`);
+                    parts.push(`- \`COMPONENT_LIST\` (CLI command below) only if reordering in the editor is a real UX win`);
+                    parts.push("");
+                    parts.push(`See \`get_migration_guide("component-composition-decision-guide")\` for the full tree. Log your choice in MIGRATION.md → \`## Custom Data Decisions\`.`);
+                    parts.push("");
+                }
+                else {
+                    parts.push(`**Default: component + COMPONENT_LIST.** Multiple fields per item — a single enum value cannot carry this structure.`);
+                    parts.push("");
+                    if (fieldCount > 0) {
+                        parts.push(`⚠️ **Fields you would lose if you flatten this:** ${fieldDescriptions.join(", ")}. Flattening to a simpler prop type drops these from the editor UI permanently. **Do not "simplify for later"** — if the feature genuinely isn't wanted, log that explicitly in MIGRATION.md → \`## Notes\` with reasoning. Otherwise build the component.`);
+                        parts.push("");
+                    }
+                    parts.push(`> See \`get_migration_guide("component-composition-decision-guide")\` for when \`COMPONENT_LIST\` is overkill.`);
+                    parts.push("");
+                }
+                const compName = cd.typescriptName ||
+                    (cd.name
+                        ? cd.name.replace(/[^a-zA-Z0-9]/g, "")
+                        : `${sectionPascal}Item`);
+                const compPropsForCli = [];
+                for (const f of fieldSource) {
+                    if (!f.key)
+                        continue;
+                    let fType = f.type;
+                    if (fType === "SLIDER")
+                        fType = "NUMBER";
+                    else if (fType === "PRODUCT_DETAIL")
+                        fType = "PRODUCT";
+                    compPropsForCli.push({
+                        name: f.key,
+                        displayName: f.name || f.key,
+                        type: fType,
+                    });
+                }
+                parts.push("```bash");
+                if (isMinimal) {
+                    parts.push(`# Fallback: COMPONENT_LIST (use only if the simpler alternatives above don't fit)`);
+                }
+                parts.push(`npx ikas-component config add-component --name "${compName}" --type component --props '${JSON.stringify(compPropsForCli)}'`);
+                parts.push(`# Then on the parent, set the prop's filteredComponentIds to the new component's id.`);
+                parts.push("```");
+                parts.push("");
+                parts.push(`If you believe this should be an enum despite the structure, see \`get_migration_guide("custom-data-conversion")\`.`);
+                parts.push("");
+            }
+            else {
+                parts.push(`**Unable to classify automatically — you decide.** See \`get_migration_guide("custom-data-conversion")\` for the enum-vs-component heuristic.`);
+                parts.push("");
+            }
+        }
+    }
     // Enums to create first
     if (enumsNeeded.length > 0) {
         parts.push(`## 3. Create Enums FIRST (if not already done)`);
@@ -1074,15 +1396,18 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
         parts.push(`Save the returned \`enumId\` values and substitute them in the parent config JSON below.`);
         parts.push("");
     }
-    // Child CLI commands — dedupe by childId (same shape may be referenced by multiple parent props)
+    // Child CLI commands — dedupe by childName (same shape may be referenced by multiple parent props)
     const uniqueChildren = new Map();
     for (const ch of children) {
-        const existing = uniqueChildren.get(ch.childId);
+        const existing = uniqueChildren.get(ch.childName);
         if (existing) {
             existing.usedByProps.push(ch.propName);
         }
         else {
-            uniqueChildren.set(ch.childId, { child: ch, usedByProps: [ch.propName] });
+            uniqueChildren.set(ch.childName, {
+                child: ch,
+                usedByProps: [ch.propName],
+            });
         }
     }
     if (uniqueChildren.size > 0) {
@@ -1090,17 +1415,19 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
         parts.push("");
         parts.push(`These children are referenced by the parent's COMPONENT_LIST props. Create them before the parent.`);
         parts.push(`**Deduped:** run each \`add-component\` command ONCE even if multiple parent props reference the same child.`);
+        parts.push(`**Capture each \`componentId\` from the CLI's JSON response** — you'll substitute these ids for the \`<id-of-{ChildName}>\` placeholders in the parent's \`filteredComponentIds\` below.`);
         parts.push("");
         for (const { child: ch, usedByProps } of uniqueChildren.values()) {
-            parts.push(`### \`${ch.childId}\` (\`${ch.childName}\`)`);
+            parts.push(`### \`${ch.childName}\``);
             const propsLabel = usedByProps.length > 1
-                ? `Used by parent props: ${usedByProps.map(p => `\`${p}\``).join(", ")} (${usedByProps.length}×)`
+                ? `Used by parent props: ${usedByProps.map((p) => `\`${p}\``).join(", ")} (${usedByProps.length}×)`
                 : `For parent prop: \`${usedByProps[0]}\``;
             parts.push(propsLabel);
             parts.push(`Old customData: "${ch.customDataName}"`);
             parts.push("");
             parts.push(`\`\`\`bash`);
             parts.push(`npx ikas-component config add-component --name "${ch.childName}" --type component --props '${JSON.stringify(ch.childPropsJson)}'`);
+            parts.push(`# → { "success": true, "componentId": "<capture-this>", ... }`);
             parts.push(`\`\`\``);
             parts.push("");
         }
@@ -1116,6 +1443,10 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
     parts.push(`\`\`\``);
     parts.push("");
     parts.push(`**IMPORTANT:** The CLI auto-generates \`types.ts\`. DO NOT manually create or edit \`types.ts\`.`);
+    if (children.length > 0) {
+        parts.push("");
+        parts.push(`**Before running the command above:** replace each \`<id-of-{ChildName}>\` placeholder in the \`--props\` JSON with the real \`componentId\` captured from the corresponding child's \`add-component\` response (or from \`npx ikas-component config list\`). Component ids are opaque random strings — the CLI will reject any unknown id with a structured error.`);
+    }
     parts.push("");
     // Implementation guidance
     const nextStep = parentStep + 1;
@@ -1132,15 +1463,18 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
     if (children.length > 0) {
         parts.push(`- For COMPONENT_LIST props, use \`<IkasComponentRenderer id="..." components={list as any[]} parentProps={props} />\``);
         parts.push(`- **Remember: the parent cannot read child prop values.** Any per-item logic must live in the child component.`);
-        parts.push(`- **Every COMPONENT_LIST slot needs a child component to render individual items.** A product list needs a ProductCard child, a blog list needs a BlogCard child, etc. Check if the child already exists from a previous migration (reuse its ID in \`filteredComponentIds\`). If not, create it as a registered component.`);
+        parts.push(`- **Every COMPONENT_LIST slot needs a child component to render individual items.** A product list needs a ProductCard child, a blog list needs a BlogCard child, etc. Check if the child already exists (run \`config list\` to see all components and their opaque ids; reuse the existing id in \`filteredComponentIds\`). If not, create it as a registered component and use the \`componentId\` from the CLI's response.`);
     }
     // Check if the section itself has data-driven list props (PRODUCT_LIST, BLOG_LIST, CATEGORY_LIST)
-    const dataListProps = (target.props || []).filter(p => p.type === "PRODUCT_LIST" || p.type === "BLOG_LIST" || p.type === "CATEGORY_LIST" || p.type === "BRAND_LIST");
+    const dataListProps = (target.props || []).filter((p) => p.type === "PRODUCT_LIST" ||
+        p.type === "BLOG_LIST" ||
+        p.type === "CATEGORY_LIST" ||
+        p.type === "BRAND_LIST");
     if (dataListProps.length > 0) {
         parts.push("");
         parts.push(`### Data-Driven List Rendering`);
         parts.push("");
-        parts.push(`This section has data-driven list props: ${dataListProps.map(p => `\`${p.name}\` (${p.type})`).join(", ")}.`);
+        parts.push(`This section has data-driven list props: ${dataListProps.map((p) => `\`${p.name}\` (${p.type})`).join(", ")}.`);
         parts.push(`These are NOT COMPONENT_LIST — the data comes from dynamic queries (filters, categories, search), not hand-picked items. Render items **internally** by mapping over the data:`);
         parts.push("");
         parts.push("```tsx");
@@ -1167,9 +1501,22 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
         parts.push(`See \`get_migration_guide("custom-data-conversion")\` → "Two Ways to Render Lists" for the full pattern.`);
     }
     // Detect form-page sections (0 or few props, name suggests a form/auth page)
-    const formKeywords = ["login", "register", "forgot", "recover", "password", "account", "email", "verification", "activate", "contact", "checkout", "address"];
+    const formKeywords = [
+        "login",
+        "register",
+        "forgot",
+        "recover",
+        "password",
+        "account",
+        "email",
+        "verification",
+        "activate",
+        "contact",
+        "checkout",
+        "address",
+    ];
     const lowerDir = (target.dir || "").toLowerCase();
-    const isLikelyFormPage = formKeywords.some(kw => lowerDir.includes(kw));
+    const isLikelyFormPage = formKeywords.some((kw) => lowerDir.includes(kw));
     if (isLikelyFormPage) {
         parts.push("");
         parts.push(`### Form Page Pattern`);
@@ -1198,7 +1545,9 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
         // Fallback heuristic only when source scan unavailable
         const heuristicLibs = [];
         const lowerName = oldName.toLowerCase();
-        if (lowerName.includes("slider") || lowerName.includes("carousel") || lowerName.includes("banner")) {
+        if (lowerName.includes("slider") ||
+            lowerName.includes("carousel") ||
+            lowerName.includes("banner")) {
             heuristicLibs.push("swiper");
         }
         if (lowerName.includes("marquee"))
@@ -1207,7 +1556,9 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
             heuristicLibs.push("react-player");
         if (lowerName.includes("chart"))
             heuristicLibs.push("recharts");
-        if (lowerName.includes("star") || lowerName.includes("rating") || lowerName.includes("review"))
+        if (lowerName.includes("star") ||
+            lowerName.includes("rating") ||
+            lowerName.includes("review"))
             heuristicLibs.push("react-simple-star-rating");
         if (heuristicLibs.length > 0) {
             parts.push(`### Likely Library Replacements (heuristic — source not scanned)`);
@@ -1221,48 +1572,70 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
             parts.push("");
         }
     }
-    // Relevant guides
-    parts.push(`## ${nextStep + 1}. Relevant Guides (call these for details)`);
+    // Relevant guides — keep terse; LLM can call get_migration_guide("list") for the full catalog
+    parts.push(`## ${nextStep + 1}. Relevant Guides`);
     parts.push("");
     parts.push(`- \`get_migration_guide("react-to-preact")\` — code conversion patterns`);
-    parts.push(`- \`get_migration_guide("library-replacements")\` — library → vanilla Preact patterns`);
-    parts.push(`- \`get_migration_guide("prop-runtime-shapes")\` — exact runtime shapes (.data vs .links)`);
-    if (children.length > 0) {
-        parts.push(`- \`get_migration_guide("component-renderer-limitations")\` — critical COMPONENT_LIST constraints`);
-        parts.push(`- \`get_framework_guide("component-renderer-patterns")\` — full IkasComponentRenderer usage`);
-        parts.push(`- \`get_migration_example("custom-dynamic-list-to-component-list")\` — concrete example`);
-    }
-    if (target.isHeader || target.isFooter) {
-        parts.push(`- \`get_framework_guide("header-footer-patterns")\` — header/footer specifics`);
+    parts.push(`- \`get_migration_guide("prop-runtime-shapes")\` — exact runtime shapes (\`.data\` vs \`.links\`, etc.)`);
+    if (children.length > 0 || target.isHeader || target.isFooter) {
+        parts.push(`- \`get_framework_guide("header-footer-patterns")\` — COMPONENT_LIST + IkasComponentRenderer wiring`);
     }
-    parts.push(`- \`get_framework_guide("common-pitfalls")\` — observer rules, common mistakes`);
     parts.push("");
     // Completion
     parts.push(`## ${nextStep + 2}. Mark Complete`);
     parts.push("");
-    parts.push(`Once the section builds cleanly with \`npx ikas-component build\`:`);
-    parts.push(`1. Edit \`MIGRATION.md\` at the project root`);
-    parts.push(`2. Change the checkbox for \`${sectionId}\` from \`[ ]\` to \`[x]\``);
-    parts.push(`3. Also mark each child component as \`[x]\``);
-    parts.push(`4. Append an entry to the **Session Log** section of \`MIGRATION.md\` noting: libraries replaced, any props added beyond the generated plan, the actual folder name the CLI created (in case it differs from the name you passed — e.g., \`FAQ\` → \`Faq/\`), and any other decisions a future agent should know.`);
+    parts.push(`Once the section builds cleanly with \`npx ikas-component build\`: edit MIGRATION.md → tick \`[x]\` for \`${sectionId}\` and each child component, log any customData decisions under \`## Custom Data Decisions\`, and append a brief entry to \`## Notes\` with anything future sessions should know.`);
     parts.push("");
     return parts.join("\n");
 }
 // --- Search helpers ---
+/**
+ * Strip every non-alphanumeric character and lowercase, so the SAME identifier written in
+ * different conventions collapses to one form: `PRODUCT_ATTRIBUTE`, `IkasProductAttributeDetail`
+ * and the prose "product attribute detail" all become `productattribute…`. Without this a query
+ * for a prop type (which is always SCREAMING_SNAKE) can never reach the function/type docs that
+ * spell the same concept in camelCase or prose — `search_docs("PRODUCT_ATTRIBUTE")` used to miss
+ * `getAttributeDetailValues` entirely.
+ */
+function squashIdentifier(text) {
+    return text.replace(/[^a-z0-9]/gi, "").toLowerCase();
+}
+/** A query word worth matching separator-insensitively: an identifier, not prose. */
+function isIdentifierLike(word) {
+    return (word.length > 3 &&
+        (/[_\-.]/.test(word) ||
+            /[a-z][A-Z]/.test(word) ||
+            /^[A-Z0-9_]+$/.test(word)));
+}
 function matchScore(text, query) {
     const lower = text.toLowerCase();
     const queryLower = query.toLowerCase();
-    const words = queryLower.split(/\s+/).filter(Boolean);
+    const words = query.split(/\s+/).filter(Boolean);
     let score = 0;
     // Exact substring match
     if (lower.includes(queryLower)) {
         score += 10;
     }
-    // Word matches
+    // Word matches. Squashing the (potentially guide-sized) text is the expensive half of the
+    // identifier check — compute it lazily, once per call, not once per query word.
+    let squashedText = null;
     for (const word of words) {
-        if (lower.includes(word)) {
+        const wordLower = word.toLowerCase();
+        if (lower.includes(wordLower)) {
             score += 3;
         }
+        else if (isIdentifierLike(word)) {
+            // Same identifier, different convention (PRODUCT_ATTRIBUTE ↔ IkasProductAttributeDetail
+            // ↔ "product attribute"). Scored below an exact word hit so literal matches still win.
+            const squashed = squashIdentifier(word);
+            if (squashed) {
+                if (squashedText === null)
+                    squashedText = squashIdentifier(text);
+                if (squashedText.includes(squashed)) {
+                    score += 2;
+                }
+            }
+        }
     }
     // Name exact match bonus
     if (lower === queryLower) {
@@ -1270,18 +1643,148 @@ 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);
+}
+/**
+ * Formatted ` — matching sections: ...` suffix naming the guide sections that match the query,
+ * so a hit buried mid-guide (e.g. "Quantity Limits" inside cart-patterns) is visible without
+ * opening the full guide. Section bodies are scored on purpose: a query for an identifier that
+ * appears only inside a section (an error code, a prop name) must still surface that section's
+ * heading. Returns "" when the query matches most of the guide's sections — matchScore is
+ * presence-based, so a broad query ("cart" against cart-patterns) ties every section and a
+ * top-3 would just echo document order, hinting nothing.
+ */
+// Topic content is loaded once at startup and never mutates, so the section parse is
+// memoized on the content string — a query only pays for scoring.
+const parsedSectionsCache = new Map();
+function parseSections(content) {
+    const cached = parsedSectionsCache.get(content);
+    if (cached)
+        return cached;
+    // Line walk instead of a heading-regex split: a `## ` line inside a fenced code block must
+    // not become a pseudo-section (it would surface a heading that doesn't exist in the guide
+    // and swallow the rest of the real section's body).
+    const sections = [];
+    let fenceOpen = false;
+    for (const line of content.split("\n")) {
+        if (/^\s*```/.test(line))
+            fenceOpen = !fenceOpen;
+        const headingMatch = fenceOpen ? null : line.match(/^#{2,4} (.+)/);
+        if (headingMatch)
+            sections.push({ heading: headingMatch[1].trim(), body: "" });
+        else if (sections.length > 0)
+            sections[sections.length - 1].body += line + "\n";
+    }
+    parsedSectionsCache.set(content, sections);
+    return sections;
+}
+function sectionHint(content, query, topicTitle) {
+    const sections = parseSections(content);
+    const scored = [];
+    for (const { heading, body } of sections) {
+        // Heading hits weigh double. The floor of 3 drops sections whose only signal is a single
+        // squashed-identifier body match (worth 2) — a literal word hit (3) or any heading match
+        // clears it.
+        const score = matchScore(heading, query) * 2 + matchScore(body, query);
+        if (score >= 3)
+            scored.push({ heading, score });
+    }
+    if (scored.length === 0)
+        return "";
+    scored.sort((a, b) => b.score - a.score);
+    // The tie-guard below must only fire when the field is genuinely flat. A single common
+    // query word ("cart") pushes every section past the floor, so counting raw matches would
+    // also suppress steep fields where one section clearly won. Sections below 60% of the top
+    // score are noise from such a word, not real matches — drop them before counting.
+    const strong = scored.filter((s) => s.score >= scored[0].score * 0.6);
+    if (strong.length > sections.length / 2)
+        return "";
+    // The guide's own title is usually its first `##` line, so it registers as a section.
+    // Its heading is the exact text the result line already prints — listing it would burn
+    // one of the three slots on a pure echo. Keep it in scoring (its body can be a genuine
+    // hit and it counts toward the tie-guard), drop it from the output only. Headings are
+    // already trimmed at parse time; trim the title too so stray whitespace in the JSON
+    // cannot silently re-admit the echo.
+    const title = topicTitle.trim();
+    const named = strong.filter((s) => s.heading !== title);
+    if (named.length === 0)
+        return "";
+    const top = named.slice(0, 3);
+    return ` — matching sections: ${top.map((s) => `"${s.heading}"`).join(", ")}`;
+}
 function searchFunctions(query) {
     const scored = storefrontData.functions
         .map((fn) => {
         const nameScore = matchScore(fn.name, query) * 3;
+        const displayNameScore = fn.displayName
+            ? matchScore(fn.displayName, query) * 3
+            : 0;
         const descScore = matchScore(fn.description, query);
-        const catScore = fn.categories.some((c) => matchScore(c, query) > 0) ? 5 : 0;
+        const catScore = fn.categories.some((c) => matchScore(c, query) > 0)
+            ? 5
+            : 0;
         const paramScore = fn.params.some((p) => matchScore(p.name, query) > 0 || matchScore(p.description, query) > 0)
             ? 2
             : 0;
         const sigScore = matchScore(fn.signature, query) * 2;
-        const typeScore = fn.parameterTypes?.some((t) => matchScore(t, query) > 0) ? 8 : 0;
-        return { fn, score: nameScore + descScore + catScore + paramScore + sigScore + typeScore };
+        const typeScore = fn.parameterTypes?.some((t) => matchScore(t, query) > 0)
+            ? 8
+            : 0;
+        return {
+            fn,
+            score: nameScore +
+                displayNameScore +
+                descScore +
+                catScore +
+                paramScore +
+                sigScore +
+                typeScore,
+        };
     })
         .filter((item) => item.score > 0)
         .sort((a, b) => b.score - a.score);
@@ -1294,7 +1797,11 @@ function searchFrameworkTopics(query) {
         const descScore = matchScore(topic.description, query) * 2;
         const contentScore = matchScore(topic.content, query);
         const tagScore = topic.tags.some((t) => matchScore(t, query) > 0) ? 5 : 0;
-        return { key, topic, score: titleScore + descScore + contentScore + tagScore };
+        return {
+            key,
+            topic,
+            score: titleScore + descScore + contentScore + tagScore,
+        };
     })
         .filter((item) => item.score > 0)
         .sort((a, b) => b.score - a.score);
@@ -1309,14 +1816,34 @@ 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;
-        return { td, score: nameScore + domainScore + propScore + enumScore };
+        const enumScore = td.enumValues?.some((v) => matchScore(v, query) > 0)
+            ? 4
+            : 0;
+        const unionScore = td.unionValues?.some((v) => matchScore(v, query) > 0)
+            ? 4
+            : 0;
+        return {
+            td,
+            score: nameScore + domainScore + propScore + enumScore + unionScore,
+        };
     })
         .filter((item) => item.score > 0)
         .sort((a, b) => b.score - a.score);
     return scored.map((item) => item.td);
 }
 // --- Format helpers ---
+/**
+ * Wrap a code snippet in a fenced block — unless it already carries its own fence. JSDoc `@example`
+ * bodies are indexed verbatim, so every one of them arrives fenced; wrapping them again produced a
+ * double ```` ``` ```` opener, which makes the block unparseable for anything extracting code from
+ * the doc. Bare snippets still get fenced as typescript.
+ */
+function asCodeBlock(snippet) {
+    const trimmed = snippet.trim();
+    return trimmed.startsWith("```")
+        ? trimmed
+        : ["```typescript", trimmed, "```"].join("\n");
+}
 function formatFunctionDoc(fn) {
     const lines = [];
     lines.push(`## ${fn.name}`);
@@ -1343,7 +1870,7 @@ function formatFunctionDoc(fn) {
         lines.push("", `**Returns:** \`${fn.returnType}\`${fn.returns ? ` - ${fn.returns}` : ""}`);
     }
     if (fn.example) {
-        lines.push("", "**Example:**", "```typescript", fn.example, "```");
+        lines.push("", "**Example:**", asCodeBlock(fn.example));
     }
     if (fn.related.length > 0) {
         lines.push("", `**Related:** ${fn.related.map((r) => `\`${r}\``).join(", ")}`);
@@ -1351,8 +1878,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 = {}) {
@@ -1360,13 +1891,24 @@ function formatTypeDefinition(td, opts = {}) {
     const lines = [];
     lines.push(`## ${td.name}`);
     lines.push("", `**Kind:** ${td.kind} | **Domain:** ${td.domain}`);
-    if (td.kind === "type") {
+    if (td.description) {
+        lines.push("", td.description);
+    }
+    if (td.kind === "type" && td.unionValues) {
+        lines.push("", "```typescript");
+        lines.push(`type ${td.name} = ${td.unionValues.map((v) => `"${v}"`).join(" | ")};`);
+        lines.push("```");
+    }
+    else if (td.kind === "type") {
         lines.push("", "```typescript");
         const extendsStr = td.extends ? ` & ${td.extends.join(" & ")}` : "";
         lines.push(`type ${td.name} = {`);
         if (td.properties) {
             for (const p of td.properties) {
                 const opt = p.optional ? "?" : "";
+                if (p.description) {
+                    lines.push("  /**", ...p.description.split("\n").map((l) => `   * ${l.trim()}`), "   */");
+                }
                 lines.push(`  ${p.name}${opt}: ${p.type};`);
             }
         }
@@ -1393,7 +1935,9 @@ function formatTypeDefinition(td, opts = {}) {
             const fn = storefrontData.functions.find((f) => f.name === fnName);
             if (fn) {
                 const desc = fn.description ? fn.description.split(".")[0] + "." : "";
-                const alias = fn.displayName && fn.displayName !== fn.name ? ` (alias: ${fn.displayName})` : "";
+                const alias = fn.displayName && fn.displayName !== fn.name
+                    ? ` (alias: ${fn.displayName})`
+                    : "";
                 lines.push(`- **\`${fn.name}\`**${alias} — ${desc}`);
                 lines.push(`  \`${fn.signature}\``);
             }
@@ -1402,7 +1946,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");
 }
@@ -1411,6 +1957,10 @@ function formatTypeSummary(td) {
         const count = td.enumValues?.length ?? 0;
         return `- \`${td.name}\` (enum, ${count} values) — domain: ${td.domain}`;
     }
+    if (td.unionValues) {
+        const values = td.unionValues.map((v) => `"${v}"`).join(" | ");
+        return `- \`${td.name}\` (union: ${values}) — domain: ${td.domain}`;
+    }
     const count = td.properties?.length ?? 0;
     const ext = td.extends ? ` extends ${td.extends.join(", ")}` : "";
     return `- \`${td.name}\` (${count} properties${ext}) — domain: ${td.domain}`;
@@ -1420,7 +1970,15 @@ 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 theme 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); `move_page_section` → reorder a section already placed on a page (by `direction` up/down or an absolute `to_index`) — the only way to change section order, since the editor UI offers it solely as a drag; `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); `list_ready_made_pages` / `update_ready_made_page_prop` / `enable_ready_made_pages` → the ikas-rendered ready-made account/membership pages (login, register, my account, orders, …) — these are NOT sections and the section tools cannot edit them; use these three to enable the groups, read their prop schemas, and customize/localize them (logo, colors, texts). When the user asks to BUILD a login/register/password/my-account/orders/addresses page, FIRST offer these ready-made pages instead of assembling one from sections — they are fully functional out of the box and customizable (logo, colors, texts); build a custom section page only if the user prefers a custom design. Offer, don't flip: `enable_ready_made_pages` creates/removes pages, so get the user's explicit OK before calling it. 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" +
+        "READY-MADE PAGES FIRST — HARD RULE for account/membership pages: USER-FACING NAME: name these in the USER'S OWN LANGUAGE — English: \"ikas's ready-made pages\", Turkish: \"ikas'ın hazır sayfaları\"; never mix the English term into a sentence in another language — the editor UI lists them as Membership Pages / My Account Pages; \"built-in\" is an internal term — keep it out of everything the user sees, including question/option labels. When the user asks for a login, register, forgot/recover-password, my-account, orders, order-detail, addresses, favorites or email-verification page, do NOT start coding a custom section page. STOP and ask the user FIRST whether to use ikas's ready-made version of that page (`list_ready_made_pages` shows it — fully functional out of the box, customized/localized via `update_ready_made_page_prop`, the whole group turned on with `enable_ready_made_pages`). Only build a custom section page AFTER the user explicitly chooses custom. When asking, list the ready-made option FIRST as the recommended default; the custom section option comes second. Never call `enable_ready_made_pages` without the user's OK — it creates/removes pages. Ready-made pages are born with ONLY their own ikas-rendered element: the theme's header/footer are NOT on them (the page draws its own top bar — logo, back-to-store link — and account nav). If the user wants the theme header/footer on a ready-made page, PLACE it there with add_section_to_page — sections can sit above/below that element — and suggest turning the page's own `showBrandBar` prop off to avoid double chrome.\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.\n\n" +
+        "COMMON (GLOBAL) SECTIONS — HEADER & FOOTER: these render on every page that CARRIES A PLACEMENT of them — pages created in the editor are seeded with one, EXCEPT ikas ready-made (built-in) account/membership pages, which are born WITHOUT the theme header/footer (see the ready-made rule above) — and their prop values are shared theme-wide, stored in ONE record on the INDEX (Home) page's placement. Reads and writes from any page are resolved to that record, and every response about such a section carries a `common` block (`isCommon`, `commonSectionType`, `canonicalPageId`, `canonicalElementId`, `valuesArePageSpecific: false`). Consequences: changing a header/footer prop from, say, a product-detail page changes it on ALL pages; and since the header/footer normally already holds the merchant's content, you must `get_section_values` first and change only what the user asked — never treat a prop as empty and never blind-fill 'missing' props, or you overwrite live content everywhere. If the INDEX page has no placement of the section there is no record at all: reads report nothing and writes fail until you add it to the INDEX page.",
 });
 // 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 }) => {
@@ -1440,7 +1998,7 @@ server.tool("search_docs", "Search across all ikas storefront API docs, framewor
     if (topics.length > 0) {
         parts.push("\n## Matching Framework Topics\n");
         for (const item of topics) {
-            parts.push(`- **${item.topic.title}** (key: \`${item.key}\`) - ${item.topic.description}`);
+            parts.push(`- **${item.topic.title}** (key: \`${item.key}\`) - ${item.topic.description}${sectionHint(item.topic.content, query, item.topic.title)}`);
         }
         parts.push("");
         parts.push("Use `get_framework_guide(topic)` to get full content for any topic.");
@@ -1456,44 +2014,84 @@ server.tool("search_docs", "Search across all ikas storefront API docs, framewor
     if (migrationTopics.length > 0) {
         parts.push("\n## Matching Migration Topics\n");
         for (const item of migrationTopics) {
-            parts.push(`- [migration] **${item.topic.title}** (key: \`${item.key}\`) - ${item.topic.description}`);
+            parts.push(`- [migration] **${item.topic.title}** (key: \`${item.key}\`) - ${item.topic.description}${sectionHint(item.topic.content, query, item.topic.title)}`);
         }
         parts.push("");
         parts.push("Use `get_migration_guide(topic)` to get full content for any migration topic.");
     }
-    if (functions.length === 0 && topics.length === 0 && types.length === 0 && migrationTopics.length === 0) {
+    if (functions.length === 0 &&
+        topics.length === 0 &&
+        types.length === 0 &&
+        migrationTopics.length === 0) {
         parts.push(`No results found for "${query}". Try different keywords or use \`list_functions()\` to see all available functions.`);
     }
     return { content: [{ type: "text", text: parts.join("\n") }] };
 });
 // Tool: get_function_doc
-server.tool("get_function_doc", "Get full documentation for a specific storefront API function including signature, parameters, return type, and example.", { name: z.string().describe("Function name (e.g. 'addItemToCart', 'Router.navigate')") }, async ({ name }) => {
+server.tool("get_function_doc", "Get full documentation for a specific storefront API function including signature, parameters, return type, and example.", {
+    name: z
+        .string()
+        .describe("Function name (e.g. 'addItemToCart', 'Router.navigate')"),
+}, async ({ name }) => {
     const nameLower = name.toLowerCase();
-    const fn = storefrontData.functions.find((f) => f.name.toLowerCase() === nameLower ||
-        (f.displayName && f.displayName.toLowerCase() === nameLower));
-    if (!fn) {
-        // Try fuzzy match
-        const matches = storefrontData.functions.filter((f) => f.name.toLowerCase().includes(nameLower) ||
-            (f.displayName && f.displayName.toLowerCase().includes(nameLower)));
-        if (matches.length > 0) {
-            const suggestions = matches.slice(0, 5).map((f) => {
-                const alias = f.displayName && f.displayName !== f.name ? ` (alias: ${f.displayName})` : "";
-                return `  - ${f.name}${alias}`;
-            });
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `Function "${name}" not found. Did you mean:\n${suggestions.join("\n")}`,
-                    },
-                ],
-            };
+    // Phase 1: canonical-name match wins. A real function name always outranks
+    // any displayName alias so aliases can never shadow the function they're
+    // named after (e.g. `hasCustomer` the function vs. `hasIkasOrderCustomer`'s
+    // [BP-DISPLAY-NAME: hasCustomer] alias).
+    const byName = storefrontData.functions.find((f) => f.name.toLowerCase() === nameLower);
+    if (byName) {
+        return {
+            content: [{ type: "text", text: formatFunctionDoc(byName) }],
+        };
+    }
+    // Phase 2: fall back to displayName aliases.
+    const byAlias = storefrontData.functions.filter((f) => f.displayName && f.displayName.toLowerCase() === nameLower);
+    if (byAlias.length === 1) {
+        const fn = byAlias[0];
+        const note = `> Note: "${name}" is a display alias for \`${fn.name}\`.\n\n`;
+        return {
+            content: [
+                { type: "text", text: note + formatFunctionDoc(fn) },
+            ],
+        };
+    }
+    if (byAlias.length > 1) {
+        const lines = [];
+        lines.push(`"${name}" is an ambiguous display alias used by ${byAlias.length} functions. Call \`get_function_doc\` again with the canonical name of the one you want:`);
+        lines.push("");
+        for (const fn of byAlias) {
+            lines.push(formatFunctionSummary(fn));
+            lines.push(`  \`${fn.signature}\``);
         }
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+    // No exact match. Try fuzzy substring match across name + displayName.
+    const matches = storefrontData.functions.filter((f) => f.name.toLowerCase().includes(nameLower) ||
+        (f.displayName && f.displayName.toLowerCase().includes(nameLower)));
+    if (matches.length > 0) {
+        const suggestions = matches.slice(0, 5).map((f) => {
+            const alias = f.displayName && f.displayName !== f.name
+                ? ` (alias: ${f.displayName})`
+                : "";
+            return `  - ${f.name}${alias}`;
+        });
         return {
-            content: [{ type: "text", text: `Function "${name}" not found. Use \`list_functions()\` to see all available functions.` }],
+            content: [
+                {
+                    type: "text",
+                    text: `Function "${name}" not found. Did you mean:\n${suggestions.join("\n")}`,
+                },
+            ],
         };
     }
-    return { content: [{ type: "text", text: formatFunctionDoc(fn) }] };
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Function "${name}" not found. Use \`list_functions()\` to see all available functions.`,
+            },
+        ],
+    };
 });
 // Tool: list_functions
 server.tool("list_functions", "List storefront API functions. Without a `category`, returns category names + counts so you can drill in. With a `category`, returns one-line summaries for that category. Use `limit`/`offset` to paginate.", {
@@ -1542,7 +2140,7 @@ server.tool("list_functions", "List storefront API functions. Without a `categor
         if (uncategorized > 0) {
             lines.push(`- \`Other\` (${uncategorized})`);
         }
-        lines.push("", "Call `list_functions(category: \"<name>\")` to see one-line summaries for a category.");
+        lines.push("", 'Call `list_functions(category: "<name>")` to see one-line summaries for a category.');
         return { content: [{ type: "text", text: lines.join("\n") }] };
     }
     const catLower = category.toLowerCase();
@@ -1574,7 +2172,11 @@ server.tool("list_functions", "List storefront API functions. Without a `categor
     return { content: [{ type: "text", text: parts.join("\n") }] };
 });
 // Tool: get_code_example
-server.tool("get_code_example", "Get an API usage reference for a specific task. Shows correct function calls, imports, and data-handling patterns from a real production theme. The JSX layout and CSS are illustrative only — create your own original visual design. Call `list_examples()` to see available example IDs.", { task: z.string().describe("Task description or example ID (call `list_examples()` for the full list)") }, async ({ task }) => {
+server.tool("get_code_example", "Get an API usage reference for a specific task. Shows correct function calls, imports, and data-handling patterns from a real production theme. The JSX layout and CSS are illustrative only — create your own original visual design. Call `list_examples()` to see available example IDs.", {
+    task: z
+        .string()
+        .describe("Task description or example ID (call `list_examples()` for the full list)"),
+}, async ({ task }) => {
     const taskLower = task.toLowerCase();
     // Try exact ID match first
     let example = storefrontData.codeExamples.find((e) => e.id === taskLower);
@@ -1594,7 +2196,9 @@ server.tool("get_code_example", "Get an API usage reference for a specific task.
         }
     }
     if (!example) {
-        const available = storefrontData.codeExamples.map((e) => `  - \`${e.id}\` - ${e.title}`).join("\n");
+        const available = storefrontData.codeExamples
+            .map((e) => `  - \`${e.id}\` - ${e.title}`)
+            .join("\n");
         return {
             content: [
                 {
@@ -1617,20 +2221,30 @@ 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, "```", "");
         }
     }
     else {
-        parts.push("```typescript", example.code, "```", "");
+        parts.push(asCodeBlock(example.code), "");
     }
     parts.push(`**Reminder:** Use the API patterns above (function calls, imports, type handling) but create your own original HTML structure and CSS.`);
     parts.push("");
@@ -1638,63 +2252,95 @@ 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",
+        conditional: "conditional-visibility",
+        "conditional-props": "conditional-visibility",
+        visibility: "conditional-visibility",
+        requiredprop: "conditional-visibility",
+        "required-prop": "conditional-visibility",
+        "dependent-props": "conditional-visibility",
+        "show-hide": "conditional-visibility",
     };
     const resolvedTopic = topicAliases[topicLower] || topicLower;
     // Topics that involve MobX store reads get a reminder about root reactivity
     const storeTopics = new Set([
-        "product-detail-patterns", "product-list-patterns", "cart-patterns",
-        "account-patterns", "header-footer-patterns", "review-patterns",
-        "blog-patterns", "form-handling", "async-data-patterns",
-        "component-structure", "imports",
+        "product-detail-patterns",
+        "product-list-patterns",
+        "cart-patterns",
+        "account-patterns",
+        "header-footer-patterns",
+        "review-patterns",
+        "blog-patterns",
+        "form-handling",
+        "async-data-patterns",
+        "component-structure",
+        "imports",
     ]);
     const observerReminder = "> **IMPORTANT: Do NOT use `observer()` on root component exports.** The ikas runtime wraps root renders in MobX `autorun()`, making them automatically reactive. All store reads (`cartStore`, `customerStore`, etc.) in root components are tracked automatically. Only use `observer()` on extracted sub-components.\n\n";
     // Try exact key match (with alias resolution)
     if (frameworkData.topics[resolvedTopic]) {
         const t = frameworkData.topics[resolvedTopic];
         const prefix = storeTopics.has(resolvedTopic) ? observerReminder : "";
-        return { content: [{ type: "text", text: `## ${t.title}\n\n${prefix}${t.content}` }] };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `## ${t.title}\n\n${prefix}${t.content}`,
+                },
+            ],
+        };
     }
     // Try original topic key (without alias) in case it's a direct key
     if (resolvedTopic !== topicLower && frameworkData.topics[topicLower]) {
         const t = frameworkData.topics[topicLower];
         const prefix = storeTopics.has(topicLower) ? observerReminder : "";
-        return { content: [{ type: "text", text: `## ${t.title}\n\n${prefix}${t.content}` }] };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `## ${t.title}\n\n${prefix}${t.content}`,
+                },
+            ],
+        };
     }
     // Try keyword search
     const matches = searchFrameworkTopics(topic);
@@ -1702,7 +2348,12 @@ server.tool("get_framework_guide", "Get a framework guide on a specific topic (e
         const best = matches[0];
         const prefix = storeTopics.has(best.key) ? observerReminder : "";
         return {
-            content: [{ type: "text", text: `## ${best.topic.title}\n\n${prefix}${best.topic.content}` }],
+            content: [
+                {
+                    type: "text",
+                    text: `## ${best.topic.title}\n\n${prefix}${best.topic.content}`,
+                },
+            ],
         };
     }
     const available = Object.entries(frameworkData.topics)
@@ -1718,16 +2369,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. Shows all properties with types, extends, enum values, or string-union values. Covers runtime models (e.g. 'IkasProduct', 'IkasOrderStatus'), theme-globals tokens returned by the getters (e.g. 'ThemeSetting', 'DesignToken', 'TypographyToken', 'ColorSchemeToken', 'BreakpointToken', 'KeyframeToken'), and style-prop TYPE shapes used by ikas.config.json props (e.g. 'BorderRadiusStyleType', 'PaddingStyleType', 'GapStyleType', 'SizeStyleType' and their '*StyleUnitType' unions). If a type reports as not found, it may not be indexed yet — fall back to reading the package's `.d.ts` (e.g. `@ikas/bp-storefront-config`) rather than typing the value as `any`.", {
+    name: z
+        .string()
+        .describe("Type or enum name (e.g. 'IkasProduct', 'IkasOrderStatus')"),
+}, async ({ name }) => {
     if (!typesData) {
         return {
-            content: [{ type: "text", text: "Type data not available. Run 'npm run docs:generate' in storefront-docs first." }],
+            content: [
+                {
+                    type: "text",
+                    text: "Type data not available. Run 'npm run docs:generate' in storefront-docs first.",
+                },
+            ],
         };
     }
     const nameLower = name.toLowerCase();
     const td = typesData.types.find((t) => t.name.toLowerCase() === nameLower);
     if (td) {
-        return { content: [{ type: "text", text: formatTypeDefinition(td) }] };
+        return {
+            content: [{ type: "text", text: formatTypeDefinition(td) }],
+        };
     }
     // Fuzzy match
     const matches = typesData.types.filter((t) => t.name.toLowerCase().includes(nameLower));
@@ -1743,14 +2405,28 @@ server.tool("get_type_definition", "Get the full definition of a storefront type
         };
     }
     return {
-        content: [{ type: "text", text: `Type "${name}" not found. Use \`list_types()\` to see all available types.` }],
+        content: [
+            {
+                type: "text",
+                text: `Type "${name}" not found. Use \`list_types()\` to see all available types.`,
+            },
+        ],
     };
 });
 // Tool: get_functions_for_type
-server.tool("get_functions_for_type", "Get full documentation for all utility functions that operate on a given storefront type. For example, get_functions_for_type('IkasImage') returns getSrc, getDefaultSrc, getThumbnailSrc, createMediaSrcset with full signatures, descriptions, and examples.", { typeName: z.string().describe("Type name (e.g. 'IkasImage', 'IkasProduct', 'IkasOrder')") }, async ({ typeName }) => {
+server.tool("get_functions_for_type", "Get full documentation for all utility functions that operate on a given storefront type. For example, get_functions_for_type('IkasImage') returns getSrc, getDefaultSrc, getThumbnailSrc, createMediaSrcset with full signatures, descriptions, and examples.", {
+    typeName: z
+        .string()
+        .describe("Type name (e.g. 'IkasImage', 'IkasProduct', 'IkasOrder')"),
+}, async ({ typeName }) => {
     if (!typesData) {
         return {
-            content: [{ type: "text", text: "Type data not available. Run 'npm run docs:generate' in storefront-docs first." }],
+            content: [
+                {
+                    type: "text",
+                    text: "Type data not available. Run 'npm run docs:generate' in storefront-docs first.",
+                },
+            ],
         };
     }
     const nameLower = typeName.toLowerCase();
@@ -1770,7 +2446,12 @@ server.tool("get_functions_for_type", "Get full documentation for all utility fu
             };
         }
         return {
-            content: [{ type: "text", text: `Type "${typeName}" not found. Use \`list_types()\` to see all available types.` }],
+            content: [
+                {
+                    type: "text",
+                    text: `Type "${typeName}" not found. Use \`list_types()\` to see all available types.`,
+                },
+            ],
         };
     }
     if (!td.relatedFunctions || td.relatedFunctions.length === 0) {
@@ -1801,7 +2482,10 @@ server.tool("get_functions_for_type", "Get full documentation for all utility fu
 });
 // Tool: get_model_guide
 server.tool("get_model_guide", "Get an overview of a storefront model type. By default returns the type definition, related function names with one-line summaries, matching example titles/IDs, and related type summaries. Pass `mode: 'full'` to inline full function docs and example code.", {
-    model: z.string().optional().describe("Model type name (e.g. 'IkasImage', 'IkasProduct', 'IkasOrder')"),
+    model: z
+        .string()
+        .optional()
+        .describe("Model type name (e.g. 'IkasImage', 'IkasProduct', 'IkasOrder')"),
     name: z.string().optional().describe("Alias for 'model'"),
     mode: z
         .enum(["summary", "full"])
@@ -1812,12 +2496,22 @@ server.tool("get_model_guide", "Get an overview of a storefront model type. By d
     const model = modelParam || nameParam;
     if (!model) {
         return {
-            content: [{ type: "text", text: "Please provide a model name (e.g. 'IkasProduct', 'IkasOrder'). Use the 'model' or 'name' parameter." }],
+            content: [
+                {
+                    type: "text",
+                    text: "Please provide a model name (e.g. 'IkasProduct', 'IkasOrder'). Use the 'model' or 'name' parameter.",
+                },
+            ],
         };
     }
     if (!typesData) {
         return {
-            content: [{ type: "text", text: "Type data not available. Run 'npm run docs:generate' in storefront-docs first." }],
+            content: [
+                {
+                    type: "text",
+                    text: "Type data not available. Run 'npm run docs:generate' in storefront-docs first.",
+                },
+            ],
         };
     }
     const modelLower = model.toLowerCase();
@@ -1839,7 +2533,12 @@ server.tool("get_model_guide", "Get an overview of a storefront model type. By d
             };
         }
         return {
-            content: [{ type: "text", text: `Model "${model}" not found. Use \`list_types()\` to see all available types.` }],
+            content: [
+                {
+                    type: "text",
+                    text: `Model "${model}" not found. Use \`list_types()\` to see all available types.`,
+                },
+            ],
         };
     }
     const parts = [`# Model Guide: ${td.name}\n`];
@@ -1947,13 +2646,23 @@ server.tool("get_model_guide", "Get an overview of a storefront model type. By d
 server.tool("search_types", "Search storefront types and enums by keyword (e.g. 'price', 'address', 'status'). Returns top matches ranked by relevance.", { query: z.string().describe("Search keyword or phrase") }, async ({ query }) => {
     if (!typesData) {
         return {
-            content: [{ type: "text", text: "Type data not available. Run 'npm run docs:generate' in storefront-docs first." }],
+            content: [
+                {
+                    type: "text",
+                    text: "Type data not available. Run 'npm run docs:generate' in storefront-docs first.",
+                },
+            ],
         };
     }
     const results = searchTypes(query).slice(0, 15);
     if (results.length === 0) {
         return {
-            content: [{ type: "text", text: `No types found matching "${query}". Use \`list_types()\` to see all available types.` }],
+            content: [
+                {
+                    type: "text",
+                    text: `No types found matching "${query}". Use \`list_types()\` to see all available types.`,
+                },
+            ],
         };
     }
     const parts = [`## Type Search Results for "${query}"\n`];
@@ -2017,7 +2726,7 @@ server.tool("list_types", "List storefront types and enums. Use `domain` and/or
         for (const [d, count] of sorted) {
             lines.push(`- \`${d}\` (${count})`);
         }
-        lines.push("", "Call `list_types(domain: \"<name>\")` to see summaries for a domain.");
+        lines.push("", 'Call `list_types(domain: "<name>")` to see summaries for a domain.');
         return { content: [{ type: "text", text: lines.join("\n") }] };
     }
     const domainLower = domain.toLowerCase();
@@ -2056,23 +2765,50 @@ 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
+// Starter templates that rebuild a page ikas already ships as a ready-made BUILT-IN page. Asked to
+// "build a login page", the agent reaches for the template before any other tool — so the
+// ask-the-user gate rides this response, where it cannot be skimmed past.
+const BUILTIN_COVERED_TEMPLATES = new Set([
+    "login-section",
+    "register-section",
+    "forgot-password-section",
+    "recover-password-section",
+    "email-verification-section",
+    "account-info-section",
+    "favorites",
+]);
+const BUILTIN_COVERED_BANNER = [
+    "STOP — ASK THE USER BEFORE CODING THIS.",
+    "This template rebuilds a page ikas already ships as a ready-made page: fully functional auth/account flows out of the box, customized and localized via `update_ready_made_page_prop`, the whole group enabled with `enable_ready_made_pages` (see `list_ready_made_pages`).",
+    "If the user has not EXPLICITLY chosen a custom-coded page, do not write code yet. Ask them now: (a) ikas's ready-made page — instant, maintained by ikas — or (b) a custom section with full design freedom. List the ready-made option FIRST as the recommended default; custom comes second. Continue with this template ONLY after they explicitly choose custom.",
+].join("\n");
 // Build the enum dynamically from the on-disk section templates directory
 const sectionTemplateKeys = sectionTemplateNames.length > 0
     ? sectionTemplateNames
     : null;
-server.tool("get_section_template", "Get the root files of a starter section template (index.tsx, types.ts, styles.css, ikas-config-snippet.json). Returns ONLY the section's root files plus the NAMES of any children, components, sub-components, utilities, and hooks — their files are NOT included by default. To view one item's full implementation, call `get_section_child(section, name, kind)` where kind is 'children' (default), 'components', or 'sub-components'. To bundle subtrees inline, pass `include`. Call `list_section_types()` for available section types. Use the API patterns shown — create your own JSX structure, CSS class names, and visual design.", {
+server.tool("get_section_template", "Get the root files of a starter section template (index.tsx, types.ts, styles.css, ikas-config-snippet.json). Returns ONLY the section's root files plus the NAMES of any children, components, sub-components, utilities, and hooks — their files are NOT included by default. To view one item's full implementation, call `get_section_child(section, name, kind)` where kind is 'children' (default), 'components', or 'sub-components'. To bundle subtrees inline, pass `include`. Call `list_section_types()` for available section types. Use the API patterns shown — create your own JSX structure, CSS class names, and visual design. **Container sections** (Header, Footer, ProductDetail, etc.) host child components via a `COMPONENT_LIST` slot — the response emits a complete multi-step Setup Recipe (create children → capture ids → wire `filteredComponentIds` via `config update-prop`). Follow all steps; the parent alone produces an empty section.", {
     sectionType: z
         .string()
         .describe("The section type (call `list_section_types()` for valid values)"),
@@ -2114,11 +2850,19 @@ server.tool("get_section_template", "Get the root files of a starter section tem
     }
     const normalizedType = normalizeName(sectionType);
     if (!sectionTemplateNames.includes(normalizedType)) {
-        return {
+        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.`,
                 },
             ],
         };
@@ -2144,9 +2888,25 @@ server.tool("get_section_template", "Get the root files of a starter section tem
         (bundle.componentNames.length > 0 && !componentsFullyIncluded) ||
         (bundle.subComponentNames.length > 0 && !subComponentsFullyIncluded);
     const parts = [
+        ...(BUILTIN_COVERED_TEMPLATES.has(normalizedType)
+            ? [BUILTIN_COVERED_BANNER, ""]
+            : []),
         `## ${bundle.title} — API Integration Pattern Reference`,
         "",
     ];
+    // Detect container-section pattern (COMPONENT_LIST with `<id-of-X>` placeholders).
+    // Surface this BEFORE every other warning so the LLM cannot miss the wiring requirement.
+    // The full recipe (commands, captured-id placeholders, update-prop call) is appended near
+    // the end of the response in the existing recipe-builder block.
+    {
+        const snippetStrForBanner = bundle.rootFiles["ikas-config-snippet.json"];
+        if (snippetStrForBanner &&
+            /<id-of-[A-Za-z0-9_]+>/.test(snippetStrForBanner)) {
+            const childMatches = Array.from(snippetStrForBanner.matchAll(/<id-of-([A-Za-z0-9_]+)>/g));
+            const uniqueChildren = Array.from(new Set(childMatches.map((m) => m[1])));
+            parts.push(`> 🔧 **CONTAINER SECTION — required wiring.** This template hosts ${uniqueChildren.length} child component${uniqueChildren.length === 1 ? "" : "s"} (${uniqueChildren.map((n) => `\`${n}\``).join(", ")}) via a \`COMPONENT_LIST\` slot. Creating the parent alone produces an empty, unusable section. **You MUST follow the full Setup Recipe below**: create each child → capture its \`componentId\` → wire them into the parent's \`filteredComponentIds\` with \`config update-prop\`. Component ids are opaque random strings (e.g. \`7ojrigep-Eml9n5sN3i\`) — they cannot be derived from names, and the CLI rejects unknown ids.`, "");
+        }
+    }
     if (anyOutstandingSubtree) {
         parts.push("> **PARTIAL TEMPLATE — NOT A COMPLETE IMPLEMENTATION.** The files below are the section's root files only. The section also ships with child components, local components, and/or shared sub-components whose files are **not included** in this response. To view one's full implementation, call `get_section_child(section, name, kind)` for each item you need (kind = `children`, `components`, or `sub-components`). The root `index.tsx` alone is not a complete reference — its imports resolve to files that live in those subtrees.", "");
     }
@@ -2215,7 +2975,10 @@ server.tool("get_section_template", "Get the root files of a starter section tem
     renderInlineSubtree("children", bundle.childContents);
     renderInlineSubtree("components", bundle.componentContents);
     renderInlineSubtree("sub-components", bundle.subComponentContents);
-    // Generate a ready-to-run CLI command from the config snippet
+    // Generate a ready-to-run CLI recipe from the config snippet. If the parent's
+    // filteredComponentIds reference `<id-of-X>` placeholders, expand into a
+    // multi-step recipe (create children → create parent → wire filteredComponentIds)
+    // so the LLM cannot skip the wiring step.
     const configSnippetStr = bundle.rootFiles["ikas-config-snippet.json"];
     if (configSnippetStr) {
         try {
@@ -2223,26 +2986,105 @@ server.tool("get_section_template", "Get the root files of a starter section tem
             const compName = configSnippet.name || normalizedType;
             const compType = configSnippet.type || "section";
             const propsArr = configSnippet.props || [];
-            let cliCommand = `npx ikas-component config add-component --name "${compName}" --type ${compType}`;
-            if (configSnippet.isHeader)
-                cliCommand += " --isHeader";
-            if (configSnippet.isFooter)
-                cliCommand += " --isFooter";
-            if (propsArr.length > 0) {
-                const propsJson = JSON.stringify(propsArr.map((p) => {
-                    const prop = {
-                        name: p.name,
-                        type: p.type,
-                    };
-                    if (p.displayName)
-                        prop.displayName = p.displayName;
-                    if (p.required)
-                        prop.required = true;
-                    return prop;
-                }));
-                cliCommand += ` --props '${propsJson}'`;
+            // Strip filteredComponentIds for the parent's add-component call (wired
+            // separately below). Preserve name/type/displayName/required so the LLM gets the prop shape.
+            const parentPropsForAdd = propsArr.map((p) => {
+                const out = { name: p.name, type: p.type };
+                if (p.displayName)
+                    out.displayName = p.displayName;
+                if (p.required)
+                    out.required = true;
+                return out;
+            });
+            const placeholderRe = /^<id-of-(.+)>$/;
+            const slotPlans = [];
+            const allChildNames = new Set();
+            for (const p of propsArr) {
+                if ((p.type === "COMPONENT_LIST" || p.type === "COMPONENT") &&
+                    Array.isArray(p.filteredComponentIds)) {
+                    const childNames = [];
+                    for (const entry of p.filteredComponentIds) {
+                        const m = typeof entry === "string" && entry.match(placeholderRe);
+                        if (m) {
+                            childNames.push(m[1]);
+                            allChildNames.add(m[1]);
+                        }
+                    }
+                    if (childNames.length > 0) {
+                        slotPlans.push({ propName: p.name, childNames });
+                    }
+                }
+            }
+            const childPlans = [];
+            for (const childName of allChildNames) {
+                const childSnippetPath = path.join(SECTION_TEMPLATES_DIR, normalizedType, "children", childName, "ikas-config-snippet.json");
+                let propsJson = "[]";
+                let hasTemplate = false;
+                if (fs.existsSync(childSnippetPath)) {
+                    hasTemplate = true;
+                    try {
+                        const childSnippet = JSON.parse(fs.readFileSync(childSnippetPath, "utf-8"));
+                        const childProps = (childSnippet.props || []).map((p) => {
+                            const out = {
+                                name: p.name,
+                                type: p.type,
+                            };
+                            if (p.displayName)
+                                out.displayName = p.displayName;
+                            if (p.required)
+                                out.required = true;
+                            return out;
+                        });
+                        propsJson = JSON.stringify(childProps);
+                    }
+                    catch {
+                        // fall through with []
+                    }
+                }
+                childPlans.push({ name: childName, propsJson, hasTemplate });
+            }
+            const baseFlags = (configSnippet.isHeader ? " --isHeader" : "") +
+                (configSnippet.isFooter ? " --isFooter" : "");
+            const parentPropsJsonStr = parentPropsForAdd.length > 0
+                ? ` --props '${JSON.stringify(parentPropsForAdd)}'`
+                : "";
+            if (slotPlans.length > 0) {
+                parts.push("---", "");
+                parts.push(`### Setup Recipe (run in order — ${childPlans.length} child component${childPlans.length === 1 ? "" : "s"} + 1 parent + wiring)`);
+                parts.push("");
+                parts.push(`> ⚠️ **This section is a CONTAINER.** It hosts child components via ${slotPlans.length === 1 ? "a COMPONENT_LIST slot" : "COMPONENT_LIST slots"} (\`${slotPlans.map((s) => s.propName).join("`, `")}\`). Creating the parent alone is **not enough** — you MUST also create the child components and wire their opaque ids into the parent's \`filteredComponentIds\`. Skipping the wiring leaves the slot empty and the section unusable.`, "");
+                parts.push("**Step 1 — Create each child component, and capture its `componentId` from the JSON response:**");
+                parts.push("", "```bash");
+                for (const ch of childPlans) {
+                    parts.push(`npx ikas-component config add-component --name "${ch.name}" --type component --props '${ch.propsJson}'`);
+                    parts.push(`# → { "success": true, "componentId": "<capture as ${ch.name.toUpperCase()}_ID>", ... }`);
+                    if (!ch.hasTemplate) {
+                        parts.push(`# (no children/${ch.name}/ template in this section bundle — \`--props '[]'\` is a stub; add real props for ${ch.name} as needed)`);
+                    }
+                }
+                parts.push("```", "");
+                parts.push("**Step 2 — Create the parent section (without `filteredComponentIds` yet — those are wired in Step 3):**");
+                parts.push("", "```bash");
+                parts.push(`npx ikas-component config add-component --name "${compName}" --type ${compType}${baseFlags}${parentPropsJsonStr}`);
+                parts.push("```", "");
+                parts.push("**Step 3 — Wire each slot to its allowed children using the ids captured in Step 1:**");
+                parts.push("", "```bash");
+                for (const slot of slotPlans) {
+                    const idsArr = slot.childNames.map((n) => `<${n.toUpperCase()}_ID>`);
+                    parts.push(`npx ikas-component config update-prop --component "${compName}" --prop ${slot.propName} \\`);
+                    parts.push(`  --filteredComponentIds '${JSON.stringify(idsArr)}'`);
+                }
+                parts.push("```", "");
+                parts.push("Replace each `<X_ID>` placeholder above with the real `componentId` from the corresponding Step 1 response (or look ids up with `config list`). The CLI rejects unknown ids with a structured error — there is no silent failure mode.");
+                parts.push("");
+                parts.push("**Do NOT manually create or edit `types.ts`** — the CLI commands above regenerate it automatically.");
+                parts.push("");
+            }
+            else {
+                // No child slots — single-step parent command (preserves previous behaviour)
+                const cliCommand = `npx ikas-component config add-component --name "${compName}" --type ${compType}${baseFlags}${parentPropsJsonStr}`;
+                parts.push("---", "", "### CLI Command (run this first)", "", "```bash", cliCommand, "```", "", "**Do NOT manually create or edit `types.ts`** — the CLI command above generates it automatically.", "");
             }
-            parts.push("---", "", "### CLI Command (run this first)", "", "```bash", cliCommand, "```", "", "**Do NOT manually create or edit `types.ts`** — the CLI command above generates it automatically.", "");
         }
         catch {
             // ignore parse errors
@@ -2259,10 +3101,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()
@@ -2418,14 +3257,21 @@ server.tool("list_section_types", "List all available `get_section_template` sec
     ];
     for (const name of sectionTemplateNames) {
         const meta = loadSectionMeta(name);
-        lines.push(`- \`${name}\`${meta ? ` — ${meta.title}` : ""}`);
+        const builtinMark = BUILTIN_COVERED_TEMPLATES.has(name)
+            ? " [ikas ships a ready-made page for this — ask the user before coding a custom one; see list_ready_made_pages]"
+            : "";
+        lines.push(`- \`${name}\`${meta ? ` — ${meta.title}` : ""}${builtinMark}`);
     }
     lines.push("", "Call `get_section_template(sectionType)` to fetch one.");
     return { content: [{ type: "text", text: lines.join("\n") }] };
 });
 // --- Migration tools ---
 // Tool: analyze_old_theme
-server.tool("analyze_old_theme", "Analyze an old ikas storefront theme.json and produce a structured migration report. Shows all components, custom data definitions, prop type breakdown, and migration recommendations. Use this as the first step when converting an old theme.", { theme_json: z.string().describe("The raw JSON content of the old theme.json file") }, async ({ theme_json }) => {
+server.tool("analyze_old_theme", "Analyze an old ikas storefront theme.json and produce a structured migration report. Shows all components, custom data definitions, prop type breakdown, and migration recommendations. Use this as the first step when converting an old theme.", {
+    theme_json: z
+        .string()
+        .describe("The raw JSON content of the old theme.json file"),
+}, async ({ theme_json }) => {
     try {
         const parsed = JSON.parse(theme_json);
         const analysis = analyzeOldTheme(parsed);
@@ -2433,102 +3279,162 @@ server.tool("analyze_old_theme", "Analyze an old ikas storefront theme.json and
     }
     catch (err) {
         return {
-            content: [{ type: "text", text: `Error parsing theme.json: ${err instanceof Error ? err.message : String(err)}. Make sure you're passing valid JSON.` }],
+            content: [
+                {
+                    type: "text",
+                    text: `Error parsing theme.json: ${err instanceof Error ? err.message : String(err)}. Make sure you're passing valid JSON.`,
+                },
+            ],
         };
     }
 });
 // Tool: get_migration_guide
 const migrationTopicAliases = {
-    "overview": "migration-overview",
-    "migrate": "migration-overview",
-    "custom": "custom-data-conversion",
+    overview: "migration-overview",
+    migrate: "migration-overview",
+    custom: "custom-data-conversion",
     "custom-data": "custom-data-conversion",
-    "customdata": "custom-data-conversion",
+    customdata: "custom-data-conversion",
     "dynamic-list": "custom-data-conversion",
     "component-list": "custom-data-conversion",
-    "slider": "prop-type-mapping",
-    "props": "prop-type-mapping",
+    slider: "prop-type-mapping",
+    props: "prop-type-mapping",
     "prop-mapping": "prop-type-mapping",
-    "types": "prop-type-mapping",
-    "react": "react-to-preact",
-    "preact": "react-to-preact",
-    "observer": "react-to-preact",
-    "libraries": "library-replacements",
-    "swiper": "library-replacements",
-    "headlessui": "library-replacements",
-    "tailwind": "library-replacements",
-    "tailwindcss": "library-replacements",
-    "recharts": "library-replacements",
-    "marquee": "library-replacements",
-    "imports": "storefront-import-mapping",
-    "storefront": "storefront-import-mapping",
+    types: "prop-type-mapping",
+    react: "react-to-preact",
+    preact: "react-to-preact",
+    observer: "react-to-preact",
+    libraries: "library-replacements",
+    swiper: "library-replacements",
+    headlessui: "library-replacements",
+    tailwind: "library-replacements",
+    tailwindcss: "library-replacements",
+    recharts: "library-replacements",
+    marquee: "library-replacements",
+    imports: "storefront-import-mapping",
+    storefront: "storefront-import-mapping",
     "bp-storefront": "storefront-import-mapping",
     "theme-json": "theme-json-anatomy",
-    "anatomy": "theme-json-anatomy",
-    "decompose": "component-decomposition-strategy",
-    "decomposition": "component-decomposition-strategy",
-    "strategy": "component-decomposition-strategy",
-    "project": "complete-project-generation",
-    "generate": "complete-project-generation",
-    "generation": "complete-project-generation",
-    "settings": "settings-conversion",
-    "colors": "settings-conversion",
-    "fonts": "settings-conversion",
-    "find": "finding-new-system-equivalents",
-    "search": "finding-new-system-equivalents",
-    "discover": "finding-new-system-equivalents",
-    "equivalent": "finding-new-system-equivalents",
-    "equivalents": "finding-new-system-equivalents",
-    "replacement": "finding-new-system-equivalents",
+    anatomy: "theme-json-anatomy",
+    decompose: "component-decomposition-strategy",
+    decomposition: "component-decomposition-strategy",
+    strategy: "component-decomposition-strategy",
+    project: "complete-project-generation",
+    generate: "complete-project-generation",
+    generation: "complete-project-generation",
+    settings: "settings-conversion",
+    colors: "settings-conversion",
+    fonts: "settings-conversion",
+    find: "finding-new-system-equivalents",
+    search: "finding-new-system-equivalents",
+    discover: "finding-new-system-equivalents",
+    equivalent: "finding-new-system-equivalents",
+    equivalents: "finding-new-system-equivalents",
+    replacement: "finding-new-system-equivalents",
 };
 const migrationTopicKeys = migrationData
     ? Object.keys(migrationData.topics)
     : [];
-server.tool("get_migration_guide", `Get a migration guide for converting old ikas themes to the new code-component system.${migrationTopicKeys.length > 0 ? ` Available topics: ${migrationTopicKeys.join(", ")}. Also supports aliases like "custom", "slider", "react", "libraries", "imports", "settings".` : ""} Call with topic "list" to see all available topics.`, { topic: z.string().describe("Migration topic key, alias, or 'list' to see all topics") }, async ({ topic }) => {
+server.tool("get_migration_guide", `Get a migration guide for converting old ikas themes to the new code-component system. **Start with \`get_migration_guide("iterative-workflow")\` if you're new to this MCP** — it explains the MCP-vs-LLM responsibility split and the four phases.${migrationTopicKeys.length > 0 ? ` Available topics: ${migrationTopicKeys.join(", ")}. Also supports aliases like "custom", "slider", "react", "libraries", "imports", "settings".` : ""} Call with topic "list" to see all available topics.`, {
+    topic: z
+        .string()
+        .describe("Migration topic key, alias, or 'list' to see all topics"),
+}, async ({ topic }) => {
     if (!migrationData) {
-        return { content: [{ type: "text", text: "Migration data not available. Ensure data/migration.json exists." }] };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "Migration data not available. Ensure data/migration.json exists.",
+                },
+            ],
+        };
     }
     if (topic.toLowerCase() === "list") {
         const available = Object.entries(migrationData.topics)
             .map(([key, t]) => `- \`${key}\` — ${t.title}: ${t.description}`)
             .join("\n");
-        return { content: [{ type: "text", text: `## Available Migration Topics\n\n${available}` }] };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `## Available Migration Topics\n\n${available}`,
+                },
+            ],
+        };
     }
     const topicLower = topic.toLowerCase().replace(/\s+/g, "-");
     const resolvedTopic = migrationTopicAliases[topicLower] || topicLower;
     if (migrationData.topics[resolvedTopic]) {
         const t = migrationData.topics[resolvedTopic];
-        return { content: [{ type: "text", text: `## ${t.title}\n\n${t.content}` }] };
+        return {
+            content: [
+                { type: "text", text: `## ${t.title}\n\n${t.content}` },
+            ],
+        };
     }
     // Try original key
     if (resolvedTopic !== topicLower && migrationData.topics[topicLower]) {
         const t = migrationData.topics[topicLower];
-        return { content: [{ type: "text", text: `## ${t.title}\n\n${t.content}` }] };
+        return {
+            content: [
+                { type: "text", text: `## ${t.title}\n\n${t.content}` },
+            ],
+        };
     }
     // Keyword search
     const matches = searchMigrationTopics(topic);
     if (matches.length > 0) {
         const best = matches[0];
-        return { content: [{ type: "text", text: `## ${best.topic.title}\n\n${best.topic.content}` }] };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `## ${best.topic.title}\n\n${best.topic.content}`,
+                },
+            ],
+        };
     }
     const available = Object.entries(migrationData.topics)
         .map(([key, t]) => `  - \`${key}\` - ${t.title}`)
         .join("\n");
     return {
-        content: [{ type: "text", text: `Migration topic "${topic}" not found. Available topics:\n${available}` }],
+        content: [
+            {
+                type: "text",
+                text: `Migration topic "${topic}" not found. Available topics:\n${available}`,
+            },
+        ],
     };
 });
 // Tool: get_migration_example
-server.tool("get_migration_example", `Get a concrete before/after migration example showing how to convert an old theme component to the new code-component system.${migrationExampleNames.length > 0 ? ` Available examples: ${migrationExampleNames.join(", ")}.` : ""} Call with example "list" to see all examples.`, { example: z.string().describe("Example name or 'list' to see all examples") }, async ({ example }) => {
+server.tool("get_migration_example", `Get a concrete before/after migration example showing how to convert an old theme component to the new code-component system.${migrationExampleNames.length > 0 ? ` Available examples: ${migrationExampleNames.join(", ")}.` : ""} Call with example "list" to see all examples.`, {
+    example: z.string().describe("Example name or 'list' to see all examples"),
+}, async ({ example }) => {
     if (example.toLowerCase() === "list") {
         if (migrationExampleNames.length === 0) {
-            return { content: [{ type: "text", text: "No migration examples available." }] };
+            return {
+                content: [
+                    { type: "text", text: "No migration examples available." },
+                ],
+            };
         }
-        const list = migrationExampleNames.map((name) => {
+        const list = migrationExampleNames
+            .map((name) => {
             const ex = loadMigrationExample(name);
-            return ex ? `- \`${name}\` — ${ex.title}: ${ex.description}` : `- \`${name}\``;
-        }).join("\n");
-        return { content: [{ type: "text", text: `## Available Migration Examples\n\n${list}` }] };
+            return ex
+                ? `- \`${name}\` — ${ex.title}: ${ex.description}`
+                : `- \`${name}\``;
+        })
+            .join("\n");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `## Available Migration Examples\n\n${list}`,
+                },
+            ],
+        };
     }
     const exampleLower = example.toLowerCase();
     let exName = migrationExampleNames.find((n) => n === exampleLower);
@@ -2538,19 +3444,26 @@ server.tool("get_migration_example", `Get a concrete before/after migration exam
     if (!exName) {
         const available = migrationExampleNames.join(", ");
         return {
-            content: [{ type: "text", text: `Migration example "${example}" not found. Available: ${available}` }],
+            content: [
+                {
+                    type: "text",
+                    text: `Migration example "${example}" not found. Available: ${available}`,
+                },
+            ],
         };
     }
     const ex = loadMigrationExample(exName);
     if (!ex) {
-        return { content: [{ type: "text", text: `Failed to load migration example "${exName}".` }] };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Failed to load migration example "${exName}".`,
+                },
+            ],
+        };
     }
-    const parts = [
-        `## ${ex.title}`,
-        "",
-        ex.description,
-        "",
-    ];
+    const parts = [`## ${ex.title}`, "", ex.description, ""];
     for (const [filename, content] of Object.entries(ex.files)) {
         const ext = filename.split(".").pop() || "text";
         const lang = ext === "tsx" || ext === "ts"
@@ -2568,41 +3481,1759 @@ 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;
+    }
+}
+// Coerce a JSON-ARRAY argument (points / settings / colors) into the single JSON-array string the
+// CLI expects. Agents sometimes send these PRE-STRINGIFIED (a JSON string instead of a real array);
+// a blind JSON.stringify would then double-encode it ("[...]" -> "\"[...]\"") and the CLI rejects it
+// with "must be a JSON array". So pass a string through as-is (the CLI parses + validates it) and
+// only stringify real arrays/values. NOTE: only for array args — a scalar `value` arg must NOT use
+// this (a plain string there is a literal value, not stringified JSON).
+function toJsonArrayArg(value) {
+    return typeof value === "string" ? value : JSON.stringify(value ?? []);
+}
+/**
+ * The `confirm` parameter shared by the destructive editor tools.
+ *
+ * Spelled out at length on purpose: a one-word "confirmation" flag reads to a model as a
+ * formality to fill in, and the whole point is that it stands for a human's answer.
+ */
+const CONFIRM_PARAM_DESCRIPTION = "Must be `true`, and only after the USER has explicitly agreed to this specific deletion. It stands for their consent, not for your own confidence \u2014 never set it to clear up something you merely believe is unused, and never re-run with it after a refusal without asking first. The merchant's content goes with the deletion and only the editor's undo stack can bring it back.";
+/** Reply for a destructive tool called without consent. The dev-server action refuses too. */
+function destructiveConfirmRefusal() {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    success: false,
+                    error: "Refused: `confirm` was not true. This deletes the merchant's content and can only be undone from the editor's undo stack. Ask the user whether to proceed, and pass confirm: true only after they agree.",
+                }, null, 2),
+            },
+        ],
+    };
+}
+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 theme 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. Placing a COMMON (global) section — the theme's header/footer — is special: it has ONE shared set of prop values stored on the INDEX (Home) page's placement, so `updates` land there and change that section on every page (the result carries a `common` block), and placing it with `updates` on a non-INDEX page while the INDEX page does not have it is rejected — place and fill it on the INDEX page instead.", {
+    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. COMMON (global) sections — the theme's header and footer — carry an extra `common` field (`isCommon`, `commonSectionType`, `canonicalPageId`/`canonicalElementId`, `valuesArePageSpecific: false`): their prop values are NOT page-specific, they are shared by every page and stored on the INDEX (Home) page's placement, so `setPropNames` for them reflects that one shared record and any write from any page changes the header/footer everywhere. A page customized per storefront-routing/specification holds a SEPARATE set of placements with its own section order in each state: this lists the BASE layer by default and reports the available states in `pageStates` (plus a `scope` field) — pass `sf_routing_id`/`specification_id` to list a state's own placements instead, which is what `move_page_section` needs when reordering that state.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    page_id: z.string().describe("Target page id (from `list_editor_pages`)."),
+    sf_routing_id: z
+        .string()
+        .optional()
+        .describe("List a routing-customized state of the page instead of the base layer. Ids come from the `pageStates` block this tool returns for a customized page."),
+    specification_id: z
+        .string()
+        .optional()
+        .describe("Specification of the customized state to list (used together with `sf_routing_id`)."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, page_id, sf_routing_id, specification_id, port }) => {
+    const args = [
+        "list-page-sections",
+        "--page-id",
+        page_id,
+        ...(sf_routing_id ? ["--sf-routing-id", sf_routing_id] : []),
+        ...(specification_id ? ["--specification-id", specification_id] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: move_page_section
+server.tool("move_page_section", "Reorder a section that is ALREADY placed on a page — the only way to change section order, since the editor UI offers it solely as a drag in the layers tree. Target the placement by its `element_id` from `list_page_sections` (NOT the sectionId/componentId — a page can hold several placements of the same section and each moves independently). Give EITHER `direction` (\"up\"/\"down\", one position — use this for a simple nudge) OR `to_index` (absolute 0-based position), never both. Indices are 0-based and count ONLY placed sections, in exactly the order `list_page_sections` returns them, so you can read that list, pick a target position from it, and pass it straight back. The result returns `fromIndex`, `resultIndex` (where the section ACTUALLY ended up) and `sections` (the full resulting order) — assert on `resultIndex`/`sections` rather than assuming the move landed where you asked; if it lands somewhere other than requested a `note` says so. A reorder that does not take effect comes back as an ERROR, never as a success that changed nothing, so a successful result means the section really moved. Out-of-range indices are rejected with the valid range (and the section's current index) instead of being clamped. Passing a `sectionId`/`componentId` where an `element_id` belongs is detected and the error names the elementId you actually wanted. COMMON (global) sections — the theme's header and footer — are REJECTED: their position is fixed by the theme, so there is nothing to reorder. SCOPE: by default this reorders the page's BASE layer. A page customized per storefront-routing/specification keeps a SEPARATE set of placements and its own section order in each of those states — pass `sf_routing_id` (and `specification_id`) to reorder one of them instead, and read that state's current order with `list_page_sections` using the SAME ids. Whenever the page has any state the result carries `scope`, `pageStates` and `pageStatesNote`: do not report a reorder as verified on such a page without checking them, since reordering the base layer leaves every state exactly as it was. The state must ALREADY exist — creating one duplicates the whole page and is a deliberate editor action, so an unknown routing/specification is rejected with the list of existing states rather than created. To place a NEW section at a specific position use `add_sections_to_page` with its `index` instead; this tool only moves existing placements.", {
+    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 to move (from `list_page_sections`)."),
+    direction: z
+        .enum(["up", "down"])
+        .optional()
+        .describe("Move one position up or down. Provide this or `to_index`, not both."),
+    to_index: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe("Absolute 0-based target position among the page's placed sections. Provide this or `direction`, not both."),
+    sf_routing_id: z
+        .string()
+        .optional()
+        .describe("Reorder a routing-customized state of the page instead of the base layer. Ids come from the `pageStates` block returned by `list_page_sections`. The state must already exist."),
+    specification_id: z
+        .string()
+        .optional()
+        .describe("Specification of the customized state to reorder (used together with `sf_routing_id`)."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, page_id, element_id, direction, to_index, sf_routing_id, specification_id, port, }) => {
+    const args = [
+        "move-page-section",
+        "--page-id",
+        page_id,
+        "--element-id",
+        element_id,
+        ...(direction ? ["--direction", direction] : []),
+        ...(to_index !== undefined ? ["--to-index", String(to_index)] : []),
+        ...(sf_routing_id ? ["--sf-routing-id", sf_routing_id] : []),
+        ...(specification_id ? ["--specification-id", specification_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). COMMON (global) sections — the theme's header and footer — keep ONE shared set of prop values for the whole theme, stored on the INDEX (Home) page's placement; for those this tool reads the values FROM that canonical placement (a non-INDEX placement stores nothing of its own) and returns a `common` block naming `canonicalPageId`/`canonicalElementId`. So the values you get for a header/footer are the live ones the page actually renders no matter which page_id you ask from — do NOT read defaults as \"empty\" and blind-fill them, and remember any write goes to that same shared record and changes all pages.", {
+    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). A COLOR prop can ALSO bind to a global theme color instead of a literal hex — pass `{ "patternValueId": "<id>" }` (the color id from `list_theme_globals` → `colors[].id`) and the prop tracks that global color live (resolved to `var(--<id>)` at render); the id is validated and an unknown one is REJECTED. 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>", ... ] }`; TYPE (style props such as BorderRadiusStyleType/PaddingStyleType/GapStyleType) = the type-shaped object ITSELF, e.g. `{ "value": 8, "unit": "px" }` — get the exact field structure from the prop\'s `writeExample`/`typeName` in `get_component_props` or `get_type_definition("<typeName>")`; unknown fields, wrong field types, and invalid union values (e.g. `"unit": "banana"`) are REJECTED; 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`; PRODUCT_ATTRIBUTE = `{ "productId": "...", "variantId": "...", "attributeId": "..." }` — `variantId` is REQUIRED alongside `productId` (without it the value resolves with `product: null` and the component renders nothing), or bind to the page product with `{ "attributeId": "...", "usePageData": true }` on a product detail page; PRODUCT_ATTRIBUTE_LIST = the same with `"attributeIds": [ "..." ]`, and note the component receives a SINGLE wrapper object, never an array (read both with `getAttributeDetailValues()` / `getAttributeListValues()` — see `get_framework_guide("prop-types")`); 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": "<id from list_categories>" }` (the field is `category`, NOT `categoryId` — `categoryId` is only the standalone CATEGORY entity prop; no productIds here) or `"ALL"` (no ids). Unknown sub-fields inside a PRODUCT_LIST (e.g. `categoryId`) are REJECTED, not silently stored. 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' +
+    "COMMON (global) sections — the theme's HEADER and FOOTER: these render on every page that carries a placement of them (ikas ready-made account/membership pages are born without one) and have ONE shared set of prop values, stored on the INDEX (Home) page's placement. Whichever page_id you write from, the value lands on that single record and changes the header/footer on ALL pages; the response carries a `common` block (`commonSectionType`, `canonicalPageId`, `canonicalElementId`) saying so, and the echoed `value` is read back from that canonical placement. Therefore: ALWAYS `get_section_values` first and change only the prop the user asked about — the props are already filled with the merchant's content even when you are on a page you have not inspected, so blind-filling \"empty-looking\" props overwrites the live header/footer everywhere. If the INDEX page has no placement of the section, there is no record to write to and the call fails telling you to add it to the INDEX page first.\n\n" +
+    "BIND TO A GLOBAL VARIABLE (Theme Setting): instead of a static `value`, pass `bind_global` = the global's `name` (its `variableName`, the `_<id>` form) from `list_theme_globals`. The prop becomes a LIVE dynamic value that always reflects that global's current value — editing the global in Theme Settings updates every bound prop. Use this to wire content to a project-wide setting (e.g. a shared announcement text, brand color, or logo image) rather than duplicating a literal. Pick a global whose type matches the prop (TEXT↔TEXT/RICH_TEXT, NUMBER↔NUMBER, BOOLEAN↔BOOLEAN, IMAGE↔IMAGE, COLOR↔COLOR, ENUM↔ENUM of the SAME enum type — the prop's `enumTypeId` must equal the setting's `enumTypeId`; a mismatch is REJECTED, …). Provide `value` OR `bind_global`, not both. To bind a prop of a COMPONENT_LIST CHILD, also pass `list_path` (the `{ propId, index }` steps down to the child) and set `prop_id` to the child's prop id. Works for every section type, including built-in / code-component sections that have no blueprint.\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()
+        .optional()
+        .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. Omit when using `bind_global`.'),
+    bind_global: z
+        .string()
+        .optional()
+        .describe("Bind this prop to a project GLOBAL variable (Theme Setting) as a LIVE dynamic value instead of writing a static `value` — the prop then always reflects that global's current value (edited in Theme Settings). Pass the global's `name` (its `variableName`, the `_<id>` form) from `list_theme_globals`. Provide `value` OR `bind_global`, not both. Bindable globals include TEXT / RICH_TEXT / NUMBER / BOOLEAN / IMAGE / COLOR / BORDER / SHADOW / ENUM settings; pick a global whose type matches the prop (an ENUM prop only binds an ENUM setting of the same enum type). (This is the general theme-global binding; a COLOR prop can alternatively take an inline `{ \"patternValueId\" }` for theme colors.)"),
+    list_path: z
+        .array(z.object({ propId: z.string(), index: z.number() }))
+        .optional()
+        .describe("Only with `bind_global`: bind a prop of a COMPONENT_LIST child instead of a section-level prop. An array of `{ propId, index }` steps from the section down to the target child; `prop_id` is then the CHILD's prop id (from `get_component_props`)."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, page_id, element_id, prop_id, prop_name, value, bind_global, list_path, 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] : []),
+        ...(bind_global
+            ? [
+                "--bind-global",
+                bind_global,
+                ...(list_path ? ["--list-path", JSON.stringify(list_path)] : []),
+            ]
+            : [
+                "--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`. This is the ONLY way to obtain a real image id — an id cannot be invented. Use the returned `id`: (1) as an IMAGE prop value for `update_section_prop` (e.g. `{ "id": "<returned-id>", "altText": "...", "isVideo": false }`), or (2) as an IMAGE theme global\'s value for `create_theme_global`/`update_theme_global` (e.g. `{ "id": "<returned-id>" }`). An id cannot be invented — an unreal one is stored as given and renders as a broken image, so always use a `upload_image` id or one already listed by `list_theme_globals`. Neither tool uploads; both only reference 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. An update item may instead bind a prop to a project GLOBAL variable (Theme Setting) as a live dynamic value: use `{ prop_id|prop_name, bind_global }` where `bind_global` is the global's `name` (its `variableName`) from `list_theme_globals` — omit `value`. Add `list_path` (an array of `{ propId, index }` steps) to bind a prop of a COMPONENT_LIST child (then `prop_id` is the child's prop id). Static value writes are applied first, then bindings. Prefer this over many update_section_prop(s) calls. If any targeted section is a COMMON (global) one — the theme's header/footer — its values are shared by every page and stored on the INDEX (Home) page's placement: the write goes there and changes that section on ALL pages, the result's `common` block says so, and the echoed values are read back from that canonical placement. Read those sections with `get_section_values` first and only change what was asked; a header/footer missing from the INDEX page has no record to write to and rejects the whole call.", {
+    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()
+                .optional()
+                .describe("Prop value, same shape update_section_prop expects for that type. Omit when using bind_global."),
+            bind_global: z
+                .string()
+                .optional()
+                .describe("Bind this prop to a project GLOBAL variable (Theme Setting) as a live dynamic value instead of a static value. The global's `name` (variableName) from list_theme_globals. Provide value OR bind_global."),
+            list_path: z
+                .array(z.object({ propId: z.string(), index: z.number() }))
+                .optional()
+                .describe("Only with bind_global: `{ propId, index }` steps down to a COMPONENT_LIST child; prop_id is then the child's prop id."),
+        }))
+            .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 } : {}),
+            ...(u.bind_global
+                ? {
+                    bindGlobal: u.bind_global,
+                    ...(u.list_path ? { listPath: u.list_path } : {}),
+                }
+                : { 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 theme 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: delete_page
+server.tool("delete_page", "Delete a theme page and every section placed on it. DESTRUCTIVE and effectively one-way from here (only the editor's own undo stack can bring it back) — ALWAYS get the user's explicit OK before calling it, and never call it to \"clean up\" a page you merely think is unused. Takes the page id from `list_editor_pages` / `get_page_by_type`; there is no name resolution. Refused for the pages a theme cannot run without — INDEX (home), CHECKOUT and NOT_FOUND (404) — and for an ikas-rendered ready-made account page, which must be turned off by its group with `enable_ready_made_pages` so the cleanup that flow does actually runs. Deleting the page currently open in the editor moves it to the home page first. Returns the deleted page's `{ pageId, pageType, name, slug }` plus `remainingPages`. Requires `ikas theme dev` running with the editor connected.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    page_id: z
+        .string()
+        .describe("Id of the page to delete (from `list_editor_pages` or `get_page_by_type`). Strict — no name resolution."),
+    confirm: z.boolean().describe(CONFIRM_PARAM_DESCRIPTION),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, page_id, confirm, port }) => {
+    if (confirm !== true)
+        return destructiveConfirmRefusal();
+    const args = [
+        "delete-page",
+        "--id",
+        page_id,
+        "--yes",
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: remove_page_section
+server.tool("remove_page_section", "Remove ONE section placement from a page — the delete counterpart of `add_section_to_page` / `move_page_section`. DESTRUCTIVE: it takes the merchant's content in that section with it, so get the user's explicit OK first. The checkout section on the CHECKOUT page is refused — the checkout page requires it, so never offer to remove it. Target the PLACEMENT by `element_id` from `list_page_sections`, never the `sectionId` or `componentId` — the same section placed twice has two independent placements and each is removed on its own (passing the wrong id is rejected with the elementId you meant). A common (header/footer) section on the home page is HIDDEN rather than deleted, because the INDEX placement is where a common section's prop values live for EVERY page; the reply says so with `hidden: true`, and `add_section_to_page` brings it back with its values intact. A page customized per routing/specification holds its own placements per state: pass `sf_routing_id`/`specification_id` to remove from that state, otherwise only the BASE layer is touched (the reply lists the states it left alone). Returns the removed placement plus the page's remaining `sections`. Requires `ikas theme dev` running with the editor connected.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    page_id: z
+        .string()
+        .describe("Id of the page holding the placement (from `list_editor_pages`)."),
+    element_id: z
+        .string()
+        .describe("The PLACEMENT's elementId from `list_page_sections` — not the sectionId and not the componentId."),
+    sf_routing_id: z
+        .string()
+        .optional()
+        .describe("Remove from this customized routing state instead of the page's base layer. The state must already exist."),
+    specification_id: z
+        .string()
+        .optional()
+        .describe("Remove from this customized specification state instead of the page's base layer. The state must already exist."),
+    confirm: z.boolean().describe(CONFIRM_PARAM_DESCRIPTION),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, page_id, element_id, sf_routing_id, specification_id, confirm, port, }) => {
+    if (confirm !== true)
+        return destructiveConfirmRefusal();
+    const args = [
+        "remove-page-section",
+        "--page-id",
+        page_id,
+        "--element-id",
+        element_id,
+        "--yes",
+        ...(sf_routing_id ? ["--sf-routing-id", sf_routing_id] : []),
+        ...(specification_id ? ["--specification-id", specification_id] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: publish_theme
+// Tool: list_ready_made_pages
+server.tool("list_ready_made_pages", "List the ikas-rendered ready-made (\"built-in\") account/membership pages (login, register, forgot/recover password, my account, orders, addresses, favorites, email verification) and how to customize them. These pages are rendered by ikas's own components, NOT by sections: a ready-made page carries no sections, so `list_page_sections` shows nothing and `update_section_prop` cannot touch it — `update_ready_made_page_prop` is the write tool. Without arguments returns the roster: per-group (`membership` = login/register/password flows, `account` = my-account pages) enabled state, every ready-made page type with its theme pageId and which props the merchant already edited, plus the SHARED SCOPES (logo, palette, account-menu labels — values edited once that reach every page in the scope's group). Pass `page_type` (e.g. LOGIN) or `scope_id` for that page's/scope's FULL prop schema (types, defaults, ENUM options, translations) and current values (`values` = what the page renders with; `ownValues` = what this page's own layer stores). Pass `sf_routing_id` to read what one storefront routing/locale sees — the no-argument call lists the store's routings (id, path, locale; `isDefault: true` = the base, needing no sf_routing_id). Typical branding flow: read the theme's palette via `list_theme_globals`, then set the shared scope's colors as `{ \"patternValueId\": \"<global color id>\" }` bindings so the pages follow the theme's colors live.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    page_type: z
+        .string()
+        .optional()
+        .describe("One ready-made page's full prop schema and values (e.g. LOGIN, ACCOUNT, ORDERS)."),
+    scope_id: z
+        .string()
+        .optional()
+        .describe("One shared scope's full prop schema and values (scope ids come from the no-argument call)."),
+    sf_routing_id: z
+        .string()
+        .optional()
+        .describe("Read the values one storefront routing/locale sees (default: the base routing)."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, page_type, scope_id, sf_routing_id, port }) => {
+    const args = [
+        "list-builtin-pages",
+        ...(page_type ? ["--page-type", page_type] : []),
+        ...(scope_id ? ["--scope-id", scope_id] : []),
+        ...(sf_routing_id ? ["--sf-routing-id", sf_routing_id] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: update_ready_made_page_prop
+server.tool("update_ready_made_page_prop", 'Set, bind, or clear ONE prop of an ikas-rendered ready-made account/membership page — the write half of `list_ready_made_pages`, and the ONLY way to customize those pages (they have no sections, so `update_section_prop` cannot reach them). Target a page\'s own prop with `page_type` (e.g. LOGIN) or a SHARED prop — logo, palette, menu labels, edited once for every page in the scope\'s group — with `scope_id`. Identify the prop by `prop_id` or `prop_name` from `list_ready_made_pages`. VALUES ARE RAW (no `{ "value": ... }` envelope — an envelope is tolerated and unwrapped): TEXT = the plain string; BOOLEAN = true/false; NUMBER = a number; ENUM = one of the prop\'s `enumOptions` VALUES; COLOR = "#rrggbb" OR `{ "patternValueId": "<global color id>" }` to follow a theme color live (ids from `list_theme_globals` → colors[].id — prefer the binding when branding, so a palette change updates the pages); IMAGE = `{ "id": "<image id>" }` (id from `upload_image`); LINK/LIST_OF_LINK = copy the shape from `list_ready_made_pages` values. `bind_global` (a global\'s `name` from `list_theme_globals`) makes the prop follow a Theme Setting instead of holding a value; `clear: true` deletes the stored value so the prop falls back to the shared value or the manifest default. `sf_routing_id` writes one routing\'s override — use it to localize texts per language; without it you write the base value every routing inherits. Writes are undoable in the editor.', {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    page_type: z
+        .string()
+        .optional()
+        .describe("Page type whose OWN prop to write (e.g. LOGIN). Pass this or scope_id."),
+    scope_id: z
+        .string()
+        .optional()
+        .describe("Shared scope whose prop to write — reaches every ready-made page in its group."),
+    prop_id: z
+        .string()
+        .optional()
+        .describe("Prop id from list_ready_made_pages. Provide this or prop_name."),
+    prop_name: z
+        .string()
+        .optional()
+        .describe("Prop name (alternative to prop_id)."),
+    value: z
+        .any()
+        .optional()
+        .describe("The RAW value (see the tool description for per-type shapes). Omit when using bind_global or clear."),
+    bind_global: z
+        .string()
+        .optional()
+        .describe("Bind the prop to a global variable (Theme Setting) — pass the global's `name` from list_theme_globals."),
+    clear: z
+        .boolean()
+        .optional()
+        .describe("true deletes the stored value; the prop falls back to the shared value or the manifest default."),
+    sf_routing_id: z
+        .string()
+        .optional()
+        .describe("Write one storefront routing's override (localization). Omit to write the base value."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, page_type, scope_id, prop_id, prop_name, value, bind_global, clear, sf_routing_id, port, }) => {
+    const args = [
+        "update-builtin-page-prop",
+        ...(page_type ? ["--page-type", page_type] : []),
+        ...(scope_id ? ["--scope-id", scope_id] : []),
+        ...(prop_id ? ["--prop-id", prop_id] : []),
+        ...(prop_name ? ["--prop-name", prop_name] : []),
+        ...(bind_global
+            ? ["--bind-global", bind_global]
+            : clear
+                ? ["--clear"]
+                : value !== undefined
+                    ? [
+                        "--value",
+                        // ALWAYS JSON-encode: the CLI JSON.parses --value (raw-string fallback), so a
+                        // verbatim TEXT string that happens to parse — "2024", "true", "null" — would
+                        // arrive as a number/boolean/clear. Encoded, it round-trips as the string it is.
+                        JSON.stringify(value),
+                    ]
+                    : []),
+        ...(sf_routing_id ? ["--sf-routing-id", sf_routing_id] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: enable_ready_made_pages
+server.tool("enable_ready_made_pages", 'Turn one GROUP of ikas-rendered ready-made pages on or off: "membership" (login, register, forgot/recover password, email verification) or "account" (my account, orders, order detail, addresses, favorites). Enabling records the choice and creates any page of the group the theme does not have yet — each born rendered by ikas\'s own component; customize them right after with `update_ready_made_page_prop`. Disabling removes ONLY the untouched pages the toggle itself created — a page the merchant built on is never deleted. The flip is one undo step in the editor. Check the current state first with `list_ready_made_pages`.', {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    group: z
+        .enum(["membership", "account"])
+        .describe('"membership" = login/register/password flows; "account" = my-account pages.'),
+    enabled: z
+        .boolean()
+        .describe("true to enable the group, false to disable it."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, group, enabled, port }) => {
+    const args = [
+        "enable-builtin-pages",
+        "--group",
+        group,
+        "--enabled",
+        String(enabled),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+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 theme 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 theme 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).",
+    "",
+    "## Account & membership pages: ASK before you build",
+    "If the page the user wants is a login, register, forgot/recover-password, my-account, orders, order-detail, addresses, favorites or email-verification page: do NOT code a custom section page yet. ikas ships ready-made versions of exactly these pages — fully functional (real auth/order/address flows), customizable (logo, colors, texts) and localizable via update_ready_made_page_prop, the whole group enabled at once with enable_ready_made_pages. FIRST ask the user which they want: the ready-made page (fast, maintained by ikas) or a custom section page (full design freedom) — list the ready-made option FIRST as the recommended default, custom second. Only start coding after the user explicitly chooses custom — and never call enable_ready_made_pages without the user's OK, it creates/removes pages. Start discovery with list_ready_made_pages. USER-FACING NAME: name these in the USER'S OWN LANGUAGE — English: \"ikas's ready-made pages\", Turkish: \"ikas'ın hazır sayfaları\"; never mix the English term into a sentence in another language — the editor UI lists them as Membership Pages / My Account Pages; \"built-in\" is an internal term — keep it out of everything the user sees, including question/option labels. Note: a ready-made page is born with ONLY its own ikas-rendered element — the theme's header/footer are NOT on it (the page draws its own top bar — logo, back-to-store link — and account nav). If the user wants the theme header/footer there, place it with add_section_to_page (sections can sit above/below that element) and suggest turning the page's `showBrandBar` prop off to avoid double chrome.",
+    "",
+    "## 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). A section returned with a `common` field is the theme's header/footer — its values are theme-wide, not this page's; read the 'COMMON (global) sections' section below BEFORE touching it. (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.",
+    "",
+    "## COMMON (global) sections: the header and the footer",
+    "The theme's header and footer are COMMON sections: they render on every page that carries a placement of them (pages created in the editor are seeded with one — EXCEPT ikas ready-made (built-in) account/membership pages, which are born without the theme header/footer) and their prop values are SHARED by the whole theme — there is exactly ONE record, kept on the INDEX (Home) page's placement. A placement of the same section on any other page stores NOTHING of its own.",
+    '- How to recognize one: list_page_sections / get_section_values / the write results return a `common` block for it — `isCommon: true`, `commonSectionType: "header"|"footer"`, `valuesArePageSpecific: false`, plus `canonicalPageId`/`canonicalElementId` (the INDEX placement that holds the values). A page containing one also gets a top-level `commonSectionsNote`.',
+    "- READS are redirected for you: get_section_values / list_page_sections report a common section's values FROM the INDEX placement, whatever page_id you pass. So what you see is what the page actually renders — no need to re-read from the INDEX page.",
+    "- WRITES are redirected too: update_section_prop / update_page_sections / add_sections_to_page store the value on that INDEX record, so the change applies to the header/footer on ALL pages. The echoed value is read back from the canonical placement, so it reflects what was really stored.",
+    '- THE TRAP to avoid: a header/footer is normally already filled with the merchant\'s content. Never conclude a prop is empty and never blind-fill "missing" props — you would overwrite live content on every page, including pages you never opened. Always get_section_values first and change ONLY the prop the user asked about.',
+    "- If the INDEX page has no placement of the section, there is no record: reads return nothing and writes are REJECTED (\"Index page does not have the common section!\"). Fix it by placing the section on the INDEX page (add_section_to_page with the INDEX page id — get it from list_editor_pages / get_page_by_type('INDEX')) and setting its props there; it then renders on the other pages too.",
+    "",
+    "## 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.",
+    "- REORDERING an already-placed section is a different tool: move_page_section(page_id, element_id, direction:'up'|'down' | to_index:<n>). The `index` on add_* only positions a NEW placement; it cannot move an existing one, and the editor UI exposes reordering solely as a drag, so this tool is the only way. Indices are 0-based over the placed sections in list_page_sections order; the result returns `resultIndex` + the full resulting `sections` order — assert on those. Header/footer (COMMON) sections cannot be reordered and are rejected.",
+    "",
+    "## 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 }.',
+    '- SVG naming: the editor shows each svg\'s `class` attribute as its display name in the list; add class="my-icon" to name it. SVG_LIST items with no class render as svg-1, svg-2, ….',
+    '- 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/…): typed objects keyed by a <entity>ListType discriminator plus initialSort/initialLimit. The id field DEPENDS on the type — for PRODUCT_LIST: STATIC → productIds:[{productId,variantId}] (from search_products); CATEGORY → category:'<categoryId>' (from list_categories) — the field is `category`, NOT `categoryId` (categoryId is ONLY the standalone CATEGORY entity prop above); ALL/DISCOUNTED/RECOMMENDED/etc → no id field. Get the exact field set + writeNote from get_component_props, or read+edit an existing value via get_section_values. Unknown sub-fields (e.g. categoryId inside a PRODUCT_LIST) are REJECTED.",
+    '  - 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, how COMMON (global) header/footer sections keep one theme-wide set of values on the INDEX page (and how not to overwrite them), 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 theme dev` running with the editor connected. Two shape gotchas when consuming the result at runtime: (1) color schemes — `colorSchemes.schemes` holds only `{id,name}` slot LABELS; the actual colors live in `colorSchemes.values[].colorsByScheme` keyed by slot id, so iterate `values[].colorsByScheme` (iterating `schemes` renders empty). (2) An IMAGE setting's `value` is an image REFERENCE like `{id:'theme-images/<uuid>'}` with no `.url` — resolve it via `getDefaultSrc`/`getSrc`. (3) Each keyframe now includes its animation `settings` (type-dependent { property, value } entries — duration/iteration/timing/etc. for keyframe, transition for transition) and each point's resolved `styles`, so you can read back the full animation config, not just the `ref`. (4) Each typography entry may include `supportedFontWeights` — the exact numeric weights that text style's font actually ships (e.g. `[400]` for Modak); when present, only set `font_weight` to a value in this list (via `update_text_style`/`create_theme_global`), otherwise the write is rejected. If the field is absent the font's weight set couldn't be determined — fall back to 400 or rely on the validation error. Each typography entry also carries `isDefault` (true for the theme's default/global text style — the editor's \"Make Default Style\"); toggle it via `update_text_style`'s `is_default`. (5) Token NAMES are NOT unique — a theme can contain two tokens with the SAME name (e.g. colors pulled from two different design assets), so NEVER match a token by its human name. ALWAYS identify a token by its `id` (globally unique). IN COMPONENT CODE: prefer embedding the token's id-derived STABLE ref directly — color → cssVar `var(--<id>)`, typography → `className` `_<id>`, keyframe (animation-name) → `ref` `_<id>` — so you don't look anything up at runtime. If you DO need to pick a token out of a `getThemeColors()` / `getThemeTypography()` / `getThemeKeyframes()` / `getThemeColorSchemes()` array, match on `.id` (e.g. `getThemeColors().find(c => c.id === \"<id>\")`), NEVER on `.name`. EXCEPTION — global variables/settings: `getThemeSetting(name)` takes the token's `name`, but here `name` is the unique runtime key (`variableName`, the `_<id>` form returned in this list), which IS safe; do NOT pass a setting's human `displayName`. The update/delete tools also identify a token ONLY by `id` (they do NOT look up by name — on those tools `name` means the NEW name when renaming). Always take the `id` (or, for settings, the `name`/variableName) from THIS list. (6) GROUPING convention: a \"/\" in a token's NAME organizes it into a group in the editor UI — the text before the first \"/\" is the group, the rest is the item label. This applies to COLORS (e.g. \"Brand/Primary\"), TEXT STYLES (e.g. \"Heading/H1\"), and COLOR-SCHEME SLOTS (e.g. \"PrimaryButton/Background\"). When you create globals (via `create_theme_global`/`update_theme_color_scheme`), use \"/\"-prefixed names to keep related tokens grouped and tidy; reuse an existing group's exact prefix so they nest together. (7) ENUM settings: a setting with `type: \"ENUM\"` selects one option of a PROJECT enum and carries `enumTypeId` (the enum's id — the same one an ENUM prop declares as `enumTypeId`) and `options` (`{ label: value }`); its `value` is always one of those option VALUES (never a label), or null when unset. The response's top-level `enumTypes` array lists the project enums a new ENUM setting may select from (`{ id, name, options }`) — use an `id` from it as `enum_type_id` in `create_theme_global`. An ENUM prop can be bound (`bind_global`) only to an ENUM setting of the SAME enum.", {
+    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);
+});
+// Shared text-style (typography) font-property schema — kept in lock-step with the editor's
+// "Update Text Style" modal fields (no color/text-align, since that modal doesn't expose them).
+// Each enum prop documents its accepted values so a bad value is caught with a clear error. Spread
+// into both create_theme_global (typography) and update_text_style so the two never drift apart.
+const textStyleFontParams = {
+    font_family: z
+        .string()
+        .optional()
+        .describe('A real font family the editor offers — a Google Fonts name with EXACT casing (e.g. "Inter", "Roboto", ' +
+        '"Poppins"), or a font already used by an existing text style in list_theme_globals. An unknown font ' +
+        "(or wrong casing) is rejected; do NOT invent a family name."),
+    font_size: z.string().optional(),
+    font_weight: z
+        .string()
+        .optional()
+        .describe("font-weight as a number (e.g. \"600\"); append 'i' for italic (e.g. \"600i\"). A PLAIN number with no 'i' " +
+        "is upright and REMOVES italic if the text style was italic (italic is carried by the weight — re-send the " +
+        "weight without 'i' to turn it off). Must be a weight the chosen " +
+        'font ships — if it isn\'t, the error lists the supported weights; when unsure use "400".'),
+    line_height: z.string().optional(),
+    letter_spacing: z.string().optional(),
+    text_decoration: z
+        .string()
+        .optional()
+        .describe("text-decoration: none | underline | line-through"),
+    text_transform: z
+        .string()
+        .optional()
+        .describe("text-transform: none | uppercase | lowercase | capitalize"),
+    text_overflow: z
+        .string()
+        .optional()
+        .describe("text-overflow: clip | ellipsis"),
+    white_space: z
+        .string()
+        .optional()
+        .describe("white-space: normal | pre | pre-wrap | pre-line | wrap | nowrap | collapse"),
+    line_break: z
+        .string()
+        .optional()
+        .describe("line-break: auto | loose | normal | strict | anywhere"),
+    word_break: z
+        .string()
+        .optional()
+        .describe("word-break: normal | break-all | keep-all"),
+    text_wrap_style: z
+        .string()
+        .optional()
+        .describe("text-wrap-style: auto | balance | pretty | stable"),
+};
+// Turn the supplied text-style font params into `ikas-component` CLI flags (omitted ones dropped).
+// The editor validates each value and rejects an unsupported one with the offending value + allowed set.
+function textStyleFontArgs(input) {
+    const map = {
+        "--font-family": input.font_family,
+        "--font-size": input.font_size,
+        "--font-weight": input.font_weight,
+        "--line-height": input.line_height,
+        "--letter-spacing": input.letter_spacing,
+        "--text-decoration": input.text_decoration,
+        "--text-transform": input.text_transform,
+        "--text-overflow": input.text_overflow,
+        "--white-space": input.white_space,
+        "--line-break": input.line_break,
+        "--word-break": input.word_break,
+        "--text-wrap-style": input.text_wrap_style,
+    };
+    return Object.entries(map).flatMap(([flag, value]) => value ? [flag, value] : []);
+}
+// 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|ENUM); value optional. Pass `value` as a REAL JSON value, never a stringified JSON. Value shapes — TEXT/COLOR: string; RICH_TEXT: HTML string; NUMBER: number; BOOLEAN: real JSON boolean true/false (NOT the string "true"); IMAGE: an image REFERENCE object { id: "theme-images/<uuid>" } (NOT { url }) — the id MUST come from a REAL upload: call `upload_image` (file_path or image_url) and use the id it returns, or reuse an id already listed by `list_theme_globals`. NEVER invent an id — it is stored as given and renders as a broken image, so if you have no image, omit `value` and let the merchant set it from the "Theme Settings" panel; BORDER: { width: { value, unit }, style, color } (width.value must be a number); SHADOW: { x, y, blur, spread, color, position: "outside"|"inside" }; ENUM: a setting that selects ONE option of a PROJECT enum — pass `enum_type_id` (an enum id from `list_theme_globals` → `enumTypes[]`; the same enum an ENUM prop declares as `enumTypeId`; built-in @ikas/* enums are REJECTED) and `value` = one of that enum\'s option VALUES (the strings in its `options`, e.g. "bottom"), NOT a label; omit `value` to leave it unset. Once created, an ENUM prop of the SAME enum can be bound to it with `update_section_prop` `bind_global`, and in component code `themeValue("_<id>")` from `./global-types` narrows to the enum\'s union type. For object types (IMAGE/BORDER/SHADOW) pass an actual JSON object, not a JSON-encoded string. Every value is validated server-side and a wrong shape is REJECTED, not silently stored.\n' +
+    '- color: requires name + value — a CONCRETE color (hex e.g. "#ff0000", rgb()/hsl() or a CSS color name). A color token cannot alias another color, so a "var(...)" reference is REJECTED here (to reuse another theme color, reference its cssVar in component code, or in a colorScheme slot). TIP: a "/" in the `name` GROUPS the color in the editor UI (e.g. "Brand/Primary", "Brand/Accent" appear under a "Brand" group); use this to organize related colors. To CHANGE an existing color later, use `update_theme_color` (edits in place, keeps the cssVar stable) — do NOT delete+recreate.\n' +
+    '- typography: requires name + at least one text-style property. These are exactly the fields the editor\'s "Update Text Style" modal exposes — nothing else (in particular there is NO color or text-align on a text style). VALUE FORMATS (all validated; a bad value is rejected with the offending value and the allowed set): font_weight is one of 100,200,300,400,500,600,700,800,900 (append \'i\' for italic, e.g. "600i") AND must be a weight the chosen font actually ships (many fonts provide only a subset, e.g. "Modak" only ships 400) — if unavailable the call fails and lists the supported weights, so when unsure use 400; stored as a numeric weight + a font-style entry; font_size is a number WITH a unit (e.g. "16px", "1.2rem", "80%"); line_height is "normal", a unitless number (e.g. "1.5") or a length; letter_spacing is "normal" or a length (e.g. "0.02em", "0.5px"); font_family is a real font the editor offers (a Google Fonts name with EXACT casing, e.g. "Inter") — an unknown/invented family is rejected; text_decoration is none|underline|line-through; text_transform is none|uppercase|lowercase|capitalize; text_overflow is clip|ellipsis; white_space is normal|pre|pre-wrap|pre-line|wrap|nowrap|collapse; line_break is auto|loose|normal|strict|anywhere; word_break is normal|break-all|keep-all; text_wrap_style is auto|balance|pretty|stable. TIP: a "/" in the `name` GROUPS the text style in the editor UI (e.g. "Heading/H1", "Heading/H2" appear under a "Heading" group); use this to organize related styles. To CHANGE an existing text style later, use `update_text_style` (edits in place, keeps the `className` stable) — do NOT delete+recreate, which changes the id/className.\n' +
+    "- breakpoint: requires name + width (a positive INTEGER, in px — no decimals). To CHANGE an existing breakpoint later, use `update_theme_breakpoint` (edits in place, keeps the id).\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\". Optional `settings` = animation-level config as { property, value } entries, TYPE-DEPENDENT: for keyframe — animation-duration, animation-iteration-count, animation-play-state, animation-delay, animation-timing-function, animation-direction, animation-fill-mode, animation-timeline, animation-range, transform-origin, backface-visibility; for transition — transition, backface-visibility. Setting these means the editor drives the animation timing (you don't have to hand-write `animation:` CSS). Use the keyframe's `ref` as the CSS animation-name. For a TRANSITION keyframe, put the target/hover-state styles on the 100% point (points[1].styles) — the 0% point is ignored (the start state is the element's own normal state). To CHANGE an existing keyframe later, use `update_theme_keyframe` (edits in place, keeps the `ref` stable) — do NOT delete+recreate, which changes the ref and breaks references.\n" +
+    '- colorScheme: requires name + colors (array of { slotId? | newSlotName?, value }) — each color targets ONE color SLOT, EITHER by `slotId` (an EXISTING slot\'s id, from `list_theme_globals` → colorSchemes.schemes[].id or a `colorsByScheme` key — the id-keyed path) OR by `newSlotName` (a name to CREATE-or-reuse a slot; write-only, for the standard vocabulary and brand-new slots). Pass EXACTLY ONE of the two per entry. `value` is EITHER a literal color (hex/rgb/hsl or a CSS color name, e.g. "#0b1120") OR a REFERENCE to an existing theme color, passed as that color\'s cssVar from `list_theme_globals` (e.g. "var(--<colorId>)"). A `var(--id)` value is stored as a linked reference (editing the global color updates the scheme too and the dependency is tracked) — do NOT inline a hex you copied from a global color; pass its cssVar. SLOT IDENTITY: `colorSchemes.schemes` lists each slot as `{id, name}`. To set a color on an EXISTING slot, find it there by name and pass its `slotId` (names are NOT unique — two design assets can each have a "Background" — so when ambiguous disambiguate via the scheme\'s existing `colorsByScheme` keys); use `newSlotName` only to add a slot the scheme does not have yet. When creating slots use the theme\'s STANDARD slot names so components resolve them: "Background", "Heading", "Text", "Link", "HoverLink", "Border", and per button "PrimaryButton/Background", "PrimaryButton/Text", "PrimaryButton/Border", "PrimaryButton/HoverBackground", "PrimaryButton/HoverText", "PrimaryButton/HoverBorder" (and the same six under "SecondaryButton/"); a "/" groups the slot in the editor UI. A scheme should normally define EVERY slot it uses; omitted slots fall back to the default scheme\'s color. A mistaken slot can be removed with `delete_theme_global` kind `colorSchemeSlot` (by slot id), or renamed in place (id stays stable) with `rename_theme_color_scheme_slot`. To CHANGE an existing scheme later, use `update_theme_color_scheme` (edits in place, keeps the className stable; merges colors by slot, and can set/clear its default flag via `is_default`).\n' +
+    "Read created items back with `list_theme_globals`. Requires `ikas theme 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."),
+    enum_type_id: z
+        .string()
+        .optional()
+        .describe("globalVariable of type ENUM only: id of the project enum the setting selects from (from `list_theme_globals` → `enumTypes[]`). Required for ENUM, invalid for other types."),
+    ...textStyleFontParams,
+    width: z
+        .number()
+        .int()
+        .optional()
+        .describe("breakpoint width in px (positive integer, no decimals)."),
+    keyframe_type: z.enum(["keyframe", "transition"]).optional(),
+    points: z.any().optional().describe("keyframe points array."),
+    settings: z
+        .any()
+        .optional()
+        .describe("keyframe animation settings: array of { property, value } (type-dependent — see tool description)."),
+    colors: z
+        .any()
+        .optional()
+        .describe('colorScheme colors: array of { slotId? | newSlotName?, value } — target an EXISTING slot by `slotId` (its id from list_theme_globals → colorSchemes.schemes / colorsByScheme keys) OR create/reuse one by `newSlotName` (use the standard slot names, "/" to group, e.g. "PrimaryButton/Background"). Exactly one per entry. value = a literal color hex/rgb/hsl/name, OR an existing theme color\'s cssVar "var(--<colorId>)" to store a linked reference.'),
+    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)]
+                    : []),
+                ...(input.enum_type_id
+                    ? ["--enum-type-id", String(input.enum_type_id)]
+                    : []),
+                ...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 ?? ""),
+                ...textStyleFontArgs(input),
+                ...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",
+                toJsonArrayArg(input.points),
+                ...(input.settings !== undefined
+                    ? ["--settings", toJsonArrayArg(input.settings)]
+                    : []),
+                ...p,
+            ];
+            break;
+        case "colorScheme":
+            args = [
+                "create-color-scheme",
+                "--name",
+                String(input.name ?? ""),
+                "--colors",
+                toJsonArrayArg(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` — pass `value` as REAL JSON (objects/booleans, never stringified); BOOLEAN is a real boolean, BORDER/SHADOW are real objects; IMAGE is an image REFERENCE object { id: \"theme-images/<uuid>\" } whose id MUST come from `upload_image` or an existing `list_theme_globals` entry — an invented id renders as a broken image; ENUM `value` is one of the enum's option VALUES (see the setting's `options` in `list_theme_globals`), and `enum_type_id` re-points the setting at another project enum. Changing `type` or `enum_type_id` of a global that props are bound to is REJECTED (the error names the places) — unbind those props first. Values are validated server-side; a wrong shape is REJECTED, not silently stored.", {
+    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|ENUM)."),
+    value: z
+        .any()
+        .optional()
+        .describe('New value as REAL JSON (shape depends on type; e.g. BOOLEAN: true/false, NUMBER: 12, IMAGE: { id: "theme-images/<uuid>" } from upload_image, ENUM: an option VALUE string — see create_theme_global). An invented IMAGE id renders as a broken image.'),
+    enum_type_id: z
+        .string()
+        .optional()
+        .describe('ENUM only: the project enum to select from (from `list_theme_globals` → `enumTypes[]`); may be passed alone to re-point an unbound ENUM global, or together with `type: "ENUM"`.'),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, name, display_name, type, value, enum_type_id, 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)] : []),
+        ...(enum_type_id !== undefined ? ["--enum-type-id", enum_type_id] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: update_theme_keyframe
+server.tool("update_theme_keyframe", "Update an existing theme keyframe IN PLACE in the connected editor. Prefer this over delete+recreate: " +
+    "it keeps the keyframe's id, so its runtime `ref` (the CSS animation-name `_<id>`) stays STABLE and every " +
+    "existing reference to it keeps working. Identify the keyframe by `id` (REQUIRED — globally unique, from " +
+    "`list_theme_globals`); name-based lookup is intentionally NOT supported here because names can collide across " +
+    "design assets. To rename, pass `name` (the new name) together with `id`. " +
+    "`points` REPLACES the keyframe's points: an array of { point, styles? } where `point` is a CSS " +
+    'keyframe offset (e.g. "0%", "50%", "100%") and each style is { property, value } using a CSS property ' +
+    "name (opacity, transform, filter, background, color, …). Pass `points` as REAL JSON (not a stringified array). " +
+    "For a TRANSITION keyframe, put the target/hover-state styles on the 100% point (points[1].styles) — the 0% " +
+    "point is ignored (the start state is the element's own normal state). " +
+    "Optional `settings` REPLACES the keyframe's animation settings (type-dependent { property, value } entries — " +
+    "see `create_theme_global`); OMIT it to keep the existing settings, or pass [] to clear them. " +
+    "Requires `ikas theme dev` running with the editor connected.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    id: z
+        .string()
+        .describe("Keyframe id (REQUIRED) from `list_theme_globals`. The token is always identified by id."),
+    name: z
+        .string()
+        .optional()
+        .describe("Optional NEW name to rename the keyframe to. NOT used to find the token — lookup is always by id."),
+    keyframe_type: z
+        .enum(["keyframe", "transition"])
+        .optional()
+        .describe("Optional new keyframe type."),
+    points: z
+        .any()
+        .describe("New keyframe points array of { point, styles? } — REPLACES the existing points."),
+    settings: z
+        .any()
+        .optional()
+        .describe("New animation settings { property, value } array (type-dependent — see create_theme_global). Omit to keep existing; [] to clear."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, id, name, keyframe_type, points, settings, port }) => {
+    const args = [
+        "update-keyframe",
+        "--id",
+        id,
+        ...(name !== undefined ? ["--name", name] : []),
+        ...(keyframe_type ? ["--type", keyframe_type] : []),
+        "--points",
+        toJsonArrayArg(points),
+        ...(settings !== undefined
+            ? ["--settings", toJsonArrayArg(settings)]
+            : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: update_text_style
+server.tool("update_text_style", "Update an existing theme typography token (text style) IN PLACE in the connected editor. Prefer this over " +
+    "delete+recreate: it keeps the text style's id, so its `className` (`_<id>`) — and every section bound to it — " +
+    "stays STABLE. Identify the text style by `id` (REQUIRED — globally unique, from `list_theme_globals`); " +
+    "name-based lookup is intentionally NOT supported here because names can collide across design assets. " +
+    "To rename, pass `name` (the new name) together with `id`. Pass only the properties you want to change; omitted " +
+    'ones keep their existing values. The settable properties are exactly the editor\'s "Update Text Style" modal ' +
+    "fields — there is NO color or text-align on a text style. VALUE FORMATS (all validated; a bad value is rejected " +
+    "with the offending value and the allowed set): font_weight is one of 100…900 (append 'i' for italic, e.g. " +
+    '"600i") AND must be a weight the chosen font actually ships — many fonts only provide a subset (e.g. "Modak" ' +
+    "only ships 400); if a weight isn't available the call fails and the error lists the supported weights, so when " +
+    'unsure use 400; font_size is a number with a unit (e.g. "16px"); line_height is "normal", a unitless number ' +
+    'or a length; letter_spacing is "normal" or a length (e.g. "0.02em"); font_family is a real font the editor ' +
+    'offers (a Google Fonts name with EXACT casing, e.g. "Inter") — an unknown/invented family is rejected; ' +
+    "text_decoration is none|underline|" +
+    "line-through; text_transform is none|uppercase|lowercase|capitalize; text_overflow is clip|ellipsis; white_space " +
+    "is normal|pre|pre-wrap|pre-line|wrap|nowrap|collapse; line_break is auto|loose|normal|strict|anywhere; word_break " +
+    "is normal|break-all|keep-all; text_wrap_style is auto|balance|pretty|stable. Set `is_default: true` to make " +
+    'this text style the theme\'s default/global style (the editor\'s right-click "Make Default Style" / "Global ' +
+    "Stil Yap\") — any other default in the group is cleared; `is_default: false` removes the flag. A text style's " +
+    "current default state is readable from `list_theme_globals` (each typography entry's `isDefault`). Requires " +
+    "`ikas theme dev` running with the editor connected.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    id: z
+        .string()
+        .describe("Text style id (REQUIRED) from `list_theme_globals`. The token is always identified by id."),
+    name: z
+        .string()
+        .optional()
+        .describe("Optional NEW name to rename the text style to. NOT used to find the token — lookup is always by id."),
+    ...textStyleFontParams,
+    is_default: z
+        .boolean()
+        .optional()
+        .describe("true → make this the theme's default/global text style (clears any other default); false → remove the " +
+        "default flag. Omit to leave the default state unchanged."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async (input) => {
+    const { project_root, id, name, is_default, port } = input;
+    const args = [
+        "update-text-style",
+        "--id",
+        id,
+        ...(name !== undefined ? ["--name", name] : []),
+        ...textStyleFontArgs(input),
+        ...(is_default === true
+            ? ["--default"]
+            : is_default === false
+                ? ["--no-default"]
+                : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: update_theme_color
+server.tool("update_theme_color", "Update an existing theme color token IN PLACE in the connected editor. Prefer this over delete+recreate: " +
+    "it keeps the color's id, so its cssVar (`var(--<id>)`) — and every element style bound to it — stays STABLE. " +
+    "Identify it by `id` (REQUIRED — globally unique, from `list_theme_globals`); name-based lookup is intentionally " +
+    "NOT supported here because a theme can have two colors with the same name (e.g. from two different design assets). " +
+    "To rename, pass `name` (the new name) together with `id`. Pass `value` to change the color — a CONCRETE " +
+    'color (hex/rgb/hsl or a CSS color name), NOT a "var(...)" reference (a color token can\'t alias another ' +
+    "color); omit it to only rename. Requires `ikas-component " +
+    "dev` running with the editor connected.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    id: z
+        .string()
+        .describe("Color id (REQUIRED) from `list_theme_globals`. The token is always identified by id."),
+    name: z
+        .string()
+        .optional()
+        .describe("Optional NEW name to rename the color to. NOT used to find the token — lookup is always by id."),
+    value: z
+        .string()
+        .optional()
+        .describe('New color value — a concrete color (e.g. "#ff0000", rgb/hsl/name), not a "var(...)" reference. Omit to only rename.'),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, id, name, value, port }) => {
+    const args = [
+        "update-color",
+        "--id",
+        id,
+        ...(name !== undefined ? ["--name", name] : []),
+        ...(value !== undefined ? ["--value", value] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: update_theme_breakpoint
+server.tool("update_theme_breakpoint", "Update an existing theme breakpoint IN PLACE in the connected editor (keeps its id). Identify it by `id` " +
+    "(REQUIRED — globally unique, from `list_theme_globals`); name-based lookup is intentionally NOT supported here " +
+    "because names can collide across design assets. To rename, pass `name` (the new name) together with `id`. " +
+    "Pass `width` (px) to change it; omit it to only rename. " +
+    "Requires `ikas theme dev` running with the editor connected.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    id: z
+        .string()
+        .describe("Breakpoint id (REQUIRED) from `list_theme_globals`. The token is always identified by id."),
+    name: z
+        .string()
+        .optional()
+        .describe("Optional NEW name to rename the breakpoint to. NOT used to find the token — lookup is always by id."),
+    width: z
+        .number()
+        .int()
+        .optional()
+        .describe("New breakpoint width in px (positive integer, no decimals). Omit to only rename."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, id, name, width, port }) => {
+    const args = [
+        "update-breakpoint",
+        "--id",
+        id,
+        ...(name !== undefined ? ["--name", name] : []),
+        ...(width !== undefined ? ["--width", String(width)] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: update_theme_color_scheme
+server.tool("update_theme_color_scheme", "Update an existing theme color scheme (palette) IN PLACE in the connected editor. Prefer this over " +
+    "delete+recreate: it keeps the scheme's id, so its className (`_<id>`) stays STABLE. Identify it by `id` " +
+    "(REQUIRED — globally unique, from `list_theme_globals`); name-based lookup is intentionally NOT supported here " +
+    "because names can collide across design assets. To rename, pass `name` (the new name) together with `id`. " +
+    "`colors` is an array of { slotId? | newSlotName?, value } — each entry targets ONE slot, EITHER by " +
+    "`slotId` (an EXISTING slot's id, from list_theme_globals colorsByScheme keys / colorSchemes.schemes — the " +
+    "id-keyed path; slot names ARE listed in colorSchemes.schemes but are not unique, so prefer the scheme's colorsByScheme keys to get the right id) OR by `newSlotName` (create/reuse " +
+    'a slot by name; use the standard slot names, "/" to group, e.g. "PrimaryButton/Background"); value = a ' +
+    'literal color hex/rgb/hsl/name, OR an existing theme color\'s cssVar "var(--<colorId>)" from ' +
+    "list_theme_globals to store it as a LINKED reference — pass the cssVar, not a hex copied from a global color) " +
+    "and MERGES by slot — only the slots you pass change. Pass `colors` as REAL " +
+    "JSON (not a stringified array). Set `is_default: true` to make this the theme's DEFAULT scheme (the " +
+    "fallback whose colors fill any slot a non-default scheme leaves unset); this is exclusive — the editor " +
+    "automatically clears the default flag from any other scheme in the same group, so there is always exactly " +
+    "one default. Set `is_default: false` to remove the default flag from this scheme. Omit all of name/colors/" +
+    "is_default to no-op. Requires `ikas theme dev` running with the editor connected.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    id: z
+        .string()
+        .describe("Color scheme id (REQUIRED) from `list_theme_globals`. The token is always identified by id."),
+    name: z
+        .string()
+        .optional()
+        .describe("Optional NEW name to rename the color scheme to. NOT used to find the token — lookup is always by id."),
+    colors: z
+        .any()
+        .optional()
+        .describe('Array of { slotId? | newSlotName?, value } to set — target an existing slot by `slotId` (from list_theme_globals colorsByScheme keys / colorSchemes.schemes) or create/reuse by `newSlotName`; value = a literal color hex/rgb/hsl/name, OR an existing theme color\'s cssVar "var(--<colorId>)" (linked reference). Merges by slot. Omit to only rename.'),
+    is_default: z
+        .boolean()
+        .optional()
+        .describe("true = make this the default scheme (exclusive — the editor clears the default flag from every other scheme in its group); false = remove the default flag. Omit to leave the default unchanged. The result echoes the persisted `isDefault`."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, id, name, colors, is_default, port }) => {
+    const args = [
+        "update-color-scheme",
+        "--id",
+        id,
+        ...(name !== undefined ? ["--name", name] : []),
+        ...(colors !== undefined ? ["--colors", toJsonArrayArg(colors)] : []),
+        ...(is_default === true
+            ? ["--default"]
+            : is_default === false
+                ? ["--no-default"]
+                : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: rename_theme_color_scheme_slot
+server.tool("rename_theme_color_scheme_slot", 'Rename a color scheme SLOT (a scheme key like "Background" or "PrimaryButton/Text") IN PLACE in the ' +
+    "connected editor. A slot's id is STABLE, so renaming keeps every runtime reference intact " +
+    "(`var(--<slotId>)` in CSS, `colorsByScheme[slotId]` in component code) — only the human display name " +
+    "changes; nothing rebinds. Identify the slot by `id` (REQUIRED — the slot id from `list_theme_globals` → " +
+    "colorSchemes.schemes[].id or a `colorsByScheme` key); name-based lookup is intentionally NOT supported " +
+    'because slot names can collide across design assets. `name` is the NEW slot name (a "/" groups it in the ' +
+    'editor UI, e.g. "PrimaryButton/Background"). Only non-design-asset (user/theme) slots can be renamed here. ' +
+    "This renames the slot itself across ALL schemes that use it (a slot is shared) — it does NOT rename a single " +
+    "scheme/palette (for that use `update_theme_color_scheme`). Requires `ikas theme dev` running with the " +
+    "editor connected.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    id: z
+        .string()
+        .min(1, "id is REQUIRED — the slot id from list_theme_globals (colorSchemes.schemes[].id / colorsByScheme keys).")
+        .describe("Slot id (REQUIRED) from `list_theme_globals` → colorSchemes.schemes[].id / colorsByScheme keys. The slot is always identified by id."),
+    name: z
+        .string()
+        .min(1, "name is REQUIRED — the new slot name (non-empty).")
+        .describe('The NEW slot name (non-empty). A "/" groups it in the editor UI (e.g. "PrimaryButton/Background").'),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, id, name, port }) => {
+    const args = [
+        "rename-color-scheme-slot",
+        "--id",
+        id,
+        "--name",
+        name,
+        ...(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`. For `kind: colorSchemeSlot` pass the color SLOT id (from `list_theme_globals` → colorSchemes.schemes[].id or a `colorsByScheme` key) — this deletes the slot itself across ALL schemes (use it to clean up a junk slot created by a typo); it CASCADES: the slot\'s color is removed from every scheme and any element/component style bound to that slot is cleared, so only delete a slot you are sure is unused. Only non-design-asset (user/theme) slots can be deleted here. Get names/ids from `list_theme_globals`. Deleting a non-existent id fails with a "not found" error (it does NOT report a false success), so a success result means the token really existed and was removed.', {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    kind: z
+        .enum([
+        "globalVariable",
+        "color",
+        "typography",
+        "breakpoint",
+        "keyframe",
+        "colorScheme",
+        "colorSchemeSlot",
+    ])
+        .describe("What to delete."),
+    name: z
+        .string()
+        .optional()
+        .describe("globalVariable runtime key (from `list_theme_globals`)."),
+    id: z
+        .string()
+        .optional()
+        .describe("design-token id, or for colorSchemeSlot the slot id from `list_theme_globals` → colorSchemes.schemes."),
+    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() {