@wootsup/mcp 0.1.0-rc.9 → 0.3.0

package/dist/modules/apimapper/flows.js

@@ -1,102 +1,123 @@
 import { z } from "zod";
-import { formatResult, autoFormatTable, readOnly, creating, mutating, destructive, } from "@getimo/mcp-toolkit";
+import { formatResult, tableResult, errorResult, readOnly, creating, mutating, destructive, createProgressReporter, elicitChoice, } from "@getimo/mcp-toolkit";
 import { request, hintFor } from "./client.js";
-import { nodeSchema } from "./node-schema.js";
+import { restErrorResult } from "./tool-result.js";
+import { toRows } from "./types.js";
+import { nodeSchema, edgeSchema, filterByNameQuery } from "./node-schema.js";
 import { unwrapEntity } from "./envelope.js";
-export function registerFlowTools(server) {
+import { ambiguityFallbackError, } from "./elicitation.js";
+import { buildFlowVisualization, SIDECAR_RESPONSE_MAX_CHARS, } from "./render/sidecar.js";
+import { FLOW_TABLE_COLUMNS, FLOW_COMPACT_COLUMNS, FLOW_LIST_NEXT_STEPS, isFlowCompiled, mapFlowRow, compactFlowRow, buildFlowDetail, buildFlowTraceTimeline, buildImportValidateDetail, } from "./flows-format.js";
+/**
+ * Register the flow CRUD + compile + detect-schema + trace + export/import
+ * tools.
+ *
+ * @param server      the tool registrar (essentials forward, rest captured).
+ * @param elicitation optional elicitation capability (the real McpServer, or
+ *   any `{ server: { elicitInput } }`). Supplied only by the host wiring in
+ *   index.ts. When omitted, `flow_compile` falls back to a structured error
+ *   on genuine flow ambiguity instead of prompting.
+ */
+export function registerFlowTools(server, elicitation) {
     // ── apimapper_flow_list ────────────────────────────────────────────
     server.registerTool("apimapper_flow_list", {
         title: "List Flows",
-        description: "List all API Mapper flows. Use apimapper_flow_get for full structure." +
-            "\n\nExample:\n  apimapper_flow_list({ limit: 25 })",
+        // rc.10 A5 (2026-05-19) — anti-thrash hint: AI was defaulting to
+        // limit:500 reflexively even though typical installs have <50 flows.
+        description: "List all API Mapper flows. The default limit of 100 already covers a typical install — " +
+            "most customers have 5-50 flows, increase the limit only if you have a specific reason. " +
+            "Use apimapper_flow_get for the full structure (nodes + edges) of a single flow." +
+            "\n\nExample:\n  apimapper_flow_list({})  // returns up to 100 flows in one call\n" +
+            "  apimapper_flow_list({ compiled: 'no' })  // filter to draft/incomplete flows",
         inputSchema: {
             source: z
                 .enum(["user", "demo", "library", "devtools", "all"])
                 .default("all")
                 .describe("Filter by origin"),
             compiled: z.enum(["any", "yes", "no"]).default("any").describe("Filter by compile status"),
-            limit: z.number().min(1).max(500).default(100).describe("Max items (1-500)"),
+            limit: z.number().min(1).max(500).default(100).describe("Max items (1-500). Default 100 already covers a typical install — do not raise unless you have evidence the list is larger."),
+            // W1.18 (F-32) — case-insensitive substring filter applied
+            // in-memory AFTER the upstream fetch (no per-name REST call).
+            // Min 2 chars at the schema boundary blocks the single-char
+            // probe-thrash pattern observed in the Maria-walkthrough logs.
+            name_query: z
+                .string()
+                .min(2)
+                .optional()
+                .describe("Case-insensitive substring filter on flow name. Applied in-memory after the upstream fetch — does NOT change the REST query. Must be 2+ characters; single-char probes are blocked. Combine with `source`/`compiled` for narrower results."),
         },
-        annotations: readOnly(),
-    }, async ({ source, compiled, limit }) => {
+        annotations: readOnly({ title: "List Flows", openWorld: true }),
+    }, async ({ source, compiled, limit, name_query }) => {
         const r = await request("/flows");
         if (!r.success) {
-            return formatResult({
-                error: r.error,
-                status: r.status,
-                errorCode: r.errorCode,
-                context: { source, compiled, limit },
-                hint: hintFor(r.errorCode),
-            }, true);
+            return restErrorResult(r, { source, compiled, limit, name_query }, { message: "flow list failed" });
         }
         let items = Array.isArray(r.data?.flows) ? r.data.flows : [];
-        // Derive `is_compiled` from REST shape: backend returns `compiledAt`
-        // (ISO timestamp string or null) and a `compiled` array of artifacts.
-        // Either indicates the flow has been compiled. Normalising here keeps
-        // downstream filtering + display logic uniform regardless of platform.
-        const isCompiledOf = (f) => {
-            if (typeof f.is_compiled === "boolean")
-                return f.is_compiled;
-            const raw = f;
-            if (typeof raw.compiledAt === "string" && raw.compiledAt.length > 0)
-                return true;
-            if (Array.isArray(raw.compiled) && raw.compiled.length > 0)
-                return true;
-            return false;
-        };
+        // `is_compiled` is derived from the REST shape (compiledAt / compiled[])
+        // by isFlowCompiled in flows-format.ts — shared between the filter and
+        // the row map so display + filtering stay uniform.
         if (source !== "all")
             items = items.filter((f) => f.source === source);
         if (compiled === "yes")
-            items = items.filter((f) => isCompiledOf(f));
+            items = items.filter((f) => isFlowCompiled(f));
         if (compiled === "no")
-            items = items.filter((f) => !isCompiledOf(f));
+            items = items.filter((f) => !isFlowCompiled(f));
+        // W1.18 (F-32) — filter BEFORE slice so limit applies to the matched
+        // subset, not the haystack. e.g. limit=10 + name_query='pexels'
+        // returns up to 10 pexels-matching flows, not the first 10 flows
+        // filtered to pexels-matching.
+        items = filterByNameQuery(items, name_query);
         items = items.slice(0, limit);
-        return autoFormatTable(items.map((f) => ({
-            id: f.id,
-            name: f.name,
-            source: f.source || "—",
-            nodes: f.node_count ?? "?",
-            compiled: isCompiledOf(f) ? "✓" : "✗",
-            types: (f.node_types || []).join(","),
-        })), {
-            columns: [
-                // Width 36 accommodates 30+ char IDs (e.g. legacy template
-                // flows like flow_calendly_jla_229fcbce95b7 = 30 chars).
-                // Truncation produces orphan IDs that downstream tools fail
-                // to resolve via flow_get. The +6 headroom matches the
-                // longest historical IDs without bloating the table.
-                { key: "id", label: "ID", width: 36 },
-                { key: "name", label: "NAME", width: 32 },
-                { key: "source", label: "SRC", width: 10 },
-                { key: "nodes", label: "N", width: 4 },
-                { key: "compiled", label: "C", width: 3 },
-                { key: "types", label: "TYPES", width: 36 },
-            ],
+        // W3.1 — tableResult: ASCII table for the LLM + typed DataTable payload
+        // for the Rich Card. T1 (W3.2): explicit compactColumns/compactMap drop
+        // NODES/TYPES at 21+ rows. IA-7: id stays llmOnly. IA-10: the footer
+        // carries the next-step guidance.
+        return tableResult(toRows(items), {
+            columns: FLOW_TABLE_COLUMNS,
+            compactColumns: FLOW_COMPACT_COLUMNS,
+            map: mapFlowRow,
+            compactMap: compactFlowRow,
             header: (n) => `${n} flows`,
-            footer: "Use apimapper_flow_get <id> for full structure.",
+            footer: FLOW_LIST_NEXT_STEPS,
         });
     });
     // ── apimapper_flow_get ─────────────────────────────────────────────
     server.registerTool("apimapper_flow_get", {
         title: "Get Flow",
-        description: "Fetch full flow definition (nodes, edges, viewport, compiled artifact)." +
+        description: "Get the full definition of one flow by ID (nodes, edges, viewport, and the " +
+            "compiled artifact). Use to inspect or debug a flow's graph before editing " +
+            "nodes/edges, changing a merge strategy, or re-compiling. " +
+            "Keywords: get flow, flow detail, inspect flow, show graph, nodes and edges, by ID. " +
+            "When NOT to use: to enumerate all flows use apimapper_flow_list; to change the " +
+            "graph use apimapper_flow_update then apimapper_flow_compile; to see the last " +
+            "run's per-step timing use apimapper_flow_trace." +
             "\n\nExample:\n  apimapper_flow_get({ id: 'flow_Z2fLg70M84' })",
         inputSchema: {
             id: z.string().describe('Flow ID (e.g., "flow_aCfOEpwCtVZnPFwPOwO61"). Use apimapper_flow_list.'),
         },
-        annotations: readOnly(),
+        annotations: readOnly({ title: "Get Flow", openWorld: true }),
     }, async ({ id }) => {
         // PHP wraps via fromControllerResponse($response, 'flow') →
         // `{success:true, flow:{…}}`. Audit: F-A2-01.
         const r = await request(`/flows/${encodeURIComponent(id)}`);
         if (!r.success) {
-            return formatResult({ error: r.error, status: r.status, errorCode: r.errorCode, context: { id }, hint: hintFor(r.errorCode) }, true);
+            return restErrorResult(r, { id }, { message: "flow get failed" });
         }
         const flow = unwrapEntity(r.data, "flow");
         if (!flow || Object.keys(flow).length === 0) {
-            return formatResult({ error: "flow not found", status: r.status, context: { id }, hint: hintFor("not_found") }, true);
+            return errorResult({
+                message: "flow not found",
+                code: r.status ? String(r.status) : "not_found",
+                suggestion: hintFor("not_found"),
+                details: { id },
+            });
         }
-        return formatResult(flow, false, { maxChars: 8000 });
+        // W3.1 — detailResult: grouped key-value detail for the Rich Card.
+        // IA-7: opaque IDs are copyable code entries. IA-10: a dedicated
+        // "Next steps" group carries the follow-up calls. The W2 flow
+        // visualization (ASCII diagram) is routed via detailResult.appendText
+        // so it reaches the LLM output without cluttering the Rich Card.
+        return buildFlowDetail(id, flow);
     });
     // ── apimapper_flow_create ──────────────────────────────────────────
     server.registerTool("apimapper_flow_create", {
@@ -116,15 +137,17 @@ export function registerFlowTools(server) {
                 'source.connectionId, local-source.contentType, filter.conditions, ' +
                 'transform.expression, merge.strategy ∈ {concat, join}.'),
             edges: z
-                .array(z.record(z.string(), z.unknown()))
-                .describe('Edge array. Each: {id, source, target, targetHandle?, sourceHandle?}. ' +
-                'For merge: targetHandle="input-A" (first input) or "input-B" (second).'),
+                .array(edgeSchema)
+                .describe('Edge array. Each: {id?, source, target, sourceHandle?, targetHandle?}. ' +
+                'source + target are required non-empty node-ids. ' +
+                'For merge nodes: targetHandle="input-0" (first input) or "input-1" (second). ' +
+                'Legacy "input-A"/"input-B" still accepted for backward-compat.'),
             viewport: z
                 .object({ x: z.number(), y: z.number(), zoom: z.number() })
                 .optional()
                 .describe('React-Flow viewport (e.g., {"x":0,"y":0,"zoom":1})'),
         },
-        annotations: creating(),
+        annotations: creating({ title: "Create Flow", openWorld: true }),
     }, async (input) => {
         // PHP fromControllerResponse(_, 'flow', 201) → {success, flow:{…}}.
         // Audit: F-A2-02.
@@ -133,23 +156,34 @@ export function registerFlowTools(server) {
             body: JSON.stringify(input),
         });
         if (!r.success) {
-            return formatResult({
-                error: r.error,
-                status: r.status,
-                errorCode: r.errorCode,
-                context: { name: input.name, node_count: input.nodes.length },
-                hint: hintFor(r.errorCode),
-            }, true);
+            return restErrorResult(r, { name: input.name, node_count: input.nodes.length }, { message: "flow create failed" });
         }
         const flow = unwrapEntity(r.data, "flow");
+        // Sidecar: flow_create always has input.nodes + input.edges
+        // (Zod-validated), so the visualization always renders unless
+        // APIMAPPER_AUTO_VISUALIZE_FLOWS="false". Additive + defensive —
+        // a render failure returns null and is omitted silently.
+        const viz = buildFlowVisualization({
+            nodes: input.nodes,
+            edges: input.edges,
+            id: flow?.id,
+            name: flow?.name,
+        });
         return formatResult({
             created: true,
             id: flow?.id,
             name: flow?.name,
             node_count: flow?.node_count,
             is_compiled: flow?.is_compiled ?? false,
-            next: "Call apimapper_flow_compile to publish to YOOtheme.",
-        }, false, { maxChars: 2000 });
+            ...(viz && { _visualization: viz }),
+            // F-3.1 (Pass-1 consolidation): IA-10 uniformity — next_steps[]
+            // (array, even if single-element) matches the structured
+            // next-step convention used by the list-result footers and the
+            // detailResult builders. Flat `next: string` was the holdout.
+            next_steps: ["Call apimapper_flow_compile to publish to YOOtheme."],
+        }, false, 
+        // Headroom for the sidecar — see SIDECAR_RESPONSE_MAX_CHARS.
+        { maxChars: SIDECAR_RESPONSE_MAX_CHARS });
     });
     // ── apimapper_flow_update ──────────────────────────────────────────
     server.registerTool("apimapper_flow_update", {
@@ -163,7 +197,7 @@ export function registerFlowTools(server) {
                 .record(z.string(), z.unknown())
                 .describe('Fields to patch (e.g., {"nodes":[...updated nodes...]} or {"name":"Renamed"})'),
         },
-        annotations: mutating(),
+        annotations: mutating({ title: "Update Flow", openWorld: true }),
     }, async ({ id, patch }) => {
         // PHP fromControllerResponse(_, 'flow') → {success, flow:{…}}. On 409 the
         // body shape is {currentVersion, error, code}. Audit: F-A2-03.
@@ -176,24 +210,39 @@ export function registerFlowTools(server) {
             // re-read + retry without a separate fetch.
             const envelope = (r.data && typeof r.data === "object" ? r.data : {});
             const currentVersion = typeof envelope.currentVersion === "number" ? envelope.currentVersion : undefined;
-            return formatResult({
-                error: r.error,
-                status: r.status,
-                errorCode: r.errorCode,
-                currentVersion,
-                context: { id },
-                hint: hintFor(r.errorCode),
-            }, true);
+            return restErrorResult(r, { id, ...(currentVersion !== undefined ? { currentVersion } : {}) }, { message: "flow update failed" });
         }
         const flow = unwrapEntity(r.data, "flow");
+        // Sidecar: flow_update's patch is a generic record. The
+        // visualization is CONDITIONAL — render only when the patch
+        // carries a full graph (both nodes and edges as arrays). A
+        // name-only / metadata-only patch has no graph to draw.
+        const patchObj = (patch && typeof patch === "object" ? patch : {});
+        const patchHasGraph = Array.isArray(patchObj.nodes) && Array.isArray(patchObj.edges);
+        const viz = patchHasGraph
+            ? buildFlowVisualization({
+                nodes: patchObj.nodes,
+                edges: patchObj.edges,
+                id: flow?.id,
+                name: flow?.name,
+            })
+            : null;
         return formatResult({
             updated: true,
             id: flow?.id,
             name: flow?.name,
             version: flow?.version,
             is_compiled: flow?.is_compiled,
-            next: flow?.is_compiled ? "Compile likely invalidated — call apimapper_flow_compile." : undefined,
-        }, false, { maxChars: 2000 });
+            ...(viz && { _visualization: viz }),
+            // F-3.1 (Pass-1 consolidation): IA-10 uniformity — flat next has
+            // been migrated to next_steps[]. Empty array when no recompile is
+            // needed (so the key shape stays uniform across all paths).
+            next_steps: flow?.is_compiled
+                ? ["Compile likely invalidated — call apimapper_flow_compile."]
+                : [],
+        }, false, 
+        // Headroom for the (conditional) sidecar — see SIDECAR_RESPONSE_MAX_CHARS.
+        { maxChars: SIDECAR_RESPONSE_MAX_CHARS });
     });
     // ── apimapper_flow_delete ──────────────────────────────────────────
     server.registerTool("apimapper_flow_delete", {
@@ -208,7 +257,7 @@ export function registerFlowTools(server) {
                 .default(false)
                 .describe("Must be true to execute. On confirm:false, returns a preview."),
         },
-        annotations: destructive(),
+        annotations: destructive({ title: "Delete Flow", openWorld: true }),
     }, async ({ id, confirm }) => {
         if (!confirm) {
             // PHP fromControllerResponse(_, 'flow') wraps as {success, flow:{…}}.
@@ -232,7 +281,7 @@ export function registerFlowTools(server) {
         }
         const r = await request(`/flows/${encodeURIComponent(id)}`, { method: "DELETE" });
         if (!r.success) {
-            return formatResult({ error: r.error, status: r.status, errorCode: r.errorCode, context: { id }, hint: hintFor(r.errorCode) }, true);
+            return restErrorResult(r, { id }, { message: "flow delete failed" });
         }
         return formatResult({ deleted: true, id }, false, { maxChars: 1500 });
     });
@@ -240,46 +289,150 @@ export function registerFlowTools(server) {
     server.registerTool("apimapper_flow_compile", {
         title: "Compile Flow",
         description: "Compile flow into executable pipeline (validation + topo sort + step generation + schema). " +
-            "Required before flow appears in YOOtheme." +
-            "\n\nExample:\n  apimapper_flow_compile({ id: 'flow_Z2fLg70M84' })",
+            "Required before flow appears in YOOtheme. " +
+            "If `id` is omitted, the flow is resolved automatically — when exactly one flow exists " +
+            "it is compiled; when several exist the user is asked to pick." +
+            "\n\nExample:\n  apimapper_flow_compile({ id: 'flow_Z2fLg70M84' })\n" +
+            "  apimapper_flow_compile({})  // resolves the flow when only one exists",
         inputSchema: {
-            id: z.string().describe("Flow ID. Use apimapper_flow_list to find."),
+            id: z
+                .string()
+                .optional()
+                .describe("Flow ID. Use apimapper_flow_list to find. Omit to resolve automatically " +
+                "when the install has a single flow."),
         },
-        annotations: mutating(),
-    }, async ({ id }) => {
+        annotations: mutating({ title: "Compile Flow", openWorld: true }),
+    }, async ({ id }, extra) => {
+        // W3.5 — coarse progress side-channel. `null` when the caller sent no
+        // progressToken; `progress?.report(...)` then no-ops.
+        const progress = extra ? createProgressReporter(extra) : null;
+        // W3.6 — resolve the flow when `id` is omitted. Exactly 1 flow →
+        // auto-pick; >1 → elicitChoice; 0 → structured error; elicitChoice
+        // null (unsupported client / declined) → structured candidate-list
+        // error. Done BEFORE the first progress report so a discovery round
+        // trip is not mistaken for compile progress.
+        let resolvedId = id;
+        if (!resolvedId) {
+            const lr = await request("/flows");
+            if (!lr.success) {
+                return restErrorResult(lr, {}, { message: "flow lookup failed" });
+            }
+            const flows = Array.isArray(lr.data?.flows) ? lr.data.flows : [];
+            if (flows.length === 0) {
+                return errorResult({
+                    message: "No flows exist to compile.",
+                    code: "flow_not_found",
+                    suggestion: "Create one with apimapper_flow_create, then compile it.",
+                    details: {},
+                });
+            }
+            if (flows.length === 1) {
+                resolvedId = flows[0].id;
+            }
+            else {
+                const candidates = flows.map((f) => ({
+                    id: f.id,
+                    label: f.name,
+                }));
+                const picked = elicitation
+                    ? await elicitChoice(elicitation, "Several flows exist. Pick the flow to compile.", candidates.map((c) => c.id))
+                    : null;
+                if (picked === null) {
+                    return ambiguityFallbackError({
+                        code: "flow_ambiguous",
+                        paramName: "id",
+                        what: "flows",
+                        candidates,
+                    });
+                }
+                resolvedId = picked;
+            }
+        }
+        await progress?.report(0, 1, "Compiling flow…");
         // PHP success body: {compiled: <CompiledFlow>, flowId: <id>}. Errors are
         // surfaced via HandlerResult::error(), not inside the 200 body. Audit:
         // F-A2-05 — the previous `errors[]` + `is_compiled===false` branch was
         // dead code.
-        const r = await request(`/flows/${encodeURIComponent(id)}/compile`, { method: "POST" });
+        const r = await request(`/flows/${encodeURIComponent(resolvedId)}/compile`, { method: "POST" });
         if (!r.success) {
-            return formatResult({ error: r.error, status: r.status, errorCode: r.errorCode, context: { id }, hint: hintFor(r.errorCode) }, true);
+            return restErrorResult(r, { id: resolvedId }, { message: "flow compile failed" });
         }
+        await progress?.report(1, 1, "Flow compiled");
         const dataObj = r.data && typeof r.data === "object" ? r.data : {};
         return formatResult({
             compiled: true,
-            id: dataObj.flowId ?? id,
-            next: "Source now appears in YOOtheme dropdown. Use apimapper_graph_preview to test items.",
+            id: dataObj.flowId ?? resolvedId,
+            // F-3.1 (Pass-1 consolidation): IA-10 uniformity — next_steps[]
+            // matches the structured shape used by other tools.
+            next_steps: [
+                "Source now appears in YOOtheme dropdown. Use apimapper_graph_preview to test items.",
+            ],
         }, false, { maxChars: 2500 });
     });
     // ── apimapper_flow_detect_schema ───────────────────────────────────
     server.registerTool("apimapper_flow_detect_schema", {
         title: "Detect Flow Schema",
         description: "Re-detect/refresh the output schema by sampling the upstream API. " +
-            "Use after upstream endpoint changes to surface new fields in the YOOtheme Builder." +
-            "\n\nExample:\n  apimapper_flow_detect_schema({ id: 'flow_Z2fLg70M84' })",
+            "Use after upstream endpoint changes to surface new fields in the YOOtheme Builder. " +
+            "For library-template connections that carry `{{placeholder}}` substitutions in their " +
+            "endpoint path (Google Sheets `{{spreadsheet_id}}`/`{{range}}`, Calendly `{{user_uri}}`, " +
+            "etc.), pass `template_fields` to override or supply the values at detect-time — " +
+            "mirrors the `apimapper_connection_data` contract." +
+            "\n\nExample:\n  apimapper_flow_detect_schema({ id: 'flow_Z2fLg70M84' })" +
+            "\n  apimapper_flow_detect_schema({ id: 'flow_X', template_fields: { spreadsheet_id: '1abc', range: 'Sheet1!A:G' } })",
         inputSchema: {
             id: z.string().describe("Flow ID. Use apimapper_flow_list to find."),
+            endpoint: z
+                .string()
+                .min(1)
+                .optional()
+                .describe('Override the source node\'s endpoint selection (e.g. "Get Values"). ' +
+                "Empty-string and whitespace-only values are rejected at the schema boundary."),
+            template_fields: z
+                .record(z.string(), z.union([z.string(), z.number(), z.boolean()]))
+                .optional()
+                .describe('Override values for `{{placeholder}}` substitutions in the endpoint URL ' +
+                '(e.g. { spreadsheet_id: "1abc", range: "Sheet1!A:G" }). Partial merge: ' +
+                "caller values win, persisted values for keys not mentioned here survive. " +
+                "Wave-12 F3 — restores parity with apimapper_connection_data."),
         },
-        annotations: mutating(),
-    }, async ({ id }) => {
-        // PHP success body: {schema:{fields:[...], …}, sourceConnectionId}.
+        annotations: mutating({ title: "Detect Flow Schema", openWorld: true }),
+    }, async ({ id, endpoint, template_fields }, extra) => {
+        // W3.5 — coarse progress side-channel. `null` when the caller sent no
+        // progressToken; `progress?.report(...)` then no-ops.
+        const progress = extra ? createProgressReporter(extra) : null;
+        await progress?.report(0, 1, "Sampling upstream API to detect schema…");
+        // PHP success body: {schema:{fields:[...], …}, sourceConnectionId,
+        // persisted, persist_error?}.
+        // H-2 fix (2026-05-27): backend now persists detected schema onto the
+        // output node so the next compile finds non-empty fields. `persisted`
+        // flag surfaces whether the write actually happened.
+        // Wave-12 F3 (Cold-AI #6, 2026-05-31): `endpoint` + `template_fields`
+        // now thread through to the PHP handler as sourceContext, restoring
+        // contract symmetry with apimapper_connection_data so library-template
+        // flows (Google Sheets etc.) can substitute URL placeholders at
+        // detect-time.
         // Audit: F-A2-06.
-        const r = await request(`/flows/${encodeURIComponent(id)}/detect-schema`, { method: "POST" });
+        const body = {};
+        if (endpoint !== undefined)
+            body.endpoint = endpoint;
+        if (template_fields !== undefined)
+            body.template_fields = template_fields;
+        const r = await request(`/flows/${encodeURIComponent(id)}/detect-schema`, {
+            method: "POST",
+            ...(Object.keys(body).length > 0
+                ? {
+                    body: JSON.stringify(body),
+                    headers: { "Content-Type": "application/json" },
+                }
+                : {}),
+        });
         if (!r.success) {
-            return formatResult({ error: r.error, status: r.status, errorCode: r.errorCode, context: { id }, hint: hintFor(r.errorCode) }, true);
+            return restErrorResult(r, { id }, { message: "flow detect-schema failed" });
         }
+        await progress?.report(1, 1, "Schema detected");
         const fields = Array.isArray(r.data?.schema?.fields) ? r.data.schema.fields : [];
+        const persisted = r.data?.persisted === true;
         return formatResult({
             detected: true,
             id,
@@ -287,6 +440,16 @@ export function registerFlowTools(server) {
             field_count: fields.length,
             fields: fields.slice(0, 50),
             schema: r.data?.schema,
+            persisted,
+            ...(r.data?.persist_error ? { persist_error: r.data.persist_error } : {}),
+            next_steps: persisted
+                ? [
+                    "Schema persisted to flow. Call apimapper_flow_compile next to publish.",
+                ]
+                : [
+                    "Schema detected but NOT persisted (no output node yet, or save failed). " +
+                        "Add an output node and call detect again, or inspect persist_error.",
+                ],
         }, false, { maxChars: 6000 });
     });
     // ── apimapper_flow_trace ───────────────────────────────────────────
@@ -298,43 +461,64 @@ export function registerFlowTools(server) {
         inputSchema: {
             id: z.string().describe("Flow ID. Use apimapper_flow_list to find."),
         },
-        annotations: readOnly(),
+        annotations: readOnly({ title: "Trace Flow", openWorld: true }),
     }, async ({ id }) => {
         // PHP success body: {trace: {steps: [...], total_ms}}. Audit: F-A2-07.
         const r = await request(`/flows/${encodeURIComponent(id)}/trace`);
         if (!r.success) {
-            return formatResult({ error: r.error, status: r.status, errorCode: r.errorCode, context: { id }, hint: hintFor(r.errorCode) }, true);
+            return restErrorResult(r, { id }, { message: "flow trace failed" });
         }
         const trace = r.data?.trace;
         const steps = Array.isArray(trace?.steps) ? trace.steps : [];
-        return formatResult({
-            id,
-            total_ms: trace?.total_ms,
-            step_count: steps.length,
-            steps: steps.slice(0, 50),
-        }, false, { maxChars: 6000 });
+        // W3.1 — timelineResult: the trace's per-step timing maps onto a
+        // chronological event timeline (display="event-timeline"). The step
+        // cap is preserved (50) so a pathological trace cannot bloat the
+        // response. buildFlowTraceTimeline does the defensive field reads.
+        return buildFlowTraceTimeline(id, steps.slice(0, 50), trace?.total_ms);
     });
     // ── apimapper_flow_export ──────────────────────────────────────────
+    // F-24 (W1.13): the export bundle contains connection REFERENCES only —
+    // never the linked credentials. Surface that explicitly in the response
+    // so downstream agents/customers cannot fatally assume "flow backup" =
+    // "credentials backup". The disclaimer is also advertised at tool
+    // registration time so AI clients see it without invoking.
+    const FLOW_EXPORT_CREDS_DISCLAIMER = "Credentials are NOT included in this bundle. The importing site must " +
+        "re-link credentials via apimapper_credential_create / apimapper_oauth_authorize_begin " +
+        "or via Admin-UI Credentials tab. Connection references in the bundle preserve the " +
+        "credential SHAPE (auth_type) but contain no secrets.";
     server.registerTool("apimapper_flow_export", {
         title: "Export Flow",
-        description: "Export a flow as a portable JSON bundle (incl. connection refs)." +
+        description: "Export a flow as a portable bundle for import on another site. " +
+            "Response includes `credentials_not_exported: true` and a `warning` string " +
+            "— credentials are NOT part of the bundle for security; the importing site " +
+            "must re-link them via apimapper_credential_create / apimapper_oauth_authorize_begin." +
             "\n\nExample:\n  apimapper_flow_export({ id: 'flow_Z2fLg70M84' })",
         inputSchema: {
             id: z.string().describe("Flow ID. Use apimapper_flow_list to find."),
         },
-        annotations: readOnly(),
+        annotations: readOnly({ title: "Export Flow", openWorld: true }),
     }, async ({ id }) => {
         // PHP wraps as `{export: {version, flow, connectionReferences, …}}`. Wave
         // 1C may rename `export` → `data` for round-trip symmetry; accept both
         // shapes so the round-trip works regardless of which side ships first.
         // Audit: F-A2-08.
-        const r = await request(`/flows/${encodeURIComponent(id)}/export`);
+        // Defense-in-depth (A5-P2 / W1.26 follow-up): the PHP backend is expected
+        // to strip credentials before export, but if that regresses, secrets must
+        // not land in the LLM context. `sanitize: true` routes the response
+        // through `credential-sanitizer.ts` (SECRET_KEYS covers auth_data /
+        // bearer_token / refresh_token / client_secret / etc.). Mirrors the
+        // belt-and-braces pattern at credentials.ts (credential_list / get).
+        const r = await request(`/flows/${encodeURIComponent(id)}/export`, {}, { sanitize: true });
         if (!r.success) {
-            return formatResult({ error: r.error, status: r.status, errorCode: r.errorCode, context: { id }, hint: hintFor(r.errorCode) }, true);
+            return restErrorResult(r, { id }, { message: "flow export failed" });
         }
         const envelope = (r.data && typeof r.data === "object" ? r.data : {});
         const bundle = envelope.data ?? envelope.export ?? envelope;
-        return formatResult(bundle ?? {}, false, { maxChars: 12000 });
+        return formatResult({
+            bundle: bundle ?? {},
+            credentials_not_exported: true,
+            warning: FLOW_EXPORT_CREDS_DISCLAIMER,
+        }, false, { maxChars: 12000 });
     });
     // ── apimapper_flow_import_validate ─────────────────────────────────
     server.registerTool("apimapper_flow_import_validate", {
@@ -347,7 +531,7 @@ export function registerFlowTools(server) {
                 .record(z.string(), z.unknown())
                 .describe("Flow bundle JSON (from apimapper_flow_export or external source)"),
         },
-        annotations: readOnly(),
+        annotations: readOnly({ title: "Validate Flow Import", openWorld: true }),
     }, async ({ bundle }) => {
         // PHP valid body: {valid, flowName, exportedFrom, connectionReferences}.
         // No `issues`/`warnings` keys — invalid path squashes errors to a single
@@ -355,14 +539,20 @@ export function registerFlowTools(server) {
         // Audit: F-A2-09.
         const r = await request("/flows/import/validate", { method: "POST", body: JSON.stringify(bundle) });
         if (!r.success) {
-            return formatResult({ error: r.error, status: r.status, errorCode: r.errorCode, context: {}, hint: hintFor(r.errorCode) }, true);
+            return restErrorResult(r, {}, { message: "flow import-validate failed" });
         }
-        return formatResult({
+        // W3.1 — detailResult: the validation result is a flat envelope
+        // ({valid, flowName, exportedFrom, connectionReferences}). The
+        // connection-reference array flattens to a count + per-item entries.
+        // IA-10: a "Next steps" group routes the AI to import or fix.
+        return buildImportValidateDetail({
             valid: r.data?.valid ?? true,
-            flow_name: r.data?.flowName,
-            exported_from: r.data?.exportedFrom,
-            connection_references: r.data?.connectionReferences ?? [],
-        }, false, { maxChars: 4000 });
+            flowName: r.data?.flowName,
+            exportedFrom: r.data?.exportedFrom,
+            connectionReferences: Array.isArray(r.data?.connectionReferences)
+                ? r.data.connectionReferences
+                : [],
+        });
     });
     // ── apimapper_flow_import ──────────────────────────────────────────
     server.registerTool("apimapper_flow_import", {
@@ -376,7 +566,7 @@ export function registerFlowTools(server) {
                 .describe("Flow bundle JSON (from apimapper_flow_export or external source)"),
             rename_to: z.string().optional().describe("Optional override for imported flow name"),
         },
-        annotations: creating(),
+        annotations: creating({ title: "Import Flow", openWorld: true }),
     }, async ({ bundle, rename_to }) => {
         // Server reads `$exportData = $data['data'] ?? $data` and then
         // `$exportData['flow']['name']`. Mutate bundle accordingly.
@@ -398,7 +588,7 @@ export function registerFlowTools(server) {
             body: JSON.stringify(body),
         });
         if (!r.success) {
-            return formatResult({ error: r.error, status: r.status, errorCode: r.errorCode, context: { rename_to }, hint: hintFor(r.errorCode) }, true);
+            return restErrorResult(r, { rename_to }, { message: "flow import failed" });
         }
         const flow = unwrapEntity(r.data, "flow");
         return formatResult({ imported: true, id: flow?.id, name: flow?.name }, false, { maxChars: 2000 });