@synergenius/flow-weaver 0.2.1 → 0.3.0

package/dist/cli/flow-weaver.mjs

@@ -935,8 +935,8 @@ var require_command = __commonJS({
   "node_modules/commander/lib/command.js"(exports2) {
     var EventEmitter2 = __require("events").EventEmitter;
     var childProcess = __require("child_process");
-    var path37 = __require("path");
-    var fs36 = __require("fs");
+    var path38 = __require("path");
+    var fs37 = __require("fs");
     var process6 = __require("process");
     var { Argument: Argument2, humanReadableArgName } = require_argument();
     var { CommanderError: CommanderError2 } = require_error();
@@ -1759,10 +1759,10 @@ Expecting one of '${allowedValues.join("', '")}'`);
         let launchWithNode = false;
         const sourceExt = [".js", ".ts", ".tsx", ".mjs", ".cjs"];
         function findFile(baseDir, baseName) {
-          const localBin = path37.resolve(baseDir, baseName);
-          if (fs36.existsSync(localBin)) return localBin;
-          if (sourceExt.includes(path37.extname(baseName))) return void 0;
-          const foundExt = sourceExt.find((ext2) => fs36.existsSync(`${localBin}${ext2}`));
+          const localBin = path38.resolve(baseDir, baseName);
+          if (fs37.existsSync(localBin)) return localBin;
+          if (sourceExt.includes(path38.extname(baseName))) return void 0;
+          const foundExt = sourceExt.find((ext2) => fs37.existsSync(`${localBin}${ext2}`));
           if (foundExt) return `${localBin}${foundExt}`;
           return void 0;
         }
@@ -1773,23 +1773,23 @@ Expecting one of '${allowedValues.join("', '")}'`);
         if (this._scriptPath) {
           let resolvedScriptPath;
           try {
-            resolvedScriptPath = fs36.realpathSync(this._scriptPath);
+            resolvedScriptPath = fs37.realpathSync(this._scriptPath);
           } catch (err) {
             resolvedScriptPath = this._scriptPath;
           }
-          executableDir = path37.resolve(path37.dirname(resolvedScriptPath), executableDir);
+          executableDir = path38.resolve(path38.dirname(resolvedScriptPath), executableDir);
         }
         if (executableDir) {
           let localFile = findFile(executableDir, executableFile);
           if (!localFile && !subcommand._executableFile && this._scriptPath) {
-            const legacyName = path37.basename(this._scriptPath, path37.extname(this._scriptPath));
+            const legacyName = path38.basename(this._scriptPath, path38.extname(this._scriptPath));
             if (legacyName !== this._name) {
               localFile = findFile(executableDir, `${legacyName}-${subcommand._name}`);
             }
           }
           executableFile = localFile || executableFile;
         }
-        launchWithNode = sourceExt.includes(path37.extname(executableFile));
+        launchWithNode = sourceExt.includes(path38.extname(executableFile));
         let proc2;
         if (process6.platform !== "win32") {
           if (launchWithNode) {
@@ -2572,7 +2572,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
        * @return {Command}
        */
       nameFromFilename(filename) {
-        this._name = path37.basename(filename, path37.extname(filename));
+        this._name = path38.basename(filename, path38.extname(filename));
         return this;
       }
       /**
@@ -2586,9 +2586,9 @@ Expecting one of '${allowedValues.join("', '")}'`);
        * @param {string} [path]
        * @return {string|null|Command}
        */
-      executableDir(path38) {
-        if (path38 === void 0) return this._executableDir;
-        this._executableDir = path38;
+      executableDir(path39) {
+        if (path39 === void 0) return this._executableDir;
+        this._executableDir = path39;
         return this;
       }
       /**
@@ -6458,10 +6458,10 @@ var init_esm3 = __esm({
        * Return a void Promise that resolves once the stream ends.
        */
       async promise() {
-        return new Promise((resolve26, reject2) => {
+        return new Promise((resolve27, reject2) => {
           this.on(DESTROYED, () => reject2(new Error("stream destroyed")));
           this.on("error", (er) => reject2(er));
-          this.on("end", () => resolve26());
+          this.on("end", () => resolve27());
         });
       }
       /**
@@ -6485,7 +6485,7 @@ var init_esm3 = __esm({
             return Promise.resolve({ done: false, value: res });
           if (this[EOF])
             return stop();
-          let resolve26;
+          let resolve27;
           let reject2;
           const onerr = (er) => {
             this.off("data", ondata);
@@ -6499,19 +6499,19 @@ var init_esm3 = __esm({
             this.off("end", onend);
             this.off(DESTROYED, ondestroy);
             this.pause();
-            resolve26({ value: value2, done: !!this[EOF] });
+            resolve27({ value: value2, done: !!this[EOF] });
           };
           const onend = () => {
             this.off("error", onerr);
             this.off("data", ondata);
             this.off(DESTROYED, ondestroy);
             stop();
-            resolve26({ done: true, value: void 0 });
+            resolve27({ done: true, value: void 0 });
           };
           const ondestroy = () => onerr(new Error("stream destroyed"));
           return new Promise((res2, rej) => {
             reject2 = rej;
-            resolve26 = res2;
+            resolve27 = res2;
             this.once(DESTROYED, ondestroy);
             this.once("error", onerr);
             this.once("end", onend);
@@ -6886,12 +6886,12 @@ var init_esm4 = __esm({
       /**
        * Get the Path object referenced by the string path, resolved from this Path
        */
-      resolve(path37) {
-        if (!path37) {
+      resolve(path38) {
+        if (!path38) {
           return this;
         }
-        const rootPath = this.getRootString(path37);
-        const dir = path37.substring(rootPath.length);
+        const rootPath = this.getRootString(path38);
+        const dir = path38.substring(rootPath.length);
         const dirParts = dir.split(this.splitSep);
         const result = rootPath ? this.getRoot(rootPath).#resolveParts(dirParts) : this.#resolveParts(dirParts);
         return result;
@@ -7495,9 +7495,9 @@ var init_esm4 = __esm({
         if (this.#asyncReaddirInFlight) {
           await this.#asyncReaddirInFlight;
         } else {
-          let resolve26 = () => {
+          let resolve27 = () => {
           };
-          this.#asyncReaddirInFlight = new Promise((res) => resolve26 = res);
+          this.#asyncReaddirInFlight = new Promise((res) => resolve27 = res);
           try {
             for (const e of await this.#fs.promises.readdir(fullpath, {
               withFileTypes: true
@@ -7510,7 +7510,7 @@ var init_esm4 = __esm({
             children.provisional = 0;
           }
           this.#asyncReaddirInFlight = void 0;
-          resolve26();
+          resolve27();
         }
         return children.slice(0, children.provisional);
       }
@@ -7643,8 +7643,8 @@ var init_esm4 = __esm({
       /**
        * @internal
        */
-      getRootString(path37) {
-        return win32.parse(path37).root;
+      getRootString(path38) {
+        return win32.parse(path38).root;
       }
       /**
        * @internal
@@ -7690,8 +7690,8 @@ var init_esm4 = __esm({
       /**
        * @internal
        */
-      getRootString(path37) {
-        return path37.startsWith("/") ? "/" : "";
+      getRootString(path38) {
+        return path38.startsWith("/") ? "/" : "";
       }
       /**
        * @internal
@@ -7740,8 +7740,8 @@ var init_esm4 = __esm({
        *
        * @internal
        */
-      constructor(cwd = process.cwd(), pathImpl, sep2, { nocase, childrenCacheSize = 16 * 1024, fs: fs36 = defaultFS } = {}) {
-        this.#fs = fsFromOption(fs36);
+      constructor(cwd = process.cwd(), pathImpl, sep2, { nocase, childrenCacheSize = 16 * 1024, fs: fs37 = defaultFS } = {}) {
+        this.#fs = fsFromOption(fs37);
         if (cwd instanceof URL || cwd.startsWith("file://")) {
           cwd = fileURLToPath(cwd);
         }
@@ -7780,11 +7780,11 @@ var init_esm4 = __esm({
       /**
        * Get the depth of a provided path, string, or the cwd
        */
-      depth(path37 = this.cwd) {
-        if (typeof path37 === "string") {
-          path37 = this.cwd.resolve(path37);
+      depth(path38 = this.cwd) {
+        if (typeof path38 === "string") {
+          path38 = this.cwd.resolve(path38);
         }
-        return path37.depth();
+        return path38.depth();
       }
       /**
        * Return the cache of child entries.  Exposed so subclasses can create
@@ -8271,9 +8271,9 @@ var init_esm4 = __esm({
         process6();
         return results;
       }
-      chdir(path37 = this.cwd) {
+      chdir(path38 = this.cwd) {
         const oldCwd = this.cwd;
-        this.cwd = typeof path37 === "string" ? this.cwd.resolve(path37) : path37;
+        this.cwd = typeof path38 === "string" ? this.cwd.resolve(path38) : path38;
         this.cwd[setAsCwd](oldCwd);
       }
     };
@@ -8299,8 +8299,8 @@ var init_esm4 = __esm({
       /**
        * @internal
        */
-      newRoot(fs36) {
-        return new PathWin32(this.rootPath, IFDIR, void 0, this.roots, this.nocase, this.childrenCache(), { fs: fs36 });
+      newRoot(fs37) {
+        return new PathWin32(this.rootPath, IFDIR, void 0, this.roots, this.nocase, this.childrenCache(), { fs: fs37 });
       }
       /**
        * Return true if the provided path string is an absolute path
@@ -8328,8 +8328,8 @@ var init_esm4 = __esm({
       /**
        * @internal
        */
-      newRoot(fs36) {
-        return new PathPosix(this.rootPath, IFDIR, void 0, this.roots, this.nocase, this.childrenCache(), { fs: fs36 });
+      newRoot(fs37) {
+        return new PathPosix(this.rootPath, IFDIR, void 0, this.roots, this.nocase, this.childrenCache(), { fs: fs37 });
       }
       /**
        * Return true if the provided path string is an absolute path
@@ -8648,8 +8648,8 @@ var init_processor = __esm({
       }
       // match, absolute, ifdir
       entries() {
-        return [...this.store.entries()].map(([path37, n]) => [
-          path37,
+        return [...this.store.entries()].map(([path38, n]) => [
+          path38,
           !!(n & 2),
           !!(n & 1)
         ]);
@@ -8862,9 +8862,9 @@ var init_walker = __esm({
       signal;
       maxDepth;
       includeChildMatches;
-      constructor(patterns, path37, opts) {
+      constructor(patterns, path38, opts) {
         this.patterns = patterns;
-        this.path = path37;
+        this.path = path38;
         this.opts = opts;
         this.#sep = !opts.posix && opts.platform === "win32" ? "\\" : "/";
         this.includeChildMatches = opts.includeChildMatches !== false;
@@ -8883,11 +8883,11 @@ var init_walker = __esm({
           });
         }
       }
-      #ignored(path37) {
-        return this.seen.has(path37) || !!this.#ignore?.ignored?.(path37);
+      #ignored(path38) {
+        return this.seen.has(path38) || !!this.#ignore?.ignored?.(path38);
       }
-      #childrenIgnored(path37) {
-        return !!this.#ignore?.childrenIgnored?.(path37);
+      #childrenIgnored(path38) {
+        return !!this.#ignore?.childrenIgnored?.(path38);
       }
       // backpressure mechanism
       pause() {
@@ -9102,8 +9102,8 @@ var init_walker = __esm({
     };
     GlobWalker = class extends GlobUtil {
       matches = /* @__PURE__ */ new Set();
-      constructor(patterns, path37, opts) {
-        super(patterns, path37, opts);
+      constructor(patterns, path38, opts) {
+        super(patterns, path38, opts);
       }
       matchEmit(e) {
         this.matches.add(e);
@@ -9140,8 +9140,8 @@ var init_walker = __esm({
     };
     GlobStream = class extends GlobUtil {
       results;
-      constructor(patterns, path37, opts) {
-        super(patterns, path37, opts);
+      constructor(patterns, path38, opts) {
+        super(patterns, path38, opts);
         this.results = new Minipass({
           signal: this.signal,
           objectMode: true
@@ -9741,7 +9741,7 @@ var require_util = __commonJS({
     var normalize2 = createSafeHandler((url2) => {
     });
     exports2.normalize = normalize2;
-    function join20(aRoot, aPath) {
+    function join21(aRoot, aPath) {
       const pathType = getURLType(aPath);
       const rootType = getURLType(aRoot);
       aRoot = ensureDirectory(aRoot);
@@ -9771,7 +9771,7 @@ var require_util = __commonJS({
       const newPath = withBase(aPath, withBase(aRoot, base));
       return computeRelativeURL(base, newPath);
     }
-    exports2.join = join20;
+    exports2.join = join21;
     function relative5(rootURL, targetURL) {
       const result = relativeIfPossible(rootURL, targetURL);
       return typeof result === "string" ? result : normalize2(targetURL);
@@ -9800,8 +9800,8 @@ var require_util = __commonJS({
         sourceURL = sourceURL.replace(/^\//, "");
       }
       let url2 = normalize2(sourceURL || "");
-      if (sourceRoot) url2 = join20(sourceRoot, url2);
-      if (sourceMapURL) url2 = join20(trimFilename(sourceMapURL), url2);
+      if (sourceRoot) url2 = join21(sourceRoot, url2);
+      if (sourceMapURL) url2 = join21(trimFilename(sourceMapURL), url2);
       return url2;
     }
     exports2.computeSourceURL = computeSourceURL;
@@ -10352,17 +10352,17 @@ var require_binary_search = __commonJS({
 var require_read_wasm = __commonJS({
   "node_modules/source-map/lib/read-wasm.js"(exports2, module2) {
     "use strict";
-    var fs36 = __require("fs");
-    var path37 = __require("path");
+    var fs37 = __require("fs");
+    var path38 = __require("path");
     module2.exports = function readWasm() {
-      return new Promise((resolve26, reject2) => {
-        const wasmPath = path37.join(__dirname, "mappings.wasm");
-        fs36.readFile(wasmPath, null, (error2, data) => {
+      return new Promise((resolve27, reject2) => {
+        const wasmPath = path38.join(__dirname, "mappings.wasm");
+        fs37.readFile(wasmPath, null, (error2, data) => {
           if (error2) {
             reject2(error2);
             return;
           }
-          resolve26(data.buffer);
+          resolve27(data.buffer);
         });
       });
     };
@@ -12506,13 +12506,13 @@ Add '@param ${fromPort}' to the workflow JSDoc and include it in the params obje
           connections.filter((c) => c.from.node === c.to.node).map((c) => c.from.node)
         );
         const nonSelfLoopConnections = connections.filter((c) => c.from.node !== c.to.node);
-        const dfs = (nodeName, path37) => {
+        const dfs = (nodeName, path38) => {
           if (recursionStack.has(nodeName)) {
             if (selfLoopNodes.has(nodeName)) {
               return false;
             }
-            const cycleStart = path37.indexOf(nodeName);
-            const cyclePath = [...path37.slice(cycleStart), nodeName];
+            const cycleStart = path38.indexOf(nodeName);
+            const cyclePath = [...path38.slice(cycleStart), nodeName];
             const cycleNodes = cyclePath.slice(0, -1);
             const sortedCycle = [...cycleNodes].sort();
             const cycleKey = sortedCycle.join(",");
@@ -12534,7 +12534,7 @@ Add '@param ${fromPort}' to the workflow JSDoc and include it in the params obje
             return false;
           }
           recursionStack.add(nodeName);
-          const newPath = [...path37, nodeName];
+          const newPath = [...path38, nodeName];
           const instance = instances.find((n) => n.id === nodeName);
           if (!instance) {
             recursionStack.delete(nodeName);
@@ -14515,15 +14515,15 @@ var require_route = __commonJS({
       };
     }
     function wrapConversion(toModel, graph) {
-      const path37 = [graph[toModel].parent, toModel];
+      const path38 = [graph[toModel].parent, toModel];
       let fn = conversions[graph[toModel].parent][toModel];
       let cur = graph[toModel].parent;
       while (graph[cur].parent) {
-        path37.unshift(graph[cur].parent);
+        path38.unshift(graph[cur].parent);
         fn = link(conversions[graph[cur].parent][cur], fn);
         cur = graph[cur].parent;
       }
-      fn.conversion = path37;
+      fn.conversion = path38;
       return fn;
     }
     module2.exports = function(fromModel) {
@@ -15004,7 +15004,7 @@ var require_lib4 = __commonJS({
 // node_modules/xmlhttprequest-ssl/lib/XMLHttpRequest.js
 var require_XMLHttpRequest = __commonJS({
   "node_modules/xmlhttprequest-ssl/lib/XMLHttpRequest.js"(exports2, module2) {
-    var fs36 = __require("fs");
+    var fs37 = __require("fs");
     var Url = __require("url");
     var spawn2 = __require("child_process").spawn;
     module2.exports = XMLHttpRequest3;
@@ -15162,7 +15162,7 @@ var require_XMLHttpRequest = __commonJS({
             throw new Error("XMLHttpRequest: Only GET method is supported");
           }
           if (settings.async) {
-            fs36.readFile(unescape(url2.pathname), function(error2, data2) {
+            fs37.readFile(unescape(url2.pathname), function(error2, data2) {
               if (error2) {
                 self2.handleError(error2, error2.errno || -1);
               } else {
@@ -15174,7 +15174,7 @@ var require_XMLHttpRequest = __commonJS({
             });
           } else {
             try {
-              this.response = fs36.readFileSync(unescape(url2.pathname));
+              this.response = fs37.readFileSync(unescape(url2.pathname));
               this.responseText = this.response.toString("utf8");
               this.status = 200;
               setState(self2.DONE);
@@ -15300,15 +15300,15 @@ var require_XMLHttpRequest = __commonJS({
         } else {
           var contentFile = ".node-xmlhttprequest-content-" + process.pid;
           var syncFile = ".node-xmlhttprequest-sync-" + process.pid;
-          fs36.writeFileSync(syncFile, "", "utf8");
+          fs37.writeFileSync(syncFile, "", "utf8");
           var execString = "var http = require('http'), https = require('https'), fs = require('fs');var doRequest = http" + (ssl ? "s" : "") + ".request;var options = " + JSON.stringify(options) + ";var responseText = '';var responseData = Buffer.alloc(0);var req = doRequest(options, function(response) {response.on('data', function(chunk) {  var data = Buffer.from(chunk);  responseText += data.toString('utf8');  responseData = Buffer.concat([responseData, data]);});response.on('end', function() {fs.writeFileSync('" + contentFile + "', JSON.stringify({err: null, data: {statusCode: response.statusCode, headers: response.headers, text: responseText, data: responseData.toString('base64')}}), 'utf8');fs.unlinkSync('" + syncFile + "');});response.on('error', function(error) {fs.writeFileSync('" + contentFile + "', 'NODE-XMLHTTPREQUEST-ERROR:' + JSON.stringify(error), 'utf8');fs.unlinkSync('" + syncFile + "');});}).on('error', function(error) {fs.writeFileSync('" + contentFile + "', 'NODE-XMLHTTPREQUEST-ERROR:' + JSON.stringify(error), 'utf8');fs.unlinkSync('" + syncFile + "');});" + (data ? "req.write('" + JSON.stringify(data).slice(1, -1).replace(/'/g, "\\'") + "');" : "") + "req.end();";
           var syncProc = spawn2(process.argv[0], ["-e", execString]);
           var statusText;
-          while (fs36.existsSync(syncFile)) {
+          while (fs37.existsSync(syncFile)) {
           }
-          self2.responseText = fs36.readFileSync(contentFile, "utf8");
+          self2.responseText = fs37.readFileSync(contentFile, "utf8");
           syncProc.stdin.end();
-          fs36.unlinkSync(contentFile);
+          fs37.unlinkSync(contentFile);
           if (self2.responseText.match(/^NODE-XMLHTTPREQUEST-ERROR:/)) {
             var errorObj = JSON.parse(self2.responseText.replace(/^NODE-XMLHTTPREQUEST-ERROR:/, ""));
             self2.handleError(errorObj, 503);
@@ -22688,7 +22688,7 @@ var require_compile = __commonJS({
       const schOrFunc = root2.refs[ref];
       if (schOrFunc)
         return schOrFunc;
-      let _sch = resolve26.call(this, root2, ref);
+      let _sch = resolve27.call(this, root2, ref);
       if (_sch === void 0) {
         const schema2 = (_a = root2.localRefs) === null || _a === void 0 ? void 0 : _a[ref];
         const { schemaId } = this.opts;
@@ -22715,7 +22715,7 @@ var require_compile = __commonJS({
     function sameSchemaEnv(s1, s2) {
       return s1.schema === s2.schema && s1.root === s2.root && s1.baseId === s2.baseId;
     }
-    function resolve26(root2, ref) {
+    function resolve27(root2, ref) {
       let sch;
       while (typeof (sch = this.refs[ref]) == "string")
         ref = sch;
@@ -22930,8 +22930,8 @@ var require_utils = __commonJS({
       }
       return ind;
     }
-    function removeDotSegments(path37) {
-      let input = path37;
+    function removeDotSegments(path38) {
+      let input = path38;
       const output = [];
       let nextSlash = -1;
       let len = 0;
@@ -23130,8 +23130,8 @@ var require_schemes = __commonJS({
         wsComponent.secure = void 0;
       }
       if (wsComponent.resourceName) {
-        const [path37, query] = wsComponent.resourceName.split("?");
-        wsComponent.path = path37 && path37 !== "/" ? path37 : void 0;
+        const [path38, query] = wsComponent.resourceName.split("?");
+        wsComponent.path = path38 && path38 !== "/" ? path38 : void 0;
         wsComponent.query = query;
         wsComponent.resourceName = void 0;
       }
@@ -23290,7 +23290,7 @@ var require_fast_uri = __commonJS({
       }
       return uri;
     }
-    function resolve26(baseURI, relativeURI, options) {
+    function resolve27(baseURI, relativeURI, options) {
       const schemelessOptions = options ? Object.assign({ scheme: "null" }, options) : { scheme: "null" };
       const resolved = resolveComponent(parse7(baseURI, schemelessOptions), parse7(relativeURI, schemelessOptions), schemelessOptions, true);
       schemelessOptions.skipEscape = true;
@@ -23517,7 +23517,7 @@ var require_fast_uri = __commonJS({
     var fastUri = {
       SCHEMES,
       normalize: normalize2,
-      resolve: resolve26,
+      resolve: resolve27,
       resolveComponent,
       equal,
       serialize,
@@ -26493,12 +26493,12 @@ var require_dist = __commonJS({
         throw new Error(`Unknown format "${name}"`);
       return f;
     };
-    function addFormats(ajv, list, fs36, exportName) {
+    function addFormats(ajv, list, fs37, exportName) {
       var _a;
       var _b;
       (_a = (_b = ajv.opts.code).formats) !== null && _a !== void 0 ? _a : _b.formats = (0, codegen_1._)`require("ajv-formats/dist/formats").${exportName}`;
       for (const f of list)
-        ajv.addFormat(f, fs36[f]);
+        ajv.addFormat(f, fs37[f]);
     }
     module2.exports = exports2 = formatsPlugin;
     Object.defineProperty(exports2, "__esModule", { value: true });
@@ -29945,9 +29945,9 @@ function shouldUseStepTag(portName, port) {
 
 // src/sugar-optimizer.ts
 init_constants();
-function validatePathMacro(path37, connections, instances) {
+function validatePathMacro(path38, connections, instances) {
   const instanceIds = new Set(instances.map((inst) => inst.id));
-  for (const step of path37.steps) {
+  for (const step of path38.steps) {
     if (step.node === "Start" || step.node === "Exit") continue;
     if (!instanceIds.has(step.node)) return false;
   }
@@ -29957,9 +29957,9 @@ function validatePathMacro(path37, connections, instances) {
       connKeys.add(`${conn.from.node}.${conn.from.port}->${conn.to.node}.${conn.to.port}`);
     }
   }
-  for (let i = 0; i < path37.steps.length - 1; i++) {
-    const current2 = path37.steps[i];
-    const next = path37.steps[i + 1];
+  for (let i = 0; i < path38.steps.length - 1; i++) {
+    const current2 = path38.steps[i];
+    const next = path38.steps[i + 1];
     const route = current2.route || "ok";
     let expectedKey;
     if (current2.node === "Start") {
@@ -30052,12 +30052,12 @@ function detectSugarPatterns(connections, instances, existingMacros, nodeTypes,
   }
   const candidateRoutes = [];
   const MAX_ROUTES = 20;
-  function dfs(node, path37, visited) {
+  function dfs(node, path38, visited) {
     if (candidateRoutes.length >= MAX_ROUTES) return;
     if (node === "Exit") {
-      path37.push({ node: "Exit" });
-      candidateRoutes.push([...path37]);
-      path37.pop();
+      path38.push({ node: "Exit" });
+      candidateRoutes.push([...path38]);
+      path38.pop();
       return;
     }
     if (visited.has(node)) return;
@@ -30069,15 +30069,15 @@ function detectSugarPatterns(connections, instances, existingMacros, nodeTypes,
     }
     if (edges.ok && !coveredByExistingMacro.has(edges.ok === "Exit" ? "" : edges.ok)) {
       const step = node === "Start" ? { node: "Start" } : { node };
-      path37.push(step);
-      dfs(edges.ok, path37, visited);
-      path37.pop();
+      path38.push(step);
+      dfs(edges.ok, path38, visited);
+      path38.pop();
     }
     if (edges.fail && !coveredByExistingMacro.has(edges.fail === "Exit" ? "" : edges.fail)) {
       const step = { node, route: "fail" };
-      path37.push(step);
-      dfs(edges.fail, path37, visited);
-      path37.pop();
+      path38.push(step);
+      dfs(edges.fail, path38, visited);
+      path38.pop();
     }
     visited.delete(node);
   }
@@ -32812,19 +32812,19 @@ function toKey(value2) {
 var toKey_default = toKey;
 
 // node_modules/lodash-es/_baseGet.js
-function baseGet(object3, path37) {
-  path37 = castPath_default(path37, object3);
-  var index = 0, length = path37.length;
+function baseGet(object3, path38) {
+  path38 = castPath_default(path38, object3);
+  var index = 0, length = path38.length;
   while (object3 != null && index < length) {
-    object3 = object3[toKey_default(path37[index++])];
+    object3 = object3[toKey_default(path38[index++])];
   }
   return index && index == length ? object3 : void 0;
 }
 var baseGet_default = baseGet;
 
 // node_modules/lodash-es/get.js
-function get(object3, path37, defaultValue) {
-  var result = object3 == null ? void 0 : baseGet_default(object3, path37);
+function get(object3, path38, defaultValue) {
+  var result = object3 == null ? void 0 : baseGet_default(object3, path38);
   return result === void 0 ? defaultValue : result;
 }
 var get_default = get;
@@ -33736,11 +33736,11 @@ function baseHasIn(object3, key) {
 var baseHasIn_default = baseHasIn;
 
 // node_modules/lodash-es/_hasPath.js
-function hasPath(object3, path37, hasFunc) {
-  path37 = castPath_default(path37, object3);
-  var index = -1, length = path37.length, result = false;
+function hasPath(object3, path38, hasFunc) {
+  path38 = castPath_default(path38, object3);
+  var index = -1, length = path38.length, result = false;
   while (++index < length) {
-    var key = toKey_default(path37[index]);
+    var key = toKey_default(path38[index]);
     if (!(result = object3 != null && hasFunc(object3, key))) {
       break;
     }
@@ -33755,21 +33755,21 @@ function hasPath(object3, path37, hasFunc) {
 var hasPath_default = hasPath;
 
 // node_modules/lodash-es/hasIn.js
-function hasIn(object3, path37) {
-  return object3 != null && hasPath_default(object3, path37, baseHasIn_default);
+function hasIn(object3, path38) {
+  return object3 != null && hasPath_default(object3, path38, baseHasIn_default);
 }
 var hasIn_default = hasIn;
 
 // node_modules/lodash-es/_baseMatchesProperty.js
 var COMPARE_PARTIAL_FLAG6 = 1;
 var COMPARE_UNORDERED_FLAG4 = 2;
-function baseMatchesProperty(path37, srcValue) {
-  if (isKey_default(path37) && isStrictComparable_default(srcValue)) {
-    return matchesStrictComparable_default(toKey_default(path37), srcValue);
+function baseMatchesProperty(path38, srcValue) {
+  if (isKey_default(path38) && isStrictComparable_default(srcValue)) {
+    return matchesStrictComparable_default(toKey_default(path38), srcValue);
   }
   return function(object3) {
-    var objValue = get_default(object3, path37);
-    return objValue === void 0 && objValue === srcValue ? hasIn_default(object3, path37) : baseIsEqual_default(srcValue, objValue, COMPARE_PARTIAL_FLAG6 | COMPARE_UNORDERED_FLAG4);
+    var objValue = get_default(object3, path38);
+    return objValue === void 0 && objValue === srcValue ? hasIn_default(object3, path38) : baseIsEqual_default(srcValue, objValue, COMPARE_PARTIAL_FLAG6 | COMPARE_UNORDERED_FLAG4);
   };
 }
 var baseMatchesProperty_default = baseMatchesProperty;
@@ -33783,16 +33783,16 @@ function baseProperty(key) {
 var baseProperty_default = baseProperty;
 
 // node_modules/lodash-es/_basePropertyDeep.js
-function basePropertyDeep(path37) {
+function basePropertyDeep(path38) {
   return function(object3) {
-    return baseGet_default(object3, path37);
+    return baseGet_default(object3, path38);
   };
 }
 var basePropertyDeep_default = basePropertyDeep;
 
 // node_modules/lodash-es/property.js
-function property(path37) {
-  return isKey_default(path37) ? baseProperty_default(toKey_default(path37)) : basePropertyDeep_default(path37);
+function property(path38) {
+  return isKey_default(path38) ? baseProperty_default(toKey_default(path38)) : basePropertyDeep_default(path38);
 }
 var property_default = property;
 
@@ -34160,8 +34160,8 @@ function baseHas(object3, key) {
 var baseHas_default = baseHas;
 
 // node_modules/lodash-es/has.js
-function has(object3, path37) {
-  return object3 != null && hasPath_default(object3, path37, baseHas_default);
+function has(object3, path38) {
+  return object3 != null && hasPath_default(object3, path38, baseHas_default);
 }
 var has_default = has;
 
@@ -34284,14 +34284,14 @@ function negate(predicate) {
 var negate_default = negate;
 
 // node_modules/lodash-es/_baseSet.js
-function baseSet(object3, path37, value2, customizer) {
+function baseSet(object3, path38, value2, customizer) {
   if (!isObject_default(object3)) {
     return object3;
   }
-  path37 = castPath_default(path37, object3);
-  var index = -1, length = path37.length, lastIndex = length - 1, nested = object3;
+  path38 = castPath_default(path38, object3);
+  var index = -1, length = path38.length, lastIndex = length - 1, nested = object3;
   while (nested != null && ++index < length) {
-    var key = toKey_default(path37[index]), newValue = value2;
+    var key = toKey_default(path38[index]), newValue = value2;
     if (key === "__proto__" || key === "constructor" || key === "prototype") {
       return object3;
     }
@@ -34299,7 +34299,7 @@ function baseSet(object3, path37, value2, customizer) {
       var objValue = nested[key];
       newValue = customizer ? customizer(objValue, key, nested) : void 0;
       if (newValue === void 0) {
-        newValue = isObject_default(objValue) ? objValue : isIndex_default(path37[index + 1]) ? [] : {};
+        newValue = isObject_default(objValue) ? objValue : isIndex_default(path38[index + 1]) ? [] : {};
       }
     }
     assignValue_default(nested, key, newValue);
@@ -34313,9 +34313,9 @@ var baseSet_default = baseSet;
 function basePickBy(object3, paths, predicate) {
   var index = -1, length = paths.length, result = {};
   while (++index < length) {
-    var path37 = paths[index], value2 = baseGet_default(object3, path37);
-    if (predicate(value2, path37)) {
-      baseSet_default(result, castPath_default(path37, object3), value2);
+    var path38 = paths[index], value2 = baseGet_default(object3, path38);
+    if (predicate(value2, path38)) {
+      baseSet_default(result, castPath_default(path38, object3), value2);
     }
   }
   return result;
@@ -34331,8 +34331,8 @@ function pickBy(object3, predicate) {
     return [prop];
   });
   predicate = baseIteratee_default(predicate);
-  return basePickBy_default(object3, props, function(value2, path37) {
-    return predicate(value2, path37[0]);
+  return basePickBy_default(object3, props, function(value2, path38) {
+    return predicate(value2, path38[0]);
   });
 }
 var pickBy_default = pickBy;
@@ -36831,12 +36831,12 @@ function assignCategoriesMapProp(tokenTypes) {
     singleAssignCategoriesToksMap([], currTokType);
   });
 }
-function singleAssignCategoriesToksMap(path37, nextNode) {
-  forEach_default(path37, (pathNode) => {
+function singleAssignCategoriesToksMap(path38, nextNode) {
+  forEach_default(path38, (pathNode) => {
     nextNode.categoryMatchesMap[pathNode.tokenTypeIdx] = true;
   });
   forEach_default(nextNode.CATEGORIES, (nextCategory) => {
-    const newPath = path37.concat(nextNode);
+    const newPath = path38.concat(nextNode);
     if (!includes_default(newPath, nextCategory)) {
       singleAssignCategoriesToksMap(newPath, nextCategory);
     }
@@ -37680,10 +37680,10 @@ var GastRefResolverVisitor = class extends GAstVisitor {
 
 // node_modules/chevrotain/lib/src/parse/grammar/interpreter.js
 var AbstractNextPossibleTokensWalker = class extends RestWalker {
-  constructor(topProd, path37) {
+  constructor(topProd, path38) {
     super();
     this.topProd = topProd;
-    this.path = path37;
+    this.path = path38;
     this.possibleTokTypes = [];
     this.nextProductionName = "";
     this.nextProductionOccurrence = 0;
@@ -37727,9 +37727,9 @@ var AbstractNextPossibleTokensWalker = class extends RestWalker {
   }
 };
 var NextAfterTokenWalker = class extends AbstractNextPossibleTokensWalker {
-  constructor(topProd, path37) {
-    super(topProd, path37);
-    this.path = path37;
+  constructor(topProd, path38) {
+    super(topProd, path38);
+    this.path = path38;
     this.nextTerminalName = "";
     this.nextTerminalOccurrence = 0;
     this.nextTerminalName = this.path.lastTok.name;
@@ -38325,10 +38325,10 @@ function initializeArrayOfArrays(size) {
   }
   return result;
 }
-function pathToHashKeys(path37) {
+function pathToHashKeys(path38) {
   let keys2 = [""];
-  for (let i = 0; i < path37.length; i++) {
-    const tokType = path37[i];
+  for (let i = 0; i < path38.length; i++) {
+    const tokType = path38[i];
     const longerKeys = [];
     for (let j = 0; j < keys2.length; j++) {
       const currShorterKey = keys2[j];
@@ -38567,7 +38567,7 @@ function validateRuleIsOverridden(ruleName, definedRulesNames, className) {
   }
   return errors2;
 }
-function validateNoLeftRecursion(topRule, currRule, errMsgProvider, path37 = []) {
+function validateNoLeftRecursion(topRule, currRule, errMsgProvider, path38 = []) {
   const errors2 = [];
   const nextNonTerminals = getFirstNoneTerminal(currRule.definition);
   if (isEmpty_default(nextNonTerminals)) {
@@ -38579,15 +38579,15 @@ function validateNoLeftRecursion(topRule, currRule, errMsgProvider, path37 = [])
       errors2.push({
         message: errMsgProvider.buildLeftRecursionError({
           topLevelRule: topRule,
-          leftRecursionPath: path37
+          leftRecursionPath: path38
         }),
         type: ParserDefinitionErrorType.LEFT_RECURSION,
         ruleName
       });
     }
-    const validNextSteps = difference_default(nextNonTerminals, path37.concat([topRule]));
+    const validNextSteps = difference_default(nextNonTerminals, path38.concat([topRule]));
     const errorsFromNextSteps = flatMap_default(validNextSteps, (currRefRule) => {
-      const newPath = clone_default(path37);
+      const newPath = clone_default(path38);
       newPath.push(currRefRule);
       return validateNoLeftRecursion(topRule, currRefRule, errMsgProvider, newPath);
     });
@@ -46201,7 +46201,7 @@ function processResult(result, scope) {
   }
   return result !== NOTHING ? result : void 0;
 }
-function finalize(rootScope, value2, path37) {
+function finalize(rootScope, value2, path38) {
   if (isFrozen(value2))
     return value2;
   const useStrictIteration = rootScope.immer_.shouldUseStrictIteration();
@@ -46209,7 +46209,7 @@ function finalize(rootScope, value2, path37) {
   if (!state) {
     each(
       value2,
-      (key, childValue) => finalizeProperty(rootScope, state, value2, key, childValue, path37),
+      (key, childValue) => finalizeProperty(rootScope, state, value2, key, childValue, path38),
       useStrictIteration
     );
     return value2;
@@ -46239,16 +46239,16 @@ function finalize(rootScope, value2, path37) {
         result,
         key,
         childValue,
-        path37,
+        path38,
         isSet22
       ),
       useStrictIteration
     );
     maybeFreeze(rootScope, result, false);
-    if (path37 && rootScope.patches_) {
+    if (path38 && rootScope.patches_) {
       getPlugin("Patches").generatePatches_(
         state,
-        path37,
+        path38,
         rootScope.patches_,
         rootScope.inversePatches_
       );
@@ -46270,9 +46270,9 @@ function finalizeProperty(rootScope, parentState, targetObject, prop, childValue
   if (process.env.NODE_ENV !== "production" && childValue === targetObject)
     die(5);
   if (isDraft(childValue)) {
-    const path37 = rootPath && parentState && parentState.type_ !== 3 && // Set objects are atomic since they have no keys.
+    const path38 = rootPath && parentState && parentState.type_ !== 3 && // Set objects are atomic since they have no keys.
     !has2(parentState.assigned_, prop) ? rootPath.concat(prop) : void 0;
-    const res = finalize(rootScope, childValue, path37);
+    const res = finalize(rootScope, childValue, path38);
     set(targetObject, prop, res);
     if (isDraft(res)) {
       rootScope.canAutoFreeze_ = false;
@@ -56997,17 +56997,17 @@ function buildAdjacency(ast) {
 function enumeratePaths(ast) {
   const { fromStart, toExit, edges } = buildAdjacency(ast);
   const paths = [];
-  function dfs(current2, path37, visited) {
+  function dfs(current2, path38, visited) {
     if (toExit.has(current2)) {
-      paths.push([...path37, "Exit"]);
+      paths.push([...path38, "Exit"]);
     }
     const targets = edges.get(current2) || [];
     for (const next of targets) {
       if (!visited.has(next)) {
         visited.add(next);
-        path37.push(next);
-        dfs(next, path37, visited);
-        path37.pop();
+        path38.push(next);
+        dfs(next, path38, visited);
+        path38.pop();
         visited.delete(next);
       }
     }
@@ -57021,22 +57021,22 @@ function enumeratePaths(ast) {
 function buildGraph(ast) {
   const { fromStart, toExit, edges } = buildAdjacency(ast);
   const lines = [];
-  function dfs(current2, path37, visited) {
+  function dfs(current2, path38, visited) {
     if (toExit.has(current2)) {
-      lines.push([...path37, "Exit"].join(" -> "));
+      lines.push([...path38, "Exit"].join(" -> "));
     }
     const targets = edges.get(current2) || [];
     for (const next of targets) {
       if (!visited.has(next)) {
         visited.add(next);
-        path37.push(next);
-        dfs(next, path37, visited);
-        path37.pop();
+        path38.push(next);
+        dfs(next, path38, visited);
+        path38.pop();
         visited.delete(next);
       }
     }
     if (targets.length === 0 && !toExit.has(current2)) {
-      lines.push(path37.join(" -> "));
+      lines.push(path38.join(" -> "));
     }
   }
   fromStart.forEach((startNode) => {
@@ -57947,14 +57947,14 @@ function waypointsToSvgPath(waypoints, cornerRadius) {
       radii[i + 1] *= scale;
     }
   }
-  let path37 = `M ${waypoints[0][0]},${waypoints[0][1]}`;
+  let path38 = `M ${waypoints[0][0]},${waypoints[0][1]}`;
   for (let i = 1; i < waypoints.length - 1; i++) {
     const prev = waypoints[i - 1];
     const curr = waypoints[i];
     const next = waypoints[i + 1];
     const r = radii[i];
     if (r < 2) {
-      path37 += ` L ${curr[0]},${curr[1]}`;
+      path38 += ` L ${curr[0]},${curr[1]}`;
       continue;
     }
     const dPrev = [prev[0] - curr[0], prev[1] - curr[1]];
@@ -57967,12 +57967,12 @@ function waypointsToSvgPath(waypoints, cornerRadius) {
     const arcEnd = [curr[0] + uNext[0] * r, curr[1] + uNext[1] * r];
     const cross = dPrev[0] * dNext[1] - dPrev[1] * dNext[0];
     const sweep = cross > 0 ? 0 : 1;
-    path37 += ` L ${arcStart[0]},${arcStart[1]}`;
-    path37 += ` A ${r} ${r} 0 0 ${sweep} ${arcEnd[0]},${arcEnd[1]}`;
+    path38 += ` L ${arcStart[0]},${arcStart[1]}`;
+    path38 += ` A ${r} ${r} 0 0 ${sweep} ${arcEnd[0]},${arcEnd[1]}`;
   }
   const last2 = waypoints[waypoints.length - 1];
-  path37 += ` L ${last2[0]},${last2[1]}`;
-  return path37;
+  path38 += ` L ${last2[0]},${last2[1]}`;
+  return path38;
 }
 function computeWaypoints(from, to, nodeBoxes, sourceNodeId, targetNodeId, padding, exitStub, entryStub, allocator) {
   const isSelfConnection = sourceNodeId === targetNodeId;
@@ -58119,7 +58119,7 @@ function calculateOrthogonalPath(from, to, nodeBoxes, sourceNodeId, targetNodeId
 }
 function calculateOrthogonalPathSafe(from, to, nodeBoxes, sourceNodeId, targetNodeId, options, allocator) {
   try {
-    const path37 = calculateOrthogonalPath(
+    const path38 = calculateOrthogonalPath(
       from,
       to,
       nodeBoxes,
@@ -58128,8 +58128,8 @@ function calculateOrthogonalPathSafe(from, to, nodeBoxes, sourceNodeId, targetNo
       options,
       allocator
     );
-    if (!path37 || path37.length < 5) return null;
-    return path37;
+    if (!path38 || path38.length < 5) return null;
+    return path38;
   } catch {
     return null;
   }
@@ -58143,13 +58143,16 @@ var PORT_PADDING_Y = 18;
 var NODE_MIN_WIDTH = 90;
 var NODE_MIN_HEIGHT = 90;
 var BORDER_RADIUS = 6;
-var LAYER_GAP_X = 220;
+var LAYER_GAP_X = 300;
+var LABEL_CLEARANCE = 42;
+var MIN_EDGE_GAP = 112;
 var NODE_GAP_Y = 60;
 var LABEL_HEIGHT = 20;
 var LABEL_GAP = 12;
-var SCOPE_PADDING = 40;
+var SCOPE_PADDING_X = 140;
+var SCOPE_PADDING_Y = 40;
 var SCOPE_PORT_COLUMN = 50;
-var SCOPE_INNER_GAP_X = 160;
+var SCOPE_INNER_GAP_X = 240;
 var ORTHOGONAL_DISTANCE_THRESHOLD = 300;
 var CHAR_WIDTHS = {
   " ": 2.78,
@@ -58256,6 +58259,18 @@ function measureText(text) {
   }
   return width;
 }
+function portBadgeWidth(port) {
+  const abbrev = TYPE_ABBREVIATIONS[port.dataType] ?? port.dataType;
+  const typeWidth = measureText(abbrev);
+  const labelWidth = measureText(port.label);
+  const pad = 7;
+  const divGap = 4;
+  return pad + typeWidth + divGap + 1 + divGap + labelWidth + pad;
+}
+function portLabelExtent(port) {
+  const badgeGap = 5;
+  return PORT_RADIUS + badgeGap + portBadgeWidth(port);
+}
 function computeNodeDimensions(node) {
   const maxPorts = Math.max(node.inputs.length, node.outputs.length);
   const portsHeight = maxPorts > 0 ? PORT_PADDING_Y + maxPorts * PORT_SIZE + (maxPorts - 1) * PORT_GAP + PORT_PADDING_Y : 0;
@@ -58309,13 +58324,13 @@ function computeConnectionPath(sx, sy, tx, ty) {
   const deUy = deY / deLen;
   const [cx, cy] = quadCurveControl(bx, by, dx, dy, -deUx, -deUy);
   const [fx, fy] = quadCurveControl(gx, gy, ex, ey, deUx, deUy);
-  let path37 = `M ${cx},${cy} M ${ax},${ay}`;
-  path37 += ` L ${bx},${by}`;
-  path37 += ` Q ${cx},${cy} ${dx},${dy}`;
-  path37 += ` L ${ex},${ey}`;
-  path37 += ` Q ${fx},${fy} ${gx},${gy}`;
-  path37 += ` L ${hx},${hy}`;
-  return path37;
+  let path38 = `M ${cx},${cy} M ${ax},${ay}`;
+  path38 += ` L ${bx},${by}`;
+  path38 += ` Q ${cx},${cy} ${dx},${dy}`;
+  path38 += ` L ${ex},${ey}`;
+  path38 += ` Q ${fx},${fy} ${gx},${gy}`;
+  path38 += ` L ${hx},${hy}`;
+  return path38;
 }
 function orderedPorts(ports, direction) {
   const cloned = {};
@@ -58454,8 +58469,12 @@ function buildScopeSubGraph(parentNode, parentNt, scopeName, childIds, ast, node
   const parentUI = ast.ui?.instances?.find((u) => u.name === parentNode.id);
   const uiWidth = parentUI?.expandedWidth ?? parentUI?.width;
   const uiHeight = parentUI?.expandedHeight ?? parentUI?.height;
-  const computedWidth = SCOPE_PORT_COLUMN + SCOPE_PADDING + childrenWidth + SCOPE_PADDING + SCOPE_PORT_COLUMN;
-  const computedHeight = SCOPE_PADDING * 2 + Math.max(childrenHeight, scopeOutPortsHeight, scopeInPortsHeight);
+  const maxLeftLabelExtent = scopeOutputPorts.length > 0 ? Math.max(...scopeOutputPorts.map(portLabelExtent)) : 0;
+  const maxRightLabelExtent = scopeInputPorts.length > 0 ? Math.max(...scopeInputPorts.map(portLabelExtent)) : 0;
+  const minInnerWidth = maxLeftLabelExtent + LABEL_CLEARANCE + maxRightLabelExtent;
+  const contentWidth = Math.max(childrenWidth, minInnerWidth);
+  const computedWidth = SCOPE_PORT_COLUMN + SCOPE_PADDING_X + contentWidth + SCOPE_PADDING_X + SCOPE_PORT_COLUMN;
+  const computedHeight = SCOPE_PADDING_Y * 2 + Math.max(childrenHeight, scopeOutPortsHeight, scopeInPortsHeight);
   parentNode.width = Math.max(parentNode.width, uiWidth ?? computedWidth);
   parentNode.height = Math.max(parentNode.height, uiHeight ?? computedHeight);
   parentNode.scopeChildren = children;
@@ -58466,13 +58485,13 @@ function finalizeScopePositions(parentNode, ast, theme = "dark") {
   const children = parentNode.scopeChildren;
   const scopePorts = parentNode.scopePorts;
   if (!children || children.length === 0 || !scopePorts) return;
-  const innerLeft = parentNode.x + SCOPE_PORT_COLUMN + SCOPE_PADDING;
-  const innerRight = parentNode.x + parentNode.width - SCOPE_PORT_COLUMN - SCOPE_PADDING;
+  const innerLeft = parentNode.x + SCOPE_PORT_COLUMN + SCOPE_PADDING_X;
+  const innerRight = parentNode.x + parentNode.width - SCOPE_PORT_COLUMN - SCOPE_PADDING_X;
   const innerWidth = innerRight - innerLeft;
   const lastChild = children[children.length - 1];
   const childrenBlockWidth = lastChild.x + lastChild.width;
   const centerOffsetX = innerLeft + (innerWidth - childrenBlockWidth) / 2;
-  const scopeOriginY = parentNode.y + SCOPE_PADDING;
+  const scopeOriginY = parentNode.y + SCOPE_PADDING_Y;
   for (const child of children) {
     child.x += centerOffsetX;
     child.y += scopeOriginY;
@@ -58599,7 +58618,7 @@ function finalizeScopePositions(parentNode, ast, theme = "dark") {
 function buildConnection(fromNode, fromPort, toNode, toPort, sourcePort, targetPort, theme = "dark") {
   const sourceColor = getPortColor(sourcePort.dataType, sourcePort.isFailure, theme);
   const targetColor = getPortColor(targetPort.dataType, targetPort.isFailure, theme);
-  const path37 = computeConnectionPath(sourcePort.cx, sourcePort.cy, targetPort.cx, targetPort.cy);
+  const path38 = computeConnectionPath(sourcePort.cx, sourcePort.cy, targetPort.cx, targetPort.cy);
   return {
     fromNode,
     fromPort,
@@ -58608,13 +58627,136 @@ function buildConnection(fromNode, fromPort, toNode, toPort, sourcePort, targetP
     sourceColor,
     targetColor,
     isStepConnection: sourcePort.dataType === "STEP",
-    path: path37
+    path: path38
   };
 }
 function portsColumnHeight(count) {
   if (count === 0) return 0;
   return PORT_PADDING_Y + count * PORT_SIZE + (count - 1) * PORT_GAP + PORT_PADDING_Y;
 }
+function extractExplicitPositions(ast) {
+  const positions = /* @__PURE__ */ new Map();
+  if (ast.ui?.startNode?.x != null && ast.ui.startNode.y != null) {
+    positions.set("Start", { x: ast.ui.startNode.x, y: ast.ui.startNode.y });
+  }
+  if (ast.ui?.exitNode?.x != null && ast.ui.exitNode.y != null) {
+    positions.set("Exit", { x: ast.ui.exitNode.x, y: ast.ui.exitNode.y });
+  }
+  for (const inst of ast.instances) {
+    if (inst.config?.x != null && inst.config.y != null) {
+      positions.set(inst.id, { x: inst.config.x, y: inst.config.y });
+    }
+  }
+  return positions;
+}
+function layerOutputExtent(layerNodes, diagramNodes) {
+  let max = 0;
+  for (const id of layerNodes) {
+    const node = diagramNodes.get(id);
+    max = Math.max(max, maxPortLabelExtent(node.outputs));
+  }
+  return max;
+}
+function layerInputExtent(layerNodes, diagramNodes) {
+  let max = 0;
+  for (const id of layerNodes) {
+    const node = diagramNodes.get(id);
+    max = Math.max(max, maxPortLabelExtent(node.inputs));
+  }
+  return max;
+}
+function assignLayerCoordinates(layers, diagramNodes) {
+  const filtered = layers.map((l) => l.filter((id) => diagramNodes.has(id)));
+  let currentX = 0;
+  for (let i = 0; i < filtered.length; i++) {
+    const layerNodes = filtered[i];
+    if (layerNodes.length === 0) {
+      currentX += LAYER_GAP_X;
+      continue;
+    }
+    const maxWidth = Math.max(...layerNodes.map((id) => diagramNodes.get(id).width));
+    const totalHeight = layerNodes.reduce((sum, id) => {
+      const n = diagramNodes.get(id);
+      return sum + n.height + LABEL_HEIGHT + LABEL_GAP;
+    }, 0) + (layerNodes.length - 1) * NODE_GAP_Y;
+    let currentY = -totalHeight / 2;
+    for (const id of layerNodes) {
+      const node = diagramNodes.get(id);
+      currentY += LABEL_HEIGHT + LABEL_GAP;
+      node.x = currentX + (maxWidth - node.width) / 2;
+      node.y = currentY;
+      currentY += node.height + NODE_GAP_Y;
+    }
+    const nextLayerNodes = filtered[i + 1];
+    if (nextLayerNodes && nextLayerNodes.length > 0) {
+      const outputOverhang = layerOutputExtent(layerNodes, diagramNodes);
+      const inputOverhang = layerInputExtent(nextLayerNodes, diagramNodes);
+      const labelMinGap = outputOverhang + LABEL_CLEARANCE + inputOverhang;
+      const edgeGap = Math.max(labelMinGap, LAYER_GAP_X - maxWidth, MIN_EDGE_GAP);
+      currentX += maxWidth + edgeGap;
+    } else {
+      currentX += maxWidth + LAYER_GAP_X;
+    }
+  }
+}
+function assignUnpositionedNodes(layers, diagramNodes, explicitPositions) {
+  for (const [id, pos] of explicitPositions) {
+    const node = diagramNodes.get(id);
+    if (node) {
+      node.x = pos.x;
+      node.y = pos.y;
+    }
+  }
+  const filtered = layers.map((l) => l.filter((id) => diagramNodes.has(id)));
+  let currentX = 0;
+  for (let i = 0; i < filtered.length; i++) {
+    const layerNodes = filtered[i];
+    if (layerNodes.length === 0) {
+      currentX += LAYER_GAP_X;
+      continue;
+    }
+    const unpositioned = layerNodes.filter((id) => !explicitPositions.has(id));
+    const maxWidth = Math.max(...layerNodes.map((id) => diagramNodes.get(id).width));
+    if (unpositioned.length > 0) {
+      const totalHeight = unpositioned.reduce((sum, id) => {
+        const n = diagramNodes.get(id);
+        return sum + n.height + LABEL_HEIGHT + LABEL_GAP;
+      }, 0) + (unpositioned.length - 1) * NODE_GAP_Y;
+      let currentY = -totalHeight / 2;
+      for (const id of unpositioned) {
+        const node = diagramNodes.get(id);
+        currentY += LABEL_HEIGHT + LABEL_GAP;
+        node.x = currentX + (maxWidth - node.width) / 2;
+        node.y = currentY;
+        currentY += node.height + NODE_GAP_Y;
+      }
+    }
+    const nextLayerNodes = filtered[i + 1];
+    if (nextLayerNodes && nextLayerNodes.length > 0) {
+      const outputOverhang = layerOutputExtent(layerNodes, diagramNodes);
+      const inputOverhang = layerInputExtent(nextLayerNodes, diagramNodes);
+      const labelMinGap = outputOverhang + LABEL_CLEARANCE + inputOverhang;
+      const edgeGap = Math.max(labelMinGap, LAYER_GAP_X - maxWidth, MIN_EDGE_GAP);
+      currentX += maxWidth + edgeGap;
+    } else {
+      currentX += maxWidth + LAYER_GAP_X;
+    }
+  }
+}
+function resolveHorizontalOverlaps(diagramNodes) {
+  const nodes = [...diagramNodes.values()].sort((a, b) => a.x - b.x);
+  for (let i = 1; i < nodes.length; i++) {
+    const prev = nodes[i - 1];
+    const curr = nodes[i];
+    const prevRightExtent = maxPortLabelExtent(prev.outputs);
+    const currLeftExtent = maxPortLabelExtent(curr.inputs);
+    const minGap = Math.max(prevRightExtent + LABEL_CLEARANCE + currLeftExtent, MIN_EDGE_GAP);
+    const actualGap = curr.x - (prev.x + prev.width);
+    if (actualGap < minGap) {
+      curr.x = prev.x + prev.width + minGap;
+    }
+  }
+}
 function buildDiagramGraph(ast, options = {}) {
   const themeName = options.theme ?? "dark";
   const nodeTypeMap = /* @__PURE__ */ new Map();
@@ -58712,28 +58854,24 @@ function buildDiagramGraph(ast, options = {}) {
     if (!parentNt) continue;
     buildScopeSubGraph(parentNode, parentNt, scopeName, childIds, ast, nodeTypeMap, themeName);
   }
-  const { layers } = layoutWorkflow(ast);
-  let currentX = 0;
-  for (const layer of layers) {
-    const layerNodes = layer.filter((id) => diagramNodes.has(id));
-    if (layerNodes.length === 0) {
-      currentX += LAYER_GAP_X;
-      continue;
-    }
-    const maxWidth = Math.max(...layerNodes.map((id) => diagramNodes.get(id).width));
-    const totalHeight = layerNodes.reduce((sum, id) => {
-      const n = diagramNodes.get(id);
-      return sum + n.height + LABEL_HEIGHT + LABEL_GAP;
-    }, 0) + (layerNodes.length - 1) * NODE_GAP_Y;
-    let currentY = -totalHeight / 2;
-    for (const id of layerNodes) {
+  const explicitPositions = extractExplicitPositions(ast);
+  const allPositioned = [...diagramNodes.keys()].every((id) => explicitPositions.has(id));
+  const nonePositioned = ![...diagramNodes.keys()].some((id) => explicitPositions.has(id));
+  if (allPositioned) {
+    for (const [id, pos] of explicitPositions) {
       const node = diagramNodes.get(id);
-      currentY += LABEL_HEIGHT + LABEL_GAP;
-      node.x = currentX + (maxWidth - node.width) / 2;
-      node.y = currentY;
-      currentY += node.height + NODE_GAP_Y;
+      if (node) {
+        node.x = pos.x;
+        node.y = pos.y;
+      }
     }
-    currentX += maxWidth + LAYER_GAP_X;
+    resolveHorizontalOverlaps(diagramNodes);
+  } else if (nonePositioned) {
+    const { layers } = layoutWorkflow(ast);
+    assignLayerCoordinates(layers, diagramNodes);
+  } else {
+    const { layers } = layoutWorkflow(ast);
+    assignUnpositionedNodes(layers, diagramNodes, explicitPositions);
   }
   for (const node of diagramNodes.values()) {
     computePortPositions(node);
@@ -58862,7 +59000,7 @@ function buildDiagramGraph(ast, options = {}) {
     const dx = tx - sx;
     const dy = ty - sy;
     const distance = Math.sqrt(dx * dx + dy * dy);
-    let path37;
+    let path38;
     if (distance > ORTHOGONAL_DISTANCE_THRESHOLD) {
       const orthoPath = calculateOrthogonalPathSafe(
         [sx, sy],
@@ -58873,9 +59011,9 @@ function buildDiagramGraph(ast, options = {}) {
         { fromPortIndex: pc.fromPortIndex, toPortIndex: pc.toPortIndex },
         allocator
       );
-      path37 = orthoPath ?? computeConnectionPath(sx, sy, tx, ty);
+      path38 = orthoPath ?? computeConnectionPath(sx, sy, tx, ty);
     } else {
-      path37 = computeConnectionPath(sx, sy, tx, ty);
+      path38 = computeConnectionPath(sx, sy, tx, ty);
     }
     const sourceColor = getPortColor(pc.sourcePort.dataType, pc.sourcePort.isFailure, themeName);
     const targetColor = getPortColor(pc.targetPort.dataType, pc.targetPort.isFailure, themeName);
@@ -58887,7 +59025,7 @@ function buildDiagramGraph(ast, options = {}) {
       sourceColor,
       targetColor,
       isStepConnection: pc.sourcePort.dataType === "STEP",
-      path: path37
+      path: path38
     });
   }
   for (const node of nodes) {
@@ -58954,12 +59092,12 @@ function resolveDefaultIcon(nt) {
   if (nt.variant === "WORKFLOW" || nt.variant === "IMPORTED_WORKFLOW") return "flow";
   return "code";
 }
-function pathExtent(path37) {
+function pathExtent(path38) {
   let maxX = -Infinity;
   let maxY = -Infinity;
   const pattern = /(-?[\d.]+),(-?[\d.]+)/g;
   let m;
-  while ((m = pattern.exec(path37)) !== null) {
+  while ((m = pattern.exec(path38)) !== null) {
     maxX = Math.max(maxX, parseFloat(m[1]));
     maxY = Math.max(maxY, parseFloat(m[2]));
   }
@@ -59026,63 +59164,81 @@ function renderSVG(graph, options = {}) {
   parts2.push(`<rect width="${vbWidth}" height="${vbHeight}" fill="url(#dot-grid)"/>`);
   parts2.push(`<g class="connections">`);
   for (let i = 0; i < graph.connections.length; i++) {
-    const conn = graph.connections[i];
-    const dashAttr = conn.isStepConnection ? "" : ' stroke-dasharray="8 4"';
-    parts2.push(
-      `  <path d="${conn.path}" fill="none" stroke="url(#conn-grad-${i})" stroke-width="3"${dashAttr} stroke-linecap="round"/>`
-    );
+    renderConnection(parts2, graph.connections[i], i);
   }
   parts2.push(`</g>`);
   parts2.push(`<g class="nodes">`);
   for (const node of graph.nodes) {
-    parts2.push(renderNode(node, theme, themeName, showPortLabels, allConnections));
+    parts2.push(renderNode(node, theme, themeName, allConnections));
+  }
+  parts2.push(`</g>`);
+  parts2.push(`<g class="labels">`);
+  for (const node of graph.nodes) {
+    renderNodeLabel(parts2, node, theme);
+    renderPortLabelsForNode(parts2, node, theme, themeName, showPortLabels);
+    if (node.scopeChildren) {
+      for (const child of node.scopeChildren) {
+        renderNodeLabel(parts2, child, theme);
+      }
+      if (showPortLabels && node.scopePorts) {
+        renderPortLabels(parts2, node.id, node.scopePorts.inputs, node.scopePorts.outputs, theme, themeName);
+      }
+      for (const child of node.scopeChildren) {
+        renderPortLabelsForNode(parts2, child, theme, themeName, showPortLabels);
+      }
+    }
   }
   parts2.push(`</g>`);
   parts2.push(`</svg>`);
   return parts2.join("\n");
 }
-function renderNode(node, theme, themeName, showPortLabels, allConnections) {
-  const parts2 = [];
-  parts2.push(`  <g>`);
-  const isScoped = !!(node.scopeChildren && node.scopeChildren.length > 0);
-  const labelText = escapeXml(node.label);
-  const textWidth = labelText.length * 7;
-  const labelBgWidth = textWidth + 16;
-  const labelBgHeight = LABEL_HEIGHT;
-  const labelBgX = isScoped ? node.x : node.x + node.width / 2 - labelBgWidth / 2;
-  const labelBgY = node.y - LABEL_GAP - labelBgHeight;
-  const labelTextX = isScoped ? node.x + 8 : node.x + node.width / 2;
-  const labelAnchor = isScoped ? "start" : "middle";
+function renderConnection(parts2, conn, gradIndex) {
+  const dashAttr = conn.isStepConnection ? "" : ' stroke-dasharray="8 4"';
   parts2.push(
-    `    <rect x="${labelBgX}" y="${labelBgY}" width="${labelBgWidth}" height="${labelBgHeight}" rx="6" fill="${theme.labelBadgeFill}" opacity="0.8"/>`
+    `  <path d="${conn.path}" fill="none" stroke="url(#conn-grad-${gradIndex})" stroke-width="3"${dashAttr} stroke-linecap="round" data-source="${escapeXml(conn.fromNode)}.${escapeXml(conn.fromPort)}" data-target="${escapeXml(conn.toNode)}.${escapeXml(conn.toPort)}"/>`
   );
+}
+function renderScopeConnection(parts2, conn, allConnections) {
+  const gradIndex = allConnections.indexOf(conn);
+  if (gradIndex < 0) return;
+  const dashAttr = conn.isStepConnection ? "" : ' stroke-dasharray="8 4"';
   parts2.push(
-    `    <text class="node-label" x="${labelTextX}" y="${labelBgY + labelBgHeight / 2 + 6}" text-anchor="${labelAnchor}" fill="${node.color !== "#334155" ? node.color : theme.labelColor}">${labelText}</text>`
+    `    <path d="${conn.path}" fill="none" stroke="url(#conn-grad-${gradIndex})" stroke-width="2.5"${dashAttr} stroke-linecap="round" data-source="${escapeXml(conn.fromNode)}.${escapeXml(conn.fromPort)}" data-target="${escapeXml(conn.toNode)}.${escapeXml(conn.toPort)}"/>`
   );
+}
+function renderNodeBody(parts2, node, theme, indent) {
   const strokeColor = node.color !== "#334155" ? node.color : theme.nodeIconColor;
   parts2.push(
-    `    <rect x="${node.x}" y="${node.y}" width="${node.width}" height="${node.height}" rx="${BORDER_RADIUS}" fill="${theme.nodeFill}" stroke="${strokeColor}" stroke-width="2"/>`
+    `${indent}<rect x="${node.x}" y="${node.y}" width="${node.width}" height="${node.height}" rx="${BORDER_RADIUS}" fill="${theme.nodeFill}" stroke="${strokeColor}" stroke-width="2"/>`
   );
+  const iconPath = NODE_ICON_PATHS[node.icon] ?? NODE_ICON_PATHS.code;
+  const iconColor = node.color !== "#334155" ? node.color : theme.nodeIconColor;
+  const iconSize = 40;
+  const iconX = node.x + (node.width - iconSize) / 2;
+  const iconY = node.y + (node.height - iconSize) / 2;
+  parts2.push(
+    `${indent}<svg x="${iconX}" y="${iconY}" width="${iconSize}" height="${iconSize}" viewBox="0 -960 960 960"><path d="${iconPath}" fill="${iconColor}"/></svg>`
+  );
+}
+function renderNode(node, theme, themeName, allConnections) {
+  const parts2 = [];
+  parts2.push(`  <g data-node-id="${escapeXml(node.id)}">`);
   if (node.scopeChildren && node.scopeChildren.length > 0) {
-    renderScopedContent(parts2, node, theme, themeName, showPortLabels, allConnections);
-  } else {
-    const iconPath = getNodeIconPath(node);
-    const iconColor = getNodeIconColor(node, theme);
-    const iconSize = 40;
-    const iconX = node.x + (node.width - iconSize) / 2;
-    const iconY = node.y + (node.height - iconSize) / 2;
+    const strokeColor = node.color !== "#334155" ? node.color : theme.nodeIconColor;
     parts2.push(
-      `    <svg x="${iconX}" y="${iconY}" width="${iconSize}" height="${iconSize}" viewBox="0 -960 960 960"><path d="${iconPath}" fill="${iconColor}"/></svg>`
+      `    <rect x="${node.x}" y="${node.y}" width="${node.width}" height="${node.height}" rx="${BORDER_RADIUS}" fill="${theme.nodeFill}" stroke="${strokeColor}" stroke-width="2"/>`
     );
+    renderScopedContent(parts2, node, theme, themeName, allConnections);
+  } else {
+    renderNodeBody(parts2, node, theme, "    ");
   }
-  renderPorts(parts2, node.inputs, node.outputs, theme, themeName, showPortLabels);
+  renderPortDots(parts2, node.id, node.inputs, node.outputs, themeName);
   parts2.push(`  </g>`);
   return parts2.join("\n");
 }
-function renderScopedContent(parts2, node, theme, themeName, showPortLabels, allConnections) {
+function renderScopedContent(parts2, node, theme, themeName, allConnections) {
   const children = node.scopeChildren;
   const scopePorts = node.scopePorts;
-  const scopeConns = node.scopeConnections ?? [];
   const scopeX = node.x + SCOPE_PORT_COLUMN;
   const scopeY = node.y + 4;
   const scopeW = node.width - SCOPE_PORT_COLUMN * 2;
@@ -59090,92 +59246,82 @@ function renderScopedContent(parts2, node, theme, themeName, showPortLabels, all
   parts2.push(
     `    <rect x="${scopeX}" y="${scopeY}" width="${scopeW}" height="${scopeH}" rx="4" fill="none" stroke="${theme.scopeAreaStroke}" stroke-width="1" stroke-dasharray="4 2" opacity="0.5"/>`
   );
-  if (scopePorts) {
-    renderPorts(parts2, scopePorts.inputs, scopePorts.outputs, theme, themeName, showPortLabels);
+  for (const conn of node.scopeConnections ?? []) {
+    renderScopeConnection(parts2, conn, allConnections);
   }
-  for (const conn of scopeConns) {
-    const gradIndex = allConnections.indexOf(conn);
-    if (gradIndex < 0) continue;
-    const dashAttr = conn.isStepConnection ? "" : ' stroke-dasharray="8 4"';
-    parts2.push(
-      `    <path d="${conn.path}" fill="none" stroke="url(#conn-grad-${gradIndex})" stroke-width="2.5"${dashAttr} stroke-linecap="round"/>`
-    );
+  if (scopePorts) {
+    renderPortDots(parts2, node.id, scopePorts.inputs, scopePorts.outputs, themeName);
   }
   for (const child of children) {
-    const childLabelX = child.x + child.width / 2;
-    const childLabelText = escapeXml(child.label);
-    const childTextWidth = childLabelText.length * 7;
-    const childLabelBgW = childTextWidth + 16;
-    const childLabelBgH = LABEL_HEIGHT;
-    const childLabelBgX = childLabelX - childLabelBgW / 2;
-    const childLabelBgY = child.y - LABEL_GAP - childLabelBgH;
-    parts2.push(
-      `    <rect x="${childLabelBgX}" y="${childLabelBgY}" width="${childLabelBgW}" height="${childLabelBgH}" rx="6" fill="${theme.labelBadgeFill}" opacity="0.8"/>`
-    );
-    parts2.push(
-      `    <text class="node-label" x="${childLabelX}" y="${childLabelBgY + childLabelBgH / 2 + 6}" text-anchor="middle" fill="${child.color !== "#334155" ? child.color : theme.labelColor}">${childLabelText}</text>`
-    );
-    const childStroke = child.color !== "#334155" ? child.color : theme.nodeIconColor;
-    parts2.push(
-      `    <rect x="${child.x}" y="${child.y}" width="${child.width}" height="${child.height}" rx="${BORDER_RADIUS}" fill="${theme.nodeFill}" stroke="${childStroke}" stroke-width="2"/>`
-    );
-    const iconPath = getNodeIconPath(child);
-    const iconColor = getNodeIconColor(child, theme);
-    const iconSize = 40;
-    const iconX = child.x + (child.width - iconSize) / 2;
-    const iconY = child.y + (child.height - iconSize) / 2;
-    parts2.push(
-      `    <svg x="${iconX}" y="${iconY}" width="${iconSize}" height="${iconSize}" viewBox="0 -960 960 960"><path d="${iconPath}" fill="${iconColor}"/></svg>`
-    );
-    renderPorts(parts2, child.inputs, child.outputs, theme, themeName, showPortLabels);
+    parts2.push(`    <g data-node-id="${escapeXml(child.id)}">`);
+    renderNodeBody(parts2, child, theme, "      ");
+    renderPortDots(parts2, child.id, child.inputs, child.outputs, themeName);
+    parts2.push(`    </g>`);
   }
 }
-function getNodeIconPath(node) {
-  return NODE_ICON_PATHS[node.icon] ?? NODE_ICON_PATHS.code;
+function renderNodeLabel(parts2, node, theme) {
+  const isScoped = !!(node.scopeChildren && node.scopeChildren.length > 0);
+  const labelText = escapeXml(node.label);
+  const textWidth = labelText.length * 7;
+  const labelBgWidth = textWidth + 16;
+  const labelBgHeight = LABEL_HEIGHT;
+  const labelBgX = isScoped ? node.x : node.x + node.width / 2 - labelBgWidth / 2;
+  const labelBgY = node.y - LABEL_GAP - labelBgHeight;
+  const labelTextX = isScoped ? node.x + 8 : node.x + node.width / 2;
+  const labelAnchor = isScoped ? "start" : "middle";
+  parts2.push(`    <g data-label-for="${escapeXml(node.id)}">`);
+  parts2.push(`      <rect x="${labelBgX}" y="${labelBgY}" width="${labelBgWidth}" height="${labelBgHeight}" rx="6" fill="${theme.labelBadgeFill}" opacity="0.8"/>`);
+  parts2.push(`      <text class="node-label" x="${labelTextX}" y="${labelBgY + labelBgHeight / 2 + 6}" text-anchor="${labelAnchor}" fill="${node.color !== "#334155" ? node.color : theme.labelColor}">${labelText}</text>`);
+  parts2.push(`    </g>`);
 }
-function getNodeIconColor(node, theme) {
-  if (node.color !== "#334155") return node.color;
-  return theme.nodeIconColor;
+function renderPortLabelsForNode(parts2, node, theme, themeName, showPortLabels) {
+  if (showPortLabels) {
+    renderPortLabels(parts2, node.id, node.inputs, node.outputs, theme, themeName);
+  }
 }
-function renderPorts(parts2, inputs, outputs, theme, themeName, showPortLabels) {
+function renderPortDots(parts2, nodeId, inputs, outputs, themeName) {
   for (const port of [...inputs, ...outputs]) {
     const color = getPortColor(port.dataType, port.isFailure, themeName);
     const ringColor = getPortRingColor(port.dataType, port.isFailure, themeName);
-    parts2.push(`    <circle cx="${port.cx}" cy="${port.cy}" r="${PORT_RADIUS}" fill="${color}" stroke="${ringColor}" stroke-width="2"/>`);
-    if (showPortLabels) {
-      const isInput = port.direction === "INPUT";
-      const abbrev = TYPE_ABBREVIATIONS[port.dataType] ?? port.dataType;
-      const portLabel = port.label;
-      const typeWidth = measureText(abbrev);
-      const labelWidth = measureText(portLabel);
-      const pad = 7;
-      const divGap = 4;
-      const badgeWidth = pad + typeWidth + divGap + 1 + divGap + labelWidth + pad;
-      const badgeHeight = 16;
-      const badgeGap = 5;
-      const rr = badgeHeight / 2;
-      if (isInput) {
-        const badgeX = port.cx - PORT_RADIUS - badgeGap - badgeWidth;
-        const badgeY = port.cy - badgeHeight / 2;
-        parts2.push(`    <rect x="${badgeX}" y="${badgeY}" width="${badgeWidth}" height="${badgeHeight}" rx="${rr}" fill="${theme.nodeFill}" stroke="${theme.labelBadgeBorder}" stroke-width="1"/>`);
-        const typeX = badgeX + badgeWidth - pad - typeWidth / 2;
-        const divX = typeX - typeWidth / 2 - divGap;
-        const nameX = divX - divGap;
-        parts2.push(`    <line x1="${divX}" y1="${badgeY + 3}" x2="${divX}" y2="${badgeY + badgeHeight - 3}" stroke="${theme.labelBadgeBorder}" stroke-width="1"/>`);
-        parts2.push(`    <text class="port-label" x="${nameX}" y="${port.cy + 3.5}" text-anchor="end">${escapeXml(portLabel)}</text>`);
-        parts2.push(`    <text class="port-type-label" x="${typeX}" y="${port.cy + 3.5}" text-anchor="middle" fill="${color}">${escapeXml(abbrev)}</text>`);
-      } else {
-        const badgeX = port.cx + PORT_RADIUS + badgeGap;
-        const badgeY = port.cy - badgeHeight / 2;
-        parts2.push(`    <rect x="${badgeX}" y="${badgeY}" width="${badgeWidth}" height="${badgeHeight}" rx="${rr}" fill="${theme.nodeFill}" stroke="${theme.labelBadgeBorder}" stroke-width="1"/>`);
-        const typeX = badgeX + pad + typeWidth / 2;
-        const divX = badgeX + pad + typeWidth + divGap;
-        const nameX = divX + 1 + divGap;
-        parts2.push(`    <line x1="${divX}" y1="${badgeY + 3}" x2="${divX}" y2="${badgeY + badgeHeight - 3}" stroke="${theme.labelBadgeBorder}" stroke-width="1"/>`);
-        parts2.push(`    <text class="port-type-label" x="${typeX}" y="${port.cy + 3.5}" text-anchor="middle" fill="${color}">${escapeXml(abbrev)}</text>`);
-        parts2.push(`    <text class="port-label" x="${nameX}" y="${port.cy + 3.5}" text-anchor="start">${escapeXml(portLabel)}</text>`);
-      }
+    const dir = port.direction === "INPUT" ? "input" : "output";
+    parts2.push(`    <circle cx="${port.cx}" cy="${port.cy}" r="${PORT_RADIUS}" fill="${color}" stroke="${ringColor}" stroke-width="2" data-port-id="${escapeXml(nodeId)}.${escapeXml(port.name)}" data-direction="${dir}"/>`);
+  }
+}
+function renderPortLabels(parts2, nodeId, inputs, outputs, theme, themeName) {
+  for (const port of [...inputs, ...outputs]) {
+    const color = getPortColor(port.dataType, port.isFailure, themeName);
+    const isInput = port.direction === "INPUT";
+    const abbrev = TYPE_ABBREVIATIONS[port.dataType] ?? port.dataType;
+    const portId = `${escapeXml(nodeId)}.${escapeXml(port.name)}`;
+    const portLabel = port.label;
+    const typeWidth = measureText(abbrev);
+    const labelWidth = measureText(portLabel);
+    const pad = 7;
+    const divGap = 4;
+    const badgeWidth = pad + typeWidth + divGap + 1 + divGap + labelWidth + pad;
+    const badgeHeight = 16;
+    const badgeGap = 5;
+    const rr = badgeHeight / 2;
+    const badgeX = isInput ? port.cx - PORT_RADIUS - badgeGap - badgeWidth : port.cx + PORT_RADIUS + badgeGap;
+    const badgeY = port.cy - badgeHeight / 2;
+    parts2.push(`    <g data-port-label="${portId}">`);
+    parts2.push(`      <rect x="${badgeX}" y="${badgeY}" width="${badgeWidth}" height="${badgeHeight}" rx="${rr}" fill="${theme.nodeFill}" stroke="${theme.labelBadgeBorder}" stroke-width="1"/>`);
+    if (isInput) {
+      const typeX = badgeX + badgeWidth - pad - typeWidth / 2;
+      const divX = typeX - typeWidth / 2 - divGap;
+      const nameX = divX - divGap;
+      parts2.push(`      <line x1="${divX}" y1="${badgeY + 3}" x2="${divX}" y2="${badgeY + badgeHeight - 3}" stroke="${theme.labelBadgeBorder}" stroke-width="1"/>`);
+      parts2.push(`      <text class="port-label" x="${nameX}" y="${port.cy + 3.5}" text-anchor="end">${escapeXml(portLabel)}</text>`);
+      parts2.push(`      <text class="port-type-label" x="${typeX}" y="${port.cy + 3.5}" text-anchor="middle" fill="${color}">${escapeXml(abbrev)}</text>`);
+    } else {
+      const typeX = badgeX + pad + typeWidth / 2;
+      const divX = badgeX + pad + typeWidth + divGap;
+      const nameX = divX + 1 + divGap;
+      parts2.push(`      <line x1="${divX}" y1="${badgeY + 3}" x2="${divX}" y2="${badgeY + badgeHeight - 3}" stroke="${theme.labelBadgeBorder}" stroke-width="1"/>`);
+      parts2.push(`      <text class="port-type-label" x="${typeX}" y="${port.cy + 3.5}" text-anchor="middle" fill="${color}">${escapeXml(abbrev)}</text>`);
+      parts2.push(`      <text class="port-label" x="${nameX}" y="${port.cy + 3.5}" text-anchor="start">${escapeXml(portLabel)}</text>`);
     }
+    parts2.push(`    </g>`);
   }
 }
 
@@ -61570,13 +61716,13 @@ var PromisePolyfill = class extends Promise {
   // Available starting from Node 22
   // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/withResolvers
   static withResolver() {
-    let resolve26;
+    let resolve27;
     let reject2;
     const promise = new Promise((res, rej) => {
-      resolve26 = res;
+      resolve27 = res;
       reject2 = rej;
     });
-    return { promise, resolve: resolve26, reject: reject2 };
+    return { promise, resolve: resolve27, reject: reject2 };
   }
 };
 
@@ -61610,7 +61756,7 @@ function createPrompt(view) {
       output
     });
     const screen = new ScreenManager(rl);
-    const { promise, resolve: resolve26, reject: reject2 } = PromisePolyfill.withResolver();
+    const { promise, resolve: resolve27, reject: reject2 } = PromisePolyfill.withResolver();
     const cancel = () => reject2(new CancelPromptError());
     if (signal) {
       const abort = () => reject2(new AbortPromptError({ cause: signal.reason }));
@@ -61637,7 +61783,7 @@ function createPrompt(view) {
       cycle(() => {
         try {
           const nextView = view(config2, (value2) => {
-            setImmediate(() => resolve26(value2));
+            setImmediate(() => resolve27(value2));
           });
           if (nextView === void 0) {
             const callerFilename = callSites[1]?.getFileName();
@@ -62218,13 +62364,13 @@ var PromisePolyfill2 = class extends Promise {
   // Available starting from Node 22
   // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/withResolvers
   static withResolver() {
-    let resolve26;
+    let resolve27;
     let reject2;
     const promise = new Promise((res, rej) => {
-      resolve26 = res;
+      resolve27 = res;
       reject2 = rej;
     });
-    return { promise, resolve: resolve26, reject: reject2 };
+    return { promise, resolve: resolve27, reject: reject2 };
   }
 };
 
@@ -62258,7 +62404,7 @@ function createPrompt2(view) {
       output
     });
     const screen = new ScreenManager2(rl);
-    const { promise, resolve: resolve26, reject: reject2 } = PromisePolyfill2.withResolver();
+    const { promise, resolve: resolve27, reject: reject2 } = PromisePolyfill2.withResolver();
     const cancel = () => reject2(new CancelPromptError2());
     if (signal) {
       const abort = () => reject2(new AbortPromptError2({ cause: signal.reason }));
@@ -62285,7 +62431,7 @@ function createPrompt2(view) {
       cycle(() => {
         try {
           const nextView = view(config2, (value2) => {
-            setImmediate(() => resolve26(value2));
+            setImmediate(() => resolve27(value2));
           });
           if (nextView === void 0) {
             const callerFilename = callSites[1]?.getFileName();
@@ -62837,13 +62983,13 @@ var PromisePolyfill3 = class extends Promise {
   // Available starting from Node 22
   // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/withResolvers
   static withResolver() {
-    let resolve26;
+    let resolve27;
     let reject2;
     const promise = new Promise((res, rej) => {
-      resolve26 = res;
+      resolve27 = res;
       reject2 = rej;
     });
-    return { promise, resolve: resolve26, reject: reject2 };
+    return { promise, resolve: resolve27, reject: reject2 };
   }
 };
 
@@ -62877,7 +63023,7 @@ function createPrompt3(view) {
       output
     });
     const screen = new ScreenManager3(rl);
-    const { promise, resolve: resolve26, reject: reject2 } = PromisePolyfill3.withResolver();
+    const { promise, resolve: resolve27, reject: reject2 } = PromisePolyfill3.withResolver();
     const cancel = () => reject2(new CancelPromptError3());
     if (signal) {
       const abort = () => reject2(new AbortPromptError3({ cause: signal.reason }));
@@ -62904,7 +63050,7 @@ function createPrompt3(view) {
       cycle(() => {
         try {
           const nextView = view(config2, (value2) => {
-            setImmediate(() => resolve26(value2));
+            setImmediate(() => resolve27(value2));
           });
           if (nextView === void 0) {
             const callerFilename = callSites[1]?.getFileName();
@@ -63764,6 +63910,7 @@ import { spawn } from "child_process";
 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);
@@ -63814,7 +63961,7 @@ async function executeWorkflowFromFile(filePath, params, options) {
     if (options?.mocks) {
       globalThis.__fw_mocks__ = options.mocks;
     }
-    const mod = await import(tmpFile);
+    const mod = await import(pathToFileURL(tmpFile).href);
     const exportedFn = findExportedFunction(mod, options?.workflowName);
     if (!exportedFn) {
       throw new Error(
@@ -65347,12 +65494,12 @@ function parse4(str2) {
   uri.queryKey = queryKey(uri, uri["query"]);
   return uri;
 }
-function pathNames(obj, path37) {
-  const regx = /\/{2,9}/g, names = path37.replace(regx, "/").split("/");
-  if (path37.slice(0, 1) == "/" || path37.length === 0) {
+function pathNames(obj, path38) {
+  const regx = /\/{2,9}/g, names = path38.replace(regx, "/").split("/");
+  if (path38.slice(0, 1) == "/" || path38.length === 0) {
     names.splice(0, 1);
   }
-  if (path37.slice(-1) == "/") {
+  if (path38.slice(-1) == "/") {
     names.splice(names.length - 1, 1);
   }
   return names;
@@ -65970,7 +66117,7 @@ var protocol2 = Socket.protocol;
 // node_modules/socket.io-client/build/esm-debug/url.js
 var import_debug7 = __toESM(require_src(), 1);
 var debug7 = (0, import_debug7.default)("socket.io-client:url");
-function url(uri, path37 = "", loc) {
+function url(uri, path38 = "", loc) {
   let obj = uri;
   loc = loc || typeof location !== "undefined" && location;
   if (null == uri)
@@ -66004,7 +66151,7 @@ function url(uri, path37 = "", loc) {
   obj.path = obj.path || "/";
   const ipv62 = obj.host.indexOf(":") !== -1;
   const host = ipv62 ? "[" + obj.host + "]" : obj.host;
-  obj.id = obj.protocol + "://" + host + ":" + obj.port + path37;
+  obj.id = obj.protocol + "://" + host + ":" + obj.port + path38;
   obj.href = obj.protocol + "://" + host + (loc && loc.port === obj.port ? "" : ":" + obj.port);
   return obj;
 }
@@ -66656,9 +66803,9 @@ var Socket2 = class extends import_component_emitter5.Emitter {
    * @return a Promise that will be fulfilled when the server acknowledges the event
    */
   emitWithAck(ev, ...args) {
-    return new Promise((resolve26, reject2) => {
+    return new Promise((resolve27, reject2) => {
       const fn = (arg1, arg2) => {
-        return arg1 ? reject2(arg1) : resolve26(arg2);
+        return arg1 ? reject2(arg1) : resolve27(arg2);
       };
       fn.withError = true;
       args.push(fn);
@@ -67631,8 +67778,8 @@ function lookup(uri, opts) {
   const parsed = url(uri, opts.path || "/socket.io");
   const source = parsed.source;
   const id = parsed.id;
-  const path37 = parsed.path;
-  const sameNamespace = cache[id] && path37 in cache[id]["nsps"];
+  const path38 = parsed.path;
+  const sameNamespace = cache[id] && path38 in cache[id]["nsps"];
   const newConnection = opts.forceNew || opts["force new connection"] || false === opts.multiplex || sameNamespace;
   let io;
   if (newConnection) {
@@ -68176,8 +68323,8 @@ function getErrorMap() {
 
 // node_modules/zod/v3/helpers/parseUtil.js
 var makeIssue = (params) => {
-  const { data, path: path37, errorMaps, issueData } = params;
-  const fullPath = [...path37, ...issueData.path || []];
+  const { data, path: path38, errorMaps, issueData } = params;
+  const fullPath = [...path38, ...issueData.path || []];
   const fullIssue = {
     ...issueData,
     path: fullPath
@@ -68293,11 +68440,11 @@ var errorUtil;
 
 // node_modules/zod/v3/types.js
 var ParseInputLazyPath = class {
-  constructor(parent, value2, path37, key) {
+  constructor(parent, value2, path38, key) {
     this._cachedPath = [];
     this.parent = parent;
     this.data = value2;
-    this._path = path37;
+    this._path = path38;
     this._key = key;
   }
   get path() {
@@ -71934,10 +72081,10 @@ function assignProp(target, prop, value2) {
     configurable: true
   });
 }
-function getElementAtPath(obj, path37) {
-  if (!path37)
+function getElementAtPath(obj, path38) {
+  if (!path38)
     return obj;
-  return path37.reduce((acc, key) => acc?.[key], obj);
+  return path38.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject(promisesObj) {
   const keys2 = Object.keys(promisesObj);
@@ -72257,11 +72404,11 @@ function aborted(x, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues(path37, issues) {
+function prefixIssues(path38, issues) {
   return issues.map((iss) => {
     var _a;
     (_a = iss).path ?? (_a.path = []);
-    iss.path.unshift(path37);
+    iss.path.unshift(path38);
     return iss;
   });
 }
@@ -79770,7 +79917,7 @@ var Protocol = class {
           return;
         }
         const pollInterval = task2.pollInterval ?? this._options?.defaultTaskPollInterval ?? 1e3;
-        await new Promise((resolve26) => setTimeout(resolve26, pollInterval));
+        await new Promise((resolve27) => setTimeout(resolve27, pollInterval));
         options?.signal?.throwIfAborted();
       }
     } catch (error2) {
@@ -79787,7 +79934,7 @@ var Protocol = class {
    */
   request(request, resultSchema, options) {
     const { relatedRequestId, resumptionToken, onresumptiontoken, task, relatedTask } = options ?? {};
-    return new Promise((resolve26, reject2) => {
+    return new Promise((resolve27, reject2) => {
       const earlyReject = (error2) => {
         reject2(error2);
       };
@@ -79865,7 +80012,7 @@ var Protocol = class {
           if (!parseResult.success) {
             reject2(parseResult.error);
           } else {
-            resolve26(parseResult.data);
+            resolve27(parseResult.data);
           }
         } catch (error2) {
           reject2(error2);
@@ -80126,12 +80273,12 @@ var Protocol = class {
       }
     } catch {
     }
-    return new Promise((resolve26, reject2) => {
+    return new Promise((resolve27, reject2) => {
       if (signal.aborted) {
         reject2(new McpError(ErrorCode.InvalidRequest, "Request cancelled"));
         return;
       }
-      const timeoutId = setTimeout(resolve26, interval);
+      const timeoutId = setTimeout(resolve27, interval);
       signal.addEventListener("abort", () => {
         clearTimeout(timeoutId);
         reject2(new McpError(ErrorCode.InvalidRequest, "Request cancelled"));
@@ -81090,7 +81237,7 @@ var McpServer = class {
     let task = createTaskResult.task;
     const pollInterval = task.pollInterval ?? 5e3;
     while (task.status !== "completed" && task.status !== "failed" && task.status !== "cancelled") {
-      await new Promise((resolve26) => setTimeout(resolve26, pollInterval));
+      await new Promise((resolve27) => setTimeout(resolve27, pollInterval));
       const updatedTask = await extra.taskStore.getTask(taskId);
       if (!updatedTask) {
         throw new McpError(ErrorCode.InternalError, `Task ${taskId} not found during polling`);
@@ -81733,12 +81880,12 @@ var StdioServerTransport = class {
     this.onclose?.();
   }
   send(message) {
-    return new Promise((resolve26) => {
+    return new Promise((resolve27) => {
       const json2 = serializeMessage(message);
       if (this._stdout.write(json2)) {
-        resolve26();
+        resolve27();
       } else {
-        this._stdout.once("drain", resolve26);
+        this._stdout.once("drain", resolve27);
       }
     });
   }
@@ -81952,17 +82099,17 @@ var EditorConnection = class {
       return { requestId: "", success: false, error: "Not connected" };
     }
     const requestId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-    return new Promise((resolve26) => {
+    return new Promise((resolve27) => {
       const handler = (data) => {
         if (data.requestId === requestId) {
           clearTimeout(timeout);
           this.socket.off("fw:ack", handler);
-          resolve26(data);
+          resolve27(data);
         }
       };
       const timeout = setTimeout(() => {
         this.socket.off("fw:ack", handler);
-        resolve26({ requestId, success: false, error: "Timeout" });
+        resolve27({ requestId, success: false, error: "Timeout" });
       }, this.ackTimeout);
       this.socket.on("fw:ack", handler);
       this.socket.emit("integration:command", { requestId, action, params });
@@ -81979,17 +82126,17 @@ var EditorConnection = class {
       return { requestId: "", success: false, error: "Not connected" };
     }
     const requestId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-    return new Promise((resolve26) => {
+    return new Promise((resolve27) => {
       const handler = (data) => {
         if (data.requestId === requestId) {
           clearTimeout(timeout);
           this.socket.off("fw:ack", handler);
-          resolve26(data);
+          resolve27(data);
         }
       };
       const timeout = setTimeout(() => {
         this.socket.off("fw:ack", handler);
-        resolve26({ requestId, success: false, error: "Timeout" });
+        resolve27({ requestId, success: false, error: "Timeout" });
       }, this.ackTimeout);
       this.socket.on("fw:ack", handler);
       this.socket.emit("integration:batch", { requestId, commands });
@@ -82017,11 +82164,11 @@ function defaultRegistrationDeps() {
         return { stdout: "", exitCode: 1 };
       }
     },
-    prompt: (question) => new Promise((resolve26) => {
+    prompt: (question) => new Promise((resolve27) => {
       const rl = readline8.createInterface({ input: process.stdin, output: process.stderr });
       rl.question(question, (answer) => {
         rl.close();
-        resolve26(answer.trim().toLowerCase());
+        resolve27(answer.trim().toLowerCase());
       });
     }),
     log: (msg) => process.stderr.write(msg + "\n"),
@@ -82305,7 +82452,7 @@ function registerEditorTools(mcp, connection, buffer) {
   );
   mcp.tool(
     "fw_execute_workflow",
-    "Run the current workflow with optional parameters and return the result.",
+    "Run the current workflow with optional parameters and return the result. Includes per-node execution trace by default (STATUS_CHANGED, VARIABLE_SET events) \u2014 use includeTrace: false to disable.",
     {
       filePath: external_exports.string().optional().describe(
         "Path to workflow file. When provided, compiles and executes directly (no editor needed)"
@@ -82507,7 +82654,7 @@ ${parseResult.errors.join("\n")}`
   );
   mcp.tool(
     "fw_compile",
-    "Compile a workflow to executable code. Use target=inngest for per-node step.run() durability.",
+    "Compile a workflow to executable code. Only regenerates code inside @flow-weaver-runtime and @flow-weaver-body marker sections \u2014 user code outside markers is preserved. Set production: true to strip debug instrumentation. Use target=inngest for per-node step.run() durability.",
     {
       filePath: external_exports.string().describe("Path to the workflow file"),
       write: external_exports.boolean().optional().describe("Whether to write the output file (default: true)"),
@@ -82560,8 +82707,8 @@ ${parseResult.errors.join("\n")}`);
           });
           const outputFile = filePath.replace(/\.ts$/, ".inngest.ts");
           if (args.write !== false) {
-            const fs36 = await import("fs");
-            fs36.writeFileSync(outputFile, code, "utf8");
+            const fs37 = await import("fs");
+            fs37.writeFileSync(outputFile, code, "utf8");
           }
           return makeToolResult({
             target: "inngest",
@@ -83991,8 +84138,8 @@ var OpenAPIGenerator = class {
     doc.paths["/health"] = this.generateHealthEndpoint();
     doc.paths["/workflows"] = this.generateListEndpoint();
     for (const endpoint of endpoints) {
-      const path37 = options.basePath ? `${options.basePath}${endpoint.path}` : endpoint.path;
-      doc.paths[path37] = this.generateWorkflowEndpoint(endpoint);
+      const path38 = options.basePath ? `${options.basePath}${endpoint.path}` : endpoint.path;
+      doc.paths[path38] = this.generateWorkflowEndpoint(endpoint);
     }
     return doc;
   }
@@ -89599,6 +89746,287 @@ function registerDiagramTools(mcp) {
   );
 }
 
+// src/docs/index.ts
+import * as fs27 from "fs";
+import * as path30 from "path";
+import { fileURLToPath as fileURLToPath4 } from "url";
+function getDocsDir() {
+  const thisFile = fileURLToPath4(import.meta.url);
+  const packageRoot = path30.resolve(path30.dirname(thisFile), "..", "..");
+  return path30.join(packageRoot, "docs", "reference");
+}
+function parseFrontmatter(raw) {
+  const fmMatch = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!fmMatch) {
+    return {
+      frontmatter: { name: "", description: "", keywords: [] },
+      body: raw
+    };
+  }
+  const fmBlock = fmMatch[1];
+  const body = fmMatch[2];
+  let name = "";
+  let description = "";
+  let keywords = [];
+  for (const line of fmBlock.split("\n")) {
+    const nameMatch = line.match(/^name:\s*(.+)$/);
+    if (nameMatch) {
+      name = nameMatch[1].trim();
+      continue;
+    }
+    const descMatch = line.match(/^description:\s*(.+)$/);
+    if (descMatch) {
+      description = descMatch[1].trim();
+      continue;
+    }
+    const kwMatch = line.match(/^keywords:\s*\[(.+)\]$/);
+    if (kwMatch) {
+      keywords = kwMatch[1].split(",").map((k) => k.trim().replace(/^['"]|['"]$/g, ""));
+      continue;
+    }
+  }
+  return { frontmatter: { name, description, keywords }, body };
+}
+function splitSections(body) {
+  const lines = body.split("\n");
+  const sections = [];
+  let currentHeading = "";
+  let currentLevel = 0;
+  let currentLines = [];
+  function flush() {
+    if (currentHeading || currentLines.length > 0) {
+      const content = currentLines.join("\n").trim();
+      const codeBlocks = [];
+      const codeRe = /```[\s\S]*?```/g;
+      let m;
+      while ((m = codeRe.exec(content)) !== null) {
+        codeBlocks.push(m[0]);
+      }
+      sections.push({
+        heading: currentHeading,
+        level: currentLevel,
+        content,
+        codeBlocks
+      });
+    }
+  }
+  for (const line of lines) {
+    const headingMatch = line.match(/^(#{1,6})\s+(.+)$/);
+    if (headingMatch) {
+      flush();
+      currentLevel = headingMatch[1].length;
+      currentHeading = headingMatch[2];
+      currentLines = [];
+    } else {
+      currentLines.push(line);
+    }
+  }
+  flush();
+  return sections;
+}
+function listTopics() {
+  const docsDir = getDocsDir();
+  if (!fs27.existsSync(docsDir)) return [];
+  const files = fs27.readdirSync(docsDir).filter((f) => f.endsWith(".md")).sort();
+  return files.map((file) => {
+    const raw = fs27.readFileSync(path30.join(docsDir, file), "utf-8");
+    const { frontmatter } = parseFrontmatter(raw);
+    return {
+      slug: file.replace(/\.md$/, ""),
+      name: frontmatter.name,
+      description: frontmatter.description,
+      keywords: frontmatter.keywords
+    };
+  });
+}
+function readTopic(slug, compact2) {
+  const docsDir = getDocsDir();
+  const filePath = path30.join(docsDir, `${slug}.md`);
+  if (!fs27.existsSync(filePath)) return null;
+  const raw = fs27.readFileSync(filePath, "utf-8");
+  const { frontmatter, body } = parseFrontmatter(raw);
+  const content = compact2 ? buildCompactContent(frontmatter, body) : body.trim();
+  return {
+    slug,
+    name: frontmatter.name,
+    description: frontmatter.description,
+    keywords: frontmatter.keywords,
+    content
+  };
+}
+function readTopicStructured(slug) {
+  const docsDir = getDocsDir();
+  const filePath = path30.join(docsDir, `${slug}.md`);
+  if (!fs27.existsSync(filePath)) return null;
+  const raw = fs27.readFileSync(filePath, "utf-8");
+  const { frontmatter, body } = parseFrontmatter(raw);
+  const sections = splitSections(body);
+  return {
+    slug,
+    name: frontmatter.name,
+    description: frontmatter.description,
+    keywords: frontmatter.keywords,
+    sections
+  };
+}
+function searchDocs(query) {
+  const topics = listTopics();
+  const docsDir = getDocsDir();
+  const queryLower = query.toLowerCase();
+  const queryTerms = queryLower.split(/\s+/).filter(Boolean);
+  const results = [];
+  for (const topic of topics) {
+    const keywordMatch = topic.keywords.some(
+      (kw) => queryTerms.some((term) => kw.toLowerCase().includes(term))
+    );
+    const filePath = path30.join(docsDir, `${topic.slug}.md`);
+    const raw = fs27.readFileSync(filePath, "utf-8");
+    const { body } = parseFrontmatter(raw);
+    const sections = splitSections(body);
+    for (const section of sections) {
+      const sectionLower = section.content.toLowerCase();
+      const headingLower = section.heading.toLowerCase();
+      let relevance = 0;
+      if (sectionLower.includes(queryLower)) {
+        relevance += 10;
+      }
+      for (const term of queryTerms) {
+        if (headingLower.includes(term)) relevance += 5;
+        if (sectionLower.includes(term)) relevance += 2;
+      }
+      if (keywordMatch) relevance += 3;
+      if (relevance > 0) {
+        const lines = section.content.split("\n");
+        const matchingLines = [];
+        for (const line of lines) {
+          if (queryTerms.some((term) => line.toLowerCase().includes(term))) {
+            matchingLines.push(line.trim());
+            if (matchingLines.length >= 3) break;
+          }
+        }
+        results.push({
+          topic: topic.name,
+          slug: topic.slug,
+          section: section.heading,
+          heading: section.heading,
+          excerpt: matchingLines.join("\n") || section.content.slice(0, 200),
+          relevance
+        });
+      }
+    }
+  }
+  results.sort((a, b) => b.relevance - a.relevance);
+  return results;
+}
+function buildCompactContent(frontmatter, body) {
+  const lines = body.split("\n");
+  const output = [];
+  output.push(`# ${frontmatter.name}`);
+  output.push(frontmatter.description);
+  output.push("");
+  let inCodeBlock = false;
+  let inTable = false;
+  for (const line of lines) {
+    if (line.trimStart().startsWith("```")) {
+      inCodeBlock = !inCodeBlock;
+      output.push(line);
+      continue;
+    }
+    if (inCodeBlock) {
+      output.push(line);
+      continue;
+    }
+    if (line.match(/^#{1,6}\s/)) {
+      output.push("");
+      output.push(line);
+      continue;
+    }
+    if (line.trim().startsWith("|")) {
+      inTable = true;
+      output.push(line);
+      continue;
+    }
+    if (inTable && !line.trim().startsWith("|")) {
+      inTable = false;
+    }
+    if (line.trim().startsWith("- ") || line.trim().startsWith("* ") || line.trim().startsWith("> ")) {
+      output.push(line);
+      continue;
+    }
+  }
+  return output.join("\n").replace(/\n{3,}/g, "\n\n").trim();
+}
+
+// src/mcp/tools-docs.ts
+function registerDocsTools(mcp) {
+  mcp.tool(
+    "fw_docs",
+    'Browse Flow Weaver documentation and reference guides. Use action="list" to see topics, action="read" to read a topic, action="search" to search across all docs.',
+    {
+      action: external_exports.enum(["list", "read", "search"]).describe("What to do: list topics, read a topic, or search"),
+      topic: external_exports.string().optional().describe('Topic slug to read (for action="read")'),
+      query: external_exports.string().optional().describe('Search query (for action="search")'),
+      compact: external_exports.boolean().optional().describe("Return compact LLM-friendly version (default: false)")
+    },
+    async (args) => {
+      try {
+        switch (args.action) {
+          case "list": {
+            const topics = listTopics();
+            return makeToolResult({
+              topics: topics.map((t) => ({
+                slug: t.slug,
+                name: t.name,
+                description: t.description,
+                keywords: t.keywords
+              }))
+            });
+          }
+          case "read": {
+            if (!args.topic) {
+              return makeErrorResult("MISSING_PARAM", 'The "topic" parameter is required for action="read"');
+            }
+            const doc = readTopic(args.topic, args.compact ?? false);
+            if (!doc) {
+              const available = listTopics().map((t) => t.slug);
+              return makeErrorResult(
+                "TOPIC_NOT_FOUND",
+                `Unknown topic "${args.topic}". Available topics: ${available.join(", ")}`
+              );
+            }
+            return makeToolResult({
+              name: doc.name,
+              description: doc.description,
+              content: doc.content
+            });
+          }
+          case "search": {
+            if (!args.query) {
+              return makeErrorResult("MISSING_PARAM", 'The "query" parameter is required for action="search"');
+            }
+            const results = searchDocs(args.query);
+            return makeToolResult({
+              query: args.query,
+              results: results.slice(0, 20).map((r) => ({
+                topic: r.topic,
+                slug: r.slug,
+                heading: r.heading,
+                excerpt: r.excerpt,
+                relevance: r.relevance
+              }))
+            });
+          }
+        }
+      } catch (err) {
+        return makeErrorResult(
+          "DOCS_ERROR",
+          `fw_docs failed: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
+  );
+}
+
 // src/mcp/resources.ts
 function registerResources(mcp, connection, buffer) {
   mcp.resource(
@@ -89701,6 +90129,7 @@ async function startMcpServer(options) {
   registerExportTools(mcp);
   registerMarketplaceTools(mcp);
   registerDiagramTools(mcp);
+  registerDocsTools(mcp);
   registerResources(mcp, connection, buffer);
   if (!options._testDeps && options.stdio) {
     const transport = new StdioServerTransport();
@@ -89732,20 +90161,20 @@ async function sendCommand(serverUrl, action, params) {
     transports: ["websocket", "polling"]
   });
   try {
-    await new Promise((resolve26, reject2) => {
-      socket.on("connect", () => resolve26());
+    await new Promise((resolve27, reject2) => {
+      socket.on("connect", () => resolve27());
       socket.on("connect_error", (err) => reject2(err));
       setTimeout(() => reject2(new Error("Connection timeout")), ACK_TIMEOUT);
     });
     const requestId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-    const result = await new Promise((resolve26) => {
+    const result = await new Promise((resolve27) => {
       const timeout = setTimeout(() => {
-        resolve26({ requestId, success: false, error: "Timeout" });
+        resolve27({ requestId, success: false, error: "Timeout" });
       }, ACK_TIMEOUT);
       socket.on("fw:ack", (data) => {
         if (data.requestId === requestId) {
           clearTimeout(timeout);
-          resolve26(data);
+          resolve27(data);
         }
       });
       socket.emit("integration:command", { requestId, action, params });
@@ -89775,20 +90204,20 @@ async function sendBatch(serverUrl, commands) {
     transports: ["websocket", "polling"]
   });
   try {
-    await new Promise((resolve26, reject2) => {
-      socket.on("connect", () => resolve26());
+    await new Promise((resolve27, reject2) => {
+      socket.on("connect", () => resolve27());
       socket.on("connect_error", (err) => reject2(err));
       setTimeout(() => reject2(new Error("Connection timeout")), ACK_TIMEOUT);
     });
     const requestId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-    const result = await new Promise((resolve26) => {
+    const result = await new Promise((resolve27) => {
       const timeout = setTimeout(() => {
-        resolve26({ requestId, success: false, error: "Timeout" });
+        resolve27({ requestId, success: false, error: "Timeout" });
       }, ACK_TIMEOUT);
       socket.on("fw:ack", (data) => {
         if (data.requestId === requestId) {
           clearTimeout(timeout);
-          resolve26(data);
+          resolve27(data);
         }
       });
       socket.emit("integration:batch", { requestId, commands });
@@ -89842,7 +90271,7 @@ async function uiBatch(json2, options) {
 }
 
 // src/cli/commands/grammar.ts
-import * as fs27 from "fs";
+import * as fs28 from "fs";
 async function grammarCommand(options = {}) {
   const { format = "html", output } = options;
   try {
@@ -89861,7 +90290,7 @@ async function grammarCommand(options = {}) {
       content = generateGrammarDiagrams();
     }
     if (output) {
-      fs27.writeFileSync(output, content, "utf-8");
+      fs28.writeFileSync(output, content, "utf-8");
       logger.success(`Grammar written to ${output}`);
     } else {
       process.stdout.write(content);
@@ -89873,11 +90302,11 @@ async function grammarCommand(options = {}) {
 }
 
 // src/cli/commands/run.ts
-import * as path30 from "path";
-import * as fs28 from "fs";
+import * as path31 from "path";
+import * as fs29 from "fs";
 async function runCommand(input, options) {
-  const filePath = path30.resolve(input);
-  if (!fs28.existsSync(filePath)) {
+  const filePath = path31.resolve(input);
+  if (!fs29.existsSync(filePath)) {
     throw new Error(`File not found: ${filePath}`);
   }
   let params = {};
@@ -89888,12 +90317,12 @@ async function runCommand(input, options) {
       throw new Error(`Invalid JSON in --params: ${options.params}`);
     }
   } else if (options.paramsFile) {
-    const paramsFilePath = path30.resolve(options.paramsFile);
-    if (!fs28.existsSync(paramsFilePath)) {
+    const paramsFilePath = path31.resolve(options.paramsFile);
+    if (!fs29.existsSync(paramsFilePath)) {
       throw new Error(`Params file not found: ${paramsFilePath}`);
     }
     try {
-      const content = fs28.readFileSync(paramsFilePath, "utf8");
+      const content = fs29.readFileSync(paramsFilePath, "utf8");
       params = JSON.parse(content);
     } catch {
       throw new Error(`Failed to parse params file: ${options.paramsFile}`);
@@ -89907,12 +90336,12 @@ async function runCommand(input, options) {
       throw new Error(`Invalid JSON in --mocks: ${options.mocks}`);
     }
   } else if (options.mocksFile) {
-    const mocksFilePath = path30.resolve(options.mocksFile);
-    if (!fs28.existsSync(mocksFilePath)) {
+    const mocksFilePath = path31.resolve(options.mocksFile);
+    if (!fs29.existsSync(mocksFilePath)) {
       throw new Error(`Mocks file not found: ${mocksFilePath}`);
     }
     try {
-      const content = fs28.readFileSync(mocksFilePath, "utf8");
+      const content = fs29.readFileSync(mocksFilePath, "utf8");
       mocks = JSON.parse(content);
     } catch {
       throw new Error(`Failed to parse mocks file: ${options.mocksFile}`);
@@ -90013,12 +90442,12 @@ async function runCommand(input, options) {
 }
 
 // src/cli/commands/serve.ts
-import * as path31 from "path";
-import * as fs30 from "fs";
+import * as path32 from "path";
+import * as fs31 from "fs";
 
 // src/server/workflow-registry.ts
 init_esm5();
-import * as fs29 from "fs";
+import * as fs30 from "fs";
 var WorkflowRegistry = class {
   constructor(workflowDir, options = {}) {
     this.workflowDir = workflowDir;
@@ -90053,7 +90482,7 @@ var WorkflowRegistry = class {
     this.endpoints.clear();
     for (const file of files) {
       try {
-        const content = fs29.readFileSync(file, "utf8");
+        const content = fs30.readFileSync(file, "utf8");
         if (!content.includes("@flowWeaver")) {
           continue;
         }
@@ -90445,11 +90874,11 @@ var WebhookServer = class {
 
 // src/cli/commands/serve.ts
 async function serveCommand(dir, options) {
-  const workflowDir = path31.resolve(dir || ".");
-  if (!fs30.existsSync(workflowDir)) {
+  const workflowDir = path32.resolve(dir || ".");
+  if (!fs31.existsSync(workflowDir)) {
     throw new Error(`Directory not found: ${workflowDir}`);
   }
-  if (!fs30.statSync(workflowDir).isDirectory()) {
+  if (!fs31.statSync(workflowDir).isDirectory()) {
     throw new Error(`Not a directory: ${workflowDir}`);
   }
   const port = options.port ?? 3e3;
@@ -90492,10 +90921,10 @@ async function serveCommand(dir, options) {
 }
 
 // src/export/index.ts
-import * as path32 from "path";
-import * as fs31 from "fs";
+import * as path33 from "path";
+import * as fs32 from "fs";
 import * as os3 from "os";
-import { fileURLToPath as fileURLToPath4 } from "url";
+import { fileURLToPath as fileURLToPath5 } from "url";
 
 // src/export/templates.ts
 var LAMBDA_TEMPLATE = `{{GENERATED_HEADER}}
@@ -90667,13 +91096,13 @@ Outputs:
 `;
 
 // src/export/index.ts
-var __filename = fileURLToPath4(import.meta.url);
-var __dirname2 = path32.dirname(__filename);
+var __filename = fileURLToPath5(import.meta.url);
+var __dirname2 = path33.dirname(__filename);
 async function exportMultiWorkflow(options) {
-  const inputPath = path32.resolve(options.input);
-  const outputDir = path32.resolve(options.output);
+  const inputPath = path33.resolve(options.input);
+  const outputDir = path33.resolve(options.output);
   const isDryRun = options.dryRun ?? false;
-  if (!fs31.existsSync(inputPath)) {
+  if (!fs32.existsSync(inputPath)) {
     throw new Error(`Input file not found: ${inputPath}`);
   }
   const parser3 = new AnnotationParser();
@@ -90691,22 +91120,22 @@ async function exportMultiWorkflow(options) {
       throw new Error(`None of the requested workflows found. Available: ${available}`);
     }
   }
-  const workDir = isDryRun ? path32.join(os3.tmpdir(), `fw-export-multi-dryrun-${Date.now()}`) : outputDir;
-  fs31.mkdirSync(workDir, { recursive: true });
-  fs31.mkdirSync(path32.join(workDir, "workflows"), { recursive: true });
-  fs31.mkdirSync(path32.join(workDir, "runtime"), { recursive: true });
+  const workDir = isDryRun ? path33.join(os3.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 });
   const compiledWorkflows = [];
   try {
     for (const workflow of selectedWorkflows) {
-      const workflowOutputPath = path32.join(workDir, "workflows", `${workflow.name}.ts`);
-      fs31.copyFileSync(inputPath, workflowOutputPath);
+      const workflowOutputPath = path33.join(workDir, "workflows", `${workflow.name}.ts`);
+      fs32.copyFileSync(inputPath, workflowOutputPath);
       await compileWorkflow(workflowOutputPath, {
         write: true,
         inPlace: true,
         parse: { workflowName: workflow.functionName },
         generate: { production: options.production ?? true }
       });
-      const compiledCode = fs31.readFileSync(workflowOutputPath, "utf8");
+      const compiledCode = fs32.readFileSync(workflowOutputPath, "utf8");
       compiledWorkflows.push({
         name: workflow.name,
         functionName: workflow.functionName,
@@ -90714,24 +91143,24 @@ async function exportMultiWorkflow(options) {
         code: compiledCode
       });
     }
-    const runtimeDir = path32.join(workDir, "runtime");
-    const libraryRuntimeDir = path32.resolve(__dirname2, "../runtime");
+    const runtimeDir = path33.join(workDir, "runtime");
+    const libraryRuntimeDir = path33.resolve(__dirname2, "../runtime");
     const runtimeFiles = ["function-registry.ts", "parameter-resolver.ts", "builtin-functions.ts"];
     for (const file of runtimeFiles) {
-      const srcPath = path32.join(libraryRuntimeDir, file);
-      const destPath = path32.join(runtimeDir, file);
-      if (fs31.existsSync(srcPath)) {
-        fs31.copyFileSync(srcPath, destPath);
+      const srcPath = path33.join(libraryRuntimeDir, file);
+      const destPath = path33.join(runtimeDir, file);
+      if (fs32.existsSync(srcPath)) {
+        fs32.copyFileSync(srcPath, destPath);
       }
     }
     const result = generateMultiHandler(options.target, compiledWorkflows, workDir, options);
     if (!isDryRun) {
       for (const file of result.files) {
-        const dirPath = path32.dirname(file.path);
-        if (!fs31.existsSync(dirPath)) {
-          fs31.mkdirSync(dirPath, { recursive: true });
+        const dirPath = path33.dirname(file.path);
+        if (!fs32.existsSync(dirPath)) {
+          fs32.mkdirSync(dirPath, { recursive: true });
         }
-        fs31.writeFileSync(file.path, file.content);
+        fs32.writeFileSync(file.path, file.content);
       }
     }
     return {
@@ -90744,7 +91173,7 @@ async function exportMultiWorkflow(options) {
   } finally {
     if (isDryRun) {
       try {
-        fs31.rmSync(workDir, { recursive: true, force: true });
+        fs32.rmSync(workDir, { recursive: true, force: true });
       } catch {
       }
     }
@@ -90752,28 +91181,28 @@ async function exportMultiWorkflow(options) {
 }
 function generateMultiHandler(target, workflows, outputDir, options) {
   const files = [];
-  const serviceName = path32.basename(options.input, path32.extname(options.input)) + "-service";
+  const serviceName = path33.basename(options.input, path33.extname(options.input)) + "-service";
   const workflowImports = workflows.map((w) => `import { ${w.functionName} } from './workflows/${w.name}.js';`).join("\n");
   const workflowEntries = workflows.map((w) => `  '${w.name}': ${w.functionName},`).join("\n");
   const openApiSpec = generateMultiWorkflowOpenAPI(workflows, serviceName);
   switch (target) {
     case "lambda":
       files.push({
-        path: path32.join(outputDir, "handler.ts"),
+        path: path33.join(outputDir, "handler.ts"),
         content: generateLambdaMultiHandler(workflowImports, workflowEntries, serviceName)
       });
       files.push({
-        path: path32.join(outputDir, "openapi.ts"),
+        path: path33.join(outputDir, "openapi.ts"),
         content: `// Generated OpenAPI specification
 export const openApiSpec = ${JSON.stringify(openApiSpec, null, 2)};
 `
       });
       files.push({
-        path: path32.join(outputDir, "template.yaml"),
+        path: path33.join(outputDir, "template.yaml"),
         content: generateLambdaSAMMultiTemplate(serviceName, workflows.length)
       });
       files.push({
-        path: path32.join(outputDir, "package.json"),
+        path: path33.join(outputDir, "package.json"),
         content: JSON.stringify(
           {
             name: `fw-${serviceName}`,
@@ -90794,7 +91223,7 @@ export const openApiSpec = ${JSON.stringify(openApiSpec, null, 2)};
         )
       });
       files.push({
-        path: path32.join(outputDir, "tsconfig.json"),
+        path: path33.join(outputDir, "tsconfig.json"),
         content: JSON.stringify(
           {
             compilerOptions: {
@@ -90815,17 +91244,17 @@ export const openApiSpec = ${JSON.stringify(openApiSpec, null, 2)};
       break;
     case "vercel":
       files.push({
-        path: path32.join(outputDir, "api", "[workflow].ts"),
+        path: path33.join(outputDir, "api", "[workflow].ts"),
         content: generateVercelMultiHandler(workflowImports, workflowEntries, serviceName)
       });
       files.push({
-        path: path32.join(outputDir, "openapi.ts"),
+        path: path33.join(outputDir, "openapi.ts"),
         content: `// Generated OpenAPI specification
 export const openApiSpec = ${JSON.stringify(openApiSpec, null, 2)};
 `
       });
       files.push({
-        path: path32.join(outputDir, "vercel.json"),
+        path: path33.join(outputDir, "vercel.json"),
         content: JSON.stringify(
           {
             functions: {
@@ -90842,17 +91271,17 @@ export const openApiSpec = ${JSON.stringify(openApiSpec, null, 2)};
       break;
     case "cloudflare":
       files.push({
-        path: path32.join(outputDir, "index.ts"),
+        path: path33.join(outputDir, "index.ts"),
         content: generateCloudflareMultiHandler(workflowImports, workflowEntries, serviceName)
       });
       files.push({
-        path: path32.join(outputDir, "openapi.ts"),
+        path: path33.join(outputDir, "openapi.ts"),
         content: `// Generated OpenAPI specification
 export const openApiSpec = ${JSON.stringify(openApiSpec, null, 2)};
 `
       });
       files.push({
-        path: path32.join(outputDir, "wrangler.toml"),
+        path: path33.join(outputDir, "wrangler.toml"),
         content: `name = "${serviceName}"
 main = "dist/index.js"
 compatibility_date = "2024-01-01"
@@ -90862,7 +91291,7 @@ command = "npm run build"
 `
       });
       files.push({
-        path: path32.join(outputDir, "package.json"),
+        path: path33.join(outputDir, "package.json"),
         content: JSON.stringify(
           {
             name: `fw-${serviceName}`,
@@ -90884,7 +91313,7 @@ command = "npm run build"
         )
       });
       files.push({
-        path: path32.join(outputDir, "tsconfig.json"),
+        path: path33.join(outputDir, "tsconfig.json"),
         content: JSON.stringify(
           {
             compilerOptions: {
@@ -90905,17 +91334,17 @@ command = "npm run build"
       break;
     case "inngest":
       files.push({
-        path: path32.join(outputDir, "handler.ts"),
+        path: path33.join(outputDir, "handler.ts"),
         content: generateInngestMultiHandler(workflowImports, workflowEntries, serviceName, workflows)
       });
       files.push({
-        path: path32.join(outputDir, "openapi.ts"),
+        path: path33.join(outputDir, "openapi.ts"),
         content: `// Generated OpenAPI specification
 export const openApiSpec = ${JSON.stringify(openApiSpec, null, 2)};
 `
       });
       files.push({
-        path: path32.join(outputDir, "package.json"),
+        path: path33.join(outputDir, "package.json"),
         content: JSON.stringify(
           {
             name: `fw-${serviceName}`,
@@ -90941,7 +91370,7 @@ export const openApiSpec = ${JSON.stringify(openApiSpec, null, 2)};
         )
       });
       files.push({
-        path: path32.join(outputDir, "tsconfig.json"),
+        path: path33.join(outputDir, "tsconfig.json"),
         content: JSON.stringify(
           {
             compilerOptions: {
@@ -91397,10 +91826,10 @@ async function exportWorkflow(options) {
   if (options.multi) {
     return exportMultiWorkflow(options);
   }
-  const inputPath = path32.resolve(options.input);
-  const outputDir = path32.resolve(options.output);
+  const inputPath = path33.resolve(options.input);
+  const outputDir = path33.resolve(options.output);
   const isDryRun = options.dryRun ?? false;
-  if (!fs31.existsSync(inputPath)) {
+  if (!fs32.existsSync(inputPath)) {
     throw new Error(`Input file not found: ${inputPath}`);
   }
   const parser3 = new AnnotationParser();
@@ -91415,8 +91844,8 @@ 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 ? path32.join(os3.tmpdir(), `fw-export-dryrun-${Date.now()}`) : outputDir;
-  fs31.mkdirSync(workDir, { recursive: true });
+  const workDir = isDryRun ? path33.join(os3.tmpdir(), `fw-export-dryrun-${Date.now()}`) : outputDir;
+  fs32.mkdirSync(workDir, { recursive: true });
   let compiledContent;
   let compiledPath;
   try {
@@ -91426,11 +91855,11 @@ async function exportWorkflow(options) {
       workDir,
       options.production
     );
-    compiledContent = fs31.readFileSync(compiledPath, "utf8");
+    compiledContent = fs32.readFileSync(compiledPath, "utf8");
   } finally {
     if (isDryRun) {
       try {
-        fs31.rmSync(workDir, { recursive: true, force: true });
+        fs32.rmSync(workDir, { recursive: true, force: true });
       } catch {
       }
     }
@@ -91445,8 +91874,8 @@ async function exportWorkflow(options) {
     handler = generateHandler(options.target, compiledPath, workflow.functionName);
   }
   const handlerFileName = getHandlerFileName(options.target, workflow.name);
-  const handlerPath = path32.join(outputDir, handlerFileName);
-  const workflowOutputPath = path32.join(outputDir, "workflow.ts");
+  const handlerPath = path33.join(outputDir, handlerFileName);
+  const workflowOutputPath = path33.join(outputDir, "workflow.ts");
   const configFiles = generateConfigFiles(
     options.target,
     workflow.name,
@@ -91454,16 +91883,16 @@ async function exportWorkflow(options) {
     workflow.description
   );
   if (!isDryRun) {
-    fs31.mkdirSync(outputDir, { recursive: true });
-    const handlerDir = path32.dirname(handlerPath);
-    if (!fs31.existsSync(handlerDir)) {
-      fs31.mkdirSync(handlerDir, { recursive: true });
+    fs32.mkdirSync(outputDir, { recursive: true });
+    const handlerDir = path33.dirname(handlerPath);
+    if (!fs32.existsSync(handlerDir)) {
+      fs32.mkdirSync(handlerDir, { recursive: true });
     }
-    fs31.writeFileSync(handlerPath, handler);
+    fs32.writeFileSync(handlerPath, handler);
     for (const file of configFiles) {
-      fs31.writeFileSync(file.path, file.content);
+      fs32.writeFileSync(file.path, file.content);
     }
-    fs31.writeFileSync(workflowOutputPath, compiledContent);
+    fs32.writeFileSync(workflowOutputPath, compiledContent);
   }
   const files = [
     { path: handlerPath, content: handler },
@@ -91478,8 +91907,8 @@ async function exportWorkflow(options) {
   };
 }
 async function compileToOutput(inputPath, functionName, outputDir, production) {
-  const outputPath = path32.join(outputDir, "workflow.ts");
-  fs31.copyFileSync(inputPath, outputPath);
+  const outputPath = path33.join(outputDir, "workflow.ts");
+  fs32.copyFileSync(inputPath, outputPath);
   await compileWorkflow(outputPath, {
     write: true,
     inPlace: true,
@@ -91490,7 +91919,7 @@ async function compileToOutput(inputPath, functionName, outputDir, production) {
 }
 function generateHandler(target, workflowPath, functionName) {
   const template = getTemplate(target);
-  const relativePath = target === "vercel" ? `../${path32.basename(workflowPath).replace(".ts", ".js")}` : `./${path32.basename(workflowPath).replace(".ts", ".js")}`;
+  const relativePath = target === "vercel" ? `../${path33.basename(workflowPath).replace(".ts", ".js")}` : `./${path33.basename(workflowPath).replace(".ts", ".js")}`;
   return template.replace("{{GENERATED_HEADER}}", getGeneratedBranding().header(`export --target ${target}`)).replace("{{WORKFLOW_IMPORT}}", `import { ${functionName} } from '${relativePath}';`).replace(/\{\{FUNCTION_NAME\}\}/g, functionName).replace("{{MAX_DURATION}}", "60");
 }
 function getTemplate(target) {
@@ -91522,14 +91951,14 @@ function generateConfigFiles(target, workflowName, outputDir, description) {
   switch (target) {
     case "lambda":
       files.push({
-        path: path32.join(outputDir, "template.yaml"),
+        path: path33.join(outputDir, "template.yaml"),
         content: SAM_TEMPLATE2.replace(/\{\{WORKFLOW_NAME\}\}/g, workflowName).replace(
           "{{WORKFLOW_DESCRIPTION}}",
           description || `Flow Weaver workflow: ${workflowName}`
         ).replace(/\{\{WORKFLOW_PATH\}\}/g, workflowName)
       });
       files.push({
-        path: path32.join(outputDir, "package.json"),
+        path: path33.join(outputDir, "package.json"),
         content: JSON.stringify(
           {
             name: `fw-${workflowName}`,
@@ -91550,7 +91979,7 @@ function generateConfigFiles(target, workflowName, outputDir, description) {
         )
       });
       files.push({
-        path: path32.join(outputDir, "tsconfig.json"),
+        path: path33.join(outputDir, "tsconfig.json"),
         content: JSON.stringify(
           {
             compilerOptions: {
@@ -91571,7 +92000,7 @@ function generateConfigFiles(target, workflowName, outputDir, description) {
       break;
     case "vercel":
       files.push({
-        path: path32.join(outputDir, "vercel.json"),
+        path: path33.join(outputDir, "vercel.json"),
         content: JSON.stringify(
           {
             functions: {
@@ -91588,7 +92017,7 @@ function generateConfigFiles(target, workflowName, outputDir, description) {
       break;
     case "cloudflare":
       files.push({
-        path: path32.join(outputDir, "wrangler.toml"),
+        path: path33.join(outputDir, "wrangler.toml"),
         content: `name = "${workflowName}"
 main = "dist/index.js"
 compatibility_date = "2024-01-01"
@@ -91598,7 +92027,7 @@ command = "npm run build"
 `
       });
       files.push({
-        path: path32.join(outputDir, "package.json"),
+        path: path33.join(outputDir, "package.json"),
         content: JSON.stringify(
           {
             name: `fw-${workflowName}`,
@@ -91620,7 +92049,7 @@ command = "npm run build"
         )
       });
       files.push({
-        path: path32.join(outputDir, "tsconfig.json"),
+        path: path33.join(outputDir, "tsconfig.json"),
         content: JSON.stringify(
           {
             compilerOptions: {
@@ -91641,7 +92070,7 @@ command = "npm run build"
       break;
     case "inngest":
       files.push({
-        path: path32.join(outputDir, "package.json"),
+        path: path33.join(outputDir, "package.json"),
         content: JSON.stringify(
           {
             name: `fw-${workflowName}`,
@@ -91665,7 +92094,7 @@ command = "npm run build"
         )
       });
       files.push({
-        path: path32.join(outputDir, "tsconfig.json"),
+        path: path33.join(outputDir, "tsconfig.json"),
         content: JSON.stringify(
           {
             compilerOptions: {
@@ -91817,14 +92246,14 @@ async function exportCommand(input, options) {
 }
 
 // src/cli/commands/openapi.ts
-import * as path33 from "path";
-import * as fs32 from "fs";
+import * as path34 from "path";
+import * as fs33 from "fs";
 async function openapiCommand(dir, options) {
-  const workflowDir = path33.resolve(dir);
-  if (!fs32.existsSync(workflowDir)) {
+  const workflowDir = path34.resolve(dir);
+  if (!fs33.existsSync(workflowDir)) {
     throw new Error(`Directory not found: ${workflowDir}`);
   }
-  if (!fs32.statSync(workflowDir).isDirectory()) {
+  if (!fs33.statSync(workflowDir).isDirectory()) {
     throw new Error(`Not a directory: ${workflowDir}`);
   }
   const registry2 = new WorkflowRegistry(workflowDir);
@@ -91843,8 +92272,8 @@ async function openapiCommand(dir, options) {
   const format = options.format || "json";
   const spec = format === "yaml" ? generateOpenAPIYaml(endpoints, generatorOptions) : generateOpenAPIJson(endpoints, generatorOptions);
   if (options.output) {
-    const outputPath = path33.resolve(options.output);
-    fs32.writeFileSync(outputPath, spec);
+    const outputPath = path34.resolve(options.output);
+    fs33.writeFileSync(outputPath, spec);
     logger.success(`OpenAPI specification written to ${outputPath}`);
   } else {
     process.stdout.write(spec + "\n");
@@ -91852,8 +92281,8 @@ async function openapiCommand(dir, options) {
 }
 
 // src/cli/commands/plugin.ts
-import * as fs33 from "fs";
-import * as path34 from "path";
+import * as fs34 from "fs";
+import * as path35 from "path";
 var PLUGIN_NAME_RE = /^[a-zA-Z0-9][-a-zA-Z0-9_.]*$/;
 var VALID_AREAS = ["sidebar", "main", "toolbar", "modal", "panel"];
 function validatePluginName(name) {
@@ -91980,18 +92409,18 @@ async function pluginInitCommand(name, options) {
     }
     return;
   }
-  const targetDir = path34.resolve("plugins", name);
+  const targetDir = path35.resolve("plugins", name);
   const filesCreated = [];
   const filesSkipped = [];
   for (const [relativePath, content] of Object.entries(files)) {
-    const absPath = path34.join(targetDir, relativePath);
-    const dir = path34.dirname(absPath);
-    fs33.mkdirSync(dir, { recursive: true });
-    if (fs33.existsSync(absPath) && !force) {
+    const absPath = path35.join(targetDir, relativePath);
+    const dir = path35.dirname(absPath);
+    fs34.mkdirSync(dir, { recursive: true });
+    if (fs34.existsSync(absPath) && !force) {
       filesSkipped.push(relativePath);
       continue;
     }
-    fs33.writeFileSync(absPath, content, "utf8");
+    fs34.writeFileSync(absPath, content, "utf8");
     filesCreated.push(relativePath);
   }
   logger.section("Plugin scaffolded");
@@ -92010,8 +92439,8 @@ async function pluginInitCommand(name, options) {
 
 // src/cli/commands/migrate.ts
 init_esm5();
-import * as fs34 from "fs";
-import * as path35 from "path";
+import * as fs35 from "fs";
+import * as path36 from "path";
 async function migrateCommand(globPattern, options = {}) {
   const { dryRun = false, diff = false } = options;
   const files = globSync(globPattern, { ignore: ["**/node_modules/**", "**/*.generated.ts"] });
@@ -92027,9 +92456,9 @@ async function migrateCommand(globPattern, options = {}) {
   let skippedCount = 0;
   let errorCount = 0;
   for (const file of files) {
-    const filePath = path35.resolve(file);
+    const filePath = path36.resolve(file);
     try {
-      const sourceCode = fs34.readFileSync(filePath, "utf8");
+      const sourceCode = fs35.readFileSync(filePath, "utf8");
       const parseResult = await parseWorkflow(filePath);
       if (parseResult.errors.length > 0) {
         logger.error(`  ${file}: parse errors \u2014 skipping`);
@@ -92062,7 +92491,7 @@ ${file}:`);
         migratedCount++;
         continue;
       }
-      fs34.writeFileSync(filePath, genResult.code, "utf8");
+      fs35.writeFileSync(filePath, genResult.code, "utf8");
       logger.success(`  ${file}: migrated`);
       migratedCount++;
     } catch (error2) {
@@ -92192,9 +92621,82 @@ async function changelogCommand(options = {}) {
   }
 }
 
+// src/cli/commands/docs.ts
+async function docsListCommand(options) {
+  const topics = listTopics();
+  if (topics.length === 0) {
+    logger.error("No documentation topics found.");
+    process.exit(1);
+  }
+  if (options.json) {
+    process.stdout.write(JSON.stringify({ topics }, null, 2) + "\n");
+    return;
+  }
+  logger.section("Flow Weaver Documentation");
+  logger.newline();
+  const maxSlug = Math.max(...topics.map((t) => t.slug.length));
+  for (const topic of topics) {
+    logger.log(`  ${topic.slug.padEnd(maxSlug + 2)} ${topic.description}`);
+  }
+  logger.newline();
+  logger.log("  Usage: flow-weaver docs <topic>");
+  logger.log("  Search: flow-weaver docs search <query>");
+  logger.newline();
+}
+async function docsReadCommand(topic, options) {
+  if (options.json) {
+    const structured = readTopicStructured(topic);
+    if (!structured) {
+      logger.error(`Unknown topic: "${topic}". Run "flow-weaver docs" to see available topics.`);
+      process.exit(1);
+    }
+    process.stdout.write(JSON.stringify(structured, null, 2) + "\n");
+    return;
+  }
+  const doc = readTopic(topic, options.compact);
+  if (!doc) {
+    logger.error(`Unknown topic: "${topic}". Run "flow-weaver docs" to see available topics.`);
+    process.exit(1);
+  }
+  process.stdout.write(doc.content + "\n");
+}
+async function docsSearchCommand(query, options) {
+  const results = searchDocs(query);
+  if (options.json) {
+    process.stdout.write(JSON.stringify({ query, results }, null, 2) + "\n");
+    return;
+  }
+  if (results.length === 0) {
+    logger.log(`No results found for "${query}".`);
+    return;
+  }
+  logger.section(`Search results for "${query}"`);
+  logger.newline();
+  const seen = /* @__PURE__ */ new Set();
+  let shown = 0;
+  for (const result of results) {
+    const key = `${result.slug}:${result.heading}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    logger.log(`  [${result.slug}] ${result.heading}`);
+    if (result.excerpt) {
+      const excerptLines = result.excerpt.split("\n").slice(0, 2);
+      for (const line of excerptLines) {
+        logger.log(`    ${line}`);
+      }
+    }
+    logger.newline();
+    shown++;
+    if (shown >= 15) break;
+  }
+  logger.log(`  ${results.length} matching section(s) across ${new Set(results.map((r) => r.slug)).size} topic(s).`);
+  logger.log("  Read a topic: flow-weaver docs <topic>");
+  logger.newline();
+}
+
 // src/cli/commands/market.ts
-import * as fs35 from "fs";
-import * as path36 from "path";
+import * as fs36 from "fs";
+import * as path37 from "path";
 import { execSync as execSync6 } from "child_process";
 async function marketInitCommand(name, options = {}) {
   if (!name.startsWith("flowweaver-pack-")) {
@@ -92202,11 +92704,11 @@ async function marketInitCommand(name, options = {}) {
     logger.warn(`Name should follow "flowweaver-pack-*" convention, using "${suggested}"`);
     name = suggested;
   }
-  const targetDir = path36.resolve(name);
-  if (fs35.existsSync(targetDir)) {
-    const stat = fs35.statSync(targetDir);
+  const targetDir = path37.resolve(name);
+  if (fs36.existsSync(targetDir)) {
+    const stat = fs36.statSync(targetDir);
     if (stat.isDirectory()) {
-      const contents = fs35.readdirSync(targetDir);
+      const contents = fs36.readdirSync(targetDir);
       if (contents.length > 0) {
         logger.error(`Directory "${name}" already exists and is not empty`);
         process.exit(1);
@@ -92221,13 +92723,13 @@ async function marketInitCommand(name, options = {}) {
   logger.newline();
   const dirs = [
     targetDir,
-    path36.join(targetDir, "src"),
-    path36.join(targetDir, "src", "node-types"),
-    path36.join(targetDir, "src", "workflows"),
-    path36.join(targetDir, "src", "patterns")
+    path37.join(targetDir, "src"),
+    path37.join(targetDir, "src", "node-types"),
+    path37.join(targetDir, "src", "workflows"),
+    path37.join(targetDir, "src", "patterns")
   ];
   for (const dir of dirs) {
-    fs35.mkdirSync(dir, { recursive: true });
+    fs36.mkdirSync(dir, { recursive: true });
   }
   const shortName = name.replace(/^flowweaver-pack-/, "");
   const pkg = {
@@ -92258,8 +92760,8 @@ async function marketInitCommand(name, options = {}) {
     },
     files: ["dist", "flowweaver.manifest.json", "README.md", "LICENSE"]
   };
-  fs35.writeFileSync(
-    path36.join(targetDir, "package.json"),
+  fs36.writeFileSync(
+    path37.join(targetDir, "package.json"),
     JSON.stringify(pkg, null, 2) + "\n"
   );
   const tsconfig = {
@@ -92277,8 +92779,8 @@ async function marketInitCommand(name, options = {}) {
     include: ["src"],
     exclude: ["node_modules", "dist"]
   };
-  fs35.writeFileSync(
-    path36.join(targetDir, "tsconfig.json"),
+  fs36.writeFileSync(
+    path37.join(targetDir, "tsconfig.json"),
     JSON.stringify(tsconfig, null, 2) + "\n"
   );
   const sampleNodeType = `/**
@@ -92296,21 +92798,21 @@ export function sample(execute: () => void, data: string): { result: string } {
   return { result: data.toUpperCase() };
 }
 `;
-  fs35.writeFileSync(path36.join(targetDir, "src", "node-types", "sample.ts"), sampleNodeType);
-  fs35.writeFileSync(
-    path36.join(targetDir, "src", "node-types", "index.ts"),
+  fs36.writeFileSync(path37.join(targetDir, "src", "node-types", "sample.ts"), sampleNodeType);
+  fs36.writeFileSync(
+    path37.join(targetDir, "src", "node-types", "index.ts"),
     "export { sample } from './sample.js';\n"
   );
-  fs35.writeFileSync(
-    path36.join(targetDir, "src", "workflows", "index.ts"),
+  fs36.writeFileSync(
+    path37.join(targetDir, "src", "workflows", "index.ts"),
     "// Export workflows here\n"
   );
-  fs35.writeFileSync(
-    path36.join(targetDir, "src", "patterns", "index.ts"),
+  fs36.writeFileSync(
+    path37.join(targetDir, "src", "patterns", "index.ts"),
     "// Export patterns here\n"
   );
-  fs35.writeFileSync(
-    path36.join(targetDir, "src", "index.ts"),
+  fs36.writeFileSync(
+    path37.join(targetDir, "src", "index.ts"),
     [
       "export * from './node-types/index.js';",
       "export * from './workflows/index.js';",
@@ -92343,9 +92845,9 @@ npm run pack    # Generate flowweaver.manifest.json
 npm publish     # Publish to npm
 \`\`\`
 `;
-  fs35.writeFileSync(path36.join(targetDir, "README.md"), readme);
-  fs35.writeFileSync(
-    path36.join(targetDir, ".gitignore"),
+  fs36.writeFileSync(path37.join(targetDir, "README.md"), readme);
+  fs36.writeFileSync(
+    path37.join(targetDir, ".gitignore"),
     ["node_modules", "dist", "*.tgz", ""].join("\n")
   );
   logger.success("Created package.json");
@@ -92365,7 +92867,7 @@ npm publish     # Publish to npm
   logger.newline();
 }
 async function marketPackCommand(directory, options = {}) {
-  const dir = path36.resolve(directory ?? ".");
+  const dir = path37.resolve(directory ?? ".");
   const { json: json2 = false, verbose = false } = options;
   if (!json2) {
     logger.section("Packing Marketplace Package");
@@ -92404,21 +92906,21 @@ async function marketPackCommand(directory, options = {}) {
   }
   const outPath = writeManifest(dir, manifest);
   logger.newline();
-  logger.success(`Manifest written to ${path36.relative(dir, outPath)}`);
+  logger.success(`Manifest written to ${path37.relative(dir, outPath)}`);
   if (warnings.length > 0) {
     logger.warn(`${warnings.length} warning(s) \u2014 consider fixing before publishing`);
   }
   logger.newline();
 }
 async function marketPublishCommand(directory, options = {}) {
-  const dir = path36.resolve(directory ?? ".");
+  const dir = path37.resolve(directory ?? ".");
   const { dryRun = false, tag } = options;
   logger.section("Publishing Marketplace Package");
   await marketPackCommand(dir, { json: false });
-  if (!fs35.existsSync(path36.join(dir, "LICENSE"))) {
+  if (!fs36.existsSync(path37.join(dir, "LICENSE"))) {
     logger.warn("LICENSE file not found \u2014 consider adding one");
   }
-  const pkg = JSON.parse(fs35.readFileSync(path36.join(dir, "package.json"), "utf-8"));
+  const pkg = JSON.parse(fs36.readFileSync(path37.join(dir, "package.json"), "utf-8"));
   logger.info(`Publishing ${pkg.name}@${pkg.version}`);
   const npmArgs = ["publish"];
   if (dryRun) npmArgs.push("--dry-run");
@@ -92453,7 +92955,7 @@ async function marketInstallCommand(packageSpec, options = {}) {
     process.exit(1);
   }
   const packageName = resolvePackageName2(packageSpec);
-  const manifest = readManifest(path36.join(process.cwd(), "node_modules", packageName));
+  const manifest = readManifest(path37.join(process.cwd(), "node_modules", packageName));
   if (json2) {
     console.log(JSON.stringify({
       success: true,
@@ -92537,7 +93039,7 @@ async function marketListCommand(options = {}) {
 }
 function resolvePackageName2(spec) {
   if (spec.endsWith(".tgz") || spec.endsWith(".tar.gz")) {
-    const base = path36.basename(spec, spec.endsWith(".tar.gz") ? ".tar.gz" : ".tgz");
+    const base = path37.basename(spec, spec.endsWith(".tar.gz") ? ".tar.gz" : ".tgz");
     const match2 = base.match(/^(.+)-\d+\.\d+\.\d+/);
     return match2 ? match2[1] : base;
   }
@@ -92586,7 +93088,7 @@ function displayInstalledPackage(pkg) {
 }
 
 // src/cli/index.ts
-var version2 = true ? "0.2.1" : "0.0.0-dev";
+var version2 = true ? "0.3.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({
@@ -92855,6 +93357,31 @@ program2.command("changelog").description("Generate changelog from git history,
     process.exit(1);
   }
 });
+var docsCmd = program2.command("docs").description("Browse reference documentation");
+docsCmd.command("list", { isDefault: true }).description("List available documentation topics").option("--json", "Output as JSON", false).option("--compact", "Compact output", false).action(async (options) => {
+  try {
+    await docsListCommand(options);
+  } catch (error2) {
+    logger.error(`Command failed: ${getErrorMessage(error2)}`);
+    process.exit(1);
+  }
+});
+docsCmd.command("read <topic>").description("Read a documentation topic").option("--json", "Output as JSON", false).option("--compact", "Return compact LLM-friendly version", false).action(async (topic, options) => {
+  try {
+    await docsReadCommand(topic, options);
+  } catch (error2) {
+    logger.error(`Command failed: ${getErrorMessage(error2)}`);
+    process.exit(1);
+  }
+});
+docsCmd.command("search <query>").description("Search across all documentation").option("--json", "Output as JSON", false).action(async (query, options) => {
+  try {
+    await docsSearchCommand(query, options);
+  } catch (error2) {
+    logger.error(`Command failed: ${getErrorMessage(error2)}`);
+    process.exit(1);
+  }
+});
 var marketCmd = program2.command("market").description("Discover, install, and publish marketplace packages");
 marketCmd.command("init <name>").description("Scaffold a new marketplace package").option("-d, --description <desc>", "Package description").option("-a, --author <author>", "Author name").option("-y, --yes", "Skip prompts and use defaults", false).action(async (name, options) => {
   try {
@@ -92956,6 +93483,13 @@ program2.on("--help", () => {
   logger.log("  $ flow-weaver market search openai");
   logger.log("  $ flow-weaver market list");
   logger.newline();
+  logger.section("Documentation");
+  logger.log("  $ flow-weaver docs");
+  logger.log("  $ flow-weaver docs read error-codes");
+  logger.log("  $ flow-weaver docs read scaffold --compact");
+  logger.log('  $ flow-weaver docs search "missing workflow"');
+  logger.log("  $ flow-weaver docs read error-codes --json");
+  logger.newline();
   logger.section("Migration & Changelog");
   logger.log("  $ flow-weaver migrate '**/*.ts'");
   logger.log("  $ flow-weaver migrate '**/*.ts' --dry-run");