@synergenius/flow-weaver 0.33.2 → 0.44.0

package/dist/doc-metadata/index.js

@@ -1,9 +1,2368 @@
-export { extractMcpTools, MCP_TOOLS } from './extractors/mcp-tools.js';
-export { extractCliCommands, CLI_COMMANDS } from './extractors/cli-commands.js';
-export { PLUGIN_DEFINITION_FIELDS, PLUGIN_CAPABILITIES, PLUGIN_COMPONENT_CONFIG_FIELDS, PLUGIN_COMPONENT_AREAS, PLUGIN_UI_KIT_COMPONENTS, } from './extractors/plugin-api.js';
-export { ALL_ANNOTATIONS, PORT_MODIFIERS, NODE_MODIFIERS, } from './extractors/annotations.js';
-export { VALIDATION_CODES } from './extractors/error-codes.js';
-export { extractGrammarEBNF, extractTerminals } from './extractors/grammar-rules.js';
-// Core metadata — data types, strategies, reserved names, templates, package exports
-export { DATA_TYPES, MERGE_STRATEGIES, BRANCHING_STRATEGY_VALUES, EXECUTION_STRATEGY_VALUES, RESERVED_NODE_NAMES, RESERVED_PORT_NAMES, SCOPED_PORT_NAMES, EXECUTION_STRATEGIES, BRANCHING_STRATEGIES, VALID_NODE_COLORS, WORKFLOW_TEMPLATES, NODE_TEMPLATES, PACKAGE_EXPORTS, } from './extractors/core-metadata.js';
-//# sourceMappingURL=index.js.map
+import {
+  nodeTemplates,
+  workflowTemplates
+} from "../chunks/chunk-NDSTGMKR.js";
+import {
+  getAllGrammars,
+  serializedToEBNF
+} from "../chunks/chunk-KMWCCOUJ.js";
+import "../chunks/chunk-QYPORSLO.js";
+import {
+  BRANCHING_STRATEGIES,
+  EXECUTION_STRATEGIES,
+  RESERVED_NODE_NAMES,
+  RESERVED_PORT_NAMES,
+  SCOPED_PORT_NAMES,
+  VALID_NODE_COLORS
+} from "../chunks/chunk-R4QGNK34.js";
+import "../chunks/chunk-SEWDMQ6Q.js";
+
+// src/doc-metadata/extractors/mcp-tools.ts
+var MCP_TOOLS = [
+  {
+    name: "fw_describe",
+    description: "Describe a workflow in LLM-friendly format (nodes, connections, graph, validation).",
+    category: "query",
+    params: [
+      {
+        name: "filePath",
+        type: "string",
+        description: "Path to the workflow .ts file",
+        required: true
+      },
+      {
+        name: "format",
+        type: "string",
+        description: "Output format (default: json). ascii/ascii-compact produce terminal-readable diagrams.",
+        required: false,
+        enum: ["json", "text", "mermaid", "paths", "ascii", "ascii-compact"]
+      },
+      {
+        name: "node",
+        type: "string",
+        description: "Focus on a specific node ID",
+        required: false
+      },
+      {
+        name: "workflowName",
+        type: "string",
+        description: "Specific workflow if file has multiple",
+        required: false
+      }
+    ]
+  },
+  {
+    name: "fw_validate",
+    description: "Validate a workflow file and return errors/warnings.",
+    category: "query",
+    params: [
+      {
+        name: "filePath",
+        type: "string",
+        description: "Path to the workflow file",
+        required: true
+      },
+      {
+        name: "workflowName",
+        type: "string",
+        description: "Specific workflow name (default: every workflow in the file)",
+        required: false
+      },
+      {
+        name: "draft",
+        type: "boolean",
+        description: "Draft mode - suppresses STUB_NODE errors for unimplemented nodes (default: false)",
+        required: false
+      }
+    ]
+  },
+  {
+    name: "fw_compile",
+    description: "Compile a workflow to executable code. Only regenerates code inside @flow-weaver-runtime and @flow-weaver-body marker sections, so user code outside markers is preserved. Set production: true to strip debug instrumentation.",
+    category: "query",
+    params: [
+      {
+        name: "filePath",
+        type: "string",
+        description: "Path to the workflow file",
+        required: true
+      },
+      {
+        name: "write",
+        type: "boolean",
+        description: "Whether to write the output file (default: true)",
+        required: false
+      },
+      {
+        name: "production",
+        type: "boolean",
+        description: "Production mode, meaning no debug events (default: false)",
+        required: false
+      },
+      {
+        name: "workflowName",
+        type: "string",
+        description: "Specific workflow name (default: every workflow in the file)",
+        required: false
+      },
+      {
+        name: "draft",
+        type: "boolean",
+        description: "Draft mode - suppresses STUB_NODE validation errors so partially implemented workflows can compile (default: false)",
+        required: false
+      }
+    ]
+  },
+  {
+    name: "fw_diff",
+    description: "Semantic diff between two workflow files: node type changes, instance changes, connection changes, breaking changes.",
+    category: "query",
+    params: [
+      {
+        name: "file1",
+        type: "string",
+        description: "Path to first workflow file",
+        required: true
+      },
+      {
+        name: "file2",
+        type: "string",
+        description: "Path to second workflow file",
+        required: true
+      },
+      {
+        name: "format",
+        type: "string",
+        description: "Output format (default: text)",
+        required: false,
+        enum: ["text", "json", "compact"]
+      },
+      {
+        name: "workflowName",
+        type: "string",
+        description: "Specific workflow name",
+        required: false
+      }
+    ]
+  },
+  {
+    name: "fw_query",
+    description: `Query workflow structure.  Query types: - nodes: All node instances [{id, nodeType, parent}] - connections: All connections [{from, to}] in "node.port" format. Optional: nodeId to filter. - deps: Direct upstream dependencies [nodeId[]]. Requires: nodeId - dependents: Direct downstream dependents [nodeId[]]. Requires: nodeId - data-deps: Data-only upstream dependencies (excludes control flow). Requires: nodeId - execution-order: Topological sort of main-flow nodes. Scoped nodes are listed separately. - isolated: Nodes with no connections [nodeId[]] - dead-ends: Nodes that don't reach Exit [nodeId[]] - disconnected-outputs: Output ports not connected to anything [{nodeId, ports[]}] - node-types: All node type definitions [{name, functionName, inputs[], outputs[]}]`,
+    category: "query",
+    params: [
+      {
+        name: "filePath",
+        type: "string",
+        description: "Path to the workflow file",
+        required: true
+      },
+      {
+        name: "query",
+        type: "string",
+        description: "Query type",
+        required: true,
+        enum: ["nodes", "connections", "deps", "dependents", "data-deps", "execution-order", "isolated", "dead-ends", "disconnected-outputs", "node-types"]
+      },
+      {
+        name: "nodeId",
+        type: "string",
+        description: "Required for deps/dependents. Optional filter for connections.",
+        required: false
+      },
+      {
+        name: "workflowName",
+        type: "string",
+        description: "Specific workflow name",
+        required: false
+      }
+    ]
+  },
+  {
+    name: "fw_doctor",
+    description: "Check project environment and configuration for flow-weaver compatibility.",
+    category: "query",
+    params: [
+      {
+        name: "directory",
+        type: "string",
+        description: "Directory to check (default: cwd)",
+        required: false
+      }
+    ]
+  },
+  {
+    name: "fw_market_search",
+    description: "Search npm for Flow Weaver marketplace packages (node types, workflows, patterns). Returns package name, version, and description.",
+    category: "query",
+    params: [
+      {
+        name: "query",
+        type: "string",
+        description: "Search query text (optional, omit to browse all)",
+        required: false
+      },
+      {
+        name: "limit",
+        type: "number",
+        description: "Maximum number of results (default: 20)",
+        required: false
+      },
+      {
+        name: "registryUrl",
+        type: "string",
+        description: "Custom registry search URL for private registries (default: public npm)",
+        required: false
+      }
+    ]
+  },
+  {
+    name: "fw_market_list",
+    description: "List installed Flow Weaver marketplace packages in the current project. Shows available node types, workflows, and patterns from each package.",
+    category: "query",
+    params: []
+  },
+  {
+    name: "fw_diagram",
+    description: "Generate a diagram of a workflow. Formats: svg draws the spine (steps in run order, control flow as lanes: failure arms, loop bodies, pulled steps) as a vector image. ascii/ascii-compact/text produce plain text readable in terminal. Provide either filePath (workflow .ts file) or source (inline code).",
+    category: "query",
+    params: [
+      {
+        name: "filePath",
+        type: "string",
+        description: "Path to the workflow .ts file (required if source is not provided)",
+        required: false
+      },
+      {
+        name: "source",
+        type: "string",
+        description: "Inline workflow source code (required if filePath is not provided)",
+        required: false
+      },
+      {
+        name: "outputPath",
+        type: "string",
+        description: "Output file path. If omitted, returns content as text.",
+        required: false
+      },
+      {
+        name: "workflowName",
+        type: "string",
+        description: "Specific workflow name if file has multiple",
+        required: false
+      },
+      {
+        name: "theme",
+        type: "string",
+        description: "Color theme (default: dark)",
+        required: false,
+        enum: ["dark", "light"]
+      },
+      {
+        name: "format",
+        type: "string",
+        description: "Output format: svg (the default, drawing the spine as a vector image), ascii (port-level detail), ascii-compact (compact boxes), text (structured list)",
+        required: false,
+        enum: ["svg", "ascii", "ascii-compact", "text"]
+      }
+    ]
+  },
+  {
+    name: "fw_docs",
+    description: '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.',
+    category: "query",
+    params: [
+      {
+        name: "action",
+        type: "string",
+        description: "What to do: list topics, read a topic, or search",
+        required: true,
+        enum: ["list", "read", "search"]
+      },
+      {
+        name: "topic",
+        type: "string",
+        description: 'Topic slug to read (for action="read")',
+        required: false
+      },
+      {
+        name: "query",
+        type: "string",
+        description: 'Search query (for action="search")',
+        required: false
+      },
+      {
+        name: "compact",
+        type: "boolean",
+        description: "Return compact LLM-friendly version (default: false)",
+        required: false
+      },
+      {
+        name: "limit",
+        type: "number",
+        description: 'Number of search hits to return (for action="search")',
+        required: false
+      }
+    ]
+  },
+  {
+    name: "fw_context",
+    description: 'Flow Weaver orientation as markdown: the model, the tool loop, which topic answers which task, and every other topic with its size. preset="core" (default) is that map; "authoring", "ops" and "full" bundle whole references.',
+    category: "query",
+    params: [
+      {
+        name: "preset",
+        type: "string",
+        description: "Topic preset",
+        required: false,
+        enum: ["core", "authoring", "full", "ops"]
+      },
+      {
+        name: "profile",
+        type: "string",
+        description: "standalone = full self-contained dump, assistant = assumes MCP tools available",
+        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: "Append the generated EBNF grammar (~3 KB), off by default",
+        required: false
+      }
+    ]
+  },
+  {
+    name: "fw_list_resources",
+    description: "List available icons, colors, and annotation tags for use in workflow definitions.",
+    category: "query",
+    params: [
+      {
+        name: "type",
+        type: "string",
+        description: "Resource type to list (default: all)",
+        required: false,
+        enum: ["icons", "colors", "tags", "all"]
+      }
+    ]
+  },
+  {
+    name: "fw_modify",
+    description: "Modify a workflow file: add/remove/rename nodes, add/remove connections, set labels. Parses the file, applies the mutation, and regenerates annotations in-place. Returns auto-validation results and a text description of the updated workflow.",
+    category: "modify",
+    params: [
+      {
+        name: "filePath",
+        type: "string",
+        description: "Path to the workflow file",
+        required: true
+      },
+      {
+        name: "workflowName",
+        type: "string",
+        description: "Specific workflow if file has multiple",
+        required: false
+      },
+      {
+        name: "operation",
+        type: "string",
+        description: "The mutation to perform",
+        required: true,
+        enum: ["addNode", "removeNode", "renameNode", "addConnection", "removeConnection", "setNodeLabel"]
+      },
+      {
+        name: "params",
+        type: "object",
+        description: 'Operation-specific parameters. addNode: {nodeId, nodeType}. removeNode: {nodeId}. renameNode: {oldId, newId}. addConnection: {from, to} ("node.port" format). removeConnection: {from, to} ("node.port" format). setNodeLabel: {nodeId, label}.',
+        required: true
+      },
+      {
+        name: "preview",
+        type: "boolean",
+        description: "Preview without writing (default: false)",
+        required: false
+      }
+    ]
+  },
+  {
+    name: "fw_modify_batch",
+    description: "Apply multiple modify operations in a single parse/write/validate cycle. More efficient than calling fw_modify multiple times.",
+    category: "modify",
+    params: [
+      {
+        name: "filePath",
+        type: "string",
+        description: "Path to the workflow file",
+        required: true
+      },
+      {
+        name: "workflowName",
+        type: "string",
+        description: "Specific workflow if file has multiple",
+        required: false
+      },
+      {
+        name: "operations",
+        type: "array",
+        description: "Array of operations to apply sequentially",
+        required: true
+      },
+      {
+        name: "preview",
+        type: "boolean",
+        description: "Preview without writing (default: false)",
+        required: false
+      }
+    ]
+  },
+  {
+    name: "fw_migrate",
+    description: "Migrate workflow files to current syntax via parse \u2192 regenerate round-trip. The parser adds defaults for missing fields, edge-case migrations transform the AST, and generateInPlace writes current syntax back.",
+    category: "modify",
+    params: [
+      {
+        name: "glob",
+        type: "string",
+        description: 'Glob pattern for workflow files to migrate (e.g., "src/**/*.ts")',
+        required: true
+      },
+      {
+        name: "dryRun",
+        type: "boolean",
+        description: "Preview changes without writing files (default: false)",
+        required: false
+      }
+    ]
+  },
+  {
+    name: "fw_market_install",
+    description: "Install a Flow Weaver marketplace package via npm. After installation, the package's node types, workflows, and patterns become available for use.",
+    category: "modify",
+    params: [
+      {
+        name: "package",
+        type: "string",
+        description: 'Package name or specifier (e.g., "flow-weaver-pack-openai" or "flow-weaver-pack-openai@1.0.0")',
+        required: true
+      }
+    ]
+  },
+  {
+    name: "fw_list_templates",
+    description: "List available scaffold templates for workflows and nodes.",
+    category: "template",
+    params: [
+      {
+        name: "type",
+        type: "string",
+        description: "Filter template type (default: all)",
+        required: false,
+        enum: ["workflow", "node", "all"]
+      }
+    ]
+  },
+  {
+    name: "fw_scaffold",
+    description: "Create a workflow or node from a template.",
+    category: "template",
+    params: [
+      {
+        name: "template",
+        type: "string",
+        description: 'Template name (e.g. "sequential", "validator", "ai-agent"). An existing filePath gets the code appended',
+        required: true
+      },
+      {
+        name: "filePath",
+        type: "string",
+        description: "Output file path",
+        required: true
+      },
+      {
+        name: "name",
+        type: "string",
+        description: "Workflow/node function name",
+        required: false
+      },
+      {
+        name: "preview",
+        type: "boolean",
+        description: "Preview only, returning generated code without writing (default: false)",
+        required: false
+      },
+      {
+        name: "config",
+        type: "object",
+        description: 'Template configuration (e.g. { nodes: ["fetch", "parse"], input: "rawData" })',
+        required: false
+      }
+    ]
+  },
+  {
+    name: "fw_find_workflows",
+    description: "Scan a directory for workflow files containing @flowWeaver workflow annotations. Returns file paths and workflow metadata.",
+    category: "query",
+    params: [
+      {
+        name: "directory",
+        type: "string",
+        description: "Directory to search for workflow files",
+        required: true
+      },
+      {
+        name: "pattern",
+        type: "string",
+        description: "Glob pattern (default: **/*.ts)",
+        required: false
+      }
+    ]
+  },
+  {
+    name: "fw_export",
+    description: "Export a workflow to a target an installed pack provides: handler code, the target's config files and deploy instructions. Without a target pack installed there is nothing to export to.",
+    category: "execution",
+    params: [
+      {
+        name: "filePath",
+        type: "string",
+        description: "Path to the workflow .ts file",
+        required: true
+      },
+      {
+        name: "target",
+        type: "string",
+        description: "Deployment target name. Targets come from installed packs. An unknown name returns INVALID_TARGET listing the installed ones.",
+        required: true
+      },
+      {
+        name: "outputDir",
+        type: "string",
+        description: "Output directory for generated files (default: ./dist relative to workflow)",
+        required: false
+      },
+      {
+        name: "serviceName",
+        type: "string",
+        description: "Service name (default: derived from filename)",
+        required: false
+      },
+      {
+        name: "workflows",
+        type: "array",
+        description: "Specific workflow function names to include (default: all)",
+        required: false
+      },
+      {
+        name: "nodeTypes",
+        type: "array",
+        description: "Specific node type names to include",
+        required: false
+      },
+      {
+        name: "includeDocs",
+        type: "boolean",
+        description: "Include OpenAPI/Swagger routes (default: false, as fw export --docs)",
+        required: false
+      },
+      {
+        name: "production",
+        type: "boolean",
+        description: "Production code without debug events (default: false, as fw export --production)",
+        required: false
+      },
+      {
+        name: "preview",
+        type: "boolean",
+        description: "Preview without writing files to disk (default: false)",
+        required: false
+      },
+      {
+        name: "durableSteps",
+        type: "boolean",
+        description: "Use deep generator with per-node durable steps",
+        required: false
+      }
+    ]
+  },
+  {
+    name: "fw_run",
+    description: "Run a workflow. Returns the result, or pauses at the first gate and returns {runId, gate}. Continue with fw_resume.",
+    category: "execution",
+    params: [
+      {
+        name: "filePath",
+        type: "string",
+        description: "Workflow .ts file",
+        required: true
+      },
+      {
+        name: "workflowName",
+        type: "string",
+        description: "Export name if the file has several",
+        required: false
+      },
+      {
+        name: "params",
+        type: "object",
+        description: "Workflow input parameters",
+        required: false
+      }
+    ]
+  },
+  {
+    name: "fw_resume",
+    description: "Continue a paused run. Give exactly one of answer (the gate's result) or reject (a reason).",
+    category: "execution",
+    params: [
+      {
+        name: "runId",
+        type: "string",
+        description: "Run id returned by fw_run",
+        required: true
+      },
+      {
+        name: "answer",
+        type: "object",
+        description: "For a single-output gate, the value. For multi-output, an object with every output (any JSON value)",
+        required: false
+      },
+      {
+        name: "reject",
+        type: "string",
+        description: "Fail the gate with this reason",
+        required: false
+      }
+    ]
+  },
+  {
+    name: "fw_runs",
+    description: "List runs, or inspect one. With runId returns the full gate so you can re-read a pause without resuming.",
+    category: "execution",
+    params: [
+      {
+        name: "runId",
+        type: "string",
+        description: "Inspect one run in full",
+        required: false
+      },
+      {
+        name: "filePath",
+        type: "string",
+        description: "Only runs of this workflow file",
+        required: false
+      },
+      {
+        name: "status",
+        type: "string",
+        description: "Only runs in this state. waiting is the one that needs you",
+        required: false,
+        enum: ["waiting", "completed", "failed", "cancelled"]
+      },
+      {
+        name: "limit",
+        type: "number",
+        description: "How many, newest first. Default 20, at most 200",
+        required: false
+      }
+    ]
+  },
+  {
+    name: "fw_debug_workflow",
+    description: "Start a step-through debug session for a workflow. Compiles and executes the workflow, pausing before the first node. Returns a debugId and the initial pause state.",
+    category: "debug",
+    params: [
+      {
+        name: "filePath",
+        type: "string",
+        description: "Path to the workflow .ts file",
+        required: true
+      },
+      {
+        name: "workflowName",
+        type: "string",
+        description: "Specific workflow function name (for multi-workflow files)",
+        required: false
+      },
+      {
+        name: "params",
+        type: "object",
+        description: "Parameters to pass to the workflow",
+        required: false
+      },
+      {
+        name: "breakpoints",
+        type: "array",
+        description: "Node IDs to set as initial breakpoints",
+        required: false
+      }
+    ]
+  },
+  {
+    name: "fw_debug_step",
+    description: "Step to the next node in a debug session. Executes one node then pauses again.",
+    category: "debug",
+    params: [
+      {
+        name: "debugId",
+        type: "string",
+        description: "The debug session ID from fw_debug_workflow",
+        required: true
+      }
+    ]
+  },
+  {
+    name: "fw_debug_continue",
+    description: "Continue execution from the current pause point. Runs to completion, or stops at the next breakpoint if toBreakpoint is true.",
+    category: "debug",
+    params: [
+      {
+        name: "debugId",
+        type: "string",
+        description: "The debug session ID",
+        required: true
+      },
+      {
+        name: "toBreakpoint",
+        type: "boolean",
+        description: "If true, pause at the next breakpoint instead of running to completion",
+        required: false
+      }
+    ]
+  },
+  {
+    name: "fw_debug_inspect",
+    description: "Inspect the current debug state without advancing execution. Returns all variables, or filter to a specific node.",
+    category: "debug",
+    params: [
+      {
+        name: "debugId",
+        type: "string",
+        description: "The debug session ID",
+        required: true
+      },
+      {
+        name: "nodeId",
+        type: "string",
+        description: "Filter to show only this node's variables",
+        required: false
+      }
+    ]
+  },
+  {
+    name: "fw_debug_set_variable",
+    description: "Modify a variable value in the debug session. The new value will be used by downstream nodes when execution continues.",
+    category: "debug",
+    params: [
+      {
+        name: "debugId",
+        type: "string",
+        description: "The debug session ID",
+        required: true
+      },
+      {
+        name: "nodeId",
+        type: "string",
+        description: "The node that produced the variable",
+        required: true
+      },
+      {
+        name: "portName",
+        type: "string",
+        description: "The output port name",
+        required: true
+      },
+      {
+        name: "value",
+        type: "object",
+        description: "The new value to set (any JSON value)",
+        required: true
+      },
+      {
+        name: "executionIndex",
+        type: "number",
+        description: "Execution index (defaults to the latest)",
+        required: false
+      }
+    ]
+  },
+  {
+    name: "fw_debug_breakpoint",
+    description: "Add, remove, or list breakpoints in a debug session. Breakpoints cause execution to pause when running with fw_debug_continue(toBreakpoint: true).",
+    category: "debug",
+    params: [
+      {
+        name: "debugId",
+        type: "string",
+        description: "The debug session ID",
+        required: true
+      },
+      {
+        name: "action",
+        type: "string",
+        description: "Action to perform",
+        required: true,
+        enum: ["add", "remove", "list"]
+      },
+      {
+        name: "nodeId",
+        type: "string",
+        description: "Node ID for add/remove (not needed for list)",
+        required: false
+      }
+    ]
+  },
+  {
+    name: "fw_list_debug_sessions",
+    description: "List all active debug sessions.",
+    category: "debug",
+    params: []
+  }
+];
+function extractMcpTools() {
+  return MCP_TOOLS;
+}
+
+// src/doc-metadata/extractors/cli-commands.ts
+var CLI_COMMANDS = [
+  // ── Core commands ──────────────────────────────────────────────
+  {
+    name: "compile",
+    syntax: "fw compile <file> [options]",
+    description: "Compile workflow source file",
+    botCompatible: true,
+    options: [
+      { flags: "-o, --output", arg: "<path>", description: "Output file or directory" },
+      { flags: "-p, --production", description: "Production build (no debug events)" },
+      { flags: "-s, --source-map", description: "Generate source maps" },
+      { flags: "-w, --workflow", arg: "<name>", description: "Compile only this workflow (default: every workflow in the file)" },
+      { flags: "-f, --format", arg: "esm|cjs|auto", description: "Module format", defaultValue: "auto" },
+      { flags: "--strict", description: "Treat type coercion warnings as errors" },
+      { flags: "--clean", description: "Omit redundant @param/@returns annotations from compiled output" },
+      { flags: "--dry-run", description: "Preview compilation without writing files" },
+      { flags: "--verbose", description: "Detailed output" }
+    ]
+  },
+  {
+    name: "validate",
+    syntax: "fw validate <file> [options]",
+    description: "Validate workflow without compiling",
+    botCompatible: true,
+    options: [
+      { flags: "-w, --workflow", arg: "<name>", description: "Validate only this workflow (default: every workflow in the file)" },
+      { flags: "--json", description: "Output as JSON", exclusive: "output-mode" },
+      { flags: "--verbose", description: "Verbose output", exclusive: "output-mode" },
+      { flags: "-q, --quiet", description: "Suppress warnings", exclusive: "output-mode" },
+      { flags: "--strict", description: "Treat type coercion warnings as errors" }
+    ]
+  },
+  {
+    name: "describe",
+    syntax: "fw describe <file> [options]",
+    description: "Output workflow structure in LLM-friendly formats (JSON, text, mermaid)",
+    botCompatible: true,
+    options: [
+      { flags: "-f, --format", arg: "json|text|mermaid|paths|ascii|ascii-compact", description: "Output format (paths: enumerate all Start-to-Exit paths via DFS; ascii: a terminal diagram)" },
+      { flags: "-w, --workflow", arg: "<name>", description: "Target workflow" },
+      { flags: "-n, --node", arg: "<id>", description: "Focus on specific node" },
+      { flags: "--compile", description: "Also update runtime markers in the source file" }
+    ]
+  },
+  {
+    name: "run",
+    syntax: "fw run <file> [options]",
+    description: "Execute a workflow file directly",
+    botCompatible: true,
+    options: [
+      { flags: "-w, --workflow", arg: "<name>", description: "Specific workflow to run" },
+      { flags: "--params", arg: "<json>", description: "Input parameters as JSON string", exclusive: "params" },
+      { flags: "--params-file", arg: "<path>", description: "Path to JSON file with input parameters", exclusive: "params" },
+      { flags: "-p, --production", description: "Production mode (no trace events)" },
+      { flags: "-t, --trace", description: "Include execution trace events" },
+      { flags: "-s, --stream", description: "Stream trace events in real time" },
+      { flags: "--json", description: "Output result as JSON" },
+      { flags: "--timeout", arg: "<ms>", description: "Execution timeout in milliseconds" },
+      { flags: "--mocks", arg: "<json>", description: "Mock config as JSON: gates (answers by node id), events, agents, invocations, fast", exclusive: "mocks" },
+      { flags: "--mocks-file", arg: "<path>", description: "Path to JSON file with mock config for built-in nodes", exclusive: "mocks" },
+      { flags: "-d, --debug", description: "Start in step-through debug mode" },
+      { flags: "-b, --breakpoint", arg: "<nodeIds...>", description: "Set initial breakpoints (repeatable)" }
+    ]
+  },
+  {
+    name: "serve",
+    syntax: "fw serve [directory] [options]",
+    description: "Serve the workflows as HTTP endpoints. Gated runs pause, resume and stream over the same API",
+    options: [
+      { flags: "-p, --port", arg: "<port>", description: "Server port", defaultValue: "3000" },
+      { flags: "-H, --host", arg: "<host>", description: "Server host. Beyond loopback it needs --token or --insecure", defaultValue: "127.0.0.1" },
+      { flags: "--token", arg: "<token>", description: "Bearer token every request must carry (also FW_SERVE_TOKEN)" },
+      { flags: "--no-agents", description: "Do not answer agent gates from .flowweaver/agents.yaml" },
+      { flags: "--trace", description: "Keep a step trace for every run and stream it on /runs/:id/events" },
+      { flags: "--dev", description: "Error stacks in responses, and mocks accepted when starting a run" },
+      { flags: "--insecure", description: "Listen beyond loopback without a token" },
+      { flags: "--no-watch", description: "Disable file watching for hot reload" },
+      { flags: "--cors", arg: "<origin>", description: "Send CORS headers for this origin" },
+      { flags: "--swagger", description: "Enable Swagger UI at /docs" },
+      { flags: "--production", description: "Deprecated: the same as leaving --trace off" }
+    ]
+  },
+  // ── Create subcommands ─────────────────────────────────────────
+  {
+    name: "create workflow",
+    syntax: "fw create workflow <template> <file> [options]",
+    description: "Create new workflow from template",
+    botCompatible: true,
+    group: "create",
+    positionalChoices: {
+      template: workflowTemplates.map((t) => ({ id: t.id, label: t.id }))
+    },
+    options: [
+      { flags: "-p, --preview", description: "Show without writing" },
+      { flags: "--provider", arg: "openai|anthropic|ollama|mock", description: "LLM provider" },
+      { flags: "--model", arg: "<model>", description: "Model identifier" },
+      { flags: "--name", arg: "<name>", description: "Override derived function name" },
+      { flags: "--nodes", arg: "<names>", description: "Comma-separated node function names" },
+      { flags: "--config", arg: "<json>", description: "Configuration as JSON string" },
+      { flags: "--input", arg: "<name>", description: "Custom input port name", defaultValue: "data" },
+      { flags: "--output", arg: "<name>", description: "Custom output port name", defaultValue: "result" },
+      { flags: "-l, --line", arg: "<number>", description: "Insert at specific line number" },
+      { flags: "-a, --async", description: "Generate an async workflow" }
+    ]
+  },
+  {
+    name: "create node",
+    syntax: "fw create node <name> <file> [options]",
+    description: "Create a node type from template",
+    botCompatible: true,
+    group: "create",
+    options: [
+      { flags: "-t, --template", arg: nodeTemplates.map((t) => t.id).join("|"), description: "Node template to use", defaultValue: "transformer" },
+      { flags: "-p, --preview", description: "Preview generated code without writing" },
+      { flags: "-l, --line", arg: "<number>", description: "Insert at specific line number" }
+    ]
+  },
+  // ── Templates (generated from registries) ──────────────────────
+  {
+    name: "templates",
+    syntax: "fw templates [--json]",
+    description: `List available workflow templates (${workflowTemplates.length} total)`,
+    botCompatible: true,
+    listStyle: "definition",
+    options: [
+      { flags: "--json", description: "Output as JSON" }
+    ],
+    list: workflowTemplates.map((t) => `${t.id} - ${t.description}`)
+  },
+  {
+    name: "Node Templates",
+    syntax: "fw create node <name> <file> --template <type>",
+    description: `Create node types from templates (${nodeTemplates.length} total)`,
+    listStyle: "definition",
+    options: [],
+    list: nodeTemplates.map((t) => `${t.id} - ${t.description}`)
+  },
+  // ── Project & dev commands ─────────────────────────────────────
+  {
+    name: "init",
+    syntax: "fw init [directory] [options]",
+    description: "Create a new flow-weaver project with templates and config",
+    options: [
+      { flags: "-n, --name", arg: "<name>", description: "Project name (defaults to directory name)" },
+      { flags: "-t, --template", arg: workflowTemplates.map((t) => t.id).join("|"), description: "Workflow template", defaultValue: "sequential" },
+      { flags: "-f, --format", arg: "esm|cjs", description: "Module format", defaultValue: "esm" },
+      { flags: "-y, --yes", description: "Skip prompts, use defaults" },
+      { flags: "--preset", arg: "nocode|vibecoder|lowcode|expert", description: "User preset" },
+      { flags: "--use-case", arg: "data|ai|api|automation|minimal", description: "Use case" },
+      { flags: "--mcp / --no-mcp", description: "Configure MCP for AI editors after scaffolding, or skip the prompt" },
+      { flags: "--no-agent", description: "Skip the post-init agent launch prompt" },
+      { flags: "--install / --no-install", description: "Run npm install after scaffolding" },
+      { flags: "--git / --no-git", description: "Initialize a git repository" },
+      { flags: "--force", description: "Overwrite existing files" },
+      { flags: "--json", description: "Output a report as JSON" }
+    ]
+  },
+  {
+    name: "watch",
+    syntax: "fw watch <file> [options]",
+    description: "Watch workflow files and recompile on changes",
+    options: [
+      { flags: "-o, --output", arg: "<path>", description: "Output file or directory" },
+      { flags: "-p, --production", description: "Production build (no debug events)" },
+      { flags: "-s, --source-map", description: "Generate source maps" },
+      { flags: "-w, --workflow", arg: "<name>", description: "Target specific workflow" },
+      { flags: "-f, --format", arg: "esm|cjs|auto", description: "Module format", defaultValue: "auto" },
+      { flags: "--verbose", description: "Detailed output" }
+    ]
+  },
+  {
+    name: "doctor",
+    syntax: "fw doctor [--json]",
+    description: "Check project environment and configuration. Validates Node.js version, TypeScript, package installation, and tsconfig.json settings.",
+    botCompatible: true,
+    options: [
+      { flags: "--json", description: "Output results as JSON" }
+    ]
+  },
+  {
+    name: "agents",
+    syntax: "fw agents [directory] [--init] [--json]",
+    description: "The agent profiles in .flowweaver/agents.yaml that answer agent gates, whether each is ready, and the gate mapping. --init writes the starter file.",
+    botCompatible: true,
+    options: [
+      { flags: "--init", description: "Write the starter .flowweaver/agents.yaml" },
+      { flags: "--force", description: "With --init: replace an existing file" },
+      { flags: "--json", description: "Output as JSON" }
+    ]
+  },
+  // ── Context ─────────────────────────────────────────────────────
+  {
+    name: "context",
+    syntax: "fw context [preset] [options]",
+    description: "Generate LLM context bundle from documentation and grammar",
+    botCompatible: true,
+    options: [
+      { flags: "--profile", arg: "standalone|assistant", description: "Output profile", defaultValue: "standalone" },
+      { flags: "--topics", arg: "<slugs>", description: "Comma-separated topic slugs (overrides preset)" },
+      { flags: "--add", arg: "<slugs>", description: "Extra topic slugs to add to preset" },
+      { flags: "--no-grammar", description: "Omit EBNF grammar section" },
+      { flags: "-o, --output", arg: "<path>", description: "Write to file instead of stdout" },
+      { flags: "--list", description: "List available presets and exit" }
+    ],
+    positionalChoices: {
+      preset: [
+        { id: "core", label: "core" },
+        { id: "authoring", label: "authoring" },
+        { id: "ops", label: "ops" },
+        { id: "full", label: "full" }
+      ]
+    }
+  },
+  // ── Export & generation ────────────────────────────────────────
+  {
+    name: "export",
+    syntax: "fw export <file> -t <target> -o <path> [options]",
+    description: "Export a workflow to a target provided by an installed pack",
+    botCompatible: true,
+    options: [
+      { flags: "-t, --target", arg: "<target>", description: "Target platform (provided by installed packs)", required: true },
+      { flags: "-o, --output", arg: "<path>", description: "Output directory", required: true },
+      { flags: "-w, --workflow", arg: "<name>", description: "Specific workflow to export" },
+      { flags: "-p, --production", description: "Production mode (no debug events)", defaultValue: "false" },
+      { flags: "--bundle", description: "Bundle node types into the output" },
+      { flags: "--multi", description: "Export all workflows as single multi-workflow service" },
+      { flags: "--workflows", arg: "<names>", description: "Comma-separated workflow subset (with --multi)" },
+      { flags: "--docs", description: "Include API documentation routes (/docs, /openapi.json)" },
+      { flags: "--durable-steps", description: "Use deep generator with per-node durable steps" },
+      { flags: "--dry-run", description: "Preview without writing files" }
+    ]
+  },
+  {
+    name: "diff",
+    syntax: "fw diff <file1> <file2> [options]",
+    description: "Semantic diff between two workflow files",
+    botCompatible: true,
+    options: [
+      { flags: "-f, --format", arg: "text|json|compact", description: "Output format", defaultValue: "text" },
+      { flags: "-w, --workflow", arg: "<name>", description: "Specific workflow to compare" },
+      { flags: "--exit-zero", description: "Exit 0 even when differences are found" }
+    ]
+  },
+  {
+    name: "openapi",
+    syntax: "fw openapi <directory> [options]",
+    description: "Generate the OpenAPI specification fw serve publishes: declared @http routes, run resources, run endpoints",
+    options: [
+      { flags: "-o, --output", arg: "<path>", description: "Output file path" },
+      { flags: "--title", arg: "<title>", description: "API title", defaultValue: "Flow Weaver API" },
+      { flags: "--version", arg: "<version>", description: "API version", defaultValue: "1.0.0" },
+      { flags: "--description", arg: "<desc>", description: "API description" },
+      { flags: "-f, --format", arg: "json|yaml", description: "Output format", defaultValue: "json" },
+      { flags: "--server", arg: "<url>", description: "Server URL" },
+      { flags: "--no-auth", description: "Leave out the bearer scheme, for a server without a token" },
+      { flags: "--no-legacy", description: "Leave out POST /workflows/<name>, keeping declared @http routes only" }
+    ]
+  },
+  {
+    name: "grammar",
+    syntax: "fw grammar [options]",
+    description: "Output JSDoc annotation grammar specification",
+    options: [
+      { flags: "-f, --format", arg: "html|ebnf", description: "Output format", defaultValue: "html" },
+      { flags: "-o, --output", arg: "<path>", description: "Write output to file instead of stdout" }
+    ]
+  },
+  // ── Integration commands ───────────────────────────────────────
+  {
+    name: "mcp-server",
+    syntax: "fw mcp-server [options]",
+    description: "Start MCP server for Claude Code integration",
+    options: [
+      { flags: "--stdio", description: "Run in MCP stdio mode (skip interactive registration)" }
+    ]
+  },
+  // ── Migration & changelog ──────────────────────────────────────
+  {
+    name: "migrate",
+    syntax: "fw migrate <glob> [options]",
+    description: "Migrate workflow files to current syntax via parse \u2192 regenerate round-trip",
+    botCompatible: true,
+    options: [
+      { flags: "--dry-run", description: "Preview changes without writing files" },
+      { flags: "--diff", description: "Show semantic diff before/after" }
+    ]
+  }
+];
+function extractCliCommands() {
+  return CLI_COMMANDS;
+}
+
+// src/doc-metadata/extractors/annotations.ts
+var CORE_ANNOTATIONS = [
+  {
+    name: "@flowWeaver",
+    category: "marker",
+    syntax: "@flowWeaver nodeType | workflow",
+    description: "Required marker to identify function purpose. Must be first Flow Weaver annotation.",
+    insertText: "@flowWeaver ",
+    insertTextFormat: "plain",
+    ebnf: 'flowWeaverTag  ::= "@flowWeaver" ( "nodeType" | "workflow" )',
+    contexts: ["nodeType", "workflow"]
+  },
+  {
+    name: "@flowWeaver nodeType",
+    category: "marker",
+    syntax: "@flowWeaver nodeType",
+    description: "Marks function as a reusable node type that can be instantiated in workflows.",
+    insertText: "@flowWeaver nodeType",
+    insertTextFormat: "plain",
+    contexts: ["nodeType"]
+  },
+  {
+    name: "@flowWeaver workflow",
+    category: "marker",
+    syntax: "@flowWeaver workflow",
+    description: "Marks function as a DAG workflow orchestration.",
+    insertText: "@flowWeaver workflow",
+    insertTextFormat: "plain",
+    contexts: ["workflow"]
+  }
+];
+var PORT_ANNOTATIONS = [
+  {
+    name: "@input",
+    category: "port",
+    syntax: "@input name [modifiers] - description",
+    description: "Declares an input port for data or control flow. Name required, modifiers in brackets optional (e.g. [type:NUMBER]).",
+    insertText: "@input ${1:name}",
+    insertTextFormat: "snippet",
+    ebnf: `inputTag       ::= "@input" ( bracketedInput | plainInput )
+                   [ scopeClause ] { metadataBracket } [ descriptionClause ]
+
+plainInput     ::= IDENTIFIER
+bracketedInput ::= "[" IDENTIFIER [ "=" defaultValue ] "]"
+
+defaultValue   ::= IDENTIFIER | INTEGER | STRING`,
+    examples: [
+      "@input name                       plain required input",
+      "@input [name]                     optional input (no connection required)",
+      "@input [name=defaultValue]        optional with default (identifier)",
+      "@input [name=42]                  optional with default (integer)",
+      '@input [name="hello"]             optional with default (string)',
+      "@input name scope:myScope         scoped input",
+      "@input name [order:2]             with ordering metadata",
+      "@input name - Short Label         the dash text is the port label (1-2 words), shown in the diagram badge"
+    ],
+    contexts: ["nodeType"]
+  },
+  {
+    name: "@output",
+    category: "port",
+    syntax: "@output name [modifiers] - description",
+    description: "Declares an output port for data or control flow. Name required, modifiers in brackets optional (e.g. [type:NUMBER]).",
+    insertText: "@output ${1:name}",
+    insertTextFormat: "snippet",
+    ebnf: `outputTag      ::= "@output" IDENTIFIER
+                   [ scopeClause ] { metadataBracket } [ descriptionClause ]`,
+    examples: [
+      "@output result",
+      "@output result scope:myScope",
+      "@output result [order:1, placement:TOP]",
+      "@output result - The computed result"
+    ],
+    contexts: ["nodeType"]
+  },
+  {
+    name: "@step",
+    category: "port",
+    syntax: "@step name - description",
+    description: "Declares a STEP port for control flow. Shorthand for @input name [type:STEP] or @output name [type:STEP].",
+    insertText: "@step ${1:name}",
+    insertTextFormat: "snippet",
+    ebnf: 'stepTag        ::= "@step" IDENTIFIER [ descriptionClause ]',
+    examples: ["@step process", "@step process - Runs the processing pipeline"],
+    contexts: ["nodeType"]
+  }
+];
+var WORKFLOW_ANNOTATIONS = [
+  {
+    name: "@node",
+    category: "workflow",
+    syntax: "@node instanceId NodeTypeName [parent.scope] [modifiers]",
+    description: "Declares a node instance in the workflow. Can optionally specify parent scope and modifiers.",
+    insertText: "@node ${1:id} ${2:NodeType}",
+    insertTextFormat: "snippet",
+    ebnf: `nodeTag        ::= "@node" IDENTIFIER IDENTIFIER [ parentScopeRef ] { attributeBracket }
+
+parentScopeRef ::= IDENTIFIER "." IDENTIFIER
+
+attributeBracket ::= "[" nodeAttr { "," nodeAttr } "]"
+
+nodeAttr       ::= labelAttr | exprAttr | portOrderAttr | portLabelAttr
+                 | minimizedAttr | pullExecutionAttr | sizeAttr
+                 | colorAttr | iconAttr | tagsAttr | customAttr
+
+customAttr     ::= IDENTIFIER ":" STRING
+labelAttr      ::= "label:" STRING
+exprAttr       ::= "expr:" IDENTIFIER "=" STRING { "," IDENTIFIER "=" STRING }
+portOrderAttr  ::= "portOrder:" IDENTIFIER "=" INTEGER { "," IDENTIFIER "=" INTEGER }
+portLabelAttr  ::= "portLabel:" IDENTIFIER "=" STRING { "," IDENTIFIER "=" STRING }
+minimizedAttr  ::= "minimized"
+pullExecutionAttr ::= "pullExecution:" IDENTIFIER
+sizeAttr       ::= "size:" INTEGER INTEGER
+colorAttr      ::= "color:" STRING
+iconAttr       ::= "icon:" STRING
+tagsAttr       ::= "tags:" tagEntry { "," tagEntry }
+tagEntry       ::= STRING [ STRING ]`,
+    examples: [
+      "@node myAdd Add",
+      '@node myAdd Add [label: "My Adder"]',
+      "@node myAdd Add parent.loopScope",
+      '@node myAdd Add [expr: a="x + 1", b="y * 2"]',
+      '@node myAdd Add [expr: a="Start.value + 1", b="scale.factor * 2"]',
+      "@node myAdd Add [portOrder: a=1, b=2]",
+      '@node myAdd Add [minimized, label: "Compact"]',
+      "@node myAdd Add [pullExecution: trigger]",
+      "@node myAdd Add [size: 200 150]",
+      '@node myAdd Add [color: "#ff0000", icon: "math-plus"]',
+      '@node myAdd Add [tags: "math" "Math operation", "transform"]',
+      '@node myAdd Add [label: "hi"] [color: "#f00"]'
+    ],
+    contexts: ["workflow"]
+  },
+  {
+    name: "@connect",
+    category: "workflow",
+    syntax: "@connect sourceNode.outPort -> targetNode.inPort",
+    description: "Connects an output port to an input port. Use arrow syntax for directionality.",
+    insertText: "@connect ${1:from}.${2:port} -> ${3:to}.${4:port}",
+    insertTextFormat: "snippet",
+    ebnf: `connectTag     ::= "@connect" portRef "->" portRef
+
+portRef        ::= IDENTIFIER "." IDENTIFIER [ ":" IDENTIFIER ]`,
+    examples: [
+      "@connect myAdd.result -> myLog.message",
+      "@connect loop.item -> process.input:loopScope"
+    ],
+    contexts: ["workflow"]
+  },
+  {
+    name: "@fwImport",
+    category: "workflow",
+    syntax: '@fwImport nodeName functionName from "packageName"',
+    description: "Imports an npm package function as a node type. Creates expression node with inferred types.",
+    insertText: '@fwImport ${1:nodeName} ${2:functionName} from "${3:package}"',
+    insertTextFormat: "snippet",
+    ebnf: `fwImportTag    ::= "@fwImport" IDENTIFIER IDENTIFIER "from" QUOTED_STRING
+
+QUOTED_STRING  ::= STRING | "'" { any character except "'" } "'"`,
+    examples: [
+      '@fwImport npm/lodash/map map from "lodash"',
+      '@fwImport npm/date-fns/format format from "date-fns"',
+      "@fwImport local/utils/helper helper from './utils'"
+    ],
+    contexts: ["workflow"]
+  },
+  {
+    name: "@path",
+    category: "workflow",
+    syntax: "@path Start -> nodeA -> nodeB:fail -> Exit",
+    description: "Declare a complete execution route with scope walking. Steps separated by ->. Suffix :ok (default) or :fail to select onSuccess/onFailure. Data ports, Exit @returns ports included, auto-resolve by walking backward to the nearest ancestor with a same-name output. An explicit @connect wins, and a Start param never passes straight through to Exit.",
+    insertText: "@path Start -> ${1:node1} -> ${2:node2} -> Exit",
+    insertTextFormat: "snippet",
+    ebnf: `pathTag        ::= "@path" pathStep ( "->" pathStep )+
+pathStep       ::= IDENTIFIER [ ":" ( "ok" | "fail" ) ]`,
+    examples: [
+      "@path Start -> validator -> classifier -> urgencyRouter:fail -> escalate -> Exit",
+      "@path Start -> validator:ok -> processor -> Exit"
+    ],
+    contexts: ["workflow"]
+  },
+  {
+    name: "@scope",
+    category: "workflow",
+    syntax: "@scope scopeRef [nodes...]",
+    description: "Assigns nodes to a scope in a workflow. The scope ref can be a simple name or parent.child.",
+    insertText: "@scope ${1:scopeRef} [${2:nodes}]",
+    insertTextFormat: "snippet",
+    ebnf: `scopeTag       ::= "@scope" scopeRef "[" IDENTIFIER { "," IDENTIFIER } "]"
+
+scopeRef       ::= IDENTIFIER | IDENTIFIER "." IDENTIFIER`,
+    examples: [
+      "@scope loopScope [process, validate]",
+      "@scope container.inner [step1, step2]"
+    ],
+    contexts: ["workflow"]
+  },
+  {
+    name: "@map",
+    category: "workflow",
+    syntax: "@map instanceId ChildType [portMapping] over source.port",
+    description: "Declares a map (iteration) node that processes items from a source array port using a child node type. The optional port mapping overrides the default input/output port wiring.",
+    insertText: "@map ${1:id} ${2:ChildType} over ${3:source}.${4:port}",
+    insertTextFormat: "snippet",
+    ebnf: `mapTag         ::= "@map" IDENTIFIER IDENTIFIER [ "(" IDENTIFIER "->" IDENTIFIER ")" ]
+                   "over" IDENTIFIER "." IDENTIFIER`,
+    examples: [
+      "@map loop process over scan.files",
+      "@map loop process(inputPort -> outputPort) over scan.files"
+    ],
+    contexts: ["workflow"]
+  },
+  {
+    name: "@fanOut",
+    category: "workflow",
+    syntax: "@fanOut source.port -> target1, target2, target3",
+    description: "Broadcasts a single output port to multiple target nodes/ports. Expands to individual @connect lines during compilation.",
+    insertText: "@fanOut ${1:source}.${2:port} -> ${3:target1}, ${4:target2}",
+    insertTextFormat: "snippet",
+    ebnf: `fanOutTag      ::= "@fanOut" portRef "->" portRef { "," portRef }
+
+portRef        ::= IDENTIFIER [ "." IDENTIFIER ]`,
+    examples: [
+      "@fanOut Start.data -> a, b, c",
+      "@fanOut Start.data -> a.input1, b.input2"
+    ],
+    contexts: ["workflow"]
+  },
+  {
+    name: "@fanIn",
+    category: "workflow",
+    syntax: "@fanIn source1.port, source2.port -> target.port",
+    description: "Merges multiple output ports into a single target input. Expands to individual @connect lines during compilation.",
+    insertText: "@fanIn ${1:source1}, ${2:source2} -> ${3:target}.${4:port}",
+    insertTextFormat: "snippet",
+    ebnf: `fanInTag       ::= "@fanIn" portRef { "," portRef } "->" portRef
+
+portRef        ::= IDENTIFIER [ "." IDENTIFIER ]`,
+    examples: [
+      "@fanIn a.result, b.result, c.result -> merge.inputs",
+      "@fanIn a, b, c -> merge.data"
+    ],
+    contexts: ["workflow"]
+  },
+  {
+    name: "@coerce",
+    category: "workflow",
+    syntax: "@coerce instanceId source.port -> target.port as TargetType",
+    description: "Inserts an explicit type coercion node between two ports. Expands to a synthetic expression node that performs the conversion inline (e.g. String(), Number()). Works with @strictTypes since both connections are type-safe through the ANY input.",
+    insertText: "@coerce ${1:id} ${2:source}.${3:port} -> ${4:target}.${5:port} as ${6|string,number,boolean,json,object|}",
+    insertTextFormat: "snippet",
+    ebnf: `coerceTag      ::= "@coerce" IDENTIFIER portRef "->" portRef "as" targetType
+
+targetType     ::= "string" | "number" | "boolean" | "json" | "object"`,
+    examples: [
+      "@coerce c1 fetch.count -> calc.amount as number",
+      "@coerce toStr llm.response -> logger.message as string",
+      "@coerce parse api.body -> transform.data as object"
+    ],
+    contexts: ["workflow"]
+  },
+  {
+    name: "@autoConnect",
+    category: "workflow",
+    syntax: "@autoConnect",
+    description: "Enables automatic linear connection wiring for the workflow. When present, the compiler automatically wires nodes in declaration order (connecting compatible ports from previous nodes). No value is needed. Its presence enables the feature.",
+    insertText: "@autoConnect",
+    insertTextFormat: "plain",
+    ebnf: 'autoConnectTag ::= "@autoConnect"',
+    examples: ["@autoConnect"],
+    contexts: ["workflow"]
+  },
+  {
+    name: "@trigger",
+    category: "workflow",
+    syntax: '@trigger event="name" | cron="expr"',
+    description: "Declares an event or cron trigger for the workflow. Can specify event, cron, or both.",
+    insertText: '@trigger event="${1:event/name}"',
+    insertTextFormat: "snippet",
+    ebnf: 'triggerTag     ::= "@trigger" ( "event=" STRING | "cron=" STRING )*',
+    examples: [
+      '@trigger event="agent/request"',
+      '@trigger cron="0 9 * * *"',
+      '@trigger event="agent/request" cron="0 9 * * *"'
+    ],
+    contexts: ["workflow"]
+  },
+  {
+    name: "@http",
+    category: "workflow",
+    syntax: "@http METHOD /path [mode=sync|async] [auth=bearer|none] [callback]",
+    description: "Serves the workflow on an HTTP route with fw serve and the embeddable server. Path :params bind to workflow params by name. GET reads the query string, other methods the JSON body. The return ports are the response, onSuccess as 200 and onFailure as 422. A workflow that pauses at a gate answers 202 with a run id. Several tags give several routes.",
+    insertText: "@http POST /${1:path}",
+    insertTextFormat: "snippet",
+    ebnf: 'httpTag        ::= "@http" METHOD PATH { "mode=" ("sync"|"async") | "auth=" ("bearer"|"none") | "callback" }',
+    examples: [
+      "@http POST /reviews",
+      "@http GET /reviews/:path",
+      "@http POST /reviews mode=async callback",
+      "@http POST /hooks/github auth=none"
+    ],
+    contexts: ["workflow"]
+  },
+  {
+    name: "@cancelOn",
+    category: "workflow",
+    syntax: '@cancelOn event="name" [match="field"] [timeout="duration"]',
+    description: "Cancels a running workflow execution when a specified event is received.",
+    insertText: '@cancelOn event="${1:event/name}"',
+    insertTextFormat: "snippet",
+    ebnf: 'cancelOnTag    ::= "@cancelOn" "event=" STRING [ "match=" STRING ] [ "timeout=" STRING ]',
+    examples: [
+      '@cancelOn event="app/user.deleted"',
+      '@cancelOn event="app/user.deleted" match="data.userId"',
+      '@cancelOn event="x" match="data.id" timeout="1h"'
+    ],
+    contexts: ["workflow"]
+  },
+  {
+    name: "@retries",
+    category: "workflow",
+    syntax: "@retries N",
+    description: "Sets the retry count for the deployed function.",
+    insertText: "@retries ${1:3}",
+    insertTextFormat: "snippet",
+    ebnf: 'retriesTag     ::= "@retries" INTEGER',
+    examples: ["@retries 5", "@retries 0"],
+    contexts: ["workflow"]
+  },
+  {
+    name: "@timeout",
+    category: "workflow",
+    syntax: '@timeout "duration"',
+    description: "Sets the maximum execution time for the deployed function.",
+    insertText: '@timeout "${1:30m}"',
+    insertTextFormat: "snippet",
+    ebnf: 'timeoutTag     ::= "@timeout" STRING',
+    examples: ['@timeout "30m"', '@timeout "2h"'],
+    contexts: ["workflow"]
+  },
+  {
+    name: "@throttle",
+    category: "workflow",
+    syntax: '@throttle limit=N [period="duration"]',
+    description: "Limits concurrent executions of the deployed function.",
+    insertText: "@throttle limit=${1:10}",
+    insertTextFormat: "snippet",
+    ebnf: 'throttleTag    ::= "@throttle" "limit=" INTEGER [ "period=" STRING ]',
+    examples: ['@throttle limit=3 period="1m"', "@throttle limit=10"],
+    contexts: ["workflow"]
+  },
+  {
+    name: "@return",
+    category: "workflow",
+    syntax: "@return name [- description]",
+    description: "Declares a workflow output (Exit port). An alias of @returns; both parse identically.",
+    insertText: "@return ${1:name}",
+    insertTextFormat: "snippet",
+    ebnf: 'returnTag      ::= ("@return" | "@returns") IDENTIFIER [ "-" TEXT ]',
+    examples: ["@return result", "@return score - The computed score"],
+    contexts: ["workflow"]
+  },
+  {
+    name: "@async",
+    category: "workflow",
+    syntax: "@async",
+    description: "Marks a workflow or node type as asynchronous. Async is auto-detected from the TypeScript signature (a function returning a Promise), so this tag is optional; it is accepted as an explicit override and for documentation. Valid on both @flowWeaver workflow and @flowWeaver nodeType blocks.",
+    insertText: "@async",
+    insertTextFormat: "plain",
+    ebnf: 'asyncTag       ::= "@async"',
+    examples: ["@async"],
+    contexts: ["workflow", "nodeType"]
+  },
+  {
+    name: "@deploy",
+    category: "workflow",
+    syntax: "@deploy target [key=value ...]",
+    description: "Attaches deployment options for a named pack target. The default `typescript` compile target ignores it; a pack target reads the keys it supports. Values coerce to boolean/number when unquoted, and a quoted comma-separated value becomes a string array. Valid on both @flowWeaver workflow and @flowWeaver nodeType blocks. Several @deploy lines for the same target merge.",
+    insertText: "@deploy ${1:target} ${2:key}=${3:value}",
+    insertTextFormat: "snippet",
+    ebnf: 'deployTag      ::= "@deploy" IDENTIFIER { IDENTIFIER "=" ( STRING | BARE ) }',
+    examples: [
+      "@deploy inngest",
+      "@deploy aws-lambda memory=512 timeout=30",
+      '@deploy vercel regions="iad1,sfo1"'
+    ],
+    contexts: ["workflow", "nodeType"]
+  }
+];
+var METADATA_ANNOTATIONS = [
+  {
+    name: "@name",
+    category: "metadata",
+    syntax: "@name identifier",
+    description: "Sets the node type identifier. Used to reference this type in @node declarations.",
+    insertText: "@name ${1:identifier}",
+    insertTextFormat: "snippet",
+    contexts: ["nodeType", "workflow"]
+  },
+  {
+    name: "@label",
+    category: "metadata",
+    syntax: '@label "Display Name"',
+    description: "Sets a human-readable display label for the node or workflow in the UI.",
+    insertText: '@label "${1:Label}"',
+    insertTextFormat: "snippet",
+    contexts: ["nodeType", "workflow"]
+  },
+  {
+    name: "@description",
+    category: "metadata",
+    syntax: "@description Text description",
+    description: "Sets a description that appears as hover tooltip in the UI.",
+    insertText: "@description ${1:description}",
+    insertTextFormat: "snippet",
+    contexts: ["nodeType", "workflow"]
+  },
+  {
+    name: "@scope",
+    category: "metadata",
+    syntax: "@scope scopeName",
+    description: "Declares a scope on a node type for nested nodes. Used for iteration patterns (forEach, map, etc.).",
+    insertText: "@scope ${1:scopeName}",
+    insertTextFormat: "snippet",
+    contexts: ["nodeType"]
+  },
+  {
+    name: "@executeWhen",
+    category: "metadata",
+    syntax: "@executeWhen CONJUNCTION | DISJUNCTION | CUSTOM",
+    description: "Controls when a node with multiple step inputs executes. CONJUNCTION waits for all, DISJUNCTION fires on first.",
+    insertText: "@executeWhen ${1|CONJUNCTION,DISJUNCTION,CUSTOM|}",
+    insertTextFormat: "snippet",
+    contexts: ["nodeType"]
+  },
+  {
+    name: "@pullExecution",
+    category: "metadata",
+    syntax: "@pullExecution triggerPort",
+    description: "Enables lazy execution - node runs only when trigger port is pulled.",
+    insertText: "@pullExecution ${1:triggerPort}",
+    insertTextFormat: "snippet",
+    contexts: ["nodeType"]
+  },
+  {
+    name: "@resilience",
+    category: "metadata",
+    syntax: '@resilience retries=N [fallback="provider"]',
+    description: "Declares retry or fallback behavior implemented inside a shared node adapter so static agent validation can account for it.",
+    insertText: '@resilience retries=${1:3} fallback="${2:provider}"',
+    insertTextFormat: "snippet",
+    examples: [
+      "@resilience retries=3",
+      '@resilience retries=3 fallback="anthropic-backup"',
+      '@resilience fallback="local-model"'
+    ],
+    contexts: ["nodeType"]
+  },
+  {
+    name: "@expression",
+    category: "metadata",
+    syntax: "@expression",
+    description: "Marks node as pure expression node. No control flow ports (execute/onSuccess/onFailure).",
+    insertText: "@expression",
+    insertTextFormat: "plain",
+    contexts: ["nodeType"]
+  },
+  {
+    name: "@strictTypes",
+    category: "metadata",
+    syntax: "@strictTypes",
+    description: "Promotes type coercion warnings to errors in this workflow.",
+    insertText: "@strictTypes",
+    insertTextFormat: "plain",
+    ebnf: 'strictTypesTag ::= "@strictTypes" [ "false" ]',
+    examples: [
+      "@strictTypes              enables strict mode",
+      "@strictTypes false        explicitly disables"
+    ],
+    contexts: ["workflow"]
+  },
+  {
+    name: "@color",
+    category: "metadata",
+    syntax: "@color value",
+    description: "Sets a UI color hint for the node type.",
+    insertText: "@color ${1:value}",
+    insertTextFormat: "snippet",
+    contexts: ["nodeType"]
+  },
+  {
+    name: "@tag",
+    category: "metadata",
+    syntax: '@tag identifier ["description"]',
+    description: "Adds a tag to the node type for categorization. Optional string description.",
+    insertText: "@tag ${1:tagName}",
+    insertTextFormat: "snippet",
+    contexts: ["nodeType"]
+  },
+  {
+    name: "@icon",
+    category: "metadata",
+    syntax: "@icon text",
+    description: "Sets an icon identifier for the node type in the UI.",
+    insertText: "@icon ${1:iconName}",
+    insertTextFormat: "snippet",
+    contexts: ["nodeType"]
+  },
+  // Durable classification. Once a workflow's reachable closure contains a
+  // gate, every node in it must carry exactly one of these three. The
+  // compiler refuses an unclassified or doubly classified node.
+  {
+    name: "@durablePure",
+    category: "metadata",
+    syntax: "@durablePure",
+    description: "Declares a node with no side effects, safe for the engine to re-run after a durable resume. Required on every non-gate, non-effect node in a workflow that contains a gate.",
+    insertText: "@durablePure",
+    insertTextFormat: "plain",
+    examples: ["@durablePure"],
+    contexts: ["nodeType"]
+  },
+  {
+    name: "@durableGate",
+    category: "metadata",
+    syntax: "@durableGate approval | input | agent | timer",
+    description: "Declares a durable gate: the workflow yields here with a continuation and resumes later with a supplied resolution. The body is never executed. The kind labels who resolves it.",
+    insertText: "@durableGate ${1|approval,input,agent,timer|}",
+    insertTextFormat: "snippet",
+    ebnf: `durableGateTag ::= "@durableGate" ( "approval" | "input" | "agent" | "timer" )`,
+    examples: ["@durableGate approval", "@durableGate agent"],
+    contexts: ["nodeType"]
+  },
+  {
+    name: "@durableEffect",
+    category: "metadata",
+    syntax: "@durableEffect",
+    description: "Declares a node that touches the outside world. It receives a trailing operationKey parameter, returns { result, receipt }, and runs only through the effect adapter so a resume never repeats it.",
+    insertText: "@durableEffect",
+    insertTextFormat: "plain",
+    examples: ["@durableEffect"],
+    contexts: ["nodeType"]
+  }
+];
+var STANDARD_ANNOTATIONS = [
+  {
+    name: "@param",
+    category: "standard",
+    syntax: "@param {type} name - description",
+    description: "Standard JSDoc parameter documentation. In workflows, defines Start port (workflow input).",
+    insertText: "@param {${1:type}} ${2:name} - ${3:description}",
+    insertTextFormat: "snippet",
+    ebnf: "paramTag       ::= IDENTIFIER [ scopeClause ] { metadataBracket } [ descriptionClause ]",
+    contexts: ["workflow"]
+  },
+  {
+    name: "@returns",
+    category: "standard",
+    syntax: "@returns {type} description",
+    description: "Standard JSDoc return documentation. In workflows, defines Exit port (workflow output).",
+    insertText: "@returns {${1:type}} ${2:description}",
+    insertTextFormat: "snippet",
+    ebnf: "returnsTag     ::= IDENTIFIER [ scopeClause ] { metadataBracket } [ descriptionClause ]",
+    contexts: ["workflow"]
+  }
+];
+var PORT_MODIFIERS = [
+  {
+    name: "order",
+    syntax: "[order:N]",
+    description: "Sets display order for the port. Lower numbers appear higher."
+  },
+  {
+    name: "placement",
+    syntax: "[placement:TOP|BOTTOM]",
+    description: "Controls port position on the node.",
+    enum: ["TOP", "BOTTOM"]
+  },
+  {
+    name: "type",
+    syntax: "[type:TYPE]",
+    description: "Overrides inferred port data type."
+  },
+  {
+    name: "hidden",
+    syntax: "[hidden]",
+    description: "Hides port from UI display."
+  },
+  {
+    name: "optional",
+    syntax: "[optional]",
+    description: "Marks input port as optional (alternative to square brackets around name)."
+  }
+];
+var NODE_MODIFIERS = [
+  {
+    name: "label",
+    syntax: '[label:"Display Name"]',
+    description: "Override the display label for this instance."
+  },
+  {
+    name: "expr",
+    syntax: '[expr:port="value"]',
+    description: "Set a port from a JavaScript expression. The expression may reference upstream ports: Start.<param> or <node>.<port>, with any further property access after the port. Each reference becomes a data dependency the graph sees. The expression is the value."
+  },
+  {
+    name: "minimized",
+    syntax: "[minimized]",
+    description: "Collapse the node in the UI."
+  },
+  {
+    name: "pullExecution",
+    syntax: "[pullExecution:port]",
+    description: "Enable lazy execution for this instance."
+  },
+  {
+    name: "portOrder",
+    syntax: "[portOrder:port=N]",
+    description: "Override display order for a specific port."
+  },
+  {
+    name: "portLabel",
+    syntax: '[portLabel:port="Label"]',
+    description: "Override display label for a specific port."
+  },
+  {
+    name: "size",
+    syntax: "[size:width,height]",
+    description: "Set custom node dimensions."
+  }
+];
+var ALL_ANNOTATIONS = [
+  ...CORE_ANNOTATIONS,
+  ...PORT_ANNOTATIONS,
+  ...WORKFLOW_ANNOTATIONS,
+  ...METADATA_ANNOTATIONS,
+  ...STANDARD_ANNOTATIONS
+];
+
+// src/doc-metadata/extractors/error-codes.ts
+var VALIDATION_CODES = [
+  // ── Structural ──────────────────────────────────────────────────────
+  {
+    code: "MISSING_WORKFLOW_NAME",
+    severity: "error",
+    title: "Missing Workflow Name",
+    description: "Workflow has no name",
+    category: "structural"
+  },
+  {
+    code: "MISSING_FUNCTION_NAME",
+    severity: "error",
+    title: "Missing Function Name",
+    description: "Workflow has no function name",
+    category: "structural"
+  },
+  {
+    code: "DUPLICATE_NODE_NAME",
+    severity: "error",
+    title: "Duplicate Node Name",
+    description: "Two node types share a function name",
+    category: "structural"
+  },
+  {
+    code: "MUTABLE_NODE_TYPE_BINDING",
+    severity: "warning",
+    title: "Mutable Node Binding",
+    description: "Node type declared with let/var instead of const",
+    category: "structural"
+  },
+  {
+    code: "INFERRED_NODE_TYPE",
+    severity: "warning",
+    title: "Inferred Node Type",
+    description: "Node type auto-inferred without explicit annotation",
+    category: "structural"
+  },
+  {
+    code: "ANNOTATION_SIGNATURE_MISMATCH",
+    severity: "warning",
+    title: "Optional Port Mismatch",
+    description: "Port optionality differs between annotation and sig",
+    category: "structural"
+  },
+  {
+    code: "ANNOTATION_SIGNATURE_TYPE_MISMATCH",
+    severity: "warning",
+    title: "Annotation Type Mismatch",
+    description: "Port type differs between annotation and signature",
+    category: "structural"
+  },
+  // ── Naming ──────────────────────────────────────────────────────────
+  {
+    code: "RESERVED_NODE_NAME",
+    severity: "error",
+    title: "Reserved Name Used",
+    description: 'Node type uses "Start" or "Exit"',
+    category: "naming"
+  },
+  {
+    code: "RESERVED_INSTANCE_ID",
+    severity: "error",
+    title: "Reserved Instance ID",
+    description: 'Instance ID is "Start" or "Exit"',
+    category: "naming"
+  },
+  {
+    code: "INVALID_SCOPE_NAME",
+    severity: "error",
+    title: "Invalid Scope Name",
+    description: "A scoped port names a scope that is not a JavaScript identifier (scope names become identifiers in generated code)",
+    category: "naming"
+  },
+  // ── Connection ──────────────────────────────────────────────────────
+  {
+    code: "UNKNOWN_SOURCE_NODE",
+    severity: "error",
+    title: "Missing Source Node",
+    description: "Connection from nonexistent node",
+    category: "connection"
+  },
+  {
+    code: "UNKNOWN_TARGET_NODE",
+    severity: "error",
+    title: "Missing Target Node",
+    description: "Connection to nonexistent node",
+    category: "connection"
+  },
+  {
+    code: "UNKNOWN_SOURCE_PORT",
+    severity: "error",
+    title: "Unknown Output Port",
+    description: "Connection from nonexistent output port",
+    category: "connection"
+  },
+  {
+    code: "UNKNOWN_TARGET_PORT",
+    severity: "error",
+    title: "Unknown Input Port",
+    description: "Connection to nonexistent input port",
+    category: "connection"
+  },
+  {
+    code: "MULTIPLE_CONNECTIONS_TO_INPUT",
+    severity: "error",
+    title: "Multiple Input Connections",
+    description: "Data input port has more than one source",
+    category: "connection"
+  },
+  // ── Type ────────────────────────────────────────────────────────────
+  {
+    code: "STEP_PORT_TYPE_MISMATCH",
+    severity: "error",
+    title: "Wrong Port Type",
+    description: "STEP port connected to data port or vice versa",
+    category: "type"
+  },
+  {
+    code: "TYPE_INCOMPATIBLE",
+    severity: "error",
+    title: "Type Incompatible",
+    description: "Type mismatch with @strictTypes enabled",
+    category: "type"
+  },
+  {
+    code: "OBJECT_TYPE_MISMATCH",
+    severity: "warning",
+    title: "Object Shape Mismatch",
+    description: "OBJECT ports have different structural types",
+    category: "type"
+  },
+  {
+    code: "LOSSY_TYPE_COERCION",
+    severity: "warning",
+    title: "Lossy Type Conversion",
+    description: "Type coercion may lose information",
+    category: "type"
+  },
+  {
+    code: "UNUSUAL_TYPE_COERCION",
+    severity: "warning",
+    title: "Unusual Type Coercion",
+    description: "Type coercion is semantically unusual",
+    category: "type"
+  },
+  {
+    code: "TYPE_MISMATCH",
+    severity: "warning",
+    title: "Type Mismatch",
+    description: "Incompatible types, runtime coercion attempted",
+    category: "type"
+  },
+  // ── Node Reference ──────────────────────────────────────────────────
+  {
+    code: "UNKNOWN_NODE_TYPE",
+    severity: "error",
+    title: "Unknown Node Type",
+    description: "Instance references nonexistent node type",
+    category: "node-ref"
+  },
+  {
+    code: "MISSING_REQUIRED_INPUT",
+    severity: "error",
+    title: "Missing Required Input",
+    description: "Required input has no connection/default/expression",
+    category: "node-ref"
+  },
+  // ── Graph ───────────────────────────────────────────────────────────
+  {
+    code: "CYCLE_DETECTED",
+    severity: "error",
+    title: "Circular Dependency Found",
+    description: "Graph contains a loop",
+    category: "graph"
+  },
+  {
+    code: "INVALID_EXIT_PORT_TYPE",
+    severity: "error",
+    title: "Invalid Exit Port Type",
+    description: "Exit onSuccess/onFailure is not STEP type",
+    category: "graph"
+  },
+  // ── Data Flow ───────────────────────────────────────────────────────
+  {
+    code: "UNUSED_NODE",
+    severity: "warning",
+    title: "Unused Node",
+    description: "Node defined but not connected",
+    category: "data-flow"
+  },
+  {
+    code: "NO_START_CONNECTIONS",
+    severity: "warning",
+    title: "No Start Connections",
+    description: "No connections from Start",
+    category: "data-flow"
+  },
+  {
+    code: "NO_EXIT_CONNECTIONS",
+    severity: "warning",
+    title: "No Exit Connections",
+    description: "No connections to Exit",
+    category: "data-flow"
+  },
+  {
+    code: "UNUSED_OUTPUT_PORT",
+    severity: "warning",
+    title: "Unused Output Port",
+    description: "Output port data is discarded",
+    category: "data-flow"
+  },
+  {
+    code: "UNREACHABLE_EXIT_PORT",
+    severity: "warning",
+    title: "Unreachable Exit Port",
+    description: "Exit port has no incoming connection",
+    category: "data-flow"
+  },
+  {
+    code: "HTTP_PARAM_UNKNOWN",
+    severity: "error",
+    title: "HTTP route param is not a workflow param",
+    description: "An @http route has a :param segment that names no parameter of the workflow",
+    category: "data-flow"
+  },
+  {
+    code: "MULTIPLE_EXIT_CONNECTIONS",
+    severity: "warning",
+    title: "Multiple Exit Connections",
+    description: "Exit port has multiple sources",
+    category: "data-flow"
+  },
+  // ── Scope ───────────────────────────────────────────────────────────
+  {
+    code: "SCOPE_MISSING_REQUIRED_INPUT",
+    severity: "error",
+    title: "Scope Child Missing Input",
+    description: "Required input port on a scoped child has no connection",
+    category: "graph"
+  },
+  {
+    code: "SCOPE_UNUSED_INPUT",
+    severity: "warning",
+    title: "Scope Input Unused",
+    description: "Scoped input port has no connection from inner nodes",
+    category: "graph"
+  },
+  {
+    code: "SCOPE_WRONG_SCOPE_NAME",
+    severity: "error",
+    title: "Invalid Scope Qualifier",
+    description: "Connection uses a scope name not defined on the node",
+    category: "graph"
+  },
+  {
+    code: "SCOPE_CONNECTION_OUTSIDE",
+    severity: "error",
+    title: "Scope Connection Leak",
+    description: "Scoped connection references a node outside the scope",
+    category: "graph"
+  },
+  {
+    code: "SCOPE_PORT_TYPE_MISMATCH",
+    severity: "warning",
+    title: "Scope Port Type Mismatch",
+    description: "Type mismatch between scoped port and connected child port",
+    category: "type"
+  },
+  {
+    code: "SCOPE_UNKNOWN_PORT",
+    severity: "error",
+    title: "Unknown Scoped Port",
+    description: "Connection references a port that is not a scoped port of the specified scope",
+    category: "connection"
+  },
+  {
+    code: "SCOPE_ORPHANED_CHILD",
+    severity: "warning",
+    title: "Orphaned Scope Child",
+    description: "Child node in scope has no scoped connections to parent",
+    category: "graph"
+  },
+  // ── Agent ───────────────────────────────────────────────────────────
+  {
+    code: "AGENT_LLM_MISSING_ERROR_HANDLER",
+    severity: "error",
+    title: "LLM Missing Error Handler",
+    description: "LLM node's onFailure port is unconnected",
+    category: "agent"
+  },
+  {
+    code: "AGENT_UNGUARDED_TOOL_EXECUTOR",
+    severity: "warning",
+    title: "Unguarded Tool Executor",
+    description: "Tool executor has no upstream human-approval gate",
+    category: "agent"
+  },
+  {
+    code: "AGENT_MISSING_MEMORY_IN_LOOP",
+    severity: "warning",
+    title: "No Memory in Agent Loop",
+    description: "Loop has LLM but no conversation memory node",
+    category: "agent"
+  },
+  {
+    code: "AGENT_LLM_NO_FALLBACK",
+    severity: "warning",
+    title: "LLM Failure Goes to Exit",
+    description: "LLM onFailure routes directly to Exit",
+    category: "agent"
+  },
+  {
+    code: "AGENT_TOOL_NO_OUTPUT_HANDLING",
+    severity: "warning",
+    title: "Tool Results Discarded",
+    description: "Tool executor data outputs all unconnected",
+    category: "agent"
+  },
+  // ── Design ──────────────────────────────────────────────────────────
+  {
+    code: "DESIGN_ASYNC_NO_ERROR_PATH",
+    severity: "warning",
+    title: "Async Node Missing Error Path",
+    description: "Async node has no onFailure connection (durable gates are exempt: their body never runs and their failure arm is the resolver's rejection)",
+    category: "design"
+  },
+  {
+    code: "DESIGN_SCOPE_NO_FAILURE_EXIT",
+    severity: "warning",
+    title: "Scope Missing Failure Exit",
+    description: "Scope node has no failure path out",
+    category: "design"
+  },
+  {
+    code: "DESIGN_UNBOUNDED_RETRY",
+    severity: "warning",
+    title: "Unbounded Retry Loop",
+    description: "Retry scope has no visible attempt limit",
+    category: "design"
+  },
+  {
+    code: "DESIGN_FANOUT_NO_FANIN",
+    severity: "warning",
+    title: "Fan-Out Without Fan-In",
+    description: "Fan-out to multiple step targets with no merge back",
+    category: "design"
+  },
+  {
+    code: "DESIGN_EXIT_DATA_UNREACHABLE",
+    severity: "warning",
+    title: "Exit Data Unreachable",
+    description: "Exit data port has no connection and no pull-execution provider",
+    category: "design"
+  },
+  {
+    code: "DESIGN_PULL_CANDIDATE",
+    severity: "warning",
+    title: "Pull Execution Candidate",
+    description: "Node has no step trigger but its outputs are consumed downstream",
+    category: "design"
+  },
+  {
+    code: "DESIGN_PULL_UNUSED",
+    severity: "warning",
+    title: "Unused Pull Execution",
+    description: "Pull-execution node has no downstream consumers",
+    category: "design"
+  },
+  // ── Previously undocumented (emitted by the validator, missing from the catalogue) ──
+  {
+    code: "DUPLICATE_INSTANCE_ID",
+    severity: "error",
+    title: "Duplicate Instance ID",
+    description: "Two @node declarations in one workflow use the same ID. Each instance ID must be unique",
+    category: "structural"
+  },
+  {
+    code: "STUB_NODE",
+    severity: "error",
+    title: "Stub Node",
+    description: "An instance uses a node type that has no implementation. Implement it, or validate in draft mode to check structure only",
+    category: "node-ref"
+  },
+  {
+    code: "DUPLICATE_CONNECTION",
+    severity: "error",
+    title: "Duplicate Connection",
+    description: "The same from-port to to-port connection is declared more than once",
+    category: "connection"
+  },
+  {
+    code: "CROSS_SCOPE_CONNECTION",
+    severity: "error",
+    title: "Cross-Scope Connection",
+    description: "A connection links nodes that live in different scopes. Nodes in different scopes cannot connect directly",
+    category: "connection"
+  },
+  {
+    code: "SCOPE_INCONSISTENT",
+    severity: "error",
+    title: "Inconsistent Scope Membership",
+    description: "An instance is listed in more than one scope. A node can belong to only one scope",
+    category: "graph"
+  },
+  {
+    code: "SCOPE_EMPTY",
+    severity: "warning",
+    title: "Empty Scope",
+    description: "A scope declared on a node has no child nodes",
+    category: "graph"
+  },
+  {
+    code: "COERCE_ON_FUNCTION_PORT",
+    severity: "error",
+    title: "Coercion On Function Port",
+    description: "An `as` coercion is applied to a FUNCTION port. Function values cannot be meaningfully coerced",
+    category: "type"
+  },
+  {
+    code: "COERCE_TYPE_MISMATCH",
+    severity: "warning",
+    title: "Coercion Type Mismatch",
+    description: "An `as` coercion produces a type the target port does not expect. Use the coercion that matches the target",
+    category: "type"
+  },
+  {
+    code: "REDUNDANT_COERCE",
+    severity: "warning",
+    title: "Redundant Coercion",
+    description: "An `as` coercion converts between identical source and target types and does nothing",
+    category: "type"
+  },
+  {
+    code: "INVALID_PORT_TYPE",
+    severity: "warning",
+    title: "Invalid Port Type",
+    description: "A port declares a dataType that is not a recognised Flow Weaver type",
+    category: "type"
+  },
+  {
+    code: "INVALID_COLOR",
+    severity: "warning",
+    title: "Invalid Color",
+    description: "A node type uses an @color value that is not in the palette. See the visual-reference topic for valid colors",
+    category: "structural"
+  },
+  {
+    code: "INVALID_ICON",
+    severity: "warning",
+    title: "Invalid Icon",
+    description: "A node type uses an @icon value that is not a Material Symbols name (snake_case or camelCase). See the visual-reference topic",
+    category: "structural"
+  },
+  {
+    code: "INVALID_EXECUTE_WHEN",
+    severity: "warning",
+    title: "Invalid Execute-When Strategy",
+    description: "A node type declares an @executeWhen value that is not a recognised execution strategy",
+    category: "structural"
+  },
+  {
+    code: "INVALID_PORT_CONFIG_REF",
+    severity: "warning",
+    title: "Invalid Port Config Reference",
+    description: "An instance configures a port (portOrder, portLabel, expr) that does not exist on its node type",
+    category: "structural"
+  },
+  {
+    code: "EXPRESSION_SYNTAX",
+    severity: "error",
+    title: "Expression Is Not JavaScript",
+    description: `An [expr:] binding or an Expression: default does not parse as a JavaScript expression (text needs quotes inside the attribute: timeout="'24h'"). It would otherwise fail only when the generated file is transpiled`,
+    category: "structural"
+  },
+  {
+    code: "DURABLE_CLOSURE_INVALID",
+    severity: "error",
+    title: "Invalid Durable Closure",
+    description: "A workflow with a durable gate breaks a durability rule (a gate/effect in more than one branch region or taking data from outside it, pull/lazy execution, an unclassified node, or a bad effect contract). Surfaced at author time. The coordinator would otherwise reject it only at run time.",
+    category: "graph"
+  },
+  {
+    code: "SUPPRESS_UNKNOWN_CODE",
+    severity: "warning",
+    title: "Unknown Suppress Code",
+    description: 'A [suppress: ...] entry cannot be a validation code, so it suppresses nothing. Codes are separate string literals, e.g. [suppress: "A", "B"], not [suppress: "A,B"]',
+    category: "structural"
+  }
+];
+
+// src/doc-metadata/extractors/grammar-rules.ts
+function extractGrammarEBNF() {
+  const grammars = getAllGrammars();
+  const groups = [];
+  for (const [name, productions] of Object.entries(grammars)) {
+    const ebnf = serializedToEBNF(productions);
+    if (ebnf.trim()) {
+      groups.push({ name, ebnf });
+    }
+  }
+  return groups;
+}
+function extractTerminals() {
+  return [
+    {
+      name: "IDENTIFIER",
+      pattern: "[a-zA-Z_$] [a-zA-Z0-9_$\\/-]*",
+      description: "IDENTIFIER supports `/` and `-` to accommodate npm package naming conventions (e.g., `npm/react-window/areEqual`)."
+    },
+    {
+      name: "INTEGER",
+      pattern: '"-"? [0-9]+',
+      description: "Signed integer literal."
+    },
+    {
+      name: "STRING",
+      pattern: `'"' { any character except '"' or '\\', or escape sequence } '"'`,
+      description: "Double-quoted string with escape sequences."
+    },
+    {
+      name: "TEXT",
+      pattern: "any characters to end of line",
+      description: "Free-form text to end of line (used in descriptions)."
+    }
+  ];
+}
+
+// src/doc-metadata/extractors/core-metadata.ts
+var DATA_TYPES = [
+  "STRING",
+  "NUMBER",
+  "BOOLEAN",
+  "OBJECT",
+  "ARRAY",
+  "FUNCTION",
+  "STEP",
+  "ANY"
+];
+var MERGE_STRATEGIES = ["FIRST", "LAST", "COLLECT", "MERGE", "CONCAT"];
+var BRANCHING_STRATEGY_VALUES = ["value-based", "exception-based", "none"];
+var EXECUTION_STRATEGY_VALUES = ["CONJUNCTION", "DISJUNCTION", "CUSTOM"];
+var WORKFLOW_TEMPLATES = workflowTemplates.map(
+  ({ id, name, description, category }) => ({ id, name, description, category })
+);
+var NODE_TEMPLATES = nodeTemplates.map(
+  ({ id, name, description, category }) => ({ id, name, description, category })
+);
+var PACKAGE_EXPORTS = [
+  { subpath: ".", description: "Core library (parser, validator, compiler)" },
+  { subpath: "./runtime", description: "Workflow runtime executor" },
+  { subpath: "./compiler", description: "Build-only executable artifact compiler" },
+  { subpath: "./built-in-nodes", description: "Standard node type library" },
+  { subpath: "./diagram", description: "Diagram rendering (SVG/Mermaid)" },
+  { subpath: "./describe", description: "Workflow description formatter" },
+  { subpath: "./doc-metadata", description: "Documentation metadata extractors" },
+  { subpath: "./docs", description: "Documentation generation utilities" },
+  { subpath: "./ast", description: "AST type definitions and builders" },
+  { subpath: "./api", description: "Public API (parseWorkflow, validateWorkflow, etc.)" },
+  { subpath: "./diff", description: "Workflow semantic diff engine" },
+  { subpath: "./editor", description: "Editor completions and diagnostics" },
+  { subpath: "./browser", description: "Browser-compatible JSDoc port sync" },
+  { subpath: "./generated-branding", description: "Generated branding configuration" },
+  { subpath: "./npm-packages", description: "NPM package metadata" },
+  { subpath: "./deployment", description: "Deployment target configurations" },
+  { subpath: "./marketplace", description: "Extension/pack marketplace APIs" },
+  { subpath: "./testing", description: "Testing utilities" },
+  { subpath: "./generator", description: "Code generation" },
+  { subpath: "./constants", description: "Constants and reserved names" },
+  { subpath: "./cli", description: "CLI command definitions" },
+  { subpath: "./version", description: "Package version metadata" },
+  { subpath: "./context", description: "LLM context generation" },
+  { subpath: "./agent", description: "Provider-agnostic agent tooling" },
+  { subpath: "./console", description: "The local operator console server" },
+  { subpath: "./coordinator", description: "Local run coordinator: start, resume and watch gated workflows from code" },
+  { subpath: "./server", description: "Workflows as HTTP endpoints: createWorkflowApi with Node, Express and fetch adapters, the handler behind fw serve" }
+];
+export {
+  ALL_ANNOTATIONS,
+  BRANCHING_STRATEGIES,
+  BRANCHING_STRATEGY_VALUES,
+  CLI_COMMANDS,
+  DATA_TYPES,
+  EXECUTION_STRATEGIES,
+  EXECUTION_STRATEGY_VALUES,
+  MCP_TOOLS,
+  MERGE_STRATEGIES,
+  NODE_MODIFIERS,
+  NODE_TEMPLATES,
+  PACKAGE_EXPORTS,
+  PORT_MODIFIERS,
+  RESERVED_NODE_NAMES,
+  RESERVED_PORT_NAMES,
+  SCOPED_PORT_NAMES,
+  VALIDATION_CODES,
+  VALID_NODE_COLORS,
+  WORKFLOW_TEMPLATES,
+  extractCliCommands,
+  extractGrammarEBNF,
+  extractMcpTools,
+  extractTerminals
+};