@wootsup/yt-builder-mcp 1.1.6 → 1.2.0

package/dist/uninstall.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Uninstall orchestration core — the inverse of the setup wizard.
+ *
+ * `setup` writes the yt-builder-mcp MCP server entry into one or more AI
+ * clients' config files (and optionally installs a skill). `uninstall`
+ * reverses that: it detects which clients currently carry our entry,
+ * removes the chosen ones, and optionally removes the installed skill.
+ *
+ * This module is the pure, testable core: detection + removal across the
+ * client registry, with every side effect injected via {@link
+ * UninstallDeps} so unit tests touch no real disk. The interactive clack
+ * checklist + the CLI flag-parsing live in `setup-cli.ts` and call into
+ * `detectInstalledClients` / `runUninstall` here.
+ *
+ * @license MIT
+ */
+import { type ClientWriter } from './clients/index.js';
+import { isSkillInstalled as defaultIsSkillInstalled, uninstallSkill as defaultUninstallSkill, type UninstallSkillResult } from './uninstall-skill.js';
+/** A client that currently carries a yt-builder-mcp server entry. */
+export interface InstalledClient {
+    readonly id: string;
+    readonly label: string;
+    readonly configPath: string;
+    /** The server keys/names found (e.g. `['yt-builder-mcp']`). */
+    readonly matchedKeys: readonly string[];
+}
+/**
+ * Probe every client in `clients` and return those whose config carries
+ * our server entry. Detection is parallel — the probes are independent
+ * file reads.
+ */
+export declare function detectInstalledClients(clients?: readonly ClientWriter[]): Promise<InstalledClient[]>;
+/** What the caller asked to uninstall. */
+export interface UninstallSelection {
+    /** Client ids to remove our entry from. */
+    readonly clientIds: readonly string[];
+    /** Also remove the installed skill (+ AGENTS.md marker)? */
+    readonly removeSkill: boolean;
+}
+/** Per-client outcome of a removal. */
+export interface ClientUninstallResult {
+    readonly id: string;
+    readonly label: string;
+    readonly configPath: string;
+    /** True when an entry was actually removed (false on no-op or error). */
+    readonly removed: boolean;
+    /** The keys removed (empty on no-op / error). */
+    readonly removedKeys: readonly string[];
+    /** Populated when removal threw. */
+    readonly error?: string;
+}
+export interface UninstallResult {
+    readonly clientResults: readonly ClientUninstallResult[];
+    /** Present only when `removeSkill` was requested. */
+    readonly skillResult?: UninstallSkillResult;
+}
+/** Injectable side effects so tests run without touching disk. */
+export interface UninstallDeps {
+    /** Registry to resolve `clientIds` against. */
+    readonly clients: readonly ClientWriter[];
+    readonly uninstallSkill: typeof defaultUninstallSkill;
+    readonly isSkillInstalled: typeof defaultIsSkillInstalled;
+}
+export declare const DEFAULT_UNINSTALL_DEPS: UninstallDeps;
+/**
+ * Execute an uninstall. Removes our server entry from each selected,
+ * KNOWN client id (unknown ids are silently skipped) and — when
+ * `removeSkill` is set — removes the installed skill. Each client removal
+ * is isolated: a failure on one is captured into its result and does not
+ * abort the others (so a partial uninstall still cleans what it can).
+ */
+export declare function runUninstall(selection: UninstallSelection, deps?: UninstallDeps): Promise<UninstallResult>;
+//# sourceMappingURL=uninstall.d.ts.map

package/dist/uninstall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uninstall.d.ts","sourceRoot":"","sources":["../src/uninstall.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAe,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,EACH,gBAAgB,IAAI,uBAAuB,EAC3C,cAAc,IAAI,qBAAqB,EACvC,KAAK,oBAAoB,EAC5B,MAAM,sBAAsB,CAAC;AAE9B,qEAAqE;AACrE,MAAM,WAAW,eAAe;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CACxC,OAAO,GAAE,SAAS,YAAY,EAAgB,GAC/C,OAAO,CAAC,eAAe,EAAE,CAAC,CAY5B;AAED,0CAA0C;AAC1C,MAAM,WAAW,kBAAkB;IAC/B,2CAA2C;IAC3C,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CACjC;AAED,uCAAuC;AACvC,MAAM,WAAW,qBAAqB;IAClC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,oCAAoC;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC5B,QAAQ,CAAC,aAAa,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACzD,qDAAqD;IACrD,QAAQ,CAAC,WAAW,CAAC,EAAE,oBAAoB,CAAC;CAC/C;AAED,kEAAkE;AAClE,MAAM,WAAW,aAAa;IAC1B,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IAC1C,QAAQ,CAAC,cAAc,EAAE,OAAO,qBAAqB,CAAC;IACtD,QAAQ,CAAC,gBAAgB,EAAE,OAAO,uBAAuB,CAAC;CAC7D;AAED,eAAO,MAAM,sBAAsB,EAAE,aAIpC,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,YAAY,CAC9B,SAAS,EAAE,kBAAkB,EAC7B,IAAI,GAAE,aAAsC,GAC7C,OAAO,CAAC,eAAe,CAAC,CAmC1B"}

package/dist/uninstall.js

@@ -0,0 +1,82 @@
+/**
+ * Uninstall orchestration core — the inverse of the setup wizard.
+ *
+ * `setup` writes the yt-builder-mcp MCP server entry into one or more AI
+ * clients' config files (and optionally installs a skill). `uninstall`
+ * reverses that: it detects which clients currently carry our entry,
+ * removes the chosen ones, and optionally removes the installed skill.
+ *
+ * This module is the pure, testable core: detection + removal across the
+ * client registry, with every side effect injected via {@link
+ * UninstallDeps} so unit tests touch no real disk. The interactive clack
+ * checklist + the CLI flag-parsing live in `setup-cli.ts` and call into
+ * `detectInstalledClients` / `runUninstall` here.
+ *
+ * @license MIT
+ */
+import { ALL_CLIENTS } from './clients/index.js';
+import { isSkillInstalled as defaultIsSkillInstalled, uninstallSkill as defaultUninstallSkill, } from './uninstall-skill.js';
+/**
+ * Probe every client in `clients` and return those whose config carries
+ * our server entry. Detection is parallel — the probes are independent
+ * file reads.
+ */
+export async function detectInstalledClients(clients = ALL_CLIENTS) {
+    const detections = await Promise.all(clients.map(async (c) => ({ client: c, det: await c.detect() })));
+    return detections
+        .filter((d) => d.det.present)
+        .map((d) => ({
+        id: d.client.id,
+        label: d.client.label,
+        configPath: d.det.configPath,
+        matchedKeys: d.det.matchedKeys,
+    }));
+}
+export const DEFAULT_UNINSTALL_DEPS = {
+    clients: ALL_CLIENTS,
+    uninstallSkill: defaultUninstallSkill,
+    isSkillInstalled: defaultIsSkillInstalled,
+};
+/**
+ * Execute an uninstall. Removes our server entry from each selected,
+ * KNOWN client id (unknown ids are silently skipped) and — when
+ * `removeSkill` is set — removes the installed skill. Each client removal
+ * is isolated: a failure on one is captured into its result and does not
+ * abort the others (so a partial uninstall still cleans what it can).
+ */
+export async function runUninstall(selection, deps = DEFAULT_UNINSTALL_DEPS) {
+    const byId = new Map(deps.clients.map((c) => [c.id, c]));
+    const clientResults = [];
+    for (const id of selection.clientIds) {
+        const client = byId.get(id);
+        if (client === undefined)
+            continue; // unknown id — skip
+        try {
+            const res = await client.remove();
+            clientResults.push({
+                id: client.id,
+                label: client.label,
+                configPath: res.configPath,
+                removed: res.removed,
+                removedKeys: res.removedKeys,
+            });
+        }
+        catch (e) {
+            const error = e instanceof Error ? e.message : String(e);
+            clientResults.push({
+                id: client.id,
+                label: client.label,
+                configPath: client.configPath(),
+                removed: false,
+                removedKeys: [],
+                error,
+            });
+        }
+    }
+    let skillResult;
+    if (selection.removeSkill) {
+        skillResult = await deps.uninstallSkill();
+    }
+    return { clientResults, ...(skillResult !== undefined ? { skillResult } : {}) };
+}
+//# sourceMappingURL=uninstall.js.map

package/dist/uninstall.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uninstall.js","sourceRoot":"","sources":["../src/uninstall.ts"],"names":[],"mappings":"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"}

package/manifest.json

@@ -2,7 +2,7 @@
     "dxt_version": "0.1",
     "name": "@wootsup/yt-builder-mcp",
     "display_name": "YT Builder MCP for YOOtheme Pro (unofficial)",
-    "version": "1.1.6",
+    "version": "1.2.0",
     "description": "Drive your YOOtheme Pro Page Builder programmatically from Claude, Cursor, Codex, Gemini and 5 other MCP-capable AI assistants — read layouts, edit settings, add elements, bind dynamic sources. Works on WordPress and Joomla 5/6. Built for YOOtheme Pro 4.0+. Independent third-party project, not affiliated with YOOtheme GmbH.",
     "long_description": "YT Builder MCP gives AI assistants a typed, scoped, and idempotent surface for your YOOtheme Pro Page Builder, on either WordPress or Joomla 5/6. Tools cover page discovery, layout inspection, element CRUD, source binding, and diagnostics. Bearer auth, optimistic locking via ETag, scope hierarchy (read < write < admin), and structured-error responses keep the agent safe and the workflow correct on first try. Independent third-party project — YOOtheme® is a registered trademark of YOOtheme GmbH (yootheme.com); YT Builder MCP is built by WootsUp (getimo productions) and is not affiliated with, endorsed by, or sponsored by YOOtheme.",
     "icon": "icon.png",
@@ -39,10 +39,10 @@
                 "${__dirname}/dist/index.js"
             ],
             "env": {
-                "YTB_MCP_SITES_FILE": "${user_config.YTB_MCP_SITES_FILE}",
                 "YTB_MCP_SITE_URL": "${user_config.YTB_MCP_SITE_URL}",
-                "YTB_MCP_PLATFORM": "${user_config.YTB_MCP_PLATFORM}",
-                "YTB_MCP_BEARER_TOKEN": "${user_config.YTB_MCP_BEARER_TOKEN}"
+                "YTB_MCP_BEARER_TOKEN": "${user_config.YTB_MCP_BEARER_TOKEN}",
+                "YTB_MCP_PROFILE": "${user_config.YTB_MCP_PROFILE}",
+                "YTB_MCP_SITES_FILE": "${user_config.YTB_MCP_SITES_FILE}"
             }
         }
     },
@@ -60,17 +60,17 @@
             "required": false,
             "sensitive": true
         },
-        "YTB_MCP_PLATFORM": {
+        "YTB_MCP_PROFILE": {
             "type": "string",
-            "title": "Platform (one site, optional)",
-            "description": "Leave this on 'auto'. The server detects WordPress or Joomla by itself. Only set 'wordpress' or 'joomla' if your host blocks the automatic check.",
+            "title": "Profile name (Optional for Single Site Configuration)",
+            "description": "Optional label for this site profile. Defaults to 'default'. With a Sites file, it selects which configured site is active; switch any time via yootheme_builder_use_site.",
             "required": false,
-            "default": "auto"
+            "default": "default"
         },
         "YTB_MCP_SITES_FILE": {
             "type": "string",
-            "title": "Sites file (connect many sites, advanced)",
-            "description": "Only for managing several sites from one install (agencies). Path to a sites.json, e.g. /Users/you/.config/yt-builder-mcp/sites.json. Create and fill it with: npx -y @wootsup/yt-builder-mcp add-site (do not hand-edit). When set, the three single-site fields above are ignored. Most people leave this empty.",
+            "title": "Sites file (for Multi-Site Configurations)",
+            "description": "Only for managing several sites from one install (agencies). Path to a sites.json, e.g. /Users/you/.config/yt-builder-mcp/sites.json. Create and fill it with: npx -y @wootsup/yt-builder-mcp add-site (do not hand-edit). When set, the single-site YTB_MCP_SITE_URL + token fields above are ignored. Most people leave this empty.",
             "required": false
         }
     },

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@wootsup/yt-builder-mcp",
-    "version": "1.1.6",
+    "version": "1.2.0",
     "type": "module",
     "description": "YT Builder MCP — drive your page builder from Claude, Cursor, Codex, Gemini and 5 other MCP-capable AI assistants. Built for YOOtheme Pro 4.0+. Independent third-party project, not affiliated with YOOtheme GmbH.",
     "license": "MIT",
@@ -48,6 +48,7 @@
         "node": ">=18.17.0"
     },
     "scripts": {
+        "prepublishOnly": "node -e \"if (process.env.RELEASE_PHP_PUBLISH !== '1') { console.error('Manual npm publish is no longer supported. Use: php scripts/release.php release yt-builder-mcp <bump> followed by php scripts/release.php push-tag yt-builder-mcp <version>, which triggers the GitHub Actions publish workflow (.github/workflows/yt-builder-mcp-publish.yml). Set RELEASE_PHP_PUBLISH=1 only if you know you are running from that workflow.'); process.exit(1); }\"",
         "build": "tsc",
         "dev": "tsc --watch",
         "test": "vitest run",
@@ -56,6 +57,7 @@
         "test:grep-gate": "vitest run tests/auth/secrets-grep-gate.test.ts",
         "typecheck": "tsc --noEmit",
         "lint": "eslint src --max-warnings=0",
+        "bump": "node ./scripts/bump-version.mjs",
         "setup": "node ./bin/yt-builder-mcp.js setup",
         "install-skill": "node ./bin/yt-builder-mcp.js install-skill",
         "build:dxt": "node ./scripts/build-dxt.js",
@@ -75,6 +77,7 @@
         "@typescript-eslint/eslint-plugin": "^8.0.0",
         "@typescript-eslint/parser": "^8.0.0",
         "@vitest/coverage-v8": "^1.4.0",
+        "esbuild": "^0.21.5",
         "eslint": "^9.0.0",
         "typescript": "^5.4.0",
         "typescript-eslint": "^8.0.0",

package/skills/yt-builder-mcp/SKILL.md

@@ -12,9 +12,9 @@ description: Drive the YOOtheme Pro Page Builder on WordPress or Joomla 5/6. Dis
 > WordPress and Joomla 5/6.
 
 This skill helps AI assistants drive the YOOtheme Pro Page Builder through the
-`@wootsup/yt-builder-mcp` server. The server exposes 27 typed, scoped, idempotent
-callable tools. 20 of them advertised as first-class entries in `tools/list`
-(17 essential L1 forwards + 2 direct L3 entries + 1 gateway), and 7 advanced
+`@wootsup/yt-builder-mcp` server. The server exposes 30 typed, scoped, idempotent
+callable tools. 23 of them advertised as first-class entries in `tools/list`
+(20 essential L1 forwards + 2 direct L3 entries + 1 gateway), and 7 advanced
 tools reachable through the single `yootheme_builder_advanced` gateway. This
 3-lane split keeps `tools/list` well below the ~40-tool Cursor cap while every
 catalogued tool stays fully reachable.
@@ -48,7 +48,7 @@ Some clients (notably Claude Desktop with the `.dxt` bundle) expose **two**
 entries when the user types "YT Builder MCP" into the picker:
 
 - **`YT Builder MCP for YOOtheme Pro (unofficial)`**: the MCP **server**.
-  Provides the 20 first-class tools (17 essential, 2 direct, 1 gateway).
+  Provides the 23 first-class tools (20 essential, 2 direct, 1 gateway).
   The `yootheme_builder_advanced` gateway routes 7 additional tools.
 - **`Von YT Builder MCP for YOOtheme Pro`**: the bundled **skill** (this
   document). Gives the agent the workflow knowledge needed to drive those
@@ -74,21 +74,22 @@ The server exposes:
 - **2 direct top-level tools**, always callable, always in `tools/list`:
   `yootheme_builder_health` and `yootheme_builder_diagnose`. These are
   the "the gateway itself might be broken" escape hatch.
-- **17 essential forwarded tools**: common reads + the most-used writes
-  (pages_list, get_etag, element_list / add / update_settings / get / move /
-  clone / delete, page_get_layout, sources_list, element_types_list,
-  element_type_get_schema, template_summary, inspect_multi_items_binding,
-  sites_list, sites_test). Always advertised in `tools/list` so AI clients
-  see them first-class.
+- **20 essential forwarded tools**: common reads + the most-used writes
+  (pages_list, pages_create, pages_delete, get_etag, element_list / add /
+  update_settings / get / move / clone / delete, page_get_layout,
+  sources_list, element_types_list, element_type_get_schema,
+  template_summary, inspect_multi_items_binding, sites_list, sites_test,
+  use_site). Always advertised in `tools/list` so AI clients see them
+  first-class.
 - **7 advanced captured tools**: everything else (page_save, page_publish,
   page_get_schema, element_get_binding, element_bind_source,
   element_unbind_source, clean_implode_directives). Reachable through one
   gateway tool: `yootheme_builder_advanced({ tool: "<name>", input: { ... } })`.
 - **1 gateway tool**: `yootheme_builder_advanced`.
 
-`tools/list` therefore advertises 20 names (17 + 2 + 1). That's 17 L1
-essentials + 2 L3 direct + 1 gateway. The total callable surface is 27
-(20 advertised + 7 advanced reachable through the gateway). If the AI
+`tools/list` therefore advertises 23 names (20 + 2 + 1). That's 20 L1
+essentials + 2 L3 direct + 1 gateway. The total callable surface is 30
+(23 advertised + 7 advanced reachable through the gateway). If the AI
 client reports "tool not found", you are almost certainly calling an
 advanced tool by its raw name. Wrap it in
 `yootheme_builder_advanced({ tool, input })` instead.
@@ -137,7 +138,7 @@ Do not loop on auth errors.
 > REST endpoints for per-article custom layouts, but they are NOT exposed
 > via MCP tools in v1.x. To use that surface, call the REST endpoints
 > directly with the Bearer key. MCP tool coverage for L2 articles is
-> planned for v1.2.0.
+> planned for a future release.
 
 ---
 
@@ -650,7 +651,7 @@ yootheme_builder_diagnose({})
 // Response shape:
 // {
 //   plugin_reachable: true,
-//   plugin_version: "1.1.0",
+//   plugin_version: "1.2.0",
 //   yootheme_loaded: true,
 //   yootheme_version: "5.0.22",
 //   endpoint_count: 16,
@@ -821,35 +822,38 @@ Joomla administrator access." Don't fabricate tool calls.
 
 <!-- TOOL-CATALOG:BEGIN -->
 
-**26 catalogued tools** plus the `yootheme_builder_advanced` gateway = **27 reachable via `tools/list`** (17 L1 + 2 L3 + 1 gateway = 20 advertised; the gateway routes to 7 additional advanced tools, bringing the total to 27 callable). Generated by `scripts/extract-tools.mjs` from the compiled `buildAllTools()` registry. Do not hand-edit this section; re-run `npm run build && node scripts/extract-tools.mjs` after changing tool definitions.
+**29 catalogued tools** plus the `yootheme_builder_advanced` gateway = **30 reachable via `tools/list`** (20 L1 + 2 L3 + 1 gateway = 23 advertised; the gateway routes to 7 additional advanced tools, bringing the total to 30 callable). Generated by `scripts/extract-tools.mjs` from the compiled `buildAllTools()` registry. Do not hand-edit this section; re-run `npm run build && node scripts/extract-tools.mjs` after changing tool definitions.
 
 | Tool | Kind | Input keys | Description |
 | --- | --- | --- | --- |
-| `yootheme_builder_clean_implode_directives` | idempotent | `element_path`, `etag`, `site_id`, `template_id` | Strips `props.source.props.*.implode` directives from an element binding. Returns audit log + new ETag. Idempotent (cleaned_count: 0 when nothing to remove). Requires ETag. Operates on the default site unless site_id is provided. |
+| `yootheme_builder_clean_implode_directives` | destructive | `confirm`, `element_path`, `etag`, `site_id`, `template_id` | Strips `props.source.props.*.implode` directives from an element binding. Returns audit log + new ETag. Idempotent at the server (cleaned_count: 0 when nothing to remove) but classed as destructive because the affected binding cannot be restored without re-mapping. Always ask the user to confirm first, then call again with `confirm: true`. Requires ETag. Operates on the default site unless site_id is provided. |
 | `yootheme_builder_diagnose` | read+idempotent | `site_id` | Full diagnostic: /health + authenticated /etag probe. Returns site_url, home_url, plugin reachability, Bearer validity in one call. First call when you need to know where the site lives. For per-template URLs see pages_list. Operates on the default site unless site_id is provided. |
 | `yootheme_builder_element_add` | mutating | `children`, `element_type`, `etag`, `parent_path`, `props`, `site_id`, `template_id` | Add a new element to a template. Provide `parent_path` (or "" for root), `element_type` (e.g. "headline", "text", "grid"), and optional `props` / `children`. Returns the new element's JSON-Pointer path. Requires ETag. Operates on the default site unless site_id is provided. |
 | `yootheme_builder_element_bind_source` | idempotent | `bindingLevel`, `element_path`, `etag`, `field_mappings`, `site_id`, `source_id`, `source_name`, `template_id` | Binds a Builder source to an element (sets `props.source`). Use bindingLevel "item" on Multi-Items containers (grid/slideshow/switcher/…) to bind on the first *_item child instead of the container itself. Requires ETag. Operates on the default site unless site_id is provided. |
 | `yootheme_builder_element_clone` | mutating | `element_path`, `etag`, `site_id`, `template_id` | Clone an element as a sibling (same parent, immediately after the source). Returns the new element's path. Requires ETag. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_element_delete` | destructive | `confirm`, `element_path`, `etag`, `site_id`, `template_id` | PERMANENTLY delete an element and all its children. Cannot be undone. Always ask the user to confirm first, then call again with `confirm: true`. Requires ETag. Operates on the default site unless site_id is provided. |
+| `yootheme_builder_element_delete` | destructive | `confirm`, `element_path`, `etag`, `site_id`, `template_id` | PERMANENTLY delete an element + children. Cannot be undone. Pass `confirm: true` (boolean) AND a fresh ETag. If `preview:true` returns despite confirm, check `details.received_confirm` — strings/numbers accepted, but boolean is canonical. Operates on the default site unless site_id is provided. |
 | `yootheme_builder_element_get` | read+idempotent | `element_path`, `site_id`, `template_id` | Get the full element object at a specific JSON-Pointer path, including props and children. Use yootheme_builder_element_list to discover paths. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_element_get_binding` | read+idempotent | `element_path`, `site_id`, `template_id` | Read the source binding attached to an element: the bound source name, the field-mappings (which source field feeds which element prop) and the query arguments/directives. Returns the empty object if the element is not bound. Operates on the default site unless site_id is provided. |
+| `yootheme_builder_element_get_binding` | read+idempotent | `element_path`, `site_id`, `template_id` | Read the source binding attached to an element — the bound source name, the field-mappings (which source field feeds which element prop) and the query arguments/directives. Returns the empty object if the element is not bound. Operates on the default site unless site_id is provided. |
 | `yootheme_builder_element_list` | read+idempotent | `cursor`, `depth`, `fields`, `limit`, `root_path`, `site_id`, `template_id` | List elements in a template as a flat array with JSON-Pointer paths + types. Scope with `root_path`/`depth` for a subtree, paginate with `limit`/`cursor` for large templates. `fields[]` narrows each row. Operates on the default site unless site_id is provided. |
 | `yootheme_builder_element_move` | idempotent | `element_path`, `etag`, `site_id`, `template_id`, `to_index`, `to_parent_path` | Move an element to a new parent + index in the tree. Useful for reordering or reparenting (e.g. moving a card from one grid column to another). Requires ETag. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_element_type_get_schema` | read+idempotent | `element_type`, `site_id`, `type_name` | **Call before every `element_add` / `_update_settings`.** Unknown prop keys are silently dropped server-side, so guessing fails quietly. Returns `{name,type,label?}` field descriptors. Use `element_type`; `type_name` is DEPRECATED. Operates on the default site unless site_id is provided. |
+| `yootheme_builder_element_type_get_schema` | read+idempotent | `element_type`, `site_id`, `type_name` | **Call before every `element_add` / `_update_settings`** — unknown prop keys are silently dropped server-side, so guessing fails quietly. Returns `{name,type,label?}` field descriptors. Use `element_type`; `type_name` is DEPRECATED. Operates on the default site unless site_id is provided. |
 | `yootheme_builder_element_types_list` | read+idempotent | `fields`, `site_id` | List element types registered on this site (built-ins + YOOessentials/uEssentials extras). Names feed `element_type` of element_add. Pass `fields[]` to narrow each row. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_element_unbind_source` | destructive | `confirm`, `element_path`, `etag`, `site_id`, `template_id` | Remove the source binding from an element. Clears `props.source`. Destructive in the sense that it may break dynamic-content rendering, so always ask the user to confirm. Requires ETag. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_element_update_settings` | idempotent | `element_path`, `etag`, `merge`, `props`, `site_id`, `template_id` | Update `props` on an element. Default replaces all props; pass `merge:true` for server-side deep-merge (only request keys overwritten, others survive, which avoids read-modify-write races). Requires ETag. Operates on the default site unless site_id is provided. |
+| `yootheme_builder_element_unbind_source` | destructive | `confirm`, `element_path`, `etag`, `site_id`, `template_id` | Remove the source binding from an element. Clears `props.source`. Destructive in the sense that it may break dynamic-content rendering — always ask the user to confirm. Requires ETag. Operates on the default site unless site_id is provided. |
+| `yootheme_builder_element_update_settings` | idempotent | `element_path`, `etag`, `merge`, `props`, `site_id`, `template_id` | Update `props` on an element. Default replaces all props; pass `merge:true` for server-side deep-merge (only request keys overwritten, others survive — avoids read-modify-write races). Requires ETag. Operates on the default site unless site_id is provided. |
 | `yootheme_builder_get_etag` | read+idempotent | `site_id` | Get the current ETag (state revision) for the YOOtheme builder. Returns sha256+revision string used for optimistic locking on writes. Pass the returned value back as `etag` on any write tool (page_save, page_publish, element_add, element_update_settings, element_clone, element_move, element_delete). The server returns HTTP 412 if the ETag has changed since you read it. Keywords: get etag, current etag, state revision, optimistic lock, version stamp. Operates on the default site unless site_id is provided. |
 | `yootheme_builder_health` | read+idempotent | `site_id` | Check plugin installed/reachable. Returns plugin version, YT Pro version, REST endpoints. Authenticated payload adds site_url + home_url for deep-linking. See yootheme_builder_diagnose for Bearer-validity + connectivity summary. Operates on the default site unless site_id is provided. |
 | `yootheme_builder_inspect_multi_items_binding` | read+idempotent | `element_path`, `site_id`, `template_id` | Reports Multi-Items binding state: container/item pair (grid↔grid_item, slideshow↔slideshow_item, …), current binding level (none\|container\|item), and a recommended_fix when the binding sits on the container instead of the child. Operates on the default site unless site_id is provided. |
 | `yootheme_builder_page_get_layout` | read+idempotent | `fields`, `flat`, `site_id`, `template_id` | Get full layout tree for one template. Default nested `{layout, etag}`. Set `flat:true` for depth-first array `{elements:[...], etag}`; combine with `fields[]` to project per-element. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_page_get_schema` | read+idempotent | `site_id`, `template_id` | Get the flat schema for a template: a list of nodes with their JSON-Pointer paths and element types. Best entry-point for navigation: lighter than page_get_layout, sufficient to locate elements before editing. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_page_publish` | idempotent | `etag`, `site_id`, `template_id` | Publish a template: persist state, flush YT + WP caches, snapshot the published-state ETag. ETag optional. When provided, 412 on conflict; when omitted, last-write-wins. Recommended for collaborative edits. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_page_save` | idempotent | `etag`, `site_id`, `template_id` | Re-run save-transforms and persist. ETag optional. When provided, 412 on conflict; when omitted, last-write-wins. Recommended for collaborative edits. No-op when state is byte-identical (returns `no_changes:true`, ETag unchanged). Operates on the default site unless site_id is provided. |
+| `yootheme_builder_page_get_schema` | read+idempotent | `site_id`, `template_id` | Get the flat schema for a template — a list of nodes with their JSON-Pointer paths and element types. Best entry-point for navigation: lighter than page_get_layout, sufficient to locate elements before editing. Operates on the default site unless site_id is provided. |
+| `yootheme_builder_page_publish` | idempotent | `etag`, `site_id`, `template_id` | Publish a template — persist state, flush YT + WP caches, snapshot the published-state ETag. ETag optional — when provided, 412 on conflict; when omitted, last-write-wins. Recommended for collaborative edits. Operates on the default site unless site_id is provided. |
+| `yootheme_builder_page_save` | idempotent | `etag`, `site_id`, `template_id` | Re-run save-transforms + flush caches. Does NOT accept a layout — land edits via element_add/update/bind/delete first. No-op if byte-identical. New pages: pages_create. Publish: page_publish. ETag optional. Operates on the default site unless site_id is provided. |
+| `yootheme_builder_pages_create` | idempotent | `dry_run`, `layout`, `site_id`, `slug`, `status`, `title` | Create a new WordPress page with a YOOtheme per-page layout. Required: title. Optional: slug (defaults to sanitize_title(title)), status (default: draft), layout (JSON, default: {type:"layout",children:[]}). Supports dry-run mode (dry_run:true) to preflight all hardening layers without persisting. Returns page_id, slug (post-collision-resolved), template_id, etag, warnings. Operates on the default site unless site_id is provided. |
+| `yootheme_builder_pages_delete` | idempotent | `confirm`, `force`, `post_id`, `site_id` | Delete a WordPress page (with associated YOOtheme per-page layout). Requires confirm:true (gate against accidental deletion). Default behavior: wp_trash_post (recoverable via wp-admin). With force:true: permanent wp_delete_post(force=true). Refuses non-page post types with 403 (Layer 9 defense). Returns deleted:true, page_id, force_deleted, bumped etag. Operates on the default site unless site_id is provided. |
 | `yootheme_builder_pages_list` | read+idempotent | `fields`, `site_id` | List all pages, templates, and layouts in the YOOtheme Pro builder. Returns template_id, label, type, element count, and frontend_url per row. CALL THIS FIRST to discover available template IDs before any tool that needs a template_id (page_get_layout, element_list, page_get_schema, etc.). Keywords: list pages, list templates, list layouts, discover template_id, index, available templates, what pages exist. Pass `fields:["id","label"]` to slim. Returns ALL pages in one call (no pagination, typically <50 templates per site). Operates on the default site unless site_id is provided. |
 | `yootheme_builder_sites_list` | read+idempotent | `site_id` | List all sites configured in this multi-site MCP installation. Returns site_id + URL + platform (wordpress\|joomla) + default flag per row. CALL THIS FIRST when working with a fresh MCP connection to discover available site_ids before targeting one with any other tool. Read-only, no REST calls. Keywords: list sites, list connections, list installations, discover site_id, available sites, configured sites, what sites exist, multi-site index. (site_id is accepted for schema-uniformity but ignored by this tool.) |
 | `yootheme_builder_sites_test` | read+idempotent | `site_id` | Verify connectivity to ONE site: probes /health (no auth) + /etag (auth) in parallel; returns plugin_reachable + bearer_valid. `site_id` is REQUIRED. Use sites_list to find IDs. |
 | `yootheme_builder_sources_list` | read+idempotent | `fields`, `site_id` | List all data sources, feeds, and dynamic content sources available in the YOOtheme Pro builder. Returns name + label + origin (apimapper / wordpress / joomla / essentials) per source. CALL THIS BEFORE binding any element to a data source. Pick a source name from the list and pass it to `element_bind_source`. Keywords: list sources, list data sources, list feeds, list bindings, dynamic content, available data, what sources exist. Pass `fields[]` to narrow each row. Operates on the default site unless site_id is provided. |
-| `yootheme_builder_template_summary` | read+idempotent | `site_id`, `template_id` | Token-efficient template overview: element counts by type, binding count, max nesting depth, and named landmark sections, computed server-side in one call. Use this to grasp a large template before pulling element_list or page_get_layout. Operates on the default site unless site_id is provided. |
+| `yootheme_builder_template_summary` | read+idempotent | `site_id`, `template_id` | Token-efficient template overview: element counts by type, binding count, max nesting depth, and named landmark sections — computed server-side in one call. Use this to grasp a large template before pulling element_list or page_get_layout. Operates on the default site unless site_id is provided. |
+| `yootheme_builder_use_site` | idempotent | `probe`, `site_id` | Switch the ACTIVE site for this multi-site session. After this call, every tool that omits `site_id` targets the site you picked here (until you switch again or restart). Runs a /health + /etag probe by default; pass `probe: false` to switch offline. A degraded site is a soft warning (the switch still happens). `site_id` is REQUIRED. Keywords: switch site, change site, set active site, select installation, use profile, activate site, target site. Use yootheme_builder_sites_list first to find IDs. |
 
 <!-- TOOL-CATALOG:END -->