@synergenius/flow-weaver 0.2.0 → 0.2.1

package/dist/chevrotain-parser/grammar-diagrams.d.ts

@@ -12,6 +12,8 @@ export interface GrammarCollection {
     position: ISerializedGast[];
     scope: ISerializedGast[];
     path: ISerializedGast[];
+    map: ISerializedGast[];
+    triggerCancel: ISerializedGast[];
 }
 /**
  * Get all grammar productions as serialized GAST (Grammar AST).

package/dist/chevrotain-parser/grammar-diagrams.js

@@ -10,6 +10,8 @@ import { getConnectGrammar } from './connect-parser.js';
 import { getPositionGrammar } from './position-parser.js';
 import { getScopeGrammar } from './scope-parser.js';
 import { getPathGrammar } from './path-parser.js';
+import { getMapGrammar } from './map-parser.js';
+import { getTriggerCancelGrammar } from './trigger-cancel-parser.js';
 export function serializedToEBNF(productions) {
     const lines = [];
     for (const prod of productions) {
@@ -72,7 +74,7 @@ function itemToEBNF(item) {
             if (pattern === 'BOTTOM\\b')
                 return '"BOTTOM"';
             // Identifier pattern - use semantic name if available
-            if (pattern === '[a-zA-Z_$][a-zA-Z0-9_$]*') {
+            if (pattern === '[a-zA-Z_$][a-zA-Z0-9_$]*' || pattern === '[a-zA-Z_$][a-zA-Z0-9_$\\/-]*') {
                 const semanticName = item.terminalLabel || 'IDENTIFIER';
                 return semanticName;
             }
@@ -126,6 +128,8 @@ export function getAllGrammars() {
         position: getPositionGrammar(),
         scope: getScopeGrammar(),
         path: getPathGrammar(),
+        map: getMapGrammar(),
+        triggerCancel: getTriggerCancelGrammar(),
     };
 }
 /**
@@ -142,6 +146,8 @@ export function generateGrammarDiagrams() {
         ...grammars.position,
         ...grammars.scope,
         ...grammars.path,
+        ...grammars.map,
+        ...grammars.triggerCancel,
     ];
     // createSyntaxDiagramsCode returns a complete HTML document
     const html = createSyntaxDiagramsCode(allProductions);

package/dist/chevrotain-parser/trigger-cancel-parser.d.ts

@@ -46,5 +46,9 @@ export declare function parseTimeoutLine(input: string, warnings: string[]): Tim
  * Parse a @throttle line and return structured result.
  * Returns null if the line is not a throttle declaration.
  */
+/**
+ * Get serialized grammar productions for documentation/diagrams.
+ */
+export declare function getTriggerCancelGrammar(): import("chevrotain").ISerializedGast[];
 export declare function parseThrottleLine(input: string, warnings: string[]): ThrottleParseResult | null;
 //# sourceMappingURL=trigger-cancel-parser.d.ts.map

package/dist/chevrotain-parser/trigger-cancel-parser.js

@@ -255,6 +255,12 @@ export function parseTimeoutLine(input, warnings) {
  * Parse a @throttle line and return structured result.
  * Returns null if the line is not a throttle declaration.
  */
+/**
+ * Get serialized grammar productions for documentation/diagrams.
+ */
+export function getTriggerCancelGrammar() {
+    return parserInstance.getSerializedGastProductions();
+}
 export function parseThrottleLine(input, warnings) {
     const lexResult = JSDocLexer.tokenize(input);
     if (lexResult.errors.length > 0) {

package/dist/cli/flow-weaver.mjs

@@ -42452,6 +42452,9 @@ function parseMapLine(input, warnings) {
   }
   return visitorInstance6.visit(cst);
 }
+function getMapGrammar() {
+  return parserInstance6.getSerializedGastProductions();
+}
 
 // src/chevrotain-parser/path-parser.ts
 var PathParser = class extends CstParser {
@@ -42710,6 +42713,9 @@ function parseCancelOnLine(input, warnings) {
   }
   return visitorInstance8.visit(cst);
 }
+function getTriggerCancelGrammar() {
+  return parserInstance8.getSerializedGastProductions();
+}
 function parseThrottleLine(input, warnings) {
   const lexResult = JSDocLexer.tokenize(input);
   if (lexResult.errors.length > 0) {
@@ -42784,7 +42790,7 @@ function itemToEBNF(item) {
       if (pattern === "minimized\\b") return '"minimized"';
       if (pattern === "TOP\\b") return '"TOP"';
       if (pattern === "BOTTOM\\b") return '"BOTTOM"';
-      if (pattern === "[a-zA-Z_$][a-zA-Z0-9_$]*") {
+      if (pattern === "[a-zA-Z_$][a-zA-Z0-9_$]*" || pattern === "[a-zA-Z_$][a-zA-Z0-9_$\\/-]*") {
         const semanticName = item.terminalLabel || "IDENTIFIER";
         return semanticName;
       }
@@ -42828,7 +42834,9 @@ function getAllGrammars() {
     connect: getConnectGrammar(),
     position: getPositionGrammar(),
     scope: getScopeGrammar(),
-    path: getPathGrammar()
+    path: getPathGrammar(),
+    map: getMapGrammar(),
+    triggerCancel: getTriggerCancelGrammar()
   };
 }
 function generateGrammarDiagrams() {
@@ -42839,7 +42847,9 @@ function generateGrammarDiagrams() {
     ...grammars.connect,
     ...grammars.position,
     ...grammars.scope,
-    ...grammars.path
+    ...grammars.path,
+    ...grammars.map,
+    ...grammars.triggerCancel
   ];
   const html = createSyntaxDiagramsCode(allProductions);
   const ebnf = serializedToEBNF(allProductions);
@@ -51919,6 +51929,22 @@ function extractCyclePath(message) {
   return match2 ? match2[1] : null;
 }
 var errorMappers = {
+  MISSING_WORKFLOW_NAME(error2) {
+    return {
+      title: "Missing Workflow Name",
+      explanation: "The workflow annotation is missing or has no name. Every workflow needs a name in the @flowWeaver workflow block.",
+      fix: "Add @flowWeaver workflow to the JSDoc block above your exported workflow function.",
+      code: error2.code
+    };
+  },
+  MISSING_FUNCTION_NAME(error2) {
+    return {
+      title: "Missing Function Name",
+      explanation: "The compiler found a @flowWeaver workflow annotation but the function is anonymous or not exported.",
+      fix: "Make sure your workflow is declared as `export function myWorkflowName(...)` \u2014 not anonymous or unexported.",
+      code: error2.code
+    };
+  },
   MISSING_REQUIRED_INPUT(error2) {
     const quoted = extractQuoted(error2.message);
     const nodeName = quoted[0] || error2.node || "unknown";
@@ -52063,6 +52089,58 @@ var errorMappers = {
       code: error2.code
     };
   },
+  RESERVED_INSTANCE_ID(error2) {
+    const quoted = extractQuoted(error2.message);
+    const instanceId = quoted[0] || error2.node || "unknown";
+    return {
+      title: "Reserved Instance ID",
+      explanation: `Instance ID '${instanceId}' is reserved. 'Start' and 'Exit' are built-in nodes in every workflow.`,
+      fix: `Choose a different instance ID, like 'startHandler' or 'exitProcessor'.`,
+      code: error2.code
+    };
+  },
+  INFERRED_NODE_TYPE(error2) {
+    const quoted = extractQuoted(error2.message);
+    const nodeTypeName = quoted[0] || error2.node || "unknown";
+    return {
+      title: "Inferred Node Type",
+      explanation: `Node type '${nodeTypeName}' was auto-inferred from the function signature. It works, but you lose explicit control over port names, types, and ordering.`,
+      fix: `Add /** @flowWeaver nodeType @expression */ above the function for explicit port control.`,
+      code: error2.code
+    };
+  },
+  UNDEFINED_NODE(error2) {
+    const quoted = extractQuoted(error2.message);
+    const nodeName = quoted[0] || error2.node || "unknown";
+    return {
+      title: "Undefined Node",
+      explanation: `A connection references node '${nodeName}', but there's no @node annotation defining it.`,
+      fix: `Add a @node annotation for '${nodeName}' in the workflow JSDoc, or remove the connections that reference it.`,
+      code: error2.code
+    };
+  },
+  TYPE_INCOMPATIBLE(error2) {
+    const types2 = extractTypes(error2.message);
+    const source = types2?.source || "unknown";
+    const target = types2?.target || "unknown";
+    return {
+      title: "Type Incompatible",
+      explanation: `Type mismatch: ${source} to ${target}. With @strictTypes enabled, this is an error instead of a warning.`,
+      fix: `Add a conversion node between the ports, change one of the port types, or remove @strictTypes to allow implicit coercions.`,
+      code: error2.code
+    };
+  },
+  UNUSUAL_TYPE_COERCION(error2) {
+    const types2 = extractTypes(error2.message);
+    const source = types2?.source || "unknown";
+    const target = types2?.target || "unknown";
+    return {
+      title: "Unusual Type Coercion",
+      explanation: `Converting ${source} to ${target} is technically valid but semantically unusual and may produce unexpected behavior.`,
+      fix: `Add an explicit conversion node if this is intentional, or use @strictTypes to enforce type safety.`,
+      code: error2.code
+    };
+  },
   MULTIPLE_CONNECTIONS_TO_INPUT(error2) {
     const quoted = extractQuoted(error2.message);
     const portName = quoted[0] || "unknown";
@@ -92508,7 +92586,7 @@ function displayInstalledPackage(pkg) {
 }
 
 // src/cli/index.ts
-var version2 = true ? "0.2.0" : "0.0.0-dev";
+var version2 = true ? "0.2.1" : "0.0.0-dev";
 var program2 = new Command();
 program2.name("flow-weaver").description("Flow Weaver Annotations - Compile and validate workflow files").version(version2, "-v, --version", "Output the current version");
 program2.configureOutput({

package/dist/doc-metadata/extractors/error-codes.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Single source of truth for validation error code documentation.
+ *
+ * Every code the validator (src/validator.ts) and agent rules
+ * (src/validation/agent-rules.ts) can emit is listed here.
+ *
+ * The generate-docs script uses this to build the summary tables
+ * in docs/reference/error-codes.md.
+ */
+export interface TValidationCodeDoc {
+    code: string;
+    severity: 'error' | 'warning';
+    title: string;
+    description: string;
+    category: 'structural' | 'naming' | 'connection' | 'type' | 'node-ref' | 'graph' | 'data-flow' | 'agent';
+}
+export declare const VALIDATION_CODES: TValidationCodeDoc[];
+//# sourceMappingURL=error-codes.d.ts.map

package/dist/doc-metadata/extractors/error-codes.js

@@ -0,0 +1,272 @@
+/**
+ * Single source of truth for validation error code documentation.
+ *
+ * Every code the validator (src/validator.ts) and agent rules
+ * (src/validation/agent-rules.ts) can emit is listed here.
+ *
+ * The generate-docs script uses this to build the summary tables
+ * in docs/reference/error-codes.md.
+ */
+export const 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',
+    },
+    // ── 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: 'UNDEFINED_NODE',
+        severity: 'error',
+        title: 'Undefined Node',
+        description: 'Connection references node with no instance',
+        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: 'MULTIPLE_EXIT_CONNECTIONS',
+        severity: 'warning',
+        title: 'Multiple Exit Connections',
+        description: 'Exit port has multiple sources',
+        category: 'data-flow',
+    },
+    // ── 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',
+    },
+];
+//# sourceMappingURL=error-codes.js.map

package/dist/doc-metadata/extractors/grammar-rules.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Extractor for grammar rule documentation.
+ *
+ * Generates EBNF text and terminal definitions from the Chevrotain parsers
+ * so the jsdoc-grammar.md reference doc stays in sync with source code.
+ */
+import { type GrammarCollection } from '../../chevrotain-parser/grammar-diagrams.js';
+export interface TGrammarGroupDoc {
+    /** Grammar group name matching GrammarCollection keys */
+    name: keyof GrammarCollection;
+    /** EBNF text for this group */
+    ebnf: string;
+}
+export interface TTerminalDoc {
+    name: string;
+    pattern: string;
+    description: string;
+}
+/**
+ * Extract EBNF for all grammar groups.
+ */
+export declare function extractGrammarEBNF(): TGrammarGroupDoc[];
+/**
+ * Extract terminal pattern definitions for the Terminals section of docs.
+ *
+ * These are the key token patterns from tokens.ts that users need to know.
+ */
+export declare function extractTerminals(): TTerminalDoc[];
+//# sourceMappingURL=grammar-rules.d.ts.map

package/dist/doc-metadata/extractors/grammar-rules.js

@@ -0,0 +1,51 @@
+/**
+ * Extractor for grammar rule documentation.
+ *
+ * Generates EBNF text and terminal definitions from the Chevrotain parsers
+ * so the jsdoc-grammar.md reference doc stays in sync with source code.
+ */
+import { getAllGrammars, serializedToEBNF, } from '../../chevrotain-parser/grammar-diagrams.js';
+/**
+ * Extract EBNF for all grammar groups.
+ */
+export 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: name, ebnf });
+        }
+    }
+    return groups;
+}
+/**
+ * Extract terminal pattern definitions for the Terminals section of docs.
+ *
+ * These are the key token patterns from tokens.ts that users need to know.
+ */
+export 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).',
+        },
+    ];
+}
+//# sourceMappingURL=grammar-rules.js.map

package/dist/doc-metadata/index.d.ts

@@ -1,5 +1,10 @@
 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 type { TValidationCodeDoc } from './extractors/error-codes.js';
+export { extractGrammarEBNF, extractTerminals } from './extractors/grammar-rules.js';
+export type { TGrammarGroupDoc, TTerminalDoc } from './extractors/grammar-rules.js';
 export type { TMcpToolDoc, TMcpToolParam, TPluginApiFieldDoc, TCliCommandDoc, TCliOptionDoc } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/doc-metadata/index.js

@@ -1,4 +1,7 @@
 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';
 //# sourceMappingURL=index.js.map

package/dist/friendly-errors.js

@@ -24,6 +24,22 @@ function extractCyclePath(message) {
     return match ? match[1] : null;
 }
 const errorMappers = {
+    MISSING_WORKFLOW_NAME(error) {
+        return {
+            title: 'Missing Workflow Name',
+            explanation: 'The workflow annotation is missing or has no name. Every workflow needs a name in the @flowWeaver workflow block.',
+            fix: 'Add @flowWeaver workflow to the JSDoc block above your exported workflow function.',
+            code: error.code,
+        };
+    },
+    MISSING_FUNCTION_NAME(error) {
+        return {
+            title: 'Missing Function Name',
+            explanation: 'The compiler found a @flowWeaver workflow annotation but the function is anonymous or not exported.',
+            fix: 'Make sure your workflow is declared as `export function myWorkflowName(...)` — not anonymous or unexported.',
+            code: error.code,
+        };
+    },
     MISSING_REQUIRED_INPUT(error) {
         const quoted = extractQuoted(error.message);
         const nodeName = quoted[0] || error.node || 'unknown';
@@ -170,6 +186,58 @@ const errorMappers = {
             code: error.code,
         };
     },
+    RESERVED_INSTANCE_ID(error) {
+        const quoted = extractQuoted(error.message);
+        const instanceId = quoted[0] || error.node || 'unknown';
+        return {
+            title: 'Reserved Instance ID',
+            explanation: `Instance ID '${instanceId}' is reserved. 'Start' and 'Exit' are built-in nodes in every workflow.`,
+            fix: `Choose a different instance ID, like 'startHandler' or 'exitProcessor'.`,
+            code: error.code,
+        };
+    },
+    INFERRED_NODE_TYPE(error) {
+        const quoted = extractQuoted(error.message);
+        const nodeTypeName = quoted[0] || error.node || 'unknown';
+        return {
+            title: 'Inferred Node Type',
+            explanation: `Node type '${nodeTypeName}' was auto-inferred from the function signature. It works, but you lose explicit control over port names, types, and ordering.`,
+            fix: `Add /** @flowWeaver nodeType @expression */ above the function for explicit port control.`,
+            code: error.code,
+        };
+    },
+    UNDEFINED_NODE(error) {
+        const quoted = extractQuoted(error.message);
+        const nodeName = quoted[0] || error.node || 'unknown';
+        return {
+            title: 'Undefined Node',
+            explanation: `A connection references node '${nodeName}', but there's no @node annotation defining it.`,
+            fix: `Add a @node annotation for '${nodeName}' in the workflow JSDoc, or remove the connections that reference it.`,
+            code: error.code,
+        };
+    },
+    TYPE_INCOMPATIBLE(error) {
+        const types = extractTypes(error.message);
+        const source = types?.source || 'unknown';
+        const target = types?.target || 'unknown';
+        return {
+            title: 'Type Incompatible',
+            explanation: `Type mismatch: ${source} to ${target}. With @strictTypes enabled, this is an error instead of a warning.`,
+            fix: `Add a conversion node between the ports, change one of the port types, or remove @strictTypes to allow implicit coercions.`,
+            code: error.code,
+        };
+    },
+    UNUSUAL_TYPE_COERCION(error) {
+        const types = extractTypes(error.message);
+        const source = types?.source || 'unknown';
+        const target = types?.target || 'unknown';
+        return {
+            title: 'Unusual Type Coercion',
+            explanation: `Converting ${source} to ${target} is technically valid but semantically unusual and may produce unexpected behavior.`,
+            fix: `Add an explicit conversion node if this is intentional, or use @strictTypes to enforce type safety.`,
+            code: error.code,
+        };
+    },
     MULTIPLE_CONNECTIONS_TO_INPUT(error) {
         const quoted = extractQuoted(error.message);
         const portName = quoted[0] || 'unknown';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synergenius/flow-weaver",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "TypeScript annotation-based workflow compiler for Flow Weaver",
   "private": false,
   "type": "module",
@@ -26,6 +26,10 @@
     "./describe": {
       "types": "./dist/cli/commands/describe.d.ts",
       "default": "./dist/cli/commands/describe.js"
+    },
+    "./doc-metadata": {
+      "types": "./dist/doc-metadata/index.d.ts",
+      "default": "./dist/doc-metadata/index.js"
     }
   },
   "bin": {
@@ -34,12 +38,15 @@
   "files": [
     "dist",
     "!dist/**/*.map",
+    "docs/reference",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
     "build": "rimraf dist .tsbuildinfo && tsc -p tsconfig.build.json && npm run build:cli",
-    "postbuild": "npx tsx scripts/postbuild.ts",
+    "postbuild": "npx tsx scripts/postbuild.ts && npm run generate:docs",
+    "generate:docs": "tsx scripts/generate-docs.ts",
+    "generate:docs:check": "tsx scripts/generate-docs.ts --check",
     "build:cli": "npx tsx scripts/build-cli.ts",
     "watch": "tsc -p tsconfig.build.json --watch --preserveWatchOutput --incremental",
     "test": "vitest run",