@walkeros/mcp 3.0.0-next-1773236214827 → 3.0.1

package/dist/index.js

@@ -56,17 +56,9 @@ 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("Transformed payload sent"),
-      errors: z.array(z.string()).optional().describe("Errors for this destination")
+      payload: z.unknown().optional().describe("Transformed payload sent")
     })
   ).optional().describe("Per-destination results"),
-  transformers: z.record(
-    z.string(),
-    z.object({
-      passed: z.boolean().describe("Whether event passed through"),
-      modified: z.boolean().describe("Whether event was modified")
-    })
-  ).optional().describe("Per-transformer results"),
   exampleMatch: z.object({
     name: z.string(),
     step: z.string(),
@@ -176,10 +168,18 @@ function registerFlowValidateTool(server2) {
             "Use flow_simulate to test event flow",
             "Use flow_bundle to build"
           ]
-        } : { next: ["Fix errors above, then run flow_validate again"] };
+        } : {
+          next: [
+            "Fix errors above, then run flow_validate again",
+            "Read walkeros://reference/flow-schema for correct structure"
+          ]
+        };
         return mcpResult(result, summary, hints);
       } catch (error) {
-        return mcpError(error);
+        return mcpError(
+          error,
+          "Check the input parameter \u2014 expected a JSON string, file path, or URL"
+        );
       }
     }
   );
@@ -236,14 +236,23 @@ function registerFlowBundleTool(server2) {
           stats: stats ?? true,
           buildOverrides: output ? { output } : void 0
         });
-        const output_ = result ?? {
-          success: true,
-          message: "Bundle created"
-        };
+        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."
+              ],
+              next: ["Run flow_validate to check your configuration"]
+            }
+          );
+        }
+        const output_ = result;
         const size = output_.totalSize;
         const time = output_.buildTime;
         const summary = `Bundled${size ? ` (${formatBytes(size)}` : ""}${time ? `, ${time}ms)` : size ? ")" : ""}`;
-        return mcpResult2(output_, summary, {
+        return mcpResult2({ success: true, ...output_ }, summary, {
           next: [
             "Use flow_simulate to test",
             "Use api({ action: 'deploy' }) to publish"
@@ -269,7 +278,7 @@ function registerFlowSimulateTool(server2) {
     "flow_simulate",
     {
       title: "Simulate Flow",
-      description: "Simulate events through a walkerOS flow without making real API calls. Processes events through the full pipeline including transformers and destinations, returning summarized per-destination results. Use the example parameter to load event input from a step example and compare output.",
+      description: 'Simulate events through a walkerOS flow without making real API calls. Events must be in walkerOS format (post-source): { name: "entity action", data: {...} }. Raw source input (dataLayer pushes, HTTP requests) must first be converted to walkerOS events. Check source package examples to see what events a source outputs. Use the example parameter to load event input from a step example and compare output.',
       inputSchema: schemas3.SimulateInputShape,
       outputSchema: SimulateOutputShape,
       annotations: {
@@ -297,8 +306,7 @@ function registerFlowSimulateTool(server2) {
             destinations[name] = {
               received: calls.length > 0,
               calls: calls.length,
-              payload: calls.length > 0 ? calls[calls.length - 1] : void 0,
-              errors: []
+              payload: calls.length > 0 ? calls[calls.length - 1] : void 0
             };
           }
         }
@@ -306,6 +314,17 @@ function registerFlowSimulateTool(server2) {
         const receivedCount = Object.values(destinations).filter(
           (d) => d.received
         ).length;
+        const warnings = [];
+        if (destCount === 0) {
+          warnings.push(
+            "No destinations found in flow configuration. Check that your flow defines at least one destination."
+          );
+        }
+        if (destCount > 0 && receivedCount === 0) {
+          warnings.push(
+            'No destinations received the event. Most common cause: mapping keys must be NESTED entity \u2192 action objects \u2014 event "product add" needs { "product": { "add": Rule } }, not "product.add". Also check event name match and consent settings.'
+          );
+        }
         const summary = `${receivedCount}/${destCount} destinations received the event`;
         const result = {
           success: raw.success,
@@ -316,7 +335,8 @@ function registerFlowSimulateTool(server2) {
           duration: raw.duration
         };
         return mcpResult3(result, summary, {
-          next: ["Use flow_bundle to build for production"]
+          next: ["Use flow_bundle to build for production"],
+          ...warnings.length > 0 ? { warnings } : {}
         });
       } catch (error) {
         return mcpError3(error, "Run flow_validate for detailed error messages");
@@ -351,10 +371,19 @@ function registerFlowPushTool(server2) {
           flow,
           platform
         });
+        if (!result.success) {
+          return mcpError4(
+            new Error(result.error || "Push failed"),
+            "Check destination configuration and network connectivity. For web destinations, use flow_simulate instead."
+          );
+        }
         const summary = `Pushed event${result.duration ? ` (${result.duration}ms)` : ""}`;
         return mcpResult4(result, summary);
       } catch (error) {
-        return mcpError4(error);
+        return mcpError4(
+          error,
+          "Check configPath and event format. For web destinations, use flow_simulate instead."
+        );
       }
     }
   );
@@ -433,12 +462,19 @@ function registerFlowExamplesTool(server2) {
           count: examples.length,
           examples
         };
-        const summary = `${examples.length} examples across ${stepSet.size} steps`;
-        return mcpResult5(result, summary, {
+        const totalExamples = examples.length;
+        const summary = `${totalExamples} examples across ${stepSet.size} steps`;
+        const hints = {
           next: ["Use flow_simulate with example parameter to test"]
-        });
+        };
+        if (totalExamples === 0) {
+          hints.warnings = [
+            "No examples found. Add examples to step definitions in your flow config for testing."
+          ];
+        }
+        return mcpResult5(result, summary, hints);
       } catch (error) {
-        return mcpError5(error);
+        return mcpError5(error, "Check configPath \u2014 expected a flow.json file");
       }
     }
   );
@@ -668,7 +704,7 @@ function registerPackageSearchTool(server2) {
         ),
         version: z4.string().optional().describe("Package version for detailed lookup (default: latest)")
       },
-      outputSchema: PackageSearchOutputShape,
+      // No outputSchema: browse mode returns {catalog, count}, lookup returns metadata — incompatible shapes
       annotations: {
         readOnlyHint: true,
         destructiveHint: false,
@@ -679,8 +715,9 @@ function registerPackageSearchTool(server2) {
     async ({ package: packageName, type, platform, version }) => {
       if (!packageName) {
         const catalog = filterRegistry({ type, platform });
+        const result = { catalog, count: catalog.length };
         const summary = `${catalog.length} packages found`;
-        return mcpResult6(catalog, summary, {
+        return mcpResult6(result, summary, {
           next: ["Use package_get for schemas and examples"]
         });
       }
@@ -700,7 +737,10 @@ function registerPackageSearchTool(server2) {
           next: ["Use package_get for schemas and examples"]
         });
       } catch (error) {
-        return mcpError6(error);
+        return mcpError6(
+          error,
+          "Package not found. Use package_search without parameters to browse available packages."
+        );
       }
     }
   );
@@ -760,7 +800,10 @@ function registerGetPackageSchemaTool(server2) {
         const summary = `${info.packageName} \u2014 ${schemaCount} schemas, ${exampleCount} examples`;
         return mcpResult6(result, summary);
       } catch (error) {
-        return mcpError6(error);
+        return mcpError6(
+          error,
+          "Use package_search to browse available package names."
+        );
       }
     }
   );
@@ -771,7 +814,7 @@ import { z as z5 } from "zod";
 import { loadJsonConfig as loadJsonConfig2 } from "@walkeros/cli";
 import { mcpResult as mcpResult7, mcpError as mcpError7 } from "@walkeros/core";
 var WEB_SKELETON = {
-  version: 1,
+  version: 3,
   flows: {
     default: {
       web: {},
@@ -782,7 +825,7 @@ var WEB_SKELETON = {
   }
 };
 var SERVER_SKELETON = {
-  version: 1,
+  version: 3,
   flows: {
     default: {
       server: {},
@@ -806,6 +849,10 @@ function registerFlowLoadTool(server2) {
           "Platform for new flows. Required when source is omitted. web = browser tracking, server = Node.js HTTP."
         )
       },
+      outputSchema: {
+        version: z5.number().describe("Flow config version"),
+        flows: z5.record(z5.string(), z5.unknown()).describe("Flow definitions")
+      },
       annotations: {
         readOnlyHint: true,
         destructiveHint: false,
@@ -839,7 +886,12 @@ function registerFlowLoadTool(server2) {
         return mcpResult7(
           skeleton,
           `Created empty ${platform} flow. Use the add-step prompt to add sources, destinations, and transformers.`,
-          { next: ["Use add-step prompt to add sources and destinations"] }
+          {
+            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 : "";
@@ -1068,7 +1120,10 @@ function registerApiTool(server2) {
             const st = data.status;
             const deployData = data;
             if (st === "failed") {
-              summary = `Deploy failed: ${deployData.errorMessage ?? "unknown error"}`;
+              const msg = `Deploy failed: ${deployData.errorMessage ?? "unknown error"}`;
+              return mcpResult8({ action, ok: false, data }, msg, {
+                next: ["Run flow_validate to check your configuration"]
+              });
             } else {
               summary = `Deployed flow ${id} \u2014 status: ${st}`;
               const publicUrl = deployData.publicUrl;
@@ -1193,70 +1248,20 @@ function registerPackageSchemaResources(server2) {
 }
 
 // src/resources/references.ts
-var FLOW_SCHEMA_REFERENCE = {
-  structure: {
-    version: "1 (required, use 1 for new flows)",
-    flows: {
-      "<flowName>": {
-        "web: {} | server: {}": "Platform marker (exactly one, use empty object as value)",
-        packages: "Record<packageName, {} | { path?, imports? }> \u2014 all referenced packages",
-        sources: "Record<name, { package, config?, env?, next? }> \u2014 event capture",
-        destinations: "Record<name, { package, config?, env?, mapping?, before? }> \u2014 event delivery",
-        transformers: "Record<name, { package, config?, env?, next? }> \u2014 event processing",
-        stores: "Record<name, { package, config?, env? }> \u2014 key-value storage",
-        collector: "{ consent?, globals? } \u2014 collector settings (optional)"
-      }
-    },
-    variables: "Record<string, string> \u2014 shared variables (optional)",
-    definitions: "Record<string, object> \u2014 reusable definitions (optional)",
-    contract: "Event contract for validation (optional)"
-  },
-  connectionRules: [
-    'Sources have `next` \u2192 links to pre-collector transformer chain (e.g., next: "transformerName")',
-    'Destinations have `before` \u2192 links to post-collector transformer chain (e.g., before: "transformerName")',
-    'Transformers have `next` \u2192 chains to next transformer (e.g., next: "anotherTransformer")',
-    "Stores are passive \u2014 injected via `env` values using `$store:storeName` syntax",
-    "Mapping on destinations transforms vendor-agnostic events into vendor-specific formats"
-  ],
-  platformOptions: {
-    web: "Browser environment \u2014 uses @walkeros/web-source-browser as default source",
-    server: "Node.js environment \u2014 uses @walkeros/server-source-express as default source"
-  },
-  minimalExample: {
-    version: 1,
-    flows: {
-      default: {
-        web: {},
-        packages: {
-          "@walkeros/web-source-browser": {},
-          "@walkeros/web-destination-gtag": {}
-        },
-        sources: {
-          browser: { package: "@walkeros/web-source-browser", config: {} }
-        },
-        destinations: {
-          gtag: {
-            package: "@walkeros/web-destination-gtag",
-            config: { measurementId: "G-XXXXXXXXXX" }
-          }
-        }
-      }
-    }
-  }
-};
+import { schemas as schemas5 } from "@walkeros/core/dev";
 function registerReferenceResources(server2) {
   server2.resource(
     "flow-schema",
     "walkeros://reference/flow-schema",
     {
-      description: "Annotated Flow.Config structure reference with connection rules and minimal example",
+      description: "JSON Schema for Flow.Config \u2014 the complete flow configuration structure",
       mimeType: "application/json"
     },
     async () => ({
       contents: [
         {
           uri: "walkeros://reference/flow-schema",
-          text: JSON.stringify(FLOW_SCHEMA_REFERENCE, null, 2),
+          text: JSON.stringify(schemas5.configJsonSchema, null, 2),
           mimeType: "application/json"
         }
       ]
@@ -1266,40 +1271,14 @@ function registerReferenceResources(server2) {
     "event-model",
     "walkeros://reference/event-model",
     {
-      description: "walkerOS event structure: entity-action naming, properties (data, context, globals, nested, consent, user)",
+      description: "JSON Schema for walkerOS events: entity-action naming, data, context, globals, user, consent",
       mimeType: "application/json"
     },
     async () => ({
       contents: [
         {
           uri: "walkeros://reference/event-model",
-          text: JSON.stringify(
-            {
-              naming: 'Events use "entity action" format: "page view", "product add", "order complete"',
-              minimalEvent: { name: "page view", data: { title: "Home" } },
-              properties: {
-                data: "Entity-specific properties (product name, price, etc.)",
-                context: "State/environment info (page type, test group)",
-                globals: "Cross-event properties set once (language, currency)",
-                nested: "Nested entities (products inside an order)",
-                user: "User identifiers (id, device, session, hash)",
-                consent: "Granted permissions (functional, analytics, marketing)",
-                custom: "Application-specific data"
-              },
-              autoPopulated: [
-                "timestamp",
-                "timing",
-                "group",
-                "count",
-                "version",
-                "source",
-                "entity",
-                "action"
-              ]
-            },
-            null,
-            2
-          ),
+          text: JSON.stringify(schemas5.eventJsonSchema, null, 2),
           mimeType: "application/json"
         }
       ]
@@ -1309,7 +1288,7 @@ function registerReferenceResources(server2) {
     "mapping",
     "walkeros://reference/mapping",
     {
-      description: "walkerOS mapping syntax: data/map/loop/set/condition/consent/policy rules for event transformation",
+      description: "JSON Schemas for walkerOS mapping: rules, valueConfig, rule, policy",
       mimeType: "application/json"
     },
     async () => ({
@@ -1318,46 +1297,10 @@ function registerReferenceResources(server2) {
           uri: "walkeros://reference/mapping",
           text: JSON.stringify(
             {
-              overview: "Mapping transforms walkerOS events into vendor-specific formats. Same syntax on sources (input normalization) and destinations (output transformation).",
-              config: {
-                consent: "Record<string, boolean> \u2014 destination-level consent requirements",
-                data: "Mapping.ValueConfig[] \u2014 field extraction rules",
-                policy: "Pre-processing rules applied before mapping",
-                mapping: "Record<entityAction, Mapping.Rule[]> \u2014 per-event mapping rules"
-              },
-              rules: {
-                keying: 'entity.action format with wildcards: "product.add", "*.view", "order.*", "*.*"',
-                priority: "Exact match > entity wildcard > action wildcard > global wildcard",
-                example: {
-                  "product.add": [
-                    {
-                      name: "add_to_cart",
-                      data: { map: { value: "data.price" } }
-                    }
-                  ],
-                  "*.view": [{ name: "page_view" }]
-                }
-              },
-              valueConfig: {
-                key: 'Source property path (e.g., "data.title", "context.page")',
-                value: "Static value or fallback",
-                fn: "$code:(event) => event.data.price * 100 \u2014 inline function",
-                map: "Record<string, ValueConfig> \u2014 object transformation",
-                loop: "Array iteration (e.g., loop nested entities)",
-                set: "Create array from multiple values",
-                condition: 'Conditional inclusion: { if: "data.price", value: "paid" }',
-                consent: 'Field-level consent: { key: "user.email", consent: { marketing: true } }',
-                validate: "Schema validation for the value"
-              },
-              codeFunction: "$code:(event, mapping, options) => expression \u2014 inline JavaScript. Access event data, mapping context, and options.",
-              policyRules: {
-                overview: "Pre-processing rules applied before mapping transforms events",
-                types: [
-                  "consent \u2014 require specific consent before processing",
-                  "ignore \u2014 skip events matching conditions",
-                  "redact \u2014 remove sensitive fields"
-                ]
-              }
+              rules: schemas5.rulesJsonSchema,
+              valueConfig: schemas5.valueConfigJsonSchema,
+              rule: schemas5.ruleJsonSchema,
+              policy: schemas5.policyJsonSchema
             },
             null,
             2
@@ -1371,43 +1314,14 @@ function registerReferenceResources(server2) {
     "consent",
     "walkeros://reference/consent",
     {
-      description: "walkerOS consent model: destination-level, rule-level, and field-level consent gating",
+      description: "JSON Schema for walkerOS consent: destination-level, rule-level, and field-level consent gating",
       mimeType: "application/json"
     },
     async () => ({
       contents: [
         {
           uri: "walkeros://reference/consent",
-          text: JSON.stringify(
-            {
-              levels: {
-                destination: "config.consent: { marketing: true } \u2014 entire destination requires consent",
-                rule: "mapping.product.add.consent: { analytics: true } \u2014 specific mapping rule requires consent",
-                field: 'data.map.email: { key: "user.email", consent: { marketing: true } } \u2014 individual field requires consent'
-              },
-              deferredInit: {
-                require: '["consent"] \u2014 destination waits for consent before initializing',
-                queue: "true (default) \u2014 events are queued while waiting for consent, replayed when granted"
-              },
-              collectorDefault: "Collector starts with empty consent state. Sources (CMP) push consent updates.",
-              example: {
-                destinations: {
-                  gtag: {
-                    package: "@walkeros/web-destination-gtag",
-                    config: { measurementId: "G-XXX" },
-                    consent: { analytics: true }
-                  },
-                  meta: {
-                    package: "@walkeros/web-destination-meta",
-                    config: { pixelId: "123" },
-                    consent: { marketing: true }
-                  }
-                }
-              }
-            },
-            null,
-            2
-          ),
+          text: JSON.stringify(schemas5.consentJsonSchema, null, 2),
           mimeType: "application/json"
         }
       ]
@@ -1470,79 +1384,48 @@ function registerReferenceResources(server2) {
     "contract",
     "walkeros://reference/contract",
     {
-      description: "walkerOS contracts: event schema validation with entity-action keying, wildcards, and inheritance",
+      description: "JSON Schema for walkerOS contracts: event schema validation with entity-action keying",
       mimeType: "application/json"
     },
     async () => ({
       contents: [
         {
           uri: "walkeros://reference/contract",
-          text: JSON.stringify(
-            {
-              overview: "Contracts define event schemas using entity-action keying. Used by the validator transformer to enforce data quality.",
-              structure: {
-                $tagging: "1 \u2014 contract format version (required)",
-                namedContracts: "Top-level keys are contract names with extends support",
-                entityAction: 'Keys use entity.action format: "product.add", "order.*", "*.*"',
-                wildcards: {
-                  "*.*": "Matches all events",
-                  "*.action": "Matches any entity with specific action",
-                  "entity.*": "Matches all actions of specific entity"
-                }
-              },
-              inheritance: {
-                extends: 'Named contracts can extend other contracts: { extends: "base" }',
-                merging: "Child properties merge with parent. Child overrides take precedence."
-              },
-              schema: {
-                properties: {
-                  data: "JSON Schema for entity data properties",
-                  globals: "JSON Schema for global properties",
-                  context: "JSON Schema for context properties",
-                  custom: "JSON Schema for custom properties",
-                  user: "JSON Schema for user identifiers",
-                  consent: "Required consent state"
-                }
-              },
-              reference: "$contract.name \u2014 use in flow config to reference a named contract",
-              example: {
-                $tagging: 1,
-                ecommerce: {
-                  "product.*": {
-                    properties: {
-                      data: {
-                        type: "object",
-                        properties: {
-                          name: { type: "string" },
-                          price: { type: "number" }
-                        },
-                        required: ["name"]
-                      }
-                    }
-                  },
-                  "order.complete": {
-                    properties: {
-                      data: {
-                        type: "object",
-                        properties: {
-                          total: { type: "number" },
-                          orderId: { type: "string" }
-                        },
-                        required: ["total", "orderId"]
-                      }
-                    }
-                  }
-                }
-              }
-            },
-            null,
-            2
-          ),
+          text: JSON.stringify(schemas5.contractJsonSchema, null, 2),
           mimeType: "application/json"
         }
       ]
     })
   );
+  server2.resource(
+    "examples",
+    "walkeros://reference/examples",
+    {
+      description: "Complete flow config example: web + server flows, mapping, contracts, step examples",
+      mimeType: "application/json"
+    },
+    async () => {
+      let example;
+      try {
+        const { readFileSync } = await import("fs");
+        const { createRequire } = await import("module");
+        const require2 = createRequire(import.meta.url);
+        const examplePath = require2.resolve("@walkeros/cli/examples/flow-complete.json");
+        example = readFileSync(examplePath, "utf-8");
+      } catch {
+        example = JSON.stringify({ error: "Example not found" });
+      }
+      return {
+        contents: [
+          {
+            uri: "walkeros://reference/examples",
+            text: example,
+            mimeType: "application/json"
+          }
+        ]
+      };
+    }
+  );
   server2.resource(
     "api",
     "walkeros://reference/api",
@@ -1619,15 +1502,18 @@ function registerAddStepPrompt(server2) {
               `2. Use package_get with section="hints" to read the selected package's configuration guidance.`,
               '3. Use package_get with section="examples" to see working configuration examples.',
               "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, connect via next/before chains if needed.",
-              "6. Use flow_validate to verify the result.",
+              "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.",
               "",
               "Important:",
               "- Read the walkeros://reference/flow-schema resource to understand connection rules.",
               "- Sources connect to pre-collector transformers via `next`.",
               "- Destinations connect to post-collector transformers via `before`.",
               "- Stores are passive \u2014 referenced via `$store:storeName` in env values.",
-              "- Use variables ($var) for values that change between environments."
+              "- Use variables ($var) for values that change between environments.",
+              "- For required settings without defaults in the package schema, ask the user which value to use. Do not guess credentials, IDs, or environment-specific values.",
+              "- If $meta.exports lists named exports, set the `code` field on the step to the chosen export name. If only one export exists, use it automatically."
             ].join("\n")
           }
         }
@@ -1656,8 +1542,14 @@ function registerSetupMappingPrompt(server2) {
             text: [
               `Help me set up mapping${stepName ? ` for the "${stepName}" step` : ""}.`,
               "",
+              "IMPORTANT \u2014 Mapping key structure:",
+              "Mapping uses NESTED entity \u2192 action keys, NOT dot-separated strings.",
+              'Event name "product add" splits into entity "product" and action "add".',
+              'Config structure: `{ "mapping": { "product": { "add": { name: "AddToCart", data: { ... } } } } }`',
+              'Wildcards: `{ "*": { "view": Rule } }` matches any entity with action "view".',
+              "",
               "Follow these steps:",
-              "1. Read the walkeros://reference/mapping resource to understand mapping syntax.",
+              "1. Read the walkeros://reference/mapping resource for full syntax reference.",
               `2. ${stepName ? `Identify the package for "${stepName}" in the flow, then u` : "U"}se package_get with section="examples" to see how events are mapped for this package.`,
               '3. Ask which events I want to map (e.g., "product view", "order complete").',
               "4. Generate mapping rules using the package examples as templates.",
@@ -1774,7 +1666,7 @@ function registerUseDefinitionsPrompt(server2) {
 var server = new McpServer(
   {
     name: "walkeros-flow",
-    version: "3.0.0-next-1773236214827"
+    version: "3.0.1"
   },
   {
     instructions: `walkerOS is an open-source, privacy-first event data collection platform. Define event pipelines as code using JSON flow configurations.
@@ -1783,24 +1675,52 @@ var server = new McpServer(
 
 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,
+  "flows": {
+    "default": {
+      "web": {},
+      "sources": { "<name>": { "package": "<npm-package>", "config": {} } },
+      "destinations": { "<name>": { "package": "<npm-package>", "config": { "settings": {} } } }
+    }
+  }
+}
+\`\`\`
+
+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
-2. Use the \`add-step\` prompt to add sources, destinations, transformers, or stores
-3. Use the \`setup-mapping\` prompt to configure event transformations
-4. \`flow_validate({ type: "flow", input: "flow.json" })\` \u2014 verify configuration
-5. \`flow_simulate({ configPath: "flow.json", event: "..." })\` \u2014 test with mocked API calls
-6. \`flow_bundle({ configPath: "flow.json" })\` \u2014 build deployable JavaScript
-7. \`api({ action: "deploy", id: "cfg_..." })\` \u2014 deploy to walkerOS cloud (requires WALKEROS_TOKEN)
+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
 
-Attach these for context: \`walkeros://reference/flow-schema\`, \`walkeros://reference/mapping\`, \`walkeros://reference/event-model\`, \`walkeros://reference/consent\`, \`walkeros://reference/variables\`, \`walkeros://reference/contract\`.
+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\`.
 
 ## Key Concepts
 
-- **Steps** are sources, destinations, transformers, or stores \u2014 each backed by an npm package with schemas, hints, and examples.
-- **Mapping** transforms events using data/map/loop/set/condition rules. Same syntax on sources and destinations.
+- **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.
+- **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.`