docs(wiki): rewrite Home.md to 14-section visual-first template

Fixes section ordering (11-8-9-10 scramble + duplicate §11), updates
banner hash to ef34c82, corrects §2 diagram (set.position → updateFlow,
evt.deltaPChange → positionChange/deltaPChange), upgrades capability
matrix to ⚠️ for set.position and cascaded VGC, rewrites §9 to reflect
the actual editor form fields (name/format/position/logger), and
replaces the orphaned "Distribution loop" duplicate-§11 with a proper
§10. AUTOGEN markers verified intact via npm run wiki:all.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

wiki/Home.md

@@ -1,21 +1,23 @@
 # valveGroupControl
 
-> **Reflects code as of `e02cd1a` · regenerated `2026-05-11` via `npm run wiki:all`**
+> **Reflects code as of `ef34c82` · regenerated `2026-05-11` via `npm run wiki:all`**
 > If this banner is stale, the page may be out of date. Treat as informative, not authoritative.
 
 ## 1. What this node is
 
-**valveGroupControl** (VGC) is an S88 Unit that distributes a group-level flow target across registered `valve` children proportional to their current Kv, aggregates the per-valve accepted flow back into a group total, and surfaces the maximum delta-P across the group. It also reconciles each child's fluid-contract advertisement into a single group-level service-type view.
+**valveGroupControl** (VGC) is an S88 Unit coordinator for a group of `valve` children. It distributes a group-level flow target across registered valves proportional to their Kv rating, runs a residual-reconciliation pass to absorb per-valve acceptance limits, aggregates group max delta-P, and reconciles upstream fluid-contract advertisements into a single group-level service-type view.
 
 ## 2. Position in the platform
 
 ```mermaid
 flowchart LR
     src[machine / MGC / PS<br/>upstream source]:::unit -.flow.predicted.-> vgc[valveGroupControl<br/>Unit]:::unit
-    vgc -->|set.position| v1[valve A]:::equip
+    vgc -->|updateFlow predicted| v1[valve A]:::equip
-    vgc -->|set.position| v2[valve B]:::equip
+    vgc -->|updateFlow predicted| v2[valve B]:::equip
-    v1 -->|evt.deltaPChange| vgc
+    v1 -->|positionChange| vgc
-    v2 -->|evt.deltaPChange| vgc
+    v2 -->|positionChange| vgc
+    v1 -->|deltaPChange| vgc
+    v2 -->|deltaPChange| vgc
     vgc -->|child.register| parent[upstream parent]:::unit
     classDef unit fill:#50a8d9,color:#000
     classDef equip fill:#86bbdd,color:#000
@@ -28,13 +30,15 @@ S88 colours: Unit `#50a8d9`, Equipment `#86bbdd`. Source of truth: `.claude/rule
 | Capability | Status | Notes |
 |---|---|---|
 | Proportional flow distribution by Kv | ✅ | `groupOps/flowDistribution.js`. |
-| Two-pass residual reconciliation | ✅ | `maxPasses: 2`, `residualTolerance: 0.001`. |
+| Two-pass residual reconciliation | ✅ | Default `maxPasses: 2`, `residualTolerance: 0.001`. |
-| Periodic tick re-balance | ✅ | Runs each adapter tick; `set.reconcileInterval` re-tunes. |
+| Periodic tick re-balance | ✅ | `tick()` calls `calcValveFlows()`; `set.reconcileInterval` re-tunes interval. |
-| Group `maxDeltaP` aggregation | ✅ | Recomputed on any child `deltaPChange`. |
+| Group `maxDeltaP` aggregation | ✅ | Recomputed on any child `deltaPChange` event. |
-| Upstream fluid-contract aggregation | ✅ | `sources/fluidContract.js`. |
+| Upstream fluid-contract aggregation | ✅ | `sources/fluidContract.js`; emits `fluidContractChange`. |
-| Sequence dispatch to all valves | ✅ | `cmd.execSequence` → per-valve `handleInput`. |
+| Group-wide sequence dispatch | ✅ | `cmd.execSequence` → `executeSequence` → per-state `transitionToState`. |
-| Per-valve positional override | ❌ | `set.position` reserved; no-op in current build. |
+| Emergency stop | ✅ | `cmd.emergencyStop` → `emergencystop` sequence on all valves. |
-| Multi-source aggregation | ✅ | Multiple machines / MGCs may register as sources. |
+| Per-valve positional override | ⚠️ | `set.position` is a debug-logged **no-op** pending Phase 7. See §14. |
+| Multi-source aggregation | ✅ | Multiple machines / MGCs / PSs may register as upstream sources. |
+| Cascaded VGC as upstream source | ⚠️ | Accepted by router but not exercised in production; test coverage absent. |
 
 ## 4. Code map
 
@@ -44,13 +48,13 @@ flowchart TB
         nc["buildDomainConfig()<br/>static DomainClass, commands"]
     end
     subgraph domain["specificClass.js — orchestrator (BaseDomain)"]
-        sc["ValveGroupControl.configure()<br/>registerChild dispatch<br/>tick → calcValveFlows"]
+        sc["ValveGroupControl.configure()<br/>router.onRegister: valve + sources<br/>tick() → calcValveFlows()"]
     end
     subgraph concerns["src/ concern modules"]
-        gops["groupOps/<br/>flowDistribution"]
+        gops["groupOps/<br/>flowDistribution + calcMaxDeltaP"]
-        srcs["sources/<br/>fluidContract"]
+        srcs["sources/<br/>fluidContract registration"]
         cmds["commands/<br/>topic registry + handlers"]
-        io["io/<br/>output + status badge"]
+        io["io/<br/>getOutput + getStatusBadge"]
     end
     nc --> sc
     sc --> gops
@@ -61,15 +65,17 @@ flowchart TB
 
 | Module | Owns | Read first if you're changing… |
 |---|---|---|
-| `groupOps/` | Flow distribution, residual solver, max-deltaP aggregation | How the group divides flow. |
+| `groupOps/` | Kv-share solver, residual pass, max-deltaP aggregation | How the group divides flow between valves. |
-| `sources/` | Upstream-source registration, fluid-contract reconciliation | Service-type aggregation, source-event subscriptions. |
+| `sources/` | Upstream-source registration, flow-event subscription, fluid-contract reconciliation | Service-type aggregation, source event wiring. |
-| `commands/` | Input-topic registry + per-topic handlers | New input topics, payload validation. |
+| `commands/` | Input-topic registry + per-topic handlers | New input topics or payload validation rules. |
-| `io/` | Port-0 output shape + status badge | What lands on the wire. |
+| `io/` | Port-0 output shape + status badge composition | What lands on the wire, badge text. |
 
 ## 5. Topic contract
 
 > **Auto-generated** from `src/commands/index.js`. Do NOT hand-edit between the markers. Re-run `npm run wiki:contract`.
 
+The **Unit** column reflects the descriptor's `units: { measure, default }` declaration, rendered as `<measure> (default <unit>)`. Topics without a `units` field show `—`. The **Effect** column is sourced from the descriptor's `description` field.
+
 <!-- BEGIN AUTOGEN: topic-contract -->
 
 | Canonical topic | Aliases | Payload | Unit | Effect |
@@ -92,9 +98,9 @@ flowchart LR
         v["valve"]:::equip
         src["machine / rotatingmachine /<br/>machinegroup / pumpingstation /<br/>valvegroupcontrol"]:::unit
     end
-    v   -->|positionChange| handler1[onPositionChange<br/>calcValveFlows]
+    v   -->|positionChange| handler1[onPositionChange<br/>→ calcValveFlows]
-    v   -->|deltaPChange|   handler2[onDeltaPChange<br/>calcMaxDeltaP]
+    v   -->|deltaPChange|   handler2[onDeltaPChange<br/>→ calcMaxDeltaP]
-    src -->|flow.predicted.*| handler3[updateFlow<br/>at atEquipment]
+    src -->|flow.predicted.*<br/>flow.measured.*| handler3[updateFlow<br/>atEquipment]
     src -->|fluidContractChange| handler4[sources.refresh<br/>aggregate contract]
     classDef equip fill:#86bbdd,color:#000
     classDef unit fill:#50a8d9,color:#000
@@ -102,11 +108,11 @@ flowchart LR
 
 | softwareType | onRegister side-effect | Subscribed events |
 |---|---|---|
-| `valve` | Stored in `this.valves[id]`; binds `positionChange` + `deltaPChange`; triggers `calcValveFlows` + `calcMaxDeltaP`. | `positionChange`, `deltaPChange`. |
+| `valve` | Stored in `this.valves[id]`; binds `positionChange` (via `child.state.emitter`) + `deltaPChange` (via `child.emitter`); triggers `calcValveFlows` + `calcMaxDeltaP`. | `positionChange`, `deltaPChange`. |
-| `machine` / `rotatingmachine` | Stored as upstream source; reads `getFluidContract()` (or default `liquid`). | `flow.predicted.*`, `flow.measured.*`, `fluidContractChange`. |
+| `machine` / `rotatingmachine` | Stored as upstream source; reads `getFluidContract()` or infers `liquid` by default. | `flow.predicted.*`, `flow.measured.*`, `fluidContractChange`. |
 | `machinegroup` / `machinegroupcontrol` | Same as machine. | Same as machine. |
 | `pumpingstation` | Same as machine. | Same as machine. |
-| `valvegroupcontrol` | Allowed for cascaded VGCs; not exercised in production. | Same. |
+| `valvegroupcontrol` | Cascaded VGC; accepted by router. Not exercised in production. | Same as machine. |
 
 ## 7. Lifecycle — what one tick / event does
 
@@ -118,46 +124,22 @@ sequenceDiagram
     participant v2 as valve B
     participant out as Port-0
 
-    src->>vgc: flow.predicted.downstream (m3/s)
+    src->>vgc: flow.predicted.downstream (m³/h)
-    vgc->>vgc: _write flow.predicted.atEquipment
+    vgc->>vgc: updateFlow('predicted', value, 'atEquipment')
     vgc->>vgc: calcValveFlows()
-    Note over vgc: solveFlowDistribution<br/>(by Kv share)
+    Note over vgc: solveFlowDistribution<br/>by Kv share (≤ maxPasses)
     vgc->>v1: updateFlow('predicted', shareA, 'downstream')
     vgc->>v2: updateFlow('predicted', shareB, 'downstream')
-    v1-->>vgc: accepted flow + deltaPChange
+    v1-->>vgc: positionChange / deltaPChange
-    v2-->>vgc: accepted flow + deltaPChange
+    v2-->>vgc: positionChange / deltaPChange
-    vgc->>vgc: residual pass (up to maxPasses)
     vgc->>vgc: calcMaxDeltaP
-    vgc->>out: msg{topic, payload (delta-compressed)}
-```
-
-## 11. Distribution loop — flow-share solver
-
-VGC has no FSM. The loop below replaces the state chart for this section.
-
-```mermaid
-sequenceDiagram
-    participant tick as adapter tick / event
-    participant vgc as VGC
-    participant solver as solveFlowDistribution
-    participant valves as valve children
-
-    tick->>vgc: calcValveFlows()
-    vgc->>vgc: read flow.measured / predicted .atEquipment
-    vgc->>solver: target=totalFlow, entries=availableValves
-    loop ≤ maxPasses while |residual| > tolerance
-        solver->>valves: updateFlow share by (Kv / totalKv)
-        valves-->>solver: accepted flow back
-        solver->>solver: residual = target - sum(accepted)
-    end
-    solver-->>vgc: { flowsById, residual, passes }
-    vgc->>vgc: write flow.predicted.atEquipment = assignedTotal
     vgc->>vgc: notifyOutputChanged()
+    vgc->>out: msg{topic, payload (delta-compressed)}
 ```
 
 ## 8. Data model — `getOutput()`
 
-What lands on Port 0. Composed in `io/output`, then delta-compressed by `outputUtils.formatMsg`.
+What lands on Port 0. Composed in `io/output.getOutput()`, then delta-compressed by `outputUtils.formatMsg`.
 
 <!-- BEGIN AUTOGEN: data-model -->
 
@@ -168,75 +150,111 @@ What lands on Port 0. Composed in `io/output`, then delta-compressed by `outputU
 
 <!-- END AUTOGEN: data-model -->
 
-Measurement-derived keys follow the `<position>_<variant>_<type>` shape (e.g. `atEquipment_predicted_flow`) and are emitted only when the container holds a finite value.
+Measurement-derived keys follow the `<position>_<variant>_<type>` shape and are emitted only when the container holds a finite value.
+
+| Example key | Unit | Description |
+|---|---|---|
+| `atEquipment_predicted_flow` | m³/h | Total group predicted flow (sum of per-valve assigned flows). |
+| `atEquipment_measured_flow` | m³/h | Total group measured flow (from upstream source). |
+| `deltaMax_predicted_pressure` | mbar | Max delta-P across registered valves. |
+
+> Delta compression: only changed fields are sent per tick. Consumers must cache and merge. See `outputUtils.formatMsg`.
 
 ## 9. Configuration — editor form ↔ config keys
 
 ```mermaid
 flowchart TB
-    subgraph editor["Node-RED editor form"]
+    subgraph editor["Node-RED editor form (vgc.html)"]
-        f1[Mode]
+        f1[Name]
-        f2[Sequences]
+        f2[Process output format]
-        f3[Allowed sources per mode]
+        f3[Database output format]
-        f4[Reconciliation interval]
+        f4[Position vs parent]
+        f5[Logger / log level]
     end
-    subgraph config["Domain config slice"]
+    subgraph config["Domain config (runtime / schema)"]
-        c1[mode.current]
+        c1[general.name]
-        c2[sequences.<name>]
+        c2[output.process]
-        c3[mode.allowedSources.<mode>]
+        c3[output.dbase]
-        c4[flowReconciliation (runtime)]
+        c4[functionality.positionVsParent]
+        c5[logging.enableLog / logLevel]
     end
     f1 --> c1
     f2 --> c2
     f3 --> c3
     f4 --> c4
+    f5 --> c5
 ```
 
-| Form field | Config key | Default | Range | Where used |
+| Form field | Config key | Default | Where used |
-|---|---|---|---|---|
+|---|---|---|---|
-| Mode | `mode.current` | per schema | enum | `setMode` |
+| Name | `general.name` | `""` | Node label, InfluxDB tag, status badge. |
-| Sequences | `sequences.<name>` | per schema | Set of state names | `executeSequence` |
+| Process output format | `output.process` | `"process"` | `outputUtils.formatMsg` Port-0 formatter. |
-| Allowed sources | `mode.allowedSources.<mode>` | per schema | Set of source ids | `isValidSourceForMode` |
+| Database output format | `output.dbase` | `"influxdb"` | `outputUtils.formatMsg` Port-1 formatter. |
-| Reconcile maxPasses | `flowReconciliation.maxPasses` | `2` | ≥ 1 | `solveFlowDistribution` |
+| Position vs parent | `functionality.positionVsParent` | `""` | Child registration Port-2 message; read by upstream parent. |
-| Reconcile tolerance | `flowReconciliation.residualTolerance` | `0.001` | ≥ 0 | `solveFlowDistribution` |
+| Enable log / log level | `logging.enableLog`, `logging.logLevel` | `false` / `"error"` | Logger verbosity. Never ship `debug` in demos. |
-| Reconcile interval | (runtime, via `set.reconcileInterval`) | adapter default | ≥ 100 ms | `setReconcileIntervalSeconds` |
 
-## 10. State chart
+> Domain-level config (`mode.current`, `sequences`, `mode.allowedSources`, `flowReconciliation`) is loaded from the node's schema defaults and updated at runtime via `set.mode` / `set.reconcileInterval`. These fields are not exposed in the editor form.
 
-Skipped — VGC has no FSM of its own. State semantics belong to the child valves; VGC is a coordinator. See section 11 for the flow-distribution loop.
+## 10. Flow-distribution loop (replaces state chart)
+
+VGC has no FSM of its own — state semantics belong to the child valves. The core coordination loop is the Kv-share solver described below.
+
+```mermaid
+sequenceDiagram
+    participant tick as adapter tick / incoming event
+    participant vgc as VGC
+    participant solver as solveFlowDistribution
+    participant valves as valve children
+
+    tick->>vgc: calcValveFlows()
+    vgc->>vgc: read flow.measured (or predicted) .atEquipment
+    vgc->>solver: target=totalFlow, entries=availableValves
+    loop ≤ maxPasses while |residual| > tolerance
+        solver->>valves: updateFlow share by (Kv / totalKv)
+        valves-->>solver: accepted flow (read back from child.measurements)
+        solver->>solver: residual = target − sum(accepted)
+    end
+    solver-->>vgc: { flowsById, residual, passes }
+    vgc->>vgc: write flow.predicted.atEquipment = assignedTotal
+    vgc->>vgc: calcMaxDeltaP()
+    vgc->>vgc: notifyOutputChanged()
+```
+
+A valve is **available** if: `state ≠ off|maintenance`, `mode ≠ maintenance`, and `kv > 0`. Unavailable valves receive `updateFlow('predicted', 0)` and are excluded from the solver.
 
 ## 11. Examples
 
 | Tier | File | What it shows | Mandatory? |
 |---|---|---|---|
-| Basic | `examples/01-Basic.flow.json` | Inject `data.totalFlow` + 2 valves + dashboard | ✅ |
+| Basic | `examples/basic.flow.json` | Inject `data.totalFlow` + 2 valves (no parent) | ✅ |
-| Integration | `examples/02-Integration.flow.json` | VGC + valves + upstream rotatingMachine | ✅ |
+| Integration | `examples/integration.flow.json` | VGC + valves + upstream rotatingMachine | ✅ |
-| Dashboard | `examples/03-Dashboard.flow.json` | Live FlowFuse charts (per-valve flow, max ΔP) | ⭕ |
+| Edge | `examples/edge.flow.json` | Edge cases: no valves, residual non-convergence, cascaded VGC | ⭕ |
 
-Screenshots under `wiki/_partial-screenshots/valveGroupControl/` when produced. Docker compose snippet under `examples/README.md`.
+Tier-1 / Tier-2 / Tier-3 naming scheme pending when existing flows are validated on live Node-RED. Screenshots under `wiki/_partial-screenshots/valveGroupControl/` when produced.
 
 ## 12. Debug recipes
 
 | Symptom | First thing to check | Where to look |
 |---|---|---|
-| All valves show `assigned flow = 0` | `getAvailableValves()` empty; check Kv > 0 and state ≠ `off` / `maintenance`. | `groupOps/flowDistribution.isValveAvailable` |
+| All valves receive `assigned flow = 0` | `getAvailableValves()` returns empty list; check Kv > 0 and child state ≠ `off` / `maintenance`. | `groupOps/flowDistribution.isValveAvailable` |
-| Residual never converges | `flowReconciliation.maxPasses` too low for the valve curve shape. | `lastFlowSolve.residual` |
+| Residual never converges | `flowReconciliation.maxPasses` too low for valve curve shape; check `lastFlowSolve.residual`. | `groupOps/flowDistribution.js` |
-| Group `maxDeltaP` stale | Child `deltaPChange` not subscribed; valve emitter not exposed. | `_bindValveEvents` |
+| Group `maxDeltaP` stale | Child `deltaPChange` not subscribed; valve emitter not exposed via `child.emitter`. | `specificClass._bindValveEvents` |
-| Service-type stays `unknown` | No source registered yet or all sources advertise unknown. | `sources.refreshFluidContract` |
+| Service-type stays `unknown` | No upstream source registered, or all advertise unknown type. | `sources/fluidContract.refreshFluidContract` |
-| `data.totalFlow` ignored | Mode rejects the source; check `mode.allowedSources`. | `isValidSourceForMode` |
+| `data.totalFlow` silently ignored | Mode rejects the source id; check `mode.allowedSources` for the current mode. | `specificClass.isValidSourceForMode` |
+| `set.position` has no effect | Known limitation — handler is a no-op. See §14. | `commands/handlers.setPosition` |
 
 > Never ship `enableLog: 'debug'` in a demo — fills the container log within seconds and obscures real errors. Use only for live debugging.
 
 ## 13. When you would NOT use this node
 
-- Use VGC for **2+ parallel valves** sharing a header. For a single valve, wire `valve` directly under the upstream parent.
+- Use `valve` directly when you have a **single** valve under an upstream parent. VGC adds coordination overhead for no benefit with one child.
-- Don't use VGC to coordinate series valves — the flow-distribution model assumes parallel branches with a shared upstream pressure.
+- Do NOT use VGC to coordinate **series** valves — the Kv-share solver assumes parallel branches sharing a common header pressure.
-- Skip VGC when the upstream source already publishes per-branch flow setpoints; route those straight to each valve.
+- Skip VGC when the upstream source already publishes **per-branch flow setpoints**; route those directly to each valve instead.
 
 ## 14. Known limitations / current issues
 
 | # | Issue | Tracked in |
 |---|---|---|
-| 1 | `set.position` is reserved but currently a no-op — per-valve override is pending Phase 7. | CONTRACT.md `## Inputs` |
+| 1 | `set.position` is a debug-logged **no-op** — per-valve positional override is reserved, pending Phase 7 topic standardisation of valve setpoint payloads. The handler in `commands/handlers.setPosition` intentionally does nothing. | `CONTRACT.md §Inputs`; `OPEN_QUESTIONS.md` Phase 7 |
-| 2 | Residual solver assumes Kv share is a good first estimate; pathological curves can need more passes than the default `2`. | `groupOps/flowDistribution.js` |
+| 2 | Residual solver assumes Kv share is a valid first estimate. Pathological valve curves (e.g. very non-linear Kv vs position) may need more passes than the default `maxPasses: 2` to reach `residualTolerance`. | `groupOps/flowDistribution.js` |
-| 3 | Cascaded `valvegroupcontrol` registration accepted but not test-covered. | CONTRACT.md `## Children` |
+| 3 | Cascaded `valvegroupcontrol` registration (VGC as upstream source of another VGC) is accepted by the router but has no test coverage and is not exercised in production. | `CONTRACT.md §Children` |