@synergenius/flow-weaver 0.11.0 → 0.12.0

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

@@ -0,0 +1,13 @@
+/**
+ * Context command - generate LLM context bundles from documentation and grammar
+ */
+export interface ContextCommandOptions {
+    profile?: string;
+    topics?: string;
+    add?: string;
+    grammar?: boolean;
+    output?: string;
+    list?: boolean;
+}
+export declare function contextCommand(preset: string | undefined, options: ContextCommandOptions): Promise<void>;
+//# sourceMappingURL=context.d.ts.map

package/dist/cli/commands/context.js

@@ -0,0 +1,53 @@
+/**
+ * Context command - generate LLM context bundles from documentation and grammar
+ */
+import * as fs from 'fs';
+import { buildContext, PRESETS, PRESET_NAMES } from '../../context/index.js';
+import { logger } from '../utils/logger.js';
+export async function contextCommand(preset, options) {
+    // --list: show presets and exit
+    if (options.list) {
+        logger.section('Context Presets');
+        logger.newline();
+        const maxName = Math.max(...PRESET_NAMES.map((n) => n.length));
+        for (const name of PRESET_NAMES) {
+            const topics = PRESETS[name];
+            logger.log(`  ${name.padEnd(maxName + 2)} ${topics.join(', ')}`);
+        }
+        logger.newline();
+        logger.log('  Usage: flow-weaver context [preset] [options]');
+        logger.newline();
+        return;
+    }
+    // Validate preset
+    const presetName = (preset ?? 'core');
+    if (!PRESET_NAMES.includes(presetName) && !options.topics) {
+        logger.error(`Unknown preset "${preset}". Available: ${PRESET_NAMES.join(', ')}. Or use --topics to specify topics directly.`);
+        process.exit(1);
+    }
+    // Validate profile
+    const profile = options.profile ?? 'standalone';
+    if (profile !== 'standalone' && profile !== 'assistant') {
+        logger.error(`Unknown profile "${profile}". Use "standalone" or "assistant".`);
+        process.exit(1);
+    }
+    const result = buildContext({
+        preset: PRESET_NAMES.includes(presetName) ? presetName : 'core',
+        profile: profile,
+        topics: options.topics ? options.topics.split(',').map((s) => s.trim()) : undefined,
+        addTopics: options.add ? options.add.split(',').map((s) => s.trim()) : undefined,
+        includeGrammar: options.grammar !== false,
+    });
+    // Write output
+    if (options.output) {
+        fs.writeFileSync(options.output, result.content, 'utf-8');
+        logger.success(`Context written to ${options.output}`);
+    }
+    else {
+        process.stdout.write(result.content);
+    }
+    // Stats to stderr (doesn't pollute piped stdout)
+    const stats = `${result.topicCount} topics, ${result.lineCount} lines (${result.profile} profile)`;
+    process.stderr.write(`flow-weaver context: ${stats}\n`);
+}
+//# sourceMappingURL=context.js.map

package/dist/cli/flow-weaver.mjs

@@ -936,7 +936,7 @@ var require_command = __commonJS({
     var EventEmitter2 = __require("events").EventEmitter;
     var childProcess = __require("child_process");
     var path51 = __require("path");
-    var fs50 = __require("fs");
+    var fs51 = __require("fs");
     var process6 = __require("process");
     var { Argument: Argument2, humanReadableArgName } = require_argument();
     var { CommanderError: CommanderError2 } = require_error();
@@ -1760,9 +1760,9 @@ Expecting one of '${allowedValues.join("', '")}'`);
         const sourceExt = [".js", ".ts", ".tsx", ".mjs", ".cjs"];
         function findFile(baseDir, baseName) {
           const localBin = path51.resolve(baseDir, baseName);
-          if (fs50.existsSync(localBin)) return localBin;
+          if (fs51.existsSync(localBin)) return localBin;
           if (sourceExt.includes(path51.extname(baseName))) return void 0;
-          const foundExt = sourceExt.find((ext2) => fs50.existsSync(`${localBin}${ext2}`));
+          const foundExt = sourceExt.find((ext2) => fs51.existsSync(`${localBin}${ext2}`));
           if (foundExt) return `${localBin}${foundExt}`;
           return void 0;
         }
@@ -1773,7 +1773,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         if (this._scriptPath) {
           let resolvedScriptPath;
           try {
-            resolvedScriptPath = fs50.realpathSync(this._scriptPath);
+            resolvedScriptPath = fs51.realpathSync(this._scriptPath);
           } catch (err) {
             resolvedScriptPath = this._scriptPath;
           }
@@ -7740,8 +7740,8 @@ var init_esm4 = __esm({
        *
        * @internal
        */
-      constructor(cwd = process.cwd(), pathImpl, sep3, { nocase, childrenCacheSize = 16 * 1024, fs: fs50 = defaultFS } = {}) {
-        this.#fs = fsFromOption(fs50);
+      constructor(cwd = process.cwd(), pathImpl, sep3, { nocase, childrenCacheSize = 16 * 1024, fs: fs51 = defaultFS } = {}) {
+        this.#fs = fsFromOption(fs51);
         if (cwd instanceof URL || cwd.startsWith("file://")) {
           cwd = fileURLToPath(cwd);
         }
@@ -8299,8 +8299,8 @@ var init_esm4 = __esm({
       /**
        * @internal
        */
-      newRoot(fs50) {
-        return new PathWin32(this.rootPath, IFDIR, void 0, this.roots, this.nocase, this.childrenCache(), { fs: fs50 });
+      newRoot(fs51) {
+        return new PathWin32(this.rootPath, IFDIR, void 0, this.roots, this.nocase, this.childrenCache(), { fs: fs51 });
       }
       /**
        * Return true if the provided path string is an absolute path
@@ -8328,8 +8328,8 @@ var init_esm4 = __esm({
       /**
        * @internal
        */
-      newRoot(fs50) {
-        return new PathPosix(this.rootPath, IFDIR, void 0, this.roots, this.nocase, this.childrenCache(), { fs: fs50 });
+      newRoot(fs51) {
+        return new PathPosix(this.rootPath, IFDIR, void 0, this.roots, this.nocase, this.childrenCache(), { fs: fs51 });
       }
       /**
        * Return true if the provided path string is an absolute path
@@ -13168,12 +13168,12 @@ var require_binary_search = __commonJS({
 var require_read_wasm = __commonJS({
   "node_modules/source-map/lib/read-wasm.js"(exports2, module2) {
     "use strict";
-    var fs50 = __require("fs");
+    var fs51 = __require("fs");
     var path51 = __require("path");
     module2.exports = function readWasm() {
       return new Promise((resolve35, reject2) => {
         const wasmPath = path51.join(__dirname, "mappings.wasm");
-        fs50.readFile(wasmPath, null, (error2, data) => {
+        fs51.readFile(wasmPath, null, (error2, data) => {
           if (error2) {
             reject2(error2);
             return;
@@ -49111,7 +49111,7 @@ var init_workflow_executor = __esm({
 // node_modules/xmlhttprequest-ssl/lib/XMLHttpRequest.js
 var require_XMLHttpRequest = __commonJS({
   "node_modules/xmlhttprequest-ssl/lib/XMLHttpRequest.js"(exports2, module2) {
-    var fs50 = __require("fs");
+    var fs51 = __require("fs");
     var Url = __require("url");
     var spawn2 = __require("child_process").spawn;
     module2.exports = XMLHttpRequest3;
@@ -49269,7 +49269,7 @@ var require_XMLHttpRequest = __commonJS({
             throw new Error("XMLHttpRequest: Only GET method is supported");
           }
           if (settings.async) {
-            fs50.readFile(unescape(url2.pathname), function(error2, data2) {
+            fs51.readFile(unescape(url2.pathname), function(error2, data2) {
               if (error2) {
                 self2.handleError(error2, error2.errno || -1);
               } else {
@@ -49281,7 +49281,7 @@ var require_XMLHttpRequest = __commonJS({
             });
           } else {
             try {
-              this.response = fs50.readFileSync(unescape(url2.pathname));
+              this.response = fs51.readFileSync(unescape(url2.pathname));
               this.responseText = this.response.toString("utf8");
               this.status = 200;
               setState(self2.DONE);
@@ -49407,15 +49407,15 @@ var require_XMLHttpRequest = __commonJS({
         } else {
           var contentFile = ".node-xmlhttprequest-content-" + process.pid;
           var syncFile = ".node-xmlhttprequest-sync-" + process.pid;
-          fs50.writeFileSync(syncFile, "", "utf8");
+          fs51.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 (fs50.existsSync(syncFile)) {
+          while (fs51.existsSync(syncFile)) {
           }
-          self2.responseText = fs50.readFileSync(contentFile, "utf8");
+          self2.responseText = fs51.readFileSync(contentFile, "utf8");
           syncProc.stdin.end();
-          fs50.unlinkSync(contentFile);
+          fs51.unlinkSync(contentFile);
           if (self2.responseText.match(/^NODE-XMLHTTPREQUEST-ERROR:/)) {
             var errorObj = JSON.parse(self2.responseText.replace(/^NODE-XMLHTTPREQUEST-ERROR:/, ""));
             self2.handleError(errorObj, 503);
@@ -64331,12 +64331,12 @@ var require_dist = __commonJS({
         throw new Error(`Unknown format "${name}"`);
       return f;
     };
-    function addFormats(ajv, list, fs50, exportName) {
+    function addFormats(ajv, list, fs51, 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, fs50[f]);
+        ajv.addFormat(f, fs51[f]);
     }
     module2.exports = exports2 = formatsPlugin;
     Object.defineProperty(exports2, "__esModule", { value: true });
@@ -94673,8 +94673,8 @@ ${parseResult.errors.join("\n")}`);
           });
           const outputFile = filePath.replace(/\.ts$/, ".inngest.ts");
           if (args.write !== false) {
-            const fs50 = await import("fs");
-            fs50.writeFileSync(outputFile, code, "utf8");
+            const fs51 = await import("fs");
+            fs51.writeFileSync(outputFile, code, "utf8");
           }
           return makeToolResult({
             target: "inngest",
@@ -103162,6 +103162,199 @@ function registerDebugTools(mcp) {
   );
 }
 
+// src/context/index.ts
+init_grammar_diagrams();
+var PRESETS = {
+  core: ["concepts", "jsdoc-grammar", "tutorial"],
+  authoring: [
+    "concepts",
+    "jsdoc-grammar",
+    "advanced-annotations",
+    "built-in-nodes",
+    "scaffold",
+    "node-conversion",
+    "patterns"
+  ],
+  ops: [
+    "cli-reference",
+    "compilation",
+    "deployment",
+    "export-interface",
+    "debugging",
+    "error-codes"
+  ],
+  full: [
+    "concepts",
+    "tutorial",
+    "jsdoc-grammar",
+    "advanced-annotations",
+    "built-in-nodes",
+    "cli-reference",
+    "compilation",
+    "debugging",
+    "deployment",
+    "error-codes",
+    "export-interface",
+    "iterative-development",
+    "marketplace",
+    "node-conversion",
+    "patterns",
+    "scaffold"
+  ]
+};
+var PRESET_NAMES = Object.keys(PRESETS);
+var STANDALONE_PREAMBLE = `# Flow Weaver Reference
+
+Flow Weaver is a TypeScript workflow compiler. You write plain .ts files with
+JSDoc annotations (@flowWeaver nodeType, @flowWeaver workflow, @input, @output,
+@connect, @node, @scope). The compiler parses these annotations, validates the
+graph, and generates executable code inline. The source file is the workflow:
+no JSON configs, no YAML, no separate graph files.
+
+Key concepts: node types define reusable processing steps with typed input/output
+ports. Workflows instantiate nodes and connect their ports. Start and Exit are
+implicit boundary nodes. The compiler handles execution ordering, type checking,
+and code generation.`;
+function buildAssistantPreamble() {
+  const allSlugs = listTopics().map((t) => t.slug);
+  return `# Flow Weaver Context
+
+You have Flow Weaver MCP tools available (fw_ prefix). Use them to create,
+modify, validate, compile, and inspect workflows without manual file editing.
+
+For documentation not included below, call fw_docs(action="read", topic="<slug>").
+Available topic slugs: ${allSlugs.join(", ")}.
+
+Tool quick reference:
+- fw_create_model: Build workflow from structured description (steps + flow path)
+- fw_implement_node: Replace a declare stub with a real function body
+- fw_modify / fw_modify_batch: Add/remove nodes, connections, rename, reposition
+- fw_validate: Check for errors after any change
+- fw_describe: Inspect structure. Use format "text" for readable, "json" for data
+- fw_diagram: Visualize. Prefer format "ascii-compact" in chat contexts
+- fw_compile: Generate executable TypeScript from annotations
+- fw_docs: Look up reference docs by topic slug
+- fw_scaffold: Create from templates (sequential, foreach, ai-agent, etc.)
+
+File conventions: .ts extension, camelCase node names, PascalCase workflow names.`;
+}
+function resolveTopics(preset, explicit, add) {
+  const base = explicit ?? PRESETS[preset];
+  const combined = add ? [...base, ...add] : base;
+  return [...new Set(combined)];
+}
+function buildGrammarSection() {
+  const grammars = getAllGrammars();
+  const allProductions = [
+    ...grammars.port,
+    ...grammars.node,
+    ...grammars.connect,
+    ...grammars.position,
+    ...grammars.scope
+  ];
+  const ebnf = serializedToEBNF(allProductions);
+  return `## JSDoc Annotation Grammar (EBNF)
+
+\`\`\`ebnf
+${ebnf}
+\`\`\``;
+}
+function buildContext(options = {}) {
+  const profile = options.profile ?? "standalone";
+  const preset = options.preset ?? "core";
+  const includeGrammar = options.includeGrammar ?? true;
+  const topicSlugs = resolveTopics(preset, options.topics, options.addTopics);
+  const sections = [];
+  if (profile === "standalone") {
+    sections.push(STANDALONE_PREAMBLE);
+  } else {
+    sections.push(buildAssistantPreamble());
+  }
+  if (includeGrammar) {
+    sections.push(buildGrammarSection());
+  }
+  let topicCount = 0;
+  const includedSlugs = [];
+  for (const slug of topicSlugs) {
+    const doc = readTopic(slug, true);
+    if (!doc) continue;
+    let body = doc.content;
+    if (body.startsWith("# ")) {
+      const lines = body.split("\n");
+      let startLine = 1;
+      if (lines.length > 1 && lines[1].trim() && !lines[1].startsWith("#")) {
+        startLine = 2;
+      }
+      body = lines.slice(startLine).join("\n").replace(/^\n+/, "");
+    }
+    const bodyLines = body.split("\n");
+    let inCode = false;
+    for (let i = 0; i < bodyLines.length; i++) {
+      if (bodyLines[i].trimStart().startsWith("```")) {
+        inCode = !inCode;
+        continue;
+      }
+      if (!inCode && bodyLines[i].match(/^#{1,5}\s/)) {
+        bodyLines[i] = "##" + bodyLines[i];
+      }
+    }
+    body = bodyLines.join("\n");
+    const heading = doc.name || slug;
+    sections.push(`## ${heading}
+
+${body}`);
+    topicCount++;
+    includedSlugs.push(slug);
+  }
+  const content = sections.join("\n\n---\n\n");
+  const lineCount = content.split("\n").length;
+  return {
+    content,
+    topicCount,
+    lineCount,
+    topicSlugs: includedSlugs,
+    profile
+  };
+}
+
+// src/mcp/tools-context.ts
+function registerContextTools(mcp) {
+  mcp.tool(
+    "fw_context",
+    'Generate a self-contained LLM context bundle with Flow Weaver documentation, grammar, and conventions. Use preset="core" for basics, "authoring" for writing workflows, "full" for everything, "ops" for CLI/deployment reference.',
+    {
+      preset: external_exports.enum(["core", "authoring", "full", "ops"]).optional().default("core").describe("Topic preset"),
+      profile: external_exports.enum(["standalone", "assistant"]).optional().default("assistant").describe("standalone = full self-contained dump, assistant = assumes MCP tools available"),
+      topics: external_exports.string().optional().describe("Comma-separated topic slugs (overrides preset)"),
+      addTopics: external_exports.string().optional().describe("Comma-separated slugs to add to preset"),
+      includeGrammar: external_exports.boolean().optional().default(true).describe("Include EBNF annotation grammar section")
+    },
+    async (args) => {
+      try {
+        const result = buildContext({
+          preset: args.preset,
+          profile: args.profile,
+          topics: args.topics ? args.topics.split(",").map((s) => s.trim()) : void 0,
+          addTopics: args.addTopics ? args.addTopics.split(",").map((s) => s.trim()) : void 0,
+          includeGrammar: args.includeGrammar
+        });
+        return makeToolResult({
+          profile: result.profile,
+          topicCount: result.topicCount,
+          lineCount: result.lineCount,
+          topicSlugs: result.topicSlugs,
+          content: result.content
+        });
+      } catch (err) {
+        return makeErrorResult(
+          "CONTEXT_ERROR",
+          `fw_context failed: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
+  );
+}
+
 // src/mcp/resources.ts
 function registerResources(mcp, connection, buffer) {
   mcp.resource(
@@ -103336,6 +103529,7 @@ async function startMcpServer(options) {
   registerDocsTools(mcp);
   registerModelTools(mcp);
   registerDebugTools(mcp);
+  registerContextTools(mcp);
   registerResources(mcp, connection, buffer);
   registerPrompts(mcp);
   if (!options._testDeps && options.stdio) {
@@ -106445,10 +106639,56 @@ async function docsSearchCommand(query, options) {
   logger.newline();
 }
 
+// src/cli/commands/context.ts
+import * as fs46 from "fs";
+async function contextCommand(preset, options) {
+  if (options.list) {
+    logger.section("Context Presets");
+    logger.newline();
+    const maxName = Math.max(...PRESET_NAMES.map((n) => n.length));
+    for (const name of PRESET_NAMES) {
+      const topics = PRESETS[name];
+      logger.log(`  ${name.padEnd(maxName + 2)} ${topics.join(", ")}`);
+    }
+    logger.newline();
+    logger.log("  Usage: flow-weaver context [preset] [options]");
+    logger.newline();
+    return;
+  }
+  const presetName = preset ?? "core";
+  if (!PRESET_NAMES.includes(presetName) && !options.topics) {
+    logger.error(
+      `Unknown preset "${preset}". Available: ${PRESET_NAMES.join(", ")}. Or use --topics to specify topics directly.`
+    );
+    process.exit(1);
+  }
+  const profile = options.profile ?? "standalone";
+  if (profile !== "standalone" && profile !== "assistant") {
+    logger.error(`Unknown profile "${profile}". Use "standalone" or "assistant".`);
+    process.exit(1);
+  }
+  const result = buildContext({
+    preset: PRESET_NAMES.includes(presetName) ? presetName : "core",
+    profile,
+    topics: options.topics ? options.topics.split(",").map((s) => s.trim()) : void 0,
+    addTopics: options.add ? options.add.split(",").map((s) => s.trim()) : void 0,
+    includeGrammar: options.grammar !== false
+  });
+  if (options.output) {
+    fs46.writeFileSync(options.output, result.content, "utf-8");
+    logger.success(`Context written to ${options.output}`);
+  } else {
+    process.stdout.write(result.content);
+  }
+  const stats = `${result.topicCount} topics, ${result.lineCount} lines (${result.profile} profile)`;
+  process.stderr.write(`flow-weaver context: ${stats}
+`);
+}
+
 // src/cli/commands/status.ts
 init_api6();
 init_validator();
-import * as fs46 from "fs";
+import * as fs47 from "fs";
 import * as path47 from "path";
 init_error_utils();
 function formatPortList(ports) {
@@ -106458,7 +106698,7 @@ async function statusCommand(input, options = {}) {
   const { workflowName, json: json2 = false } = options;
   try {
     const filePath = path47.resolve(input);
-    if (!fs46.existsSync(filePath)) {
+    if (!fs47.existsSync(filePath)) {
       if (json2) {
         console.log(JSON.stringify({ error: `File not found: ${input}` }));
       } else {
@@ -106550,7 +106790,7 @@ async function statusCommand(input, options = {}) {
 // src/cli/commands/implement.ts
 init_api6();
 init_annotation_generator();
-import * as fs47 from "fs";
+import * as fs48 from "fs";
 import * as path48 from "path";
 init_error_utils();
 function findDeclareFunction2(source, functionName) {
@@ -106575,7 +106815,7 @@ async function implementCommand(input, nodeName, options = {}) {
   const { workflowName, preview = false } = options;
   try {
     const filePath = path48.resolve(input);
-    if (!fs47.existsSync(filePath)) {
+    if (!fs48.existsSync(filePath)) {
       logger.error(`File not found: ${input}`);
       process.exit(1);
     }
@@ -106605,7 +106845,7 @@ async function implementCommand(input, nodeName, options = {}) {
       }
       process.exit(1);
     }
-    const source = fs47.readFileSync(filePath, "utf8");
+    const source = fs48.readFileSync(filePath, "utf8");
     const found = findDeclareFunction2(source, stubNodeType.functionName);
     if (!found) {
       logger.error(`Could not find "declare function ${stubNodeType.functionName}" in source file.`);
@@ -106620,7 +106860,7 @@ async function implementCommand(input, nodeName, options = {}) {
       console.log(replacement);
     } else {
       const updated = source.replace(found.match, replacement);
-      fs47.writeFileSync(filePath, updated, "utf8");
+      fs48.writeFileSync(filePath, updated, "utf8");
       logger.success(`Implemented ${stubNodeType.functionName} in ${path48.basename(filePath)}`);
     }
   } catch (error2) {
@@ -106630,7 +106870,7 @@ async function implementCommand(input, nodeName, options = {}) {
 }
 
 // src/cli/commands/market.ts
-import * as fs48 from "fs";
+import * as fs49 from "fs";
 import * as path49 from "path";
 import { execSync as execSync5 } from "child_process";
 init_error_utils();
@@ -106641,10 +106881,10 @@ async function marketInitCommand(name, options = {}) {
     name = suggested;
   }
   const targetDir = path49.resolve(name);
-  if (fs48.existsSync(targetDir)) {
-    const stat2 = fs48.statSync(targetDir);
+  if (fs49.existsSync(targetDir)) {
+    const stat2 = fs49.statSync(targetDir);
     if (stat2.isDirectory()) {
-      const contents = fs48.readdirSync(targetDir);
+      const contents = fs49.readdirSync(targetDir);
       if (contents.length > 0) {
         logger.error(`Directory "${name}" already exists and is not empty`);
         process.exit(1);
@@ -106665,7 +106905,7 @@ async function marketInitCommand(name, options = {}) {
     path49.join(targetDir, "src", "patterns")
   ];
   for (const dir of dirs) {
-    fs48.mkdirSync(dir, { recursive: true });
+    fs49.mkdirSync(dir, { recursive: true });
   }
   const shortName = name.replace(/^flowweaver-pack-/, "");
   const pkg = {
@@ -106696,7 +106936,7 @@ async function marketInitCommand(name, options = {}) {
     },
     files: ["dist", "flowweaver.manifest.json", "README.md", "LICENSE"]
   };
-  fs48.writeFileSync(
+  fs49.writeFileSync(
     path49.join(targetDir, "package.json"),
     JSON.stringify(pkg, null, 2) + "\n"
   );
@@ -106715,7 +106955,7 @@ async function marketInitCommand(name, options = {}) {
     include: ["src"],
     exclude: ["node_modules", "dist"]
   };
-  fs48.writeFileSync(
+  fs49.writeFileSync(
     path49.join(targetDir, "tsconfig.json"),
     JSON.stringify(tsconfig, null, 2) + "\n"
   );
@@ -106734,20 +106974,20 @@ export function sample(execute: () => void, data: string): { result: string } {
   return { result: data.toUpperCase() };
 }
 `;
-  fs48.writeFileSync(path49.join(targetDir, "src", "node-types", "sample.ts"), sampleNodeType);
-  fs48.writeFileSync(
+  fs49.writeFileSync(path49.join(targetDir, "src", "node-types", "sample.ts"), sampleNodeType);
+  fs49.writeFileSync(
     path49.join(targetDir, "src", "node-types", "index.ts"),
     "export { sample } from './sample.js';\n"
   );
-  fs48.writeFileSync(
+  fs49.writeFileSync(
     path49.join(targetDir, "src", "workflows", "index.ts"),
     "// Export workflows here\n"
   );
-  fs48.writeFileSync(
+  fs49.writeFileSync(
     path49.join(targetDir, "src", "patterns", "index.ts"),
     "// Export patterns here\n"
   );
-  fs48.writeFileSync(
+  fs49.writeFileSync(
     path49.join(targetDir, "src", "index.ts"),
     [
       "export * from './node-types/index.js';",
@@ -106781,8 +107021,8 @@ npm run pack    # Generate flowweaver.manifest.json
 npm publish     # Publish to npm
 \`\`\`
 `;
-  fs48.writeFileSync(path49.join(targetDir, "README.md"), readme);
-  fs48.writeFileSync(
+  fs49.writeFileSync(path49.join(targetDir, "README.md"), readme);
+  fs49.writeFileSync(
     path49.join(targetDir, ".gitignore"),
     ["node_modules", "dist", "*.tgz", ""].join("\n")
   );
@@ -106853,10 +107093,10 @@ async function marketPublishCommand(directory, options = {}) {
   const { dryRun = false, tag } = options;
   logger.section("Publishing Marketplace Package");
   await marketPackCommand(dir, { json: false });
-  if (!fs48.existsSync(path49.join(dir, "LICENSE"))) {
+  if (!fs49.existsSync(path49.join(dir, "LICENSE"))) {
     logger.warn("LICENSE file not found \u2014 consider adding one");
   }
-  const pkg = JSON.parse(fs48.readFileSync(path49.join(dir, "package.json"), "utf-8"));
+  const pkg = JSON.parse(fs49.readFileSync(path49.join(dir, "package.json"), "utf-8"));
   logger.info(`Publishing ${pkg.name}@${pkg.version}`);
   const npmArgs = ["publish"];
   if (dryRun) npmArgs.push("--dry-run");
@@ -107025,7 +107265,7 @@ function displayInstalledPackage(pkg) {
 
 // src/cli/commands/mcp-setup.ts
 import { execSync as execSync6 } from "child_process";
-import * as fs49 from "fs";
+import * as fs50 from "fs";
 import * as path50 from "path";
 import * as os3 from "os";
 var MCP_COMMAND = "npx";
@@ -107043,7 +107283,7 @@ function defaultDeps() {
     },
     fileExists: async (filePath) => {
       try {
-        await fs49.promises.access(filePath);
+        await fs50.promises.access(filePath);
         return true;
       } catch {
         return false;
@@ -107051,16 +107291,16 @@ function defaultDeps() {
     },
     readFile: async (filePath) => {
       try {
-        return await fs49.promises.readFile(filePath, "utf8");
+        return await fs50.promises.readFile(filePath, "utf8");
       } catch {
         return null;
       }
     },
     writeFile: async (filePath, content) => {
-      await fs49.promises.writeFile(filePath, content, "utf8");
+      await fs50.promises.writeFile(filePath, content, "utf8");
     },
     mkdir: async (dirPath) => {
-      await fs49.promises.mkdir(dirPath, { recursive: true });
+      await fs50.promises.mkdir(dirPath, { recursive: true });
     },
     cwd: () => process.cwd(),
     homedir: () => os3.homedir(),
@@ -107350,7 +107590,7 @@ async function mcpSetupCommand(options, deps) {
 
 // src/cli/index.ts
 init_error_utils();
-var version2 = true ? "0.11.0" : "0.0.0-dev";
+var version2 = true ? "0.12.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({
@@ -107678,6 +107918,14 @@ program2.command("docs [args...]").description("Browse reference documentation")
     process.exit(1);
   }
 });
+program2.command("context [preset]").description("Generate LLM context bundle from documentation and grammar").option("--profile <profile>", "Output profile: standalone or assistant", "standalone").option("--topics <slugs>", "Comma-separated topic slugs (overrides preset)").option("--add <slugs>", "Comma-separated topic slugs to add to preset").option("--no-grammar", "Omit EBNF grammar section").option("-o, --output <path>", "Write to file instead of stdout").option("--list", "List available presets and exit").action(async (preset, options) => {
+  try {
+    await contextCommand(preset, 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 {

package/dist/cli/index.js

@@ -32,6 +32,7 @@ import { migrateCommand } from './commands/migrate.js';
 import { changelogCommand } from './commands/changelog.js';
 import { stripCommand } from './commands/strip.js';
 import { docsListCommand, docsReadCommand, docsSearchCommand } from './commands/docs.js';
+import { contextCommand } from './commands/context.js';
 import { statusCommand } from './commands/status.js';
 import { implementCommand } from './commands/implement.js';
 import { marketInitCommand, marketPackCommand, marketPublishCommand, marketInstallCommand, marketSearchCommand, marketListCommand, } from './commands/market.js';
@@ -703,6 +704,25 @@ program
         process.exit(1);
     }
 });
+// Context command: generate LLM context bundles
+program
+    .command('context [preset]')
+    .description('Generate LLM context bundle from documentation and grammar')
+    .option('--profile <profile>', 'Output profile: standalone or assistant', 'standalone')
+    .option('--topics <slugs>', 'Comma-separated topic slugs (overrides preset)')
+    .option('--add <slugs>', 'Comma-separated topic slugs to add to preset')
+    .option('--no-grammar', 'Omit EBNF grammar section')
+    .option('-o, --output <path>', 'Write to file instead of stdout')
+    .option('--list', 'List available presets and exit')
+    .action(async (preset, options) => {
+    try {
+        await contextCommand(preset, options);
+    }
+    catch (error) {
+        logger.error(`Command failed: ${getErrorMessage(error)}`);
+        process.exit(1);
+    }
+});
 // Marketplace command group
 const marketCmd = program.command('market').description('Discover, install, and publish marketplace packages');
 marketCmd

package/dist/context/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * LLM context bundle builder.
+ *
+ * Composes Flow Weaver documentation, annotation grammar, and a profile-specific
+ * preamble into a single markdown document suitable for LLM consumption.
+ */
+export type ContextProfile = 'standalone' | 'assistant';
+export type ContextPreset = 'core' | 'authoring' | 'full' | 'ops';
+export interface ContextOptions {
+    preset?: ContextPreset;
+    profile?: ContextProfile;
+    /** Explicit topic slugs. Overrides the preset's topic list. */
+    topics?: string[];
+    /** Extra topic slugs appended to the preset. */
+    addTopics?: string[];
+    /** Include EBNF grammar section. Default true. */
+    includeGrammar?: boolean;
+}
+export interface ContextResult {
+    content: string;
+    topicCount: number;
+    lineCount: number;
+    topicSlugs: string[];
+    profile: ContextProfile;
+}
+export declare const PRESETS: Record<ContextPreset, string[]>;
+export declare const PRESET_NAMES: ContextPreset[];
+export declare function resolveTopics(preset: ContextPreset, explicit?: string[], add?: string[]): string[];
+export declare function buildContext(options?: ContextOptions): ContextResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/context/index.js

@@ -0,0 +1,182 @@
+/**
+ * LLM context bundle builder.
+ *
+ * Composes Flow Weaver documentation, annotation grammar, and a profile-specific
+ * preamble into a single markdown document suitable for LLM consumption.
+ */
+import { readTopic, listTopics } from '../docs/index.js';
+import { getAllGrammars, serializedToEBNF } from '../chevrotain-parser/grammar-diagrams.js';
+// ---------------------------------------------------------------------------
+// Presets
+// ---------------------------------------------------------------------------
+export const PRESETS = {
+    core: ['concepts', 'jsdoc-grammar', 'tutorial'],
+    authoring: [
+        'concepts',
+        'jsdoc-grammar',
+        'advanced-annotations',
+        'built-in-nodes',
+        'scaffold',
+        'node-conversion',
+        'patterns',
+    ],
+    ops: [
+        'cli-reference',
+        'compilation',
+        'deployment',
+        'export-interface',
+        'debugging',
+        'error-codes',
+    ],
+    full: [
+        'concepts',
+        'tutorial',
+        'jsdoc-grammar',
+        'advanced-annotations',
+        'built-in-nodes',
+        'cli-reference',
+        'compilation',
+        'debugging',
+        'deployment',
+        'error-codes',
+        'export-interface',
+        'iterative-development',
+        'marketplace',
+        'node-conversion',
+        'patterns',
+        'scaffold',
+    ],
+};
+export const PRESET_NAMES = Object.keys(PRESETS);
+// ---------------------------------------------------------------------------
+// Preambles
+// ---------------------------------------------------------------------------
+const STANDALONE_PREAMBLE = `# Flow Weaver Reference
+
+Flow Weaver is a TypeScript workflow compiler. You write plain .ts files with
+JSDoc annotations (@flowWeaver nodeType, @flowWeaver workflow, @input, @output,
+@connect, @node, @scope). The compiler parses these annotations, validates the
+graph, and generates executable code inline. The source file is the workflow:
+no JSON configs, no YAML, no separate graph files.
+
+Key concepts: node types define reusable processing steps with typed input/output
+ports. Workflows instantiate nodes and connect their ports. Start and Exit are
+implicit boundary nodes. The compiler handles execution ordering, type checking,
+and code generation.`;
+function buildAssistantPreamble() {
+    const allSlugs = listTopics().map((t) => t.slug);
+    return `# Flow Weaver Context
+
+You have Flow Weaver MCP tools available (fw_ prefix). Use them to create,
+modify, validate, compile, and inspect workflows without manual file editing.
+
+For documentation not included below, call fw_docs(action="read", topic="<slug>").
+Available topic slugs: ${allSlugs.join(', ')}.
+
+Tool quick reference:
+- fw_create_model: Build workflow from structured description (steps + flow path)
+- fw_implement_node: Replace a declare stub with a real function body
+- fw_modify / fw_modify_batch: Add/remove nodes, connections, rename, reposition
+- fw_validate: Check for errors after any change
+- fw_describe: Inspect structure. Use format "text" for readable, "json" for data
+- fw_diagram: Visualize. Prefer format "ascii-compact" in chat contexts
+- fw_compile: Generate executable TypeScript from annotations
+- fw_docs: Look up reference docs by topic slug
+- fw_scaffold: Create from templates (sequential, foreach, ai-agent, etc.)
+
+File conventions: .ts extension, camelCase node names, PascalCase workflow names.`;
+}
+// ---------------------------------------------------------------------------
+// Topic resolution
+// ---------------------------------------------------------------------------
+export function resolveTopics(preset, explicit, add) {
+    const base = explicit ?? PRESETS[preset];
+    const combined = add ? [...base, ...add] : base;
+    // Deduplicate while preserving order
+    return [...new Set(combined)];
+}
+// ---------------------------------------------------------------------------
+// Grammar builder
+// ---------------------------------------------------------------------------
+function buildGrammarSection() {
+    const grammars = getAllGrammars();
+    const allProductions = [
+        ...grammars.port,
+        ...grammars.node,
+        ...grammars.connect,
+        ...grammars.position,
+        ...grammars.scope,
+    ];
+    const ebnf = serializedToEBNF(allProductions);
+    return `## JSDoc Annotation Grammar (EBNF)\n\n\`\`\`ebnf\n${ebnf}\n\`\`\``;
+}
+// ---------------------------------------------------------------------------
+// Main builder
+// ---------------------------------------------------------------------------
+export function buildContext(options = {}) {
+    const profile = options.profile ?? 'standalone';
+    const preset = options.preset ?? 'core';
+    const includeGrammar = options.includeGrammar ?? true;
+    const topicSlugs = resolveTopics(preset, options.topics, options.addTopics);
+    const sections = [];
+    // Preamble
+    if (profile === 'standalone') {
+        sections.push(STANDALONE_PREAMBLE);
+    }
+    else {
+        sections.push(buildAssistantPreamble());
+    }
+    // Grammar
+    if (includeGrammar) {
+        sections.push(buildGrammarSection());
+    }
+    // Topics
+    let topicCount = 0;
+    const includedSlugs = [];
+    for (const slug of topicSlugs) {
+        const doc = readTopic(slug, true);
+        if (!doc)
+            continue;
+        // Compact mode prepends "# Name\ndescription\n" which duplicates our heading.
+        // Strip the leading heading block so we can use our own consistent ## heading.
+        // Then bump all remaining headings down one level so they nest under our ##.
+        let body = doc.content;
+        if (body.startsWith('# ')) {
+            const lines = body.split('\n');
+            // Skip the "# Name" line and the description line that follows it
+            let startLine = 1;
+            if (lines.length > 1 && lines[1].trim() && !lines[1].startsWith('#')) {
+                startLine = 2;
+            }
+            body = lines.slice(startLine).join('\n').replace(/^\n+/, '');
+        }
+        // Bump all headings down one level (# -> ##, ## -> ###, etc.)
+        // so they nest under our ## topic heading. Only transform outside code blocks.
+        const bodyLines = body.split('\n');
+        let inCode = false;
+        for (let i = 0; i < bodyLines.length; i++) {
+            if (bodyLines[i].trimStart().startsWith('```')) {
+                inCode = !inCode;
+                continue;
+            }
+            if (!inCode && bodyLines[i].match(/^#{1,5}\s/)) {
+                bodyLines[i] = '##' + bodyLines[i];
+            }
+        }
+        body = bodyLines.join('\n');
+        const heading = doc.name || slug;
+        sections.push(`## ${heading}\n\n${body}`);
+        topicCount++;
+        includedSlugs.push(slug);
+    }
+    const content = sections.join('\n\n---\n\n');
+    const lineCount = content.split('\n').length;
+    return {
+        content,
+        topicCount,
+        lineCount,
+        topicSlugs: includedSlugs,
+        profile,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/doc-metadata/extractors/mcp-tools.js

@@ -868,6 +868,46 @@ export const MCP_TOOLS = [
         category: 'debug',
         params: [],
     },
+    // Context tools (tools-context.ts)
+    {
+        name: 'fw_context',
+        description: 'Generate a self-contained LLM context bundle with Flow Weaver documentation, grammar, and conventions.',
+        category: 'query',
+        params: [
+            {
+                name: 'preset',
+                type: 'string',
+                description: 'Topic preset: core, authoring, full, or ops',
+                required: false,
+                enum: ['core', 'authoring', 'full', 'ops'],
+            },
+            {
+                name: 'profile',
+                type: 'string',
+                description: 'Output profile: standalone (full dump) or assistant (assumes MCP tools)',
+                required: false,
+                enum: ['standalone', 'assistant'],
+            },
+            {
+                name: 'topics',
+                type: 'string',
+                description: 'Comma-separated topic slugs (overrides preset)',
+                required: false,
+            },
+            {
+                name: 'addTopics',
+                type: 'string',
+                description: 'Comma-separated slugs to add to preset',
+                required: false,
+            },
+            {
+                name: 'includeGrammar',
+                type: 'boolean',
+                description: 'Include EBNF annotation grammar section (default: true)',
+                required: false,
+            },
+        ],
+    },
 ];
 /**
  * Extract MCP tool documentation

package/dist/mcp/server.js

@@ -13,6 +13,7 @@ import { registerDiagramTools } from './tools-diagram.js';
 import { registerDocsTools } from './tools-docs.js';
 import { registerModelTools } from './tools-model.js';
 import { registerDebugTools } from './tools-debug.js';
+import { registerContextTools } from './tools-context.js';
 import { registerResources } from './resources.js';
 import { registerPrompts } from './prompts.js';
 function parseEventFilterFromEnv() {
@@ -76,6 +77,7 @@ export async function startMcpServer(options) {
     registerDocsTools(mcp);
     registerModelTools(mcp);
     registerDebugTools(mcp);
+    registerContextTools(mcp);
     registerResources(mcp, connection, buffer);
     registerPrompts(mcp);
     // Connect transport (only in stdio MCP mode)

package/dist/mcp/tools-context.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerContextTools(mcp: McpServer): void;
+//# sourceMappingURL=tools-context.d.ts.map

package/dist/mcp/tools-context.js

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+import { buildContext } from '../context/index.js';
+import { makeToolResult, makeErrorResult } from './response-utils.js';
+export function registerContextTools(mcp) {
+    mcp.tool('fw_context', 'Generate a self-contained LLM context bundle with Flow Weaver documentation, grammar, and conventions. Use preset="core" for basics, "authoring" for writing workflows, "full" for everything, "ops" for CLI/deployment reference.', {
+        preset: z
+            .enum(['core', 'authoring', 'full', 'ops'])
+            .optional()
+            .default('core')
+            .describe('Topic preset'),
+        profile: z
+            .enum(['standalone', 'assistant'])
+            .optional()
+            .default('assistant')
+            .describe('standalone = full self-contained dump, assistant = assumes MCP tools available'),
+        topics: z
+            .string()
+            .optional()
+            .describe('Comma-separated topic slugs (overrides preset)'),
+        addTopics: z
+            .string()
+            .optional()
+            .describe('Comma-separated slugs to add to preset'),
+        includeGrammar: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe('Include EBNF annotation grammar section'),
+    }, async (args) => {
+        try {
+            const result = buildContext({
+                preset: args.preset,
+                profile: args.profile,
+                topics: args.topics ? args.topics.split(',').map((s) => s.trim()) : undefined,
+                addTopics: args.addTopics ? args.addTopics.split(',').map((s) => s.trim()) : undefined,
+                includeGrammar: args.includeGrammar,
+            });
+            return makeToolResult({
+                profile: result.profile,
+                topicCount: result.topicCount,
+                lineCount: result.lineCount,
+                topicSlugs: result.topicSlugs,
+                content: result.content,
+            });
+        }
+        catch (err) {
+            return makeErrorResult('CONTEXT_ERROR', `fw_context failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+}
+//# sourceMappingURL=tools-context.js.map

package/docs/reference/cli-reference.md

@@ -1,7 +1,7 @@
 ---
 name: CLI Reference
 description: Complete reference for all Flow Weaver CLI commands, flags, and options
-keywords: [cli, commands, compile, validate, strip, run, watch, dev, serve, export, diagram, diff, doctor, init, migrate, marketplace, plugin, grammar, changelog, openapi, pattern, create, templates]
+keywords: [cli, commands, compile, validate, strip, run, watch, dev, serve, export, diagram, diff, doctor, init, migrate, marketplace, plugin, grammar, changelog, openapi, pattern, create, templates, context]
 ---
 
 # CLI Reference
@@ -34,6 +34,7 @@ Complete reference for all `flow-weaver` CLI commands.
 | `changelog` | Generate changelog from git |
 | `market` | Marketplace packages |
 | `plugin` | External plugins |
+| `context` | Generate LLM context bundle |
 | `docs` | Browse reference documentation |
 | `ui` | Send commands to the editor |
 | `listen` | Stream editor events |
@@ -805,6 +806,37 @@ flow-weaver docs search "missing workflow"
 
 ---
 
+### context
+
+Generate a self-contained LLM context bundle from documentation and annotation grammar. Two profiles control the output format: `standalone` produces a complete reference for pasting into any LLM, `assistant` produces a leaner version that assumes MCP tools are available.
+
+```bash
+flow-weaver context [preset] [options]
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--profile <profile>` | `standalone` or `assistant` | `standalone` |
+| `--topics <slugs>` | Comma-separated topic slugs (overrides preset) | — |
+| `--add <slugs>` | Extra topic slugs on top of preset | — |
+| `--no-grammar` | Omit EBNF grammar section | grammar included |
+| `-o, --output <path>` | Write to file instead of stdout | stdout |
+| `--list` | List available presets and exit | — |
+
+Built-in presets: `core` (concepts, grammar, tutorial), `authoring` (concepts, grammar, annotations, built-in nodes, scaffold, node-conversion, patterns), `ops` (CLI, compilation, deployment, export, debugging, error-codes), `full` (all 16 topics).
+
+**Examples:**
+```bash
+flow-weaver context core | pbcopy
+flow-weaver context full -o .flow-weaver-context.md
+flow-weaver context authoring --profile assistant
+flow-weaver context --topics concepts,jsdoc-grammar,error-codes
+flow-weaver context core --add error-codes
+flow-weaver context --list
+```
+
+---
+
 ## Editor Integration
 
 ### ui focus-node

package/package.json

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