@synergenius/flow-weaver 0.6.0 → 0.7.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

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 = [

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/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}`);
+                                }
                             }
                         });
                     }

package/dist/cli/flow-weaver.mjs

@@ -11870,7 +11870,7 @@ var init_type_checker = __esm({
 });
 
 // src/validator.ts
-var WorkflowValidator, validator;
+var DOCS_BASE, ERROR_DOC_URLS, WorkflowValidator, validator;
 var init_validator = __esm({
   "src/validator.ts"() {
     "use strict";
@@ -11878,6 +11878,18 @@ var init_validator = __esm({
     init_string_distance();
     init_signature_parser();
     init_type_checker();
+    DOCS_BASE = "https://docs.flowweaver.dev/reference";
+    ERROR_DOC_URLS = {
+      UNKNOWN_NODE_TYPE: `${DOCS_BASE}/concepts#node-registration`,
+      UNKNOWN_SOURCE_PORT: `${DOCS_BASE}/concepts#port-architecture`,
+      UNKNOWN_TARGET_PORT: `${DOCS_BASE}/concepts#port-architecture`,
+      TYPE_MISMATCH: `${DOCS_BASE}/compilation#type-compatibility`,
+      UNREACHABLE_NODE: `${DOCS_BASE}/concepts#graph-structure`,
+      MISSING_START_CONNECTION: `${DOCS_BASE}/concepts#start-and-exit`,
+      MISSING_EXIT_CONNECTION: `${DOCS_BASE}/concepts#start-and-exit`,
+      INFERRED_NODE_TYPE: `${DOCS_BASE}/node-conversion`,
+      DUPLICATE_CONNECTION: `${DOCS_BASE}/concepts#connections`
+    };
     WorkflowValidator = class {
       errors = [];
       warnings = [];
@@ -12005,6 +12017,11 @@ var init_validator = __esm({
             return true;
           });
         }
+        for (const diag of [...this.errors, ...this.warnings]) {
+          if (!diag.docUrl && ERROR_DOC_URLS[diag.code]) {
+            diag.docUrl = ERROR_DOC_URLS[diag.code];
+          }
+        }
         return {
           valid: this.errors.length === 0,
           errors: this.errors,
@@ -30777,7 +30794,9 @@ var AnnotationGenerator = class {
     }
     lines.push("/**");
     if (includeComments && nodeType.description) {
-      lines.push(` * ${nodeType.description}`);
+      for (const descLine of nodeType.description.split("\n")) {
+        lines.push(` * ${descLine}`);
+      }
       lines.push(` *`);
     }
     lines.push(" * @flowWeaver nodeType");
@@ -31510,6 +31529,9 @@ function replaceWorkflowFunctionBody(source, functionName, newBody) {
     return { code: source, changed: false };
   }
   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 = [
@@ -57939,12 +57961,18 @@ 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}`;
                 if (err.node) {
                   msg += ` (node: ${err.node})`;
                 }
                 logger.error(msg);
+                if (err.docUrl) {
+                  logger.info(`    See: ${err.docUrl}`);
+                }
               }
             });
             errorCount++;
@@ -62030,6 +62058,9 @@ 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}`;
                 if (err.location) {
@@ -62042,6 +62073,9 @@ 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}`);
+                }
               }
             });
           }
@@ -62056,6 +62090,9 @@ 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}`;
                 if (warn.location) {
@@ -62065,6 +62102,9 @@ async function validateCommand(input, options = {}) {
                   msg += ` (node: ${warn.node})`;
                 }
                 logger.warn(msg);
+                if (warn.docUrl) {
+                  logger.info(`    See: ${warn.docUrl}`);
+                }
               }
             });
           }
@@ -65370,13 +65410,16 @@ function generateProjectFiles(projectName, template, format = "esm") {
   const gitignore = `node_modules/
 dist/
 .tsbuildinfo
+`;
+  const configYaml = `defaultFileType: ts
 `;
   return {
     "package.json": packageJson,
     "tsconfig.json": tsconfigJson,
     [`src/${workflowFile}`]: workflowCode,
     "src/main.ts": mainTs,
-    ".gitignore": gitignore
+    ".gitignore": gitignore,
+    ".flowweaver/config.yaml": configYaml
   };
 }
 function scaffoldProject(targetDir, files, options) {
@@ -65576,22 +65619,19 @@ async function watchCommand(input, options = {}) {
 init_esm5();
 import * as path19 from "path";
 import * as fs18 from "fs";
-import * as os2 from "os";
+import * as os from "os";
 import { spawn } from "child_process";
 
 // src/mcp/workflow-executor.ts
 import * as path18 from "path";
 import * as fs17 from "fs";
-import * as os from "os";
 import { pathToFileURL } from "url";
 import ts4 from "typescript";
 async function executeWorkflowFromFile(filePath, params, options) {
   const resolvedPath = path18.resolve(filePath);
   const includeTrace = options?.includeTrace !== false;
-  const tmpBase = path18.join(
-    os.tmpdir(),
-    `fw-exec-${Date.now()}-${Math.random().toString(36).slice(2)}`
-  );
+  const tmpId = `fw-exec-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  const tmpBase = path18.join(path18.dirname(resolvedPath), tmpId);
   const tmpTsFile = `${tmpBase}.ts`;
   const tmpFile = `${tmpBase}.mjs`;
   try {
@@ -65887,7 +65927,7 @@ async function runInngestDevMode(filePath, options) {
   if (missingDeps.length > 0) {
     throw new Error(`Missing dependencies: ${missingDeps.join(", ")}. Install them with: npm install ${missingDeps.join(" ")}`);
   }
-  const tmpDir = fs18.mkdtempSync(path19.join(os2.tmpdir(), "fw-inngest-dev-"));
+  const tmpDir = fs18.mkdtempSync(path19.join(os.tmpdir(), "fw-inngest-dev-"));
   const inngestOutputPath = path19.join(tmpDir, path19.basename(filePath).replace(/\.ts$/, ".inngest.ts"));
   let serverProcess = null;
   const compileInngest = async () => {
@@ -84262,15 +84302,30 @@ function registerEditorTools(mcp, connection, buffer) {
       params: external_exports.record(external_exports.unknown()).optional().describe("Optional execution parameters"),
       includeTrace: external_exports.boolean().optional().describe("Include execution trace events (default: true)")
     },
-    async (args) => {
+    async (args, extra) => {
       if (args.filePath) {
         try {
           const channel = new AgentChannel();
           const runId = `run-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+          const progressToken = extra._meta?.progressToken;
+          let eventCount = 0;
+          const onEvent = progressToken ? (event) => {
+            eventCount++;
+            extra.sendNotification({
+              method: "notifications/progress",
+              params: {
+                progressToken,
+                progress: eventCount,
+                message: event.type === "STATUS_CHANGED" ? `${event.data?.id ?? ""}: ${event.data?.status ?? ""}` : event.type
+              }
+            }).catch(() => {
+            });
+          } : void 0;
           const execPromise = executeWorkflowFromFile(args.filePath, args.params, {
             workflowName: args.workflowName,
             includeTrace: args.includeTrace,
-            agentChannel: channel
+            agentChannel: channel,
+            onEvent
           });
           const raceResult = await Promise.race([
             execPromise.then((r) => ({ type: "completed", result: r })),
@@ -92226,6 +92281,9 @@ async function runCommand(input, options) {
       throw new Error(`Failed to parse mocks file: ${options.mocksFile}`);
     }
   }
+  if (mocks && !options.json) {
+    await validateMockConfig(mocks, filePath, options.workflow);
+  }
   let timeoutId;
   let timedOut = false;
   if (options.timeout) {
@@ -92380,6 +92438,35 @@ async function runCommand(input, options) {
     }
   }
 }
+var VALID_MOCK_KEYS = /* @__PURE__ */ new Set(["events", "invocations", "agents", "fast"]);
+var MOCK_SECTION_TO_NODE = {
+  events: "waitForEvent",
+  invocations: "invokeWorkflow",
+  agents: "waitForAgent"
+};
+async function validateMockConfig(mocks, filePath, workflowName) {
+  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(", ")}`);
+    }
+  }
+  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 {
+  }
+}
 function promptForInput(question) {
   return new Promise((resolve27) => {
     const rl = readline9.createInterface({
@@ -92876,7 +92963,7 @@ async function serveCommand(dir, options) {
 // src/export/index.ts
 import * as path33 from "path";
 import * as fs32 from "fs";
-import * as os3 from "os";
+import * as os2 from "os";
 import { fileURLToPath as fileURLToPath5 } from "url";
 
 // src/export/templates.ts
@@ -93073,7 +93160,7 @@ async function exportMultiWorkflow(options) {
       throw new Error(`None of the requested workflows found. Available: ${available}`);
     }
   }
-  const workDir = isDryRun ? path33.join(os3.tmpdir(), `fw-export-multi-dryrun-${Date.now()}`) : outputDir;
+  const workDir = isDryRun ? path33.join(os2.tmpdir(), `fw-export-multi-dryrun-${Date.now()}`) : outputDir;
   fs32.mkdirSync(workDir, { recursive: true });
   fs32.mkdirSync(path33.join(workDir, "workflows"), { recursive: true });
   fs32.mkdirSync(path33.join(workDir, "runtime"), { recursive: true });
@@ -93797,7 +93884,7 @@ async function exportWorkflow(options) {
     const available = parseResult.workflows.map((w) => w.name).join(", ");
     throw new Error(`Workflow "${options.workflow}" not found. Available: ${available}`);
   }
-  const workDir = isDryRun ? path33.join(os3.tmpdir(), `fw-export-dryrun-${Date.now()}`) : outputDir;
+  const workDir = isDryRun ? path33.join(os2.tmpdir(), `fw-export-dryrun-${Date.now()}`) : outputDir;
   fs32.mkdirSync(workDir, { recursive: true });
   let compiledContent;
   let compiledPath;
@@ -95041,7 +95128,7 @@ function displayInstalledPackage(pkg) {
 }
 
 // src/cli/index.ts
-var version2 = true ? "0.6.0" : "0.0.0-dev";
+var version2 = true ? "0.7.0" : "0.0.0-dev";
 var program2 = new Command();
 program2.name("flow-weaver").description("Flow Weaver Annotations - Compile and validate workflow files").version(version2, "-v, --version", "Output the current version");
 program2.configureOutput({

package/dist/mcp/tools-editor.js

@@ -133,16 +133,35 @@ export function registerEditorTools(mcp, connection, buffer) {
             .boolean()
             .optional()
             .describe('Include execution trace events (default: true)'),
-    }, async (args) => {
+    }, async (args, extra) => {
         // When filePath is provided, compile and execute directly (no editor needed)
         if (args.filePath) {
             try {
                 const channel = new AgentChannel();
                 const runId = `run-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+                // Send progress notifications for trace events when client supports it
+                const progressToken = extra._meta?.progressToken;
+                let eventCount = 0;
+                const onEvent = progressToken
+                    ? (event) => {
+                        eventCount++;
+                        extra.sendNotification({
+                            method: 'notifications/progress',
+                            params: {
+                                progressToken,
+                                progress: eventCount,
+                                message: event.type === 'STATUS_CHANGED'
+                                    ? `${event.data?.id ?? ''}: ${event.data?.status ?? ''}`
+                                    : event.type,
+                            },
+                        }).catch(() => { });
+                    }
+                    : undefined;
                 const execPromise = executeWorkflowFromFile(args.filePath, args.params, {
                     workflowName: args.workflowName,
                     includeTrace: args.includeTrace,
                     agentChannel: channel,
+                    onEvent,
                 });
                 // Race between workflow completing and workflow pausing
                 const raceResult = await Promise.race([

package/dist/mcp/workflow-executor.js

@@ -4,7 +4,6 @@
  */
 import * as path from 'path';
 import * as fs from 'fs';
-import * as os from 'os';
 import { pathToFileURL } from 'url';
 import ts from 'typescript';
 import { compileWorkflow } from '../api/index.js';
@@ -31,7 +30,13 @@ export async function executeWorkflowFromFile(filePath, params, options) {
     // In-place compilation preserves all functions in the module (node types,
     // sibling workflows), which is required for workflow composition where one
     // workflow calls another as a node type.
-    const tmpBase = path.join(os.tmpdir(), `fw-exec-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    //
+    // Temp files are written in the source file's directory (not os.tmpdir())
+    // so that ESM module resolution can walk up to the project's node_modules.
+    // On Windows, os.tmpdir() is disconnected from the project tree, causing
+    // bare import specifiers (e.g. 'zod', 'openai') to fail with MODULE_NOT_FOUND.
+    const tmpId = `fw-exec-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    const tmpBase = path.join(path.dirname(resolvedPath), tmpId);
     const tmpTsFile = `${tmpBase}.ts`;
     const tmpFile = `${tmpBase}.mjs`;
     try {

package/dist/validator.js

@@ -2,6 +2,19 @@ import { RESERVED_NODE_NAMES, isStartNode, isExitNode, isExecutePort, isReserved
 import { findClosestMatches } from './utils/string-distance.js';
 import { parseFunctionSignature } from './jsdoc-port-sync/signature-parser.js';
 import { checkTypeCompatibilityFromStrings } from './type-checker.js';
+const DOCS_BASE = 'https://docs.flowweaver.dev/reference';
+/** Map error codes to the documentation page that explains how to fix them. */
+const ERROR_DOC_URLS = {
+    UNKNOWN_NODE_TYPE: `${DOCS_BASE}/concepts#node-registration`,
+    UNKNOWN_SOURCE_PORT: `${DOCS_BASE}/concepts#port-architecture`,
+    UNKNOWN_TARGET_PORT: `${DOCS_BASE}/concepts#port-architecture`,
+    TYPE_MISMATCH: `${DOCS_BASE}/compilation#type-compatibility`,
+    UNREACHABLE_NODE: `${DOCS_BASE}/concepts#graph-structure`,
+    MISSING_START_CONNECTION: `${DOCS_BASE}/concepts#start-and-exit`,
+    MISSING_EXIT_CONNECTION: `${DOCS_BASE}/concepts#start-and-exit`,
+    INFERRED_NODE_TYPE: `${DOCS_BASE}/node-conversion`,
+    DUPLICATE_CONNECTION: `${DOCS_BASE}/concepts#connections`,
+};
 export class WorkflowValidator {
     errors = [];
     warnings = [];
@@ -149,6 +162,12 @@ export class WorkflowValidator {
                 return true;
             });
         }
+        // Attach doc URLs to diagnostics that have mapped error codes
+        for (const diag of [...this.errors, ...this.warnings]) {
+            if (!diag.docUrl && ERROR_DOC_URLS[diag.code]) {
+                diag.docUrl = ERROR_DOC_URLS[diag.code];
+            }
+        }
         return {
             valid: this.errors.length === 0,
             errors: this.errors,

package/docs/reference/concepts.md

@@ -215,11 +215,24 @@ Use `@fwImport` to turn npm package functions or local module exports into node
  */
 ```
 
-- First identifier: node type name (convention: `npm/pkg/fn` or `local/path/fn`)
-- Second identifier: exported function name
-- String: package name or relative path
+**Syntax**: `@fwImport <nodeTypeName> <functionName> from "<package-or-path>"`
 
-Imported functions become expression nodes. Port types are inferred from `.d.ts` files when available.
+- **Node type name** (first identifier): used in `@node` declarations. Convention: `npm/pkg/fn` for packages, `local/path/fn` for local modules.
+- **Function name** (second identifier): the actual exported function name to import.
+- **Source** (quoted string): npm package name or relative path to a local module.
+
+**Prefix semantics**:
+- `npm/` — resolves to a bare package specifier. The package must be installed in `node_modules`. At compile time, the compiler generates an `import { fn } from "package"` statement in the output.
+- `local/` — resolves to a relative import from the workflow file's directory. Generates `import { fn } from "./path"`.
+
+**Type inference**: port types are inferred from the function's TypeScript signature (from `.d.ts` files for npm packages, or from the source for local modules). If type information isn't available, ports default to `ANY`.
+
+**What happens at compile time**: the compiler parses the `@fwImport` annotation, resolves the function signature, creates a virtual node type with inferred ports, and emits the corresponding import statement in the generated code. The imported function is called as an expression node — no `execute` parameter, no STEP ports.
+
+**Common errors**:
+- Package not installed: `npm install <package>` before compiling.
+- Wrong export name: check the package's exports with your IDE or `npm info <package>`.
+- No type information: install `@types/<package>` for community type definitions.
 
 ## Mandatory Signatures
 
@@ -245,6 +258,33 @@ export function myWorkflow(execute: boolean, params: { inputA: Type }): {...}
 
 > **Key difference:** Nodes use direct params, workflows use `params` object.
 
+## Node Registration
+
+Every node used in a workflow must be explicitly declared with `@node`. The compiler builds a static directed graph from annotations at compile time, so it needs to know about every node before code generation begins. This is different from normal function calls where you just invoke a function directly.
+
+Built-in nodes (`delay`, `waitForEvent`, `invokeWorkflow`, `waitForAgent`) are exported from the library but still need explicit declaration in your workflow file. The compiler validates all `@node` references against the set of available node types — functions annotated with `@flowWeaver nodeType` in the same file or imported via `@fwImport`.
+
+To use a built-in node, define or import the function and annotate it:
+
+```typescript
+import { waitForEvent } from '@synergenius/flow-weaver/built-in-nodes';
+
+/**
+ * @flowWeaver nodeType
+ * @input eventName - Event to wait for
+ * @output eventData - Received event payload
+ */
+// (function body provided by the library)
+
+/**
+ * @flowWeaver workflow
+ * @node wait waitForEvent
+ * @connect Start.eventName -> wait.eventName
+ * @connect wait.eventData -> Exit.data
+ */
+export function myWorkflow(execute: boolean, params: { eventName: string }) { ... }
+```
+
 ## Port Types
 
 STRING, NUMBER, BOOLEAN, OBJECT, ARRAY, FUNCTION, ANY, STEP

package/docs/reference/debugging.md

@@ -169,6 +169,39 @@ flow-weaver describe src/workflows/my-workflow.ts --format mermaid     # diagram
 flow-weaver describe src/workflows/my-workflow.ts --node fetcher1      # focus on a node
 ```
 
+### flow-weaver run --stream vs --trace
+
+Both flags give you execution trace data, but in different ways:
+
+**`--stream`** writes events to stderr in real-time as nodes execute. Each STATUS_CHANGED event prints the node ID, new status, and duration. Use this for live debugging during development — you can watch the workflow progress node by node.
+
+```bash
+flow-weaver run workflow.ts --stream
+# Output (to stderr):
+#   [STATUS_CHANGED] fetcher: → RUNNING
+#   [STATUS_CHANGED] fetcher: → SUCCEEDED (142ms)
+#   [STATUS_CHANGED] processor: → RUNNING
+#   [VARIABLE_SET] processor.result
+#   [STATUS_CHANGED] processor: → SUCCEEDED (38ms)
+```
+
+**`--trace`** collects all ExecutionTraceEvent objects during execution and includes them in the output after completion. Use this for post-mortem analysis or programmatic consumption (e.g., in CI or with `--json`).
+
+```bash
+flow-weaver run workflow.ts --trace
+# Shows: "12 events captured" + first 5 events as summary
+
+flow-weaver run workflow.ts --trace --json | jq '.traceCount'
+# Outputs: 12
+```
+
+**Combining both**: `--stream --trace` gives you real-time output during execution AND the collected trace array in the result. Useful when you want to watch progress live but also capture the full event log.
+
+**When to use which**:
+- Debugging interactively → `--stream`
+- CI pipeline or scripted analysis → `--trace --json`
+- Both → `--stream --trace`
+
 ### Diagnostic Strategy
 
 1. **flow-weaver validate** -- Get all errors and warnings. Fix errors first.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synergenius/flow-weaver",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Deterministic workflow compiler for AI agents. Compiles to standalone TypeScript, no runtime dependencies.",
   "private": false,
   "type": "module",