@wootsup/mcp 0.1.0 → 0.4.0

package/dist/modules/apimapper/workflows.js

@@ -4,6 +4,8 @@ import { request, hintFor } from "./client.js";
 import { unwrapEntity } from "./envelope.js";
 import { buildFlowGraph } from "./graph-builder.js";
 import { normalizeMergeStrategy } from "./normalizers.js";
+import { MERGE_STRATEGIES_INPUT, MERGE_JOIN_TYPES } from "./merge-constants.js";
+import { FILTER_OPERATORS } from "./filter-operators.js";
 /**
  * F-37 (W1.22): matches the default labels emitted by
  * `apimapper_flow_change_merge_strategy`. User-customised labels (which
@@ -14,8 +16,30 @@ import { normalizeMergeStrategy } from "./normalizers.js";
  * casings count as user-custom and are preserved as-is.
  */
 const DEFAULT_MERGE_LABEL_RE = /^Merge: (Concat|Join)$/;
-const SourceSpec = z.object({
-    connection: z.string().describe("Connection ID. Use apimapper_connection_list to find."),
+// F25 (2026-06-10): a local-source descriptor (CMS-native WordPress posts /
+// Joomla articles) — queried straight from the platform DB, no Connection.
+// Mirrors the `local-source` node-schema (`data.contentType`, limit, filters).
+const LocalSourceSpec = z.object({
+    content_type: z
+        .string()
+        .min(1)
+        .describe('Fully-qualified content type, e.g. "wordpress/post", "wordpress/page", "joomla/article". ' +
+        'The bare "post" is rejected at save time — always qualify with the platform prefix.'),
+    limit: z.number().int().min(1).optional().describe("Max items (clamped to tier max server-side)"),
+    filters: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe('Server-side filters (e.g. {"category":"news"})'),
+});
+const SourceSpec = z
+    .object({
+    // F25: `connection` is now OPTIONAL — a source is EITHER a connection
+    // source OR a local source. The .superRefine below enforces exactly-one.
+    connection: z
+        .string()
+        .optional()
+        .describe("Connection ID (API source). Use apimapper_connection_list to find."),
+    local_source: LocalSourceSpec.optional().describe("Local-source descriptor (CMS-native source). Mutually exclusive with `connection`."),
     endpoint: z.string().optional().describe('Endpoint id (e.g., "Scheduled Events")'),
     template_fields: z
         .record(z.string(), z.string())
@@ -23,16 +47,102 @@ const SourceSpec = z.object({
         .describe('Template field values (e.g., {"user_uri":"...","spreadsheet_id":"..."})'),
     items_path: z.string().optional().describe("Override items_path"),
     label: z.string().optional().describe("Display label for the source node"),
+})
+    .superRefine((s, ctx) => {
+    const hasConnection = typeof s.connection === "string" && s.connection !== "";
+    const hasLocal = !!s.local_source;
+    if (!hasConnection && !hasLocal) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "each source must set either `connection` (API source) or `local_source` (CMS source)",
+        });
+    }
+    if (hasConnection && hasLocal) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "a source must set `connection` OR `local_source`, not both",
+        });
+    }
 });
+// A8/F45 (2026-06-10): the merge join key is the make-or-break input of the
+// two-source task, and a wrong/incomparable key silently yields 0 rows. The
+// describe()s steer the agent to DISCOVER the key by sampling both sources
+// (apimapper_connection_data) before choosing it, and name the
+// connection_data sampling + the merge-two-sources-on-key topic explicitly so
+// the contract is learnable at the chokepoint, not only inside a skill topic.
 const MergeSpec = z.object({
-    strategy: z.enum(["join", "concat", "append"]).describe('Merge strategy ("append" alias for "concat")'),
-    joinKey: z.string().optional().describe("Left-side join key field (required for strategy=join)"),
-    joinKeyRight: z.string().optional().describe("Right-side join key field (defaults to joinKey)"),
-    joinType: z.enum(["left", "inner"]).default("left").describe("Join type"),
+    // F156 — strategy + joinType enums come from the shared merge-constants so
+    // the composite path and the raw node-schema path can never drift. 'append'
+    // is the customer-facing alias normalized to 'concat' downstream.
+    strategy: z.enum(MERGE_STRATEGIES_INPUT).describe('Merge strategy ("append" alias for "concat")'),
+    // A8/F45/F149 — surface the joinKey DISCOVERY hint right at the chokepoint,
+    // not only in the merge-two-sources-on-key skill topic. A cold agent has no
+    // idea WHICH field is the shared key; point it at connection_data to inspect
+    // the rows and call out the same-type requirement.
+    joinKey: z
+        .string()
+        .optional()
+        .describe("Left-side join key field (required for strategy=join). This is the field PRESENT IN BOTH " +
+        "sources' rows on which they join. DISCOVER it first: call apimapper_connection_data on " +
+        "EACH source and find a field whose values overlap and are the SAME type/format on both " +
+        "sides (a string \"P-100\" never equals a number 42). If the keys differ in shape, add a " +
+        "Transform before the merge to make them comparable (e.g. date-primitive transforms for a " +
+        "weekday name ↔ ISO date). See apimapper_get_skill({ topic: 'merge-two-sources-on-key' }) " +
+        "→ 'Discovering the join key'."),
+    joinKeyRight: z
+        .string()
+        .optional()
+        .describe("Right-side join key field (defaults to joinKey). Set this when the two sources name the " +
+        "same value differently (e.g. left 'property_id' vs right 'propertyId'). Sample both with " +
+        "apimapper_connection_data to confirm the values actually match."),
+    // F156 — full SQL-style join kinds (left/right/inner/outer), matching the
+    // raw node-schema mergeNodeSchema. The old composite enum only had
+    // left/inner, so an agent that learned joinType:'outer' on the raw graph
+    // path got a hard reject here.
+    joinType: z.enum(MERGE_JOIN_TYPES).default("left").describe("Join type (left/right/inner/outer)"),
+});
+// F53/F54 (2026-06-10): one-shot filter. `operator` is a CLOSED enum so the
+// schema itself advertises the valid vocabulary — a cold agent reaching for
+// `greater_than` / `>` / `<` is rejected at the zod boundary with the full set
+// named, instead of shipping a flow that silently yields 0 rows at render.
+// Mirrors FilterOperators::ALL (PHP) and FILTER_OPERATOR_VALUES (admin-ui).
+const FILTER_OPERATOR_ENUM = z.enum(FILTER_OPERATORS);
+const FilterConditionSpec = z.object({
+    field: z.string().min(1).describe('Field to filter on (e.g., "price", "media_type", "user.role")'),
+    operator: FILTER_OPERATOR_ENUM.describe('Comparison operator. Numeric: gt/gte/lt/lte. Text: equals/not_equals/contains/' +
+        'starts_with/ends_with. Set: in/not_in. Presence: exists/not_exists/empty/not_empty. ' +
+        'Symbolic operators (">", "<") are NOT accepted — use "gt"/"lt".'),
+    value: z
+        .union([z.string(), z.number(), z.boolean(), z.null(), z.array(z.union([z.string(), z.number()]))])
+        .optional()
+        .describe('Value to compare against. Omit for value-less operators (exists/not_exists/empty/not_empty; ' +
+        "for empty/not_empty, 0 and '0' are NOT empty). " +
+        'Numeric operators auto-coerce formatted strings like "$1,250,000".'),
+});
+// Accepts EITHER an inline single condition `{ field, operator, value }` OR a
+// `{ conditions: [...], logic }` list. buildFlowGraph()/normalizeFilterSpec()
+// re-validates and normalises both shapes.
+const FilterSpec = z.object({
+    field: z.string().min(1).optional().describe("Inline single-condition field (shorthand)"),
+    operator: FILTER_OPERATOR_ENUM.optional().describe("Inline single-condition operator (shorthand)"),
+    value: z
+        .union([z.string(), z.number(), z.boolean(), z.null(), z.array(z.union([z.string(), z.number()]))])
+        .optional()
+        .describe("Inline single-condition value (shorthand)"),
+    conditions: z.array(FilterConditionSpec).optional().describe("Explicit condition list (for 2+ conditions)"),
+    logic: z.enum(["and", "or"]).optional().describe('Combinator across conditions; defaults to "and"'),
 });
 const TransformSpec = z.object({
     expression: z.string().default("[*]").describe('JMESPath expression (e.g., "[*]" or "[*].{title:name,id:id}")'),
 });
+// F181 (2026-06-12): a transform is EITHER one TransformSpec OR an array of
+// them. The JMESPath depth cap (10 levels of bracket/pipe nesting) forces a
+// deeply-nested reshape to be SPLIT into two (or more) Transform nodes piped
+// together — each node's pipe resets the depth counter. The composite builder
+// chains an array as source(s) → [merge →] [filter →] t1 → t2 → … → output. A
+// single object and a one-element array produce an identical graph; an empty
+// array is treated as no transform at all.
+const TransformChainSpec = z.union([TransformSpec, z.array(TransformSpec)]);
 const OutputSpec = z.object({
     type: z.enum(["yootheme", "shortcode"]).default("yootheme").describe("Output type"),
     name: z.string().min(1).describe("Source name shown in YOOtheme dropdown"),
@@ -42,23 +152,67 @@ export function registerWorkflowTools(server) {
     // ── apimapper_flow_setup_with_sources ──────────────────────────────
     server.registerTool("apimapper_flow_setup_with_sources", {
         title: "Setup Multi-Source Flow (Composite)",
-        description: "Compose a complete flow from connections in one call. Sequence: " +
+        description: "Compose a complete flow from connections AND/OR CMS-native local sources in one call. " +
+            "Sequence: " +
             "(1) build graph via buildFlowGraph() — pure function, deterministic layout. " +
             "(2) POST /flows (creates row). " +
             "(3) POST /flows/{id}/compile (publishes to YOOtheme). " +
-            "Returns flow_id + per-step status. On partial failure, returns cleanup hint." +
-            "\n\nExample:\n  apimapper_flow_setup_with_sources({ name: 'Pexels + IG Gallery', sources: [{ connection: 'con_pexels' }, { connection: 'con_instagram' }], merge: { strategy: 'concat' }, output: { type: 'yootheme', name: 'Gallery' } })",
+            "Returns flow_id + per-step status. On partial failure, returns cleanup hint. " +
+            "Each source is EITHER an API connection (`connection`) OR a local source " +
+            "(`local_source: { content_type, limit?, filters? }`) — never both. Local " +
+            "content_type must be fully-qualified (e.g. 'wordpress/post', 'joomla/article'); " +
+            "a bare 'post' is rejected at save time." +
+            "\n\nConnection-source example:\n  apimapper_flow_setup_with_sources({ name: 'Pexels + IG Gallery', sources: [{ connection: 'con_pexels' }, { connection: 'con_instagram' }], merge: { strategy: 'concat' }, output: { type: 'yootheme', name: 'Gallery' } })" +
+            "\n\nLocal-source example:\n  apimapper_flow_setup_with_sources({ name: 'Latest Posts', sources: [{ local_source: { content_type: 'wordpress/post', limit: 12 } }], output: { type: 'yootheme', name: 'Posts' } })" +
+            "\n\nFilter example (one-shot — no raw graph editing needed):\n  apimapper_flow_setup_with_sources({ name: 'Warm EU Cities', sources: [{ connection: 'con_weather' }], filter: { field: 'temp', operator: 'gt', value: 10 }, output: { type: 'yootheme', name: 'Warm' } })" +
+            "\n\nFilter operators: equals, not_equals, contains, starts_with, ends_with, gt, gte, lt, lte, exists, not_exists, empty, not_empty, in, not_in. " +
+            "Use the named operators (gt/lt), NOT symbols (>/<). Numeric operators auto-coerce formatted strings ('$1,250,000'). " +
+            "The filter runs AFTER merge and BEFORE transform." +
+            "\n\nMulti-stage reshape? Pass `transform` as an ARRAY of stages — each stage gets its own depth budget." +
+            "\n\nMulti-transform example (JMESPath depth cap → split into chained transforms):\n  apimapper_flow_setup_with_sources({ name: 'Opening Hours', sources: [{ connection: 'con_hours' }], transform: [{ expression: '[1:]' }, { expression: '[*].{day: [0], hours: [1]}' }], output: { type: 'yootheme', name: 'Hours' } })" +
+            "\nPass `transform` as an ARRAY to chain N transform nodes (t1 → t2 → …). The pipe between chained nodes resets the JMESPath depth counter, so a reshape that overflows the depth cap (10) in one expression succeeds when split across two. A single `{ expression }` object still works for the one-transform case.",
         inputSchema: {
             name: z.string().min(1).describe('Flow name (appears in YOOtheme dropdown)'),
             description: z.string().optional().describe("Optional description"),
-            sources: z.array(SourceSpec).min(1).describe("1..N source connections"),
+            sources: z
+                .array(SourceSpec)
+                .min(1)
+                .describe("1..N sources — each a connection source OR a local_source (CMS-native)"),
             merge: MergeSpec.optional().describe("Merge config — required if sources.length >= 2"),
-            transform: TransformSpec.optional().describe("Optional Transform node"),
+            filter: FilterSpec.optional().describe("Optional Filter node (F54). Inline `{field, operator, value}` or `{conditions:[...], logic}`. " +
+                "Runs after merge, before transform. Unknown operators are rejected hard."),
+            transform: TransformChainSpec.optional().describe("Optional Transform node(s). Multi-stage reshape? Pass `transform` as an ARRAY of stages — " +
+                "each stage gets its own depth budget. A single `{ expression }` covers the one-reshape case; " +
+                "an ARRAY CHAINs multiple transforms (t1 → t2 → …). Chaining is the remedy for the " +
+                "JMESPath depth cap (10): split one over-nested expression into two shallow ones — the " +
+                "pipe between chained nodes resets the depth counter. " +
+                "See apimapper_get_skill({ topic: 'jmespath-cookbook' }) → 'Two-Transform split'."),
             output: OutputSpec.describe("Output node config"),
+            // Phase 2.7 (change protocol): this composite builds a whole flow, so
+            // the action is IMPLICIT (`flow.created`) — only `summary` is needed;
+            // the handler defaults the action. Threaded into the create POST body
+            // as `change: { summary }` (conditional-spread when present).
+            summary: z
+                .string()
+                .max(280)
+                .optional()
+                .describe("Optional one-line summary of this flow for the change history " +
+                '(e.g., "Set up a merged Pexels + Instagram gallery").'),
             compile: z.boolean().default(true).describe("Compile after save (= publish to YOOtheme)"),
+            autofix: z
+                .boolean()
+                .default(true)
+                .describe("Defaults to true. When compile:true, auto-repair empty-output-schema compile errors " +
+                "by calling detect-schema then retrying compile so the new source compiles and " +
+                "appears. Pass false to opt out (verbatim old behaviour — no detect-schema retry). " +
+                "Mirrors `flow_full_recompile_publish` autofix."),
         },
         annotations: creating({ title: "Setup Flow with Sources", openWorld: true }),
-    }, async ({ name, description, sources, merge, transform, output, compile }, extra) => {
+    }, async ({ name, description, sources, merge, filter, transform, output, compile, autofix, summary }, extra) => {
+        // C (2026-06-04): autofix defaults to true. Treat `undefined` (omitted
+        // arg / unit-test harness that bypasses the schema default) as the
+        // on-default; only an explicit `autofix:false` opts out.
+        const autofixEnabled = autofix !== false;
         // W3.5 — progress side-channel. `null` when the caller sent no
         // progressToken; `progress?.report(...)` then no-ops. Total steps:
         // build-graph + create + (compile when requested).
@@ -71,6 +225,7 @@ export function registerWorkflowTools(server) {
             graph = buildFlowGraph({
                 sources,
                 merge: merge,
+                filter: filter,
                 transform: transform,
                 output: output,
             });
@@ -78,8 +233,8 @@ export function registerWorkflowTools(server) {
         catch (e) {
             return formatResult({
                 error: e instanceof Error ? e.message : String(e),
-                context: { source_count: sources.length, has_merge: !!merge },
-                hint: "Check the validation rules in buildFlowGraph — typically missing merge for multi-source, or missing joinKey for strategy=join.",
+                context: { source_count: sources.length, has_merge: !!merge, has_filter: !!filter },
+                hint: "Check the validation rules in buildFlowGraph — typically missing merge for multi-source, missing joinKey for strategy=join, or an invalid filter operator (use gt/lt, not >/<).",
             }, true);
         }
         // Step 1: create
@@ -95,6 +250,9 @@ export function registerWorkflowTools(server) {
                 nodes: graph.nodes,
                 edges: graph.edges,
                 viewport: graph.viewport,
+                // Phase 2.7 — implicit action (`flow.created`); attach `change:
+                // { summary }` only when supplied so the body is unchanged otherwise.
+                ...(summary !== undefined ? { change: { summary } } : {}),
             }),
         });
         const createdFlow = unwrapEntity(createR.data, "flow");
@@ -104,7 +262,10 @@ export function registerWorkflowTools(server) {
                 status: createR.status,
                 errorCode: createR.errorCode,
                 context: { name, stage: "create" },
-                hint: hintFor(createR.errorCode),
+                // F83: pass the create error message so a JMESPath depth-limit 422
+                // (classifies to "unknown") routes to the two-transform-split
+                // remedy + jmespath-cookbook pointer, NOT the generic health hint.
+                hint: hintFor(createR.errorCode, createR.error),
             }, true);
         }
         const flowId = createdFlow.id;
@@ -116,9 +277,29 @@ export function registerWorkflowTools(server) {
         // does not include the full flow object.
         let compiled = false;
         let compileError;
+        const autofixActions = [];
         if (compile) {
             await progress?.report(2, totalSteps, "Compiling and publishing to YOOtheme…");
-            const compileR = await request(`/flows/${encodeURIComponent(flowId)}/compile`, { method: "POST" });
+            let compileR = await request(`/flows/${encodeURIComponent(flowId)}/compile`, { method: "POST" });
+            // F5 (W9b, 2026-05-29): autofix mirror of flow_full_recompile_publish.
+            // CODE_EMPTY_SCHEMA = 4 (PHP FlowCompilerException constant, frozen).
+            // On empty-schema error, call detect-schema then retry compile. This
+            // makes the composite tool self-healing on the most common compile
+            // failure (newly created flow has no output schema yet).
+            const COMPILER_CODE_EMPTY_SCHEMA = 4;
+            if (!compileR.success &&
+                autofixEnabled &&
+                compileR.errorBody?.compiler_error_code === COMPILER_CODE_EMPTY_SCHEMA) {
+                autofixActions.push("Detected empty output schema, running detect-schema");
+                const detectR = await request(`/flows/${encodeURIComponent(flowId)}/detect-schema`, { method: "POST" });
+                if (detectR.success) {
+                    autofixActions.push("Schema detected, retrying compile");
+                    compileR = await request(`/flows/${encodeURIComponent(flowId)}/compile`, { method: "POST" });
+                }
+                else {
+                    autofixActions.push(`Schema detection failed: ${detectR.error ?? "unknown"}; cannot retry compile`);
+                }
+            }
             if (!compileR.success) {
                 compileError = compileR.error;
                 steps.push(`2. Compile FAILED: ${compileR.error}`);
@@ -132,7 +313,8 @@ export function registerWorkflowTools(server) {
                 }
                 else {
                     compiled = true;
-                    steps.push("2. Compiled — flow visible in YOOtheme dropdown");
+                    const autofixSuffix = autofixActions.length > 0 ? " (autofix applied)" : "";
+                    steps.push(`2. Compiled — flow visible in YOOtheme dropdown${autofixSuffix}`);
                 }
             }
         }
@@ -142,10 +324,11 @@ export function registerWorkflowTools(server) {
                 flow_id: flowId,
                 compiled: false,
                 compile_error: compileError,
+                autofix_actions: autofixActions.length > 0 ? autofixActions : undefined,
                 steps,
                 next_action: "investigate_compile_error",
-                cleanup: `Call apimapper_flow_delete with id="${flowId}" + confirm=true to roll back the orphan, OR fix node config and call apimapper_flow_compile again.`,
-                hint: "Compile errors usually mean missing joinKey, invalid JMESPath, or missing connection. Use apimapper_flow_get to inspect node data.",
+                cleanup: `Roll back the orphan via apimapper_advanced({ tool: "apimapper_flow_delete", arguments: { id: "${flowId}", confirm: true } }), OR fix node config and recompile via apimapper_flow_full_recompile_publish.`,
+                hint: 'Compile errors usually mean missing joinKey, invalid JMESPath, or missing connection. Inspect node data via apimapper_advanced({ tool: "apimapper_flow_get", arguments: { id } }).',
             }, true);
         }
         await progress?.report(totalSteps, totalSteps, compiled ? "Flow created and published" : "Flow created");
@@ -158,8 +341,8 @@ export function registerWorkflowTools(server) {
             merge_strategy: merge ? normalizeMergeStrategy(merge.strategy) : null,
             steps,
             next: compiled
-                ? "Use apimapper_graph_preview to test items, or bind in YOOtheme Builder."
-                : "Call apimapper_flow_compile to publish.",
+                ? 'Test items via apimapper_advanced({ tool: "apimapper_graph_preview", arguments: { flow_id } }), or bind in the YOOtheme Builder.'
+                : "Publish via apimapper_flow_full_recompile_publish.",
         }, false, { maxChars: 3000 });
     });
     // ── apimapper_flow_change_merge_strategy ───────────────────────────
@@ -171,14 +354,24 @@ export function registerWorkflowTools(server) {
             "\n\nExample:\n  apimapper_flow_change_merge_strategy({ flow_id: 'flow_Z2fLg70M84', strategy: 'join', joinKey: 'id' })",
         inputSchema: {
             flow_id: z.string().describe("Flow ID. Use apimapper_flow_list to find."),
-            strategy: z.enum(["join", "concat", "append"]).describe("New merge strategy"),
+            // F156 — shared enums (see merge-constants.ts) keep this in lock-step
+            // with the raw node-schema + flow_setup_with_sources MergeSpec.
+            strategy: z.enum(MERGE_STRATEGIES_INPUT).describe("New merge strategy"),
             joinKey: z.string().optional().describe("Left-side join key (required for strategy=join)"),
             joinKeyRight: z.string().optional().describe("Right-side join key (defaults to joinKey)"),
-            joinType: z.enum(["left", "inner"]).optional().describe("Join type override"),
+            joinType: z.enum(MERGE_JOIN_TYPES).optional().describe("Join type override (left/right/inner/outer)"),
+            // Phase 2.7 (change protocol): the action is IMPLICIT (`merge.changed`)
+            // — only `summary` is needed; the handler defaults the action.
+            // Threaded into the PUT body as `change: { summary }`.
+            summary: z
+                .string()
+                .max(280)
+                .optional()
+                .describe('Optional one-line summary of this merge change (e.g., "Switched merge to join on id").'),
             compile: z.boolean().default(true).describe("Compile after save"),
         },
         annotations: mutating({ title: "Change Flow Merge Strategy", openWorld: true }),
-    }, async ({ flow_id, strategy, joinKey, joinKeyRight, joinType, compile }) => {
+    }, async ({ flow_id, strategy, joinKey, joinKeyRight, joinType, compile, summary }) => {
         const getR = await request(`/flows/${encodeURIComponent(flow_id)}`);
         if (!getR.success || !getR.data) {
             return formatResult({
@@ -196,7 +389,7 @@ export function registerWorkflowTools(server) {
             return formatResult({
                 error: "flow.nodes is not an array",
                 context: { flow_id, type: typeof flow.nodes },
-                hint: "Flow data shape unexpected. Use apimapper_flow_get to inspect.",
+                hint: 'Flow data shape unexpected. Inspect via apimapper_advanced({ tool: "apimapper_flow_get", arguments: { id: flow_id } }).',
             }, true);
         }
         const mergeNode = flow.nodes.find((n) => n.type === "merge");
@@ -238,7 +431,12 @@ export function registerWorkflowTools(server) {
         // `(putR.data as any)?.flow` before reading fields.
         const putR = await request(`/flows/${encodeURIComponent(flow_id)}`, {
             method: "PUT",
-            body: JSON.stringify({ nodes: flow.nodes }),
+            body: JSON.stringify({
+                nodes: flow.nodes,
+                // Phase 2.7 — implicit action (`merge.changed`); attach `change:
+                // { summary }` only when supplied so the body is unchanged otherwise.
+                ...(summary !== undefined ? { change: { summary } } : {}),
+            }),
         });
         if (!putR.success) {
             return formatResult({
@@ -246,7 +444,9 @@ export function registerWorkflowTools(server) {
                 status: putR.status,
                 errorCode: putR.errorCode,
                 context: { flow_id, stage: "update" },
-                hint: hintFor(putR.errorCode),
+                // F83: a depth-limit 422 can surface on this write path too — route
+                // the message to the two-transform-split remedy.
+                hint: hintFor(putR.errorCode, putR.error),
             }, true);
         }
         let compiled = false;
@@ -268,10 +468,10 @@ export function registerWorkflowTools(server) {
                 compiled: false,
                 compile_error: compileError,
                 next_action: "investigate_compile_error_or_revert",
-                cleanup: "Option A: fix the merge config (e.g., correct joinKey field name) and call apimapper_flow_compile. " +
-                    "Option B: revert via apimapper_flow_change_merge_strategy back to the previous strategy. " +
+                cleanup: "Option A: fix the merge config (e.g., correct joinKey field name) and recompile via apimapper_flow_full_recompile_publish. " +
+                    'Option B: revert via apimapper_advanced({ tool: "apimapper_flow_change_merge_strategy" }) back to the previous strategy. ' +
                     "The flow PUT succeeded — node data is updated but the flow won't appear in YOOtheme until compile passes.",
-                hint: "Compile errors usually mean wrong joinKey field name. Use apimapper_flow_get to inspect node data.",
+                hint: 'Compile errors usually mean wrong joinKey field name. Inspect node data via apimapper_advanced({ tool: "apimapper_flow_get", arguments: { id: flow_id } }).',
             }, true);
         }
         return formatResult({
@@ -298,20 +498,30 @@ export function registerWorkflowTools(server) {
     //      so the source appears in YOOtheme immediately without a second MCP
     //      package (matches audit recommendation A1 P1).
     //
-    // The default (`autofix:false`) preserves the v2.0.7 behaviour verbatim so
-    // existing tool callers do not see a behaviour change. The PHP layer
-    // surfaces `compiler_error_code` on compile-error responses (FlowHandler.php)
-    // so this branch reads a numeric class rather than string-matching messages.
+    // C (2026-06-04): the default is now `autofix:true`. Observed live in a
+    // Claude Desktop session: when the AI omits `autofix`, the old default
+    // (false) meant the YOOtheme schema cache was never flushed, so the source
+    // did NOT appear in the YOOtheme builder after publish. Flipping the default
+    // makes the autofix path (detect-schema retry + flush-yt) the normal path,
+    // so a plain `apimapper_flow_full_recompile_publish({id})` reliably publishes
+    // a visible source. `autofix:false` is now an explicit opt-out that restores
+    // the verbatim v2.0.7 behaviour (compile + admin-cache only, no detect-schema
+    // retry, no YT flush). The handler treats `autofix !== false` as enabled, so
+    // an omitted/undefined value behaves identically to the schema default at the
+    // real SDK call boundary. The PHP layer surfaces `compiler_error_code` on
+    // compile-error responses (FlowHandler.php) so this branch reads a numeric
+    // class rather than string-matching messages.
     server.registerTool("apimapper_flow_full_recompile_publish", {
         title: "Full Recompile + Cache Clear (Composite)",
-        description: "Compile a flow + invalidate admin cache in one call. Use after upstream API changes " +
-            "to ensure the flow + schema are fresh. Each step's success is surfaced separately, " +
-            "and a cache-clear failure does NOT silently downgrade compile success. " +
-            "Pass autofix:true to auto-repair common compile errors " +
-            "(empty output schema → re-detect; then retry compile) and to flush the " +
-            "YOOtheme schema cache so the source becomes visible in YOOtheme without " +
-            "a second MCP package." +
-            "\n\nExample:\n  apimapper_flow_full_recompile_publish({ id: 'flow_Z2fLg70M84', autofix: true })",
+        description: "Compile a flow + invalidate admin cache + flush the YOOtheme schema cache in one call. " +
+            "Use after upstream API changes to ensure the flow + schema are fresh. Each step's success " +
+            "is surfaced separately, and a cache-clear failure does NOT silently downgrade compile success. " +
+            "autofix defaults to true: it auto-repairs common compile errors " +
+            "(empty output schema → re-detect; then retry compile) AND flushes the " +
+            "YOOtheme schema cache so the source becomes visible in the YOOtheme builder — " +
+            "no second MCP package needed. Pass autofix:false to opt out (compile + admin-cache " +
+            "only, no detect-schema retry, no YT flush — the verbatim v2.0.7 behaviour)." +
+            "\n\nExample:\n  apimapper_flow_full_recompile_publish({ id: 'flow_Z2fLg70M84' })",
         inputSchema: {
             // L-6 (W3F-5): accept either `id` (canonical, matches every other
             // flow_* tool) or `flow_id` (legacy alias kept so existing callers
@@ -327,13 +537,24 @@ export function registerWorkflowTools(server) {
                 .describe("Deprecated alias for `id` — accepted for back-compat with pre-W3F-5 callers."),
             autofix: z
                 .boolean()
-                .default(false)
-                .describe("When true: on empty-schema compile error, call detect-schema and retry compile. " +
-                "On compile success, also flush the YOOtheme schema cache so the source surfaces " +
-                "in the YOOtheme builder. Default false preserves v2.0.7 behaviour."),
+                .default(true)
+                .describe("When true (default): on empty-schema compile error, call detect-schema and retry " +
+                "compile. On compile success, also flush the YOOtheme schema cache so the source " +
+                "surfaces in the YOOtheme builder. Pass false to opt out — compile + admin-cache " +
+                "only, no detect-schema retry, no YT flush (the verbatim v2.0.7 behaviour)."),
+            // Phase 2.7 (change protocol): recompile = (re)publish, so the action
+            // is IMPLICIT (`flow.published`) — only `summary` is needed; the handler
+            // defaults the action. Attached to the compile POST body as
+            // `change: { summary }` (the compile POST otherwise has no body).
+            summary: z
+                .string()
+                .max(280)
+                .optional()
+                .describe('Optional one-line summary of this publish for the change history ' +
+                '(e.g., "Republished after refreshing the upstream schema").'),
         },
         annotations: mutating({ title: "Full Recompile & Publish Flow", openWorld: true }),
-    }, async ({ id, flow_id: flowIdAlias, autofix }, extra) => {
+    }, async ({ id, flow_id: flowIdAlias, autofix, summary }, extra) => {
         // L-6 (W3F-5): resolve the dual-name input — `id` (canonical) takes
         // priority over the legacy `flow_id` alias when both are present.
         const flow_id = id ?? flowIdAlias;
@@ -346,20 +567,36 @@ export function registerWorkflowTools(server) {
         const steps = [];
         const errors = [];
         const autofixActions = [];
-        // W3.5: progress side-channel. autofix:true adds a third stage
+        // C (2026-06-04): autofix defaults to true. Treat `undefined` (caller
+        // omitted the arg, and the unit-test harness bypasses the schema default)
+        // identically to the on-default, so only an explicit `autofix:false`
+        // opts out. This keeps the handler faithful to the documented default
+        // whether or not the SDK applied the Zod default before dispatch.
+        const autofixEnabled = autofix !== false;
+        // W3.5: progress side-channel. autofix adds a third stage
         // (YOOtheme schema cache flush) so it's a 3-step pipeline.
-        const totalSteps = autofix ? 3 : 2;
+        const totalSteps = autofixEnabled ? 3 : 2;
         const progress = extra ? createProgressReporter(extra) : null;
         await progress?.report(0, totalSteps, "Recompiling flow…");
         // Stage 1: compile (with optional autofix retry)
-        let compileR = await request(`/flows/${encodeURIComponent(flow_id)}/compile`, { method: "POST" });
+        // Phase 2.7 — implicit action (`flow.published`). Attach `change:
+        // { summary }` only when supplied so the body is unchanged otherwise. The
+        // autofix-retry compile below does NOT re-attach it (one publish = one
+        // ChangeEvent; the first compile carries the summary).
+        let compileR = await request(`/flows/${encodeURIComponent(flow_id)}/compile`, summary !== undefined
+            ? {
+                method: "POST",
+                body: JSON.stringify({ change: { summary } }),
+                headers: { "Content-Type": "application/json" },
+            }
+            : { method: "POST" });
         // W2-3 autofix: on CODE_EMPTY_SCHEMA (4), call detect-schema then retry.
         // PHP FlowCompilerException::CODE_EMPTY_SCHEMA = 4 (constant frozen for
         // wire-stability across plugin versions; same number on WP + Joomla
         // because both share src/modules/core/src/Flow/FlowCompilerException.php).
         const COMPILER_CODE_EMPTY_SCHEMA = 4;
         if (!compileR.success &&
-            autofix === true &&
+            autofixEnabled &&
             compileR.errorBody?.compiler_error_code === COMPILER_CODE_EMPTY_SCHEMA) {
             autofixActions.push("Detected empty output schema, running detect-schema");
             const detectR = await request(`/flows/${encodeURIComponent(flow_id)}/detect-schema`, { method: "POST" });
@@ -377,9 +614,11 @@ export function registerWorkflowTools(server) {
                 status: compileR.status,
                 errorCode: compileR.errorCode,
                 compiler_error_code: compileR.errorBody?.compiler_error_code,
-                context: { flow_id, stage: "compile", autofix: !!autofix },
+                context: { flow_id, stage: "compile", autofix: autofixEnabled },
                 autofix_actions: autofixActions.length > 0 ? autofixActions : undefined,
-                hint: hintFor(compileR.errorCode),
+                // F83: the depth-limit overflow can surface late at compile /
+                // detect-schema time too — route its message to the split remedy.
+                hint: hintFor(compileR.errorCode, compileR.error),
             }, true);
         }
         steps.push("1. Flow compiled");
@@ -406,7 +645,7 @@ export function registerWorkflowTools(server) {
         // {flushed: false, error: <msg>} in the body when the buster threw.
         // We treat the request-level success/failure as authoritative and
         // record any flushed:false as a non-fatal warning step.
-        if (autofix === true) {
+        if (autofixEnabled) {
             await progress?.report(2, totalSteps, "Flushing YOOtheme schema cache…");
             const ytR = await request("/cache/flush-yt", { method: "POST" });
             if (ytR.success && ytR.data?.flushed !== false) {
@@ -434,11 +673,16 @@ export function registerWorkflowTools(server) {
             errors: ok ? undefined : errors,
             autofix_actions: autofixActions.length > 0 ? autofixActions : undefined,
             next: ok
-                ? autofix
+                ? autofixEnabled
                     ? "Flow recompiled, admin cache invalidated, and YOOtheme schema cache flushed. The source should now be visible in the YOOtheme builder."
-                    : "Flow is fresh in both admin + render layers. YOOtheme schema cache is NOT cleared by this tool; pass autofix:true (or call yootheme_clear_cache via the YOOtheme MCP) if the source does not appear in the builder."
-                : "Compile succeeded but a cache step had issues. Manually call apimapper_cache_invalidate scope=all if downstream still sees stale data.",
-        }, ok, { maxChars: 2500 });
+                    : "Flow is fresh in both admin + render layers. You passed autofix:false, so the YOOtheme schema cache was NOT cleared by this tool; re-run without autofix:false (the default flushes it) or call yootheme_clear_cache via the YOOtheme MCP if the source does not appear in the builder."
+                : 'Compile succeeded but a cache step had issues. Manually invalidate via apimapper_advanced({ tool: "apimapper_cache_invalidate", arguments: { scope: "all" } }) if downstream still sees stale data.',
+        }, 
+        // Wave-5 F7 fix (2026-05-29): formatResult's 2nd positional is `isError`.
+        // Pre-fix we passed `ok` here, which inverted the meaning — ok:true was
+        // tagged as `<error>` envelope. Pass `!ok` so success-with-no-errors
+        // renders as success and partial (errors.length > 0) renders as error.
+        !ok, { maxChars: 2500 });
     });
 }
 //# sourceMappingURL=workflows.js.map