docs(wiki): full 5-page wiki matching the rotatingMachine reference format

Replaces the prior stub/partial wiki with a Home + Reference-{Architecture,
Contracts,Examples,Limitations} + _Sidebar structure. Topic-contract and
data-model sections wrapped in AUTOGEN markers for the future wiki-gen tool.
Source-vs-spec contradictions surfaced and flagged inline (not silently
fixed). Pending-review notes mark sections that need a full node review.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

wiki/Reference-Examples.md

@@ -0,0 +1,150 @@
+# Reference — Examples
+
+![code-ref](https://img.shields.io/badge/code--ref-4973a8b-blue)
+
+> [!NOTE]
+> Pending full node review (2026-05). Example flows under `nodes/diffuser/examples/` are at the **legacy** `basic` / `integration` / `edge` filename tier — they predate the rotatingMachine `01 - …` numbered convention and have not yet been re-validated against the current `src/commands/index.js` topic registry. `examples/README.md` is a one-line placeholder.
+
+---
+
+## Shipped examples
+
+| File | Tier | Dependencies | What it shows |
+|:---|:---:|:---|:---|
+| `examples/basic.flow.json` | 1 (legacy) | EVOLV only | Single-diffuser flow driven by inject buttons — setter topics for flow, density, water height, header pressure, elements, alpha factor. Debug taps on the process port. |
+| `examples/integration.flow.json` | 2 (legacy) | EVOLV (+ `reactor` if you wire one) | Diffuser auto-registers with a parent (Port 2 `child.register`). |
+| `examples/edge.flow.json` | 3 (legacy) | EVOLV only | Edge cases: flow = 0 idle reset, very large flow (alarm band), missing curve fallback to default. |
+
+> [!IMPORTANT]
+> **TODO — upgrade to numbered tier set.** Mirror rotatingMachine's convention:
+>
+> | New file | Tier | Replaces |
+> |:---|:---:|:---|
+> | `01 - Basic Manual Control.json` | 1 | `basic.flow.json` |
+> | `02 - Integration with Reactor.json` | 2 | `integration.flow.json` |
+> | `03 - Dashboard Visualization.json` | 3 | (new, requires `@flowfuse/node-red-dashboard`) |
+>
+> Keep the legacy files until the new tier set has been Docker-validated. Then update `examples/README.md` to per-tier descriptions.
+
+---
+
+## Loading a flow
+
+### Via the editor
+
+1. Open the Node-RED editor at `http://localhost:1880`.
+2. Menu → Import → drag the JSON file.
+3. Click Deploy.
+
+### Via the Admin API
+
+```bash
+curl -X POST -H 'Content-Type: application/json' \
+  --data @nodes/diffuser/examples/basic.flow.json \
+  http://localhost:1880/flow
+```
+
+(Use `/flows` to bulk-deploy all tabs.)
+
+---
+
+## Example — Basic Manual Control (legacy `basic.flow.json`)
+
+Single-diffuser flow with one inject per setter topic.
+
+### What to do after deploy
+
+1. Click `set.water-height = 5` — 5 m column above the diffuser. `oPLoss` updates to reflect static head.
+2. Click `set.elements = 100` — 100 elements. `oFlowElement` and `oFluxPerM2` denominators update.
+3. Click `set.density = 15` — 15 % bottom coverage, the default curve key.
+4. Click `set.header-pressure = 600` — 600 mbar gauge. Air-density correction kicks in; `nFlow` shifts from `iFlow`.
+5. Click `set.alfa-factor = 0.7` — the α correction. Influences `oKgo2H` only.
+6. Click `data.flow = 200` — the model engages. Watch Port 0 in the debug pane: `oOtr`, `oKgo2H`, `oFluxPerM2`, `efficiency`, `slope` all populate; `idle` flips from `true` to `false`.
+7. Click `data.flow = 0` — `idle` flips back; derived outputs reset to zero. `oPLoss` falls to just the static head.
+
+> [!IMPORTANT]
+> **GIF needed.** Demo recording of steps 1–7 with the status badge progression. Save as `wiki/_partial-gifs/diffuser/01-basic-demo.gif`, target ≤ 1 MB after `gifsicle -O3 --lossy=80`.
+
+### Try the alarm band
+
+After steps 1–6 above the diffuser is at `oFluxPerM2 ≈ 12 Nm³/(h·m²)`. Push it past the curve's `maxX`:
+
+1. Set `set.elements = 10` (one tenth of the previous).
+2. With the same `data.flow = 200`, `oFluxPerM2` jumps roughly tenfold. The `_checkLimits` band fires; `alarm` becomes a non-empty array and the status badge turns red.
+3. Restore `set.elements = 100` — alarm clears.
+
+---
+
+## Example — Integration with Reactor (legacy `integration.flow.json`)
+
+> [!IMPORTANT]
+> **Screenshot needed.** Editor capture of `integration.flow.json`. Save as `wiki/_partial-screenshots/diffuser/02-integration.png`.
+
+A diffuser wired to a parent reactor. Demonstrates:
+
+- Auto-registration via Port 2 at deploy (the diffuser emits `child.register` with `positionVsParent='atEquipment'`).
+- Reactor consumes `oZoneOtr` from the diffuser's Port 0 (legacy reactor-control port has been merged into Port 0 in Phase 6).
+
+> [!NOTE]
+> The reactor's side of this contract has not been verified against the latest reactor submodule in this audit. Reactor wiki: https://gitea.wbd-rd.nl/RnD/reactor/wiki/Home
+
+---
+
+## Example — Edge Cases (legacy `edge.flow.json`)
+
+Drives the diffuser through:
+
+- `data.flow = 0` → idle reset path.
+- Very large `data.flow` → alarm band on `oFluxPerM2`.
+- Asset model id pointing at an unknown curve → fallback to `gva-elastox-r` (no constructor crash).
+
+---
+
+## Docker compose snippet
+
+To bring up Node-RED + InfluxDB with EVOLV nodes pre-loaded:
+
+```yaml
+# docker-compose.yml (extract)
+services:
+  nodered:
+    build: ./docker/nodered
+    ports: ['1880:1880']
+    volumes:
+      - ./docker/nodered/data:/data/evolv
+  influxdb:
+    image: influxdb:2.7
+    ports: ['8086:8086']
+```
+
+Full file: [EVOLV/docker-compose.yml](https://gitea.wbd-rd.nl/RnD/EVOLV/src/branch/development/docker-compose.yml).
+
+---
+
+## Debug recipes
+
+| Symptom | First thing to check | Where to look |
+|:---|:---|:---|
+| `oOtr` stays at `0` | `iFlow` is zero or negative → `idle = true`. Push a positive value via `data.flow`. | `_recalculate` early-return path. |
+| `oZoneOtr` is `0` even though `oKgo2H > 0` | `diffuser.zoneVolume` is unset or non-positive. Set it in the editor or via config. | `getReactorOtr(zoneVolumeM3)`. |
+| `warning` / `alarm` always firing | `oFluxPerM2` is outside the loaded curve's `[minX, maxX]` band ± hysteresis. Either the flow is wildly off the asset's design point or the wrong curve is loaded. | `_checkLimits`, `_loadSpecs`. |
+| `nFlow` does not equal `iFlow` | Air-density correction. Header pressure and atmospheric pressure deviate from the standard baseline (T=20 °C, p=1.01325 bar, RH=0). | `_calcAirDensityMbar`. |
+| `efficiency` is flat at `0` | OTR or ΔP curve span is zero in the operating band. Inspect the supplier curve. | `_combineEff`. |
+| Constructor throws `curve '…' is missing otr_curve/p_curve` | The `asset.model` field references a curve id that exists in the registry but lacks one of the required curves. Pick a complete model in the editor. | `_loadSpecs`. |
+| Editor palette colour wrong | `diffuser.html` already declares `color: '#86bbdd'` (Equipment Module). If a stale palette shows otherwise, hard-refresh the editor or check the Node-RED version. | `diffuser.html`. |
+| Alias warns spammed every tick | A consumer is sending the legacy alias on every tick instead of the canonical topic. Aliases warn **once** per deploy — if you're seeing repeats, something is re-creating the node. | `src/commands/index.js` alias list. |
+
+> Never ship `enableLog: 'debug'` in a demo — fills the container log within seconds and obscures real errors.
+
+---
+
+## Related pages
+
+| Page | Why |
+|:---|:---|
+| [Home](Home) | Intuitive overview |
+| [Reference — Contracts](Reference-Contracts) | Topic + config + child registration |
+| [Reference — Architecture](Reference-Architecture) | Code map, OTR / ΔP pipeline |
+| [Reference — Limitations](Reference-Limitations) | Known issues and open questions |
+| [reactor — Examples](https://gitea.wbd-rd.nl/RnD/reactor/wiki/Reference-Examples) | Parent-side example flows |
+| [EVOLV — Topology Patterns](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Topology-Patterns) | Where diffuser fits in a larger plant |