@synergenius/flow-weaver 0.17.10 → 0.17.12

package/dist/ast/types.d.ts

@@ -786,7 +786,7 @@ export type TNodeTagAST = {
 };
 /** Visual customization for node types */
 export type TNodeVisualsAST = {
-    /** Theme color: blue, purple, teal, orange, pink, green */
+    /** Theme color: blue, purple, cyan, orange, pink, green, red, yellow (teal is an alias for cyan) */
     color?: string;
     /** Icon preset name */
     icon?: string;

package/dist/cli/flow-weaver.mjs

@@ -9671,7 +9671,7 @@ var VERSION;
 var init_generated_version = __esm({
   "src/generated-version.ts"() {
     "use strict";
-    VERSION = "0.17.10";
+    VERSION = "0.17.12";
   }
 });
 
@@ -37889,7 +37889,7 @@ function darkenHex(hex, amount) {
   const nb = Math.round(b * (1 - amount));
   return `#${nr.toString(16).padStart(2, "0")}${ng.toString(16).padStart(2, "0")}${nb.toString(16).padStart(2, "0")}`;
 }
-var DARK_PORT_COLORS, LIGHT_PORT_COLORS, DARK_FAILURE_COLOR, LIGHT_FAILURE_COLOR, NODE_VARIANT_COLORS, DARK_PALETTE, LIGHT_PALETTE, TYPE_ABBREVIATIONS, NODE_ICON_PATHS, VALID_NODE_ICONS;
+var DARK_PORT_COLORS, LIGHT_PORT_COLORS, DARK_FAILURE_COLOR, LIGHT_FAILURE_COLOR, NODE_DEFAULT_COLOR, NODE_VARIANT_COLORS, DARK_PALETTE, LIGHT_PALETTE, TYPE_ABBREVIATIONS, NODE_ICON_PATHS, VALID_NODE_ICONS;
 var init_theme = __esm({
   "src/diagram/theme.ts"() {
     "use strict";
@@ -37931,6 +37931,7 @@ var init_theme = __esm({
     };
     DARK_FAILURE_COLOR = "#ff4f4f";
     LIGHT_FAILURE_COLOR = "#e34646";
+    NODE_DEFAULT_COLOR = "#334155";
     NODE_VARIANT_COLORS = {
       blue: { border: "#548ce3", darkBorder: "#5e9eff" },
       // blue-shade-2 / blue-dark-shade-1
@@ -37938,6 +37939,8 @@ var init_theme = __esm({
       // purple-shade-2 / purple-dark-shade-1
       cyan: { border: "#63ccc4", darkBorder: "#6fe5dc" },
       // cyan-shade-2 / cyan-dark-shade-1
+      teal: { border: "#63ccc4", darkBorder: "#6fe5dc" },
+      // alias for cyan
       orange: { border: "#e3732d", darkBorder: "#ff8133" },
       // orange-shade-2 / orange-dark-shade-1
       pink: { border: "#e349c2", darkBorder: "#ff52da" },
@@ -37946,10 +37949,8 @@ var init_theme = __esm({
       // green-shade-2 / green-dark-shade-1
       red: { border: "#e34646", darkBorder: "#ff4f4f" },
       // red-shade-2 / red-dark-shade-1
-      yellow: { border: "#e3a82b", darkBorder: "#ffbd30" },
+      yellow: { border: "#e3a82b", darkBorder: "#ffbd30" }
       // yellow-shade-2 / yellow-dark-shade-1
-      teal: { border: "#3db0a8", darkBorder: "#4dc7be" }
-      // teal-shade-2 / teal-dark-shade-1
     };
     DARK_PALETTE = {
       background: "#202139",
@@ -50852,7 +50853,7 @@ function buildDiagramGraph(ast, options = {}) {
   diagramNodes.set("Start", {
     id: "Start",
     label: "Start",
-    color: "#334155",
+    color: NODE_DEFAULT_COLOR,
     icon: "startNode",
     isVirtual: true,
     inputs: [],
@@ -50875,7 +50876,7 @@ function buildDiagramGraph(ast, options = {}) {
   diagramNodes.set("Exit", {
     id: "Exit",
     label: "Exit",
-    color: "#334155",
+    color: NODE_DEFAULT_COLOR,
     icon: "exitNode",
     isVirtual: true,
     inputs: exitInputs,
@@ -51181,7 +51182,7 @@ function filterNonScopedPorts(ports) {
   return result;
 }
 function resolveNodeColor(color, theme = "dark") {
-  if (!color) return "#334155";
+  if (!color) return NODE_DEFAULT_COLOR;
   const variant = NODE_VARIANT_COLORS[color];
   if (variant) return theme === "dark" ? variant.darkBorder : variant.border;
   return color;
@@ -51890,12 +51891,12 @@ function renderScopeConnection(parts2, conn, allConnections, parentNodeId) {
   );
 }
 function renderNodeBody(parts2, node, theme, indent) {
-  const strokeColor = node.color !== "#334155" ? node.color : theme.nodeIconColor;
+  const strokeColor = node.color !== NODE_DEFAULT_COLOR ? node.color : theme.nodeIconColor;
   parts2.push(
     `${indent}<rect x="${node.x}" y="${node.y}" width="${node.width}" height="${node.height}" rx="${BORDER_RADIUS}" fill="${theme.nodeFill}" stroke="${strokeColor}" stroke-width="2" filter="url(#node-shadow)"/>`
   );
   const iconPath = NODE_ICON_PATHS[node.icon] ?? NODE_ICON_PATHS.code;
-  const iconColor = node.color !== "#334155" ? node.color : theme.nodeIconColor;
+  const iconColor = node.color !== NODE_DEFAULT_COLOR ? node.color : theme.nodeIconColor;
   const iconSize = 40;
   const iconX = node.x + (node.width - iconSize) / 2;
   const iconY = node.y + (node.height - iconSize) / 2;
@@ -51907,7 +51908,7 @@ function renderNode(node, theme, themeName, allConnections) {
   const parts2 = [];
   parts2.push(`  <g data-node-id="${escapeXml(node.id)}">`);
   if (node.scopeChildren && node.scopeChildren.length > 0) {
-    const strokeColor = node.color !== "#334155" ? node.color : theme.nodeIconColor;
+    const strokeColor = node.color !== NODE_DEFAULT_COLOR ? node.color : theme.nodeIconColor;
     parts2.push(
       `    <rect x="${node.x}" y="${node.y}" width="${node.width}" height="${node.height}" rx="${BORDER_RADIUS}" fill="${theme.nodeFill}" stroke="${strokeColor}" stroke-width="2" filter="url(#node-shadow)"/>`
     );
@@ -51954,7 +51955,7 @@ function renderNodeLabel(parts2, node, theme) {
   const labelAnchor = isScoped ? "start" : "middle";
   parts2.push(`    <g data-label-for="${escapeXml(node.id)}">`);
   parts2.push(`      <rect x="${labelBgX}" y="${labelBgY}" width="${labelBgWidth}" height="${labelBgHeight}" rx="6" fill="${theme.labelBadgeFill}" opacity="0.8"/>`);
-  parts2.push(`      <text class="node-label" x="${labelTextX}" y="${labelBgY + labelBgHeight / 2 + 6}" text-anchor="${labelAnchor}" fill="${node.color !== "#334155" ? node.color : theme.labelColor}">${labelText}</text>`);
+  parts2.push(`      <text class="node-label" x="${labelTextX}" y="${labelBgY + labelBgHeight / 2 + 6}" text-anchor="${labelAnchor}" fill="${node.color !== NODE_DEFAULT_COLOR ? node.color : theme.labelColor}">${labelText}</text>`);
   parts2.push(`    </g>`);
 }
 function renderPortLabelsForNode(parts2, node, theme, themeName, showPortLabels) {
@@ -101300,8 +101301,17 @@ async function generateManifest(options) {
       errors2.push(`Failed to parse ${file}: ${err instanceof Error ? err.message : String(err)}`);
     }
   }
+  const existing = readManifest(directory);
+  const v2Fields = {};
+  if (existing) {
+    if (existing.tagHandlers) v2Fields.tagHandlers = existing.tagHandlers;
+    if (existing.validationRuleSets) v2Fields.validationRuleSets = existing.validationRuleSets;
+    if (existing.exportTargets) v2Fields.exportTargets = existing.exportTargets;
+    if (existing.docs) v2Fields.docs = existing.docs;
+    if (existing.initContributions) v2Fields.initContributions = existing.initContributions;
+  }
   const manifest = {
-    manifestVersion: 1,
+    manifestVersion: 2,
     name: pkg.name ?? "unknown",
     version: pkg.version ?? "0.0.0",
     ...pkg.description && { description: pkg.description },
@@ -101310,6 +101320,7 @@ async function generateManifest(options) {
     nodeTypes: allNodeTypes,
     workflows: allWorkflows,
     patterns: allPatterns,
+    ...v2Fields,
     ...Object.keys(pkg.dependencies ?? {}).length > 0 && {
       dependencies: {
         npm: pkg.dependencies
@@ -101330,7 +101341,7 @@ function readManifest(directory) {
 }
 function emptyManifest(name, version3) {
   return {
-    manifestVersion: 1,
+    manifestVersion: 2,
     name,
     version: version3,
     nodeTypes: [],
@@ -104449,6 +104460,8 @@ async function exportSingleWorkflowViaRegistry(target, inputPath, outputDir, isD
     throw new Error(`Input file not found: ${inputPath}`);
   }
   const parser3 = new AnnotationParser();
+  const projectDir = path46.dirname(inputPath);
+  await parser3.loadPackHandlers(projectDir);
   const parseResult = parser3.parse(inputPath);
   if (parseResult.workflows.length === 0) {
     throw new Error(`No workflows found in ${inputPath}`);
@@ -104524,6 +104537,8 @@ async function exportMultiWorkflowViaRegistry(target, inputPath, outputDir, isDr
     throw new Error(`Input file not found: ${inputPath}`);
   }
   const parser3 = new AnnotationParser();
+  const projectDir = path46.dirname(inputPath);
+  await parser3.loadPackHandlers(projectDir);
   const parseResult = parser3.parse(inputPath);
   if (parseResult.workflows.length === 0) {
     throw new Error(`No workflows found in ${inputPath}`);
@@ -105876,7 +105891,7 @@ function displayInstalledPackage(pkg) {
 // src/cli/index.ts
 init_logger();
 init_error_utils();
-var version2 = true ? "0.17.10" : "0.0.0-dev";
+var version2 = true ? "0.17.12" : "0.0.0-dev";
 var program2 = new Command();
 program2.name("flow-weaver").description("Flow Weaver Annotations - Compile and validate workflow files").option("-v, --version", "Output the current version").option("--no-color", "Disable colors").option("--color", "Force colors").on("option:version", () => {
   logger.banner(version2);

package/dist/diagram/geometry.js

@@ -1,6 +1,6 @@
 import { isExecutePort, isSuccessPort, isFailurePort, SCOPED_PORT_NAMES, isScopedStartPort, isScopedSuccessPort, isScopedFailurePort } from '../constants.js';
 import { assignImplicitPortOrders } from '../utils/port-ordering.js';
-import { getPortColor, NODE_VARIANT_COLORS, TYPE_ABBREVIATIONS } from './theme.js';
+import { getPortColor, NODE_VARIANT_COLORS, NODE_DEFAULT_COLOR, TYPE_ABBREVIATIONS } from './theme.js';
 import { layoutWorkflow } from './layout.js';
 import { calculateOrthogonalPathSafe, TrackAllocator } from './orthogonal-router.js';
 // ---- Constants (matching React component-node) ----
@@ -707,7 +707,7 @@ export function buildDiagramGraph(ast, options = {}) {
     diagramNodes.set('Start', {
         id: 'Start',
         label: 'Start',
-        color: '#334155',
+        color: NODE_DEFAULT_COLOR,
         icon: 'startNode',
         isVirtual: true,
         inputs: [],
@@ -731,7 +731,7 @@ export function buildDiagramGraph(ast, options = {}) {
     diagramNodes.set('Exit', {
         id: 'Exit',
         label: 'Exit',
-        color: '#334155',
+        color: NODE_DEFAULT_COLOR,
         icon: 'exitNode',
         isVirtual: true,
         inputs: exitInputs,
@@ -1098,7 +1098,7 @@ function filterNonScopedPorts(ports) {
 }
 function resolveNodeColor(color, theme = 'dark') {
     if (!color)
-        return '#334155';
+        return NODE_DEFAULT_COLOR;
     const variant = NODE_VARIANT_COLORS[color];
     if (variant)
         return theme === 'dark' ? variant.darkBorder : variant.border;

package/dist/diagram/renderer.js

@@ -1,4 +1,4 @@
-import { getTheme, getPortColor, getPortRingColor, TYPE_ABBREVIATIONS, NODE_ICON_PATHS } from './theme.js';
+import { getTheme, getPortColor, getPortRingColor, TYPE_ABBREVIATIONS, NODE_ICON_PATHS, NODE_DEFAULT_COLOR } from './theme.js';
 import { PORT_RADIUS, BORDER_RADIUS, LABEL_HEIGHT, LABEL_GAP, SCOPE_PORT_COLUMN, measureText } from './geometry.js';
 function escapeXml(str) {
     return str.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
@@ -113,10 +113,10 @@ function renderScopeConnection(parts, conn, allConnections, parentNodeId) {
 // ---- Node rendering ----
 /** Render node body rect + icon */
 function renderNodeBody(parts, node, theme, indent) {
-    const strokeColor = node.color !== '#334155' ? node.color : theme.nodeIconColor;
+    const strokeColor = node.color !== NODE_DEFAULT_COLOR ? node.color : theme.nodeIconColor;
     parts.push(`${indent}<rect x="${node.x}" y="${node.y}" width="${node.width}" height="${node.height}" rx="${BORDER_RADIUS}" fill="${theme.nodeFill}" stroke="${strokeColor}" stroke-width="2" filter="url(#node-shadow)"/>`);
     const iconPath = NODE_ICON_PATHS[node.icon] ?? NODE_ICON_PATHS.code;
-    const iconColor = node.color !== '#334155' ? node.color : theme.nodeIconColor;
+    const iconColor = node.color !== NODE_DEFAULT_COLOR ? node.color : theme.nodeIconColor;
     const iconSize = 40;
     const iconX = node.x + (node.width - iconSize) / 2;
     const iconY = node.y + (node.height - iconSize) / 2;
@@ -126,8 +126,8 @@ function renderNode(node, theme, themeName, allConnections) {
     const parts = [];
     parts.push(`  <g data-node-id="${escapeXml(node.id)}">`);
     if (node.scopeChildren && node.scopeChildren.length > 0) {
-        // Scoped node: body rect only (no icon), then scope internals
-        const strokeColor = node.color !== '#334155' ? node.color : theme.nodeIconColor;
+        // Scoped node: body rect only (icon omitted — children occupy the inner area)
+        const strokeColor = node.color !== NODE_DEFAULT_COLOR ? node.color : theme.nodeIconColor;
         parts.push(`    <rect x="${node.x}" y="${node.y}" width="${node.width}" height="${node.height}" rx="${BORDER_RADIUS}" fill="${theme.nodeFill}" stroke="${strokeColor}" stroke-width="2" filter="url(#node-shadow)"/>`);
         renderScopedContent(parts, node, theme, themeName, allConnections);
     }
@@ -178,7 +178,7 @@ function renderNodeLabel(parts, node, theme) {
     const labelAnchor = isScoped ? 'start' : 'middle';
     parts.push(`    <g data-label-for="${escapeXml(node.id)}">`);
     parts.push(`      <rect x="${labelBgX}" y="${labelBgY}" width="${labelBgWidth}" height="${labelBgHeight}" rx="6" fill="${theme.labelBadgeFill}" opacity="0.8"/>`);
-    parts.push(`      <text class="node-label" x="${labelTextX}" y="${labelBgY + labelBgHeight / 2 + 6}" text-anchor="${labelAnchor}" fill="${node.color !== '#334155' ? node.color : theme.labelColor}">${labelText}</text>`);
+    parts.push(`      <text class="node-label" x="${labelTextX}" y="${labelBgY + labelBgHeight / 2 + 6}" text-anchor="${labelAnchor}" fill="${node.color !== NODE_DEFAULT_COLOR ? node.color : theme.labelColor}">${labelText}</text>`);
     parts.push(`    </g>`);
 }
 /** Render port labels for a node if showPortLabels is enabled */

package/dist/diagram/theme.d.ts

@@ -1,5 +1,6 @@
 import type { TDataType } from '../ast/types.js';
 import type { ThemePalette } from './types.js';
+export declare const NODE_DEFAULT_COLOR = "#334155";
 export declare const NODE_VARIANT_COLORS: Record<string, {
     border: string;
     darkBorder: string;

package/dist/diagram/theme.js

@@ -26,16 +26,17 @@ const LIGHT_FAILURE_COLOR = '#e34646'; // red-shade-2
 // ---- Node theme variant colors ----
 // Dark: border = X-dark-shade-1 (base), icon = X-dark-shade-3
 // Light: border = X-shade-2
+export const NODE_DEFAULT_COLOR = '#334155';
 export const NODE_VARIANT_COLORS = {
     blue: { border: '#548ce3', darkBorder: '#5e9eff' }, // blue-shade-2 / blue-dark-shade-1
     purple: { border: '#9f5fe3', darkBorder: '#b36bff' }, // purple-shade-2 / purple-dark-shade-1
     cyan: { border: '#63ccc4', darkBorder: '#6fe5dc' }, // cyan-shade-2 / cyan-dark-shade-1
+    teal: { border: '#63ccc4', darkBorder: '#6fe5dc' }, // alias for cyan
     orange: { border: '#e3732d', darkBorder: '#ff8133' }, // orange-shade-2 / orange-dark-shade-1
     pink: { border: '#e349c2', darkBorder: '#ff52da' }, // pink-shade-2 / pink-dark-shade-1
     green: { border: '#0ec850', darkBorder: '#10e15a' }, // green-shade-2 / green-dark-shade-1
     red: { border: '#e34646', darkBorder: '#ff4f4f' }, // red-shade-2 / red-dark-shade-1
     yellow: { border: '#e3a82b', darkBorder: '#ffbd30' }, // yellow-shade-2 / yellow-dark-shade-1
-    teal: { border: '#3db0a8', darkBorder: '#4dc7be' }, // teal-shade-2 / teal-dark-shade-1
 };
 // ---- Theme palettes (exact values from token system) ----
 const DARK_PALETTE = {

package/dist/editor-completions/annotationValues.js

@@ -100,7 +100,7 @@ const ANNOTATION_VALUES = {
         },
         {
             label: 'teal',
-            detail: 'Teal node color',
+            detail: 'Teal node color (alias for cyan)',
             insertText: 'teal',
             insertTextFormat: 'plain',
             kind: 'value',

package/dist/export/index.js

@@ -42,8 +42,10 @@ async function exportSingleWorkflowViaRegistry(target, inputPath, outputDir, isD
     if (!fs.existsSync(inputPath)) {
         throw new Error(`Input file not found: ${inputPath}`);
     }
-    // Parse to find workflows
+    // Parse to find workflows (load pack tag handlers so CI/CD annotations resolve)
     const parser = new AnnotationParser();
+    const projectDir = path.dirname(inputPath);
+    await parser.loadPackHandlers(projectDir);
     const parseResult = parser.parse(inputPath);
     if (parseResult.workflows.length === 0) {
         throw new Error(`No workflows found in ${inputPath}`);
@@ -123,8 +125,10 @@ async function exportMultiWorkflowViaRegistry(target, inputPath, outputDir, isDr
     if (!fs.existsSync(inputPath)) {
         throw new Error(`Input file not found: ${inputPath}`);
     }
-    // Parse to find workflows
+    // Parse to find workflows (load pack tag handlers so CI/CD annotations resolve)
     const parser = new AnnotationParser();
+    const projectDir = path.dirname(inputPath);
+    await parser.loadPackHandlers(projectDir);
     const parseResult = parser.parse(inputPath);
     if (parseResult.workflows.length === 0) {
         throw new Error(`No workflows found in ${inputPath}`);

package/dist/generated-version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.17.10";
+export declare const VERSION = "0.17.12";
 //# 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.17.10';
+export const VERSION = '0.17.12';
 //# sourceMappingURL=generated-version.js.map

package/dist/marketplace/manifest.js

@@ -132,8 +132,25 @@ export async function generateManifest(options) {
             errors.push(`Failed to parse ${file}: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
+    // Preserve v2 extension fields from the existing manifest so that
+    // re-running pack:manifest doesn't wipe manually declared tagHandlers,
+    // validationRuleSets, docs, exportTargets, initContributions, etc.
+    const existing = readManifest(directory);
+    const v2Fields = {};
+    if (existing) {
+        if (existing.tagHandlers)
+            v2Fields.tagHandlers = existing.tagHandlers;
+        if (existing.validationRuleSets)
+            v2Fields.validationRuleSets = existing.validationRuleSets;
+        if (existing.exportTargets)
+            v2Fields.exportTargets = existing.exportTargets;
+        if (existing.docs)
+            v2Fields.docs = existing.docs;
+        if (existing.initContributions)
+            v2Fields.initContributions = existing.initContributions;
+    }
     const manifest = {
-        manifestVersion: 1,
+        manifestVersion: 2,
         name: pkg.name ?? 'unknown',
         version: pkg.version ?? '0.0.0',
         ...(pkg.description && { description: pkg.description }),
@@ -142,6 +159,7 @@ export async function generateManifest(options) {
         nodeTypes: allNodeTypes,
         workflows: allWorkflows,
         patterns: allPatterns,
+        ...v2Fields,
         ...(Object.keys(pkg.dependencies ?? {}).length > 0 && {
             dependencies: {
                 npm: pkg.dependencies,
@@ -165,7 +183,7 @@ export function readManifest(directory) {
 }
 function emptyManifest(name, version) {
     return {
-        manifestVersion: 1,
+        manifestVersion: 2,
         name,
         version,
         nodeTypes: [],

package/dist/marketplace/types.d.ts

@@ -9,7 +9,7 @@ import type { TDataType } from '../ast/types.js';
 /** Auto-generated manifest describing a marketplace package's contents. */
 export type TMarketplaceManifest = {
     /** Manifest schema version */
-    manifestVersion: 1 | 2;
+    manifestVersion: 2;
     /** npm package name */
     name: string;
     /** Semver version */

package/docs/reference/advanced-annotations.md

@@ -481,7 +481,7 @@ These annotations go on `@flowWeaver nodeType` blocks:
 | `@name` | Override display name | `@name MyCustomName` |
 | `@label` | Human-readable label | `@label Fetch with Timeout` |
 | `@description` | Node description | `@description Validates expense data` |
-| `@color` | Custom color | `@color "#ff6b35"` |
+| `@color` | Custom color | `@color purple` or `@color "#ff6b35"` |
 | `@icon` | Custom icon | `@icon "database"` |
 | `@tag` | Visual tag/badge | `@tag async` or `@tag beta "Experimental"` |
 | `@scope` | Provides a named scope | `@scope processItem` |
@@ -491,6 +491,42 @@ These annotations go on `@flowWeaver nodeType` blocks:
 
 ---
 
+## Available Colors
+
+Named colors adapt to the diagram theme (dark/light). You can also pass any hex color directly (e.g. `@color "#ff6b35"`).
+
+`blue` · `purple` · `cyan` · `orange` · `pink` · `green` · `red` · `yellow` · `teal` (alias for cyan)
+
+## Available Icons
+
+Icons render inside the node body in SVG diagrams. Names correspond to Material Symbols (outlined, weight 500).
+
+**AI & ML:** `psychology` · `smartToy` · `autoAwesome` · `modelTraining` · `science` · `biotech`
+
+**Data & storage:** `database` · `dataObject` · `tableChart` · `token` · `storage` · `memory`
+
+**Cloud & network:** `api` · `webhook` · `cloudSync` · `cloudUpload` · `cloudDownload` · `dns` · `router` · `http` · `link`
+
+**Security & auth:** `key` · `shield` · `vpnKey` · `verified` · `security` · `policy` · `adminPanelSettings`
+
+**Logic & flow:** `altRoute` · `callSplit` · `callMerge` · `rule` · `filterAlt` · `repeat` · `sort`
+
+**Actions & status:** `bolt` · `build` · `rocketLaunch` · `send` · `sync` · `refresh`
+
+**Communication:** `notifications` · `email` · `campaign`
+
+**Scheduling:** `event` · `schedule` · `timer`
+
+**General tools:** `terminal` · `settings` · `tune` · `search` · `save` · `upload` · `download` · `edit` · `delete`
+
+**Status:** `checkCircle` · `error` · `warning` · `info` · `help` · `visibility`
+
+**Files:** `folder` · `description` · `attachFile`
+
+**Structural:** `code` (default) · `flow` (workflow nodes) · `startNode` · `exitNode`
+
+---
+
 ## Related Topics
 
 - [Concepts](concepts) — Core workflow fundamentals

package/docs/reference/concepts.md

@@ -137,6 +137,7 @@ Expression nodes are pure functions where:
   - Primitive/array return -> single output port
   - Object return `{ a, b }` -> one port per property
 - Best for: transformers, math, utilities, data mapping, async fetchers, API calls
+- Optional `@color` and `@icon` annotations customize the node's appearance in SVG diagrams (see `advanced-annotations` for available values)
 
 > **Start with expression mode.** Only switch to normal mode when you need to return data alongside a failure (error-with-data patterns) or for void side-effect functions. Expression nodes handle success/failure branching automatically — throw to trigger the `onFailure` path.
 

package/docs/reference/jsdoc-grammar.md

@@ -244,7 +244,7 @@ Multiple attribute brackets are allowed (zero or more). Attributes can be split
 @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 [color: "red", icon: "database"]
 @node myAdd Add [tags: "math" "Math operation", "transform"]
 @node myAdd Add [position: 180 0]
 @node myAdd Add [label: "hi"] [color: "#f00"] [position: 360 0]

package/package.json

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