updates

.agents/improvements/EXAMPLE_FLOW_TEMPLATE.md

@@ -0,0 +1,123 @@
+# EVOLV Example Flow Template Standard
+
+## Overview
+
+Every EVOLV node MUST have example flows in its `examples/` directory. Node-RED automatically discovers these and shows them in **Import > Examples > EVOLV**.
+
+## Naming Convention
+
+```
+examples/
+  01 - Basic Manual Control.json          # Tier 1: inject-based, zero deps
+  02 - Integration with Parent Node.json  # Tier 2: parent-child wiring
+  03 - Dashboard Visualization.json       # Tier 3: FlowFuse dashboard (optional)
+```
+
+The filename (minus `.json`) becomes the menu label in Node-RED.
+
+## Tier 1: Basic (inject-based, zero external dependencies)
+
+**Purpose:** Demonstrate all key functionality using only core Node-RED nodes.
+
+**Required elements:**
+- 1x `comment` node (top-left): title + 2-3 line description of what the flow demonstrates
+- 1x `comment` node (near inputs): "HOW TO USE: 1. Deploy flow. 2. Click inject nodes..."
+- `inject` nodes for each control action (labeled clearly)
+- The EVOLV node under test with **realistic, working configuration**
+- 3x `debug` nodes: "Port 0: Process", "Port 1: InfluxDB", "Port 2: Parent"
+- Optional: 1x `function` node to format output readably (keep under 20 lines)
+
+**Forbidden:** No dashboard nodes. No FlowFuse widgets. No HTTP nodes. No third-party nodes.
+
+**Config rules:**
+- All required config fields filled with realistic values
+- Model/curve fields set to existing models in the library
+- `enableLog: true, logLevel: "info"` so users can see what happens
+- Unit fields explicitly set (not empty strings)
+
+**Layout rules:**
+- Comment nodes: top-left
+- Input section: left side (x: 100-400)
+- EVOLV node: center (x: 500-600)
+- Debug/output: right side (x: 700-900)
+- Y spacing: ~60px between nodes
+
+## Tier 2: Integration (parent-child relationships)
+
+**Purpose:** Show how nodes connect as parent-child via Port 2.
+
+**Required elements:**
+- 1x `comment` node: what relationship is being demonstrated
+- Parent node + child node(s) properly wired
+- Port 2 of child → Port 0 input of parent (registration pathway)
+- `inject` nodes to send control commands to parent
+- `inject` nodes to send measurement/state to children
+- `debug` nodes on all ports of both parent and children
+
+**Node-specific integration patterns:**
+- `machineGroupControl` → 2x `rotatingMachine`
+- `pumpingStation` → 1x `rotatingMachine` + 1x `measurement` (assetType: "flow")
+- `valveGroupControl` → 2x `valve`
+- `reactor` → `settler` (downstream cascade)
+- `measurement` → any parent node
+
+## Tier 3: Dashboard Visualization (optional)
+
+**Purpose:** Rich interactive demo with FlowFuse dashboard.
+
+**Allowed additional dependencies:** FlowFuse dashboard nodes only (`@flowfuse/node-red-dashboard`).
+
+**Required elements:**
+- 1x `comment` node: "Requires @flowfuse/node-red-dashboard"
+- Auto-initialization: `inject` node with "Inject once after 1 second" for default mode/state
+- Dashboard controls clearly labeled
+- Charts with proper axis labels and units
+- Keep parser/formatter functions under 40 lines (split if needed)
+- No null message outputs (filter before sending to charts)
+
+## Comment Node Standard
+
+Every comment node must use this format:
+
+```
+Title: [Node Name] - [Flow Tier]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+[2-3 line description]
+
+Prerequisites: [list any requirements]
+```
+
+## ID Naming Convention
+
+Use predictable, readable IDs for all nodes (not random hex):
+
+```
+{nodeName}_{tier}_{purpose}
+
+Examples:
+- rm_basic_tab           (rotatingMachine, basic flow, tab)
+- rm_basic_node          (the actual rotatingMachine node)
+- rm_basic_debug_port0   (debug on port 0)
+- rm_basic_inject_start  (inject for startup)
+- rm_basic_comment_title (title comment)
+```
+
+## Validation Checklist
+
+Before committing an example flow:
+
+- [ ] Can be imported into clean Node-RED + EVOLV (no other packages needed for Tier 1/2)
+- [ ] All nodes show correct status after deploy (no red triangles)
+- [ ] Comment nodes present and descriptive
+- [ ] All 3 output ports wired to something (debug at minimum)
+- [ ] IDs follow naming convention (no random hex)
+- [ ] Node config uses realistic values (not empty strings or defaults)
+- [ ] File named per convention (01/02/03 prefix)
+
+## Gitea Wiki Integration
+
+Each node's wiki gets an "Examples" page that:
+1. Lists all available example flows with descriptions
+2. Links to the raw .json file in the repo
+3. Describes prerequisites and step-by-step usage
+4. Shows expected behavior after deploy