@synergenius/flow-weaver 0.20.0 → 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/cli/pack-commands.js

@@ -9,18 +9,8 @@
  * when the user actually invokes a pack command.
  */
 import * as path from 'path';
-import { createRequire } from 'node:module';
 import { listInstalledPackages } from '../marketplace/registry.js';
-function getEngineVersion() {
-    try {
-        const req = createRequire(import.meta.url);
-        const pkg = req('../../package.json');
-        return pkg.version;
-    }
-    catch {
-        return '0.0.0';
-    }
-}
+import { VERSION } from '../generated-version.js';
 function compareVersions(a, b) {
     const pa = a.split('.').map(Number);
     const pb = b.split('.').map(Number);
@@ -36,9 +26,7 @@ function checkPackEngineVersion(pkg) {
     if (!required)
         return;
     const minVersion = required.replace(/^>=?\s*/, '');
-    const current = getEngineVersion();
-    if (current === '0.0.0')
-        return; // dev mode, skip check
+    const current = VERSION;
     if (compareVersions(current, minVersion) < 0) {
         console.warn(`\x1b[33mWarning: ${pkg.name} requires flow-weaver >=${minVersion} but ${current} is installed.\x1b[0m`);
         console.warn(`\x1b[33mRun: npm install @synergenius/flow-weaver@latest\x1b[0m`);

package/dist/diagram/geometry.js

@@ -699,8 +699,8 @@ export function buildDiagramGraph(ast, options = {}) {
     // Build diagram nodes
     const diagramNodes = new Map();
     // Start node — ensure mandatory execute STEP port exists
-    const allStartPorts = { ...ast.startPorts };
-    if (!allStartPorts.execute) {
+    const allStartPorts = filterHiddenPorts({ ...ast.startPorts });
+    if (!allStartPorts.execute && !ast.startPorts.execute?.hidden) {
         allStartPorts.execute = { dataType: 'STEP' };
     }
     const startOutputs = orderedPorts(allStartPorts, 'OUTPUT');
@@ -717,14 +717,14 @@ export function buildDiagramGraph(ast, options = {}) {
         height: NODE_MIN_HEIGHT,
     });
     // Exit node — ensure mandatory onSuccess/onFailure STEP ports exist
-    const allExitPorts = { ...ast.exitPorts };
-    if (!allExitPorts.onSuccess) {
+    const allExitPorts = filterHiddenPorts({ ...ast.exitPorts });
+    if (!allExitPorts.onSuccess && !ast.exitPorts.onSuccess?.hidden) {
         allExitPorts.onSuccess = { dataType: 'STEP', isControlFlow: true };
     }
-    if (!allExitPorts.onFailure) {
+    if (!allExitPorts.onFailure && !ast.exitPorts.onFailure?.hidden) {
         allExitPorts.onFailure = { dataType: 'STEP', isControlFlow: true, failure: true };
     }
-    else {
+    else if (allExitPorts.onFailure) {
         allExitPorts.onFailure = { ...allExitPorts.onFailure, failure: true };
     }
     const exitInputs = orderedPorts(allExitPorts, 'INPUT');

package/dist/generated-version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.20.0";
+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.0';
+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/pack-tools.js

@@ -5,18 +5,8 @@
  * imports the entrypoint and calls its registerMcpTools(mcp) function.
  */
 import * as path from 'path';
-import { createRequire } from 'node:module';
 import { listInstalledPackages } from '../marketplace/registry.js';
-function getEngineVersion() {
-    try {
-        const req = createRequire(import.meta.url);
-        const pkg = req('../../package.json');
-        return pkg.version;
-    }
-    catch {
-        return '0.0.0';
-    }
-}
+import { VERSION } from '../generated-version.js';
 function compareVersions(a, b) {
     const pa = a.split('.').map(Number);
     const pb = b.split('.').map(Number);
@@ -32,9 +22,7 @@ function checkPackEngineVersion(pkg) {
     if (!required)
         return;
     const minVersion = required.replace(/^>=?\s*/, '');
-    const current = getEngineVersion();
-    if (current === '0.0.0')
-        return;
+    const current = VERSION;
     if (compareVersions(current, minVersion) < 0) {
         process.stderr.write(`\x1b[33mWarning: ${pkg.name} requires flow-weaver >=${minVersion} but ${current} is installed.\x1b[0m\n`);
         process.stderr.write(`\x1b[33mRun: npm install @synergenius/flow-weaver@latest\x1b[0m\n`);

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