@respira/wordpress-mcp-server 7.3.0 → 7.4.1

package/dist/server.js

@@ -15,61 +15,8 @@ import { WordPressClient } from './wordpress-client.js';
 import { RespiraVersionChecker } from './version-checker.js';
 import { getBricksTools, dispatchBricksTool } from './bricks-tools.js';
 import { getElementorTools, dispatchElementorTool } from './elementor-tools.js';
-import { getAcfTools, resolveAcfToolName } from './acf-tools.js';
+import { getAcfTools, ACF_TOOL_NAMES } from './acf-tools.js';
 import { getUsageEmitter, deriveToolKind } from './usage-emitter.js';
-import { loadConfig, saveConfig } from './config.js';
-/**
- * Per-tool argument aliases. AI clients (especially Cowork / Claude desktop)
- * frequently pass a natural-but-wrong key for a value: `pageId` / `page_id`
- * instead of `id`, `filePath` instead of `file`. Because the dispatch never
- * validated required params, a misnamed id silently produced a broken request
- * like `/wp-json/respira/v2/pages/undefined`, and a misnamed file produced an
- * empty upload that failed with "Could not connect — no response received".
- *
- * This map fills the canonical key a handler reads from the first present
- * synonym, and ONLY when the canonical key is absent — an explicit value is
- * never overwritten. Keyed by the canonical (wordpress_*) tool name, i.e.
- * after normalizeToolName().
- */
-const TOOL_ARG_ALIASES = {
-    wordpress_read_page: { id: ['page_id', 'pageId', 'post_id', 'postId'] },
-    wordpress_read_post: { id: ['post_id', 'postId', 'page_id', 'pageId'] },
-    wordpress_create_page_duplicate: {
-        original_id: ['page_id', 'pageId', 'id', 'original_page_id', 'originalId'],
-    },
-    wordpress_create_post_duplicate: {
-        original_id: ['post_id', 'postId', 'id', 'original_post_id', 'originalId'],
-    },
-    wordpress_get_snapshot: { snapshot_uuid: ['snapshot_id', 'snapshotId', 'uuid', 'id'] },
-    wordpress_find_element: { post_id: ['page_id', 'pageId', 'id', 'postId'] },
-    wordpress_upload_media: {
-        file: ['filePath', 'file_path', 'path', 'url', 'file_url', 'fileUrl'],
-        filename: ['file_name', 'fileName', 'name'],
-    },
-};
-/**
- * Fill canonical argument keys from known synonyms, in place. No-op for tools
- * without an alias entry and for args that already carry the canonical key.
- */
-function normalizeToolArgs(canonicalName, args) {
-    if (!args || typeof args !== 'object')
-        return;
-    const aliases = TOOL_ARG_ALIASES[canonicalName];
-    if (!aliases)
-        return;
-    const record = args;
-    const isSet = (v) => v !== undefined && v !== null && v !== '';
-    for (const [canonical, synonyms] of Object.entries(aliases)) {
-        if (isSet(record[canonical]))
-            continue;
-        for (const syn of synonyms) {
-            if (isSet(record[syn])) {
-                record[canonical] = record[syn];
-                break;
-            }
-        }
-    }
-}
 /**
  * Read the server version from package.json at module load time so the
  * MCP handshake, the `instructions` block, and the version-checker all
@@ -303,15 +250,6 @@ const TOOLS_WITH_PAGINATION_HINT = {
     respira_list_users: 'Pass per_page (default 100, recommend 25) and page args plus a search filter to narrow results.',
     respira_list_media: 'Pass per_page (default 100, recommend 25) and page args plus a mime_type filter to narrow results.',
     respira_extract_builder_content: 'Use respira_get_page_outline first for a row-level summary, or pass node_id to extract just the subtree you care about.',
-    // capResponseSize is called with the canonical wordpress_* name, so the
-    // extract/read tools need wordpress_* keys too or they fall through to the
-    // generic hint. Read tools were missing entirely, which is why a large-page
-    // read gave no "use get_page_outline + node_id" guidance. (Jeff, 2026-07-09.)
-    wordpress_extract_builder_content: 'Use wordpress_get_page_outline first for a row-level summary, or pass node_id to extract just the subtree you care about.',
-    respira_read_page: 'Large page. Call respira_get_page_outline first for a row-level map, then respira_extract_builder_content with a node_id to pull one subtree at a time.',
-    wordpress_read_page: 'Large page. Call wordpress_get_page_outline first for a row-level map, then wordpress_extract_builder_content with a node_id to pull one subtree at a time.',
-    respira_read_post: 'Large post. Call respira_get_page_outline first for a row-level map, then respira_extract_builder_content with a node_id to pull one subtree at a time.',
-    wordpress_read_post: 'Large post. Call wordpress_get_page_outline first for a row-level map, then wordpress_extract_builder_content with a node_id to pull one subtree at a time.',
     respira_list_plugins: 'No pagination arg today. The full plugin list is usually small; consider filing a feature request if your site hits the cap here.',
 };
 export class RespiraWordPressServer {
@@ -325,9 +263,10 @@ export class RespiraWordPressServer {
     allowedSites = null;
     /** Whether the plugin version warning has already been shown this session. */
     versionWarningShown = false;
-    /** Epoch ms of the last account site-list refresh (throttle network calls). */
+    /** Epoch ms of the last site-list self-heal against respira.press (throttle). */
     lastSiteRefreshAt = 0;
-    static SITE_REFRESH_MIN_INTERVAL_MS = 60_000;
+    /** Dedupe concurrent self-heals so parallel list_sites calls share one fetch. */
+    siteRefreshInFlight = null;
     static MCP_SERVER_VERSION = MCP_SERVER_VERSION;
     /**
      * Normalize a tool name: respira_* → wordpress_* for switch dispatch.
@@ -570,14 +509,9 @@ Use respira_get_builder_info first to detect which builder is active. Then use t
 - _nextNodeId tracking for proper element ID sequencing after injection
 - respira_find_element and respira_update_element work via tree traversal with full element schema
 
-### Oxygen
-There are TWO different Oxygen builders. Check get_builder_info to know which is active.
-- **Oxygen Classic** (the ct_* shortcode builder): content in ct_builder_shortcodes / ct_builder_json meta; templates use the ct_template post type.
-- **Oxygen 6 (codename Jenga, the Breakdance engine)** — a different builder, not Classic. Content is a node tree in the _oxygen_data meta, rendered as native OxygenElements\\* / EssentialElements\\* elements, NOT shortcodes. Author with simplified types via wordpress_inject_builder_content / build_page (pass type + settings, Respira maps them): section, heading (settings.text + level h1-h6), text, rich-text, button (text + url), image (url), icon, video, row, column. On an Oxygen 6 site, get_builder_info returns an \`oxygen6\` block with the full per-element schemas and a structure playbook — read it before building.
-  - Build with native elements. NEVER put a whole page or section into a single code/html block: it renders but is not editable in the Visual Builder and is the wrong way to build an Oxygen page.
-  - Header, footer, and templates are separate post types: oxygen_header, oxygen_footer, oxygen_template. Edit the existing header/footer posts; do not delete them and inline header/footer into every page.
-  - A template MUST use a Template Content Area element (OxygenElements\\TemplateContentArea) where the page body should render. Do NOT use a Post Content element on Oxygen 6 — it errors and the page cannot be edited. This is the most common Oxygen 6 template mistake.
-  - The richest building blocks (a real Section, Heading, Button with full design controls) come from the "Breakdance Elements for Oxygen" add-on; when it is absent Respira uses the core OxygenElements equivalents, still native and editable.
+### Oxygen (Smart Defaults)
+- Content stored in ct_builder_shortcodes and/or ct_builder_json meta
+- Templates use ct_template post type
 - respira_find_element works via tree traversal on the parsed structure
 
 ### WPBakery (Smart Defaults)
@@ -706,124 +640,6 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
     getSiteSummary(site) {
         return site.getSiteSummary(site.getSiteId() === this.defaultSiteId);
     }
-    /**
-     * Re-pull the account's CURRENT site list from respira.press and merge in any
-     * sites that aren't in the running server yet.
-     *
-     * Why this exists: the server boots from whatever site list was in its config
-     * at startup. When the user adds a site on the dashboard afterwards, a
-     * long-lived server (Cowork especially) never learns about it and silently
-     * serves the stale list — Emil had 4 sites but Cowork only ever saw 3
-     * (2026-06-30). Rather than make the user re-paste config and restart, this
-     * lets list_sites self-heal: authenticate with a `respira_site_` token the
-     * server already holds, fetch the account's canonical config, and register
-     * any new sites in-memory (and persist to ~/.respira/config.json when that is
-     * the active source).
-     *
-     * Best-effort and throttled: a network/auth failure is swallowed and the
-     * existing list is returned unchanged. Servers with no site token (OAuth-only)
-     * or pinned to RESPIRA_CONFIG_B64 still get the in-session merge; only the
-     * on-disk persistence is skipped when the file is not the active source.
-     */
-    async refreshSitesFromAccount(force = false) {
-        const result = { added: [] };
-        const now = Date.now();
-        if (!force && now - this.lastSiteRefreshAt < RespiraWordPressServer.SITE_REFRESH_MIN_INTERVAL_MS) {
-            return result;
-        }
-        // Pick a live dashboard site token to authenticate the refresh.
-        let authToken = '';
-        for (const client of this.sites.values()) {
-            const key = client.getApiKey();
-            if (typeof key === 'string' && key.startsWith('respira_site_')) {
-                authToken = key;
-                break;
-            }
-        }
-        if (!authToken) {
-            // OAuth-only or token-less server: nothing to authenticate with.
-            return result;
-        }
-        // Stamp before the network call so a hang/failure still respects the
-        // throttle and we don't retry on every single list_sites.
-        this.lastSiteRefreshAt = now;
-        const apiBase = process.env.RESPIRA_API_BASE || 'https://www.respira.press';
-        const url = `${apiBase.replace(/\/+$/, '')}/api/mcp/config/refresh`;
-        let payload = null;
-        try {
-            const response = await fetch(url, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify({ token: authToken }),
-                signal: AbortSignal.timeout(8000),
-            });
-            if (!response.ok) {
-                return result;
-            }
-            payload = await response.json().catch(() => null);
-        }
-        catch {
-            return result;
-        }
-        const accountSites = payload?.config?.sites;
-        if (!Array.isArray(accountSites)) {
-            return result;
-        }
-        for (const site of accountSites) {
-            if (!site?.id || !site?.url || !site?.apiKey)
-                continue;
-            if (this.sites.has(site.id))
-                continue;
-            const cfg = {
-                id: site.id,
-                name: site.name || site.id,
-                url: site.url,
-                apiKey: site.apiKey,
-                default: false,
-            };
-            const client = new WordPressClient(cfg);
-            this.sites.set(cfg.id, client);
-            if (this.currentSite === null) {
-                this.currentSite = client;
-                this.defaultSiteId = cfg.id;
-            }
-            try {
-                getUsageEmitter().registerSiteToken(cfg.url, cfg.apiKey);
-            }
-            catch {
-                // Best-effort; usage telemetry never blocks.
-            }
-            result.added.push(cfg.name);
-        }
-        // Persist new sites to disk so a restart keeps them — only when the file is
-        // the active config source. A RESPIRA_CONFIG_B64- or RESPIRA_CONFIG_FILE-
-        // pinned server still has the correct in-memory list this session; writing
-        // the default file would not be read on its next boot and could orphan a
-        // stray file, so skip it there.
-        const fileIsActiveSource = !process.env.RESPIRA_CONFIG_B64?.trim() && !process.env.RESPIRA_CONFIG_FILE?.trim();
-        if (result.added.length > 0 && fileIsActiveSource) {
-            try {
-                const onDisk = loadConfig();
-                const known = new Set(onDisk.sites.map((s) => s.id));
-                for (const site of accountSites) {
-                    if (site?.id && site?.url && site?.apiKey && !known.has(site.id)) {
-                        onDisk.sites.push({
-                            id: site.id,
-                            name: site.name || site.id,
-                            url: site.url,
-                            apiKey: site.apiKey,
-                            default: false,
-                        });
-                    }
-                }
-                saveConfig(onDisk);
-            }
-            catch {
-                // Best-effort; the in-memory merge above is what unblocks this session.
-            }
-        }
-        return result;
-    }
     /**
      * N6 fix (v6.19.0): the response envelope `site` field must reflect the
      * client that ACTUALLY serviced the call, not the global default. Pre-fix,
@@ -915,14 +731,9 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
         const apiBase = process.env.RESPIRA_API_BASE || 'https://www.respira.press';
         const url = `${apiBase.replace(/\/+$/, '')}/docs-search?q=${encodeURIComponent(query)}&limit=${limit}`;
         try {
-            // Bound the docs fetch (20s) so a slow or unreachable respira.press
-            // (a QUIC-hostile network, a proxy, a stalled link) fails fast instead
-            // of hanging the tool to the MCP client's multi-minute ceiling.
-            // search_docs is a convenience lookup, never worth blocking triage on.
             const response = await fetch(url, {
                 method: 'GET',
                 headers: { 'User-Agent': `respira-mcp/${MCP_SERVER_VERSION}` },
-                signal: AbortSignal.timeout(20_000),
             });
             if (!response.ok) {
                 return {
@@ -1224,41 +1035,159 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             url: s.url,
         }));
         const hasConfigB64 = Boolean(process.env.RESPIRA_CONFIG_B64);
-        // FAIL LOUD when the server is pinned to RESPIRA_CONFIG_B64. The config load
-        // order is RESPIRA_CONFIG_B64 -> RESPIRA_CONFIG_FILE -> ~/.respira/config.json
-        // (see config.ts), so the file we just wrote is OVERRIDDEN by the env var and
-        // the freshly-redeemed token never takes effect. The old code reported
-        // success with the caveat appended to the end of the message; agents glossed
-        // over it and reported "no output", so the user reconnected forever with a
-        // stale token (Sara / crediso.io: repeated redeems, token never updated,
-        // every authenticated call rejected). Returning success:false with the fix
-        // and the exact replacement value up front makes it impossible to miss.
-        if (hasConfigB64) {
-            const newConfigB64 = Buffer.from(JSON.stringify(config)).toString('base64');
-            return {
-                success: false,
-                error: 'config_pinned_to_env',
-                config_b64_active: true,
-                action_required: true,
-                config_path: configPath,
-                sites_count: sites.length,
-                sites,
-                new_config_b64: newConfigB64,
-                message: 'The token was redeemed and written to ~/.respira/config.json, but it will NOT take effect yet: this MCP server is pinned to the RESPIRA_CONFIG_B64 environment variable, which overrides the config file. That is exactly why reconnecting never updates the token and authenticated calls keep failing. ' +
-                    'Fix it one of two ways, then FULLY restart the agent: ' +
-                    '(1) remove RESPIRA_CONFIG_B64 from this server\'s MCP config so the file just written is used, or ' +
-                    '(2) replace the value of RESPIRA_CONFIG_B64 with this updated base64:\n\n' + newConfigB64,
-            };
-        }
+        const baseMessage = `Connected ${sites.length} site${sites.length === 1 ? '' : 's'} via the Respira Cowork token. The config was written to ~/.respira/config.json. Restart this Cowork chat (or open a new one) so the MCP server picks up the new sites.`;
+        const message = hasConfigB64
+            ? `${baseMessage} IMPORTANT: your MCP server is currently configured via the RESPIRA_CONFIG_B64 environment variable, which takes precedence over the file on disk. To activate the new site, update RESPIRA_CONFIG_B64 in your agent's MCP server config with the base64-encoded contents of the new ~/.respira/config.json file, then restart the agent.`
+            : baseMessage;
         return {
             success: true,
             sites_count: sites.length,
             sites,
             config_path: configPath,
-            config_b64_active: false,
-            message: `Connected ${sites.length} site${sites.length === 1 ? '' : 's'} via the Respira Cowork token. The config was written to ~/.respira/config.json. Restart this Cowork chat (or open a new one) so the MCP server picks up the new sites.`,
+            config_b64_active: hasConfigB64,
+            message,
         };
     }
+    /**
+     * Self-heal the in-memory site list from respira.press.
+     *
+     * The running server boots from whatever site list was frozen into its
+     * config at startup (RESPIRA_CONFIG_B64 env, or ~/.respira/config.json).
+     * When the user later adds a site on the dashboard, that frozen list never
+     * learns about it: RESPIRA_CONFIG_B64 outranks the file (see loadConfig), and
+     * Cowork's sandbox can't even write the file, so `redeem` can't persist a new
+     * site there. The only workaround users found was deleting and reinstalling
+     * the connector for every new site (Mario, 3 sites; Emil, 4 sites Cowork saw
+     * as 3). That is the bug this fixes.
+     *
+     * Here we re-pull the account's CURRENT canonical inventory using a
+     * credential the server already holds (any one live `respira_site_` token)
+     * via /api/mcp/config/refresh, and merge any missing sites straight into the
+     * live `this.sites` map. Because the merge is in-memory it takes effect in
+     * the SAME session with no restart, no re-paste, and no file write, so it
+     * works identically under RESPIRA_CONFIG_B64 and inside Cowork's sandbox.
+     *
+     * Best-effort and non-blocking: any failure (offline, OAuth-only config with
+     * no site token, backend error, timeout) resolves to 0 added and never
+     * throws, so list_sites still returns the sites already known. Throttled to
+     * at most once per RESPIRA_SITE_REFRESH_THROTTLE_MS (default 60s) and
+     * deduped so parallel calls share one fetch.
+     *
+     * @returns number of newly added sites.
+     */
+    async maybeSelfHealSiteList(force = false) {
+        if (process.env.RESPIRA_DISABLE_SITE_REFRESH === '1') {
+            return 0;
+        }
+        const throttleMs = Number(process.env.RESPIRA_SITE_REFRESH_THROTTLE_MS) || 60_000;
+        if (!force && Date.now() - this.lastSiteRefreshAt < throttleMs) {
+            return 0;
+        }
+        if (this.siteRefreshInFlight) {
+            return this.siteRefreshInFlight;
+        }
+        this.siteRefreshInFlight = this.performSiteRefresh().finally(() => {
+            this.siteRefreshInFlight = null;
+        });
+        return this.siteRefreshInFlight;
+    }
+    async performSiteRefresh() {
+        // Any one live dashboard site token identifies the account. OAuth
+        // per-site tokens (rsp_at_) are not account-wide and are skipped.
+        let token;
+        for (const client of this.sites.values()) {
+            const key = client.getApiKey?.();
+            if (key && key.startsWith('respira_site_')) {
+                token = key;
+                break;
+            }
+        }
+        // Stamp the attempt time even when we bail, so a token-less config doesn't
+        // retry the loop on every single list_sites call.
+        this.lastSiteRefreshAt = Date.now();
+        if (!token) {
+            return 0;
+        }
+        const apiBase = process.env.RESPIRA_API_BASE || 'https://www.respira.press';
+        const url = `${apiBase.replace(/\/+$/, '')}/api/mcp/config/refresh`;
+        const timeoutMs = Number(process.env.RESPIRA_SITE_REFRESH_TIMEOUT_MS) || 8000;
+        let payload;
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ token }),
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            if (!response.ok) {
+                return 0;
+            }
+            payload = await response.json();
+        }
+        catch {
+            // Offline / proxy / firewall / timeout: never block list_sites on this.
+            return 0;
+        }
+        const sites = payload?.config?.sites;
+        if (!Array.isArray(sites)) {
+            return 0;
+        }
+        const knownUrls = new Set();
+        for (const client of this.sites.values()) {
+            knownUrls.add(this.normalizeSiteUrl(client.getSiteUrl()));
+        }
+        let added = 0;
+        for (const s of sites) {
+            if (!s || typeof s !== 'object' || !s.id || !s.url || !s.apiKey) {
+                continue;
+            }
+            // Dedupe by id AND by normalized URL (a stale frozen config may hold the
+            // same site under a different id than the canonical inventory returns).
+            if (this.sites.has(s.id) || knownUrls.has(this.normalizeSiteUrl(s.url))) {
+                continue;
+            }
+            try {
+                const client = new WordPressClient({
+                    id: s.id,
+                    url: s.url,
+                    apiKey: s.apiKey,
+                    name: s.name || s.id,
+                    default: false,
+                });
+                this.sites.set(s.id, client);
+                knownUrls.add(this.normalizeSiteUrl(s.url));
+                if (!this.currentSite) {
+                    this.currentSite = client;
+                    this.defaultSiteId = s.id;
+                }
+                try {
+                    getUsageEmitter().registerSiteToken(s.url, s.apiKey);
+                }
+                catch {
+                    // usage telemetry never blocks
+                }
+                added += 1;
+            }
+            catch {
+                // A single malformed site entry never aborts the merge.
+            }
+        }
+        if (added > 0) {
+            console.error(`respira-mcp: self-heal added ${added} site${added === 1 ? '' : 's'} from respira.press ` +
+                `(now ${this.sites.size} connected).`);
+        }
+        return added;
+    }
+    /** Normalize a site URL for cross-config dedupe: scheme/host only, no www, lowercase. */
+    normalizeSiteUrl(raw) {
+        try {
+            const u = new URL(raw);
+            return u.host.replace(/^www\./i, '').toLowerCase() + u.pathname.replace(/\/+$/, '');
+        }
+        catch {
+            return String(raw || '').trim().toLowerCase().replace(/\/+$/, '');
+        }
+    }
     /**
      * When a WRITE tool runs against the default site because the caller
      * omitted site_id and the account has more than one site connected,
@@ -1368,12 +1297,6 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             // (wordpress_redeem_token) because normalizeToolName rewrites the
             // respira_* alias to wordpress_* before dispatch.
             const canonical = this.normalizeToolName(name).canonical;
-            // Tolerate natural-but-wrong arg names from AI clients (pageId/page_id
-            // vs id, filePath vs file). Fills canonical keys from synonyms in place
-            // so a misnamed required param no longer yields /pages/undefined or an
-            // empty "no response received" upload. No-op for tools without aliases;
-            // an explicit canonical value is never overwritten.
-            normalizeToolArgs(canonical, args);
             if (canonical === 'wordpress_redeem_token') {
                 // redeemInstallToken returns a plain object. Wrap it in the standard
                 // MCP content envelope — the early-exit path bypasses the normal
@@ -1475,18 +1398,6 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                                     timeout_ms: error.timeoutMs,
                                     message: error.message,
                                     hint: 'Other tools should continue to work. ' +
-                                        // For a read on a large page, the timeout is almost
-                                        // always a SIZE problem wearing a timeout costume: a big
-                                        // page takes longer to generate/transfer than the
-                                        // per-request HTTP timeout, so the request aborts before
-                                        // the response-size cap can return its truncation
-                                        // envelope. Without this line the user only sees "timeout"
-                                        // and keeps raising RESPIRA_MAX_TOOL_TIMEOUT_MS or
-                                        // restarting the client, never learning it was the cap.
-                                        // (Jeff Imperial, 2026-07-09.)
-                                        (/read_page|read_post|read_custom_post|extract_builder_content|find_builder_targets|get_builder_info|get_page/.test(String(error.toolName || ''))
-                                            ? 'This was a read on a page or site that may be large. The most likely cause is response SIZE, not a dead server: a big page can exceed the per-request HTTP timeout before the response-size cap returns a truncation envelope, so it surfaces as a plain timeout. Recover by calling respira_get_page_outline first, then respira_extract_builder_content with a node_id to pull one row or subtree at a time (or add a search / per_page filter). '
-                                            : '') +
                                         'If this operation genuinely needs more time, raise RESPIRA_MAX_TOOL_TIMEOUT_MS. ' +
                                         'For uploads specifically, also see RESPIRA_UPLOAD_TIMEOUT_MS and RESPIRA_MAX_UPLOAD_MB. ' +
                                         'To triangulate which network layer (origin / Cloudflare / Wordfence) is slow, run respira_diagnose_connection — it probes the same site with HEAD/GET/OPTIONS and reports per-layer latency + edge-layer presence. ' +
@@ -2284,7 +2195,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             },
             {
                 name: 'wordpress_inject_builder_content',
-                description: 'REPLACE (or append to) the entire page builder layout. WARNING: By default this REPLACES all existing content (use mode:"append" to add content without destroying existing elements). For editing a single module, use wordpress_update_module instead. Use exactly: gutenberg, divi, elementor, bricks, beaver, oxygen, breakdance, brizy, thrive, visual-composer, wpbakery. For Divi, divi_version is required ("4" or "5"). Replacing a page that already has content with mode="replace" requires confirm_replace=true, else returns 409 respira_replace_confirmation_required. Alternatives: mode="append" to add to existing content, or edit_target="live" to overwrite the live page directly. The gate prevents silent data loss.\n\nCanonical Divi 5 nested shape: `content: [{ type: "section", children: [{ type: "row", children: [{ type: "column", children: [{ type: "heading", settings: {...} }] }] }] }]` (rows/cols/columns/modules/elements/innerBlocks also accepted as `children` aliases). Each Divi module needs its render-critical attr in `settings` (e.g. heading→title, text→content, button→button_text); the plugin names any missing one via `respira_divi_required_attrs_missing`.\n\nLARGE SECTIONS (payload cap): if a fully styled section is too big to send in one call (some AI clients cap tool-call payload size), build it in pieces with `target_path`. First create the section frame (the section + rows + empty columns) in one small call, then append each module into its column with separate small calls: `target_path: "sections[0].rows[0].columns[1]"`, `position: -1` (append to end). Get exact bracket paths from `extract_builder_content`. Do NOT split one section across multiple top-level `mode:"append"` calls — append adds each call as a NEW section, so you would get several sections instead of one. `target_path` insert is supported on Divi 5 today; on other builders it returns `respira_target_path_unsupported` (use the lean-skeleton + `update_module` approach there).',
+                description: 'REPLACE (or append to) the entire page builder layout. WARNING: By default this REPLACES all existing content (use mode:"append" to add content without destroying existing elements). For editing a single module, use wordpress_update_module instead. Use exactly: gutenberg, divi, elementor, bricks, beaver, oxygen, breakdance, brizy, thrive, visual-composer, wpbakery. For Divi, divi_version is required ("4" or "5"). Replacing a page that already has content with mode="replace" requires confirm_replace=true, else returns 409 respira_replace_confirmation_required. Alternatives: mode="append" to add to existing content, or edit_target="live" to overwrite the live page directly. The gate prevents silent data loss.\n\nCanonical Divi 5 nested shape: `content: [{ type: "section", children: [{ type: "row", children: [{ type: "column", children: [{ type: "heading", settings: {...} }] }] }] }]` (rows/cols/columns/modules/elements/innerBlocks also accepted as `children` aliases). Each Divi module needs its render-critical attr in `settings` (e.g. heading→title, text→content, button→button_text); the plugin names any missing one via `respira_divi_required_attrs_missing`.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -2319,14 +2230,6 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                             description: 'Divi generation hint ("4" for shortcode format, "5" for block format). Required for all Divi inject calls.',
                             enum: ['4', '5'],
                         },
-                        target_path: {
-                            type: 'string',
-                            description: 'Insert the content as children of the container at this bracket path (from extract_builder_content), e.g. "sections[0].rows[1].columns[0]", instead of at page top level. Use this to build a large section in small calls when the whole tree exceeds the AI client payload cap: create the section frame first, then append each module by target_path. Omit for normal whole-page inject. Supported on Divi 5 today; other builders return respira_target_path_unsupported.',
-                        },
-                        position: {
-                            type: 'number',
-                            description: 'Where to insert within the target_path container: -1 (default) appends to the end, 0 inserts first, N inserts at index N. Only used when target_path is set.',
-                        },
                     },
                     required: ['builder', 'page_id', 'content'],
                 },
@@ -2409,10 +2312,6 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                             description: 'When editing an original, choose ask, live, or duplicate. Defaults to ask when direct editing is enabled.',
                             enum: ['ask', 'live', 'duplicate'],
                         },
-                        confirm_live_edit: {
-                            type: 'boolean',
-                            description: 'Set true together with edit_target:"live" to acknowledge a direct write to the published original. Exposed at the top level so autonomous flows can complete the confirmation_required handshake without polluting the updates object.',
-                        },
                     },
                     required: ['builder', 'page_id', 'module_identifier', 'updates'],
                 },
@@ -2573,10 +2472,6 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                             description: 'When editing an original, choose ask, live, or duplicate. Defaults to ask when direct editing is enabled.',
                             enum: ['ask', 'live', 'duplicate'],
                         },
-                        confirm_live_edit: {
-                            type: 'boolean',
-                            description: 'Set true together with edit_target:"live" to acknowledge a direct write to the published original. Exposed at the top level so autonomous flows can complete the confirmation_required handshake without polluting the operations.',
-                        },
                     },
                     required: ['builder', 'post_id', 'operations'],
                 },
@@ -2647,35 +2542,6 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     required: ['relative_path', 'content'],
                 },
             },
-            {
-                name: 'wordpress_read_debug_log',
-                description: 'Tail wp-content/debug.log (or a custom WP_DEBUG_LOG path) to diagnose PHP fatals, warnings and notices without SSH. Read-only: never writes, rotates, or deletes the log. Only reads the last few MB of the file from the end, so this is safe on large logs. Requires plugin v7.4.21+, WP_DEBUG_LOG must be enabled on the site, and the user behind the API key must have the WP `edit_themes` capability (same gate as wordpress_read_theme_file). Lines are grouped into log entries (a stack trace stays attached to its originating error) and obvious secrets (Authorization: Bearer tokens, api_key=/password= style params, long hex/base64 blobs) are redacted before the response leaves the server. Use `level` to filter to fatals/errors/warnings, `since` to scope to recent activity, and `grep` to search for a specific string or pattern. Pairs well with wordpress_diagnose_connection: when a route returns a 5xx, pull the matching debug.log lines from around that time.',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        lines: {
-                            type: 'number',
-                            description: 'Maximum number of matching log entries to return, most recent first is NOT applied (returned in chronological order). Default 200, capped at 2000.',
-                            minimum: 1,
-                            maximum: 2000,
-                        },
-                        level: {
-                            type: 'string',
-                            description: 'Filter by severity: "fatal" (PHP Fatal error only), "error" (fatal + parse + recoverable + warning-class PHP errors), "warning" (PHP Warning / Notice / Deprecated), or "all" (default, no filtering).',
-                            enum: ['fatal', 'error', 'warning', 'all'],
-                        },
-                        since: {
-                            type: 'string',
-                            description: 'Only return entries whose leading timestamp is after this point. Accepts an ISO-8601 timestamp or a relative expression like "-1 hour", "-30 minutes", "yesterday".',
-                        },
-                        grep: {
-                            type: 'string',
-                            description: 'Filter to entries containing this plain substring (case-insensitive), or a `/pattern/` regex (also matched case-insensitively; malformed patterns fall back to a plain substring match instead of erroring).',
-                        },
-                    },
-                },
-                readOnlyHint: true,
-            },
             {
                 name: 'wordpress_switch_site',
                 description: 'Switch to a different WordPress site in the active Respira multi-site configuration.',
@@ -4061,21 +3927,6 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                 },
                 destructiveHint: true,
             },
-            {
-                name: 'wordpress_detach_duplicate',
-                description: 'Clear the is_duplicate/original_id link on a post Respira still tracks as a pending duplicate, WITHOUT deleting it or overwriting the original. Use this instead of approving or rejecting when the "duplicate" turned out to be its own independent live page (for example it was cloned from the original once, long ago, as a starting template and later rebuilt into unrelated content). This is the fix for "Cannot edit original ... A duplicate already exists ..." errors caused by a stale/phantom duplicate: detach the duplicate_id from the error response, then retry the original edit. Works for pages, posts, and any custom post type since the relationship is tracked by post meta, not post type.',
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        duplicate_id: {
-                            type: 'number',
-                            description: 'ID of the post currently marked as a Respira duplicate to detach (the duplicate_id returned in the "A duplicate already exists" error, NOT the original id).',
-                        },
-                    },
-                    required: ['duplicate_id'],
-                },
-                idempotentHint: true,
-            },
             // Options
             {
                 name: 'wordpress_list_options',
@@ -4528,56 +4379,6 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
     /** Cached site context for tool filtering (refreshed on site switch). */
     cachedFilterContext = null;
     static FILTER_CACHE_TTL = 60_000; // 1 minute
-    /**
-     * Capability negotiation (7.2.6): tools whose plugin REST route only exists
-     * from a given plugin version. On older plugins these 404 with
-     * respira_rest_no_route — the biggest non-element failure class in the
-     * MCP-quality telemetry (656 errors across 97 tools), pure version skew since
-     * only ~half the connected sites run a current plugin. We stop advertising
-     * these tools when the connected plugin predates the route, so the agent is
-     * never offered something that will 404. @since values are verified against
-     * the plugin source (the first release tag that contains each route).
-     */
-    static TOOL_MIN_PLUGIN_VERSION = {
-        wordpress_run_pagespeed_audit: '7.1.0', // /pagespeed/audit — first in v7.1.0
-        wordpress_analyze_pagespeed: '7.1.0', // /analyze/pagespeed — first in v7.1.0
-        wordpress_abilities_gap_report: '7.1.0', // /abilities/gap-report — first in v7.1.0
-        wordpress_invoke_ability: '7.1.0', // /abilities/invoke — first in v7.1.0
-        wordpress_read_theme_file: '7.0.42', // /theme-files/* — @since 7.0.42
-        wordpress_write_theme_file: '7.0.42',
-        wordpress_append_theme_file: '7.0.42',
-    };
-    /**
-     * Capability negotiation Phase 2 (7.2.7): the feature flag each version-skewed
-     * tool needs. From plugin 7.4.20 the compatibility endpoint declares these
-     * flags from its LIVE registered REST routes, so this is an exact "does the
-     * route exist on this install" signal — more precise than the version map
-     * above and self-maintaining. The version map stays as the fallback for
-     * plugins older than 7.4.20, which do not declare per-capability features yet.
-     */
-    static TOOL_REQUIRED_FEATURE = {
-        wordpress_run_pagespeed_audit: 'pagespeed',
-        wordpress_analyze_pagespeed: 'pagespeed',
-        wordpress_abilities_gap_report: 'abilities',
-        wordpress_invoke_ability: 'abilities',
-        wordpress_read_theme_file: 'theme_files',
-        wordpress_write_theme_file: 'theme_files',
-        wordpress_append_theme_file: 'theme_files',
-    };
-    /** First plugin version that declares per-capability features (Phase 2). */
-    static FEATURE_DECL_MIN_PLUGIN_VERSION = '7.4.20';
-    /** True when version `a` is strictly older than `b` (both "x.y.z"). */
-    static versionLt(a, b) {
-        const pa = a.split('.').map((n) => parseInt(n, 10) || 0);
-        const pb = b.split('.').map((n) => parseInt(n, 10) || 0);
-        for (let i = 0; i < 3; i++) {
-            const x = pa[i] || 0;
-            const y = pb[i] || 0;
-            if (x !== y)
-                return x < y;
-        }
-        return false;
-    }
     async filterToolsByContext(tools) {
         if (!this.currentSite) {
             return tools; // No site connected — show everything.
@@ -4596,22 +4397,6 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                 return tools; // Can't fetch context — show everything.
             }
         }
-        // Capability negotiation: make sure the plugin version is known (cheap and
-        // memoized in the client) so the per-tool gate below can hide routes the
-        // connected plugin is too old to have. Never blocks the filter on failure.
-        try {
-            await this.currentSite.checkCompatibility();
-        }
-        catch {
-            /* non-fatal — fall through with whatever version we have (possibly null) */
-        }
-        const pluginVersion = this.currentSite.pluginVersion ?? null;
-        // Phase 2 (7.2.7): plugin 7.4.20+ declares per-capability features from its
-        // live REST routes; trust those exactly. Older plugins do not, so they fall
-        // back to the version map in the per-tool gate below.
-        const pluginFeatures = this.currentSite.pluginFeatures ?? [];
-        const declaresFeatures = !!pluginVersion &&
-            !RespiraWordPressServer.versionLt(pluginVersion, RespiraWordPressServer.FEATURE_DECL_MIN_PLUGIN_VERSION);
         const detectedBuilder = (context?.page_builder?.name || '').toLowerCase();
         const hasWooCommerce = Boolean(context?.woocommerce?.active || context?.addons?.woocommerce?.installed);
         return tools.filter((tool) => {
@@ -4636,20 +4421,6 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             if (name.startsWith('woocommerce_')) {
                 return hasWooCommerce;
             }
-            // Capability negotiation: hide tools whose plugin route the connected site
-            // does not expose (avoids rest_no_route 404s on version-skewed sites).
-            // Prefer the plugin's declared per-capability features (7.4.20+, computed
-            // from its live routes — exact), and fall back to the verified version map
-            // for older plugins that do not declare them. Both are conservative: a tool
-            // is hidden only on a positive signal that its route is absent.
-            const reqFeature = RespiraWordPressServer.TOOL_REQUIRED_FEATURE[name];
-            if (reqFeature && declaresFeatures) {
-                return pluginFeatures.includes(reqFeature);
-            }
-            const minPv = RespiraWordPressServer.TOOL_MIN_PLUGIN_VERSION[name];
-            if (minPv && pluginVersion && RespiraWordPressServer.versionLt(pluginVersion, minPv)) {
-                return false;
-            }
             // Everything else: always show.
             return true;
         });
@@ -4767,6 +4538,15 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                             items: { type: 'object' },
                             description: 'Alternative tag payload (IDs, names, slugs, or objects with id/name/slug)',
                         },
+                        global_unique_id: {
+                            type: 'string',
+                            description: 'GTIN/UPC/EAN (WooCommerce 9.2+). The strongest identifier for feeds and AI shopping.',
+                        },
+                        gallery_image_ids: {
+                            type: 'array',
+                            items: { type: 'number' },
+                            description: 'Gallery image attachment IDs; empty array clears the gallery',
+                        },
                     },
                     required: ['id'],
                 },
@@ -5487,6 +5267,320 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                 },
                 destructiveHint: true,
             },
+            // --- Subscriptions / Bookings / Memberships (addon v3.1, extensions) ---
+            {
+                name: 'woocommerce_list_subscriptions',
+                description: 'List WooCommerce Subscriptions, filterable by status, customer, or product. Requires the WooCommerce Subscriptions extension on the site.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        status: { type: 'string', description: 'active, on-hold, cancelled, pending-cancel, expired' },
+                        customer_id: { type: 'number' },
+                        product_id: { type: 'number' },
+                        per_page: { type: 'number' },
+                        page: { type: 'number' },
+                    },
+                },
+                readOnlyHint: true,
+            },
+            {
+                name: 'woocommerce_get_subscription',
+                description: 'Get one subscription with items, dates, and payment method.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'number', description: 'Subscription ID' },
+                    },
+                    required: ['id'],
+                },
+                readOnlyHint: true,
+            },
+            {
+                name: 'woocommerce_update_subscription_status',
+                description: 'Pause (on-hold), reactivate, or cancel a subscription. DRY-RUN BY DEFAULT: pass dry_run: false to apply. Transitions are validated against Subscriptions rules; snapshots taken.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'number', description: 'Subscription ID' },
+                        status: { type: 'string', description: 'active, on-hold, cancelled, pending-cancel' },
+                        note: { type: 'string' },
+                        dry_run: { type: 'boolean', description: 'Default TRUE: preview only' },
+                    },
+                    required: ['id', 'status'],
+                },
+                destructiveHint: true,
+            },
+            {
+                name: 'woocommerce_update_subscription_dates',
+                description: 'Move a subscription\'s next_payment, end, or trial_end dates (empty string clears). DRY-RUN BY DEFAULT: moving next_payment changes when the customer is charged.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'number', description: 'Subscription ID' },
+                        next_payment: { type: 'string', description: 'ISO 8601' },
+                        end: { type: 'string' },
+                        trial_end: { type: 'string' },
+                        dry_run: { type: 'boolean', description: 'Default TRUE: preview only' },
+                    },
+                    required: ['id'],
+                },
+                destructiveHint: true,
+            },
+            {
+                name: 'woocommerce_add_subscription_note',
+                description: 'Add a note to a subscription. Private by default; customer_note: true emails the customer.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'number', description: 'Subscription ID' },
+                        note: { type: 'string' },
+                        customer_note: { type: 'boolean', description: 'Default false (private note)' },
+                    },
+                    required: ['id', 'note'],
+                },
+            },
+            {
+                name: 'woocommerce_list_bookings',
+                description: 'List WooCommerce Bookings, filterable by status or product. Requires the WooCommerce Bookings extension on the site.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        status: { type: 'string', description: 'unpaid, pending-confirmation, confirmed, paid, cancelled, complete' },
+                        product_id: { type: 'number' },
+                        per_page: { type: 'number' },
+                        page: { type: 'number' },
+                    },
+                },
+                readOnlyHint: true,
+            },
+            {
+                name: 'woocommerce_get_booking',
+                description: 'Get one booking with times, persons, resource, and order linkage.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'number', description: 'Booking ID' },
+                    },
+                    required: ['id'],
+                },
+                readOnlyHint: true,
+            },
+            {
+                name: 'woocommerce_update_booking_status',
+                description: 'Confirm, mark paid, complete, or cancel a booking. DRY-RUN BY DEFAULT: status changes can trigger customer emails.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'number', description: 'Booking ID' },
+                        status: { type: 'string', description: 'unpaid, pending-confirmation, confirmed, paid, cancelled, complete' },
+                        dry_run: { type: 'boolean', description: 'Default TRUE: preview only' },
+                    },
+                    required: ['id', 'status'],
+                },
+                destructiveHint: true,
+            },
+            {
+                name: 'woocommerce_reschedule_booking',
+                description: 'Move a booking to a new time window. DRY-RUN BY DEFAULT with a conflict scan against other bookings on the same product; overlapping windows need force: true.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'number', description: 'Booking ID' },
+                        start: { type: 'string', description: 'ISO 8601' },
+                        end: { type: 'string', description: 'ISO 8601' },
+                        force: { type: 'boolean', description: 'Apply despite conflicts' },
+                        dry_run: { type: 'boolean', description: 'Default TRUE: preview only' },
+                    },
+                    required: ['id', 'start', 'end'],
+                },
+                destructiveHint: true,
+            },
+            {
+                name: 'woocommerce_list_membership_plans',
+                description: 'All membership plans with member counts. Requires the WooCommerce Memberships extension on the site.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {},
+                },
+                readOnlyHint: true,
+            },
+            {
+                name: 'woocommerce_list_memberships',
+                description: 'List user memberships, filterable by plan, customer, or status.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        plan_id: { type: 'number' },
+                        customer_id: { type: 'number' },
+                        status: { type: 'string', description: 'active, paused, cancelled, expired, pending' },
+                        per_page: { type: 'number' },
+                        page: { type: 'number' },
+                    },
+                },
+                readOnlyHint: true,
+            },
+            {
+                name: 'woocommerce_get_membership',
+                description: 'Get one user membership with plan, dates, and order linkage.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'number', description: 'Membership ID' },
+                    },
+                    required: ['id'],
+                },
+                readOnlyHint: true,
+            },
+            {
+                name: 'woocommerce_update_membership_status',
+                description: 'Pause, resume, or cancel a member\'s access. DRY-RUN BY DEFAULT: the change takes effect immediately for the member.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'number', description: 'Membership ID' },
+                        membership_action: { type: 'string', description: 'pause, resume, or cancel' },
+                        note: { type: 'string' },
+                        dry_run: { type: 'boolean', description: 'Default TRUE: preview only' },
+                    },
+                    required: ['id', 'membership_action'],
+                },
+                destructiveHint: true,
+            },
+            {
+                name: 'woocommerce_set_membership_end_date',
+                description: 'Move or clear a membership\'s expiry date (empty string = never expires). DRY-RUN BY DEFAULT.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'number', description: 'Membership ID' },
+                        end_date: { type: 'string', description: 'ISO 8601; empty string = never expires' },
+                        dry_run: { type: 'boolean', description: 'Default TRUE: preview only' },
+                    },
+                    required: ['id', 'end_date'],
+                },
+                destructiveHint: true,
+            },
+            // --- Assisted checkout (addon v3.1) ---
+            {
+                name: 'woocommerce_create_cart_link',
+                description: 'Create a signed multi-item cart URL for a shopper: their cart fills server-side and they land on this store\'s own checkout, with the order attributed to the agent source. The assisted-checkout layer that works while native agent checkout programs are gated.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        items: {
+                            type: 'array',
+                            items: { type: 'object' },
+                            description: 'Each: {product_id or variation_id, quantity}. Variable products need a variation_id.',
+                        },
+                        utm_source: { type: 'string', description: 'Attribution source, e.g. chatgpt.com (default ai-agent)' },
+                        replace_cart: { type: 'boolean', description: 'Empty the shopper\'s cart first (default false)' },
+                        expires_in_days: { type: 'number', description: 'Default 30; 0 = never expires' },
+                    },
+                    required: ['items'],
+                },
+            },
+            {
+                name: 'woocommerce_agent_orders_report',
+                description: 'Orders and revenue that arrived through agent cart links over a period, with a per-source breakdown.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        days: { type: 'number', description: 'Period in days (default 30, max 365)' },
+                    },
+                },
+                readOnlyHint: true,
+            },
+            // --- Readiness autofix (addon v3.1) ---
+            {
+                name: 'woocommerce_readiness_fixlist',
+                description: 'The catalog AI-readiness scan as an ordered work queue: weakest products first, each failing check paired with the tool and params that fix it. Work it top-down to raise the catalog score.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        limit: { type: 'number', description: 'Products to scan (default 100, max 500)' },
+                        target_score: { type: 'number', description: 'Skip products at or above this score (default 90)' },
+                    },
+                },
+                readOnlyHint: true,
+            },
+            {
+                name: 'woocommerce_set_image_alt',
+                description: 'Set alt text on a product\'s featured image (default) or a specific gallery image. The readiness check that fails most often.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'number', description: 'Product ID' },
+                        alt: { type: 'string' },
+                        attachment_id: { type: 'number', description: 'Optional gallery image; defaults to the featured image' },
+                    },
+                    required: ['id', 'alt'],
+                },
+                idempotentHint: true,
+            },
+            // --- Product feeds + llms.txt (addon v3.1) ---
+            {
+                name: 'woocommerce_configure_feed',
+                description: 'Read or update product feed settings (formats, cadence, countries, llms.txt) and get the public feed URLs. Call with no params to read.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        enabled_formats: {
+                            type: 'array',
+                            items: { type: 'string' },
+                            description: 'Any of: google, openai, meta, pinterest, tiktok, csv',
+                        },
+                        cadence: { type: 'string', description: 'hourly, twicedaily, or daily' },
+                        include_out_of_stock: { type: 'boolean' },
+                        target_countries: { type: 'array', items: { type: 'string' }, description: 'ISO 3166-1 alpha-2' },
+                        store_country: { type: 'string' },
+                        llms_txt: { type: 'boolean', description: 'Serve a store llms.txt at the site root' },
+                        rotate_token: { type: 'boolean', description: 'Rotate the secret feed URLs' },
+                    },
+                },
+                idempotentHint: true,
+            },
+            {
+                name: 'woocommerce_generate_feed',
+                description: 'Build the enabled product feeds now (batched in the background; the first batch runs immediately, so this works even when wp-cron is dead). Idempotent while a build is running.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        format: { type: 'string', description: 'Optional: enable and build one specific format' },
+                    },
+                },
+            },
+            {
+                name: 'woocommerce_get_feed_status',
+                description: 'Per-format feed URLs, row counts, generation times, running build progress, and wp-cron health warnings.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {},
+                },
+                readOnlyHint: true,
+            },
+            {
+                name: 'woocommerce_validate_feed',
+                description: 'Check a catalog sample against one feed format\'s requirements (identifiers, images, descriptions, titles, category mapping) with per-check failing product IDs, so the catalog tools can fix them.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        format: { type: 'string', description: 'google (default), openai, meta, pinterest, tiktok, csv' },
+                        limit: { type: 'number', description: 'Parent products to sample (default 100, max 200)' },
+                    },
+                },
+                readOnlyHint: true,
+            },
+            {
+                name: 'woocommerce_set_feed_category_mapping',
+                description: 'Map WooCommerce product categories to Google product categories for the feeds. Call with no params to list mapped and unmapped categories with product counts.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        mappings: { type: 'object', description: '{"<term_id>": "<google category id or full path>"}; empty string removes a mapping' },
+                    },
+                },
+                idempotentHint: true,
+            },
             // --- AI readiness (addon v3.0) ---
             {
                 name: 'woocommerce_product_ai_readiness',
@@ -5755,10 +5849,10 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     ? await client.getSiteContext()
                     : await client.getCompactSiteContext();
             case 'wordpress_list_sites': {
-                // Self-heal a stale list: re-pull the account's current sites so a site
-                // added on the dashboard after this server booted shows up without a
-                // re-paste or restart. Best-effort and throttled; never blocks the list.
-                const refresh = await this.refreshSitesFromAccount().catch(() => ({ added: [] }));
+                // Self-heal first so a site added on the dashboard after this server
+                // started shows up here without a reinstall or re-paste (throttled,
+                // best-effort, never throws).
+                await this.maybeSelfHealSiteList();
                 const allSites = Array.from(this.sites.values());
                 const visibleSites = allSites.filter((site) => this.isSiteAllowed(site));
                 // v6.17.2: surface hidden sites so the AI can explain
@@ -5771,13 +5865,6 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                 return {
                     sites: visibleSites.map((site) => this.getSiteSummary(site)),
                     active_site: this.getActiveSiteSummary(),
-                    ...(refresh.added.length > 0
-                        ? {
-                            refreshed_note: `Picked up ${refresh.added.length} newly added site${refresh.added.length === 1 ? '' : 's'} from your respira.press account: ${refresh.added.join(', ')}.${process.env.RESPIRA_CONFIG_B64?.trim()
-                                ? ' This server is pinned to the RESPIRA_CONFIG_B64 env var, so update that env to keep these sites after a restart.'
-                                : ''}`,
-                        }
-                        : {}),
                     ...(hiddenSites.length > 0
                         ? {
                             hidden_by_filter: hiddenSites,
@@ -5919,14 +6006,14 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                 return await client.getBuilderInlineSchemas(args.builder, args.types);
             case 'wordpress_inject_builder_content':
                 return hoistDroppedStylingWarnings({
-                    ...(await client.injectBuilderContent(args.builder, args.page_id, args.content, args.divi_version, args.edit_target, args.mode, args.confirm_replace, args.target_path, args.position)),
+                    ...(await client.injectBuilderContent(args.builder, args.page_id, args.content, args.divi_version, args.edit_target, args.mode, args.confirm_replace)),
                     respira_approvals_url: client.getApprovalsUrl(),
                 });
             case 'wordpress_make_responsive':
                 return await client.makeResponsive(args.page_id, args.dry_run || false);
             case 'wordpress_update_module':
                 return hoistDroppedStylingWarnings({
-                    ...(await client.updateModule(args.builder, args.page_id, args.module_identifier, args.updates, args.edit_target, args.confirm_live_edit)),
+                    ...(await client.updateModule(args.builder, args.page_id, args.module_identifier, args.updates, args.edit_target)),
                     respira_approvals_url: client.getApprovalsUrl(),
                 });
             case 'wordpress_validate_security':
@@ -5943,17 +6030,17 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     ...(await client.appendThemeFile(args.relative_path, args.content)),
                     respira_approvals_url: client.getApprovalsUrl(),
                 };
-            case 'wordpress_read_debug_log':
-                return await client.readDebugLog({
-                    lines: args.lines,
-                    level: args.level,
-                    since: args.since,
-                    grep: args.grep,
-                });
             case 'wordpress_switch_site': {
-                const newSite = this.sites.get(args.site_id);
+                let newSite = this.sites.get(args.site_id);
+                if (!newSite) {
+                    // The target may be a site added on the dashboard after this server
+                    // started. Self-heal once, then retry before giving up.
+                    await this.maybeSelfHealSiteList();
+                    newSite = this.sites.get(args.site_id);
+                }
                 if (!newSite) {
-                    throw new Error(`Site with ID "${args.site_id}" not found in configuration`);
+                    const available = Array.from(this.sites.keys()).join(', ') || '(none configured)';
+                    throw new Error(`Site with ID "${args.site_id}" not found in configuration. Available: ${available}`);
                 }
                 if (!this.isSiteAllowed(newSite)) {
                     throw new Error(`Site "${args.site_id}" is not in this MCP configuration group.`);
@@ -6176,8 +6263,6 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     confirm_live_edit: args.confirm_live_edit,
                     approval_token: args.approval_token,
                 });
-            case 'wordpress_detach_duplicate':
-                return await client.callRestV1('POST', `/duplicates/${args.duplicate_id}/detach`);
             // Options
             case 'wordpress_list_options':
                 return await client.listOptions(args.search);
@@ -6238,7 +6323,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             case 'wordpress_end_session':
                 return await client.callRestV2('POST', '/snapshots/session/end', {});
             case 'wordpress_apply_builder_patch':
-                return await client.applyBuilderPatch(args.builder, args.post_id, args.operations, args.include, args.edit_target, args.confirm_live_edit);
+                return await client.applyBuilderPatch(args.builder, args.post_id, args.operations, args.include, args.edit_target);
             case 'woocommerce_list_products':
                 return await client.woocommerceListProducts(args);
             case 'woocommerce_get_product':
@@ -6374,6 +6459,68 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                 const { id, ...payload } = args;
                 return await client.woocommerceCreateOrderRefund(id, payload);
             }
+            case 'woocommerce_list_subscriptions':
+                return await client.woocommerceListSubscriptions(args);
+            case 'woocommerce_get_subscription':
+                return await client.woocommerceGetSubscription(args.id);
+            case 'woocommerce_update_subscription_status': {
+                const { id, ...payload } = args;
+                return await client.woocommerceUpdateSubscriptionStatus(id, payload);
+            }
+            case 'woocommerce_update_subscription_dates': {
+                const { id, ...payload } = args;
+                return await client.woocommerceUpdateSubscriptionDates(id, payload);
+            }
+            case 'woocommerce_add_subscription_note': {
+                const { id, ...payload } = args;
+                return await client.woocommerceAddSubscriptionNote(id, payload);
+            }
+            case 'woocommerce_list_bookings':
+                return await client.woocommerceListBookings(args);
+            case 'woocommerce_get_booking':
+                return await client.woocommerceGetBooking(args.id);
+            case 'woocommerce_update_booking_status': {
+                const { id, ...payload } = args;
+                return await client.woocommerceUpdateBookingStatus(id, payload);
+            }
+            case 'woocommerce_reschedule_booking': {
+                const { id, ...payload } = args;
+                return await client.woocommerceRescheduleBooking(id, payload);
+            }
+            case 'woocommerce_list_membership_plans':
+                return await client.woocommerceListMembershipPlans(args);
+            case 'woocommerce_list_memberships':
+                return await client.woocommerceListMemberships(args);
+            case 'woocommerce_get_membership':
+                return await client.woocommerceGetMembership(args.id);
+            case 'woocommerce_update_membership_status': {
+                const { id, ...payload } = args;
+                return await client.woocommerceUpdateMembershipStatus(id, payload);
+            }
+            case 'woocommerce_set_membership_end_date': {
+                const { id, ...payload } = args;
+                return await client.woocommerceSetMembershipEndDate(id, payload);
+            }
+            case 'woocommerce_create_cart_link':
+                return await client.woocommerceCreateCartLink(args);
+            case 'woocommerce_agent_orders_report':
+                return await client.woocommerceAgentOrdersReport(args);
+            case 'woocommerce_readiness_fixlist':
+                return await client.woocommerceReadinessFixlist(args);
+            case 'woocommerce_set_image_alt': {
+                const { id, ...payload } = args;
+                return await client.woocommerceSetImageAlt(id, payload);
+            }
+            case 'woocommerce_configure_feed':
+                return await client.woocommerceConfigureFeed(args);
+            case 'woocommerce_generate_feed':
+                return await client.woocommerceGenerateFeed(args);
+            case 'woocommerce_get_feed_status':
+                return await client.woocommerceGetFeedStatus();
+            case 'woocommerce_validate_feed':
+                return await client.woocommerceValidateFeed(args);
+            case 'woocommerce_set_feed_category_mapping':
+                return await client.woocommerceSetFeedCategoryMapping(args);
             case 'woocommerce_product_ai_readiness':
                 return await client.woocommerceProductAiReadiness(args.id);
             case 'woocommerce_catalog_ai_readiness':
@@ -6477,16 +6624,8 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                 if (elementorResult !== null) {
                     return elementorResult;
                 }
-                // Check if this is an ACF tool. ACF tools live only under the
-                // respira_acf_* namespace (ACF_TOOL_NAMES + wordpress-client ACF_ROUTES
-                // are keyed by respira_acf_*), but normalizeToolName blindly rewrites
-                // respira_* -> wordpress_*, so by the time dispatchToolCall runs an ACF
-                // call arrives as wordpress_acf_*. Map it back so the guard matches and
-                // the plugin dispatch gets the name it expects. Without this every ACF
-                // tool fell through to "Unknown tool: wordpress_acf_*" (kenbi/Pedro,
-                // 2026-07-14; same class as the v7.1.0 fix that regressed).
-                const acfName = resolveAcfToolName(name);
-                if (acfName) {
+                // Check if this is an ACF tool.
+                if (ACF_TOOL_NAMES.has(name)) {
                     if (!(await this.isAcfAvailable())) {
                         return {
                             __respira_is_error: true,
@@ -6494,7 +6633,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                             hint: 'Install Advanced Custom Fields on the target site, then retry. ACF Pro is required for repeaters, flexible content, galleries, and options pages.'
                         };
                     }
-                    return await this.currentSite.dispatchAcfTool(acfName, args);
+                    return await this.currentSite.dispatchAcfTool(name, args);
                 }
                 // Check if this is a widget shortcut (wordpress_add_*).
                 if (name.startsWith('wordpress_add_')) {
@@ -6602,20 +6741,6 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                             type: 'number',
                             description: 'Position index within the target container (0-based). Pass -1 to append.',
                         },
-                        edit_target: {
-                            type: 'string',
-                            enum: ['live', 'duplicate'],
-                            description: 'Where to apply the write. "duplicate" (default) routes the edit to the Respira duplicate of the original (or auto-creates one) so changes go through the Respira → Changes approval flow before they reach the public page. "live" writes straight to the published original (requires Respira → Settings → Allow direct edit, or the original to be a draft / existing Respira duplicate). The response always reports the resolved target so you know exactly which post received the write.',
-                        },
-                        editTarget: {
-                            type: 'string',
-                            enum: ['live', 'duplicate'],
-                            description: 'Deprecated camelCase alias of edit_target. Prefer edit_target. Kept for back-compat with pre-v6.19.5 callers.',
-                        },
-                        confirm_live_edit: {
-                            type: 'boolean',
-                            description: 'Required when responding to a `confirmation_required` reply on the live path. Pass `true` alongside `edit_target: "live"` to acknowledge the published-original write. Has no effect when `edit_target` is `duplicate` or omitted.',
-                        },
                     },
                     required: ['post_id', 'identifier_type', 'identifier_value', 'target_container_path', 'position'],
                 },
@@ -6653,27 +6778,13 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                         post_id: { type: 'number', description: 'Page/post ID' },
                         identifier_type: {
                             type: 'string',
-                            enum: ['id', 'css_class', 'text', 'widget_type', 'global_id', 'path'],
-                            description: 'How to locate the element: "id" (element ID), "css_class" (CSS class name), "text" (visible text content), "widget_type" (widget/module type), "global_id" (cross-page global element ID), or "path" (position in the tree, e.g. "0.1.2"). Use "path" to remove an element that has no text and shares a class with its siblings, such as an empty wrapper left after its only child was removed; find_element returns each element\'s path in its candidate list.',
+                            enum: ['id', 'css_class', 'text', 'widget_type', 'global_id'],
+                            description: 'How to locate the element: "id" (element ID), "css_class" (CSS class name), "text" (visible text content), "widget_type" (widget/module type), or "global_id" (cross-page global element ID).',
                         },
                         identifier_value: {
                             type: 'string',
                             description: 'Value matching the chosen identifier_type (e.g. the element ID, the class name, the text to match).',
                         },
-                        edit_target: {
-                            type: 'string',
-                            enum: ['live', 'duplicate'],
-                            description: 'Where to apply the write. "duplicate" (default) routes the edit to the Respira duplicate of the original (or auto-creates one) so changes go through the Respira → Changes approval flow before they reach the public page. "live" writes straight to the published original (requires Respira → Settings → Allow direct edit, or the original to be a draft / existing Respira duplicate). The response always reports the resolved target so you know exactly which post received the write.',
-                        },
-                        editTarget: {
-                            type: 'string',
-                            enum: ['live', 'duplicate'],
-                            description: 'Deprecated camelCase alias of edit_target. Prefer edit_target. Kept for back-compat with pre-v6.19.5 callers.',
-                        },
-                        confirm_live_edit: {
-                            type: 'boolean',
-                            description: 'Required when responding to a `confirmation_required` reply on the live path. Pass `true` alongside `edit_target: "live"` to acknowledge the published-original write. Has no effect when `edit_target` is `duplicate` or omitted.',
-                        },
                     },
                     required: ['post_id', 'identifier_type', 'identifier_value'],
                 },
@@ -6723,20 +6834,6 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                             description: 'Array of element IDs in the desired order.',
                             items: { type: 'string' },
                         },
-                        edit_target: {
-                            type: 'string',
-                            enum: ['live', 'duplicate'],
-                            description: 'Where to apply the write. "duplicate" (default) routes the edit to the Respira duplicate of the original (or auto-creates one) so changes go through the Respira → Changes approval flow before they reach the public page. "live" writes straight to the published original (requires Respira → Settings → Allow direct edit, or the original to be a draft / existing Respira duplicate). The response always reports the resolved target so you know exactly which post received the write.',
-                        },
-                        editTarget: {
-                            type: 'string',
-                            enum: ['live', 'duplicate'],
-                            description: 'Deprecated camelCase alias of edit_target. Prefer edit_target. Kept for back-compat with pre-v6.19.5 callers.',
-                        },
-                        confirm_live_edit: {
-                            type: 'boolean',
-                            description: 'Required when responding to a `confirmation_required` reply on the live path. Pass `true` alongside `edit_target: "live"` to acknowledge the published-original write. Has no effect when `edit_target` is `duplicate` or omitted.',
-                        },
                     },
                     required: ['post_id', 'container_path', 'new_order'],
                 },