@ikas/code-components-mcp 1.4.0-beta.15 → 1.4.0-beta.151

package/dist/index.js

@@ -98,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");
@@ -261,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);
@@ -288,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`);
@@ -327,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`);
@@ -342,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) {
@@ -352,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 + "  "));
@@ -364,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 = [];
@@ -446,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));
             }
@@ -481,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];
@@ -495,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);
         }
@@ -504,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] });
         }
@@ -521,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)
@@ -532,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;
@@ -564,7 +592,7 @@ function generateMigrationPlan(theme, projectName, oldSourceDir) {
     parts.push(`# Theme Migration Plan — \`${projectName}\``);
     parts.push("");
     parts.push(`**Generated:** ${new Date().toISOString().slice(0, 10)}`);
-    parts.push(`**Source:** ${components.length} old components, ${customData.filter(cd => cd.isRoot).length} custom data types, ${(theme.pages || []).length} pages`);
+    parts.push(`**Source:** ${components.length} old components, ${customData.filter((cd) => cd.isRoot).length} custom data types, ${(theme.pages || []).length} pages`);
     parts.push("");
     parts.push(`> ## READ THIS FIRST`);
     parts.push(`>`);
@@ -654,16 +682,22 @@ function generateMigrationPlan(theme, projectName, oldSourceDir) {
             const cdType = cd.type || "?";
             let shape = "";
             if (cd.type === "ENUM") {
-                const opts = (cd.enumOptions || []).map((o) => o.value || o.displayName).filter(Boolean);
+                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);
+                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)_`;
+            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("");
@@ -697,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 = [];
@@ -707,8 +745,13 @@ function generateMigrationPlan(theme, projectName, oldSourceDir) {
                     if (cd && (cd.type === "DYNAMIC_LIST" || cd.type === "STATIC_LIST")) {
                         const itemObj = cd.nestedData?.[0];
                         if (itemObj) {
-                            const childName = itemObj.typescriptName || (itemObj.name ? itemObj.name.replace(/[^a-zA-Z0-9]/g, "") : `${oldName}Item`);
-                            const fields = (itemObj.nestedData || []).map((f) => f.key || f.name || "?").slice(0, 8);
+                            const childName = itemObj.typescriptName ||
+                                (itemObj.name
+                                    ? itemObj.name.replace(/[^a-zA-Z0-9]/g, "")
+                                    : `${oldName}Item`);
+                            const fields = (itemObj.nestedData || [])
+                                .map((f) => f.key || f.name || "?")
+                                .slice(0, 8);
                             children.push({ propName: p.name || "?", childName, fields });
                         }
                     }
@@ -767,11 +810,25 @@ function generateMigrationPlan(theme, projectName, oldSourceDir) {
 }
 // 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;
@@ -790,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));
             }
         }
@@ -807,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 {
@@ -821,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);
@@ -829,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);
                 }
@@ -892,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();
@@ -908,27 +982,38 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
             customDataMap.set(cd.id, cd);
     }
     // Find the component — try match by dir, displayName, id, or new-id
-    const target = components.find(c => {
+    const target = components.find((c) => {
         if (!c)
             return false;
-        if (c.dir === sectionName || c.displayName === sectionName || c.id === sectionName)
+        if (c.dir === sectionName ||
+            c.displayName === sectionName ||
+            c.id === sectionName)
             return true;
         const kebab = toKebabCase(c.dir || c.displayName || c.id || "");
         const newId = `${projectName}-${kebab}`;
         return newId === sectionName;
     });
     if (!target) {
-        const available = components.map(c => c.dir || c.displayName || c.id).filter(Boolean).join(", ");
+        const available = components
+            .map((c) => c.dir || c.displayName || c.id)
+            .filter(Boolean)
+            .join(", ");
         return `Section "${sectionName}" not found in theme. Available: ${available}`;
     }
     const parts = [];
     const oldName = target.displayName || target.dir || target.id || "Unknown";
     const kebabName = toKebabCase(target.dir || target.displayName || target.id || "unknown");
     const sectionId = `${projectName}-${kebabName}`;
-    const sectionPascal = (target.dir || target.displayName || "").replace(/[^a-zA-Z0-9]/g, "") || kebabName.split("-").map(s => s[0]?.toUpperCase() + s.slice(1)).join("");
+    const sectionPascal = (target.dir || target.displayName || "").replace(/[^a-zA-Z0-9]/g, "") ||
+        kebabName
+            .split("-")
+            .map((s) => s[0]?.toUpperCase() + s.slice(1))
+            .join("");
     // Scan the old source for imports, libraries, field usage
-    const propNames = (target.props || []).map(p => p.name || "").filter(Boolean);
-    const sourceScan = (oldSourceDir && target.dir)
+    const propNames = (target.props || [])
+        .map((p) => p.name || "")
+        .filter(Boolean);
+    const sourceScan = oldSourceDir && target.dir
         ? scanSectionSource(path.join(oldSourceDir, target.dir), propNames)
         : null;
     parts.push(`# Section Migration Plan: ${oldName}`);
@@ -974,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("");
@@ -1020,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);
@@ -1028,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);
@@ -1039,7 +1132,10 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
                 if (cd.type === "DYNAMIC_LIST" || cd.type === "STATIC_LIST") {
                     // Child component needed
                     const itemObj = cd.nestedData?.[0];
-                    const childName = itemObj?.typescriptName || (itemObj?.name ? itemObj.name.replace(/[^a-zA-Z0-9]/g, "") : `${sectionPascal}Item`);
+                    const childName = itemObj?.typescriptName ||
+                        (itemObj?.name
+                            ? itemObj.name.replace(/[^a-zA-Z0-9]/g, "")
+                            : `${sectionPascal}Item`);
                     const childProps = [];
                     const nestedWarnings = [];
                     for (const f of (itemObj?.nestedData || [])) {
@@ -1050,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);
@@ -1066,10 +1169,14 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
                     if (childProps.length === 0 && sourceScan?.propFieldUsage[oldName]) {
                         const inferred = sourceScan.propFieldUsage[oldName];
                         for (const fieldName of inferred) {
-                            childProps.push({ name: fieldName, displayName: fieldName, type: "TEXT" });
+                            childProps.push({
+                                name: fieldName,
+                                displayName: fieldName,
+                                type: "TEXT",
+                            });
                         }
                         if (inferred.length > 0) {
-                            notes = `Was CUSTOM → ${cd.type} with empty customData. **Inferred props from source usage:** ${inferred.map(f => `\`${f}\``).join(", ")}. Verify types and required flags — default inferred type is TEXT.`;
+                            notes = `Was CUSTOM → ${cd.type} with empty customData. **Inferred props from source usage:** ${inferred.map((f) => `\`${f}\``).join(", ")}. Verify types and required flags — default inferred type is TEXT.`;
                         }
                     }
                     children.push({
@@ -1098,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);
@@ -1113,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;
@@ -1121,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);
@@ -1130,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);
@@ -1139,7 +1260,9 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
     }
     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));
+    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("");
@@ -1154,7 +1277,9 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
             let shape = "";
             let shapeKind = "unknown";
             if (cd.type === "ENUM") {
-                const opts = (cd.enumOptions || []).map((o) => o.value || o.displayName).filter(Boolean);
+                const opts = (cd.enumOptions || [])
+                    .map((o) => o.value || o.displayName)
+                    .filter(Boolean);
                 shape = `enum {${opts.slice(0, 6).join(", ")}${opts.length > 6 ? ", ..." : ""}}`;
                 shapeKind = "enum";
             }
@@ -1187,7 +1312,8 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
             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 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;
@@ -1222,7 +1348,10 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
                     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 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)
@@ -1232,7 +1361,11 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
                         fType = "NUMBER";
                     else if (fType === "PRODUCT_DETAIL")
                         fType = "PRODUCT";
-                    compPropsForCli.push({ name: f.key, displayName: f.name || f.key, type: fType });
+                    compPropsForCli.push({
+                        name: f.key,
+                        displayName: f.name || f.key,
+                        type: fType,
+                    });
                 }
                 parts.push("```bash");
                 if (isMinimal) {
@@ -1271,7 +1404,10 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
             existing.usedByProps.push(ch.propName);
         }
         else {
-            uniqueChildren.set(ch.childName, { child: ch, usedByProps: [ch.propName] });
+            uniqueChildren.set(ch.childName, {
+                child: ch,
+                usedByProps: [ch.propName],
+            });
         }
     }
     if (uniqueChildren.size > 0) {
@@ -1284,7 +1420,7 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
         for (const { child: ch, usedByProps } of uniqueChildren.values()) {
             parts.push(`### \`${ch.childName}\``);
             const propsLabel = usedByProps.length > 1
-                ? `Used by parent props: ${usedByProps.map(p => `\`${p}\``).join(", ")} (${usedByProps.length}×)`
+                ? `Used by parent props: ${usedByProps.map((p) => `\`${p}\``).join(", ")} (${usedByProps.length}×)`
                 : `For parent prop: \`${usedByProps[0]}\``;
             parts.push(propsLabel);
             parts.push(`Old customData: "${ch.customDataName}"`);
@@ -1330,12 +1466,15 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
         parts.push(`- **Every COMPONENT_LIST slot needs a child component to render individual items.** A product list needs a ProductCard child, a blog list needs a BlogCard child, etc. Check if the child already exists (run \`config list\` to see all components and their opaque ids; reuse the existing id in \`filteredComponentIds\`). If not, create it as a registered component and use the \`componentId\` from the CLI's response.`);
     }
     // Check if the section itself has data-driven list props (PRODUCT_LIST, BLOG_LIST, CATEGORY_LIST)
-    const dataListProps = (target.props || []).filter(p => p.type === "PRODUCT_LIST" || p.type === "BLOG_LIST" || p.type === "CATEGORY_LIST" || p.type === "BRAND_LIST");
+    const dataListProps = (target.props || []).filter((p) => p.type === "PRODUCT_LIST" ||
+        p.type === "BLOG_LIST" ||
+        p.type === "CATEGORY_LIST" ||
+        p.type === "BRAND_LIST");
     if (dataListProps.length > 0) {
         parts.push("");
         parts.push(`### Data-Driven List Rendering`);
         parts.push("");
-        parts.push(`This section has data-driven list props: ${dataListProps.map(p => `\`${p.name}\` (${p.type})`).join(", ")}.`);
+        parts.push(`This section has data-driven list props: ${dataListProps.map((p) => `\`${p.name}\` (${p.type})`).join(", ")}.`);
         parts.push(`These are NOT COMPONENT_LIST — the data comes from dynamic queries (filters, categories, search), not hand-picked items. Render items **internally** by mapping over the data:`);
         parts.push("");
         parts.push("```tsx");
@@ -1362,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`);
@@ -1393,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"))
@@ -1402,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)`);
@@ -1433,10 +1589,26 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
     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)) {
@@ -1444,9 +1616,18 @@ function matchScore(text, query) {
     }
     // Word matches
     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 && squashIdentifier(text).includes(squashed)) {
+                score += 2;
+            }
+        }
     }
     // Name exact match bonus
     if (lower === queryLower) {
@@ -1474,8 +1655,7 @@ function levenshtein(a, b) {
             const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
             curr[j] = Math.min(curr[j - 1] + 1, // insertion
             prev[j] + 1, // deletion
-            prev[j - 1] + cost // substitution
-            );
+            prev[j - 1] + cost);
         }
         for (let j = 0; j <= n; j++)
             prev[j] = curr[j];
@@ -1506,17 +1686,29 @@ function searchFunctions(query) {
     const scored = storefrontData.functions
         .map((fn) => {
         const nameScore = matchScore(fn.name, query) * 3;
-        const displayNameScore = fn.displayName ? matchScore(fn.displayName, query) * 3 : 0;
+        const displayNameScore = fn.displayName
+            ? matchScore(fn.displayName, query) * 3
+            : 0;
         const descScore = matchScore(fn.description, query);
-        const catScore = fn.categories.some((c) => matchScore(c, query) > 0) ? 5 : 0;
+        const catScore = fn.categories.some((c) => matchScore(c, query) > 0)
+            ? 5
+            : 0;
         const paramScore = fn.params.some((p) => matchScore(p.name, query) > 0 || matchScore(p.description, query) > 0)
             ? 2
             : 0;
         const sigScore = matchScore(fn.signature, query) * 2;
-        const typeScore = fn.parameterTypes?.some((t) => matchScore(t, query) > 0) ? 8 : 0;
+        const typeScore = fn.parameterTypes?.some((t) => matchScore(t, query) > 0)
+            ? 8
+            : 0;
         return {
             fn,
-            score: nameScore + displayNameScore + descScore + catScore + paramScore + sigScore + typeScore,
+            score: nameScore +
+                displayNameScore +
+                descScore +
+                catScore +
+                paramScore +
+                sigScore +
+                typeScore,
         };
     })
         .filter((item) => item.score > 0)
@@ -1530,7 +1722,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);
@@ -1545,14 +1741,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}`);
@@ -1579,7 +1795,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(", ")}`);
@@ -1587,8 +1803,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 = {}) {
@@ -1596,13 +1816,21 @@ function formatTypeDefinition(td, opts = {}) {
     const lines = [];
     lines.push(`## ${td.name}`);
     lines.push("", `**Kind:** ${td.kind} | **Domain:** ${td.domain}`);
-    if (td.kind === "type") {
+    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};`);
             }
         }
@@ -1629,7 +1857,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}\``);
             }
@@ -1638,7 +1868,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");
 }
@@ -1647,6 +1879,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}`;
@@ -1656,7 +1892,14 @@ const server = new McpServer({
     name: "ikas-code-components",
     version: "0.1.0",
 }, {
-    instructions: "Examples and section templates from this server are API reference only — reuse imports, function calls, and data-access patterns; create your own JSX structure, CSS class names, and visual design.",
+    instructions: "Examples and section templates from this server are API reference only — reuse imports, function calls, and data-access patterns; create your own JSX structure, CSS class names, and visual design.\n\n" +
+        "Live-editor actions (require `ikas-component dev` running with the editor connected): `list_editor_pages` → page ids; `list_imported_sections` → imported component ids; `import_section` → import a built component; `add_section_to_page` → place one section (`add_sections_to_page` places MANY at once and can set their props in the same call — fastest way to build a page); `list_page_sections` → the sections placed on a page (LEAN roster: per-placement `elementId`, `componentId`, `propCount`, which props are filled — NO schema/values, so it never truncates); `get_component_props` → a component's prop blueprint (types, ENUM valid `options`, COMPONENT_LIST `allowedComponentIds`) for any section OR child id; `get_section_values` → one section's current prop values (for read-modify-write); `get_page_by_type` → a theme page id by pageType (e.g. CATEGORY), to build PAGE links to entities (`create_page` adds that page if it does not exist yet, so you never guess a slug); `update_section_prop` → change a single prop value of a placed section (`update_page_sections` fills MANY sections/props of a page in ONE call — strongly prefer it to cut round-trips when filling content); `upload_image` → upload one image (file or URL) and get an image id (`upload_images` uploads many in one call — prefer it for several); `search_products` / `list_categories` / `list_brands` / `list_blogs` / `list_blog_categories` → find real entity ids for PRODUCT/CATEGORY/BRAND/BLOG/BLOG_CATEGORY prop values; `publish_theme` → publish the theme LIVE and get back the preview URL to review (guarded — needs `confirm:true`, and `confirm_production:true` for the main theme; only call it when the user explicitly asks to publish). For the full end-to-end process (placing a section and filling its content, with per-prop value shapes and COMPONENT_LIST rules), call `get_editor_workflow` first.\n\n" +
+        "To CHANGE/EDIT a prop value (text, color, boolean, number, etc.) of a section that is already on a page, this IS supported: call `list_page_sections(page_id)` to get the placement `elementId` and the prop names/ids, then `update_section_prop(page_id, element_id, prop_name|prop_id, value)`. Do not assume prop editing is unavailable.\n\n" +
+        "TWO DISTINCT JOBS — do not confuse them, and do not jump to writing code for the second one:\n" +
+        "(A) DEFINING props / authoring a component = changing which props a component HAS. This edits the component source/config (types.ts via `ikas-component config add-prop`/`add-component`, JSX in index.tsx, etc.) and requires a rebuild. Use this ONLY when the needed prop does not exist yet, or the user explicitly asks to build/modify the component's code or prop schema.\n" +
+        "(B) SETTING prop VALUES / filling content = giving values to props that ALREADY exist on a section placed on a page. This is pure data entry via `list_page_sections` + `update_section_prop` (and `upload_image` for images). It writes NO code and needs NO rebuild.\n" +
+        "When the user says things like 'fill this section', 'set the heading/title/text/image/link', 'populate', 'change the content/value', or 'enter this data', that is JOB (B): use `update_section_prop`. First call `list_page_sections` and check the existing `props` — if the prop is already there (it usually is), just set its value. Only fall back to JOB (A) if the required prop genuinely does not exist in that section's `props`. Writing a new component or adding a prop to fill in a value the section already supports is the wrong move.\n\n" +
+        "COMMON (GLOBAL) SECTIONS — HEADER & FOOTER: these render on EVERY page 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 }) => {
@@ -1697,13 +1940,20 @@ server.tool("search_docs", "Search across all ikas storefront API docs, framewor
         parts.push("");
         parts.push("Use `get_migration_guide(topic)` to get full content for any migration topic.");
     }
-    if (functions.length === 0 && topics.length === 0 && types.length === 0 && migrationTopics.length === 0) {
+    if (functions.length === 0 &&
+        topics.length === 0 &&
+        types.length === 0 &&
+        migrationTopics.length === 0) {
         parts.push(`No results found for "${query}". Try different keywords or use \`list_functions()\` to see all available functions.`);
     }
     return { content: [{ type: "text", text: parts.join("\n") }] };
 });
 // Tool: get_function_doc
-server.tool("get_function_doc", "Get full documentation for a specific storefront API function including signature, parameters, return type, and example.", { name: z.string().describe("Function name (e.g. 'addItemToCart', 'Router.navigate')") }, async ({ name }) => {
+server.tool("get_function_doc", "Get full documentation for a specific storefront API function including signature, parameters, return type, and example.", {
+    name: z
+        .string()
+        .describe("Function name (e.g. 'addItemToCart', 'Router.navigate')"),
+}, async ({ name }) => {
     const nameLower = name.toLowerCase();
     // Phase 1: canonical-name match wins. A real function name always outranks
     // any displayName alias so aliases can never shadow the function they're
@@ -1711,7 +1961,9 @@ server.tool("get_function_doc", "Get full documentation for a specific storefron
     // [BP-DISPLAY-NAME: hasCustomer] alias).
     const byName = storefrontData.functions.find((f) => f.name.toLowerCase() === nameLower);
     if (byName) {
-        return { content: [{ type: "text", text: formatFunctionDoc(byName) }] };
+        return {
+            content: [{ type: "text", text: formatFunctionDoc(byName) }],
+        };
     }
     // Phase 2: fall back to displayName aliases.
     const byAlias = storefrontData.functions.filter((f) => f.displayName && f.displayName.toLowerCase() === nameLower);
@@ -1719,7 +1971,9 @@ server.tool("get_function_doc", "Get full documentation for a specific storefron
         const fn = byAlias[0];
         const note = `> Note: "${name}" is a display alias for \`${fn.name}\`.\n\n`;
         return {
-            content: [{ type: "text", text: note + formatFunctionDoc(fn) }],
+            content: [
+                { type: "text", text: note + formatFunctionDoc(fn) },
+            ],
         };
     }
     if (byAlias.length > 1) {
@@ -1737,7 +1991,9 @@ server.tool("get_function_doc", "Get full documentation for a specific storefron
         (f.displayName && f.displayName.toLowerCase().includes(nameLower)));
     if (matches.length > 0) {
         const suggestions = matches.slice(0, 5).map((f) => {
-            const alias = f.displayName && f.displayName !== f.name ? ` (alias: ${f.displayName})` : "";
+            const alias = f.displayName && f.displayName !== f.name
+                ? ` (alias: ${f.displayName})`
+                : "";
             return `  - ${f.name}${alias}`;
         });
         return {
@@ -1750,7 +2006,12 @@ server.tool("get_function_doc", "Get full documentation for a specific storefron
         };
     }
     return {
-        content: [{ type: "text", text: `Function "${name}" not found. Use \`list_functions()\` to see all available functions.` }],
+        content: [
+            {
+                type: "text",
+                text: `Function "${name}" not found. Use \`list_functions()\` to see all available functions.`,
+            },
+        ],
     };
 });
 // Tool: list_functions
@@ -1800,7 +2061,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();
@@ -1832,7 +2093,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);
@@ -1852,7 +2117,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: [
                 {
@@ -1875,20 +2142,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("");
@@ -1896,63 +2173,88 @@ server.tool("get_code_example", "Get an API usage reference for a specific task.
     return { content: [{ type: "text", text: parts.join("\n") }] };
 });
 // Tool: get_framework_guide
-server.tool("get_framework_guide", "Get a framework guide on a specific topic (e.g. 'ai-workflow', 'common-pitfalls', 'prop-types', 'css-scoping', 'form-handling'). Call `list_topics()` to see all available topic keys.", { topic: z.string().describe("Topic key or keyword (call `list_topics()` for the full list)") }, async ({ topic }) => {
+server.tool("get_framework_guide", "Get a framework guide on a specific topic (e.g. 'ai-workflow', 'common-pitfalls', 'prop-types', 'css-scoping', 'form-handling'). Call `list_topics()` to see all available topic keys.", {
+    topic: z
+        .string()
+        .describe("Topic key or keyword (call `list_topics()` for the full list)"),
+}, async ({ topic }) => {
     const topicLower = topic.toLowerCase().replace(/\s+/g, "-");
     // Alias mapping for common alternative topic names
     const topicAliases = {
         "form-handling": "form-patterns",
-        "forms": "form-patterns",
+        forms: "form-patterns",
         "data-fetching": "async-data-patterns",
-        "async": "async-data-patterns",
-        "loading": "async-data-patterns",
+        async: "async-data-patterns",
+        loading: "async-data-patterns",
         "sub-components": "sub-component-patterns",
-        "subcomponents": "sub-component-patterns",
-        "routing": "navigation-patterns",
-        "router": "navigation-patterns",
-        "observer": "component-structure",
-        "reactivity": "component-structure",
-        "pitfalls": "common-pitfalls",
-        "gotchas": "common-pitfalls",
-        "mistakes": "common-pitfalls",
-        "header": "header-footer-patterns",
-        "footer": "header-footer-patterns",
-        "blog": "blog-patterns",
-        "cart": "cart-patterns",
-        "account": "account-patterns",
+        subcomponents: "sub-component-patterns",
+        routing: "navigation-patterns",
+        router: "navigation-patterns",
+        observer: "component-structure",
+        reactivity: "component-structure",
+        pitfalls: "common-pitfalls",
+        gotchas: "common-pitfalls",
+        mistakes: "common-pitfalls",
+        header: "header-footer-patterns",
+        footer: "header-footer-patterns",
+        blog: "blog-patterns",
+        cart: "cart-patterns",
+        account: "account-patterns",
         "product-detail": "product-detail-patterns",
         "product-list": "product-list-patterns",
-        "filtering": "product-list-patterns",
-        "reviews": "review-patterns",
-        "slider": "slider-overlay-patterns",
-        "overlay": "slider-overlay-patterns",
-        "modal": "slider-overlay-patterns",
-        "architecture": "real-world-architecture",
-        "theme": "real-world-architecture",
+        filtering: "product-list-patterns",
+        reviews: "review-patterns",
+        slider: "slider-overlay-patterns",
+        overlay: "slider-overlay-patterns",
+        modal: "slider-overlay-patterns",
+        architecture: "real-world-architecture",
+        theme: "real-world-architecture",
         "global-styles": "global-css",
-        "global": "global-css",
+        global: "global-css",
         "css-variables": "global-css",
         "custom-properties": "global-css",
     };
     const resolvedTopic = topicAliases[topicLower] || topicLower;
     // Topics that involve MobX store reads get a reminder about root reactivity
     const storeTopics = new Set([
-        "product-detail-patterns", "product-list-patterns", "cart-patterns",
-        "account-patterns", "header-footer-patterns", "review-patterns",
-        "blog-patterns", "form-handling", "async-data-patterns",
-        "component-structure", "imports",
+        "product-detail-patterns",
+        "product-list-patterns",
+        "cart-patterns",
+        "account-patterns",
+        "header-footer-patterns",
+        "review-patterns",
+        "blog-patterns",
+        "form-handling",
+        "async-data-patterns",
+        "component-structure",
+        "imports",
     ]);
     const observerReminder = "> **IMPORTANT: Do NOT use `observer()` on root component exports.** The ikas runtime wraps root renders in MobX `autorun()`, making them automatically reactive. All store reads (`cartStore`, `customerStore`, etc.) in root components are tracked automatically. Only use `observer()` on extracted sub-components.\n\n";
     // Try exact key match (with alias resolution)
     if (frameworkData.topics[resolvedTopic]) {
         const t = frameworkData.topics[resolvedTopic];
         const prefix = storeTopics.has(resolvedTopic) ? observerReminder : "";
-        return { content: [{ type: "text", text: `## ${t.title}\n\n${prefix}${t.content}` }] };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `## ${t.title}\n\n${prefix}${t.content}`,
+                },
+            ],
+        };
     }
     // Try original topic key (without alias) in case it's a direct key
     if (resolvedTopic !== topicLower && frameworkData.topics[topicLower]) {
         const t = frameworkData.topics[topicLower];
         const prefix = storeTopics.has(topicLower) ? observerReminder : "";
-        return { content: [{ type: "text", text: `## ${t.title}\n\n${prefix}${t.content}` }] };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `## ${t.title}\n\n${prefix}${t.content}`,
+                },
+            ],
+        };
     }
     // Try keyword search
     const matches = searchFrameworkTopics(topic);
@@ -1960,7 +2262,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)
@@ -1976,16 +2283,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));
@@ -2001,14 +2319,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();
@@ -2028,7 +2360,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) {
@@ -2059,7 +2396,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"])
@@ -2070,12 +2410,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();
@@ -2097,7 +2447,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`];
@@ -2205,13 +2560,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`];
@@ -2275,7 +2640,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();
@@ -2314,15 +2679,25 @@ server.tool("list_types", "List storefront types and enums. Use `domain` and/or
     return { content: [{ type: "text", text: parts.join("\n") }] };
 });
 // Tool: get_prop_types
-server.tool("get_prop_types", "Get all available ikas.config.json prop types with descriptions, TypeScript types, and examples. Tip: Use `npx ikas-component config add-component --props '[...]'` to create a component with all props in one command, or `add-prop` to add props incrementally. NEVER manually edit types.ts — it is auto-generated by the CLI.", {}, async () => {
+server.tool("get_prop_types", 'Get all available ikas.config.json prop types with descriptions, TypeScript types, and examples. NOTE: these are the TypeScript prop-definition types for authoring a component — they are NOT the runtime JSON value shapes you write via `update_section_prop` (e.g. a TEXT prop is typed `string` here but written as `{ "value": "..." }`, and an IMAGE is `IkasImage | null` here but written as `{ "id": "..." }`). For the value shapes to pass to `update_section_prop`, see that tool\'s description. Tip: Use `npx ikas-component config add-component --props \'[...]\'` to create a component with all props in one command, or `add-prop` to add props incrementally. NEVER manually edit types.ts — it is auto-generated by the CLI.', {}, async () => {
     const propTypesTopic = frameworkData.topics["prop-types"];
     if (propTypesTopic) {
         return {
-            content: [{ type: "text", text: `## ${propTypesTopic.title}\n\n${propTypesTopic.content}` }],
+            content: [
+                {
+                    type: "text",
+                    text: `## ${propTypesTopic.title}\n\n${propTypesTopic.content}`,
+                },
+            ],
         };
     }
     return {
-        content: [{ type: "text", text: "Prop types documentation not available." }],
+        content: [
+            {
+                type: "text",
+                text: "Prop types documentation not available.",
+            },
+        ],
     };
 });
 // Tool: get_section_template
@@ -2419,7 +2794,8 @@ server.tool("get_section_template", "Get the root files of a starter section tem
     // the end of the response in the existing recipe-builder block.
     {
         const snippetStrForBanner = bundle.rootFiles["ikas-config-snippet.json"];
-        if (snippetStrForBanner && /<id-of-[A-Za-z0-9_]+>/.test(snippetStrForBanner)) {
+        if (snippetStrForBanner &&
+            /<id-of-[A-Za-z0-9_]+>/.test(snippetStrForBanner)) {
             const childMatches = Array.from(snippetStrForBanner.matchAll(/<id-of-([A-Za-z0-9_]+)>/g));
             const uniqueChildren = Array.from(new Set(childMatches.map((m) => m[1])));
             parts.push(`> 🔧 **CONTAINER SECTION — required wiring.** This template hosts ${uniqueChildren.length} child component${uniqueChildren.length === 1 ? "" : "s"} (${uniqueChildren.map((n) => `\`${n}\``).join(", ")}) via a \`COMPONENT_LIST\` slot. Creating the parent alone produces an empty, unusable section. **You MUST follow the full Setup Recipe below**: create each child → capture its \`componentId\` → wire them into the parent's \`filteredComponentIds\` with \`config update-prop\`. Component ids are opaque random strings (e.g. \`7ojrigep-Eml9n5sN3i\`) — they cannot be derived from names, and the CLI rejects unknown ids.`, "");
@@ -2543,7 +2919,10 @@ server.tool("get_section_template", "Get the root files of a starter section tem
                     try {
                         const childSnippet = JSON.parse(fs.readFileSync(childSnippetPath, "utf-8"));
                         const childProps = (childSnippet.props || []).map((p) => {
-                            const out = { name: p.name, type: p.type };
+                            const out = {
+                                name: p.name,
+                                type: p.type,
+                            };
                             if (p.displayName)
                                 out.displayName = p.displayName;
                             if (p.required)
@@ -2616,10 +2995,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()
@@ -2782,7 +3158,11 @@ server.tool("list_section_types", "List all available `get_section_template` sec
 });
 // --- Migration tools ---
 // Tool: analyze_old_theme
-server.tool("analyze_old_theme", "Analyze an old ikas storefront theme.json and produce a structured migration report. Shows all components, custom data definitions, prop type breakdown, and migration recommendations. Use this as the first step when converting an old theme.", { theme_json: z.string().describe("The raw JSON content of the old theme.json file") }, async ({ theme_json }) => {
+server.tool("analyze_old_theme", "Analyze an old ikas storefront theme.json and produce a structured migration report. Shows all components, custom data definitions, prop type breakdown, and migration recommendations. Use this as the first step when converting an old theme.", {
+    theme_json: z
+        .string()
+        .describe("The raw JSON content of the old theme.json file"),
+}, async ({ theme_json }) => {
     try {
         const parsed = JSON.parse(theme_json);
         const analysis = analyzeOldTheme(parsed);
@@ -2790,102 +3170,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. **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 }) => {
+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);
@@ -2895,19 +3335,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"
@@ -2926,13 +3373,31 @@ server.tool("get_migration_example", `Get a concrete before/after migration exam
 });
 // Tool: plan_migration
 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 }) => {
+    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 = resolveThemeJson(theme_json, theme_json_path);
         const projectName = project_name || "my-theme";
@@ -2993,18 +3458,37 @@ server.tool("plan_migration", "Generate the **initial** migration plan and (when
     }
     catch (err) {
         return {
-            content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }],
+            content: [
+                {
+                    type: "text",
+                    text: `Error: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
         };
     }
 });
 // Tool: get_section_migration_plan
 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 }) => {
+    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 = resolveThemeJson(theme_json, theme_json_path);
         const projectName = project_name || "my-theme";
@@ -3013,7 +3497,12 @@ server.tool("get_section_migration_plan", "Returns concrete CLI commands and pro
     }
     catch (err) {
         return {
-            content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }],
+            content: [
+                {
+                    type: "text",
+                    text: `Error: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
         };
     }
 });
@@ -3043,13 +3532,22 @@ function resolveIkasComponentBinary(projectRoot) {
 async function runIkasComponentCli(projectRoot, args) {
     const bin = resolveIkasComponentBinary(projectRoot);
     return new Promise((resolve) => {
-        execFile(bin, args, { cwd: projectRoot, windowsHide: true }, (err, stdout, stderr) => {
+        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 });
+            resolve({
+                stdout: stdout?.toString() ?? "",
+                stderr: stderr?.toString() ?? "",
+                exitCode,
+            });
         });
     });
 }
@@ -3057,24 +3555,47 @@ function parseCliJson(stdout) {
     const trimmed = stdout.trim();
     if (!trimmed)
         return null;
-    // CLI prints exactly one JSON object on stdout; if multiple lines appeared
-    // (e.g., warnings on stderr leaked), take the last non-empty line.
-    const last = trimmed.split("\n").map(l => l.trim()).filter(Boolean).pop();
-    if (!last)
-        return null;
+    // Fast path: the CLI prints exactly one JSON object on stdout.
     try {
-        return JSON.parse(last);
+        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 ?? []);
+}
 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: JSON.stringify(parsed, null, 2) },
+                ],
+            };
         }
         return {
             content: [
@@ -3097,38 +3618,77 @@ async function callEditorAction(projectRoot, args) {
         };
     }
 }
+//
 // Tool: list_editor_pages
 server.tool("list_editor_pages", "List pages in the connected editor's project. Returns id, name, pageType, slug for each page. Requires `ikas-component dev` to be running with the editor connected. Use the returned `id`s as the `pageId` argument to `add_section_to_page`.", {
-    project_root: z.string().describe("Absolute path to the code-component project (where `node_modules/.bin/ikas-component` lives)."),
-    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+    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)] : [])];
+    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)."),
+    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)] : [])];
+    const args = [
+        "import",
+        "--id",
+        component_id,
+        ...(port ? ["--port", String(port)] : []),
+    ];
     return callEditorAction(project_root, args);
 });
 // Tool: add_section_to_page
-server.tool("add_section_to_page", "Place an already-imported section-type code component on a page in the editor. Equivalent to right-clicking the section in the dev-components panel and choosing \"Add to Page\". Errors if the component is not imported, is not section-type, or the page id is unknown. Use `list_editor_pages` to discover page ids and `list_imported_sections` to discover component ids.", {
-    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)."),
+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)."),
+    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",
@@ -3141,6 +3701,1139 @@ server.tool("add_section_to_page", "Place an already-imported section-type code
     ];
     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.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    page_id: z.string().describe("Target page id (from `list_editor_pages`)."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, page_id, port }) => {
+    const args = [
+        "list-page-sections",
+        "--page-id",
+        page_id,
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: get_component_props
+server.tool("get_component_props", "Get prop blueprints straight from the editor (the source of truth) for one or MANY components in a single call — for any section OR child code component ids. Returns `{ components: [...] }`, each prop carrying its `id`, `name`, `type`, `required`, `default`, and crucially: a ready-to-use `writeExample` (the EXACT value shape to pass to update_section_prop / update_page_sections — e.g. PRODUCT_LIST, BLOG_LIST, COMPONENT_LIST, LINK) plus a `writeNote` for variants, so you do NOT have to guess or trial-write the JSON; for ENUM props the `options` (valid `value`s); and for COMPONENT/COMPONENT_LIST props the `allowedComponentIds` (which children the slot permits — when empty, an `allowedComponentsNote` says any imported code component is allowed). Use this (its `writeExample`/`options`/`allowedComponentIds`) instead of guessing or reading ikas.config.json. Pass ALL the section/child ids you need at once (batch). Child component ids come from a parent prop's `allowedComponentIds` (or get_section_template).", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    component_ids: z
+        .array(z.string())
+        .describe("Section/child code-component ids to resolve (batch). From list_imported_sections or a COMPONENT_LIST prop's allowedComponentIds."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, component_ids, port }) => {
+    const args = [
+        "get-component-props",
+        "--component-ids",
+        (component_ids || []).join(","),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: get_section_values
+server.tool("get_section_values", "Get the CURRENT prop values of one or MANY placed sections (each with its full `propValues` plus blueprint `props` — every prop carrying a `writeExample`/`writeNote` for the exact value shape, plus ENUM `options` and COMPONENT_LIST `allowedComponentIds`). `list_page_sections` is lean and omits values to avoid truncation; use this to read sections' values — needed for read-modify-write of a COMPONENT_LIST, or to inspect the exact stored shape of an existing value. Returns `{ sections: [...] }`. Pass all the elementIds you need at once (batch). 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 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, …). 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 settings; pick a global whose type matches the prop. (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-component dev` running with the editor connected.', {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    page_type: z
+        .string()
+        .describe("Page type to create, e.g. CATEGORY, PRODUCT, BRAND, BLOG, BLOG_CATEGORY, INDEX, CUSTOM."),
+    name: z
+        .string()
+        .optional()
+        .describe("Page name. Required for CUSTOM pages; ignored otherwise."),
+    slug: z
+        .string()
+        .optional()
+        .describe("Page slug. Required (and unique) for CUSTOM pages; ignored otherwise."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, page_type, name, slug, port }) => {
+    const args = [
+        "create-page",
+        "--page-type",
+        page_type,
+        ...(name ? ["--name", name] : []),
+        ...(slug ? ["--slug", slug] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: publish_theme
+server.tool("publish_theme", "Publish the current theme LIVE — the same action as the editor's Publish button (uploads the whole project to the storefront). This is REAL and customer-facing: the published site changes. SAFETY: it publishes nothing unless `confirm: true` is passed; if you omit it you get a dry-run with the `previewUrl` and a warning describing the impact. The MAIN/production theme additionally requires `confirm_production: true` (its URL is the live customer-facing domain). Use this when the user explicitly asks to publish/go live — do NOT publish on your own initiative. On success returns `{ published: true, previewUrl, isMainTheme }`; open `previewUrl` to review the result. Requires `ikas-component dev` running with the editor connected.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    confirm: z
+        .boolean()
+        .optional()
+        .describe("Set true to actually publish. Omitted/false = dry-run (returns previewUrl + warning, publishes nothing)."),
+    confirm_production: z
+        .boolean()
+        .optional()
+        .describe("Required IN ADDITION to confirm when the target is the MAIN/production theme (live customer-facing site)."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, confirm, confirm_production, port }) => {
+    const args = [
+        "publish-theme",
+        ...(confirm ? ["--confirm"] : []),
+        ...(confirm_production ? ["--confirm-production"] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: get_editor_workflow
+const EDITOR_WORKFLOW_GUIDE = [
+    "# Editor workflow: placing sections and filling their content on a page",
+    "",
+    "Use this when the user wants to add a section to a page and/or fill in its content (heading, text, image, link, slides, etc.) in the live editor. These are LIVE-EDITOR actions and require `ikas-component dev` running with the editor connected; image upload additionally requires the editor to be embedded in the ikas admin panel (the admin panel performs the upload — a standalone editor cannot upload).",
+    "",
+    "## Two distinct jobs — do not confuse them",
+    "- (A) DEFINE props / author component code — changing WHICH props a component has. Edits component source/config (config add-prop/add-component, index.tsx) and needs a rebuild. Do this ONLY when a needed prop does not exist yet, or the user explicitly asks to build/modify the component.",
+    "- (B) SET prop VALUES / fill content — giving values to props that ALREADY exist on a placed section. Pure data entry via list_page_sections + update_section_prop (+ upload_image). No code, no rebuild.",
+    "When the user says 'fill this section', 'set the title/text/image/link', 'populate', 'change the content' → that is JOB (B). Do NOT write a component or add a prop to fill a value the section already supports.",
+    "",
+    "## Step-by-step (JOB B — fill content)",
+    "1. list_editor_pages → choose the target page_id.",
+    "2. list_page_sections(page_id) → for each placed section: its per-placement elementId, blueprint props (id, name, type), and setPropNames (which props already have a value). It is LEAN — no prop VALUES, so it never truncates. To read a section's current values (e.g. to read-modify-write a COMPONENT_LIST), call get_section_values(page_id, element_id). 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 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.",
+    "",
+    "## 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-component 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.", {
+    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); 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" }. 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-component dev` running with the editor connected.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    kind: z
+        .enum([
+        "globalVariable",
+        "color",
+        "typography",
+        "breakpoint",
+        "keyframe",
+        "colorScheme",
+    ])
+        .describe("What to create."),
+    name: z.string().optional().describe("Name (design tokens)."),
+    display_name: z
+        .string()
+        .optional()
+        .describe("Human label (globalVariable)."),
+    type: z.string().optional().describe("globalVariable value type."),
+    value: z
+        .any()
+        .optional()
+        .describe("globalVariable default value (shape depends on type — see tool description), or color hex string."),
+    ...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)]
+                    : []),
+                ...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. 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)."),
+    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 — see create_theme_global). An invented IMAGE id renders as a broken image.'),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, name, display_name, type, value, port }) => {
+    const args = [
+        "update-global-variable",
+        "--name",
+        name,
+        ...(display_name !== undefined ? ["--display-name", display_name] : []),
+        ...(type !== undefined ? ["--type", type] : []),
+        ...(value !== undefined ? ["--value", JSON.stringify(value)] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: 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-component 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-component 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-component 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-component 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-component 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() {
     const transport = new StdioServerTransport();