@walkeros/mcp 3.1.0 → 3.2.0-next-1775064795590

package/dist/index.js

@@ -56,7 +56,7 @@ var SimulateOutputShape = {
     z.object({
       received: z.boolean().describe("Whether destination received the event"),
       calls: z.number().describe("Number of API calls made"),
-      payload: z.unknown().optional().describe("Full payload (only when verbose: true)")
+      payload: z.unknown().optional().describe("All intercepted API calls (only when verbose: true)")
     })
   ).optional().describe("Per-destination results"),
   capturedEvents: z.array(z.record(z.string(), z.unknown())).optional().describe("Events captured by source simulation"),
@@ -114,7 +114,6 @@ function registerFlowValidateTool(server2) {
           flow,
           path
         });
-        const summary = result.valid ? "Valid" : `Invalid: ${result.errors.length} errors, ${result.warnings.length} warnings`;
         const hints = result.valid ? {
           next: [
             "Use flow_simulate to test event flow",
@@ -126,7 +125,7 @@ function registerFlowValidateTool(server2) {
             "Read walkeros://reference/flow-schema for correct structure"
           ]
         };
-        return mcpResult(result, summary, hints);
+        return mcpResult(result, hints);
       } catch (error) {
         return mcpError(
           error,
@@ -172,16 +171,15 @@ function registerFlowBundleTool(server2) {
             content,
             flowName: flow
           });
-          const r = result2;
-          const size2 = r.totalSize ?? r.size;
-          const time2 = r.buildTime;
-          const summary2 = `Bundled${size2 ? ` (${formatBytes(size2)}` : ""}${time2 ? `, ${time2}ms)` : size2 ? ")" : ""}`;
-          return mcpResult2({ success: true, ...result2 }, summary2, {
-            next: [
-              "Use flow_simulate to test",
-              "Use api({ action: 'deploy' }) to publish"
-            ]
-          });
+          return mcpResult2(
+            { success: true, ...result2 },
+            {
+              next: [
+                "Use flow_simulate to test",
+                "Use api({ action: 'deploy' }) to publish"
+              ]
+            }
+          );
         }
         const result = await bundle(configPath, {
           flowName: flow,
@@ -191,7 +189,6 @@ function registerFlowBundleTool(server2) {
         if (!result) {
           return mcpResult2(
             { success: false, message: "Bundle produced no output" },
-            "Bundle produced no output",
             {
               warnings: [
                 "The build returned no result. The flow may be empty or misconfigured."
@@ -201,29 +198,29 @@ function registerFlowBundleTool(server2) {
           );
         }
         const output_ = result;
-        const size = output_.totalSize;
-        const time = output_.buildTime;
-        const summary = `Bundled${size ? ` (${formatBytes(size)}` : ""}${time ? `, ${time}ms)` : size ? ")" : ""}`;
-        return mcpResult2({ success: true, ...output_ }, summary, {
-          next: [
-            "Use flow_simulate to test",
-            "Use api({ action: 'deploy' }) to publish"
-          ]
-        });
+        return mcpResult2(
+          { success: true, ...output_ },
+          {
+            next: [
+              "Use flow_simulate to test",
+              "Use api({ action: 'deploy' }) to publish"
+            ]
+          }
+        );
       } catch (error) {
         return mcpError2(error, "Run flow_validate for detailed error messages");
       }
     }
   );
 }
-function formatBytes(bytes) {
-  if (bytes < 1024) return `${bytes} B`;
-  return `${(bytes / 1024).toFixed(1)} KB`;
-}
 
 // src/tools/simulate.ts
 import { z as z3 } from "zod";
-import { simulate } from "@walkeros/cli";
+import {
+  simulateSource,
+  simulateTransformer,
+  simulateDestination
+} from "@walkeros/cli";
 import { schemas as schemas3 } from "@walkeros/cli/dev";
 import { mcpResult as mcpResult3, mcpError as mcpError3 } from "@walkeros/core";
 function registerFlowSimulateTool(server2) {
@@ -231,11 +228,11 @@ function registerFlowSimulateTool(server2) {
     "flow_simulate",
     {
       title: "Simulate Flow",
-      description: 'Simulate events through a walkerOS flow without making real API calls. For destinations: event is a walkerOS event { name: "entity action", data: {...} }. For sources: event is { content: ..., trigger?: { type?, options? }, env?: {...} }. Use step to target a specific step. Use flow_examples to discover available test data.',
+      description: 'Simulate events through a walkerOS flow without making real API calls. For destinations: event is a walkerOS event { name: "entity action", data: {...} }. For sources: event is { content: ..., trigger?: { type?, options? }, env?: {...} }. Use step to target a specific step. Use flow_examples to discover available test data. IMPORTANT: Destinations with require (e.g. require: ["consent"]) stay pending until that collector event fires \u2014 simulation will error "not found" if require is not satisfied. Remove require from config or provide consent/user events before simulating. Separately, destinations with consent (e.g. consent: { marketing: true }) only receive events where the event includes matching consent. Mapping transforms event names and data at the destination level. Policy redacts or injects fields before mapping runs.',
       inputSchema: {
         configPath: schemas3.SimulateInputShape.configPath,
         event: z3.union([z3.record(z3.string(), z3.unknown()), z3.string()]).optional().describe(
-          "For destinations: { name, data }. For sources: { content, trigger?, env? }. Can also be a JSON string or file path."
+          "For destinations: { name, data, consent? }. Include consent (e.g. { marketing: true }) to satisfy destination consent requirements. For sources: { content, trigger?, env? }. Can also be a JSON string or file path."
         ),
         flow: schemas3.SimulateInputShape.flow,
         platform: schemas3.SimulateInputShape.platform,
@@ -257,24 +254,76 @@ function registerFlowSimulateTool(server2) {
             "event is required. For sources provide { content, trigger? }, for destinations provide { name, data }."
           );
         }
-        const raw = await simulate(configPath, event, {
-          json: true,
-          flow,
-          platform,
-          step
-        });
-        if (raw.capturedEvents) {
-          const eventCount = raw.capturedEvents.length;
+        if (!step) {
+          throw new Error(
+            'step is required. Specify a target like "source.browser", "destination.gtag", or "transformer.demo".'
+          );
+        }
+        let resolvedEvent = event;
+        if (typeof event === "string") {
+          try {
+            resolvedEvent = JSON.parse(event);
+          } catch {
+            throw new Error(
+              "Event string must be valid JSON. Got: " + event.substring(0, 50)
+            );
+          }
+        }
+        const dotIndex = step.indexOf(".");
+        if (dotIndex === -1) {
+          throw new Error(
+            `Invalid step format "${step}". Use "type.name" (e.g. "source.browser", "destination.gtag").`
+          );
+        }
+        const stepType = step.substring(0, dotIndex);
+        const stepId = step.substring(dotIndex + 1);
+        let result;
+        switch (stepType) {
+          case "source":
+            result = await simulateSource(configPath, resolvedEvent, {
+              sourceId: stepId,
+              flow,
+              silent: true
+            });
+            break;
+          case "transformer":
+            result = await simulateTransformer(
+              configPath,
+              resolvedEvent,
+              {
+                transformerId: stepId,
+                flow,
+                silent: true
+              }
+            );
+            break;
+          case "destination":
+            result = await simulateDestination(
+              configPath,
+              resolvedEvent,
+              {
+                destinationId: stepId,
+                flow,
+                silent: true
+              }
+            );
+            break;
+          default:
+            throw new Error(
+              `Unknown step type "${stepType}". Use "source", "transformer", or "destination".`
+            );
+        }
+        if (result.captured && result.captured.length > 0) {
+          const eventCount = result.captured.length;
           const summary2 = `Source captured ${eventCount} event${eventCount !== 1 ? "s" : ""}`;
           return mcpResult3(
             {
-              success: raw.success,
-              error: raw.error,
+              success: result.success,
+              error: result.error,
               summary: summary2,
-              capturedEvents: raw.capturedEvents,
-              duration: raw.duration
+              capturedEvents: result.captured,
+              duration: result.duration
             },
-            summary2,
             {
               next: eventCount > 0 ? [
                 "Use flow_simulate with a destination step to test downstream processing"
@@ -285,14 +334,20 @@ function registerFlowSimulateTool(server2) {
           );
         }
         const destinations = {};
-        if (raw.usage) {
-          for (const [name, calls] of Object.entries(raw.usage)) {
+        if (result.elbResult && typeof result.elbResult === "object" && "done" in result.elbResult && result.elbResult.done) {
+          const done = result.elbResult.done;
+          for (const name of Object.keys(done)) {
+            destinations[name] = { received: true, calls: 0 };
+          }
+        }
+        if (result.usage) {
+          for (const [name, calls] of Object.entries(result.usage)) {
             const summary2 = {
               received: calls.length > 0,
               calls: calls.length
             };
             if (verbose && calls.length > 0) {
-              summary2.payload = calls[calls.length - 1];
+              summary2.payload = calls;
             }
             destinations[name] = summary2;
           }
@@ -302,28 +357,30 @@ function registerFlowSimulateTool(server2) {
           (d) => d.received
         ).length;
         const warnings = [];
-        if (destCount === 0) {
-          warnings.push("No destinations found in flow configuration.");
-        }
-        if (destCount > 0 && receivedCount === 0) {
+        if (stepType === "destination" && destCount === 0) {
           warnings.push(
-            "No destinations received the event. Check: mapping keys use nested entity\u2192action structure, event name matches, consent is granted."
+            'Destination did not receive the event. Common causes: (1) destination config has consent: { marketing: true } but event lacks matching consent, (2) mapping rules do not match the event name, (3) policy redacted required fields. Add consent to the event: { name: "...", data: {...}, consent: { marketing: true } }.'
           );
         }
-        const summary = `${receivedCount}/${destCount} destinations received the event`;
-        const result = {
-          success: raw.success,
-          error: raw.error,
+        const summary = stepType === "transformer" ? `Transformer processed event` : `${receivedCount}/${destCount} destinations received the event`;
+        const resultObj = {
+          success: result.success,
+          error: result.error,
           summary,
           destinations: destCount > 0 ? destinations : void 0,
-          duration: raw.duration
+          duration: result.duration
         };
-        return mcpResult3(result, summary, {
+        return mcpResult3(resultObj, {
           next: ["Use flow_bundle to build for production"],
           ...warnings.length > 0 ? { warnings } : {}
         });
       } catch (error) {
-        return mcpError3(error, "Run flow_validate for detailed error messages");
+        const msg = error instanceof Error ? error.message : "";
+        let hint = "Run flow_validate for detailed error messages";
+        if (msg.includes("not found in collector")) {
+          hint = 'If this destination has require: ["consent"] or require: ["user"], it stays pending until that event fires. For simulation, either remove require from the config or simulate with a flow that omits require on the target destination.';
+        }
+        return mcpError3(error, hint);
       }
     }
   );
@@ -369,8 +426,7 @@ function registerFlowPushTool(server2) {
             "Check destination configuration and connectivity."
           );
         }
-        const summary = `Pushed event${result.duration ? ` (${result.duration}ms)` : ""}`;
-        return mcpResult4(result, summary);
+        return mcpResult4(result);
       } catch (error) {
         return mcpError4(
           error,
@@ -456,23 +512,20 @@ function registerFlowExamplesTool(server2) {
             }
           }
         }
-        const stepSet = new Set(examples.map((e) => e.step));
         const result = {
           flow: flowName,
           count: examples.length,
           examples
         };
-        const totalExamples = examples.length;
-        const summary = `${totalExamples} examples across ${stepSet.size} steps`;
         const hints = {
           next: ["Use flow_simulate with step and event to simulate"]
         };
-        if (totalExamples === 0) {
+        if (examples.length === 0) {
           hints.warnings = [
             "No examples found. Add examples to step definitions in your flow config for testing."
           ];
         }
-        return mcpResult5(result, summary, hints);
+        return mcpResult5(result, hints);
       } catch (error) {
         return mcpError5(error, "Check configPath \u2014 expected a flow.json file");
       }
@@ -511,13 +564,27 @@ async function fetchCatalog(filters) {
   }
   let entries;
   try {
-    entries = await fetchFromNpm();
+    entries = filters?.baseUrl ? await fetchCatalogFrom(filters.baseUrl, filters) : await fetchFromNpm();
   } catch {
-    return [];
+    try {
+      entries = await fetchFromNpm();
+    } catch {
+      return [];
+    }
   }
   cache = { entries, timestamp: Date.now() };
   return applyFilters(entries, filters);
 }
+async function fetchCatalogFrom(baseUrl, filters) {
+  const params = new URLSearchParams();
+  if (filters?.type) params.set("type", filters.type);
+  if (filters?.platform) params.set("platform", filters.platform);
+  const url = `${baseUrl}/api/packages${params.toString() ? `?${params}` : ""}`;
+  const res = await fetch(url, { signal: AbortSignal.timeout(15e3) });
+  if (!res.ok) throw new Error(`Catalog fetch failed: ${res.status}`);
+  const data = await res.json();
+  return data.catalog;
+}
 async function fetchFromNpm() {
   const res = await fetch(`${NPM_SEARCH_URL}?text=@walkeros/&size=250`, {
     signal: AbortSignal.timeout(1e4)
@@ -571,7 +638,7 @@ function registerPackageSearchTool(server2) {
     "package_search",
     {
       title: "Search Package",
-      description: "Browse walkerOS packages or look up a specific one. Without package name: returns catalog filtered by type/platform. With package name: returns metadata, hint keys, and example summaries.",
+      description: "Start here for package discovery. Never guess package names \u2014 use this tool first to find exact names. Without package name: returns catalog filtered by type/platform. With package name: returns metadata, hint keys, and example summaries.",
       inputSchema: {
         package: z6.string().min(1).optional().describe(
           "Exact npm package name for detailed lookup (e.g., @walkeros/web-destination-snowplow)"
@@ -591,16 +658,16 @@ function registerPackageSearchTool(server2) {
       }
     },
     async ({ package: packageName, type, platform, version }) => {
+      const baseUrl = process.env.APP_URL || void 0;
       if (!packageName) {
-        const catalog = await fetchCatalog({ type, platform });
+        const catalog = await fetchCatalog({ type, platform, baseUrl });
         const result = { catalog, count: catalog.length };
-        const summary = `${catalog.length} packages found`;
-        return mcpResult6(result, summary, {
+        return mcpResult6(result, {
           next: ["Use package_get for schemas and examples"]
         });
       }
       try {
-        const info = await fetchPackage(packageName, { version });
+        const info = await fetchPackage(packageName, { version, baseUrl });
         const result = {
           package: info.packageName,
           version: info.version,
@@ -610,8 +677,7 @@ function registerPackageSearchTool(server2) {
           hintKeys: info.hintKeys,
           exampleSummaries: info.exampleSummaries
         };
-        const summary = `${info.packageName} v${info.version}`;
-        return mcpResult6(result, summary, {
+        return mcpResult6(result, {
           next: ["Use package_get for schemas and examples"]
         });
       } catch (error) {
@@ -628,7 +694,7 @@ function registerGetPackageSchemaTool(server2) {
     "package_get",
     {
       title: "Get Package",
-      description: 'Fetch walkerOS package details from npm. By default returns schemas + hint texts + example summaries (lightweight). Use section parameter to get full content: "hints" (with code blocks), "examples" (full in/out data), or "all" (everything). Use package_search first to browse available packages.',
+      description: 'Requires exact package name \u2014 do not guess names, use package_search first to find them. Returns schemas + hint texts + example summaries by default (lightweight). Use section parameter for full content: "hints" (with code blocks), "examples" (full in/out data), or "all".',
       inputSchema: {
         package: z6.string().min(1).describe(
           "Exact npm package name (e.g., @walkeros/web-destination-snowplow)"
@@ -647,8 +713,9 @@ function registerGetPackageSchemaTool(server2) {
       }
     },
     async ({ package: packageName, version, section }) => {
+      const baseUrl = process.env.APP_URL || void 0;
       try {
-        const info = await fetchPackage(packageName, { version });
+        const info = await fetchPackage(packageName, { version, baseUrl });
         const mergedSchemas = {};
         if (info.type) {
           mergedSchemas.config = mergeConfigSchema(
@@ -685,10 +752,7 @@ function registerGetPackageSchemaTool(server2) {
         } else {
           result.exampleSummaries = info.exampleSummaries;
         }
-        const schemaCount = Object.keys(info.schemas).length;
-        const exampleCount = info.exampleSummaries.length;
-        const summary = `${info.packageName} \u2014 ${schemaCount} schemas, ${exampleCount} examples`;
-        return mcpResult6(result, summary);
+        return mcpResult6(result);
       } catch (error) {
         return mcpError6(
           error,
@@ -754,16 +818,12 @@ function registerFlowLoadTool(server2) {
       try {
         if (source) {
           const config = await loadJsonConfig2(source);
-          return mcpResult7(
-            config,
-            `Loaded flow from ${source}. Use flow_validate to check, or add-step prompt to modify.`,
-            {
-              next: [
-                "Use flow_validate to check",
-                "Use add-step prompt to modify"
-              ]
-            }
-          );
+          return mcpResult7(config, {
+            next: [
+              "Use flow_validate to check",
+              "Use add-step prompt to modify"
+            ]
+          });
         }
         if (!platform) {
           return mcpError7(
@@ -773,16 +833,12 @@ function registerFlowLoadTool(server2) {
           );
         }
         const skeleton = platform === "web" ? WEB_SKELETON : SERVER_SKELETON;
-        return mcpResult7(
-          skeleton,
-          `Created empty ${platform} flow. Use the add-step prompt to add sources, destinations, and transformers.`,
-          {
-            next: [
-              "Read walkeros://reference/flow-schema for config structure",
-              "Use add-step prompt to add sources and destinations"
-            ]
-          }
-        );
+        return mcpResult7(skeleton, {
+          next: [
+            "Read walkeros://reference/flow-schema for config structure",
+            "Use add-step prompt to add sources and destinations"
+          ]
+        });
       } catch (error) {
         const msg = error instanceof Error ? error.message : "";
         if (msg.includes("not found") || msg.includes("ENOENT"))
@@ -827,7 +883,6 @@ function registerFeedbackTool(server2) {
         if (anonymous === void 0 && explicitAnonymous === void 0) {
           return mcpResult8(
             { needsConsent: true },
-            'Before sending feedback, ask the user: "Would you like to include your user and project info with feedback? This is a one-time choice." Then call feedback again with the anonymous parameter set.',
             {
               next: [
                 "Ask the user if they want to include their info",
@@ -842,8 +897,8 @@ function registerFeedbackTool(server2) {
           writeConfig({ ...base, anonymousFeedback: anonymous });
         }
         const isAnonymous = explicitAnonymous ?? anonymous ?? true;
-        await feedback(text, { anonymous: isAnonymous, version: "3.1.0" });
-        return mcpResult8({ ok: true }, "Feedback sent. Thanks!");
+        await feedback(text, { anonymous: isAnonymous, version: "3.2.0-next-1775064795590" });
+        return mcpResult8({ ok: true });
       } catch (error) {
         return mcpError8(error);
       }
@@ -956,40 +1011,33 @@ function registerApiTool(server2) {
       } = params;
       try {
         let data;
-        let summary;
         switch (action) {
           // Auth
           case "whoami": {
             data = await whoami();
-            summary = `Authenticated as ${data.email}`;
             break;
           }
           // Projects
           case "project.list": {
             data = await listProjects();
-            summary = `${(data.projects ?? []).length} projects`;
             break;
           }
           case "project.get": {
             data = await getProject({ projectId });
-            summary = `Project "${data.name}"`;
             break;
           }
           case "project.create": {
             if (!name) throw new Error("name required for project.create");
             data = await createProject({ name });
-            summary = `Created project "${name}"`;
             break;
           }
           case "project.update": {
             if (!name) throw new Error("name required for project.update");
             data = await updateProject({ projectId, name });
-            summary = `Updated project "${name}"`;
             break;
           }
           case "project.delete": {
             data = await deleteProject({ projectId });
-            summary = `Deleted project ${projectId ?? "default"}`;
             break;
           }
           // Flows
@@ -1000,20 +1048,17 @@ function registerApiTool(server2) {
               order,
               includeDeleted
             });
-            summary = `${(data.flows ?? []).length} flows`;
             break;
           }
           case "flow.get": {
             if (!flowId) throw new Error("flowId required for flow.get");
             data = await getFlow({ flowId, projectId, fields });
-            summary = `Flow "${data.name}" (${flowId})`;
             break;
           }
           case "flow.create": {
             if (!name) throw new Error("name required for flow.create");
             if (!content) throw new Error("content required for flow.create");
             data = await createFlow({ name, content, projectId });
-            summary = `Created flow "${name}" (${data.id})`;
             break;
           }
           case "flow.update": {
@@ -1025,19 +1070,16 @@ function registerApiTool(server2) {
               projectId,
               mergePatch: patch ?? true
             });
-            summary = `Updated flow ${flowId}`;
             break;
           }
           case "flow.delete": {
             if (!flowId) throw new Error("flowId required for flow.delete");
             data = await deleteFlow({ flowId, projectId });
-            summary = `Deleted flow ${flowId}`;
             break;
           }
           case "flow.duplicate": {
             if (!flowId) throw new Error("flowId required for flow.duplicate");
             data = await duplicateFlow({ flowId, name, projectId });
-            summary = `Duplicated flow ${flowId}`;
             break;
           }
           // Deploy
@@ -1098,12 +1140,13 @@ function registerApiTool(server2) {
             const st = data.status;
             const deployData = data;
             if (st === "failed") {
-              const msg = `Deploy failed: ${deployData.errorMessage ?? "unknown error"}`;
-              return mcpResult9({ action, ok: false, data }, msg, {
-                next: ["Run flow_validate to check your configuration"]
-              });
+              return mcpResult9(
+                { action, ok: false, data },
+                {
+                  next: ["Run flow_validate to check your configuration"]
+                }
+              );
             } else {
-              summary = `Deployed flow ${flowId} \u2014 status: ${st}`;
               const publicUrl = deployData.publicUrl;
               const containerUrl = deployData.containerUrl;
               const deployType = deployData.type;
@@ -1116,9 +1159,12 @@ function registerApiTool(server2) {
                 nextHints.push(`Test: curl ${containerUrl}/health`);
               }
               if (nextHints.length > 0) {
-                return mcpResult9({ action, ok: true, data }, summary, {
-                  next: nextHints
-                });
+                return mcpResult9(
+                  { action, ok: true, data },
+                  {
+                    next: nextHints
+                  }
+                );
               }
             }
             break;
@@ -1134,7 +1180,6 @@ function registerApiTool(server2) {
             } catch {
               data = await getDeploymentBySlug({ slug: flowId });
             }
-            summary = `Deployment ${data.slug ?? flowId} \u2014 ${data.status}`;
             break;
           }
           case "deployment.list": {
@@ -1143,7 +1188,6 @@ function registerApiTool(server2) {
               type,
               status
             });
-            summary = `${(data.deployments ?? []).length} deployments`;
             break;
           }
           case "deployment.create": {
@@ -1152,14 +1196,12 @@ function registerApiTool(server2) {
                 "type (web/server) required for deployment.create"
               );
             data = await createDep({ type, label: name, projectId });
-            summary = `Created ${type} deployment ${data.slug}`;
             break;
           }
           case "deployment.delete": {
             if (!flowId)
               throw new Error("flowId (slug) required for deployment.delete");
             data = await deleteDep({ slug: flowId });
-            summary = `Deleted deployment ${flowId}`;
             break;
           }
           default:
@@ -1167,7 +1209,7 @@ function registerApiTool(server2) {
               `Unknown action: ${action}. Use one of: ${ACTIONS.join(", ")}`
             );
         }
-        return mcpResult9({ action, ok: true, data }, summary);
+        return mcpResult9({ action, ok: true, data });
       } catch (error) {
         const msg = error instanceof Error ? error.message : "";
         const name2 = error instanceof Error ? error.name : "";
@@ -1178,7 +1220,6 @@ function registerApiTool(server2) {
               ok: true,
               data: { status: "deploying", flowId }
             },
-            `Deploy in progress (timed out waiting). Use deployment.list with projectId to check status.`,
             {
               next: [
                 'Use api(action: "deployment.list") to check current status'
@@ -1504,9 +1545,10 @@ function registerAddStepPrompt(server2) {
               "4. Scaffold the step config using the package schemas \u2014 include required settings with placeholder values.",
               "5. Wire the step into the flow: add to packages section (with version if needed), connect via next/before chains if needed.",
               '6. For destinations: configure mapping using nested entity \u2192 action keys. Event "product add" maps to `{ "product": { "add": { name: "AddToCart" } } }`. Use the setup-mapping prompt for guidance.',
-              "7. Use flow_validate to verify the result.",
-              "8. For server sources: check if the package supports `ingest` configuration via package_get. Ingest extracts request metadata (IP, user-agent, headers) using mapping syntax. Transformers like fingerprint depend on ingest data.",
-              "9. When adding a transformer that uses ingest fields, verify the source has `ingest` configured \u2014 otherwise ingest fields resolve to empty values.",
+              '7. For destinations: if consent-gated loading is needed, add require: ["consent"] to config. Note: require delays initialization until a "walker consent" event fires. When simulating with flow_simulate, destinations with require will error "not found" \u2014 remove require temporarily or test without it. For per-event consent filtering, add consent: { marketing: true } to config.',
+              "8. Use flow_validate to verify the result.",
+              "9. For server sources: check if the package supports `ingest` configuration via package_get. Ingest extracts request metadata (IP, user-agent, headers) using mapping syntax. Transformers like fingerprint depend on ingest data.",
+              "10. When adding a transformer that uses ingest fields, verify the source has `ingest` configured \u2014 otherwise ingest fields resolve to empty values.",
               "",
               "Important:",
               "- Read the walkeros://reference/flow-schema resource to understand connection rules.",
@@ -1554,7 +1596,13 @@ function registerSetupMappingPrompt(server2) {
               "",
               'Mapping uses nested entity \u2192 action keys. Event "product add" maps to `{ "product": { "add": Rule } }`. Wildcards: `{ "*": { "view": Rule } }`.',
               "",
-              "Use $def references for shared mapping patterns across destinations."
+              "Use $def references for shared mapping patterns across destinations.",
+              "",
+              "Policy and consent in mapping:",
+              "- config.policy runs BEFORE mapping rules \u2014 use it to inject or redact fields on the event.",
+              "- rule.policy runs after config.policy but before data transformation \u2014 use for event-specific pre-processing.",
+              "- config.consent gates ALL events to this destination. rule.consent gates specific event types.",
+              "- Individual value configs support consent: { marketing: true } for field-level gating."
             ].join("\n")
           }
         }
@@ -1660,19 +1708,36 @@ function registerUseDefinitionsPrompt(server2) {
 var server = new McpServer(
   {
     name: "walkeros-flow",
-    version: "3.1.0"
+    version: "3.2.0-next-1775064795590"
   },
   {
     instructions: `walkerOS is an open-source, privacy-first event data collection platform. Define event pipelines as code using JSON flow configurations.
 
+## Rules
+
+- **Never guess package names.** Always use \`package_search\` first to find exact names, then \`package_get\` for details.
+- **Never construct flow configs from memory.** Read \`walkeros://reference/flow-schema\` and use \`package_get\` for package-specific schemas.
+- **Always validate.** Run \`flow_validate\` after every config change. If validation fails, fix and re-validate.
+- **Simulate before deploying.** Use \`flow_simulate\` to test with mocked API calls before \`flow_bundle\` or \`flow_push\`.
+
+## Workflow
+
+1. \`flow_load({ platform: "web" })\` or \`flow_load({ source: "./flow.json" })\` \u2014 create or load
+2. \`package_search({ type: "destination", platform: "web" })\` \u2014 discover packages
+3. \`package_get({ package: "..." })\` \u2014 read schemas, hints, examples
+4. Use the \`add-step\` prompt \u2014 guided step addition
+5. Use the \`setup-mapping\` prompt \u2014 event transformation config
+6. \`flow_validate({ type: "flow", input: "flow.json" })\` \u2014 verify
+7. \`flow_simulate({ configPath: "flow.json", event: "..." })\` \u2014 test
+8. \`flow_bundle({ configPath: "flow.json" })\` \u2014 build
+9. \`api({ action: "deploy", id: "cfg_..." })\` \u2014 deploy (requires WALKEROS_TOKEN)
+
 ## Architecture: Source \u2192 Collector \u2192 Destination(s)
 
 Every component in a flow is a **step**: sources capture events, transformers process them, destinations deliver them, stores provide shared state. Steps connect via \`next\` (pre-collector) and \`before\` (post-collector) chains.
 
 ## Flow Config Structure
 
-Every flow config follows this shape:
-
 \`\`\`json
 {
   "version": 3,
@@ -1686,38 +1751,28 @@ Every flow config follows this shape:
 }
 \`\`\`
 
-Event format: \`{ name: "entity action", data: {...}, entity: "...", action: "..." }\`. Sources convert raw input into this format.
-
-Key rules:
 - \`version: 3\` is required
 - Each flow must have exactly one of \`web: {}\` or \`server: {}\`
 - Destination settings go inside \`config.settings\`, not directly on the destination
-- Read \`walkeros://reference/flow-schema\` for the full annotated structure
-
-## Getting Started
-
-1. \`flow_load({ platform: "web" })\` or \`flow_load({ source: "./flow.json" })\` \u2014 create or load a flow (also accepts inline JSON strings or URLs)
-2. \`package_search({ type: "destination", platform: "web" })\` \u2014 discover available packages
-3. Use the \`add-step\` prompt to add sources, destinations, transformers, or stores
-4. Use the \`setup-mapping\` prompt to configure event transformations
-5. \`flow_validate({ type: "flow", input: "flow.json" })\` \u2014 verify configuration
-6. \`flow_simulate({ configPath: "flow.json", event: "..." })\` \u2014 test with mocked API calls
-7. \`flow_bundle({ configPath: "flow.json" })\` \u2014 build deployable JavaScript
-8. \`api({ action: "deploy", id: "cfg_..." })\` \u2014 deploy to walkerOS cloud (requires WALKEROS_TOKEN env var; unavailable without it)
-
-If validation fails, fix the reported errors and re-validate. Do not skip validation.
-
-## Reference Resources
-
-Read these before constructing configs manually: \`walkeros://reference/flow-schema\`, \`walkeros://reference/mapping\`, \`walkeros://reference/event-model\`, \`walkeros://reference/consent\`, \`walkeros://reference/variables\`, \`walkeros://reference/contract\`, \`walkeros://reference/examples\`.
+- Event format: \`{ name: "entity action", data: {...}, entity: "...", action: "..." }\`
 
 ## Key Concepts
 
-- **Steps** are sources, destinations, transformers, or stores \u2014 each backed by an npm package. Use \`package_search\` to browse, \`package_get\` for schemas and examples. \`package_get\` returns \`schemas.config\` \u2014 a merged JSON Schema combining base config fields (consent, require, logger, mapping, etc.) with the package's typed settings. Non-config schemas (mapping rules, utility schemas) remain as sibling keys.
 - **Mapping** transforms events using data/map/loop/set/condition rules. Same syntax on sources and destinations. Mapping rules use NESTED entity \u2192 action keying: event name "product add" maps to \`{ "product": { "add": Rule } }\`. Wildcards: \`{ "*": { "view": Rule } }\`.
 - **Contracts** define event schemas using entity-action keying. Can generate FROM mappings or scaffold mappings FROM contracts.
 - **Variables** ($var, $env, $def, $code, $store) enable DRY, environment-aware config. Use the \`use-definitions\` prompt to extract shared patterns.
-- **Consent** gates destinations, mapping rules, and individual fields. Privacy-first by design.`
+- **Consent** gates destinations, mapping rules, and individual fields. Privacy-first by design.
+
+## Simulation Tips
+
+- Destinations with \`require: ["consent"]\` stay **pending** until a \`"walker consent"\` event fires. Simulation will error "not found" for pending destinations \u2014 remove \`require\` from config when testing with \`flow_simulate\`.
+- Destinations with \`consent: { marketing: true }\` silently skip events that lack matching consent. Include \`consent\` in the event: \`{ name: "page view", data: {...}, consent: { marketing: true } }\`.
+- **Mapping** transforms event names and data at the destination level. Events without a matching mapping rule pass through unmodified.
+- **Policy** modifies the event before mapping runs \u2014 use it to inject computed fields or redact sensitive data.
+
+## Reference Resources
+
+Read these before constructing configs manually: \`walkeros://reference/flow-schema\`, \`walkeros://reference/mapping\`, \`walkeros://reference/event-model\`, \`walkeros://reference/consent\`, \`walkeros://reference/variables\`, \`walkeros://reference/contract\`, \`walkeros://reference/examples\`.`
   }
 );
 registerFlowValidateTool(server);