@ikas/code-components-mcp 1.4.0-beta.23 → 1.4.0-beta.231

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,20 +1589,53 @@ 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)) {
         score += 10;
     }
-    // Word matches
+    // Word matches. Squashing the (potentially guide-sized) text is the expensive half of the
+    // identifier check — compute it lazily, once per call, not once per query word.
+    let squashedText = null;
     for (const word of words) {
-        if (lower.includes(word)) {
+        const wordLower = word.toLowerCase();
+        if (lower.includes(wordLower)) {
             score += 3;
         }
+        else if (isIdentifierLike(word)) {
+            // Same identifier, different convention (PRODUCT_ATTRIBUTE ↔ IkasProductAttributeDetail
+            // ↔ "product attribute"). Scored below an exact word hit so literal matches still win.
+            const squashed = squashIdentifier(word);
+            if (squashed) {
+                if (squashedText === null)
+                    squashedText = squashIdentifier(text);
+                if (squashedText.includes(squashed)) {
+                    score += 2;
+                }
+            }
+        }
     }
     // Name exact match bonus
     if (lower === queryLower) {
@@ -1474,8 +1663,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];
@@ -1502,21 +1690,100 @@ function suggestClosestNames(input, candidates, opts) {
         .sort((a, b) => a.d - b.d);
     return edits.slice(0, max).map((s) => s.name);
 }
+/**
+ * Formatted ` — matching sections: ...` suffix naming the guide sections that match the query,
+ * so a hit buried mid-guide (e.g. "Quantity Limits" inside cart-patterns) is visible without
+ * opening the full guide. Section bodies are scored on purpose: a query for an identifier that
+ * appears only inside a section (an error code, a prop name) must still surface that section's
+ * heading. Returns "" when the query matches most of the guide's sections — matchScore is
+ * presence-based, so a broad query ("cart" against cart-patterns) ties every section and a
+ * top-3 would just echo document order, hinting nothing.
+ */
+// Topic content is loaded once at startup and never mutates, so the section parse is
+// memoized on the content string — a query only pays for scoring.
+const parsedSectionsCache = new Map();
+function parseSections(content) {
+    const cached = parsedSectionsCache.get(content);
+    if (cached)
+        return cached;
+    // Line walk instead of a heading-regex split: a `## ` line inside a fenced code block must
+    // not become a pseudo-section (it would surface a heading that doesn't exist in the guide
+    // and swallow the rest of the real section's body).
+    const sections = [];
+    let fenceOpen = false;
+    for (const line of content.split("\n")) {
+        if (/^\s*```/.test(line))
+            fenceOpen = !fenceOpen;
+        const headingMatch = fenceOpen ? null : line.match(/^#{2,4} (.+)/);
+        if (headingMatch)
+            sections.push({ heading: headingMatch[1].trim(), body: "" });
+        else if (sections.length > 0)
+            sections[sections.length - 1].body += line + "\n";
+    }
+    parsedSectionsCache.set(content, sections);
+    return sections;
+}
+function sectionHint(content, query, topicTitle) {
+    const sections = parseSections(content);
+    const scored = [];
+    for (const { heading, body } of sections) {
+        // Heading hits weigh double. The floor of 3 drops sections whose only signal is a single
+        // squashed-identifier body match (worth 2) — a literal word hit (3) or any heading match
+        // clears it.
+        const score = matchScore(heading, query) * 2 + matchScore(body, query);
+        if (score >= 3)
+            scored.push({ heading, score });
+    }
+    if (scored.length === 0)
+        return "";
+    scored.sort((a, b) => b.score - a.score);
+    // The tie-guard below must only fire when the field is genuinely flat. A single common
+    // query word ("cart") pushes every section past the floor, so counting raw matches would
+    // also suppress steep fields where one section clearly won. Sections below 60% of the top
+    // score are noise from such a word, not real matches — drop them before counting.
+    const strong = scored.filter((s) => s.score >= scored[0].score * 0.6);
+    if (strong.length > sections.length / 2)
+        return "";
+    // The guide's own title is usually its first `##` line, so it registers as a section.
+    // Its heading is the exact text the result line already prints — listing it would burn
+    // one of the three slots on a pure echo. Keep it in scoring (its body can be a genuine
+    // hit and it counts toward the tie-guard), drop it from the output only. Headings are
+    // already trimmed at parse time; trim the title too so stray whitespace in the JSON
+    // cannot silently re-admit the echo.
+    const title = topicTitle.trim();
+    const named = strong.filter((s) => s.heading !== title);
+    if (named.length === 0)
+        return "";
+    const top = named.slice(0, 3);
+    return ` — matching sections: ${top.map((s) => `"${s.heading}"`).join(", ")}`;
+}
 function searchFunctions(query) {
     const scored = storefrontData.functions
         .map((fn) => {
         const nameScore = matchScore(fn.name, query) * 3;
-        const displayNameScore = fn.displayName ? matchScore(fn.displayName, query) * 3 : 0;
+        const 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 +1797,11 @@ function searchFrameworkTopics(query) {
         const descScore = matchScore(topic.description, query) * 2;
         const contentScore = matchScore(topic.content, query);
         const tagScore = topic.tags.some((t) => matchScore(t, query) > 0) ? 5 : 0;
-        return { key, topic, score: titleScore + descScore + contentScore + tagScore };
+        return {
+            key,
+            topic,
+            score: titleScore + descScore + contentScore + tagScore,
+        };
     })
         .filter((item) => item.score > 0)
         .sort((a, b) => b.score - a.score);
@@ -1545,14 +1816,34 @@ function searchTypes(query) {
         const propScore = td.properties?.some((p) => matchScore(p.name, query) > 0 || matchScore(p.type, query) > 0)
             ? 4
             : 0;
-        const enumScore = td.enumValues?.some((v) => matchScore(v, query) > 0) ? 4 : 0;
-        return { td, score: nameScore + domainScore + propScore + enumScore };
+        const enumScore = td.enumValues?.some((v) => matchScore(v, query) > 0)
+            ? 4
+            : 0;
+        const unionScore = td.unionValues?.some((v) => matchScore(v, query) > 0)
+            ? 4
+            : 0;
+        return {
+            td,
+            score: nameScore + domainScore + propScore + enumScore + unionScore,
+        };
     })
         .filter((item) => item.score > 0)
         .sort((a, b) => b.score - a.score);
     return scored.map((item) => item.td);
 }
 // --- Format helpers ---
+/**
+ * Wrap a code snippet in a fenced block — unless it already carries its own fence. JSDoc `@example`
+ * bodies are indexed verbatim, so every one of them arrives fenced; wrapping them again produced a
+ * double ```` ``` ```` opener, which makes the block unparseable for anything extracting code from
+ * the doc. Bare snippets still get fenced as typescript.
+ */
+function asCodeBlock(snippet) {
+    const trimmed = snippet.trim();
+    return trimmed.startsWith("```")
+        ? trimmed
+        : ["```typescript", trimmed, "```"].join("\n");
+}
 function formatFunctionDoc(fn) {
     const lines = [];
     lines.push(`## ${fn.name}`);
@@ -1579,7 +1870,7 @@ function formatFunctionDoc(fn) {
         lines.push("", `**Returns:** \`${fn.returnType}\`${fn.returns ? ` - ${fn.returns}` : ""}`);
     }
     if (fn.example) {
-        lines.push("", "**Example:**", "```typescript", fn.example, "```");
+        lines.push("", "**Example:**", asCodeBlock(fn.example));
     }
     if (fn.related.length > 0) {
         lines.push("", `**Related:** ${fn.related.map((r) => `\`${r}\``).join(", ")}`);
@@ -1587,8 +1878,12 @@ function formatFunctionDoc(fn) {
     return lines.join("\n");
 }
 function formatFunctionSummary(fn) {
-    const desc = fn.description ? fn.description.split(".")[0] + "." : "No description.";
-    const alias = fn.displayName && fn.displayName !== fn.name ? ` (alias: ${fn.displayName})` : "";
+    const desc = fn.description
+        ? fn.description.split(".")[0] + "."
+        : "No description.";
+    const alias = fn.displayName && fn.displayName !== fn.name
+        ? ` (alias: ${fn.displayName})`
+        : "";
     return `- \`${fn.name}\`${alias} - ${desc}`;
 }
 function formatTypeDefinition(td, opts = {}) {
@@ -1596,13 +1891,24 @@ function formatTypeDefinition(td, opts = {}) {
     const lines = [];
     lines.push(`## ${td.name}`);
     lines.push("", `**Kind:** ${td.kind} | **Domain:** ${td.domain}`);
-    if (td.kind === "type") {
+    if (td.description) {
+        lines.push("", td.description);
+    }
+    if (td.kind === "type" && td.unionValues) {
+        lines.push("", "```typescript");
+        lines.push(`type ${td.name} = ${td.unionValues.map((v) => `"${v}"`).join(" | ")};`);
+        lines.push("```");
+    }
+    else if (td.kind === "type") {
         lines.push("", "```typescript");
         const extendsStr = td.extends ? ` & ${td.extends.join(" & ")}` : "";
         lines.push(`type ${td.name} = {`);
         if (td.properties) {
             for (const p of td.properties) {
                 const opt = p.optional ? "?" : "";
+                if (p.description) {
+                    lines.push("  /**", ...p.description.split("\n").map((l) => `   * ${l.trim()}`), "   */");
+                }
                 lines.push(`  ${p.name}${opt}: ${p.type};`);
             }
         }
@@ -1629,7 +1935,9 @@ function formatTypeDefinition(td, opts = {}) {
             const fn = storefrontData.functions.find((f) => f.name === fnName);
             if (fn) {
                 const desc = fn.description ? fn.description.split(".")[0] + "." : "";
-                const alias = fn.displayName && fn.displayName !== fn.name ? ` (alias: ${fn.displayName})` : "";
+                const alias = fn.displayName && fn.displayName !== fn.name
+                    ? ` (alias: ${fn.displayName})`
+                    : "";
                 lines.push(`- **\`${fn.name}\`**${alias} — ${desc}`);
                 lines.push(`  \`${fn.signature}\``);
             }
@@ -1638,7 +1946,9 @@ function formatTypeDefinition(td, opts = {}) {
             }
         }
         lines.push("");
-        lines.push("Use `get_functions_for_type(\"" + td.name + "\")` for full documentation of these functions.");
+        lines.push('Use `get_functions_for_type("' +
+            td.name +
+            '")` for full documentation of these functions.');
     }
     return lines.join("\n");
 }
@@ -1647,6 +1957,10 @@ function formatTypeSummary(td) {
         const count = td.enumValues?.length ?? 0;
         return `- \`${td.name}\` (enum, ${count} values) — domain: ${td.domain}`;
     }
+    if (td.unionValues) {
+        const values = td.unionValues.map((v) => `"${v}"`).join(" | ");
+        return `- \`${td.name}\` (union: ${values}) — domain: ${td.domain}`;
+    }
     const count = td.properties?.length ?? 0;
     const ext = td.extends ? ` extends ${td.extends.join(", ")}` : "";
     return `- \`${td.name}\` (${count} properties${ext}) — domain: ${td.domain}`;
@@ -1656,7 +1970,16 @@ 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" +
+        "CONFIG FILE — HARD RULE: NEVER edit `ikas.config.json` directly (no file write, patch or search/replace). Change it ONLY through `ikas-component` commands (`ikas-component config add-component` / `add-prop` / `update-prop` / `add-enum`, …; `ikas-component config list` to inspect). `projectId` and every component `id` are generated once and are IMMUTABLE — never change them, and never copy an id returned by the editor (`list_imported_sections`, `list_page_sections`, …) into `ikas.config.json`. On a theme that INSTALLED this project as a design asset the editor reports PUBLISHED ids, whose prefix differs from this project's `projectId`; that difference is expected and is NOT drift to fix — pass the editor's id to the editor tools and leave the config untouched. A config id that does not start with the project's own `projectId` makes `ikas-component dev` / `publish` fail and can corrupt the published theme.\n\n" +
+        "Live-editor actions (require `ikas theme dev` running with the editor connected): `list_editor_pages` → page ids; `list_imported_sections` → imported component ids; `import_section` → import a built component; `add_section_to_page` → place one section (`add_sections_to_page` places MANY at once and can set their props in the same call — fastest way to build a page); `list_page_sections` → the sections placed on a page (LEAN roster: per-placement `elementId`, `componentId`, `propCount`, which props are filled — NO schema/values, so it never truncates); `move_page_section` → reorder a section already placed on a page (by `direction` up/down or an absolute `to_index`) — the only way to change section order, since the editor UI offers it solely as a drag; `get_component_props` → a component's prop blueprint (types, ENUM valid `options`, COMPONENT_LIST `allowedComponentIds`) for any section OR child id; `get_section_values` → one section's current prop values (for read-modify-write); `get_page_by_type` → a theme page id by pageType (e.g. CATEGORY), to build PAGE links to entities (`create_page` adds that page if it does not exist yet, so you never guess a slug); `update_section_prop` → change a single prop value of a placed section (`update_page_sections` fills MANY sections/props of a page in ONE call — strongly prefer it to cut round-trips when filling content); `upload_image` → upload one image (file or URL) and get an image id (`upload_images` uploads many in one call — prefer it for several); `search_products` / `list_categories` / `list_brands` / `list_blogs` / `list_blog_categories` → find real entity ids for PRODUCT/CATEGORY/BRAND/BLOG/BLOG_CATEGORY prop values; `publish_theme` → publish the theme LIVE and get back the preview URL to review (guarded — needs `confirm:true`, and `confirm_production:true` for the main theme; only call it when the user explicitly asks to publish); `list_ready_made_pages` / `update_ready_made_page_prop` / `enable_ready_made_pages` → the ikas-rendered ready-made account/membership pages (login, register, my account, orders, …) — these are NOT sections and the section tools cannot edit them; use these three to enable the groups, read their prop schemas, and customize/localize them (logo, colors, texts). When the user asks to BUILD a login/register/password/my-account/orders/addresses page, FIRST offer these ready-made pages instead of assembling one from sections — they are fully functional out of the box and customizable (logo, colors, texts); build a custom section page only if the user prefers a custom design. Offer, don't flip: `enable_ready_made_pages` creates/removes pages, so get the user's explicit OK before calling it. For the full end-to-end process (placing a section and filling its content, with per-prop value shapes and COMPONENT_LIST rules), call `get_editor_workflow` first.\n\n" +
+        "READY-MADE PAGES FIRST — HARD RULE for account/membership pages: USER-FACING NAME: name these in the USER'S OWN LANGUAGE — English: \"ikas's ready-made pages\", Turkish: \"ikas'ın hazır sayfaları\"; never mix the English term into a sentence in another language — the editor UI lists them as Membership Pages / My Account Pages; \"built-in\" is an internal term — keep it out of everything the user sees, including question/option labels. When the user asks for a login, register, forgot/recover-password, my-account, orders, order-detail, addresses, favorites or email-verification page, do NOT start coding a custom section page. STOP and ask the user FIRST whether to use ikas's ready-made version of that page (`list_ready_made_pages` shows it — fully functional out of the box, customized/localized via `update_ready_made_page_prop`, the whole group turned on with `enable_ready_made_pages`). Only build a custom section page AFTER the user explicitly chooses custom. When asking, list the ready-made option FIRST as the recommended default; the custom section option comes second. Never call `enable_ready_made_pages` without the user's OK — it creates/removes pages. Ready-made pages are born with ONLY their own ikas-rendered element: the theme's header/footer are NOT on them (the page draws its own top bar — logo, back-to-store link — and account nav). If the user wants the theme header/footer on a ready-made page, PLACE it there with add_section_to_page — sections can sit above/below that element — and suggest turning the page's own `showBrandBar` prop off to avoid double chrome.\n\n" +
+        "To CHANGE/EDIT a prop value (text, color, boolean, number, etc.) of a section that is already on a page, this IS supported: call `list_page_sections(page_id)` to get the placement `elementId` and the prop names/ids, then `update_section_prop(page_id, element_id, prop_name|prop_id, value)`. Do not assume prop editing is unavailable.\n\n" +
+        "TWO DISTINCT JOBS — do not confuse them, and do not jump to writing code for the second one:\n" +
+        "(A) DEFINING props / authoring a component = changing which props a component HAS. This edits the component source/config (types.ts via `ikas-component config add-prop`/`add-component`, JSX in index.tsx, etc.) and requires a rebuild. Use this ONLY when the needed prop does not exist yet, or the user explicitly asks to build/modify the component's code or prop schema.\n" +
+        "(B) SETTING prop VALUES / filling content = giving values to props that ALREADY exist on a section placed on a page. This is pure data entry via `list_page_sections` + `update_section_prop` (and `upload_image` for images). It writes NO code and needs NO rebuild.\n" +
+        "When the user says things like 'fill this section', 'set the heading/title/text/image/link', 'populate', 'change the content/value', or 'enter this data', that is JOB (B): use `update_section_prop`. First call `list_page_sections` and check the existing `props` — if the prop is already there (it usually is), just set its value. Only fall back to JOB (A) if the required prop genuinely does not exist in that section's `props`. Writing a new component or adding a prop to fill in a value the section already supports is the wrong move.\n\n" +
+        "COMMON (GLOBAL) SECTIONS — HEADER & FOOTER: these render on every page that CARRIES A PLACEMENT of them — pages created in the editor are seeded with one, EXCEPT ikas ready-made (built-in) account/membership pages, which are born WITHOUT the theme header/footer (see the ready-made rule above) — and their prop values are shared theme-wide, stored in ONE record on the INDEX (Home) page's placement. Reads and writes from any page are resolved to that record, and every response about such a section carries a `common` block (`isCommon`, `commonSectionType`, `canonicalPageId`, `canonicalElementId`, `valuesArePageSpecific: false`). Consequences: changing a header/footer prop from, say, a product-detail page changes it on ALL pages; and since the header/footer normally already holds the merchant's content, you must `get_section_values` first and change only what the user asked — never treat a prop as empty and never blind-fill 'missing' props, or you overwrite live content everywhere. If the INDEX page has no placement of the section there is no record at all: reads report nothing and writes fail until you add it to the INDEX page.",
 });
 // Tool: search_docs
 server.tool("search_docs", "Search across all ikas storefront API docs, framework guides, and migration guides. Returns matching functions, framework topics, and migration topics ranked by relevance.", { query: z.string().describe("Search keyword or phrase") }, async ({ query }) => {
@@ -1676,7 +1999,7 @@ server.tool("search_docs", "Search across all ikas storefront API docs, framewor
     if (topics.length > 0) {
         parts.push("\n## Matching Framework Topics\n");
         for (const item of topics) {
-            parts.push(`- **${item.topic.title}** (key: \`${item.key}\`) - ${item.topic.description}`);
+            parts.push(`- **${item.topic.title}** (key: \`${item.key}\`) - ${item.topic.description}${sectionHint(item.topic.content, query, item.topic.title)}`);
         }
         parts.push("");
         parts.push("Use `get_framework_guide(topic)` to get full content for any topic.");
@@ -1692,18 +2015,25 @@ server.tool("search_docs", "Search across all ikas storefront API docs, framewor
     if (migrationTopics.length > 0) {
         parts.push("\n## Matching Migration Topics\n");
         for (const item of migrationTopics) {
-            parts.push(`- [migration] **${item.topic.title}** (key: \`${item.key}\`) - ${item.topic.description}`);
+            parts.push(`- [migration] **${item.topic.title}** (key: \`${item.key}\`) - ${item.topic.description}${sectionHint(item.topic.content, query, item.topic.title)}`);
         }
         parts.push("");
         parts.push("Use `get_migration_guide(topic)` to get full content for any migration topic.");
     }
-    if (functions.length === 0 && topics.length === 0 && types.length === 0 && migrationTopics.length === 0) {
+    if (functions.length === 0 &&
+        topics.length === 0 &&
+        types.length === 0 &&
+        migrationTopics.length === 0) {
         parts.push(`No results found for "${query}". Try different keywords or use \`list_functions()\` to see all available functions.`);
     }
     return { content: [{ type: "text", text: parts.join("\n") }] };
 });
 // Tool: get_function_doc
-server.tool("get_function_doc", "Get full documentation for a specific storefront API function including signature, parameters, return type, and example.", { name: z.string().describe("Function name (e.g. 'addItemToCart', 'Router.navigate')") }, async ({ name }) => {
+server.tool("get_function_doc", "Get full documentation for a specific storefront API function including signature, parameters, return type, and example.", {
+    name: z
+        .string()
+        .describe("Function name (e.g. 'addItemToCart', 'Router.navigate')"),
+}, async ({ name }) => {
     const nameLower = name.toLowerCase();
     // 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 +2041,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 +2051,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 +2071,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 +2086,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 +2141,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 +2173,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 +2197,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 +2222,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 +2253,95 @@ server.tool("get_code_example", "Get an API usage reference for a specific task.
     return { content: [{ type: "text", text: parts.join("\n") }] };
 });
 // Tool: get_framework_guide
-server.tool("get_framework_guide", "Get a framework guide on a specific topic (e.g. 'ai-workflow', 'common-pitfalls', 'prop-types', 'css-scoping', 'form-handling'). Call `list_topics()` to see all available topic keys.", { topic: z.string().describe("Topic key or keyword (call `list_topics()` for the full list)") }, async ({ topic }) => {
+server.tool("get_framework_guide", "Get a framework guide on a specific topic (e.g. 'ai-workflow', 'common-pitfalls', 'prop-types', 'css-scoping', 'form-handling'). Call `list_topics()` to see all available topic keys.", {
+    topic: z
+        .string()
+        .describe("Topic key or keyword (call `list_topics()` for the full list)"),
+}, async ({ topic }) => {
     const topicLower = topic.toLowerCase().replace(/\s+/g, "-");
     // Alias mapping for common alternative topic names
     const topicAliases = {
         "form-handling": "form-patterns",
-        "forms": "form-patterns",
+        forms: "form-patterns",
         "data-fetching": "async-data-patterns",
-        "async": "async-data-patterns",
-        "loading": "async-data-patterns",
+        async: "async-data-patterns",
+        loading: "async-data-patterns",
         "sub-components": "sub-component-patterns",
-        "subcomponents": "sub-component-patterns",
-        "routing": "navigation-patterns",
-        "router": "navigation-patterns",
-        "observer": "component-structure",
-        "reactivity": "component-structure",
-        "pitfalls": "common-pitfalls",
-        "gotchas": "common-pitfalls",
-        "mistakes": "common-pitfalls",
-        "header": "header-footer-patterns",
-        "footer": "header-footer-patterns",
-        "blog": "blog-patterns",
-        "cart": "cart-patterns",
-        "account": "account-patterns",
+        subcomponents: "sub-component-patterns",
+        routing: "navigation-patterns",
+        router: "navigation-patterns",
+        observer: "component-structure",
+        reactivity: "component-structure",
+        pitfalls: "common-pitfalls",
+        gotchas: "common-pitfalls",
+        mistakes: "common-pitfalls",
+        header: "header-footer-patterns",
+        footer: "header-footer-patterns",
+        blog: "blog-patterns",
+        cart: "cart-patterns",
+        account: "account-patterns",
         "product-detail": "product-detail-patterns",
         "product-list": "product-list-patterns",
-        "filtering": "product-list-patterns",
-        "reviews": "review-patterns",
-        "slider": "slider-overlay-patterns",
-        "overlay": "slider-overlay-patterns",
-        "modal": "slider-overlay-patterns",
-        "architecture": "real-world-architecture",
-        "theme": "real-world-architecture",
+        filtering: "product-list-patterns",
+        reviews: "review-patterns",
+        slider: "slider-overlay-patterns",
+        overlay: "slider-overlay-patterns",
+        modal: "slider-overlay-patterns",
+        architecture: "real-world-architecture",
+        theme: "real-world-architecture",
         "global-styles": "global-css",
-        "global": "global-css",
+        global: "global-css",
         "css-variables": "global-css",
         "custom-properties": "global-css",
+        conditional: "conditional-visibility",
+        "conditional-props": "conditional-visibility",
+        visibility: "conditional-visibility",
+        requiredprop: "conditional-visibility",
+        "required-prop": "conditional-visibility",
+        "dependent-props": "conditional-visibility",
+        "show-hide": "conditional-visibility",
     };
     const resolvedTopic = topicAliases[topicLower] || topicLower;
     // Topics that involve MobX store reads get a reminder about root reactivity
     const storeTopics = new Set([
-        "product-detail-patterns", "product-list-patterns", "cart-patterns",
-        "account-patterns", "header-footer-patterns", "review-patterns",
-        "blog-patterns", "form-handling", "async-data-patterns",
-        "component-structure", "imports",
+        "product-detail-patterns",
+        "product-list-patterns",
+        "cart-patterns",
+        "account-patterns",
+        "header-footer-patterns",
+        "review-patterns",
+        "blog-patterns",
+        "form-handling",
+        "async-data-patterns",
+        "component-structure",
+        "imports",
     ]);
     const observerReminder = "> **IMPORTANT: Do NOT use `observer()` on root component exports.** The ikas runtime wraps root renders in MobX `autorun()`, making them automatically reactive. All store reads (`cartStore`, `customerStore`, etc.) in root components are tracked automatically. Only use `observer()` on extracted sub-components.\n\n";
     // Try exact key match (with alias resolution)
     if (frameworkData.topics[resolvedTopic]) {
         const t = frameworkData.topics[resolvedTopic];
         const prefix = storeTopics.has(resolvedTopic) ? observerReminder : "";
-        return { content: [{ type: "text", text: `## ${t.title}\n\n${prefix}${t.content}` }] };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `## ${t.title}\n\n${prefix}${t.content}`,
+                },
+            ],
+        };
     }
     // Try original topic key (without alias) in case it's a direct key
     if (resolvedTopic !== topicLower && frameworkData.topics[topicLower]) {
         const t = frameworkData.topics[topicLower];
         const prefix = storeTopics.has(topicLower) ? observerReminder : "";
-        return { content: [{ type: "text", text: `## ${t.title}\n\n${prefix}${t.content}` }] };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `## ${t.title}\n\n${prefix}${t.content}`,
+                },
+            ],
+        };
     }
     // Try keyword search
     const matches = searchFrameworkTopics(topic);
@@ -1960,7 +2349,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 +2370,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 +2406,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 +2447,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 +2483,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 +2497,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 +2534,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 +2647,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 +2727,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,18 +2766,45 @@ server.tool("list_types", "List storefront types and enums. Use `domain` and/or
     return { content: [{ type: "text", text: parts.join("\n") }] };
 });
 // Tool: get_prop_types
-server.tool("get_prop_types", "Get all available ikas.config.json prop types with descriptions, TypeScript types, and examples. Tip: Use `npx ikas-component config add-component --props '[...]'` to create a component with all props in one command, or `add-prop` to add props incrementally. NEVER manually edit types.ts — it is auto-generated by the CLI.", {}, async () => {
+server.tool("get_prop_types", 'Get all available ikas.config.json prop types with descriptions, TypeScript types, and examples. NOTE: these are the TypeScript prop-definition types for authoring a component — they are NOT the runtime JSON value shapes you write via `update_section_prop` (e.g. a TEXT prop is typed `string` here but written as `{ "value": "..." }`, and an IMAGE is `IkasImage | null` here but written as `{ "id": "..." }`). For the value shapes to pass to `update_section_prop`, see that tool\'s description. Tip: Use `npx ikas-component config add-component --props \'[...]\'` to create a component with all props in one command, or `add-prop` to add props incrementally. NEVER manually edit types.ts — it is auto-generated by the CLI.', {}, async () => {
     const propTypesTopic = frameworkData.topics["prop-types"];
     if (propTypesTopic) {
         return {
-            content: [{ type: "text", text: `## ${propTypesTopic.title}\n\n${propTypesTopic.content}` }],
+            content: [
+                {
+                    type: "text",
+                    text: `## ${propTypesTopic.title}\n\n${propTypesTopic.content}`,
+                },
+            ],
         };
     }
     return {
-        content: [{ type: "text", text: "Prop types documentation not available." }],
+        content: [
+            {
+                type: "text",
+                text: "Prop types documentation not available.",
+            },
+        ],
     };
 });
 // Tool: get_section_template
+// Starter templates that rebuild a page ikas already ships as a ready-made BUILT-IN page. Asked to
+// "build a login page", the agent reaches for the template before any other tool — so the
+// ask-the-user gate rides this response, where it cannot be skimmed past.
+const BUILTIN_COVERED_TEMPLATES = new Set([
+    "login-section",
+    "register-section",
+    "forgot-password-section",
+    "recover-password-section",
+    "email-verification-section",
+    "account-info-section",
+    "favorites",
+]);
+const BUILTIN_COVERED_BANNER = [
+    "STOP — ASK THE USER BEFORE CODING THIS.",
+    "This template rebuilds a page ikas already ships as a ready-made page: fully functional auth/account flows out of the box, customized and localized via `update_ready_made_page_prop`, the whole group enabled with `enable_ready_made_pages` (see `list_ready_made_pages`).",
+    "If the user has not EXPLICITLY chosen a custom-coded page, do not write code yet. Ask them now: (a) ikas's ready-made page — instant, maintained by ikas — or (b) a custom section with full design freedom. List the ready-made option FIRST as the recommended default; custom comes second. Continue with this template ONLY after they explicitly choose custom.",
+].join("\n");
 // Build the enum dynamically from the on-disk section templates directory
 const sectionTemplateKeys = sectionTemplateNames.length > 0
     ? sectionTemplateNames
@@ -2410,6 +2889,9 @@ server.tool("get_section_template", "Get the root files of a starter section tem
         (bundle.componentNames.length > 0 && !componentsFullyIncluded) ||
         (bundle.subComponentNames.length > 0 && !subComponentsFullyIncluded);
     const parts = [
+        ...(BUILTIN_COVERED_TEMPLATES.has(normalizedType)
+            ? [BUILTIN_COVERED_BANNER, ""]
+            : []),
         `## ${bundle.title} — API Integration Pattern Reference`,
         "",
     ];
@@ -2419,7 +2901,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 +3026,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 +3102,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()
@@ -2775,14 +3258,21 @@ server.tool("list_section_types", "List all available `get_section_template` sec
     ];
     for (const name of sectionTemplateNames) {
         const meta = loadSectionMeta(name);
-        lines.push(`- \`${name}\`${meta ? ` — ${meta.title}` : ""}`);
+        const builtinMark = BUILTIN_COVERED_TEMPLATES.has(name)
+            ? " [ikas ships a ready-made page for this — ask the user before coding a custom one; see list_ready_made_pages]"
+            : "";
+        lines.push(`- \`${name}\`${meta ? ` — ${meta.title}` : ""}${builtinMark}`);
     }
     lines.push("", "Call `get_section_template(sectionType)` to fetch one.");
     return { content: [{ type: "text", text: lines.join("\n") }] };
 });
 // --- Migration tools ---
 // Tool: analyze_old_theme
-server.tool("analyze_old_theme", "Analyze an old ikas storefront theme.json and produce a structured migration report. Shows all components, custom data definitions, prop type breakdown, and migration recommendations. Use this as the first step when converting an old theme.", { theme_json: z.string().describe("The raw JSON content of the old theme.json file") }, async ({ theme_json }) => {
+server.tool("analyze_old_theme", "Analyze an old ikas storefront theme.json and produce a structured migration report. Shows all components, custom data definitions, prop type breakdown, and migration recommendations. Use this as the first step when converting an old theme.", {
+    theme_json: z
+        .string()
+        .describe("The raw JSON content of the old theme.json file"),
+}, async ({ theme_json }) => {
     try {
         const parsed = JSON.parse(theme_json);
         const analysis = analyzeOldTheme(parsed);
@@ -2790,102 +3280,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 +3445,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 +3483,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 +3568,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 +3607,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 +3642,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 +3665,68 @@ 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;
     }
 }
-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) }] };
+// Coerce a JSON-ARRAY argument (points / settings / colors) into the single JSON-array string the
+// CLI expects. Agents sometimes send these PRE-STRINGIFIED (a JSON string instead of a real array);
+// a blind JSON.stringify would then double-encode it ("[...]" -> "\"[...]\"") and the CLI rejects it
+// with "must be a JSON array". So pass a string through as-is (the CLI parses + validates it) and
+// only stringify real arrays/values. NOTE: only for array args — a scalar `value` arg must NOT use
+// this (a plain string there is a literal value, not stringified JSON).
+function toJsonArrayArg(value) {
+    return typeof value === "string" ? value : JSON.stringify(value ?? []);
+}
+/**
+ * The `confirm` parameter shared by the destructive editor tools.
+ *
+ * Spelled out at length on purpose: a one-word "confirmation" flag reads to a model as a
+ * formality to fill in, and the whole point is that it stands for a human's answer.
+ */
+const CONFIRM_PARAM_DESCRIPTION = "Must be `true`, and only after the USER has explicitly agreed to this specific deletion. It stands for their consent, not for your own confidence \u2014 never set it to clear up something you merely believe is unused, and never re-run with it after a refusal without asking first. The merchant's content goes with the deletion and only the editor's undo stack can bring it back.";
+/** Reply for a destructive tool called without consent. The dev-server action refuses too. */
+function destructiveConfirmRefusal() {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    success: false,
+                    error: "Refused: `confirm` was not true. This deletes the merchant's content and can only be undone from the editor's undo stack. Ask the user whether to proceed, and pass confirm: true only after they agree.",
+                }, null, 2),
+            },
+        ],
+    };
+}
+async function callEditorAction(projectRoot, args) {
+    try {
+        const { stdout, stderr, exitCode } = await runIkasComponentCli(projectRoot, args);
+        const parsed = parseCliJson(stdout);
+        if (parsed) {
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(parsed, null, 2) },
+                ],
+            };
         }
         return {
             content: [
@@ -3097,38 +3749,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)."),
+server.tool("list_editor_pages", "List pages in the connected editor's project. Returns id, name, pageType, slug for each page. Requires `ikas theme dev` to be running with the editor connected. Use the returned `id`s as the `pageId` argument to `add_section_to_page`.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project (where `node_modules/.bin/ikas-component` lives)."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
 }, async ({ project_root, port }) => {
     const args = ["list-pages", ...(port ? ["--port", String(port)] : [])];
     return callEditorAction(project_root, args);
 });
 // Tool: list_imported_sections
-server.tool("list_imported_sections", "List section-type code components already imported into the editor's project (theme.codeComponents, filtered to type=section). Use to confirm a component is ready to be placed on a page. The component must be built (`ikas-component build`/`dev`) and imported (`import_section`) before it can be added to a page. The returned `id` is the editor's id for the imported component — normally identical to the id in `ikas.config.json`, but it can differ if the dev component was deleted and re-scaffolded after a previous import. Always use the `id` from this tool, not from `ikas.config.json`, when calling `add_section_to_page`.", {
-    project_root: z.string().describe("Absolute path to the code-component project."),
-    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+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, or when the theme installed this project as a design asset (the editor then reports the published id). Always use the `id` from this tool, not from `ikas.config.json`, when calling `add_section_to_page`. A differing id is NEVER a reason to edit `ikas.config.json` — config ids are immutable.", {
+    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)] : [])];
+    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 or on a theme that installed the project as a design asset; never edit the config to make them match)."),
     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,8 +3832,1638 @@ server.tool("add_section_to_page", "Place an already-imported section-type code
     ];
     return callEditorAction(project_root, args);
 });
-// --- Start server ---
+// 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.strictObject({
+        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.strictObject({
+            prop_id: z
+                .string()
+                .optional()
+                .describe("Blueprint prop id (provide this or prop_name)."),
+            prop_name: z
+                .string()
+                .optional()
+                .describe("Blueprint prop name (alternative to prop_id)."),
+            value: z
+                .any()
+                .describe("Prop value, same shape update_section_prop expects for that type."),
+        }))
+            .optional()
+            .describe("Optional prop values to set on this section right after placing it."),
+    }))
+        .describe("Non-empty array of sections to place (in order), each with its componentId and optional prop updates."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, page_id, sections, port }) => {
+    const normalized = (sections || []).map((s) => ({
+        componentId: s.component_id,
+        ...(typeof s.index === "number" ? { index: s.index } : {}),
+        ...(s.updates
+            ? {
+                updates: s.updates.map((u) => ({
+                    ...(u.prop_id ? { propId: u.prop_id } : {}),
+                    ...(u.prop_name ? { propName: u.prop_name } : {}),
+                    value: u.value,
+                })),
+            }
+            : {}),
+    }));
+    const args = [
+        "add-sections-to-page",
+        "--page-id",
+        page_id,
+        "--sections",
+        JSON.stringify(normalized),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: list_page_sections
+server.tool("list_page_sections", "List the sections placed on a page — a LEAN ROSTER that never truncates: per-placement `elementId` (the identity of THIS placement — there can be multiple of the same section), `sectionId`, `componentId`, `name`, `propCount`, and `setPropNames` (which props already have a value). It deliberately omits the prop SCHEMA and the prop VALUES (both can be large — Header alone can have ~80 props). To get a section's prop schema (types, ENUM options, allowed children) call `get_component_props(componentId)`; to read its current values call `get_section_values(element_id)`. Use the returned `elementId` with `update_section_prop` / `update_page_sections`. Use `list_editor_pages` for page ids. COMMON (global) sections — the theme's header and footer — carry an extra `common` field (`isCommon`, `commonSectionType`, `canonicalPageId`/`canonicalElementId`, `valuesArePageSpecific: false`): their prop values are NOT page-specific, they are shared by every page and stored on the INDEX (Home) page's placement, so `setPropNames` for them reflects that one shared record and any write from any page changes the header/footer everywhere. A page customized per storefront-routing/specification holds a SEPARATE set of placements with its own section order in each state: this lists the BASE layer by default and reports the available states in `pageStates` (plus a `scope` field) — pass `sf_routing_id`/`specification_id` to list a state's own placements instead, which is what `move_page_section` needs when reordering that state.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    page_id: z.string().describe("Target page id (from `list_editor_pages`)."),
+    sf_routing_id: z
+        .string()
+        .optional()
+        .describe("List a routing-customized state of the page instead of the base layer. Ids come from the `pageStates` block this tool returns for a customized page."),
+    specification_id: z
+        .string()
+        .optional()
+        .describe("Specification of the customized state to list (used together with `sf_routing_id`)."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, page_id, sf_routing_id, specification_id, port }) => {
+    const args = [
+        "list-page-sections",
+        "--page-id",
+        page_id,
+        ...(sf_routing_id ? ["--sf-routing-id", sf_routing_id] : []),
+        ...(specification_id ? ["--specification-id", specification_id] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: move_page_section
+server.tool("move_page_section", "Reorder a section that is ALREADY placed on a page — the only way to change section order, since the editor UI offers it solely as a drag in the layers tree. Target the placement by its `element_id` from `list_page_sections` (NOT the sectionId/componentId — a page can hold several placements of the same section and each moves independently). Give EITHER `direction` (\"up\"/\"down\", one position — use this for a simple nudge) OR `to_index` (absolute 0-based position), never both. Indices are 0-based and count ONLY placed sections, in exactly the order `list_page_sections` returns them, so you can read that list, pick a target position from it, and pass it straight back. The result returns `fromIndex`, `resultIndex` (where the section ACTUALLY ended up) and `sections` (the full resulting order) — assert on `resultIndex`/`sections` rather than assuming the move landed where you asked; if it lands somewhere other than requested a `note` says so. A reorder that does not take effect comes back as an ERROR, never as a success that changed nothing, so a successful result means the section really moved. Out-of-range indices are rejected with the valid range (and the section's current index) instead of being clamped. Passing a `sectionId`/`componentId` where an `element_id` belongs is detected and the error names the elementId you actually wanted. COMMON (global) sections — the theme's header and footer — are REJECTED: their position is fixed by the theme, so there is nothing to reorder. SCOPE: by default this reorders the page's BASE layer. A page customized per storefront-routing/specification keeps a SEPARATE set of placements and its own section order in each of those states — pass `sf_routing_id` (and `specification_id`) to reorder one of them instead, and read that state's current order with `list_page_sections` using the SAME ids. Whenever the page has any state the result carries `scope`, `pageStates` and `pageStatesNote`: do not report a reorder as verified on such a page without checking them, since reordering the base layer leaves every state exactly as it was. The state must ALREADY exist — creating one duplicates the whole page and is a deliberate editor action, so an unknown routing/specification is rejected with the list of existing states rather than created. To place a NEW section at a specific position use `add_sections_to_page` with its `index` instead; this tool only moves existing placements.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    page_id: z.string().describe("Target page id (from `list_editor_pages`)."),
+    element_id: z
+        .string()
+        .describe("Placed-section elementId to move (from `list_page_sections`)."),
+    direction: z
+        .enum(["up", "down"])
+        .optional()
+        .describe("Move one position up or down. Provide this or `to_index`, not both."),
+    to_index: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe("Absolute 0-based target position among the page's placed sections. Provide this or `direction`, not both."),
+    sf_routing_id: z
+        .string()
+        .optional()
+        .describe("Reorder a routing-customized state of the page instead of the base layer. Ids come from the `pageStates` block returned by `list_page_sections`. The state must already exist."),
+    specification_id: z
+        .string()
+        .optional()
+        .describe("Specification of the customized state to reorder (used together with `sf_routing_id`)."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, page_id, element_id, direction, to_index, sf_routing_id, specification_id, port, }) => {
+    const args = [
+        "move-page-section",
+        "--page-id",
+        page_id,
+        "--element-id",
+        element_id,
+        ...(direction ? ["--direction", direction] : []),
+        ...(to_index !== undefined ? ["--to-index", String(to_index)] : []),
+        ...(sf_routing_id ? ["--sf-routing-id", sf_routing_id] : []),
+        ...(specification_id ? ["--specification-id", specification_id] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: get_component_props
+server.tool("get_component_props", "Get prop blueprints straight from the editor (the source of truth) for one or MANY components in a single call — for any section OR child code component ids. Returns `{ components: [...] }`, each prop carrying its `id`, `name`, `type`, `required`, `default`, and crucially: a ready-to-use `writeExample` (the EXACT value shape to pass to update_section_prop / update_page_sections — e.g. PRODUCT_LIST, BLOG_LIST, COMPONENT_LIST, LINK) plus a `writeNote` for variants, so you do NOT have to guess or trial-write the JSON; for ENUM props the `options` (valid `value`s); and for COMPONENT/COMPONENT_LIST props the `allowedComponentIds` (which children the slot permits — when empty, an `allowedComponentsNote` says any imported code component is allowed). Use this (its `writeExample`/`options`/`allowedComponentIds`) instead of guessing or reading ikas.config.json. Pass ALL the section/child ids you need at once (batch). Child component ids come from a parent prop's `allowedComponentIds` (or get_section_template).", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    component_ids: z
+        .array(z.string())
+        .describe("Section/child code-component ids to resolve (batch). From list_imported_sections or a COMPONENT_LIST prop's allowedComponentIds."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, component_ids, port }) => {
+    const args = [
+        "get-component-props",
+        "--component-ids",
+        (component_ids || []).join(","),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: get_section_values
+server.tool("get_section_values", "Get the CURRENT prop values of one or MANY placed sections (each with its full `propValues` plus blueprint `props` — every prop carrying a `writeExample`/`writeNote` for the exact value shape, plus ENUM `options` and COMPONENT_LIST `allowedComponentIds`). `list_page_sections` is lean and omits values to avoid truncation; use this to read sections' values — needed for read-modify-write of a COMPONENT_LIST, or to inspect the exact stored shape of an existing value. Returns `{ sections: [...] }`. Pass all the elementIds you need at once (batch). COMMON (global) sections — the theme's header and footer — keep ONE shared set of prop values for the whole theme, stored on the INDEX (Home) page's placement; for those this tool reads the values FROM that canonical placement (a non-INDEX placement stores nothing of its own) and returns a `common` block naming `canonicalPageId`/`canonicalElementId`. So the values you get for a header/footer are the live ones the page actually renders no matter which page_id you ask from — do NOT read defaults as \"empty\" and blind-fill them, and remember any write goes to that same shared record and changes all pages. A prop bound to a theme GLOBAL variable stores no value in `propValues` — it is listed in the section's `bindings` map instead (`{ \"<propName>\": { boundGlobal: \"_<id>\", displayName, type } }`); treat such a prop as SET, not empty, and do not overwrite it with a static value unless asked (a static write removes the binding).", {
+    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`."),
+    locale: z
+        .string()
+        .optional()
+        .describe("A store language (e.g. `en`): the values as that language shows them on these placements (its own value, else the section's translation, else the base value). Read before `update_section_prop` with `locale`. When the result lists several `routings`, they may differ: read and write one with `routing`."),
+    routing: z
+        .string()
+        .optional()
+        .describe("One routing of the store, by path (e.g. `/test2`) or id: as `locale`, for that routing alone. A language several routings show (`/en`, `/test2`) gives each its own values, link labels included; `locale` reads the first and writes all of them."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, page_id, element_ids, locale, routing, port }) => {
+    const args = [
+        "get-section-values",
+        "--page-id",
+        page_id,
+        "--element-ids",
+        (element_ids || []).join(","),
+        ...(locale ? ["--locale", locale] : []),
+        ...(routing ? ["--routing", routing] : []),
+        ...(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). A link\'s label on the other routings is its `translations`, each routing showing its own `{ "locale", "label", "sfRoutingId" }`, else its language\'s `{ "locale", "label" }`, else `label`. Do NOT write these by hand: write the link with only its label changed using `locale` (every routing of that language) or `routing` (one routing), and the label becomes that translation, with no copy of the links (see below). A link sent without `translations` keeps its stored ones (matched by its `id`), so a link list can be resent with new links but without its labels; `"translations": null` drops them. Hand-written ones are REJECTED unless there is at most one per language and per routing and each `sfRoutingId` is a routing with a path whose language is the record\'s `locale`; the labels of a routing the store no longer has are dropped (the result\'s `removedRoutingLabels` names them). On a PRODUCT/CATEGORY/BRAND link with `itemId`, `"useItemNameTranslations": true` shows the item\'s own name in each language instead, its `translations` never showing; the name is fetched when the page renders, not stored (the result\'s `itemNamesNote` says so). A translatable value may hold `"pinned": true`: the editor\'s mark that it is this placement\'s own and stays so when its language\'s default text changes — send it back as read. PRODUCT = `{ "productId": "...", "variantId"?: "..." }`. This SAME unwrapped shape applies whether the prop sits at section level OR nested inside a COMPONENT_LIST entry\'s `propValues` — there is no section-vs-nested difference. IMPORTANT: pass `value` as the parsed JSON object/array itself, NEVER as a JSON string (a stringified value is double-encoded and stored as a useless string). Values are validated server-side (deeply, including nested COMPONENT_LIST children): wrong shapes AND wrong semantics are REJECTED with an explanatory error instead of being silently stored. This includes: a `{ "value": [...] }` wrapper for a COMPONENT_LIST; a `{ "value": ... }`-wrapped IMAGE; `props` instead of `propValues`; a missing/duplicate entry `id`; a child referenced by the wrong key (a code component MUST use `codeComponentId`, a theme component `componentId`) or by an id that does not exist (child ids are opaque — take them from `get_section_template` / `list_imported_sections`, never invent them); and any `propValues` key that is not a real prop of that child component (the error lists the valid prop names). Auto-import: a referenced child code component that has been BUILT but not yet imported into the theme is imported automatically before the value is set (the response lists any such ids under `autoImported`); only children that are not built at all fail with a "no imported code component" error — build them first (`ikas-component build`/`dev`). For any prop type you are unsure about, inspect the existing value with `get_section_values` and match its exact shape. The change is applied with undo support.\n\n' +
+    "COMMON (global) sections — the theme's HEADER and FOOTER: these render on every page that carries a placement of them (ikas ready-made account/membership pages are born without one) and have ONE shared set of prop values, stored on the INDEX (Home) page's placement. Whichever page_id you write from, the value lands on that single record and changes the header/footer on ALL pages; the response carries a `common` block (`commonSectionType`, `canonicalPageId`, `canonicalElementId`) saying so, and the echoed `value` is read back from that canonical placement. Therefore: ALWAYS `get_section_values` first and change only the prop the user asked about — the props are already filled with the merchant's content even when you are on a page you have not inspected, so blind-filling \"empty-looking\" props overwrites the live header/footer everywhere. If the INDEX page has no placement of the section, there is no record to write to and the call fails telling you to add it to the INDEX page first.\n\n" +
+    "ONE LANGUAGE OF THIS PLACEMENT (`locale`): with `locale` (a store language, e.g. `en`) the value is written for that language on THIS placement only, as the editor's canvas does with that language selected — the tool for a section that should read differently per page in a language (the translations page translates a section once, for every placement), and for a link's label in that language (a LINK / LIST_OF_LINK, or a link inside a COMPONENT_LIST entry): send the value as `get_section_values` with the same `locale` shows it, with ONLY labels changed, and they become that language's link translations (the links keep following the base). Any other change (a link's page, URL, order, a new link) gives that language its own copy of the links, which stops following the base. Without `locale` the base value is written: the base language's, and every other language's that has no value of its own (a translatable prop — TEXT, RICH_TEXT, IMAGE, IMAGE_LIST, VIDEO — shows the section's translation in that language first: update_translations). The base language itself takes no `locale` (refused). A prop bound to a global shows the binding in every language, so `locale` is refused for it. Read what a language shows with `get_section_values` and the same `locale` first; the result echoes `locale` and the `routings` written ({ sfRoutingId, path, locale }). ONE ROUTING (`routing`, e.g. `/test2`): a language several routings show (`/en`, `/test2`) gives each its own values, link labels included, and `locale` writes to all of them. When `get_section_values` with `locale` lists several `routings` (and a `routingsNote`), read with `routing` and write back with the SAME `routing` — writing those values with `locale` replaces the other routings' own labels.\n\nBIND TO A GLOBAL VARIABLE (Theme Setting): instead of a static `value`, pass `bind_global` = the global's `name` (its `variableName`, the `_<id>` form) from `list_theme_globals`. The prop becomes a LIVE dynamic value that always reflects that global's current value — editing the global in Theme Settings updates every bound prop. Use this to wire content to a project-wide setting (e.g. a shared announcement text, brand color, or logo image) rather than duplicating a literal. Pick a global whose type matches the prop (TEXT↔TEXT/RICH_TEXT, NUMBER↔NUMBER, BOOLEAN↔BOOLEAN, IMAGE↔IMAGE, COLOR↔COLOR, ENUM↔ENUM of the SAME enum type — the prop's `enumTypeId` must equal the setting's `enumTypeId`; a mismatch is REJECTED, …). Provide `value` OR `bind_global`, not both. Writing a static `value` to a prop that is bound to a global (see `bindings` in `get_section_values`) REPLACES the binding — the prop stops following the global, and the result carries `unboundGlobal` + a `warning`. To change what a bound prop shows, update the global (`update_theme_global`) instead. 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. Writing a static `value` to a prop that is bound to a global (see `bindings` in `get_section_values`) REPLACES the binding — the prop stops following the global, and the result carries `unboundGlobal` + a `warning`. To change what a bound prop shows, update the global (`update_theme_global`) instead. Bindable globals include TEXT / RICH_TEXT / NUMBER / BOOLEAN / IMAGE / COLOR / BORDER / SHADOW / ENUM settings; pick a global whose type matches the prop (an ENUM prop only binds an ENUM setting of the same enum type). (This is the general theme-global binding; a COLOR prop can alternatively take an inline `{ \"patternValueId\" }` for theme colors.)"),
+    locale: z
+        .string()
+        .optional()
+        .describe("A store language (e.g. `en`): write that language's value of THIS placement only, instead of the base value. Not with `bind_global`; not the base language."),
+    routing: z
+        .string()
+        .optional()
+        .describe("One routing of the store, by path (e.g. `/test2`) or id: as `locale`, for that routing alone. A language several routings show (`/en`, `/test2`) gives each its own values, link labels included; `locale` reads the first and writes all of them."),
+    list_path: z
+        .array(z.strictObject({ 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, locale, routing, 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] : []),
+        ...(locale ? ["--locale", locale] : []),
+        ...(routing ? ["--routing", routing] : []),
+        ...(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. Pass `locale` to write ONE language's values of these placements instead of the base values, as update_section_prop's `locale` does (no bind_global items then).", {
+    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.strictObject({
+        element_id: z
+            .string()
+            .describe("Placed-section elementId (from list_page_sections)."),
+        updates: z
+            .array(z.strictObject({
+            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.strictObject({ 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."),
+    locale: z
+        .string()
+        .optional()
+        .describe("A store language (e.g. `en`): write that language's values of these placements only, instead of the base values. Not with bind_global items; not the base language."),
+    routing: z
+        .string()
+        .optional()
+        .describe("One routing of the store, by path (e.g. `/test2`) or id: as `locale`, for that routing alone. A language several routings show (`/en`, `/test2`) gives each its own values, link labels included; `locale` reads the first and writes all of them."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, page_id, sections, locale, routing, 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),
+        ...(locale ? ["--locale", locale] : []),
+        ...(routing ? ["--routing", routing] : []),
+        ...(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.strictObject({
+        file_path: z
+            .string()
+            .optional()
+            .describe("Local image file path (provide this or image_url)."),
+        image_url: z
+            .string()
+            .optional()
+            .describe("Image URL to fetch (alternative to file_path)."),
+        alt_text: z.string().optional().describe("Alt text for this image."),
+    }))
+        .describe("Non-empty array of images to upload."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, images, port }) => {
+    const manifest = (images || []).map((im) => ({
+        ...(im.file_path ? { file: im.file_path } : {}),
+        ...(im.image_url ? { url: im.image_url } : {}),
+        ...(im.alt_text ? { alt: im.alt_text } : {}),
+    }));
+    const args = [
+        "upload-images",
+        "--manifest",
+        JSON.stringify(manifest),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: search_products
+server.tool("search_products", 'Search the connected store\'s products to obtain a real productId (and first variantId) for a PRODUCT prop value. Returns products with productId, variantId, name, slug, variantCount, and `imageSrc` (the full-resolution CDN URL of the product\'s main image). To use that product image in an IMAGE prop, you CANNOT reuse a product image id directly (it is not a theme asset) — pass the `imageSrc` URL to `upload_image(image_url: <imageSrc>)` (or `upload_images`), then use the returned id in the IMAGE value. This gives real product imagery instead of external/placeholder URLs. Use the result in update_section_prop as `{ "productId": "<productId>", "variantId": "<variantId>" }`. Pass `query` for free-text search, or `product_ids` to resolve specific ids. Requires the editor embedded in the ikas admin panel (the admin panel runs the search; a standalone editor cannot).', {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    query: z
+        .string()
+        .optional()
+        .describe("Free-text product search (name, sku, barcode)."),
+    product_ids: z
+        .array(z.string())
+        .optional()
+        .describe("Specific product ids to resolve directly (alternative to `query`)."),
+    per_page: z.number().optional().describe("Results per page."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, query, product_ids, per_page, port }) => {
+    const args = [
+        "search-products",
+        ...(query ? ["--query", query] : []),
+        ...(product_ids && product_ids.length
+            ? ["--ids", product_ids.join(",")]
+            : []),
+        ...(typeof per_page === "number" ? ["--per-page", String(per_page)] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: list_categories
+server.tool("list_categories", 'List the store\'s product categories and their ids, to fill a CATEGORY prop value `{ "categoryId": "<id>" }`. Returns categoryId, name, slug, parentId for each. Returns all categories (no query). To link to a category from a LINK prop, also call `get_page_by_type("CATEGORY")` for the page id, then build `{ "linkType": "PAGE", "pageId": <pageId>, "pageType": "CATEGORY", "itemId": <categoryId>, "id": <unique>, "label": "..." }`. Requires the editor embedded in the ikas admin panel.', {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, port }) => {
+    const args = [
+        "list-entities",
+        "--kind",
+        "category",
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: list_brands
+server.tool("list_brands", 'List the store\'s product brands and their ids, to fill a BRAND prop value `{ "brandId": "<id>" }`. Returns brandId, name, slug for each. Returns all brands (no query). To link to a brand from a LINK prop, also call `get_page_by_type("BRAND")` for the page id, then build `{ "linkType": "PAGE", "pageId": <pageId>, "pageType": "BRAND", "itemId": <brandId>, "id": <unique>, "label": "..." }`. Requires the editor embedded in the ikas admin panel.', {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, port }) => {
+    const args = [
+        "list-entities",
+        "--kind",
+        "brand",
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: list_blogs
+server.tool("list_blogs", 'List the store\'s blogs and their ids, to fill a BLOG prop value `{ "blogId": "<id>" }`. Returns blogId, name, slug for each. Accepts an optional `query` for free-text search. To link to a blog from a LINK prop, also call `get_page_by_type("BLOG")` for the page id, then build `{ "linkType": "PAGE", "pageId": <pageId>, "pageType": "BLOG", "itemId": <blogId>, "id": <unique>, "label": "..." }`. Requires the editor embedded in the ikas admin panel.', {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    query: z.string().optional().describe("Free-text blog search."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, query, port }) => {
+    const args = [
+        "list-entities",
+        "--kind",
+        "blog",
+        ...(query ? ["--query", query] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: list_blog_categories
+server.tool("list_blog_categories", 'List the store\'s blog categories and their ids, to fill a BLOG_CATEGORY prop value `{ "blogCategoryId": "<id>" }`. Returns blogCategoryId, name, slug for each. Accepts an optional `query` for free-text search. To link to a blog category from a LINK prop, also call `get_page_by_type("BLOG_CATEGORY")` for the page id, then build `{ "linkType": "PAGE", "pageId": <pageId>, "pageType": "BLOG_CATEGORY", "itemId": <blogCategoryId>, "id": <unique>, "label": "..." }`. Requires the editor embedded in the ikas admin panel.', {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    query: z.string().optional().describe("Free-text blog-category search."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, query, port }) => {
+    const args = [
+        "list-entities",
+        "--kind",
+        "blog-category",
+        ...(query ? ["--query", query] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: get_page_by_type
+server.tool("get_page_by_type", 'Resolve a theme page\'s id from its pageType (CATEGORY, PRODUCT, BRAND, BLOG, BLOG_CATEGORY, INDEX, …). Use this to get the `pageId` needed to build a PAGE link to an entity: pair it with the entity id from list_categories/list_brands/list_blogs/list_blog_categories — `{ linkType:"PAGE", pageId:<this pageId>, pageType:<type>, itemId:<entityId>, id:<unique>, label:... }`. Returns `pageId: null` (with a note) if no page of that type exists yet — in that case call `create_page(page_type)` to add it, then use the returned pageId (do not guess a slug/EXTERNAL URL).', {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    page_type: z
+        .string()
+        .describe("Page type to resolve, e.g. CATEGORY, PRODUCT, BRAND, BLOG, BLOG_CATEGORY, INDEX."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, page_type, port }) => {
+    const args = [
+        "get-page-by-type",
+        "--page-type",
+        page_type,
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: create_page
+server.tool("create_page", 'Create a theme page of a given pageType in the connected editor. Use this when get_page_by_type returns `pageId: null` for a dynamic page (CATEGORY/PRODUCT/BRAND/BLOG/BLOG_CATEGORY) you need to link to: create the page, then build a PAGE link `{ linkType:"PAGE", pageId:<this pageId>, pageType:<type>, itemId:<entityId>, id:<unique>, label:... }` — do NOT guess a slug/EXTERNAL URL. Non-CUSTOM page types are unique per theme: if one already exists it is returned unchanged (`alreadyExisted: true`). CUSTOM pages require `name` and a unique `slug`. Account sub-pages (ADDRESSES/ORDERS/ORDER_DETAIL/FAVORITE_PRODUCTS/RAFFLE_ACCOUNT) need an ACCOUNT page first. Returns `{ pageType, pageId, name, slug }`. Requires `ikas theme dev` running with the editor connected.', {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    page_type: z
+        .string()
+        .describe("Page type to create, e.g. CATEGORY, PRODUCT, BRAND, BLOG, BLOG_CATEGORY, INDEX, CUSTOM."),
+    name: z
+        .string()
+        .optional()
+        .describe("Page name. Required for CUSTOM pages; ignored otherwise."),
+    slug: z
+        .string()
+        .optional()
+        .describe("Page slug. Required (and unique) for CUSTOM pages; ignored otherwise."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, page_type, name, slug, port }) => {
+    const args = [
+        "create-page",
+        "--page-type",
+        page_type,
+        ...(name ? ["--name", name] : []),
+        ...(slug ? ["--slug", slug] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: delete_page
+server.tool("delete_page", "Delete a theme page and every section placed on it. DESTRUCTIVE and effectively one-way from here (only the editor's own undo stack can bring it back) — ALWAYS get the user's explicit OK before calling it, and never call it to \"clean up\" a page you merely think is unused. Takes the page id from `list_editor_pages` / `get_page_by_type`; there is no name resolution. Refused for the pages a theme cannot run without — INDEX (home), CHECKOUT and NOT_FOUND (404) — and for an ikas-rendered ready-made account page, which must be turned off by its group with `enable_ready_made_pages` so the cleanup that flow does actually runs. Deleting the page currently open in the editor moves it to the home page first. Returns the deleted page's `{ pageId, pageType, name, slug }` plus `remainingPages`. Requires `ikas theme dev` running with the editor connected.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    page_id: z
+        .string()
+        .describe("Id of the page to delete (from `list_editor_pages` or `get_page_by_type`). Strict — no name resolution."),
+    confirm: z.boolean().describe(CONFIRM_PARAM_DESCRIPTION),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, page_id, confirm, port }) => {
+    if (confirm !== true)
+        return destructiveConfirmRefusal();
+    const args = [
+        "delete-page",
+        "--id",
+        page_id,
+        "--yes",
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: remove_page_section
+server.tool("remove_page_section", "Remove ONE section placement from a page — the delete counterpart of `add_section_to_page` / `move_page_section`. DESTRUCTIVE: it takes the merchant's content in that section with it, so get the user's explicit OK first. The checkout section on the CHECKOUT page is refused — the checkout page requires it, so never offer to remove it. Target the PLACEMENT by `element_id` from `list_page_sections`, never the `sectionId` or `componentId` — the same section placed twice has two independent placements and each is removed on its own (passing the wrong id is rejected with the elementId you meant). A common (header/footer) section on the home page is HIDDEN rather than deleted, because the INDEX placement is where a common section's prop values live for EVERY page; the reply says so with `hidden: true`, and `add_section_to_page` brings it back with its values intact. A page customized per routing/specification holds its own placements per state: pass `sf_routing_id`/`specification_id` to remove from that state, otherwise only the BASE layer is touched (the reply lists the states it left alone). Returns the removed placement plus the page's remaining `sections`. Requires `ikas theme dev` running with the editor connected.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    page_id: z
+        .string()
+        .describe("Id of the page holding the placement (from `list_editor_pages`)."),
+    element_id: z
+        .string()
+        .describe("The PLACEMENT's elementId from `list_page_sections` — not the sectionId and not the componentId."),
+    sf_routing_id: z
+        .string()
+        .optional()
+        .describe("Remove from this customized routing state instead of the page's base layer. The state must already exist."),
+    specification_id: z
+        .string()
+        .optional()
+        .describe("Remove from this customized specification state instead of the page's base layer. The state must already exist."),
+    confirm: z.boolean().describe(CONFIRM_PARAM_DESCRIPTION),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, page_id, element_id, sf_routing_id, specification_id, confirm, port, }) => {
+    if (confirm !== true)
+        return destructiveConfirmRefusal();
+    const args = [
+        "remove-page-section",
+        "--page-id",
+        page_id,
+        "--element-id",
+        element_id,
+        "--yes",
+        ...(sf_routing_id ? ["--sf-routing-id", sf_routing_id] : []),
+        ...(specification_id ? ["--specification-id", specification_id] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: publish_theme
+// Tool: list_ready_made_pages
+server.tool("list_ready_made_pages", "List the ikas-rendered ready-made (\"built-in\") account/membership pages (login, register, forgot/recover password, my account, orders, addresses, favorites, email verification) and how to customize them. These pages are rendered by ikas's own components, NOT by sections: a ready-made page carries no sections, so `list_page_sections` shows nothing and `update_section_prop` cannot touch it — `update_ready_made_page_prop` is the write tool. Without arguments returns the roster: per-group (`membership` = login/register/password flows, `account` = my-account pages) enabled state, every ready-made page type with its theme pageId and which props the merchant already edited, plus the SHARED SCOPES (logo, palette, account-menu labels — values edited once that reach every page in the scope's group). Pass `page_type` (e.g. LOGIN) or `scope_id` for that page's/scope's FULL prop schema (types, defaults, ENUM options, translations) and current values (`values` = what the page renders with; `ownValues` = what this page's own layer stores). Pass `sf_routing_id` to read what one storefront routing/locale sees — the no-argument call lists the store's routings (id, path, locale; `isDefault: true` = the base, needing no sf_routing_id). Typical branding flow: read the theme's palette via `list_theme_globals`, then set the shared scope's colors as `{ \"patternValueId\": \"<global color id>\" }` bindings so the pages follow the theme's colors live.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    page_type: z
+        .string()
+        .optional()
+        .describe("One ready-made page's full prop schema and values (e.g. LOGIN, ACCOUNT, ORDERS)."),
+    scope_id: z
+        .string()
+        .optional()
+        .describe("One shared scope's full prop schema and values (scope ids come from the no-argument call)."),
+    sf_routing_id: z
+        .string()
+        .optional()
+        .describe("Read the values one storefront routing/locale sees (default: the base routing)."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, page_type, scope_id, sf_routing_id, port }) => {
+    const args = [
+        "list-builtin-pages",
+        ...(page_type ? ["--page-type", page_type] : []),
+        ...(scope_id ? ["--scope-id", scope_id] : []),
+        ...(sf_routing_id ? ["--sf-routing-id", sf_routing_id] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: update_ready_made_page_prop
+server.tool("update_ready_made_page_prop", 'Set, bind, or clear ONE prop of an ikas-rendered ready-made account/membership page — the write half of `list_ready_made_pages`, and the ONLY way to customize those pages (they have no sections, so `update_section_prop` cannot reach them). Target a page\'s own prop with `page_type` (e.g. LOGIN) or a SHARED prop — logo, palette, menu labels, edited once for every page in the scope\'s group — with `scope_id`. Identify the prop by `prop_id` or `prop_name` from `list_ready_made_pages`. VALUES ARE RAW (no `{ "value": ... }` envelope — an envelope is tolerated and unwrapped): TEXT = the plain string; BOOLEAN = true/false; NUMBER = a number; ENUM = one of the prop\'s `enumOptions` VALUES; COLOR = "#rrggbb" OR `{ "patternValueId": "<global color id>" }` to follow a theme color live (ids from `list_theme_globals` → colors[].id — prefer the binding when branding, so a palette change updates the pages); IMAGE = `{ "id": "<image id>" }` (id from `upload_image`); LINK/LIST_OF_LINK = copy the shape from `list_ready_made_pages` values. `bind_global` (a global\'s `name` from `list_theme_globals`) makes the prop follow a Theme Setting instead of holding a value; `clear: true` deletes the stored value so the prop falls back to the shared value or the manifest default. `sf_routing_id` writes one routing\'s override — use it to localize texts per language; without it you write the base value every routing inherits. Writes are undoable in the editor.', {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    page_type: z
+        .string()
+        .optional()
+        .describe("Page type whose OWN prop to write (e.g. LOGIN). Pass this or scope_id."),
+    scope_id: z
+        .string()
+        .optional()
+        .describe("Shared scope whose prop to write — reaches every ready-made page in its group."),
+    prop_id: z
+        .string()
+        .optional()
+        .describe("Prop id from list_ready_made_pages. Provide this or prop_name."),
+    prop_name: z
+        .string()
+        .optional()
+        .describe("Prop name (alternative to prop_id)."),
+    value: z
+        .any()
+        .optional()
+        .describe("The RAW value (see the tool description for per-type shapes). Omit when using bind_global or clear."),
+    bind_global: z
+        .string()
+        .optional()
+        .describe("Bind the prop to a global variable (Theme Setting) — pass the global's `name` from list_theme_globals."),
+    clear: z
+        .boolean()
+        .optional()
+        .describe("true deletes the stored value; the prop falls back to the shared value or the manifest default."),
+    sf_routing_id: z
+        .string()
+        .optional()
+        .describe("Write one storefront routing's override (localization). Omit to write the base value."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, page_type, scope_id, prop_id, prop_name, value, bind_global, clear, sf_routing_id, port, }) => {
+    const args = [
+        "update-builtin-page-prop",
+        ...(page_type ? ["--page-type", page_type] : []),
+        ...(scope_id ? ["--scope-id", scope_id] : []),
+        ...(prop_id ? ["--prop-id", prop_id] : []),
+        ...(prop_name ? ["--prop-name", prop_name] : []),
+        ...(bind_global
+            ? ["--bind-global", bind_global]
+            : clear
+                ? ["--clear"]
+                : value !== undefined
+                    ? [
+                        "--value",
+                        // ALWAYS JSON-encode: the CLI JSON.parses --value (raw-string fallback), so a
+                        // verbatim TEXT string that happens to parse — "2024", "true", "null" — would
+                        // arrive as a number/boolean/clear. Encoded, it round-trips as the string it is.
+                        JSON.stringify(value),
+                    ]
+                    : []),
+        ...(sf_routing_id ? ["--sf-routing-id", sf_routing_id] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: enable_ready_made_pages
+server.tool("enable_ready_made_pages", 'Turn one GROUP of ikas-rendered ready-made pages on or off: "membership" (login, register, forgot/recover password, email verification) or "account" (my account, orders, order detail, addresses, favorites). Enabling records the choice and creates any page of the group the theme does not have yet — each born rendered by ikas\'s own component; customize them right after with `update_ready_made_page_prop`. Disabling removes ONLY the untouched pages the toggle itself created — a page the merchant built on is never deleted. The flip is one undo step in the editor. Check the current state first with `list_ready_made_pages`.', {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    group: z
+        .enum(["membership", "account"])
+        .describe('"membership" = login/register/password flows; "account" = my-account pages.'),
+    enabled: z
+        .boolean()
+        .describe("true to enable the group, false to disable it."),
+    confirm: z
+        .boolean()
+        .optional()
+        .describe(`Disabling only (it removes pages). ${CONFIRM_PARAM_DESCRIPTION}`),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, group, enabled, confirm, port }) => {
+    if (!enabled && confirm !== true)
+        return destructiveConfirmRefusal();
+    const args = [
+        "enable-builtin-pages",
+        "--group",
+        group,
+        "--enabled",
+        String(enabled),
+        ...(enabled ? [] : ["--yes"]),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: list_translations
+server.tool("list_translations", 'Read the editor\'s translations page — everything its two sides hold. `mode: "store"` = store content: sections\' and components\' translatable prop values (TEXT, RICH_TEXT, IMAGE, IMAGE_LIST, VIDEO), element texts, the storefront\'s common texts (`common`, per store language only), the global texts/images (`global`), and the code component projects\' UI texts (`i18n`: the `src/i18n` files read with `t()`; one item per top-level group, `<projectId>:<group>`; key = the dotted path; "default" = default.json). `mode: "editor"` = the editor texts: item names, prop labels/descriptions, group names/descriptions, and the global settings\' names (`global`: one item per settings list). Locales: "default" is the base texts every language falls back to (no record); otherwise a store language (store mode) or an added editor language (editor mode). Without `area`: the languages, the addable ones, routing languages, and each language\'s translated/total by area — start here. With `area` + `locale`: the area\'s items with progress. With `item_id`: the item\'s fields — `key` (what update_translations takes), `kind` (the value\'s shape), `source` (the text it is translated from), `value` (now), `required`, and `editedOverAsset` when the field holds an edit over a design asset\'s value (resettable). `only_missing: true` keeps the empty fields. Requires `ikas theme dev` running with the editor connected.', {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    mode: z.enum(["store", "editor"]).describe("store = store content; editor = editor texts."),
+    area: z
+        .enum(["sections", "components", "common", "global", "i18n"])
+        .optional()
+        .describe("The page's sidebar list (editor mode has no `common` or `i18n`). Omit for the languages and progress."),
+    locale: z
+        .string()
+        .optional()
+        .describe('"default" or a language code. Required with `area`.'),
+    item_id: z
+        .string()
+        .optional()
+        .describe("An item id from the area's list: returns its fields."),
+    only_missing: z
+        .boolean()
+        .optional()
+        .describe("With item_id: only the fields without a value in `locale`."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, mode, area, locale, item_id, only_missing, port }) => {
+    const args = [
+        "list-translations",
+        "--mode",
+        mode,
+        ...(area ? ["--area", area] : []),
+        ...(locale ? ["--locale", locale] : []),
+        ...(item_id ? ["--item", item_id] : []),
+        ...(only_missing ? ["--only-missing"] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: update_translations
+server.tool("update_translations", 'Write translations in ONE language through the editor\'s translations page, as a batch: each edit is `{ area, item_id, key, value }`, or `{ area, item_id, key, reset: true }` to put back the design asset\'s value of a field listed with `editedOverAsset`. Take `key` and `kind` from `list_translations` with `item_id` — never guess keys. VALUES BY KIND: text = a string; richText = an HTML string (e.g. "<p>Hi</p>"); image = `{ "id": "<image id>", "altText"?: string }` (id from `upload_image`), or `{ "altText": string }` alone in a language to translate only the alt text: the image stays the default\'s and follows it; imageList = `{ "images": [{ "id": ..., "altText"?: string }] }`, or `{ "images": [{ "altText": string }, ...] }` for the default images\' alt texts by their place; video = `{ "video": { "id": ... }, "thumbnailImage"?: { "id": ... }, "autoplay"?, "controls"?, "loop"?, "muted"?: boolean }`; globalImage = `{ "id": ..., "altText"?: string }`, or `{ "altText": string }` as image; `null` empties the field (a cleared common text takes ikas\'s own back); emptying a field that holds a value needs `confirm: true`, after the user agreed. STRICT: every edit is checked before anything is written — the language must be added, the item and key must exist, the value must match the kind (unknown keys rejected), a default name/label or UI text (`i18n`) base text cannot be empty, a UI text\'s translation must use exactly its base text\'s `{{params}}`, and a global setting\'s default name must pass the page\'s rules; one bad edit and NOTHING is written (the reply lists each error). The batch is one undo step in the editor; the open translations page reloads (or warns its unsaved edits). Edits of the connected project\'s code components are written on to its ikas.config.json, its UI texts to its `src/i18n/*.json`. A section\'s `source` is its own default, which every placement without a value of its own shows: a placement\'s value (update_section_prop) can differ. Translate from `source`, keep HTML structure in rich text, do not translate brand names.', {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    mode: z.enum(["store", "editor"]).describe("store = store content; editor = editor texts."),
+    locale: z
+        .string()
+        .describe('"default" (the base texts) or an added language code.'),
+    edits: z
+        .array(z.strictObject({
+        area: z.enum(["sections", "components", "common", "global", "i18n"]),
+        item_id: z.string(),
+        key: z.string(),
+        value: z.any().optional(),
+        reset: z.literal(true).optional(),
+    }))
+        .min(1)
+        .describe("The edits; a field at most once."),
+    confirm: z
+        .boolean()
+        .optional()
+        .describe("Required when an edit empties (value: null) a field that holds a value. Ask the user first; pass true only after they agreed."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, mode, locale, edits, confirm, port }) => {
+    const args = [
+        "update-translations",
+        "--mode",
+        mode,
+        "--locale",
+        locale,
+        "--edits",
+        JSON.stringify(edits),
+        ...(confirm ? ["--yes"] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: manage_translation_languages
+server.tool("manage_translation_languages", 'Add languages to the editor\'s translations page or delete one, as its language settings do. `mode: "store"`: store languages — any language code (`list_translations` lists the addable ones); a new one gets ikas\'s built-in common texts. `mode: "editor"`: the editor languages the editor texts are translated into (tr/en). Pass `add` (codes) OR `remove` (one code). DESTRUCTIVE removal: it deletes every text in that language (and with `remove_page_values`, a routing language\'s page values) — ask the user first and pass `confirm: true` only after they agreed. Adding is one undo step.', {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    mode: z.enum(["store", "editor"]).describe("store = store languages; editor = editor languages."),
+    add: z
+        .array(z.string())
+        .optional()
+        .describe("Language codes to add (e.g. [\"de\", \"fr\"])."),
+    remove: z.string().optional().describe("The language code to delete."),
+    remove_page_values: z
+        .boolean()
+        .optional()
+        .describe("With remove on a store language that has a storefront routing: also remove its page values."),
+    confirm: z.boolean().optional().describe(CONFIRM_PARAM_DESCRIPTION),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, mode, add, remove, remove_page_values, confirm, port }) => {
+    if (remove !== undefined && confirm !== true)
+        return destructiveConfirmRefusal();
+    const args = [
+        "translation-languages",
+        "--mode",
+        mode,
+        ...(add ? ["--add", add.join(",")] : []),
+        ...(remove !== undefined
+            ? ["--remove", remove, "--yes", ...(remove_page_values ? ["--remove-page-values"] : [])]
+            : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+server.tool("publish_theme", "Publish the current theme LIVE — the same action as the editor's Publish button (uploads the whole project to the storefront). This is REAL and customer-facing: the published site changes. SAFETY: it publishes nothing unless `confirm: true` is passed; if you omit it you get a dry-run with the `previewUrl` and a warning describing the impact. The MAIN/production theme additionally requires `confirm_production: true` (its URL is the live customer-facing domain). Use this when the user explicitly asks to publish/go live — do NOT publish on your own initiative. On success returns `{ published: true, previewUrl, isMainTheme }`; open `previewUrl` to review the result. Requires `ikas theme dev` running with the editor connected.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    confirm: z
+        .boolean()
+        .optional()
+        .describe("Set true to actually publish. Omitted/false = dry-run (returns previewUrl + warning, publishes nothing)."),
+    confirm_production: z
+        .boolean()
+        .optional()
+        .describe("Required IN ADDITION to confirm when the target is the MAIN/production theme (live customer-facing site)."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, confirm, confirm_production, port }) => {
+    const args = [
+        "publish-theme",
+        ...(confirm ? ["--confirm"] : []),
+        ...(confirm_production ? ["--confirm-production"] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: get_editor_workflow
+const EDITOR_WORKFLOW_GUIDE = [
+    "# Editor workflow: placing sections and filling their content on a page",
+    "",
+    "Use this when the user wants to add a section to a page and/or fill in its content (heading, text, image, link, slides, etc.) in the live editor. These are LIVE-EDITOR actions and require `ikas theme dev` running with the editor connected; image upload additionally requires the editor to be embedded in the ikas admin panel (the admin panel performs the upload — a standalone editor cannot upload).",
+    "",
+    "## Account & membership pages: ASK before you build",
+    "If the page the user wants is a login, register, forgot/recover-password, my-account, orders, order-detail, addresses, favorites or email-verification page: do NOT code a custom section page yet. ikas ships ready-made versions of exactly these pages — fully functional (real auth/order/address flows), customizable (logo, colors, texts) and localizable via update_ready_made_page_prop, the whole group enabled at once with enable_ready_made_pages. FIRST ask the user which they want: the ready-made page (fast, maintained by ikas) or a custom section page (full design freedom) — list the ready-made option FIRST as the recommended default, custom second. Only start coding after the user explicitly chooses custom — and never call enable_ready_made_pages without the user's OK, it creates/removes pages. Start discovery with list_ready_made_pages. USER-FACING NAME: name these in the USER'S OWN LANGUAGE — English: \"ikas's ready-made pages\", Turkish: \"ikas'ın hazır sayfaları\"; never mix the English term into a sentence in another language — the editor UI lists them as Membership Pages / My Account Pages; \"built-in\" is an internal term — keep it out of everything the user sees, including question/option labels. Note: a ready-made page is born with ONLY its own ikas-rendered element — the theme's header/footer are NOT on it (the page draws its own top bar — logo, back-to-store link — and account nav). If the user wants the theme header/footer there, place it with add_section_to_page (sections can sit above/below that element) and suggest turning the page's `showBrandBar` prop off to avoid double chrome.",
+    "",
+    "## Two distinct jobs — do not confuse them",
+    "- (A) DEFINE props / author component code — changing WHICH props a component has. Edits component source/config (config add-prop/add-component, index.tsx) and needs a rebuild. Do this ONLY when a needed prop does not exist yet, or the user explicitly asks to build/modify the component.",
+    "- (B) SET prop VALUES / fill content — giving values to props that ALREADY exist on a placed section. Pure data entry via list_page_sections + update_section_prop (+ upload_image). No code, no rebuild.",
+    "When the user says 'fill this section', 'set the title/text/image/link', 'populate', 'change the content' → that is JOB (B). Do NOT write a component or add a prop to fill a value the section already supports.",
+    "",
+    "## Step-by-step (JOB B — fill content)",
+    "1. list_editor_pages → choose the target page_id.",
+    "2. list_page_sections(page_id) → for each placed section: its per-placement elementId, blueprint props (id, name, type), and setPropNames (which props already have a value). It is LEAN — no prop VALUES, so it never truncates. To read a section's current values (e.g. to read-modify-write a COMPONENT_LIST), call get_section_values(page_id, element_id). A section returned with a `common` field is the theme's header/footer — its values are theme-wide, not this page's; read the 'COMMON (global) sections' section below BEFORE touching it. (If the section is not on the page yet, see 'Placing a section' below.)",
+    "3. To set props (fewest round-trips = fastest): update_page_sections(page_id, sections:[{element_id, updates:[{prop_name,value}]}]) fills the WHOLE page (or one section, or just one prop — it scales to all cases) in ONE call (best). update_section_prop sets a single prop, for quick one-offs. Pass each value as a parsed JSON object/array, NEVER a JSON string.",
+    "4. For image props: upload_images(images:[{file_path|image_url, alt_text}]) uploads many in ONE call (preferred); upload_image for a single one. Use the returned id(s) in IMAGE values. Do uploads BEFORE the update call so you have the ids.",
+    "Speed tip: each tool call is a round-trip — gather first (one list_page_sections), batch your uploads (upload_images) and your writes (update_page_sections), rather than calling per-prop/per-image.",
+    "",
+    "## COMMON (global) sections: the header and the footer",
+    "The theme's header and footer are COMMON sections: they render on every page that carries a placement of them (pages created in the editor are seeded with one — EXCEPT ikas ready-made (built-in) account/membership pages, which are born without the theme header/footer) and their prop values are SHARED by the whole theme — there is exactly ONE record, kept on the INDEX (Home) page's placement. A placement of the same section on any other page stores NOTHING of its own.",
+    '- How to recognize one: list_page_sections / get_section_values / the write results return a `common` block for it — `isCommon: true`, `commonSectionType: "header"|"footer"`, `valuesArePageSpecific: false`, plus `canonicalPageId`/`canonicalElementId` (the INDEX placement that holds the values). A page containing one also gets a top-level `commonSectionsNote`.',
+    "- READS are redirected for you: get_section_values / list_page_sections report a common section's values FROM the INDEX placement, whatever page_id you pass. So what you see is what the page actually renders — no need to re-read from the INDEX page.",
+    "- WRITES are redirected too: update_section_prop / update_page_sections / add_sections_to_page store the value on that INDEX record, so the change applies to the header/footer on ALL pages. The echoed value is read back from the canonical placement, so it reflects what was really stored.",
+    '- THE TRAP to avoid: a header/footer is normally already filled with the merchant\'s content. Never conclude a prop is empty and never blind-fill "missing" props — you would overwrite live content on every page, including pages you never opened. Always get_section_values first and change ONLY the prop the user asked about.',
+    "- If the INDEX page has no placement of the section, there is no record: reads return nothing and writes are REJECTED (\"Index page does not have the common section!\"). Fix it by placing the section on the INDEX page (add_section_to_page with the INDEX page id — get it from list_editor_pages / get_page_by_type('INDEX')) and setting its props there; it then renders on the other pages too.",
+    "",
+    "## Building a whole page fast (placing + filling)",
+    "- add_sections_to_page(page_id, sections:[{component_id, index?, updates:[{prop_name,value}]}]) places MANY sections AND sets their props in ONE call, returning each new elementId. This is the fastest path — prefer it over add_section_to_page per section followed by separate fills. Built-but-unimported section/child components are auto-imported.",
+    "- For a single section: list_imported_sections (confirm imported; else import_section, after building) → add_section_to_page(component_id, page_id, index?) → then list_page_sections to get its elementId.",
+    "- REORDERING an already-placed section is a different tool: move_page_section(page_id, element_id, direction:'up'|'down' | to_index:<n>). The `index` on add_* only positions a NEW placement; it cannot move an existing one, and the editor UI exposes reordering solely as a drag, so this tool is the only way. Indices are 0-based over the placed sections in list_page_sections order; the result returns `resultIndex` + the full resulting `sections` order — assert on those. Header/footer (COMMON) sections cannot be reordered and are rejected.",
+    "",
+    "## Value shapes by prop type (what to pass as `value`)",
+    '- Scalars are WRAPPED: TEXT/RICH_TEXT { "value": "..." }, BOOLEAN { "value": true }, NUMBER { "value": 12 }, COLOR { "value": "#FF0000" }, ENUM { "value": "<key>" }, DATE { "value": ... }.',
+    '- SVG is value-wrapped: { "value": "<svg markup>" }. NUMBER_RANGE: { "value": <number>, "unit": "px"|null }.',
+    '- SVG naming: the editor shows each svg\'s `class` attribute as its display name in the list; add class="my-icon" to name it. SVG_LIST items with no class render as svg-1, svg-2, ….',
+    '- Object props are NOT wrapped (no { "value": ... }):',
+    '  - IMAGE: { "id": "<asset-id>", "altText"?: "...", "isVideo"?: false } — get the id from upload_image. Same shape at section level AND nested in a component list. IMAGE_LIST: { "images": [ <image>, ... ] }.',
+    '  - VIDEO: { "video": { "id": "<asset-id>" }, "thumbnailImage"?: { "id": "..." }, "autoplay"?: false, "controls"?: true, "loop"?: false, "muted"?: false } — NOT a bare { "id": ... }. SVG_LIST: { "svgs": [ "<svg>", ... ] }.',
+    '  - LINK: { "id": "<unique>", "linkType": "PAGE"|"EXTERNAL"|"FILE", "label": "...", "subLinks": [] } plus target — for a static page: pageId + pageType (from list_editor_pages); for EXTERNAL: externalLink. To link to a CATEGORY/BRAND/BLOG/BLOG_CATEGORY entity, do NOT guess a slug — get the entity id from list_categories/list_brands/list_blogs/list_blog_categories and the page id from get_page_by_type(\'<TYPE>\'), then build { id, linkType:\'PAGE\', label, pageId:<pageId>, pageType:\'<TYPE>\', itemId:<entityId>, subLinks:[] }. LIST_OF_LINK = { "links": [ <link>, ... ] }. Optional on any link (sub-links too): "translations": [ { "locale": "en", "label": "Home" } ] = its label on the other routings: a routing\'s own { "locale", "label", "sfRoutingId" }, else its language\'s { "locale", "label" }, else "label". Do NOT write them by hand: write the link with only its label changed using update_section_prop `locale` (every routing of that language) or `routing` (one routing) and it becomes that translation, the links still following the base; a link sent without "translations" keeps its stored ones (by its id), so new links can be added to a list without resending its labels; on a PRODUCT/CATEGORY/BRAND link with itemId, "useItemNameTranslations": true shows that item\'s own name in each language instead of "label".',
+    '  - 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.",
+    "",
+    "## Translations (other languages)",
+    "update_section_prop / update_page_sections write the base value; with `locale` they write one language's value of that placement only (a section reading differently per page in a language, a link list of its own in a language; a link's label written alone with `locale` or `routing` becomes its translation in that language or routing, without a copy). A section's texts in another language for every placement, the common and global texts, the editor texts (names, labels), the code components' UI texts (`i18n`) and the languages themselves are the translations page's: list_translations (start without an area: languages and progress) → list_translations with area/locale/item_id for the field keys → update_translations (a checked batch in one language) → manage_translation_languages to add a language (deleting one needs the user's OK).",
+].join("\n");
+server.tool("get_editor_workflow", "Read this FIRST when the user wants to place a section on a page or fill/edit a section's content (text, image, link, slides, component lists) in the live editor. Returns the complete step-by-step workflow for the live-editor tools (list_editor_pages, list_imported_sections, import_section, add_section_to_page, list_page_sections, update_section_prop, upload_image), the per-prop-type value shapes, the COMPONENT_LIST read-modify-write rules, how COMMON (global) header/footer sections keep one theme-wide set of values on the INDEX page (and how not to overwrite them), and how validation/auto-import behave. Use it to avoid the common mistake of writing component code to set a value a section already supports.", {}, async () => {
+    return {
+        content: [{ type: "text", text: EDITOR_WORKFLOW_GUIDE }],
+    };
+});
+// Tool: list_theme_globals
+server.tool("list_theme_globals", "List the theme's global settings from the connected editor: global variables (Theme Settings) and design tokens (colors, typography, breakpoints, keyframes, color schemes). Call this BEFORE generating sections/components so you reuse the theme's existing variables and tokens (read them in component code via `getThemeSetting`/`getThemeColors`/... from `@ikas/bp-storefront`). Includes items created manually in the editor UI. Requires `ikas theme dev` running with the editor connected. Two shape gotchas when consuming the result at runtime: (1) color schemes — `colorSchemes.schemes` holds only `{id,name}` slot LABELS; the actual colors live in `colorSchemes.values[].colorsByScheme` keyed by slot id, so iterate `values[].colorsByScheme` (iterating `schemes` renders empty). (2) An IMAGE setting's `value` is an image REFERENCE like `{id:'theme-images/<uuid>'}` with no `.url` — resolve it via `getDefaultSrc`/`getSrc`. (3) Each keyframe now includes its animation `settings` (type-dependent { property, value } entries — duration/iteration/timing/etc. for keyframe, transition for transition) and each point's resolved `styles`, so you can read back the full animation config, not just the `ref`. (4) Each typography entry may include `supportedFontWeights` — the exact numeric weights that text style's font actually ships (e.g. `[400]` for Modak); when present, only set `font_weight` to a value in this list (via `update_text_style`/`create_theme_global`), otherwise the write is rejected. If the field is absent the font's weight set couldn't be determined — fall back to 400 or rely on the validation error. Each typography entry also carries `isDefault` (true for the theme's default/global text style — the editor's \"Make Default Style\"); toggle it via `update_text_style`'s `is_default`. (5) Token NAMES are NOT unique — a theme can contain two tokens with the SAME name (e.g. colors pulled from two different design assets), so NEVER match a token by its human name. ALWAYS identify a token by its `id` (globally unique). IN COMPONENT CODE: prefer embedding the token's id-derived STABLE ref directly — color → cssVar `var(--<id>)`, typography → `className` `_<id>`, keyframe (animation-name) → `ref` `_<id>` — so you don't look anything up at runtime. If you DO need to pick a token out of a `getThemeColors()` / `getThemeTypography()` / `getThemeKeyframes()` / `getThemeColorSchemes()` array, match on `.id` (e.g. `getThemeColors().find(c => c.id === \"<id>\")`), NEVER on `.name`. EXCEPTION — global variables/settings: `getThemeSetting(name)` takes the token's `name`, but here `name` is the unique runtime key (`variableName`, the `_<id>` form returned in this list), which IS safe; do NOT pass a setting's human `displayName`. The update/delete tools also identify a token ONLY by `id` (they do NOT look up by name — on those tools `name` means the NEW name when renaming). Always take the `id` (or, for settings, the `name`/variableName) from THIS list. (6) GROUPING convention: a \"/\" in a token's NAME organizes it into a group in the editor UI — the text before the first \"/\" is the group, the rest is the item label. This applies to COLORS (e.g. \"Brand/Primary\"), TEXT STYLES (e.g. \"Heading/H1\"), and COLOR-SCHEME SLOTS (e.g. \"PrimaryButton/Background\"). When you create globals (via `create_theme_global`/`update_theme_color_scheme`), use \"/\"-prefixed names to keep related tokens grouped and tidy; reuse an existing group's exact prefix so they nest together. (7) ENUM settings: a setting with `type: \"ENUM\"` selects one option of a PROJECT enum and carries `enumTypeId` (the enum's id — the same one an ENUM prop declares as `enumTypeId`) and `options` (`{ label: value }`); its `value` is always one of those option VALUES (never a label), or null when unset. The response's top-level `enumTypes` array lists the project enums a new ENUM setting may select from (`{ id, name, options }`) — use an `id` from it as `enum_type_id` in `create_theme_global`. An ENUM prop can be bound (`bind_global`) only to an ENUM setting of the SAME enum.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project (where `node_modules/.bin/ikas-component` lives)."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, port }) => {
+    const args = [
+        "list-theme-globals",
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Shared text-style (typography) font-property schema — kept in lock-step with the editor's
+// "Update Text Style" modal fields (no color/text-align, since that modal doesn't expose them).
+// Each enum prop documents its accepted values so a bad value is caught with a clear error. Spread
+// into both create_theme_global (typography) and update_text_style so the two never drift apart.
+const textStyleFontParams = {
+    font_family: z
+        .string()
+        .optional()
+        .describe('A real font family the editor offers — a Google Fonts name with EXACT casing (e.g. "Inter", "Roboto", ' +
+        '"Poppins"), or a font already used by an existing text style in list_theme_globals. An unknown font ' +
+        "(or wrong casing) is rejected; do NOT invent a family name."),
+    font_size: z.string().optional(),
+    font_weight: z
+        .string()
+        .optional()
+        .describe("font-weight as a number (e.g. \"600\"); append 'i' for italic (e.g. \"600i\"). A PLAIN number with no 'i' " +
+        "is upright and REMOVES italic if the text style was italic (italic is carried by the weight — re-send the " +
+        "weight without 'i' to turn it off). Must be a weight the chosen " +
+        'font ships — if it isn\'t, the error lists the supported weights; when unsure use "400".'),
+    line_height: z.string().optional(),
+    letter_spacing: z.string().optional(),
+    text_decoration: z
+        .string()
+        .optional()
+        .describe("text-decoration: none | underline | line-through"),
+    text_transform: z
+        .string()
+        .optional()
+        .describe("text-transform: none | uppercase | lowercase | capitalize"),
+    text_overflow: z
+        .string()
+        .optional()
+        .describe("text-overflow: clip | ellipsis — ellipsis only truncates with white_space: nowrap and overflow: hidden in the component CSS"),
+    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,
+    };
+    // An empty string is passed through: with breakpoint_id it removes that override.
+    return Object.entries(map).flatMap(([flag, value]) => value != null ? [flag, value] : []);
+}
+// Per-breakpoint text-style overrides in one call. `.strict()` so a non-responsive property
+// (e.g. text_transform) is rejected instead of silently dropped.
+const textStyleBreakpointsParam = z
+    .array(z
+    .object({
+    breakpoint_id: z
+        .string()
+        .describe("Existing theme breakpoint id from `list_theme_globals`."),
+    font_size: z.string().optional(),
+    font_weight: z
+        .string()
+        .optional()
+        .describe('Plain number, e.g. "500" (the style\'s italic is kept).'),
+    line_height: z.string().optional(),
+    letter_spacing: z.string().optional(),
+})
+    .strict())
+    .optional()
+    .describe("RESPONSIVE overrides for several breakpoints in ONE call: [{ breakpoint_id, font_size?, font_weight?, " +
+    "line_height?, letter_spacing? }]. Only these 4 properties, each needs a desktop value (set in this same " +
+    'call or earlier), "" removes an override. Validated as a whole: one invalid entry rejects the call and ' +
+    "nothing is written. Breakpoints are not created here.");
+function textStyleBreakpointsArgs(breakpoints) {
+    if (!breakpoints)
+        return [];
+    const json = breakpoints.map((bp) => ({
+        breakpointId: bp.breakpoint_id,
+        fontSize: bp.font_size,
+        fontWeight: bp.font_weight,
+        lineHeight: bp.line_height,
+        letterSpacing: bp.letter_spacing,
+    }));
+    return ["--breakpoints", JSON.stringify(json)];
+}
+// Tool: create_theme_global
+server.tool("create_theme_global", "Create a theme global setting in the connected editor. `kind` selects what to create:\n" +
+    '- globalVariable: requires display_name + type (TEXT|RICH_TEXT|IMAGE|COLOR|NUMBER|BOOLEAN|BORDER|SHADOW|ENUM); value optional. Pass `value` as a REAL JSON value, never a stringified JSON. Value shapes — TEXT/COLOR: string; RICH_TEXT: HTML string; NUMBER: number; BOOLEAN: real JSON boolean true/false (NOT the string "true"); IMAGE: an image REFERENCE object { id: "theme-images/<uuid>" } (NOT { url }) — the id MUST come from a REAL upload: call `upload_image` (file_path or image_url) and use the id it returns, or reuse an id already listed by `list_theme_globals`. NEVER invent an id — it is stored as given and renders as a broken image, so if you have no image, omit `value` and let the merchant set it from the "Theme Settings" panel; BORDER: { width: { value, unit }, style, color } (width.value must be a number); SHADOW: { x, y, blur, spread, color, position: "outside"|"inside" }; ENUM: a setting that selects ONE option of a PROJECT enum — pass `enum_type_id` (an enum id from `list_theme_globals` → `enumTypes[]`; the same enum an ENUM prop declares as `enumTypeId`; built-in @ikas/* enums are REJECTED) and `value` = one of that enum\'s option VALUES (the strings in its `options`, e.g. "bottom"), NOT a label; omit `value` to leave it unset. Once created, an ENUM prop of the SAME enum can be bound to it with `update_section_prop` `bind_global`, and in component code `themeValue("_<id>")` from `./global-types` narrows to the enum\'s union type. For object types (IMAGE/BORDER/SHADOW) pass an actual JSON object, not a JSON-encoded string. Every value is validated server-side and a wrong shape is REJECTED, not silently stored.\n' +
+    '- color: requires name + value — a CONCRETE color (hex e.g. "#ff0000", rgb()/hsl() or a CSS color name). A color token cannot alias another color, so a "var(...)" reference is REJECTED here (to reuse another theme color, reference its cssVar in component code, or in a colorScheme slot). TIP: a "/" in the `name` GROUPS the color in the editor UI (e.g. "Brand/Primary", "Brand/Accent" appear under a "Brand" group); use this to organize related colors. To CHANGE an existing color later, use `update_theme_color` (edits in place, keeps the cssVar stable) — do NOT delete+recreate.\n' +
+    '- typography: requires name + at least one text-style property. These are exactly the fields the editor\'s "Update Text Style" modal exposes — nothing else (in particular there is NO color or text-align on a text style). VALUE FORMATS (all validated; a bad value is rejected with the offending value and the allowed set): font_weight is one of 100,200,300,400,500,600,700,800,900 (append \'i\' for italic, e.g. "600i") AND must be a weight the chosen font actually ships (many fonts provide only a subset, e.g. "Modak" only ships 400) — if unavailable the call fails and lists the supported weights, so when unsure use 400; stored as a numeric weight + a font-style entry; font_size is a number WITH a unit (e.g. "16px", "1.2rem", "80%"); line_height is "normal", a unitless number (e.g. "1.5") or a length; letter_spacing is "normal" or a length (e.g. "0.02em", "0.5px"); font_family is a real font the editor offers (a Google Fonts name with EXACT casing, e.g. "Inter") — an unknown/invented family is rejected; text_decoration is none|underline|line-through; text_transform is none|uppercase|lowercase|capitalize; text_overflow is clip|ellipsis; white_space is normal|pre|pre-wrap|pre-line|wrap|nowrap|collapse; line_break is auto|loose|normal|strict|anywhere; word_break is normal|break-all|keep-all; text_wrap_style is auto|balance|pretty|stable. TIP: a "/" in the `name` GROUPS the text style in the editor UI (e.g. "Heading/H1", "Heading/H2" appear under a "Heading" group); use this to organize related styles. Optional `breakpoints` sets responsive overrides in the same call (see the param). To CHANGE an existing text style later, use `update_text_style` (edits in place, keeps the `className` stable) — do NOT delete+recreate, which changes the id/className.\n' +
+    "- breakpoint: requires name + width (a positive INTEGER, in px — no decimals). To CHANGE an existing breakpoint later, use `update_theme_breakpoint` (edits in place, keeps the id).\n" +
+    "- keyframe: requires name + points (array of { point, styles? }) where each style is { property, value } using a CSS property name (opacity, transform, filter, background, color, …); keyframe_type defaults to \"keyframe\". Optional `settings` = animation-level config as { property, value } entries, TYPE-DEPENDENT: for keyframe — animation-duration, animation-iteration-count, animation-play-state, animation-delay, animation-timing-function, animation-direction, animation-fill-mode, animation-timeline, animation-range, transform-origin, backface-visibility; for transition — transition, backface-visibility. Setting these means the editor drives the animation timing (you don't have to hand-write `animation:` CSS). Use the keyframe's `ref` as the CSS animation-name. For a TRANSITION keyframe, put the target/hover-state styles on the 100% point (points[1].styles) — the 0% point is ignored (the start state is the element's own normal state). To CHANGE an existing keyframe later, use `update_theme_keyframe` (edits in place, keeps the `ref` stable) — do NOT delete+recreate, which changes the ref and breaks references.\n" +
+    '- colorScheme: requires name + colors (array of { slotId? | newSlotName?, value }) — each color targets ONE color SLOT, EITHER by `slotId` (an EXISTING slot\'s id, from `list_theme_globals` → colorSchemes.schemes[].id or a `colorsByScheme` key — the id-keyed path) OR by `newSlotName` (a name to CREATE-or-reuse a slot; write-only, for the standard vocabulary and brand-new slots). Pass EXACTLY ONE of the two per entry. `value` is EITHER a literal color (hex/rgb/hsl or a CSS color name, e.g. "#0b1120") OR a REFERENCE to an existing theme color, passed as that color\'s cssVar from `list_theme_globals` (e.g. "var(--<colorId>)"). A `var(--id)` value is stored as a linked reference (editing the global color updates the scheme too and the dependency is tracked) — do NOT inline a hex you copied from a global color; pass its cssVar. SLOT IDENTITY: `colorSchemes.schemes` lists each slot as `{id, name}`. To set a color on an EXISTING slot, find it there by name and pass its `slotId` (names are NOT unique — two design assets can each have a "Background" — so when ambiguous disambiguate via the scheme\'s existing `colorsByScheme` keys); use `newSlotName` only to add a slot the scheme does not have yet. When creating slots use the theme\'s STANDARD slot names so components resolve them: "Background", "Heading", "Text", "Link", "HoverLink", "Border", and per button "PrimaryButton/Background", "PrimaryButton/Text", "PrimaryButton/Border", "PrimaryButton/HoverBackground", "PrimaryButton/HoverText", "PrimaryButton/HoverBorder" (and the same six under "SecondaryButton/"); a "/" groups the slot in the editor UI. A scheme should normally define EVERY slot it uses; omitted slots fall back to the default scheme\'s color. A mistaken slot can be removed with `delete_theme_global` kind `colorSchemeSlot` (by slot id), or renamed in place (id stays stable) with `rename_theme_color_scheme_slot`. To CHANGE an existing scheme later, use `update_theme_color_scheme` (edits in place, keeps the className stable; merges colors by slot, and can set/clear its default flag via `is_default`).\n' +
+    "Read created items back with `list_theme_globals`. Requires `ikas theme dev` running with the editor connected.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    kind: z
+        .enum([
+        "globalVariable",
+        "color",
+        "typography",
+        "breakpoint",
+        "keyframe",
+        "colorScheme",
+    ])
+        .describe("What to create."),
+    name: z.string().optional().describe("Name (design tokens)."),
+    display_name: z
+        .string()
+        .optional()
+        .describe("Human label (globalVariable)."),
+    type: z.string().optional().describe("globalVariable value type."),
+    value: z
+        .any()
+        .optional()
+        .describe("globalVariable default value (shape depends on type — see tool description), or color hex string."),
+    enum_type_id: z
+        .string()
+        .optional()
+        .describe("globalVariable of type ENUM only: id of the project enum the setting selects from (from `list_theme_globals` → `enumTypes[]`). Required for ENUM, invalid for other types."),
+    ...textStyleFontParams,
+    breakpoints: textStyleBreakpointsParam.describe("typography only: " + textStyleBreakpointsParam.description),
+    width: z
+        .number()
+        .int()
+        .optional()
+        .describe("breakpoint width in px (positive integer, no decimals)."),
+    keyframe_type: z.enum(["keyframe", "transition"]).optional(),
+    points: z.any().optional().describe("keyframe points array."),
+    settings: z
+        .any()
+        .optional()
+        .describe("keyframe animation settings: array of { property, value } (type-dependent — see tool description)."),
+    colors: z
+        .any()
+        .optional()
+        .describe('colorScheme colors: array of { slotId? | newSlotName?, value } — target an EXISTING slot by `slotId` (its id from list_theme_globals → colorSchemes.schemes / colorsByScheme keys) OR create/reuse one by `newSlotName` (use the standard slot names, "/" to group, e.g. "PrimaryButton/Background"). Exactly one per entry. value = a literal color hex/rgb/hsl/name, OR an existing theme color\'s cssVar "var(--<colorId>)" to store a linked reference.'),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async (input) => {
+    const p = input.port ? ["--port", String(input.port)] : [];
+    let args;
+    switch (input.kind) {
+        case "globalVariable":
+            args = [
+                "create-global-variable",
+                "--display-name",
+                String(input.display_name ?? ""),
+                "--type",
+                String(input.type ?? ""),
+                ...(input.value !== undefined
+                    ? ["--value", JSON.stringify(input.value)]
+                    : []),
+                ...(input.enum_type_id
+                    ? ["--enum-type-id", String(input.enum_type_id)]
+                    : []),
+                ...p,
+            ];
+            break;
+        case "color":
+            args = [
+                "create-color",
+                "--name",
+                String(input.name ?? ""),
+                "--value",
+                String(input.value ?? ""),
+                ...p,
+            ];
+            break;
+        case "typography":
+            args = [
+                "create-text-style",
+                "--name",
+                String(input.name ?? ""),
+                ...textStyleFontArgs(input),
+                ...textStyleBreakpointsArgs(input.breakpoints),
+                ...p,
+            ];
+            break;
+        case "breakpoint":
+            args = [
+                "create-breakpoint",
+                "--name",
+                String(input.name ?? ""),
+                "--width",
+                String(input.width ?? ""),
+                ...p,
+            ];
+            break;
+        case "keyframe":
+            args = [
+                "create-keyframe",
+                "--name",
+                String(input.name ?? ""),
+                ...(input.keyframe_type ? ["--type", input.keyframe_type] : []),
+                "--points",
+                toJsonArrayArg(input.points),
+                ...(input.settings !== undefined
+                    ? ["--settings", toJsonArrayArg(input.settings)]
+                    : []),
+                ...p,
+            ];
+            break;
+        case "colorScheme":
+            args = [
+                "create-color-scheme",
+                "--name",
+                String(input.name ?? ""),
+                "--colors",
+                toJsonArrayArg(input.colors),
+                ...p,
+            ];
+            break;
+        default:
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error: unknown kind "${input.kind}"`,
+                    },
+                ],
+            };
+    }
+    return callEditorAction(input.project_root, args);
+});
+// Tool: update_theme_global
+server.tool("update_theme_global", "Update an existing global variable in the connected editor (e.g. fix its value or change its type). Identify it by `name` (the runtime key from `list_theme_globals`). Only the fields you pass are changed. Value shapes follow `create_theme_global` — pass `value` as REAL JSON (objects/booleans, never stringified); BOOLEAN is a real boolean, BORDER/SHADOW are real objects; IMAGE is an image REFERENCE object { id: \"theme-images/<uuid>\" } whose id MUST come from `upload_image` or an existing `list_theme_globals` entry — an invented id renders as a broken image; ENUM `value` is one of the enum's option VALUES (see the setting's `options` in `list_theme_globals`), and `enum_type_id` re-points the setting at another project enum. Changing `type` or `enum_type_id` of a global that props are bound to is REJECTED (the error names the places) — unbind those props first. Values are validated server-side; a wrong shape is REJECTED, not silently stored.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    name: z
+        .string()
+        .describe("The variable's runtime key (from `list_theme_globals`)."),
+    display_name: z.string().optional().describe("New label."),
+    type: z
+        .string()
+        .optional()
+        .describe("New value type (TEXT|RICH_TEXT|IMAGE|COLOR|NUMBER|BOOLEAN|BORDER|SHADOW|ENUM)."),
+    value: z
+        .any()
+        .optional()
+        .describe('New value as REAL JSON (shape depends on type; e.g. BOOLEAN: true/false, NUMBER: 12, IMAGE: { id: "theme-images/<uuid>" } from upload_image, ENUM: an option VALUE string — see create_theme_global). An invented IMAGE id renders as a broken image.'),
+    enum_type_id: z
+        .string()
+        .optional()
+        .describe('ENUM only: the project enum to select from (from `list_theme_globals` → `enumTypes[]`); may be passed alone to re-point an unbound ENUM global, or together with `type: "ENUM"`.'),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, name, display_name, type, value, enum_type_id, port, }) => {
+    const args = [
+        "update-global-variable",
+        "--name",
+        name,
+        ...(display_name !== undefined ? ["--display-name", display_name] : []),
+        ...(type !== undefined ? ["--type", type] : []),
+        ...(value !== undefined ? ["--value", JSON.stringify(value)] : []),
+        ...(enum_type_id !== undefined ? ["--enum-type-id", enum_type_id] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: update_theme_keyframe
+server.tool("update_theme_keyframe", "Update an existing theme keyframe IN PLACE in the connected editor. Prefer this over delete+recreate: " +
+    "it keeps the keyframe's id, so its runtime `ref` (the CSS animation-name `_<id>`) stays STABLE and every " +
+    "existing reference to it keeps working. Identify the keyframe by `id` (REQUIRED — globally unique, from " +
+    "`list_theme_globals`); name-based lookup is intentionally NOT supported here because names can collide across " +
+    "design assets. To rename, pass `name` (the new name) together with `id`. " +
+    "`points` REPLACES the keyframe's points: an array of { point, styles? } where `point` is a CSS " +
+    'keyframe offset (e.g. "0%", "50%", "100%") and each style is { property, value } using a CSS property ' +
+    "name (opacity, transform, filter, background, color, …). Pass `points` as REAL JSON (not a stringified array). " +
+    "For a TRANSITION keyframe, put the target/hover-state styles on the 100% point (points[1].styles) — the 0% " +
+    "point is ignored (the start state is the element's own normal state). " +
+    "Optional `settings` REPLACES the keyframe's animation settings (type-dependent { property, value } entries — " +
+    "see `create_theme_global`); OMIT it to keep the existing settings, or pass [] to clear them. " +
+    "Requires `ikas theme dev` running with the editor connected.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    id: z
+        .string()
+        .describe("Keyframe id (REQUIRED) from `list_theme_globals`. The token is always identified by id."),
+    name: z
+        .string()
+        .optional()
+        .describe("Optional NEW name to rename the keyframe to. NOT used to find the token — lookup is always by id."),
+    keyframe_type: z
+        .enum(["keyframe", "transition"])
+        .optional()
+        .describe("Optional new keyframe type."),
+    points: z
+        .any()
+        .describe("New keyframe points array of { point, styles? } — REPLACES the existing points."),
+    settings: z
+        .any()
+        .optional()
+        .describe("New animation settings { property, value } array (type-dependent — see create_theme_global). Omit to keep existing; [] to clear."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, id, name, keyframe_type, points, settings, port }) => {
+    const args = [
+        "update-keyframe",
+        "--id",
+        id,
+        ...(name !== undefined ? ["--name", name] : []),
+        ...(keyframe_type ? ["--type", keyframe_type] : []),
+        "--points",
+        toJsonArrayArg(points),
+        ...(settings !== undefined
+            ? ["--settings", toJsonArrayArg(settings)]
+            : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: update_text_style
+server.tool("update_text_style", "Update an existing theme typography token (text style) IN PLACE in the connected editor. Prefer this over " +
+    "delete+recreate: it keeps the text style's id, so its `className` (`_<id>`) — and every section bound to it — " +
+    "stays STABLE. Identify the text style by `id` (REQUIRED — globally unique, from `list_theme_globals`); " +
+    "name-based lookup is intentionally NOT supported here because names can collide across design assets. " +
+    "To rename, pass `name` (the new name) together with `id`. Pass only the properties you want to change; omitted " +
+    'ones keep their existing values. The settable properties are exactly the editor\'s "Update Text Style" modal ' +
+    "fields — there is NO color or text-align on a text style. VALUE FORMATS (all validated; a bad value is rejected " +
+    "with the offending value and the allowed set): font_weight is one of 100…900 (append 'i' for italic, e.g. " +
+    '"600i") AND must be a weight the chosen font actually ships — many fonts only provide a subset (e.g. "Modak" ' +
+    "only ships 400); if a weight isn't available the call fails and the error lists the supported weights, so when " +
+    'unsure use 400; font_size is a number with a unit (e.g. "16px"); line_height is "normal", a unitless number ' +
+    'or a length; letter_spacing is "normal" or a length (e.g. "0.02em"); font_family is a real font the editor ' +
+    'offers (a Google Fonts name with EXACT casing, e.g. "Inter") — an unknown/invented family is rejected; ' +
+    "text_decoration is none|underline|" +
+    "line-through; text_transform is none|uppercase|lowercase|capitalize; text_overflow is clip|ellipsis (ellipsis also needs white_space: nowrap here and overflow: hidden in the component CSS); 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`). " +
+    "RESPONSIVE: pass `breakpoint_id` (an existing breakpoint id from `list_theme_globals`) to set that breakpoint's " +
+    "overrides instead of the desktop values. Then ONLY font_size, font_weight, line_height and letter_spacing are " +
+    "allowed, each needs a desktop value on the style first, font_weight is a plain number (the style's italic is kept — italic is " +
+    'shared by all breakpoints) and an empty string ("") removes that override so the value is inherited again. Overrides cascade ' +
+    "desktop-first and chained: a property a breakpoint does not override comes from the nearest WIDER breakpoint that overrides it, else desktop; `list_theme_globals` returns them per typography " +
+    "entry under `breakpoints` (`overrides` = own values, `resolved` = effective values). Breakpoints are NOT created " +
+    "by this tool. To write SEVERAL breakpoints (optionally together with desktop values) in one call, use " +
+    "`breakpoints` instead of `breakpoint_id`. Requires " +
+    "`ikas theme dev` running with the editor connected.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    id: z
+        .string()
+        .describe("Text style id (REQUIRED) from `list_theme_globals`. The token is always identified by id."),
+    name: z
+        .string()
+        .optional()
+        .describe("Optional NEW name to rename the text style to. NOT used to find the token — lookup is always by id."),
+    ...textStyleFontParams,
+    is_default: z
+        .boolean()
+        .optional()
+        .describe("true → make this the theme's default/global text style (clears any other default); false → remove the " +
+        "default flag. Omit to leave the default state unchanged."),
+    breakpoint_id: z
+        .string()
+        .optional()
+        .describe("Existing theme breakpoint id from `list_theme_globals`. When set, the font params are written as that " +
+        'breakpoint\'s overrides (font_size/font_weight/line_height/letter_spacing only; "" removes one).'),
+    breakpoints: textStyleBreakpointsParam,
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async (input) => {
+    const { project_root, id, name, is_default, breakpoint_id, breakpoints, port, } = input;
+    const args = [
+        "update-text-style",
+        "--id",
+        id,
+        ...(breakpoint_id !== undefined ? ["--breakpoint", breakpoint_id] : []),
+        ...(name !== undefined ? ["--name", name] : []),
+        ...textStyleFontArgs(input),
+        ...textStyleBreakpointsArgs(breakpoints),
+        ...(is_default === true
+            ? ["--default"]
+            : is_default === false
+                ? ["--no-default"]
+                : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: update_theme_color
+server.tool("update_theme_color", "Update an existing theme color token IN PLACE in the connected editor. Prefer this over delete+recreate: " +
+    "it keeps the color's id, so its cssVar (`var(--<id>)`) — and every element style bound to it — stays STABLE. " +
+    "Identify it by `id` (REQUIRED — globally unique, from `list_theme_globals`); name-based lookup is intentionally " +
+    "NOT supported here because a theme can have two colors with the same name (e.g. from two different design assets). " +
+    "To rename, pass `name` (the new name) together with `id`. Pass `value` to change the color — a CONCRETE " +
+    'color (hex/rgb/hsl or a CSS color name), NOT a "var(...)" reference (a color token can\'t alias another ' +
+    "color); omit it to only rename. Requires `ikas-component " +
+    "dev` running with the editor connected.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    id: z
+        .string()
+        .describe("Color id (REQUIRED) from `list_theme_globals`. The token is always identified by id."),
+    name: z
+        .string()
+        .optional()
+        .describe("Optional NEW name to rename the color to. NOT used to find the token — lookup is always by id."),
+    value: z
+        .string()
+        .optional()
+        .describe('New color value — a concrete color (e.g. "#ff0000", rgb/hsl/name), not a "var(...)" reference. Omit to only rename.'),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, id, name, value, port }) => {
+    const args = [
+        "update-color",
+        "--id",
+        id,
+        ...(name !== undefined ? ["--name", name] : []),
+        ...(value !== undefined ? ["--value", value] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: update_theme_breakpoint
+server.tool("update_theme_breakpoint", "Update an existing theme breakpoint IN PLACE in the connected editor (keeps its id). Identify it by `id` " +
+    "(REQUIRED — globally unique, from `list_theme_globals`); name-based lookup is intentionally NOT supported here " +
+    "because names can collide across design assets. To rename, pass `name` (the new name) together with `id`. " +
+    "Pass `width` (px) to change it; omit it to only rename. " +
+    "Requires `ikas theme dev` running with the editor connected.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    id: z
+        .string()
+        .describe("Breakpoint id (REQUIRED) from `list_theme_globals`. The token is always identified by id."),
+    name: z
+        .string()
+        .optional()
+        .describe("Optional NEW name to rename the breakpoint to. NOT used to find the token — lookup is always by id."),
+    width: z
+        .number()
+        .int()
+        .optional()
+        .describe("New breakpoint width in px (positive integer, no decimals). Omit to only rename."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, id, name, width, port }) => {
+    const args = [
+        "update-breakpoint",
+        "--id",
+        id,
+        ...(name !== undefined ? ["--name", name] : []),
+        ...(width !== undefined ? ["--width", String(width)] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: update_theme_color_scheme
+server.tool("update_theme_color_scheme", "Update an existing theme color scheme (palette) IN PLACE in the connected editor. Prefer this over " +
+    "delete+recreate: it keeps the scheme's id, so its className (`_<id>`) stays STABLE. Identify it by `id` " +
+    "(REQUIRED — globally unique, from `list_theme_globals`); name-based lookup is intentionally NOT supported here " +
+    "because names can collide across design assets. To rename, pass `name` (the new name) together with `id`. " +
+    "`colors` is an array of { slotId? | newSlotName?, value } — each entry targets ONE slot, EITHER by " +
+    "`slotId` (an EXISTING slot's id, from list_theme_globals colorsByScheme keys / colorSchemes.schemes — the " +
+    "id-keyed path; slot names ARE listed in colorSchemes.schemes but are not unique, so prefer the scheme's colorsByScheme keys to get the right id) OR by `newSlotName` (create/reuse " +
+    'a slot by name; use the standard slot names, "/" to group, e.g. "PrimaryButton/Background"); value = a ' +
+    'literal color hex/rgb/hsl/name, OR an existing theme color\'s cssVar "var(--<colorId>)" from ' +
+    "list_theme_globals to store it as a LINKED reference — pass the cssVar, not a hex copied from a global color) " +
+    "and MERGES by slot — only the slots you pass change. Pass `colors` as REAL " +
+    "JSON (not a stringified array). Set `is_default: true` to make this the theme's DEFAULT scheme (the " +
+    "fallback whose colors fill any slot a non-default scheme leaves unset); this is exclusive — the editor " +
+    "automatically clears the default flag from any other scheme in the same group, so there is always exactly " +
+    "one default. Set `is_default: false` to remove the default flag from this scheme. Omit all of name/colors/" +
+    "is_default to no-op. Requires `ikas theme dev` running with the editor connected.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    id: z
+        .string()
+        .describe("Color scheme id (REQUIRED) from `list_theme_globals`. The token is always identified by id."),
+    name: z
+        .string()
+        .optional()
+        .describe("Optional NEW name to rename the color scheme to. NOT used to find the token — lookup is always by id."),
+    colors: z
+        .any()
+        .optional()
+        .describe('Array of { slotId? | newSlotName?, value } to set — target an existing slot by `slotId` (from list_theme_globals colorsByScheme keys / colorSchemes.schemes) or create/reuse by `newSlotName`; value = a literal color hex/rgb/hsl/name, OR an existing theme color\'s cssVar "var(--<colorId>)" (linked reference). Merges by slot. Omit to only rename.'),
+    is_default: z
+        .boolean()
+        .optional()
+        .describe("true = make this the default scheme (exclusive — the editor clears the default flag from every other scheme in its group); false = remove the default flag. Omit to leave the default unchanged. The result echoes the persisted `isDefault`."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, id, name, colors, is_default, port }) => {
+    const args = [
+        "update-color-scheme",
+        "--id",
+        id,
+        ...(name !== undefined ? ["--name", name] : []),
+        ...(colors !== undefined ? ["--colors", toJsonArrayArg(colors)] : []),
+        ...(is_default === true
+            ? ["--default"]
+            : is_default === false
+                ? ["--no-default"]
+                : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: rename_theme_color_scheme_slot
+server.tool("rename_theme_color_scheme_slot", 'Rename a color scheme SLOT (a scheme key like "Background" or "PrimaryButton/Text") IN PLACE in the ' +
+    "connected editor. A slot's id is STABLE, so renaming keeps every runtime reference intact " +
+    "(`var(--<slotId>)` in CSS, `colorsByScheme[slotId]` in component code) — only the human display name " +
+    "changes; nothing rebinds. Identify the slot by `id` (REQUIRED — the slot id from `list_theme_globals` → " +
+    "colorSchemes.schemes[].id or a `colorsByScheme` key); name-based lookup is intentionally NOT supported " +
+    'because slot names can collide across design assets. `name` is the NEW slot name (a "/" groups it in the ' +
+    'editor UI, e.g. "PrimaryButton/Background"). Only non-design-asset (user/theme) slots can be renamed here. ' +
+    "This renames the slot itself across ALL schemes that use it (a slot is shared) — it does NOT rename a single " +
+    "scheme/palette (for that use `update_theme_color_scheme`). Requires `ikas theme dev` running with the " +
+    "editor connected.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    id: z
+        .string()
+        .min(1, "id is REQUIRED — the slot id from list_theme_globals (colorSchemes.schemes[].id / colorsByScheme keys).")
+        .describe("Slot id (REQUIRED) from `list_theme_globals` → colorSchemes.schemes[].id / colorsByScheme keys. The slot is always identified by id."),
+    name: z
+        .string()
+        .min(1, "name is REQUIRED — the new slot name (non-empty).")
+        .describe('The NEW slot name (non-empty). A "/" groups it in the editor UI (e.g. "PrimaryButton/Background").'),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, id, name, port }) => {
+    const args = [
+        "rename-color-scheme-slot",
+        "--id",
+        id,
+        "--name",
+        name,
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: delete_theme_global
+server.tool("delete_theme_global", 'Delete a theme global setting from the connected editor. For `kind: globalVariable` pass `name` (the runtime key); for design-token kinds (color | typography | breakpoint | keyframe | colorScheme) pass the token `id`. For `kind: colorSchemeSlot` pass the color SLOT id (from `list_theme_globals` → colorSchemes.schemes[].id or a `colorsByScheme` key) — this deletes the slot itself across ALL schemes (use it to clean up a junk slot created by a typo); it CASCADES: the slot\'s color is removed from every scheme and any element/component style bound to that slot is cleared, so only delete a slot you are sure is unused. Only non-design-asset (user/theme) slots can be deleted here. Get names/ids from `list_theme_globals`. Deleting a non-existent id fails with a "not found" error (it does NOT report a false success), so a success result means the token really existed and was removed.', {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    kind: z
+        .enum([
+        "globalVariable",
+        "color",
+        "typography",
+        "breakpoint",
+        "keyframe",
+        "colorScheme",
+        "colorSchemeSlot",
+    ])
+        .describe("What to delete."),
+    name: z
+        .string()
+        .optional()
+        .describe("globalVariable runtime key (from `list_theme_globals`)."),
+    id: z
+        .string()
+        .optional()
+        .describe("design-token id, or for colorSchemeSlot the slot id from `list_theme_globals` → colorSchemes.schemes."),
+    confirm: z.boolean().describe(CONFIRM_PARAM_DESCRIPTION),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, kind, name, id, confirm, port }) => {
+    if (confirm !== true)
+        return destructiveConfirmRefusal();
+    const p = [...(port ? ["--port", String(port)] : []), "--yes"];
+    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 ---
+/**
+ * Every tool's arguments are checked strictly: an unknown argument (a typo, an invented field) is an error the
+ * agent sees, not one dropped in silence while the call goes on without it.
+ */
+function makeToolArgumentsStrict() {
+    // The SDK builds a lenient object from each tool's fields; the same fields make the strict one (nested
+    // objects are declared with `z.strictObject`).
+    const tools = server._registeredTools;
+    for (const tool of Object.values(tools)) {
+        const shape = tool.inputSchema?.shape ?? tool.inputSchema?._zod?.def?.shape;
+        if (shape)
+            tool.inputSchema = z.strictObject(shape);
+    }
+}
 async function main() {
+    makeToolArgumentsStrict();
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }