@synergenius/flow-weaver 0.20.1 → 0.20.2

package/dist/cli/index.js

@@ -39,6 +39,7 @@ import { docsListCommand, docsReadCommand, docsSearchCommand } from './commands/
 import { contextCommand } from './commands/context.js';
 import { statusCommand } from './commands/status.js';
 import { implementCommand } from './commands/implement.js';
+import { modifyAddNodeCommand, modifyRemoveNodeCommand, modifyAddConnectionCommand, modifyRemoveConnectionCommand, modifyRenameNodeCommand, modifySetPositionCommand, modifySetLabelCommand, } from './commands/modify.js';
 import { marketInitCommand, marketPackCommand, marketPublishCommand, marketInstallCommand, marketSearchCommand, marketListCommand, } from './commands/market.js';
 import { mcpSetupCommand } from './commands/mcp-setup.js';
 import { logger } from './utils/logger.js';
@@ -352,6 +353,71 @@ createCmd
     .action(wrapAction(async (name, file, options) => {
     await createNodeCommand(name, file, options);
 }));
+// Modify command (with subcommands)
+const modifyCmd = program.command('modify').description('Modify workflow structure');
+modifyCmd
+    .command('addNode')
+    .description('Add a node instance to a workflow')
+    .requiredOption('--file <path>', 'Workflow file')
+    .requiredOption('--nodeId <id>', 'Node instance ID')
+    .requiredOption('--nodeType <type>', 'Node type name')
+    .action(wrapAction(async (options) => {
+    await modifyAddNodeCommand(options.file, options);
+}));
+modifyCmd
+    .command('removeNode')
+    .description('Remove a node instance from a workflow')
+    .requiredOption('--file <path>', 'Workflow file')
+    .requiredOption('--nodeId <id>', 'Node instance ID')
+    .action(wrapAction(async (options) => {
+    await modifyRemoveNodeCommand(options.file, options);
+}));
+modifyCmd
+    .command('addConnection')
+    .description('Add a connection between nodes')
+    .requiredOption('--file <path>', 'Workflow file')
+    .requiredOption('--from <node.port>', 'Source (e.g. nodeA.output)')
+    .requiredOption('--to <node.port>', 'Target (e.g. nodeB.input)')
+    .action(wrapAction(async (options) => {
+    await modifyAddConnectionCommand(options.file, options);
+}));
+modifyCmd
+    .command('removeConnection')
+    .description('Remove a connection between nodes')
+    .requiredOption('--file <path>', 'Workflow file')
+    .requiredOption('--from <node.port>', 'Source (e.g. nodeA.output)')
+    .requiredOption('--to <node.port>', 'Target (e.g. nodeB.input)')
+    .action(wrapAction(async (options) => {
+    await modifyRemoveConnectionCommand(options.file, options);
+}));
+modifyCmd
+    .command('renameNode')
+    .description('Rename a node instance (updates all connections)')
+    .requiredOption('--file <path>', 'Workflow file')
+    .requiredOption('--oldId <id>', 'Current node ID')
+    .requiredOption('--newId <id>', 'New node ID')
+    .action(wrapAction(async (options) => {
+    await modifyRenameNodeCommand(options.file, options);
+}));
+modifyCmd
+    .command('setPosition')
+    .description('Set position of a node instance')
+    .requiredOption('--file <path>', 'Workflow file')
+    .requiredOption('--nodeId <id>', 'Node instance ID')
+    .requiredOption('--x <number>', 'X coordinate')
+    .requiredOption('--y <number>', 'Y coordinate')
+    .action(wrapAction(async (options) => {
+    await modifySetPositionCommand(options.file, options);
+}));
+modifyCmd
+    .command('setLabel')
+    .description('Set display label for a node instance')
+    .requiredOption('--file <path>', 'Workflow file')
+    .requiredOption('--nodeId <id>', 'Node instance ID')
+    .requiredOption('--label <text>', 'Display label')
+    .action(wrapAction(async (options) => {
+    await modifySetLabelCommand(options.file, options);
+}));
 // Templates command
 program
     .command('templates')
@@ -503,14 +569,19 @@ program
 }));
 // Implement command
 program
-    .command('implement <input> <node>')
+    .command('implement <input> [node]')
     .description('Replace a stub node with a real function skeleton')
     .option('-w, --workflow <name>', 'Specific workflow name')
+    .option('--nodeId <id>', 'Node to implement (alternative to positional arg)')
     .option('-p, --preview', 'Preview the generated code without writing', false)
     .action(wrapAction(async (input, node, options) => {
+    const nodeName = node ?? options.nodeId;
+    if (!nodeName) {
+        throw new Error('Node name is required (as positional arg or --nodeId flag)');
+    }
     if (options.workflow)
         options.workflowName = options.workflow;
-    await implementCommand(input, node, options);
+    await implementCommand(input, nodeName, options);
 }));
 // Changelog command
 program

package/dist/generated-version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.20.1";
+export declare const VERSION = "0.20.2";
 //# sourceMappingURL=generated-version.d.ts.map

package/dist/generated-version.js

@@ -1,3 +1,3 @@
 // Auto-generated by scripts/generate-version.ts — do not edit manually
-export const VERSION = '0.20.1';
+export const VERSION = '0.20.2';
 //# sourceMappingURL=generated-version.js.map

package/dist/jsdoc-parser.d.ts

@@ -88,6 +88,7 @@ export interface JSDocWorkflowConfig {
         job?: string;
         /** CI/CD deployment environment */
         environment?: string;
+        suppressWarnings?: string[];
     }>;
     connections?: Array<{
         from: {

package/dist/jsdoc-parser.js

@@ -850,7 +850,7 @@ export class JSDocParser {
         if (!result) {
             return;
         }
-        const { instanceId, nodeType, parentScope, label, expressions, portOrder, portLabel, minimized, pullExecution, size, position, color, icon, tags, job, environment, } = result;
+        const { instanceId, nodeType, parentScope, label, expressions, portOrder, portLabel, minimized, pullExecution, size, position, color, icon, tags, job, environment, suppress, } = result;
         // Capture source location from tag
         const line = tag.getStartLineNumber();
         // Build portConfigs from portOrder, portLabel, and expressions
@@ -900,6 +900,7 @@ export class JSDocParser {
             ...(position && { x: position.x, y: position.y }),
             ...(job && { job }),
             ...(environment && { environment }),
+            ...(suppress && suppress.length > 0 && { suppressWarnings: suppress }),
             sourceLocation: { line, column: 0 },
         });
     }

package/dist/mcp/tools-pattern.js

@@ -7,191 +7,12 @@ import { listPatterns, applyPattern, findWorkflows, extractPattern } from '../ap
 import { generateInPlace } from '../api/generate-in-place.js';
 import { applyMigrations, getRegisteredMigrations } from '../migration/registry.js';
 import { describeWorkflow, formatDescribeOutput } from '../cli/commands/describe.js';
+import { applyModifyOperation, validateModifyParams } from '../api/modify-operation.js';
 import { addNode as manipAddNode, removeNode as manipRemoveNode, renameNode as manipRenameNode, addConnection as manipAddConnection, removeConnection as manipRemoveConnection, setNodePosition as manipSetNodePosition, setNodeLabel as manipSetNodeLabel, } from '../api/manipulation/index.js';
 import { findIsolatedNodes } from '../api/query.js';
 import { AnnotationParser } from '../parser.js';
 import { makeToolResult, makeErrorResult, addHintsToItems } from './response-utils.js';
 import { getFriendlyError } from '../friendly-errors.js';
-// Runtime validation schemas for fw_modify operations
-const modifyParamsSchemas = {
-    addNode: z.object({
-        nodeId: z.string({ required_error: 'nodeId is required' }),
-        nodeType: z.string({ required_error: 'nodeType is required' }),
-        x: z.number().optional(),
-        y: z.number().optional(),
-    }),
-    removeNode: z.object({
-        nodeId: z.string({ required_error: 'nodeId is required' }),
-    }),
-    renameNode: z.object({
-        oldId: z.string({ required_error: 'oldId is required' }),
-        newId: z.string({ required_error: 'newId is required' }),
-    }),
-    addConnection: z.object({
-        from: z.string({ required_error: 'from is required (format: "node.port")' }),
-        to: z.string({ required_error: 'to is required (format: "node.port")' }),
-    }),
-    removeConnection: z.object({
-        from: z.string({ required_error: 'from is required (format: "node.port")' }),
-        to: z.string({ required_error: 'to is required (format: "node.port")' }),
-    }),
-    setNodePosition: z.object({
-        nodeId: z.string({ required_error: 'nodeId is required' }),
-        x: z.number({ required_error: 'x is required', invalid_type_error: 'x must be a number' }),
-        y: z.number({ required_error: 'y is required', invalid_type_error: 'y must be a number' }),
-    }),
-    setNodeLabel: z.object({
-        nodeId: z.string({ required_error: 'nodeId is required' }),
-        label: z.string({ required_error: 'label is required' }),
-    }),
-};
-function validateModifyParams(operation, params) {
-    const schema = modifyParamsSchemas[operation];
-    if (!schema) {
-        return { success: false, error: `Unknown operation: ${operation}` };
-    }
-    const result = schema.safeParse(params);
-    if (!result.success) {
-        const messages = result.error.issues.map((i) => i.message).join('; ');
-        return { success: false, error: `${operation} params invalid: ${messages}` };
-    }
-    return { success: true };
-}
-/**
- * Apply a single modify operation to an AST.
- * Shared by fw_modify and fw_modify_batch.
- */
-function applyModifyOperation(ast, operation, params) {
-    const p = params;
-    const warnings = [];
-    const extraData = {};
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- AST manipulation functions use loose typing
-    let modifiedAST = ast;
-    switch (operation) {
-        case 'addNode': {
-            const nodeId = p.nodeId;
-            const nodeType = p.nodeType;
-            const nodeTypeExists = modifiedAST.nodeTypes.some((nt) => nt.name === nodeType || nt.functionName === nodeType);
-            if (!nodeTypeExists) {
-                warnings.push(`Node type "${nodeType}" is not defined in the file. ` +
-                    `The node will be added but may not render until the type is defined.`);
-            }
-            let autoX = typeof p.x === 'number' ? p.x : undefined;
-            let autoY = typeof p.y === 'number' ? p.y : undefined;
-            if (autoX === undefined || autoY === undefined) {
-                const positions = modifiedAST.instances
-                    .map((inst) => inst.config)
-                    .filter((c) => c !== undefined &&
-                    c !== null &&
-                    typeof c.x === 'number' &&
-                    typeof c.y === 'number');
-                if (positions.length > 0) {
-                    const maxX = Math.max(...positions.map((pos) => pos.x));
-                    if (autoX === undefined)
-                        autoX = maxX + 180;
-                    if (autoY === undefined)
-                        autoY = 0;
-                }
-                else {
-                    if (autoX === undefined)
-                        autoX = 0;
-                    if (autoY === undefined)
-                        autoY = 0;
-                }
-            }
-            modifiedAST = manipAddNode(modifiedAST, {
-                type: 'NodeInstance',
-                id: nodeId,
-                nodeType,
-                config: { x: autoX, y: autoY },
-            });
-            break;
-        }
-        case 'removeNode': {
-            const nodeId = p.nodeId;
-            const removedConnections = modifiedAST.connections
-                .filter((c) => c.from.node === nodeId || c.to.node === nodeId)
-                .map((c) => ({
-                from: `${c.from.node}.${c.from.port}`,
-                to: `${c.to.node}.${c.to.port}`,
-            }));
-            modifiedAST = manipRemoveNode(modifiedAST, nodeId);
-            if (removedConnections.length > 0) {
-                extraData.removedConnections = removedConnections;
-            }
-            break;
-        }
-        case 'renameNode': {
-            modifiedAST = manipRenameNode(modifiedAST, p.oldId, p.newId);
-            break;
-        }
-        case 'addConnection': {
-            const from = p.from;
-            const to = p.to;
-            const [fromNode, fromPort] = from.split('.');
-            const [toNode, toPort] = to.split('.');
-            if (!fromPort || !toPort) {
-                throw new Error('Connection format must be "node.port" (e.g., "Start.execute")');
-            }
-            const validNodes = [
-                'Start',
-                'Exit',
-                ...modifiedAST.instances.map((i) => i.id),
-            ];
-            if (!validNodes.includes(fromNode)) {
-                throw new Error(`Source node "${fromNode}" not found. Available: ${validNodes.join(', ')}`);
-            }
-            if (!validNodes.includes(toNode)) {
-                throw new Error(`Target node "${toNode}" not found. Available: ${validNodes.join(', ')}`);
-            }
-            if (fromNode !== 'Start' && fromNode !== 'Exit') {
-                const inst = modifiedAST.instances.find((i) => i.id === fromNode);
-                const nt = modifiedAST.nodeTypes.find((t) => t.name === inst?.nodeType);
-                if (nt && !nt.outputs[fromPort]) {
-                    throw new Error(`Node "${fromNode}" has no output "${fromPort}". Available: ${Object.keys(nt.outputs).join(', ')}`);
-                }
-            }
-            if (toNode !== 'Start' && toNode !== 'Exit') {
-                const inst = modifiedAST.instances.find((i) => i.id === toNode);
-                const nt = modifiedAST.nodeTypes.find((t) => t.name === inst?.nodeType);
-                if (nt && !nt.inputs[toPort]) {
-                    throw new Error(`Node "${toNode}" has no input "${toPort}". Available: ${Object.keys(nt.inputs).join(', ')}`);
-                }
-            }
-            modifiedAST = manipAddConnection(modifiedAST, from, to);
-            // Transition from autoConnect to explicit mode when connections are manually modified
-            if (modifiedAST.options?.autoConnect) {
-                modifiedAST = { ...modifiedAST, options: { ...modifiedAST.options, autoConnect: undefined } };
-                warnings.push('autoConnect was disabled because connections were manually modified');
-            }
-            break;
-        }
-        case 'removeConnection': {
-            modifiedAST = manipRemoveConnection(modifiedAST, p.from, p.to);
-            // Transition from autoConnect to explicit mode when connections are manually modified
-            if (modifiedAST.options?.autoConnect) {
-                modifiedAST = { ...modifiedAST, options: { ...modifiedAST.options, autoConnect: undefined } };
-                warnings.push('autoConnect was disabled because connections were manually modified');
-            }
-            const newlyIsolated = findIsolatedNodes(modifiedAST);
-            if (newlyIsolated.length > 0) {
-                extraData.newlyIsolatedNodes = newlyIsolated;
-            }
-            break;
-        }
-        case 'setNodePosition': {
-            modifiedAST = manipSetNodePosition(modifiedAST, p.nodeId, p.x, p.y);
-            break;
-        }
-        case 'setNodeLabel': {
-            modifiedAST = manipSetNodeLabel(modifiedAST, p.nodeId, p.label);
-            break;
-        }
-        default:
-            throw new Error(`Unknown operation: ${operation}`);
-    }
-    return { ast: modifiedAST, warnings, extraData };
-}
 export function registerPatternTools(mcp) {
     mcp.tool('fw_list_patterns', 'List reusable patterns defined in a file.', {
         filePath: z.string().describe('Path to file containing patterns'),

package/dist/parser.js

@@ -970,6 +970,7 @@ export class AnnotationParser {
                         ...(inst.tags && inst.tags.length > 0 && { tags: inst.tags }),
                         ...(inst.width && { width: inst.width }),
                         ...(inst.height && { height: inst.height }),
+                        ...(inst.suppressWarnings?.length && { suppressWarnings: inst.suppressWarnings }),
                     },
                     ...(inst.sourceLocation && {
                         sourceLocation: { file: filePath, ...inst.sourceLocation },

package/dist/validator.js

@@ -228,6 +228,21 @@ export class WorkflowValidator {
             });
             this.warnings.push(...promoted);
         }
+        // Filter out warnings suppressed by per-instance [suppress: "CODE"] annotations
+        const suppressMap = new Map();
+        for (const inst of workflow.instances) {
+            if (inst.config?.suppressWarnings?.length) {
+                suppressMap.set(inst.id, new Set(inst.config.suppressWarnings));
+            }
+        }
+        if (suppressMap.size > 0) {
+            this.warnings = this.warnings.filter((w) => {
+                if (!w.node)
+                    return true;
+                const codes = suppressMap.get(w.node);
+                return !codes || !codes.has(w.code);
+            });
+        }
         // Attach doc URLs to diagnostics that have mapped error codes
         for (const diag of [...this.errors, ...this.warnings]) {
             if (!diag.docUrl && ERROR_DOC_URLS[diag.code]) {

package/docs/reference/advanced-annotations.md

@@ -423,6 +423,17 @@ Visual tags/badges on the instance. Each tag has a label string and optional too
 @node myNode MyType [tags: "async" "Runs asynchronously", "beta"]
 ```
 
+### Suppress Warnings (`[suppress: ...]`)
+
+Silences specific validator warnings on a per-instance basis. Useful when a warning is intentional, such as output ports that are deliberately left unconnected in CI/CD workflows where data is discarded by design.
+
+```typescript
+@node fetch fetchData [suppress: "UNUSED_OUTPUT_PORT"]
+@node check runCheck [suppress: "UNUSED_OUTPUT_PORT", "UNREACHABLE_EXIT_PORT"]
+```
+
+The suppression is scoped to the annotated instance only. Other instances of the same type still produce warnings normally. The codes correspond to the warning codes listed in the error codes reference.
+
 ### Combining Attributes
 
 Multiple attribute brackets can appear on the same `@node`:

package/docs/reference/cli-reference.md

@@ -1,7 +1,7 @@
 ---
 name: CLI Reference
 description: Complete reference for all Flow Weaver CLI commands, flags, and options
-keywords: [cli, commands, compile, validate, strip, run, watch, dev, serve, export, diagram, diff, doctor, init, migrate, marketplace, plugin, grammar, changelog, openapi, pattern, create, templates, context]
+keywords: [cli, commands, compile, validate, strip, run, watch, dev, serve, export, diagram, diff, doctor, init, migrate, marketplace, plugin, grammar, changelog, openapi, pattern, create, templates, context, modify, implement, status]
 ---
 
 # CLI Reference
@@ -34,6 +34,9 @@ Complete reference for all `flow-weaver` CLI commands.
 | `changelog` | Generate changelog from git |
 | `market` | Marketplace packages |
 | `plugin` | External plugins |
+| `modify` | Add/remove/rename nodes, connections, positions, and labels |
+| `implement` | Replace stub node with function skeleton |
+| `status` | Report implementation progress |
 | `context` | Generate LLM context bundle |
 | `docs` | Browse reference documentation |
 | `ui` | Send commands to the editor |
@@ -475,6 +478,120 @@ flow-weaver create node checker my-workflow.ts --template validator
 
 ---
 
+### modify
+
+Modify workflow structure programmatically. Parses the file, applies the operation, and regenerates the JSDoc annotations in place. Useful for scripting, CI pipelines, and the genesis self-evolution system.
+
+#### modify addNode
+
+```bash
+flow-weaver modify addNode --file <path> --nodeId <id> --nodeType <type>
+```
+
+Adds a new node instance to the workflow. Auto-positions to the right of the rightmost existing node. Warns if the node type isn't defined in the file.
+
+#### modify removeNode
+
+```bash
+flow-weaver modify removeNode --file <path> --nodeId <id>
+```
+
+Removes a node instance and all connections attached to it.
+
+#### modify addConnection
+
+```bash
+flow-weaver modify addConnection --file <path> --from <node.port> --to <node.port>
+```
+
+Adds a connection between two ports. Both nodes must exist. Port names are validated against the node type definition when available.
+
+#### modify removeConnection
+
+```bash
+flow-weaver modify removeConnection --file <path> --from <node.port> --to <node.port>
+```
+
+Removes an existing connection.
+
+#### modify renameNode
+
+```bash
+flow-weaver modify renameNode --file <path> --oldId <id> --newId <id>
+```
+
+Renames a node instance and updates all connections that reference it.
+
+#### modify setPosition
+
+```bash
+flow-weaver modify setPosition --file <path> --nodeId <id> --x <number> --y <number>
+```
+
+Sets the canvas position of a node instance.
+
+#### modify setLabel
+
+```bash
+flow-weaver modify setLabel --file <path> --nodeId <id> --label <text>
+```
+
+Sets the display label for a node instance.
+
+**Examples:**
+```bash
+flow-weaver modify addNode --file workflow.ts --nodeId validator --nodeType validateInput
+flow-weaver modify addConnection --file workflow.ts --from Start.data --to validator.input
+flow-weaver modify removeNode --file workflow.ts --nodeId oldStep
+flow-weaver modify removeConnection --file workflow.ts --from a.output --to b.input
+flow-weaver modify renameNode --file workflow.ts --oldId step1 --newId validateStep
+flow-weaver modify setPosition --file workflow.ts --nodeId step1 --x 200 --y 100
+flow-weaver modify setLabel --file workflow.ts --nodeId step1 --label "Validate Input"
+```
+
+---
+
+### implement
+
+Replace a stub node (`declare function`) with a real function skeleton containing the correct signature, JSDoc annotations, and return type.
+
+```bash
+flow-weaver implement <input> <node> [options]
+flow-weaver implement <input> --nodeId <id> [options]
+```
+
+The node can be specified as a positional argument or with the `--nodeId` flag.
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-w, --workflow <name>` | Specific workflow name | — |
+| `--nodeId <id>` | Node to implement (alternative to positional arg) | — |
+| `-p, --preview` | Preview without writing | `false` |
+
+**Examples:**
+```bash
+flow-weaver implement workflow.ts validateInput
+flow-weaver implement workflow.ts --nodeId validateInput
+flow-weaver implement workflow.ts myNode --preview
+```
+
+---
+
+### status
+
+Report implementation progress for stub workflows. Shows which nodes are implemented vs still declared as stubs.
+
+```bash
+flow-weaver status <input> [options]
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-w, --workflow <name>` | Specific workflow name | — |
+| `--json` | Output as JSON | `false` |
+
+---
+
 ### templates
 
 List available workflow and node templates.

package/docs/reference/error-codes.md

@@ -540,7 +540,7 @@ const fetchData = (execute: boolean, url: string, apiKey: string) => { ... };
 | Severity      | Warning                                                                                                                                                                                                                                 |
 | Meaning       | A node's data output port is never connected to anything. The data produced by this port is discarded.                                                                                                                                  |
 | Common Causes | The node produces an output that is not needed by the current workflow. A connection from this port was removed but the port still exists. Control flow ports (`onSuccess`, `onFailure`) and scoped ports are excluded from this check. |
-| Fix           | If the output is needed, connect it to a downstream node or to `Exit`. If not needed, the warning can be ignored, but it may indicate an incomplete workflow.                                                                           |
+| Fix           | If the output is needed, connect it to a downstream node or to `Exit`. If the output is intentionally discarded, add `[suppress: "UNUSED_OUTPUT_PORT"]` to the `@node` annotation to silence this warning for that instance. |
 
 #### UNREACHABLE_EXIT_PORT (warning)
 

package/docs/reference/jsdoc-grammar.md

@@ -212,8 +212,8 @@ attributeBracket ::= "[" nodeAttr { "," nodeAttr } "]"
 
 nodeAttr       ::= labelAttr | exprAttr | portOrderAttr | portLabelAttr
                  | minimizedAttr | pullExecutionAttr | sizeAttr
-                 | colorAttr | iconAttr | tagsAttr | positionAttr
-                 | jobAttr | environmentAttr
+                 | colorAttr | iconAttr | tagsAttr | suppressAttr
+                 | positionAttr | jobAttr | environmentAttr
 
 labelAttr      ::= "label:" STRING
 exprAttr       ::= "expr:" IDENTIFIER "=" STRING { "," IDENTIFIER "=" STRING }
@@ -229,6 +229,7 @@ tagEntry       ::= STRING [ STRING ]
 positionAttr   ::= "position:" INTEGER INTEGER
 jobAttr        ::= "job:" STRING
 environmentAttr ::= "environment:" STRING
+suppressAttr   ::= "suppress:" STRING { "," STRING }
 ```
 
 Multiple attribute brackets are allowed (zero or more). Attributes can be split across brackets or combined in one.
@@ -250,6 +251,7 @@ Multiple attribute brackets are allowed (zero or more). Attributes can be split
 @node myAdd Add [label: "hi"] [color: "#f00"] [position: 360 0]
 @node build npmBuild [job: "build"]
 @node deploy deploySsh [job: "deploy"] [environment: "production"]
+@node fetch fetchData [suppress: "UNUSED_OUTPUT_PORT"]
 ```
 
 ## @connect

package/docs/reference/marketplace.md

@@ -159,6 +159,80 @@ The `market pack` command validates packages against additional rules beyond sta
 
 ---
 
+## Custom Tag Handlers
+
+Tag handlers let packs extend the parser with custom JSDoc annotations. When the parser encounters a tag it doesn't recognize natively, it delegates to registered pack handlers before emitting "Unknown annotation" warnings.
+
+The CI/CD pack (`flowweaver-pack-cicd`) is the primary example: it registers handlers for `@secret`, `@runner`, `@cache`, `@artifact`, and other CI/CD tags.
+
+### Writing a handler
+
+A tag handler is a function matching the `TTagHandlerFn` signature:
+
+```typescript
+import type { TTagHandlerFn } from '@synergenius/flow-weaver/api';
+
+export const myHandler: TTagHandlerFn = (tagName, comment, ctx) => {
+  // tagName: the tag without '@', e.g. "secret"
+  // comment: everything after the tag on that line
+  // ctx.deploy: the deploy map for your namespace (mutate it directly)
+  // ctx.warnings: push parser warnings here
+
+  const value = comment.trim();
+  if (!value) {
+    ctx.warnings.push(`Empty @${tagName} tag`);
+    return;
+  }
+
+  const items = (ctx.deploy['items'] as string[]) ?? [];
+  items.push(value);
+  ctx.deploy['items'] = items;
+};
+```
+
+The handler receives one call per tag occurrence. Parsed data goes into `ctx.deploy`, which maps to `workflow.deploy[namespace]` or `nodeType.deploy[namespace]` in the final AST.
+
+### Declaring handlers in the manifest
+
+Add a `tagHandlers` entry to your `flowweaver.manifest.json`:
+
+```json
+{
+  "manifestVersion": 2,
+  "tagHandlers": [
+    {
+      "tags": ["secret", "runner", "cache"],
+      "namespace": "cicd",
+      "scope": "both",
+      "file": "dist/tag-handler.js",
+      "exportName": "cicdTagHandler"
+    }
+  ]
+}
+```
+
+Fields:
+
+| Field | Description |
+|-------|-------------|
+| `tags` | Tag names this handler processes (without the `@` prefix) |
+| `namespace` | Key in the deploy map where parsed data is stored |
+| `scope` | `workflow` for workflow-level tags, `nodeType` for node type tags, `both` for either |
+| `file` | Relative path to the compiled JS file exporting the handler |
+| `exportName` | Named export from the file (omit for `default` export) |
+
+### Handler scope
+
+A handler scoped to `workflow` only runs for tags inside `@flowWeaver workflow` blocks. A handler scoped to `nodeType` only runs inside `@flowWeaver nodeType` blocks. Use `both` when your tags are valid in either context.
+
+If a tag appears in the wrong scope, the parser emits a warning and skips the handler call.
+
+### How discovery works
+
+When `parseWorkflow()` is called with a `projectDir` option (or when the CLI runs from a project directory), the parser scans `node_modules` for installed packs with a `flowweaver.manifest.json`. It reads the `tagHandlers` array from each manifest, dynamically imports the handler files, and registers them in the `TagHandlerRegistry`. This scan runs once per project directory and is cached for subsequent parse calls.
+
+---
+
 ## External Plugins
 
 Plugins extend the Flow Weaver Studio IDE with custom UI components, system logic, and integrations.

package/package.json

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