@ikas/code-components-mcp 1.4.0-beta.21 → 1.4.0-beta.212

package/dist/index.js

@@ -1589,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) {
@@ -1657,6 +1690,73 @@ 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) => {
@@ -1719,13 +1819,31 @@ function searchTypes(query) {
         const enumScore = td.enumValues?.some((v) => matchScore(v, query) > 0)
             ? 4
             : 0;
-        return { td, score: nameScore + domainScore + propScore + enumScore };
+        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}`);
@@ -1752,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(", ")}`);
@@ -1773,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};`);
             }
         }
@@ -1828,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}`;
@@ -1838,12 +1971,15 @@ const server = new McpServer({
     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.\n\n" +
-        "Live-editor actions (require `ikas-component dev` running with the editor connected): `list_editor_pages` → page ids; `list_imported_sections` → imported component ids; `import_section` → import a built component; `add_section_to_page` → place a section on a page; `list_page_sections` → the sections already placed on a page, each with its per-placement `elementId`, current `propValues`, and blueprint `props`; `update_section_prop` → change a single prop value of a placed section; `upload_image` → upload an image (file or URL) and get an image id to use in an IMAGE prop value.\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.",
+        "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 }) => {
@@ -1863,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.");
@@ -1879,7 +2015,7 @@ 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.");
@@ -2109,7 +2245,7 @@ server.tool("get_code_example", "Get an API usage reference for a specific task.
         }
     }
     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("");
@@ -2157,6 +2293,13 @@ server.tool("get_framework_guide", "Get a framework guide on a specific topic (e
         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
@@ -2227,7 +2370,7 @@ 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.", {
+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')"),
@@ -2623,7 +2766,7 @@ 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. 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 () => {
+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 {
@@ -2645,6 +2788,23 @@ server.tool("get_prop_types", "Get all available ikas.config.json prop types wit
     };
 });
 // 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
@@ -2729,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`,
         "",
     ];
@@ -3095,7 +3258,10 @@ 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") }] };
@@ -3476,7 +3642,12 @@ 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
@@ -3494,22 +3665,58 @@ function parseCliJson(stdout) {
     const trimmed = stdout.trim();
     if (!trimmed)
         return null;
-    // CLI prints exactly one JSON object on stdout; if multiple lines appeared
-    // (e.g., warnings on stderr leaked), take the last non-empty line.
-    const last = trimmed
-        .split("\n")
-        .map((l) => l.trim())
-        .filter(Boolean)
-        .pop();
-    if (!last)
-        return null;
+    // Fast path: the CLI prints exactly one JSON object on stdout.
     try {
-        return JSON.parse(last);
+        return JSON.parse(trimmed);
     }
     catch {
+        // Fallback: if anything leaked onto stdout before/after the JSON, scan the
+        // lines and return the last one that parses as JSON.
+        const lines = trimmed
+            .split("\n")
+            .map((l) => l.trim())
+            .filter(Boolean);
+        for (let i = lines.length - 1; i >= 0; i--) {
+            try {
+                return JSON.parse(lines[i]);
+            }
+            catch {
+                // keep scanning
+            }
+        }
         return null;
     }
 }
+// Coerce a JSON-ARRAY argument (points / settings / colors) into the single JSON-array string the
+// CLI expects. Agents sometimes send these PRE-STRINGIFIED (a JSON string instead of a real array);
+// a blind JSON.stringify would then double-encode it ("[...]" -> "\"[...]\"") and the CLI rejects it
+// with "must be a JSON array". So pass a string through as-is (the CLI parses + validates it) and
+// only stringify real arrays/values. NOTE: only for array args — a scalar `value` arg must NOT use
+// this (a plain string there is a literal value, not stringified JSON).
+function toJsonArrayArg(value) {
+    return typeof value === "string" ? value : JSON.stringify(value ?? []);
+}
+/**
+ * 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);
@@ -3544,7 +3751,7 @@ 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`.", {
+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)."),
@@ -3557,7 +3764,7 @@ server.tool("list_editor_pages", "List pages in the connected editor's project.
     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`.", {
+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."),
@@ -3595,13 +3802,13 @@ server.tool("import_section", "Import a built section-type code component into t
     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. After placing, change the section\'s prop values with `update_section_prop` (use `list_page_sections` to get the placement\'s `elementId` and prop names).', {
+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)."),
+        .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()
@@ -3625,28 +3832,194 @@ server.tool("add_section_to_page", 'Place an already-imported section-type code
     ];
     return callEditorAction(project_root, args);
 });
+// Tool: add_sections_to_page
+server.tool("add_sections_to_page", "Place MANY sections on a page in a SINGLE call — and optionally set each section's prop values AT placement time, so you skip the separate fill step. The fastest way to build a page: one round-trip instead of one add (and one fill) per section. Pass `sections`, each `{ component_id, index?, updates?: [{ prop_name|prop_id, value }] }`; values use the same per-type shapes as update_section_prop / get_editor_workflow. Returns the new `elementId` for each placement (plus written prop results). Built-but-unimported section AND child code components are auto-imported. All update values are validated before anything is placed. Use `list_editor_pages` for page ids and `list_imported_sections` for component ids. Placing a COMMON (global) section — the theme's header/footer — is special: it has ONE shared set of prop values stored on the INDEX (Home) page's placement, so `updates` land there and change that section on every page (the result carries a `common` block), and placing it with `updates` on a non-INDEX page while the INDEX page does not have it is rejected — place and fill it on the INDEX page instead.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    page_id: z.string().describe("Target page id (from `list_editor_pages`)."),
+    sections: z
+        .array(z.object({
+        component_id: z
+            .string()
+            .describe("Imported (or built) section-type code component id."),
+        index: z
+            .number()
+            .int()
+            .nonnegative()
+            .optional()
+            .describe("Zero-based insertion index; appends when omitted."),
+        updates: z
+            .array(z.object({
+            prop_id: z
+                .string()
+                .optional()
+                .describe("Blueprint prop id (provide this or prop_name)."),
+            prop_name: z
+                .string()
+                .optional()
+                .describe("Blueprint prop name (alternative to prop_id)."),
+            value: z
+                .any()
+                .describe("Prop value, same shape update_section_prop expects for that type."),
+        }))
+            .optional()
+            .describe("Optional prop values to set on this section right after placing it."),
+    }))
+        .describe("Non-empty array of sections to place (in order), each with its componentId and optional prop updates."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, page_id, sections, port }) => {
+    const normalized = (sections || []).map((s) => ({
+        componentId: s.component_id,
+        ...(typeof s.index === "number" ? { index: s.index } : {}),
+        ...(s.updates
+            ? {
+                updates: s.updates.map((u) => ({
+                    ...(u.prop_id ? { propId: u.prop_id } : {}),
+                    ...(u.prop_name ? { propName: u.prop_name } : {}),
+                    value: u.value,
+                })),
+            }
+            : {}),
+    }));
+    const args = [
+        "add-sections-to-page",
+        "--page-id",
+        page_id,
+        "--sections",
+        JSON.stringify(normalized),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
 // Tool: list_page_sections
-server.tool("list_page_sections", "List the sections placed on a page. Each entry includes the per-placement `elementId` (the identity of THIS placement — there can be multiple placements of the same section), `sectionId`, `componentId`, `name`, the current `propValues`, and the blueprint `props` (each with `id`, `name`, `type`). Use the returned `elementId` plus a prop `id`/`name` with `update_section_prop` to change a prop value of that specific placement. Use `list_editor_pages` to discover page ids.", {
+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, port }) => {
+}, 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`."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, page_id, element_ids, port }) => {
+    const args = [
+        "get-section-values",
+        "--page-id",
+        page_id,
+        "--element-ids",
+        (element_ids || []).join(","),
         ...(port ? ["--port", String(port)] : []),
     ];
     return callEditorAction(project_root, args);
 });
 // Tool: update_section_prop
-server.tool("update_section_prop", 'Change a single prop value of a section placed on a page. This is the tool for FILLING/SETTING content (heading, text, image, link, etc.) on an existing section — it is pure data entry: it writes NO component code and needs NO rebuild. Do not author a new prop or component to set a value the section already supports; first check the section\'s existing `props` via `list_page_sections`. Target the specific placement by its `element_id` (from `list_page_sections`) and the prop by `prop_id` or `prop_name` (also from `list_page_sections`). `value` is the prop value object as stored by the editor — for scalar props it is wrapped as `{ "value": <scalar> }` (e.g. `{ "value": "Hello" }` for TEXT, `{ "value": true }` for BOOLEAN, `{ "value": 12 }` for NUMBER, `{ "value": "#FF0000" }` for COLOR, `{ "value": "<enum-key>" }` for ENUM). Richer object prop types use their own object shape and are NOT `{ "value": ... }`-wrapped: IMAGE/VIDEO/SVG = `{ "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`); 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": [] }`. LIST_OF_LINK = `{ "links": [ <link>, ... ] }` (each item is a link object as above). PRODUCT = `{ "productId": "...", "variantId"?: "..." }`. This SAME unwrapped shape applies whether the prop sits at section level OR nested inside a COMPONENT_LIST entry\'s `propValues` — there is no section-vs-nested difference. IMPORTANT: pass `value` as the parsed JSON object/array itself, NEVER as a JSON string (a stringified value is double-encoded and stored as a useless string). Values are validated server-side: a wrong shape (e.g. `{ "value": [...] }` for a COMPONENT_LIST, a `{ "value": ... }`-wrapped IMAGE, `componentId`+`props` instead of `codeComponentId`+`propValues`, or a missing entry `id`) is now REJECTED with an explanatory error instead of being silently stored. For any prop type you are unsure about, inspect the existing entry in `list_page_sections` `propValues` and match its exact shape. The change is applied with undo support.\n\n' +
-    'COMPONENT_LIST / COMPONENT props: the value is NOT wrapped in `{ "value": ... }`. A COMPONENT_LIST value is `{ "components": [ <entry>, ... ] }`; a single COMPONENT value is one `<entry>`. Each entry = `{ "id": "<unique-id>", "codeComponentId": "<child-id>" | "componentId": "<child-id>", "propValues": { "<childPropName>": <wrapped-value>, ... } }`. Rules: (1) `id` is a unique short alphanumeric string identifying THIS entry — generate a fresh one per new entry and NEVER reuse an existing entry\'s id. (2) Use `codeComponentId` for code components, `componentId` for built-in theme components. (3) `propValues` is keyed by the CHILD component\'s prop NAMES, each using the same scalar wrappers as above (nesting is recursive — a child may itself hold a COMPONENT_LIST). (4) `update_section_prop` REPLACES the whole prop value — there is NO partial/deep merge. ALWAYS send the COMPLETE, fully-nested value for the prop: every existing entry (with its id), every nested `propValues`, and every nested COMPONENT_LIST at every depth. To change anything (even one deeply-nested scalar, or to add/remove/reorder a child), READ-MODIFY-WRITE: take the current `{ "components": [...] }` from `list_page_sections`, 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; the allowed set is the blueprint prop\'s `filteredComponentIds`, which for container sections (Header, Footer, ProductDetail, …) is wired at build/config time per the `get_section_template` setup recipe (`config update-prop`), not here.\n\n' +
+server.tool("update_section_prop", 'Change a single prop value of a section placed on a page. This is the tool for FILLING/SETTING content (heading, text, image, link, etc.) on an existing section — it is pure data entry: it writes NO component code and needs NO rebuild. Do not author a new prop or component to set a value the section already supports; first check the section\'s existing `props` via `list_page_sections`. Target the specific placement by its `element_id` (from `list_page_sections`) and the prop by `prop_id` or `prop_name` (also from `list_page_sections`). `value` is the prop value object as stored by the editor — for scalar props it is wrapped as `{ "value": <scalar> }` (e.g. `{ "value": "Hello" }` for TEXT, `{ "value": true }` for BOOLEAN, `{ "value": 12 }` for NUMBER, `{ "value": "#FF0000" }` for COLOR, `{ "value": "<enum-key>" }` for ENUM). A COLOR prop can ALSO bind to a global theme color instead of a literal hex — pass `{ "patternValueId": "<id>" }` (the color id from `list_theme_globals` → `colors[].id`) and the prop tracks that global color live (resolved to `var(--<id>)` at render); the id is validated and an unknown one is REJECTED. Richer object prop types use their own object shape and are NOT `{ "value": ... }`-wrapped (full catalog in `get_editor_workflow`): IMAGE = `{ "id": "<asset-id>", "altText"?: "<alt>", "isVideo"?: false }` (the `id` MUST reference an already-uploaded asset — call `upload_image` with a `file_path`/`image_url` to get one, or reuse an existing `id` from another section\'s `propValues`); IMAGE_LIST = `{ "images": [ <image>, ... ] }`; VIDEO = `{ "video": { "id": "<asset-id>" }, "thumbnailImage"?: { "id": "..." }, "autoplay"?: false, "controls"?: true, "loop"?: false, "muted"?: false }` (NOT a bare `{ "id": ... }`); SVG = `{ "value": "<svg markup>" }` (value-wrapped, like a scalar); SVG_LIST = `{ "svgs": [ "<svg>", ... ] }`; TYPE (style props such as BorderRadiusStyleType/PaddingStyleType/GapStyleType) = the type-shaped object ITSELF, e.g. `{ "value": 8, "unit": "px" }` — get the exact field structure from the prop\'s `writeExample`/`typeName` in `get_component_props` or `get_type_definition("<typeName>")`; unknown fields, wrong field types, and invalid union values (e.g. `"unit": "banana"`) are REJECTED; entity props PRODUCT/CATEGORY/BRAND/BLOG/BLOG_CATEGORY/RAFFLE = `{ "<entity>Id": "...", "usePageData"?: false }` (e.g. `{ "categoryId": "..." }`) — get real ids from `search_products` (PRODUCT), `list_categories`, `list_brands`, `list_blogs`, `list_blog_categories`; PRODUCT_ATTRIBUTE = `{ "productId": "...", "variantId": "...", "attributeId": "..." }` — `variantId` is REQUIRED alongside `productId` (without it the value resolves with `product: null` and the component renders nothing), or bind to the page product with `{ "attributeId": "...", "usePageData": true }` on a product detail page; PRODUCT_ATTRIBUTE_LIST = the same with `"attributeIds": [ "..." ]`, and note the component receives a SINGLE wrapper object, never an array (read both with `getAttributeDetailValues()` / `getAttributeListValues()` — see `get_framework_guide("prop-types")`); list/collection props are typed objects keyed by a `<entity>ListType` discriminator: PRODUCT_LIST = `{ "id": "<unique>", "productListType": "STATIC", "productIds": [ { "productId": "...", "variantId": "..." } ], "initialLimit"?: 12 }` — note productIds is an array of {productId, variantId} PAIRS (from search_products), not bare ids; productListType ∈ ALL|STATIC|DISCOUNTED|RECOMMENDED|CATEGORY|SEARCH|LAST_VIEWED|RELATED_PRODUCTS|VIEWED_TOGETHER|PURCHASED_TOGETHER, and for a dynamic type use e.g. `{ "id": "<unique>", "productListType": "CATEGORY", "category": "<id from list_categories>" }` (the field is `category`, NOT `categoryId` — `categoryId` is only the standalone CATEGORY entity prop; no productIds here) or `"ALL"` (no ids). Unknown sub-fields inside a PRODUCT_LIST (e.g. `categoryId`) are REJECTED, not silently stored. CATEGORY_LIST = `{ "categoryListType": "STATIC", "categoryIds": ["..."] }` or `{ "categoryListType": "ALL" }`. BRAND_LIST = `{ "brandListType": "STATIC", "brandIds": ["..."] }` or ALL. BLOG_LIST = `{ "blogListType": "STATIC", "blogIds": ["..."] }`, `{ "blogListType": "CATEGORY", "categoryId": "..." }`, or ALL. BLOG_CATEGORY_LIST = `{ "blogCategoryListType": "STATIC", "blogCategoryIds": ["..."] }` or ALL. (Get the entity ids from search_products / list_*; you can also read an existing value with `get_section_values` to copy its exact shape.) LINK = a single link object `{ "id": "<unique-short-id>", "linkType": "PAGE"|"EXTERNAL"|"FILE", "label": "...", "openInNewTab"?: false, "subLinks": [] }` plus the target for its type — for PAGE add `"pageId"` AND `"pageType"` (both from `list_editor_pages`, e.g. pageType "INDEX"; for dynamic page types like PRODUCT/CATEGORY/BLOG also add the target `"itemId"`), for EXTERNAL add `"externalLink": "https://..."`. Examples: PAGE → `{ "id": "k3p9x", "linkType": "PAGE", "label": "Home", "pageId": "<page-id>", "pageType": "INDEX", "openInNewTab": false, "subLinks": [] }`; EXTERNAL → `{ "id": "m7q2z", "linkType": "EXTERNAL", "label": "Docs", "externalLink": "https://example.com", "openInNewTab": true, "subLinks": [] }`. To link to an ENTITY (category/brand/blog/blog-category) do NOT guess a slug — get the entity id from `list_categories`/`list_brands`/`list_blogs`/`list_blog_categories` and the page id from `get_page_by_type("<TYPE>")`, then build `{ "id": "<unique>", "linkType": "PAGE", "label": "...", "pageId": <pageId>, "pageType": "<TYPE>", "itemId": <entityId>, "subLinks": [] }`. LIST_OF_LINK = `{ "links": [ <link>, ... ] }` (each item is a link object as above). PRODUCT = `{ "productId": "...", "variantId"?: "..." }`. This SAME unwrapped shape applies whether the prop sits at section level OR nested inside a COMPONENT_LIST entry\'s `propValues` — there is no section-vs-nested difference. IMPORTANT: pass `value` as the parsed JSON object/array itself, NEVER as a JSON string (a stringified value is double-encoded and stored as a useless string). Values are validated server-side (deeply, including nested COMPONENT_LIST children): wrong shapes AND wrong semantics are REJECTED with an explanatory error instead of being silently stored. This includes: a `{ "value": [...] }` wrapper for a COMPONENT_LIST; a `{ "value": ... }`-wrapped IMAGE; `props` instead of `propValues`; a missing/duplicate entry `id`; a child referenced by the wrong key (a code component MUST use `codeComponentId`, a theme component `componentId`) or by an id that does not exist (child ids are opaque — take them from `get_section_template` / `list_imported_sections`, never invent them); and any `propValues` key that is not a real prop of that child component (the error lists the valid prop names). Auto-import: a referenced child code component that has been BUILT but not yet imported into the theme is imported automatically before the value is set (the response lists any such ids under `autoImported`); only children that are not built at all fail with a "no imported code component" error — build them first (`ikas-component build`/`dev`). For any prop type you are unsure about, inspect the existing value with `get_section_values` and match its exact shape. The change is applied with undo support.\n\n' +
+    "COMMON (global) sections — the theme's HEADER and FOOTER: these render on every page that carries a placement of them (ikas ready-made account/membership pages are born without one) and have ONE shared set of prop values, stored on the INDEX (Home) page's placement. Whichever page_id you write from, the value lands on that single record and changes the header/footer on ALL pages; the response carries a `common` block (`commonSectionType`, `canonicalPageId`, `canonicalElementId`) saying so, and the echoed `value` is read back from that canonical placement. Therefore: ALWAYS `get_section_values` first and change only the prop the user asked about — the props are already filled with the merchant's content even when you are on a page you have not inspected, so blind-filling \"empty-looking\" props overwrites the live header/footer everywhere. If the INDEX page has no placement of the section, there is no record to write to and the call fails telling you to add it to the INDEX page first.\n\n" +
+    "BIND TO A GLOBAL VARIABLE (Theme Setting): instead of a static `value`, pass `bind_global` = the global's `name` (its `variableName`, the `_<id>` form) from `list_theme_globals`. The prop becomes a LIVE dynamic value that always reflects that global's current value — editing the global in Theme Settings updates every bound prop. Use this to wire content to a project-wide setting (e.g. a shared announcement text, brand color, or logo image) rather than duplicating a literal. Pick a global whose type matches the prop (TEXT↔TEXT/RICH_TEXT, NUMBER↔NUMBER, BOOLEAN↔BOOLEAN, IMAGE↔IMAGE, COLOR↔COLOR, ENUM↔ENUM of the SAME enum type — the prop's `enumTypeId` must equal the setting's `enumTypeId`; a mismatch is REJECTED, …). Provide `value` OR `bind_global`, not both. 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
@@ -3666,12 +4039,21 @@ server.tool("update_section_prop", 'Change a single prop value of a section plac
         .describe("Blueprint prop name to update (alternative to `prop_id`)."),
     value: z
         .any()
-        .describe('The prop value object to store, e.g. `{ "value": "Hello" }`. Match the shape of the existing entry in `list_page_sections` propValues for non-scalar prop types.'),
+        .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.)"),
+    list_path: z
+        .array(z.object({ propId: z.string(), index: z.number() }))
+        .optional()
+        .describe("Only with `bind_global`: bind a prop of a COMPONENT_LIST child instead of a section-level prop. An array of `{ propId, index }` steps from the section down to the target child; `prop_id` is then the CHILD's prop id (from `get_component_props`)."),
     port: z
         .number()
         .optional()
         .describe("Dev server WebSocket port (default 5201)."),
-}, async ({ project_root, page_id, element_id, prop_id, prop_name, value, port }) => {
+}, async ({ project_root, page_id, element_id, prop_id, prop_name, value, bind_global, list_path, port, }) => {
     const args = [
         "update-section-prop",
         "--page-id",
@@ -3680,17 +4062,25 @@ server.tool("update_section_prop", 'Change a single prop value of a section plac
         element_id,
         ...(prop_id ? ["--prop-id", prop_id] : []),
         ...(prop_name ? ["--prop-name", prop_name] : []),
-        "--value",
-        // The CLI JSON.parses --value. If `value` is already a JSON string, pass
-        // it through verbatim — re-stringifying it would double-encode it and the
-        // editor would store a string instead of the object/array.
-        typeof value === "string" ? value : JSON.stringify(value),
+        ...(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`. Use the returned `id` as the `id` of an IMAGE prop value passed to `update_section_prop` (e.g. `{ \"id\": \"<returned-id>\", \"altText\": \"...\", \"isVideo\": false }`). This is the way to set an image prop — `update_section_prop` does not upload, it only references an existing image id. Supported types: png, jpg, jpeg, webp, gif; max 10MB. Requires the editor to be embedded in the ikas admin panel (the admin panel performs the actual upload; a standalone editor cannot upload and will error/time out).", {
+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."),
@@ -3702,7 +4092,10 @@ server.tool("upload_image", "Upload an image to the connected editor's project a
         .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."),
+    alt_text: z
+        .string()
+        .optional()
+        .describe("Alt text to store with the image."),
     port: z
         .number()
         .optional()
@@ -3717,6 +4110,1185 @@ server.tool("upload_image", "Upload an image to the connected editor's project a
     ];
     return callEditorAction(project_root, args);
 });
+// Tool: update_page_sections
+server.tool("update_page_sections", "Fill MANY placed sections of a page in a SINGLE call — the fastest way to populate a whole page (one round-trip for the entire page instead of one call per section/prop). Takes `sections`, each `{ element_id, updates: [{ prop_name|prop_id, value }] }`; values use the same per-type shapes as update_section_prop / get_editor_workflow. All-or-nothing across the whole page: every value is resolved and deeply validated (and built-but-unimported child code components auto-imported) before anything is written — one invalid value rejects the entire page update. An update item may instead bind a prop to a project GLOBAL variable (Theme Setting) as a live dynamic value: use `{ prop_id|prop_name, bind_global }` where `bind_global` is the global's `name` (its `variableName`) from `list_theme_globals` — omit `value`. Add `list_path` (an array of `{ propId, index }` steps) to bind a prop of a COMPONENT_LIST child (then `prop_id` is the child's prop id). Static value writes are applied first, then bindings. Prefer this over many update_section_prop(s) calls. If any targeted section is a COMMON (global) one — the theme's header/footer — its values are shared by every page and stored on the INDEX (Home) page's placement: the write goes there and changes that section on ALL pages, the result's `common` block says so, and the echoed values are read back from that canonical placement. Read those sections with `get_section_values` first and only change what was asked; a header/footer missing from the INDEX page has no record to write to and rejects the whole call.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    page_id: z.string().describe("Target page id (from list_editor_pages)."),
+    sections: z
+        .array(z.object({
+        element_id: z
+            .string()
+            .describe("Placed-section elementId (from list_page_sections)."),
+        updates: z
+            .array(z.object({
+            prop_id: z
+                .string()
+                .optional()
+                .describe("Blueprint prop id (provide this or prop_name)."),
+            prop_name: z
+                .string()
+                .optional()
+                .describe("Blueprint prop name (alternative to prop_id)."),
+            value: z
+                .any()
+                .optional()
+                .describe("Prop value, same shape update_section_prop expects for that type. Omit when using bind_global."),
+            bind_global: z
+                .string()
+                .optional()
+                .describe("Bind this prop to a project GLOBAL variable (Theme Setting) as a live dynamic value instead of a static value. The global's `name` (variableName) from list_theme_globals. Provide value OR bind_global."),
+            list_path: z
+                .array(z.object({ propId: z.string(), index: z.number() }))
+                .optional()
+                .describe("Only with bind_global: `{ propId, index }` steps down to a COMPONENT_LIST child; prop_id is then the child's prop id."),
+        }))
+            .describe("Non-empty array of prop updates for this section."),
+    }))
+        .describe("Non-empty array of sections to fill, each with its elementId and prop updates."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, page_id, sections, port }) => {
+    const normalized = (sections || []).map((s) => ({
+        elementId: s.element_id,
+        updates: (s.updates || []).map((u) => ({
+            ...(u.prop_id ? { propId: u.prop_id } : {}),
+            ...(u.prop_name ? { propName: u.prop_name } : {}),
+            ...(u.bind_global
+                ? {
+                    bindGlobal: u.bind_global,
+                    ...(u.list_path ? { listPath: u.list_path } : {}),
+                }
+                : { value: u.value }),
+        })),
+    }));
+    const args = [
+        "update-page-sections",
+        "--page-id",
+        page_id,
+        "--sections",
+        JSON.stringify(normalized),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: upload_images
+server.tool("upload_images", "Upload MANY images in one call (batch upload_image) and get their ids back in order — the host uploads them all in a single round-trip. Pass `images`, each `{ file_path?, image_url?, alt_text? }`. Returns an array of { id, fileName, altText, isVideo } in the same order; use each id in an IMAGE prop value. Prefer this over multiple upload_image calls when a section/page needs several images. Supported: png/jpg/jpeg/webp/gif, max 10MB each. Requires the editor embedded in the ikas admin panel.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    images: z
+        .array(z.object({
+        file_path: z
+            .string()
+            .optional()
+            .describe("Local image file path (provide this or image_url)."),
+        image_url: z
+            .string()
+            .optional()
+            .describe("Image URL to fetch (alternative to file_path)."),
+        alt_text: z.string().optional().describe("Alt text for this image."),
+    }))
+        .describe("Non-empty array of images to upload."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, images, port }) => {
+    const manifest = (images || []).map((im) => ({
+        ...(im.file_path ? { file: im.file_path } : {}),
+        ...(im.image_url ? { url: im.image_url } : {}),
+        ...(im.alt_text ? { alt: im.alt_text } : {}),
+    }));
+    const args = [
+        "upload-images",
+        "--manifest",
+        JSON.stringify(manifest),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: search_products
+server.tool("search_products", 'Search the connected store\'s products to obtain a real productId (and first variantId) for a PRODUCT prop value. Returns products with productId, variantId, name, slug, variantCount, and `imageSrc` (the full-resolution CDN URL of the product\'s main image). To use that product image in an IMAGE prop, you CANNOT reuse a product image id directly (it is not a theme asset) — pass the `imageSrc` URL to `upload_image(image_url: <imageSrc>)` (or `upload_images`), then use the returned id in the IMAGE value. This gives real product imagery instead of external/placeholder URLs. Use the result in update_section_prop as `{ "productId": "<productId>", "variantId": "<variantId>" }`. Pass `query` for free-text search, or `product_ids` to resolve specific ids. Requires the editor embedded in the ikas admin panel (the admin panel runs the search; a standalone editor cannot).', {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    query: z
+        .string()
+        .optional()
+        .describe("Free-text product search (name, sku, barcode)."),
+    product_ids: z
+        .array(z.string())
+        .optional()
+        .describe("Specific product ids to resolve directly (alternative to `query`)."),
+    per_page: z.number().optional().describe("Results per page."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, query, product_ids, per_page, port }) => {
+    const args = [
+        "search-products",
+        ...(query ? ["--query", query] : []),
+        ...(product_ids && product_ids.length
+            ? ["--ids", product_ids.join(",")]
+            : []),
+        ...(typeof per_page === "number" ? ["--per-page", String(per_page)] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: list_categories
+server.tool("list_categories", 'List the store\'s product categories and their ids, to fill a CATEGORY prop value `{ "categoryId": "<id>" }`. Returns categoryId, name, slug, parentId for each. Returns all categories (no query). To link to a category from a LINK prop, also call `get_page_by_type("CATEGORY")` for the page id, then build `{ "linkType": "PAGE", "pageId": <pageId>, "pageType": "CATEGORY", "itemId": <categoryId>, "id": <unique>, "label": "..." }`. Requires the editor embedded in the ikas admin panel.', {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, port }) => {
+    const args = [
+        "list-entities",
+        "--kind",
+        "category",
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: list_brands
+server.tool("list_brands", 'List the store\'s product brands and their ids, to fill a BRAND prop value `{ "brandId": "<id>" }`. Returns brandId, name, slug for each. Returns all brands (no query). To link to a brand from a LINK prop, also call `get_page_by_type("BRAND")` for the page id, then build `{ "linkType": "PAGE", "pageId": <pageId>, "pageType": "BRAND", "itemId": <brandId>, "id": <unique>, "label": "..." }`. Requires the editor embedded in the ikas admin panel.', {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, port }) => {
+    const args = [
+        "list-entities",
+        "--kind",
+        "brand",
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: list_blogs
+server.tool("list_blogs", 'List the store\'s blogs and their ids, to fill a BLOG prop value `{ "blogId": "<id>" }`. Returns blogId, name, slug for each. Accepts an optional `query` for free-text search. To link to a blog from a LINK prop, also call `get_page_by_type("BLOG")` for the page id, then build `{ "linkType": "PAGE", "pageId": <pageId>, "pageType": "BLOG", "itemId": <blogId>, "id": <unique>, "label": "..." }`. Requires the editor embedded in the ikas admin panel.', {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    query: z.string().optional().describe("Free-text blog search."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, query, port }) => {
+    const args = [
+        "list-entities",
+        "--kind",
+        "blog",
+        ...(query ? ["--query", query] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: list_blog_categories
+server.tool("list_blog_categories", 'List the store\'s blog categories and their ids, to fill a BLOG_CATEGORY prop value `{ "blogCategoryId": "<id>" }`. Returns blogCategoryId, name, slug for each. Accepts an optional `query` for free-text search. To link to a blog category from a LINK prop, also call `get_page_by_type("BLOG_CATEGORY")` for the page id, then build `{ "linkType": "PAGE", "pageId": <pageId>, "pageType": "BLOG_CATEGORY", "itemId": <blogCategoryId>, "id": <unique>, "label": "..." }`. Requires the editor embedded in the ikas admin panel.', {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    query: z.string().optional().describe("Free-text blog-category search."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, query, port }) => {
+    const args = [
+        "list-entities",
+        "--kind",
+        "blog-category",
+        ...(query ? ["--query", query] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: get_page_by_type
+server.tool("get_page_by_type", 'Resolve a theme page\'s id from its pageType (CATEGORY, PRODUCT, BRAND, BLOG, BLOG_CATEGORY, INDEX, …). Use this to get the `pageId` needed to build a PAGE link to an entity: pair it with the entity id from list_categories/list_brands/list_blogs/list_blog_categories — `{ linkType:"PAGE", pageId:<this pageId>, pageType:<type>, itemId:<entityId>, id:<unique>, label:... }`. Returns `pageId: null` (with a note) if no page of that type exists yet — in that case call `create_page(page_type)` to add it, then use the returned pageId (do not guess a slug/EXTERNAL URL).', {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    page_type: z
+        .string()
+        .describe("Page type to resolve, e.g. CATEGORY, PRODUCT, BRAND, BLOG, BLOG_CATEGORY, INDEX."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, page_type, port }) => {
+    const args = [
+        "get-page-by-type",
+        "--page-type",
+        page_type,
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: create_page
+server.tool("create_page", 'Create a theme page of a given pageType in the connected editor. Use this when get_page_by_type returns `pageId: null` for a dynamic page (CATEGORY/PRODUCT/BRAND/BLOG/BLOG_CATEGORY) you need to link to: create the page, then build a PAGE link `{ linkType:"PAGE", pageId:<this pageId>, pageType:<type>, itemId:<entityId>, id:<unique>, label:... }` — do NOT guess a slug/EXTERNAL URL. Non-CUSTOM page types are unique per theme: if one already exists it is returned unchanged (`alreadyExisted: true`). CUSTOM pages require `name` and a unique `slug`. Account sub-pages (ADDRESSES/ORDERS/ORDER_DETAIL/FAVORITE_PRODUCTS/RAFFLE_ACCOUNT) need an ACCOUNT page first. Returns `{ pageType, pageId, name, slug }`. Requires `ikas theme dev` running with the editor connected.', {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    page_type: z
+        .string()
+        .describe("Page type to create, e.g. CATEGORY, PRODUCT, BRAND, BLOG, BLOG_CATEGORY, INDEX, CUSTOM."),
+    name: z
+        .string()
+        .optional()
+        .describe("Page name. Required for CUSTOM pages; ignored otherwise."),
+    slug: z
+        .string()
+        .optional()
+        .describe("Page slug. Required (and unique) for CUSTOM pages; ignored otherwise."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, page_type, name, slug, port }) => {
+    const args = [
+        "create-page",
+        "--page-type",
+        page_type,
+        ...(name ? ["--name", name] : []),
+        ...(slug ? ["--slug", slug] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: delete_page
+server.tool("delete_page", "Delete a theme page and every section placed on it. DESTRUCTIVE and effectively one-way from here (only the editor's own undo stack can bring it back) — ALWAYS get the user's explicit OK before calling it, and never call it to \"clean up\" a page you merely think is unused. Takes the page id from `list_editor_pages` / `get_page_by_type`; there is no name resolution. Refused for the pages a theme cannot run without — INDEX (home), CHECKOUT and NOT_FOUND (404) — and for an ikas-rendered ready-made account page, which must be turned off by its group with `enable_ready_made_pages` so the cleanup that flow does actually runs. Deleting the page currently open in the editor moves it to the home page first. Returns the deleted page's `{ pageId, pageType, name, slug }` plus `remainingPages`. Requires `ikas theme dev` running with the editor connected.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    page_id: z
+        .string()
+        .describe("Id of the page to delete (from `list_editor_pages` or `get_page_by_type`). Strict — no name resolution."),
+    confirm: z.boolean().describe(CONFIRM_PARAM_DESCRIPTION),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, page_id, confirm, port }) => {
+    if (confirm !== true)
+        return destructiveConfirmRefusal();
+    const args = [
+        "delete-page",
+        "--id",
+        page_id,
+        "--yes",
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: remove_page_section
+server.tool("remove_page_section", "Remove ONE section placement from a page — the delete counterpart of `add_section_to_page` / `move_page_section`. DESTRUCTIVE: it takes the merchant's content in that section with it, so get the user's explicit OK first. The checkout section on the CHECKOUT page is refused — the checkout page requires it, so never offer to remove it. Target the PLACEMENT by `element_id` from `list_page_sections`, never the `sectionId` or `componentId` — the same section placed twice has two independent placements and each is removed on its own (passing the wrong id is rejected with the elementId you meant). A common (header/footer) section on the home page is HIDDEN rather than deleted, because the INDEX placement is where a common section's prop values live for EVERY page; the reply says so with `hidden: true`, and `add_section_to_page` brings it back with its values intact. A page customized per routing/specification holds its own placements per state: pass `sf_routing_id`/`specification_id` to remove from that state, otherwise only the BASE layer is touched (the reply lists the states it left alone). Returns the removed placement plus the page's remaining `sections`. Requires `ikas theme dev` running with the editor connected.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    page_id: z
+        .string()
+        .describe("Id of the page holding the placement (from `list_editor_pages`)."),
+    element_id: z
+        .string()
+        .describe("The PLACEMENT's elementId from `list_page_sections` — not the sectionId and not the componentId."),
+    sf_routing_id: z
+        .string()
+        .optional()
+        .describe("Remove from this customized routing state instead of the page's base layer. The state must already exist."),
+    specification_id: z
+        .string()
+        .optional()
+        .describe("Remove from this customized specification state instead of the page's base layer. The state must already exist."),
+    confirm: z.boolean().describe(CONFIRM_PARAM_DESCRIPTION),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, page_id, element_id, sf_routing_id, specification_id, confirm, port, }) => {
+    if (confirm !== true)
+        return destructiveConfirmRefusal();
+    const args = [
+        "remove-page-section",
+        "--page-id",
+        page_id,
+        "--element-id",
+        element_id,
+        "--yes",
+        ...(sf_routing_id ? ["--sf-routing-id", sf_routing_id] : []),
+        ...(specification_id ? ["--specification-id", specification_id] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: publish_theme
+// Tool: list_ready_made_pages
+server.tool("list_ready_made_pages", "List the ikas-rendered ready-made (\"built-in\") account/membership pages (login, register, forgot/recover password, my account, orders, addresses, favorites, email verification) and how to customize them. These pages are rendered by ikas's own components, NOT by sections: a ready-made page carries no sections, so `list_page_sections` shows nothing and `update_section_prop` cannot touch it — `update_ready_made_page_prop` is the write tool. Without arguments returns the roster: per-group (`membership` = login/register/password flows, `account` = my-account pages) enabled state, every ready-made page type with its theme pageId and which props the merchant already edited, plus the SHARED SCOPES (logo, palette, account-menu labels — values edited once that reach every page in the scope's group). Pass `page_type` (e.g. LOGIN) or `scope_id` for that page's/scope's FULL prop schema (types, defaults, ENUM options, translations) and current values (`values` = what the page renders with; `ownValues` = what this page's own layer stores). Pass `sf_routing_id` to read what one storefront routing/locale sees — the no-argument call lists the store's routings (id, path, locale; `isDefault: true` = the base, needing no sf_routing_id). Typical branding flow: read the theme's palette via `list_theme_globals`, then set the shared scope's colors as `{ \"patternValueId\": \"<global color id>\" }` bindings so the pages follow the theme's colors live.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    page_type: z
+        .string()
+        .optional()
+        .describe("One ready-made page's full prop schema and values (e.g. LOGIN, ACCOUNT, ORDERS)."),
+    scope_id: z
+        .string()
+        .optional()
+        .describe("One shared scope's full prop schema and values (scope ids come from the no-argument call)."),
+    sf_routing_id: z
+        .string()
+        .optional()
+        .describe("Read the values one storefront routing/locale sees (default: the base routing)."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, page_type, scope_id, sf_routing_id, port }) => {
+    const args = [
+        "list-builtin-pages",
+        ...(page_type ? ["--page-type", page_type] : []),
+        ...(scope_id ? ["--scope-id", scope_id] : []),
+        ...(sf_routing_id ? ["--sf-routing-id", sf_routing_id] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: update_ready_made_page_prop
+server.tool("update_ready_made_page_prop", 'Set, bind, or clear ONE prop of an ikas-rendered ready-made account/membership page — the write half of `list_ready_made_pages`, and the ONLY way to customize those pages (they have no sections, so `update_section_prop` cannot reach them). Target a page\'s own prop with `page_type` (e.g. LOGIN) or a SHARED prop — logo, palette, menu labels, edited once for every page in the scope\'s group — with `scope_id`. Identify the prop by `prop_id` or `prop_name` from `list_ready_made_pages`. VALUES ARE RAW (no `{ "value": ... }` envelope — an envelope is tolerated and unwrapped): TEXT = the plain string; BOOLEAN = true/false; NUMBER = a number; ENUM = one of the prop\'s `enumOptions` VALUES; COLOR = "#rrggbb" OR `{ "patternValueId": "<global color id>" }` to follow a theme color live (ids from `list_theme_globals` → colors[].id — prefer the binding when branding, so a palette change updates the pages); IMAGE = `{ "id": "<image id>" }` (id from `upload_image`); LINK/LIST_OF_LINK = copy the shape from `list_ready_made_pages` values. `bind_global` (a global\'s `name` from `list_theme_globals`) makes the prop follow a Theme Setting instead of holding a value; `clear: true` deletes the stored value so the prop falls back to the shared value or the manifest default. `sf_routing_id` writes one routing\'s override — use it to localize texts per language; without it you write the base value every routing inherits. Writes are undoable in the editor.', {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    page_type: z
+        .string()
+        .optional()
+        .describe("Page type whose OWN prop to write (e.g. LOGIN). Pass this or scope_id."),
+    scope_id: z
+        .string()
+        .optional()
+        .describe("Shared scope whose prop to write — reaches every ready-made page in its group."),
+    prop_id: z
+        .string()
+        .optional()
+        .describe("Prop id from list_ready_made_pages. Provide this or prop_name."),
+    prop_name: z
+        .string()
+        .optional()
+        .describe("Prop name (alternative to prop_id)."),
+    value: z
+        .any()
+        .optional()
+        .describe("The RAW value (see the tool description for per-type shapes). Omit when using bind_global or clear."),
+    bind_global: z
+        .string()
+        .optional()
+        .describe("Bind the prop to a global variable (Theme Setting) — pass the global's `name` from list_theme_globals."),
+    clear: z
+        .boolean()
+        .optional()
+        .describe("true deletes the stored value; the prop falls back to the shared value or the manifest default."),
+    sf_routing_id: z
+        .string()
+        .optional()
+        .describe("Write one storefront routing's override (localization). Omit to write the base value."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, page_type, scope_id, prop_id, prop_name, value, bind_global, clear, sf_routing_id, port, }) => {
+    const args = [
+        "update-builtin-page-prop",
+        ...(page_type ? ["--page-type", page_type] : []),
+        ...(scope_id ? ["--scope-id", scope_id] : []),
+        ...(prop_id ? ["--prop-id", prop_id] : []),
+        ...(prop_name ? ["--prop-name", prop_name] : []),
+        ...(bind_global
+            ? ["--bind-global", bind_global]
+            : clear
+                ? ["--clear"]
+                : value !== undefined
+                    ? [
+                        "--value",
+                        // ALWAYS JSON-encode: the CLI JSON.parses --value (raw-string fallback), so a
+                        // verbatim TEXT string that happens to parse — "2024", "true", "null" — would
+                        // arrive as a number/boolean/clear. Encoded, it round-trips as the string it is.
+                        JSON.stringify(value),
+                    ]
+                    : []),
+        ...(sf_routing_id ? ["--sf-routing-id", sf_routing_id] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: enable_ready_made_pages
+server.tool("enable_ready_made_pages", 'Turn one GROUP of ikas-rendered ready-made pages on or off: "membership" (login, register, forgot/recover password, email verification) or "account" (my account, orders, order detail, addresses, favorites). Enabling records the choice and creates any page of the group the theme does not have yet — each born rendered by ikas\'s own component; customize them right after with `update_ready_made_page_prop`. Disabling removes ONLY the untouched pages the toggle itself created — a page the merchant built on is never deleted. The flip is one undo step in the editor. Check the current state first with `list_ready_made_pages`.', {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    group: z
+        .enum(["membership", "account"])
+        .describe('"membership" = login/register/password flows; "account" = my-account pages.'),
+    enabled: z
+        .boolean()
+        .describe("true to enable the group, false to disable it."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, group, enabled, port }) => {
+    const args = [
+        "enable-builtin-pages",
+        "--group",
+        group,
+        "--enabled",
+        String(enabled),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+server.tool("publish_theme", "Publish the current theme LIVE — the same action as the editor's Publish button (uploads the whole project to the storefront). This is REAL and customer-facing: the published site changes. SAFETY: it publishes nothing unless `confirm: true` is passed; if you omit it you get a dry-run with the `previewUrl` and a warning describing the impact. The MAIN/production theme additionally requires `confirm_production: true` (its URL is the live customer-facing domain). Use this when the user explicitly asks to publish/go live — do NOT publish on your own initiative. On success returns `{ published: true, previewUrl, isMainTheme }`; open `previewUrl` to review the result. Requires `ikas theme dev` running with the editor connected.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    confirm: z
+        .boolean()
+        .optional()
+        .describe("Set true to actually publish. Omitted/false = dry-run (returns previewUrl + warning, publishes nothing)."),
+    confirm_production: z
+        .boolean()
+        .optional()
+        .describe("Required IN ADDITION to confirm when the target is the MAIN/production theme (live customer-facing site)."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, confirm, confirm_production, port }) => {
+    const args = [
+        "publish-theme",
+        ...(confirm ? ["--confirm"] : []),
+        ...(confirm_production ? ["--confirm-production"] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: get_editor_workflow
+const EDITOR_WORKFLOW_GUIDE = [
+    "# Editor workflow: placing sections and filling their content on a page",
+    "",
+    "Use this when the user wants to add a section to a page and/or fill in its content (heading, text, image, link, slides, etc.) in the live editor. These are LIVE-EDITOR actions and require `ikas theme dev` running with the editor connected; image upload additionally requires the editor to be embedded in the ikas admin panel (the admin panel performs the upload — a standalone editor cannot upload).",
+    "",
+    "## Account & membership pages: ASK before you build",
+    "If the page the user wants is a login, register, forgot/recover-password, my-account, orders, order-detail, addresses, favorites or email-verification page: do NOT code a custom section page yet. ikas ships ready-made versions of exactly these pages — fully functional (real auth/order/address flows), customizable (logo, colors, texts) and localizable via update_ready_made_page_prop, the whole group enabled at once with enable_ready_made_pages. FIRST ask the user which they want: the ready-made page (fast, maintained by ikas) or a custom section page (full design freedom) — list the ready-made option FIRST as the recommended default, custom second. Only start coding after the user explicitly chooses custom — and never call enable_ready_made_pages without the user's OK, it creates/removes pages. Start discovery with list_ready_made_pages. USER-FACING NAME: name these in the USER'S OWN LANGUAGE — English: \"ikas's ready-made pages\", Turkish: \"ikas'ın hazır sayfaları\"; never mix the English term into a sentence in another language — the editor UI lists them as Membership Pages / My Account Pages; \"built-in\" is an internal term — keep it out of everything the user sees, including question/option labels. Note: a ready-made page is born with ONLY its own ikas-rendered element — the theme's header/footer are NOT on it (the page draws its own top bar — logo, back-to-store link — and account nav). If the user wants the theme header/footer there, place it with add_section_to_page (sections can sit above/below that element) and suggest turning the page's `showBrandBar` prop off to avoid double chrome.",
+    "",
+    "## Two distinct jobs — do not confuse them",
+    "- (A) DEFINE props / author component code — changing WHICH props a component has. Edits component source/config (config add-prop/add-component, index.tsx) and needs a rebuild. Do this ONLY when a needed prop does not exist yet, or the user explicitly asks to build/modify the component.",
+    "- (B) SET prop VALUES / fill content — giving values to props that ALREADY exist on a placed section. Pure data entry via list_page_sections + update_section_prop (+ upload_image). No code, no rebuild.",
+    "When the user says 'fill this section', 'set the title/text/image/link', 'populate', 'change the content' → that is JOB (B). Do NOT write a component or add a prop to fill a value the section already supports.",
+    "",
+    "## Step-by-step (JOB B — fill content)",
+    "1. list_editor_pages → choose the target page_id.",
+    "2. list_page_sections(page_id) → for each placed section: its per-placement elementId, blueprint props (id, name, type), and setPropNames (which props already have a value). It is LEAN — no prop VALUES, so it never truncates. To read a section's current values (e.g. to read-modify-write a COMPONENT_LIST), call get_section_values(page_id, element_id). A section returned with a `common` field is the theme's header/footer — its values are theme-wide, not this page's; read the 'COMMON (global) sections' section below BEFORE touching it. (If the section is not on the page yet, see 'Placing a section' below.)",
+    "3. To set props (fewest round-trips = fastest): update_page_sections(page_id, sections:[{element_id, updates:[{prop_name,value}]}]) fills the WHOLE page (or one section, or just one prop — it scales to all cases) in ONE call (best). update_section_prop sets a single prop, for quick one-offs. Pass each value as a parsed JSON object/array, NEVER a JSON string.",
+    "4. For image props: upload_images(images:[{file_path|image_url, alt_text}]) uploads many in ONE call (preferred); upload_image for a single one. Use the returned id(s) in IMAGE values. Do uploads BEFORE the update call so you have the ids.",
+    "Speed tip: each tool call is a round-trip — gather first (one list_page_sections), batch your uploads (upload_images) and your writes (update_page_sections), rather than calling per-prop/per-image.",
+    "",
+    "## COMMON (global) sections: the header and the footer",
+    "The theme's header and footer are COMMON sections: they render on every page that carries a placement of them (pages created in the editor are seeded with one — EXCEPT ikas ready-made (built-in) account/membership pages, which are born without the theme header/footer) and their prop values are SHARED by the whole theme — there is exactly ONE record, kept on the INDEX (Home) page's placement. A placement of the same section on any other page stores NOTHING of its own.",
+    '- How to recognize one: list_page_sections / get_section_values / the write results return a `common` block for it — `isCommon: true`, `commonSectionType: "header"|"footer"`, `valuesArePageSpecific: false`, plus `canonicalPageId`/`canonicalElementId` (the INDEX placement that holds the values). A page containing one also gets a top-level `commonSectionsNote`.',
+    "- READS are redirected for you: get_section_values / list_page_sections report a common section's values FROM the INDEX placement, whatever page_id you pass. So what you see is what the page actually renders — no need to re-read from the INDEX page.",
+    "- WRITES are redirected too: update_section_prop / update_page_sections / add_sections_to_page store the value on that INDEX record, so the change applies to the header/footer on ALL pages. The echoed value is read back from the canonical placement, so it reflects what was really stored.",
+    '- THE TRAP to avoid: a header/footer is normally already filled with the merchant\'s content. Never conclude a prop is empty and never blind-fill "missing" props — you would overwrite live content on every page, including pages you never opened. Always get_section_values first and change ONLY the prop the user asked about.',
+    "- If the INDEX page has no placement of the section, there is no record: reads return nothing and writes are REJECTED (\"Index page does not have the common section!\"). Fix it by placing the section on the INDEX page (add_section_to_page with the INDEX page id — get it from list_editor_pages / get_page_by_type('INDEX')) and setting its props there; it then renders on the other pages too.",
+    "",
+    "## Building a whole page fast (placing + filling)",
+    "- add_sections_to_page(page_id, sections:[{component_id, index?, updates:[{prop_name,value}]}]) places MANY sections AND sets their props in ONE call, returning each new elementId. This is the fastest path — prefer it over add_section_to_page per section followed by separate fills. Built-but-unimported section/child components are auto-imported.",
+    "- For a single section: list_imported_sections (confirm imported; else import_section, after building) → add_section_to_page(component_id, page_id, index?) → then list_page_sections to get its elementId.",
+    "- REORDERING an already-placed section is a different tool: move_page_section(page_id, element_id, direction:'up'|'down' | to_index:<n>). The `index` on add_* only positions a NEW placement; it cannot move an existing one, and the editor UI exposes reordering solely as a drag, so this tool is the only way. Indices are 0-based over the placed sections in list_page_sections order; the result returns `resultIndex` + the full resulting `sections` order — assert on those. Header/footer (COMMON) sections cannot be reordered and are rejected.",
+    "",
+    "## Value shapes by prop type (what to pass as `value`)",
+    '- Scalars are WRAPPED: TEXT/RICH_TEXT { "value": "..." }, BOOLEAN { "value": true }, NUMBER { "value": 12 }, COLOR { "value": "#FF0000" }, ENUM { "value": "<key>" }, DATE { "value": ... }.',
+    '- SVG is value-wrapped: { "value": "<svg markup>" }. NUMBER_RANGE: { "value": <number>, "unit": "px"|null }.',
+    '- SVG naming: the editor shows each svg\'s `class` attribute as its display name in the list; add class="my-icon" to name it. SVG_LIST items with no class render as svg-1, svg-2, ….',
+    '- Object props are NOT wrapped (no { "value": ... }):',
+    '  - IMAGE: { "id": "<asset-id>", "altText"?: "...", "isVideo"?: false } — get the id from upload_image. Same shape at section level AND nested in a component list. IMAGE_LIST: { "images": [ <image>, ... ] }.',
+    '  - VIDEO: { "video": { "id": "<asset-id>" }, "thumbnailImage"?: { "id": "..." }, "autoplay"?: false, "controls"?: true, "loop"?: false, "muted"?: false } — NOT a bare { "id": ... }. SVG_LIST: { "svgs": [ "<svg>", ... ] }.',
+    '  - LINK: { "id": "<unique>", "linkType": "PAGE"|"EXTERNAL"|"FILE", "label": "...", "subLinks": [] } plus target — for a static page: pageId + pageType (from list_editor_pages); for EXTERNAL: externalLink. To link to a CATEGORY/BRAND/BLOG/BLOG_CATEGORY entity, do NOT guess a slug — get the entity id from list_categories/list_brands/list_blogs/list_blog_categories and the page id from get_page_by_type(\'<TYPE>\'), then build { id, linkType:\'PAGE\', label, pageId:<pageId>, pageType:\'<TYPE>\', itemId:<entityId>, subLinks:[] }. LIST_OF_LINK = { "links": [ <link>, ... ] }.',
+    '  - Entity props PRODUCT/CATEGORY/BRAND/BLOG/BLOG_CATEGORY/RAFFLE: { "<entity>Id": "...", "usePageData"?: false } — e.g. { "productId": "...", "variantId"?: "..." }, { "categoryId": "..." }. Get real ids (never invent them) from: search_products (PRODUCT), list_categories (CATEGORY), list_brands (BRAND), list_blogs (BLOG), list_blog_categories (BLOG_CATEGORY). (RAFFLE has no lookup tool yet — read an existing value or ask the user.)',
+    "  - List/collection props (PRODUCT_LIST/CATEGORY_LIST/BRAND_LIST/BLOG_LIST/…): typed objects keyed by a <entity>ListType discriminator plus initialSort/initialLimit. The id field DEPENDS on the type — for PRODUCT_LIST: STATIC → productIds:[{productId,variantId}] (from search_products); CATEGORY → category:'<categoryId>' (from list_categories) — the field is `category`, NOT `categoryId` (categoryId is ONLY the standalone CATEGORY entity prop above); ALL/DISCOUNTED/RECOMMENDED/etc → no id field. Get the exact field set + writeNote from get_component_props, or read+edit an existing value via get_section_values. Unknown sub-fields (e.g. categoryId inside a PRODUCT_LIST) are REJECTED.",
+    '  - COMPONENT_LIST: { "components": [ { "id": "<unique>", "codeComponentId": "<child-id>", "propValues": { "<childProp>": <value>, ... } }, ... ] }. A single COMPONENT prop is one such entry. childProp values use these same per-type shapes, recursively.',
+    "",
+    "## COMPONENT_LIST rules (the part most often gotten wrong)",
+    "- READ-MODIFY-WRITE: update_section_prop REPLACES the whole prop value. To add/edit/remove one child, take the CURRENT { components: [...] } from get_section_values, edit it, and resend the ENTIRE array (with all existing entries and their ids). Sending only your new entry wipes the rest.",
+    "- Each entry needs a UNIQUE id (a short string you generate; it does not need to match anything). Do not reuse another entry's id.",
+    '- Reference a code component with "codeComponentId" and a built-in theme component with "componentId" — not the other way around. Use "propValues" (not "props").',
+    "- Child ids are opaque — take them from get_section_template / list_imported_sections; never invent them.",
+    "- Auto-import: a referenced child that is BUILT but not yet imported is imported automatically (returned under autoImported). A child that is not built at all errors — build it first.",
+    "",
+    "## Reading prop schemas (avoid guessing)",
+    "- get_component_props(componentId) → a component's props with types, required, default, ENUM `options` (the valid values to set), and COMPONENT_LIST `allowedComponentIds` (valid children). Works for any section OR child id. Use it BEFORE filling — to know prop names, enum values, and which children a slot allows — instead of guessing or reading ikas.config.json.",
+    "- For a COMPONENT_LIST: get_component_props(parent) → its allowedComponentIds → get_component_props(child) → the child's props/enums. Then build the components array.",
+    "- get_section_values(element_id) → one placed section's current values (read-modify-write of a COMPONENT_LIST, or to copy an existing value's exact shape).",
+    "- Real entity ids/images: search_products returns productId + variantId + imageSrc (the product image URL). To use that image in an IMAGE prop, you can't reuse a product image id — upload it: upload_image(image_url: imageSrc) → use the returned id. list_categories/list_brands/list_blogs/list_blog_categories return the entity ids; to LINK to one, also call get_page_by_type('<TYPE>') for the page id and build a PAGE link { linkType:'PAGE', pageId, pageType, itemId:<entityId>, id, label }. IMPORTANT: if get_page_by_type returns pageId:null, that dynamic page does NOT exist in the theme yet — do NOT guess a slug/EXTERNAL URL. Call create_page('<TYPE>') to add it (non-CUSTOM types are unique and returned as-is if already present), then use the returned pageId to build the PAGE link. Always have a real pageId before building a PAGE link.",
+    "",
+    "## Validation",
+    "Values are validated server-side (deeply, including nested children). Wrong shape or wrong semantics (double-encoded string, { value } wrapper on an object prop, props vs propValues, missing/duplicate id, wrong reference key, nonexistent component id, unknown prop name) are REJECTED with an explanatory error instead of being stored silently. Read the error and fix the value; if unsure of a shape, read it with get_section_values and match it.",
+].join("\n");
+server.tool("get_editor_workflow", "Read this FIRST when the user wants to place a section on a page or fill/edit a section's content (text, image, link, slides, component lists) in the live editor. Returns the complete step-by-step workflow for the live-editor tools (list_editor_pages, list_imported_sections, import_section, add_section_to_page, list_page_sections, update_section_prop, upload_image), the per-prop-type value shapes, the COMPONENT_LIST read-modify-write rules, how COMMON (global) header/footer sections keep one theme-wide set of values on the INDEX page (and how not to overwrite them), and how validation/auto-import behave. Use it to avoid the common mistake of writing component code to set a value a section already supports.", {}, async () => {
+    return {
+        content: [{ type: "text", text: EDITOR_WORKFLOW_GUIDE }],
+    };
+});
+// Tool: list_theme_globals
+server.tool("list_theme_globals", "List the theme's global settings from the connected editor: global variables (Theme Settings) and design tokens (colors, typography, breakpoints, keyframes, color schemes). Call this BEFORE generating sections/components so you reuse the theme's existing variables and tokens (read them in component code via `getThemeSetting`/`getThemeColors`/... from `@ikas/bp-storefront`). Includes items created manually in the editor UI. Requires `ikas theme dev` running with the editor connected. Two shape gotchas when consuming the result at runtime: (1) color schemes — `colorSchemes.schemes` holds only `{id,name}` slot LABELS; the actual colors live in `colorSchemes.values[].colorsByScheme` keyed by slot id, so iterate `values[].colorsByScheme` (iterating `schemes` renders empty). (2) An IMAGE setting's `value` is an image REFERENCE like `{id:'theme-images/<uuid>'}` with no `.url` — resolve it via `getDefaultSrc`/`getSrc`. (3) Each keyframe now includes its animation `settings` (type-dependent { property, value } entries — duration/iteration/timing/etc. for keyframe, transition for transition) and each point's resolved `styles`, so you can read back the full animation config, not just the `ref`. (4) Each typography entry may include `supportedFontWeights` — the exact numeric weights that text style's font actually ships (e.g. `[400]` for Modak); when present, only set `font_weight` to a value in this list (via `update_text_style`/`create_theme_global`), otherwise the write is rejected. If the field is absent the font's weight set couldn't be determined — fall back to 400 or rely on the validation error. Each typography entry also carries `isDefault` (true for the theme's default/global text style — the editor's \"Make Default Style\"); toggle it via `update_text_style`'s `is_default`. (5) Token NAMES are NOT unique — a theme can contain two tokens with the SAME name (e.g. colors pulled from two different design assets), so NEVER match a token by its human name. ALWAYS identify a token by its `id` (globally unique). IN COMPONENT CODE: prefer embedding the token's id-derived STABLE ref directly — color → cssVar `var(--<id>)`, typography → `className` `_<id>`, keyframe (animation-name) → `ref` `_<id>` — so you don't look anything up at runtime. If you DO need to pick a token out of a `getThemeColors()` / `getThemeTypography()` / `getThemeKeyframes()` / `getThemeColorSchemes()` array, match on `.id` (e.g. `getThemeColors().find(c => c.id === \"<id>\")`), NEVER on `.name`. EXCEPTION — global variables/settings: `getThemeSetting(name)` takes the token's `name`, but here `name` is the unique runtime key (`variableName`, the `_<id>` form returned in this list), which IS safe; do NOT pass a setting's human `displayName`. The update/delete tools also identify a token ONLY by `id` (they do NOT look up by name — on those tools `name` means the NEW name when renaming). Always take the `id` (or, for settings, the `name`/variableName) from THIS list. (6) GROUPING convention: a \"/\" in a token's NAME organizes it into a group in the editor UI — the text before the first \"/\" is the group, the rest is the item label. This applies to COLORS (e.g. \"Brand/Primary\"), TEXT STYLES (e.g. \"Heading/H1\"), and COLOR-SCHEME SLOTS (e.g. \"PrimaryButton/Background\"). When you create globals (via `create_theme_global`/`update_theme_color_scheme`), use \"/\"-prefixed names to keep related tokens grouped and tidy; reuse an existing group's exact prefix so they nest together. (7) ENUM settings: a setting with `type: \"ENUM\"` selects one option of a PROJECT enum and carries `enumTypeId` (the enum's id — the same one an ENUM prop declares as `enumTypeId`) and `options` (`{ label: value }`); its `value` is always one of those option VALUES (never a label), or null when unset. The response's top-level `enumTypes` array lists the project enums a new ENUM setting may select from (`{ id, name, options }`) — use an `id` from it as `enum_type_id` in `create_theme_global`. An ENUM prop can be bound (`bind_global`) only to an ENUM setting of the SAME enum.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project (where `node_modules/.bin/ikas-component` lives)."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, port }) => {
+    const args = [
+        "list-theme-globals",
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Shared text-style (typography) font-property schema — kept in lock-step with the editor's
+// "Update Text Style" modal fields (no color/text-align, since that modal doesn't expose them).
+// Each enum prop documents its accepted values so a bad value is caught with a clear error. Spread
+// into both create_theme_global (typography) and update_text_style so the two never drift apart.
+const textStyleFontParams = {
+    font_family: z
+        .string()
+        .optional()
+        .describe('A real font family the editor offers — a Google Fonts name with EXACT casing (e.g. "Inter", "Roboto", ' +
+        '"Poppins"), or a font already used by an existing text style in list_theme_globals. An unknown font ' +
+        "(or wrong casing) is rejected; do NOT invent a family name."),
+    font_size: z.string().optional(),
+    font_weight: z
+        .string()
+        .optional()
+        .describe("font-weight as a number (e.g. \"600\"); append 'i' for italic (e.g. \"600i\"). A PLAIN number with no 'i' " +
+        "is upright and REMOVES italic if the text style was italic (italic is carried by the weight — re-send the " +
+        "weight without 'i' to turn it off). Must be a weight the chosen " +
+        'font ships — if it isn\'t, the error lists the supported weights; when unsure use "400".'),
+    line_height: z.string().optional(),
+    letter_spacing: z.string().optional(),
+    text_decoration: z
+        .string()
+        .optional()
+        .describe("text-decoration: none | underline | line-through"),
+    text_transform: z
+        .string()
+        .optional()
+        .describe("text-transform: none | uppercase | lowercase | capitalize"),
+    text_overflow: z
+        .string()
+        .optional()
+        .describe("text-overflow: clip | ellipsis — 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."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, kind, name, id, port }) => {
+    const p = port ? ["--port", String(port)] : [];
+    const args = kind === "globalVariable"
+        ? ["delete-global-variable", "--name", String(name ?? ""), ...p]
+        : [
+            "delete-design-token",
+            "--token-type",
+            kind,
+            "--id",
+            String(id ?? ""),
+            ...p,
+        ];
+    return callEditorAction(project_root, args);
+});
 // --- Start server ---
 async function main() {
     const transport = new StdioServerTransport();