@synergenius/flow-weaver 0.6.0 → 0.8.0

package/dist/annotation-generator.js

@@ -40,9 +40,11 @@ export class AnnotationGenerator {
         }
         // Generate JSDoc comment block (only when no functionText)
         lines.push("/**");
-        // Add description if present
+        // Add description if present (handle multi-line descriptions)
         if (includeComments && nodeType.description) {
-            lines.push(` * ${nodeType.description}`);
+            for (const descLine of nodeType.description.split('\n')) {
+                lines.push(` * ${descLine}`);
+            }
             lines.push(` *`);
         }
         // @flowWeaver nodeType marker
@@ -279,12 +281,7 @@ export class AnnotationGenerator {
         if (workflow.ui?.startNode?.x !== undefined && workflow.ui?.startNode?.y !== undefined) {
             lines.push(` * @position Start ${Math.round(workflow.ui.startNode.x)} ${Math.round(workflow.ui.startNode.y)}`);
         }
-        // Add instance positions
-        workflow.instances.forEach((instance) => {
-            if (instance.config?.x !== undefined && instance.config?.y !== undefined) {
-                lines.push(` * @position ${instance.id} ${Math.round(instance.config.x)} ${Math.round(instance.config.y)}`);
-            }
-        });
+        // Instance positions are now emitted as [position: x y] on @node lines
         // Add Exit node position if present
         if (workflow.ui?.exitNode?.x !== undefined && workflow.ui?.exitNode?.y !== undefined) {
             lines.push(` * @position Exit ${Math.round(workflow.ui.exitNode.x)} ${Math.round(workflow.ui.exitNode.y)}`);
@@ -610,7 +607,12 @@ export function generateNodeInstanceTag(instance) {
     if (instance.config?.width !== undefined && instance.config?.height !== undefined) {
         sizeAttr = ` [size: ${Math.round(instance.config.width)} ${Math.round(instance.config.height)}]`;
     }
-    return ` * @node ${instance.id} ${instance.nodeType}${parent}${labelAttr}${portOrderAttr}${portLabelAttr}${exprAttr}${pullExecutionAttr}${minimizedAttr}${colorAttr}${iconAttr}${tagsAttr}${sizeAttr}`;
+    // Generate [position: x y] attribute if present
+    let positionAttr = '';
+    if (instance.config?.x !== undefined && instance.config?.y !== undefined) {
+        positionAttr = ` [position: ${Math.round(instance.config.x)} ${Math.round(instance.config.y)}]`;
+    }
+    return ` * @node ${instance.id} ${instance.nodeType}${parent}${labelAttr}${portOrderAttr}${portLabelAttr}${exprAttr}${pullExecutionAttr}${minimizedAttr}${colorAttr}${iconAttr}${tagsAttr}${sizeAttr}${positionAttr}`;
 }
 export const annotationGenerator = new AnnotationGenerator();
 //# sourceMappingURL=annotation-generator.js.map

package/dist/api/generate-in-place.js

@@ -408,6 +408,9 @@ function replaceWorkflowFunctionBody(source, functionName, newBody) {
     }
     // Find the closing brace
     const closeBraceIdx = functionNode.body.end - 1;
+    if (closeBraceIdx <= openBraceIdx) {
+        return { code: source, changed: false };
+    }
     const before = source.slice(0, openBraceIdx + 1);
     const after = source.slice(closeBraceIdx);
     const newBodyWithMarkers = [
@@ -1116,17 +1119,36 @@ function generateWorkflowJSDoc(ast, options = {}) {
         }
         lines.push(` * @fwImport ${npmType.name} ${actualFunctionName} from "${npmType.importSource}"`);
     }
-    // Add node instances — skip synthetic MAP_ITERATOR instances, strip parent from macro children
+    // Auto-position: compute default positions for nodes without explicit positions.
+    // Must happen before instance tags are generated so [position:] can be emitted.
+    const autoPositions = computeAutoPositions(ast);
+    // Add node instances — skip synthetic MAP_ITERATOR instances, strip parent from macro children.
+    // Merge auto-computed positions into instance config (without mutating the AST).
     for (const instance of ast.instances) {
         if (macroInstanceIds.has(instance.id))
             continue;
-        if (macroChildIds.has(instance.id) && instance.parent) {
+        // Merge auto-position into config if not already set
+        let inst = instance;
+        if (inst.config?.x === undefined || inst.config?.y === undefined) {
+            const autoPos = autoPositions.get(inst.id);
+            if (autoPos) {
+                inst = {
+                    ...inst,
+                    config: {
+                        ...inst.config,
+                        x: inst.config?.x ?? autoPos.x,
+                        y: inst.config?.y ?? autoPos.y,
+                    },
+                };
+            }
+        }
+        if (macroChildIds.has(inst.id) && inst.parent) {
             // Write child @node without parent scope — @map handles it
-            const stripped = { ...instance, parent: undefined };
+            const stripped = { ...inst, parent: undefined };
             lines.push(generateNodeInstanceTag(stripped));
         }
         else {
-            lines.push(generateNodeInstanceTag(instance));
+            lines.push(generateNodeInstanceTag(inst));
         }
     }
     // Filter stale macros (e.g. paths whose connections were deleted)
@@ -1165,27 +1187,13 @@ function generateWorkflowJSDoc(ast, options = {}) {
             }
         }
     }
-    // Auto-position: compute default positions for nodes without explicit positions.
-    // Uses a left-to-right layout with topological ordering when connections are available.
-    const autoPositions = computeAutoPositions(ast);
-    // Add positions - Start node
+    // Add positions - Start node (virtual, standalone @position)
     const startX = ast.ui?.startNode?.x ?? autoPositions.get('Start')?.x;
     const startY = ast.ui?.startNode?.y ?? autoPositions.get('Start')?.y;
     if (startX !== undefined && startY !== undefined) {
         lines.push(` * @position Start ${Math.round(startX)} ${Math.round(startY)}`);
     }
-    // Add positions - instances (use explicit position if available, otherwise auto-computed)
-    for (const instance of ast.instances) {
-        const explicitX = instance.config?.x;
-        const explicitY = instance.config?.y;
-        const autoPos = autoPositions.get(instance.id);
-        const x = explicitX ?? autoPos?.x;
-        const y = explicitY ?? autoPos?.y;
-        if (x !== undefined && y !== undefined) {
-            lines.push(` * @position ${instance.id} ${Math.round(x)} ${Math.round(y)}`);
-        }
-    }
-    // Add positions - Exit node
+    // Add positions - Exit node (virtual, standalone @position)
     const exitX = ast.ui?.exitNode?.x ?? autoPositions.get('Exit')?.x;
     const exitY = ast.ui?.exitNode?.y ?? autoPositions.get('Exit')?.y;
     if (exitX !== undefined && exitY !== undefined) {

package/dist/api/patterns.js

@@ -48,8 +48,13 @@ export function applyPattern(options) {
             conflicts.push(nodeType.name);
         }
     }
-    // ── Build @node declarations ────────────────────────────────────────
-    const nodeDeclarations = pattern.instances.map((inst) => ` * @node ${nodePrefix}${inst.id} ${inst.nodeType}`);
+    // ── Build @node declarations (with inline [position:] when present) ──
+    const nodeDeclarations = pattern.instances.map((inst) => {
+        const posAttr = inst.config?.x !== undefined && inst.config?.y !== undefined
+            ? ` [position: ${inst.config.x} ${inst.config.y}]`
+            : '';
+        return ` * @node ${nodePrefix}${inst.id} ${inst.nodeType}${posAttr}`;
+    });
     // ── Build @connect declarations + wiring instructions ───────────────
     const connectDeclarations = [];
     const wiringInstructions = [];
@@ -85,10 +90,6 @@ export function applyPattern(options) {
             connectDeclarations.push(` * @connect ${fromNode}.${conn.from.port} -> ${toNode}.${conn.to.port}`);
         }
     }
-    // ── Build @position declarations ────────────────────────────────────
-    const positionDeclarations = pattern.instances
-        .filter((inst) => inst.config?.x !== undefined && inst.config?.y !== undefined)
-        .map((inst) => ` * @position ${nodePrefix}${inst.id} ${inst.config.x} ${inst.config.y}`);
     // ── Generate node type functions (only non-conflicting) ─────────────
     const nodeTypesAdded = [];
     const nodeTypeFunctions = [];
@@ -103,7 +104,6 @@ export function applyPattern(options) {
         `// --- Pattern: ${pattern.name} ${prefix ? `(prefix: ${prefix})` : ''} ---`,
         ...nodeDeclarations,
         ...connectDeclarations,
-        ...positionDeclarations,
     ];
     // ── Insert into target content ──────────────────────────────────────
     const workflowMatch = targetContent.match(/\/\*\*[\s\S]*?@flowWeaver\s+workflow[\s\S]*?\*\//);
@@ -250,9 +250,12 @@ export function extractPattern(options) {
     lines.push('/**');
     lines.push(` * @flowWeaver pattern`);
     lines.push(` * @name ${patternName}`);
-    // Node declarations
+    // Node declarations (with inline [position:] when present)
     for (const inst of extractedInstances) {
-        lines.push(` * @node ${inst.id} ${inst.nodeType}`);
+        const posAttr = inst.config?.x !== undefined && inst.config?.y !== undefined
+            ? ` [position: ${inst.config.x} ${inst.config.y}]`
+            : '';
+        lines.push(` * @node ${inst.id} ${inst.nodeType}${posAttr}`);
     }
     // Internal connections
     for (const conn of internalConnections) {
@@ -280,12 +283,6 @@ export function extractPattern(options) {
     for (const port of [...new Set(outputPorts)]) {
         lines.push(` * @port OUT.${port}`);
     }
-    // Positions
-    for (const inst of extractedInstances) {
-        if (inst.config?.x !== undefined && inst.config?.y !== undefined) {
-            lines.push(` * @position ${inst.id} ${inst.config.x} ${inst.config.y}`);
-        }
-    }
     lines.push(' */');
     lines.push('function patternPlaceholder() {}');
     // Add node type functions

package/dist/ast/types.d.ts

@@ -637,6 +637,8 @@ export type TValidationError = {
     node?: string;
     connection?: TConnectionAST;
     location?: TSourceLocation;
+    /** Reference to documentation explaining this error and how to fix it. */
+    docUrl?: string;
 };
 export type TAnalysisResult = {
     controlFlowGraph: TControlFlowGraph;

package/dist/built-in-nodes/invoke-workflow.js

@@ -1,4 +1,4 @@
-import { getMockConfig } from './mock-types.js';
+import { getMockConfig, lookupMock } from './mock-types.js';
 /**
  * @flowWeaver nodeType
  * @input functionId - Inngest function ID (e.g. "my-service/sub-workflow")
@@ -11,8 +11,8 @@ export async function invokeWorkflow(execute, functionId, payload, timeout) {
         return { onSuccess: false, onFailure: false, result: {} };
     const mocks = getMockConfig();
     if (mocks) {
-        // Mock mode active — look up result by functionId
-        const mockResult = mocks.invocations?.[functionId];
+        // Mock mode — look up result by functionId (supports instance-qualified keys)
+        const mockResult = lookupMock(mocks.invocations, functionId);
         if (mockResult !== undefined) {
             return { onSuccess: true, onFailure: false, result: mockResult };
         }

package/dist/built-in-nodes/mock-types.d.ts

@@ -17,4 +17,24 @@ export interface FwMockConfig {
  * Read the mock config from globalThis, returning undefined if not set.
  */
 export declare function getMockConfig(): FwMockConfig | undefined;
+/**
+ * Look up a mock value from a section, supporting instance-qualified keys.
+ *
+ * Checks "instanceId:key" first (for per-node targeting), then falls back
+ * to plain "key". The instance ID comes from __fw_current_node_id__ which
+ * the generated code sets before each node invocation.
+ *
+ * @example
+ * ```json
+ * {
+ *   "invocations": {
+ *     "retryCall:api/process": { "status": "ok" },
+ *     "api/process": { "status": "default" }
+ *   }
+ * }
+ * ```
+ * When the node "retryCall" invokes "api/process", it gets `{ status: "ok" }`.
+ * Any other node invoking "api/process" gets `{ status: "default" }`.
+ */
+export declare function lookupMock<T>(section: Record<string, T> | undefined, key: string): T | undefined;
 //# sourceMappingURL=mock-types.d.ts.map

package/dist/built-in-nodes/mock-types.js

@@ -9,4 +9,34 @@
 export function getMockConfig() {
     return globalThis.__fw_mocks__;
 }
+/**
+ * Look up a mock value from a section, supporting instance-qualified keys.
+ *
+ * Checks "instanceId:key" first (for per-node targeting), then falls back
+ * to plain "key". The instance ID comes from __fw_current_node_id__ which
+ * the generated code sets before each node invocation.
+ *
+ * @example
+ * ```json
+ * {
+ *   "invocations": {
+ *     "retryCall:api/process": { "status": "ok" },
+ *     "api/process": { "status": "default" }
+ *   }
+ * }
+ * ```
+ * When the node "retryCall" invokes "api/process", it gets `{ status: "ok" }`.
+ * Any other node invoking "api/process" gets `{ status: "default" }`.
+ */
+export function lookupMock(section, key) {
+    if (!section)
+        return undefined;
+    const nodeId = globalThis.__fw_current_node_id__;
+    if (nodeId) {
+        const qualified = section[`${nodeId}:${key}`];
+        if (qualified !== undefined)
+            return qualified;
+    }
+    return section[key];
+}
 //# sourceMappingURL=mock-types.js.map

package/dist/built-in-nodes/wait-for-agent.js

@@ -1,4 +1,4 @@
-import { getMockConfig } from './mock-types.js';
+import { getMockConfig, lookupMock } from './mock-types.js';
 /**
  * @flowWeaver nodeType
  * @input agentId - Agent/task identifier
@@ -9,10 +9,11 @@ import { getMockConfig } from './mock-types.js';
 export async function waitForAgent(execute, agentId, context, prompt) {
     if (!execute)
         return { onSuccess: false, onFailure: false, agentResult: {} };
-    // 1. Check mocks first
+    // 1. Check mocks first (supports instance-qualified keys)
     const mocks = getMockConfig();
-    if (mocks?.agents?.[agentId]) {
-        return { onSuccess: true, onFailure: false, agentResult: mocks.agents[agentId] };
+    const mockResult = lookupMock(mocks?.agents, agentId);
+    if (mockResult !== undefined) {
+        return { onSuccess: true, onFailure: false, agentResult: mockResult };
     }
     // 2. Check agent channel (set by executor for pause/resume)
     const channel = globalThis.__fw_agent_channel__;

package/dist/built-in-nodes/wait-for-event.js

@@ -1,4 +1,4 @@
-import { getMockConfig } from './mock-types.js';
+import { getMockConfig, lookupMock } from './mock-types.js';
 /**
  * @flowWeaver nodeType
  * @input eventName - Event name to wait for (e.g. "app/approval.received")
@@ -11,8 +11,8 @@ export async function waitForEvent(execute, eventName, match, timeout) {
         return { onSuccess: false, onFailure: false, eventData: {} };
     const mocks = getMockConfig();
     if (mocks) {
-        // Mock mode active — look up event data by name
-        const mockData = mocks.events?.[eventName];
+        // Mock mode — look up event data by name (supports instance-qualified keys)
+        const mockData = lookupMock(mocks.events, eventName);
         if (mockData !== undefined) {
             return { onSuccess: true, onFailure: false, eventData: mockData };
         }

package/dist/chevrotain-parser/node-parser.d.ts

@@ -17,6 +17,10 @@ export interface NodeParseResult {
         width: number;
         height: number;
     };
+    position?: {
+        x: number;
+        y: number;
+    };
     color?: string;
     icon?: string;
     tags?: Array<{

package/dist/chevrotain-parser/node-parser.js

@@ -4,7 +4,7 @@
  * Parser for @node declarations using Chevrotain.
  */
 import { CstParser } from 'chevrotain';
-import { JSDocLexer, NodeTag, Identifier, Dot, Integer, LabelPrefix, ExprPrefix, PortOrderPrefix, PortLabelPrefix, MinimizedKeyword, PullExecutionPrefix, SizePrefix, ColorPrefix, IconPrefix, TagsPrefix, StringLiteral, LBracket, RBracket, Comma, Equals, EventEq, CronEq, MatchEq, TimeoutEq, LimitEq, PeriodEq, allTokens, } from './tokens.js';
+import { JSDocLexer, NodeTag, Identifier, Dot, Integer, LabelPrefix, ExprPrefix, PortOrderPrefix, PortLabelPrefix, MinimizedKeyword, PullExecutionPrefix, SizePrefix, PositionPrefix, ColorPrefix, IconPrefix, TagsPrefix, StringLiteral, LBracket, RBracket, Comma, Equals, EventEq, CronEq, MatchEq, TimeoutEq, LimitEq, PeriodEq, allTokens, } from './tokens.js';
 // =============================================================================
 // Parser Definition
 // =============================================================================
@@ -48,6 +48,7 @@ class NodeParser extends CstParser {
                     { ALT: () => this.SUBRULE(this.minimizedAttr) },
                     { ALT: () => this.SUBRULE(this.pullExecutionAttr) },
                     { ALT: () => this.SUBRULE(this.sizeAttr) },
+                    { ALT: () => this.SUBRULE(this.positionAttr) },
                     { ALT: () => this.SUBRULE(this.colorAttr) },
                     { ALT: () => this.SUBRULE(this.iconAttr) },
                     { ALT: () => this.SUBRULE(this.tagsAttr) },
@@ -140,6 +141,12 @@ class NodeParser extends CstParser {
         this.CONSUME(Integer, { LABEL: 'widthValue' });
         this.CONSUME2(Integer, { LABEL: 'heightValue' });
     });
+    // position: x y
+    positionAttr = this.RULE('positionAttr', () => {
+        this.CONSUME(PositionPrefix);
+        this.CONSUME(Integer, { LABEL: 'xValue' });
+        this.CONSUME2(Integer, { LABEL: 'yValue' });
+    });
     // color: "value"
     colorAttr = this.RULE('colorAttr', () => {
         this.CONSUME(ColorPrefix);
@@ -192,6 +199,7 @@ class NodeVisitor extends BaseVisitor {
         let minimized;
         let pullExecution;
         let size;
+        let position;
         let color;
         let icon;
         let tags;
@@ -215,6 +223,8 @@ class NodeVisitor extends BaseVisitor {
                     pullExecution = attrs.pullExecution;
                 if (attrs.size)
                     size = attrs.size;
+                if (attrs.position)
+                    position = attrs.position;
                 if (attrs.color)
                     color = attrs.color;
                 if (attrs.icon)
@@ -234,6 +244,7 @@ class NodeVisitor extends BaseVisitor {
             ...(minimized && { minimized }),
             ...(pullExecution && { pullExecution }),
             ...(size && { size }),
+            ...(position && { position }),
             ...(color && { color }),
             ...(icon && { icon }),
             ...(tags && { tags }),
@@ -252,6 +263,7 @@ class NodeVisitor extends BaseVisitor {
         let minimized;
         let pullExecution;
         let size;
+        let position;
         let color;
         let icon;
         let tags;
@@ -291,6 +303,11 @@ class NodeVisitor extends BaseVisitor {
                 size = this.visit(attr);
             }
         }
+        if (ctx.positionAttr) {
+            for (const attr of ctx.positionAttr) {
+                position = this.visit(attr);
+            }
+        }
         if (ctx.colorAttr) {
             for (const attr of ctx.colorAttr) {
                 color = this.visit(attr);
@@ -315,6 +332,7 @@ class NodeVisitor extends BaseVisitor {
             minimized,
             pullExecution,
             size,
+            position,
             color,
             icon,
             tags,
@@ -397,6 +415,11 @@ class NodeVisitor extends BaseVisitor {
         const height = parseInt(ctx.heightValue[0].image, 10);
         return { width, height };
     }
+    positionAttr(ctx) {
+        const x = parseInt(ctx.xValue[0].image, 10);
+        const y = parseInt(ctx.yValue[0].image, 10);
+        return { x, y };
+    }
     colorAttr(ctx) {
         return this.unescapeString(ctx.colorValue[0].image);
     }

package/dist/chevrotain-parser/tokens.d.ts

@@ -44,6 +44,7 @@ export declare const MergeStrategyPrefix: import("chevrotain").TokenType;
 export declare const PullExecutionPrefix: import("chevrotain").TokenType;
 export declare const MinimizedKeyword: import("chevrotain").TokenType;
 export declare const SizePrefix: import("chevrotain").TokenType;
+export declare const PositionPrefix: import("chevrotain").TokenType;
 export declare const ColorPrefix: import("chevrotain").TokenType;
 export declare const IconPrefix: import("chevrotain").TokenType;
 export declare const TagsPrefix: import("chevrotain").TokenType;

package/dist/chevrotain-parser/tokens.js

@@ -172,6 +172,10 @@ export const SizePrefix = createToken({
     name: 'SizePrefix',
     pattern: /size:/,
 });
+export const PositionPrefix = createToken({
+    name: 'PositionPrefix',
+    pattern: /position:/,
+});
 export const ColorPrefix = createToken({
     name: 'ColorPrefix',
     pattern: /color:/,
@@ -356,6 +360,7 @@ export const allTokens = [
     MergeStrategyPrefix,
     PullExecutionPrefix,
     SizePrefix,
+    PositionPrefix,
     ColorPrefix,
     IconPrefix,
     TagsPrefix,

package/dist/cli/commands/compile.js

@@ -116,6 +116,9 @@ export async function compileCommand(input, options = {}) {
                                 const loc = err.location ? `[line ${err.location.line}] ` : '';
                                 logger.error(`  ${loc}${friendly.title}: ${friendly.explanation}`);
                                 logger.info(`    How to fix: ${friendly.fix}`);
+                                if (err.docUrl) {
+                                    logger.info(`    See: ${err.docUrl}`);
+                                }
                             }
                             else {
                                 let msg = `  - ${err.message}`;
@@ -123,6 +126,9 @@ export async function compileCommand(input, options = {}) {
                                     msg += ` (node: ${err.node})`;
                                 }
                                 logger.error(msg);
+                                if (err.docUrl) {
+                                    logger.info(`    See: ${err.docUrl}`);
+                                }
                             }
                         });
                         errorCount++;

package/dist/cli/commands/init.js

@@ -273,12 +273,14 @@ export function generateProjectFiles(projectName, template, format = 'esm') {
         ].join('\n');
     }
     const gitignore = `node_modules/\ndist/\n.tsbuildinfo\n`;
+    const configYaml = `defaultFileType: ts\n`;
     return {
         'package.json': packageJson,
         'tsconfig.json': tsconfigJson,
         [`src/${workflowFile}`]: workflowCode,
         'src/main.ts': mainTs,
         '.gitignore': gitignore,
+        '.flowweaver/config.yaml': configYaml,
     };
 }
 // ── Filesystem writer ────────────────────────────────────────────────────────

package/dist/cli/commands/run.d.ts

@@ -1,6 +1,7 @@
 /**
  * Run command - execute a workflow file directly from the CLI
  */
+import type { FwMockConfig } from '../../built-in-nodes/mock-types.js';
 export interface RunOptions {
     /** Specific workflow name to run (if file contains multiple workflows) */
     workflow?: string;
@@ -48,4 +49,5 @@ export interface RunOptions {
  * ```
  */
 export declare function runCommand(input: string, options: RunOptions): Promise<void>;
+export declare function validateMockConfig(mocks: FwMockConfig, filePath: string, workflowName?: string): Promise<void>;
 //# sourceMappingURL=run.d.ts.map

package/dist/cli/commands/run.js

@@ -9,6 +9,7 @@ import { AgentChannel } from '../../mcp/agent-channel.js';
 import { logger } from '../utils/logger.js';
 import { getFriendlyError } from '../../friendly-errors.js';
 import { getErrorMessage } from '../../utils/error-utils.js';
+import { parseWorkflow } from '../../api/index.js';
 /**
  * Execute a workflow file and output the result.
  *
@@ -85,6 +86,10 @@ export async function runCommand(input, options) {
             throw new Error(`Failed to parse mocks file: ${options.mocksFile}`);
         }
     }
+    // Validate mock config against workflow when mocks are provided
+    if (mocks && !options.json) {
+        await validateMockConfig(mocks, filePath, options.workflow);
+    }
     // Set up timeout if specified
     let timeoutId;
     let timedOut = false;
@@ -263,6 +268,39 @@ export async function runCommand(input, options) {
         }
     }
 }
+const VALID_MOCK_KEYS = new Set(['events', 'invocations', 'agents', 'fast']);
+const BUILT_IN_NODE_TYPES = new Set(['delay', 'waitForEvent', 'invokeWorkflow', 'waitForAgent']);
+const MOCK_SECTION_TO_NODE = {
+    events: 'waitForEvent',
+    invocations: 'invokeWorkflow',
+    agents: 'waitForAgent',
+};
+export async function validateMockConfig(mocks, filePath, workflowName) {
+    // Check for unknown top-level keys (catches typos like "invocation" instead of "invocations")
+    for (const key of Object.keys(mocks)) {
+        if (!VALID_MOCK_KEYS.has(key)) {
+            logger.warn(`Mock config has unknown key "${key}". Valid keys: ${[...VALID_MOCK_KEYS].join(', ')}`);
+        }
+    }
+    // Quick-parse the workflow to check which built-in node types are used
+    try {
+        const result = await parseWorkflow(filePath, { workflowName });
+        if (result.errors.length > 0 || !result.ast?.instances)
+            return;
+        const usedNodeTypes = new Set(result.ast.instances.map((i) => i.nodeType));
+        for (const [section, nodeType] of Object.entries(MOCK_SECTION_TO_NODE)) {
+            const mockSection = mocks[section];
+            if (mockSection && typeof mockSection === 'object' && Object.keys(mockSection).length > 0) {
+                if (!usedNodeTypes.has(nodeType)) {
+                    logger.warn(`Mock config has "${section}" entries but workflow has no ${nodeType} nodes`);
+                }
+            }
+        }
+    }
+    catch {
+        // Parsing failed — skip validation, the execution will report the real error
+    }
+}
 function promptForInput(question) {
     return new Promise((resolve) => {
         const rl = readline.createInterface({

package/dist/cli/commands/validate.js

@@ -140,6 +140,9 @@ export async function validateCommand(input, options = {}) {
                                 const loc = err.location ? `[line ${err.location.line}] ` : '';
                                 logger.error(`  ${loc}${friendly.title}: ${friendly.explanation}`);
                                 logger.info(`    How to fix: ${friendly.fix}`);
+                                if (err.docUrl) {
+                                    logger.info(`    See: ${err.docUrl}`);
+                                }
                             }
                             else {
                                 let msg = `  - ${err.message}`;
@@ -153,6 +156,9 @@ export async function validateCommand(input, options = {}) {
                                     msg += ` (connection: ${err.connection.from.node}:${err.connection.from.port} -> ${err.connection.to.node}:${err.connection.to.port})`;
                                 }
                                 logger.error(msg);
+                                if (err.docUrl) {
+                                    logger.info(`    See: ${err.docUrl}`);
+                                }
                             }
                         });
                     }
@@ -167,6 +173,9 @@ export async function validateCommand(input, options = {}) {
                                 const loc = warn.location ? `[line ${warn.location.line}] ` : '';
                                 logger.warn(`  ${loc}${friendly.title}: ${friendly.explanation}`);
                                 logger.info(`    How to fix: ${friendly.fix}`);
+                                if (warn.docUrl) {
+                                    logger.info(`    See: ${warn.docUrl}`);
+                                }
                             }
                             else {
                                 let msg = `  - ${warn.message}`;
@@ -177,6 +186,9 @@ export async function validateCommand(input, options = {}) {
                                     msg += ` (node: ${warn.node})`;
                                 }
                                 logger.warn(msg);
+                                if (warn.docUrl) {
+                                    logger.info(`    See: ${warn.docUrl}`);
+                                }
                             }
                         });
                     }