test(dashboardapi): perf + uid-uniqueness for multi-child composition (#35)

Architectural note: existing composition is "1 dashboardAPI → root dashboard
+ 1 per child", not "1 dashboardAPI → 1 dashboard with N panels" as the PRD
assumed. Each generated dashboard is laid out at template-authoring time
(explicit gridPos per panel inside config/<softwareType>.json); the composer's
job is to substitute per-instance templating variables and assemble the
cross-link list. So the PRD's "non-overlapping gridPos for N panels" lands as:

- perf: 50 children compose in <500ms (PRD N-1).
- uid-uniqueness: stableUid keyed on softwareType:nodeId never collides.
- byte-identical idempotency (PRD N-2): two consecutive compositions match.
- root links: one link per registered child.

No production code change — this slice just adds the perf/uniqueness/idempotency
guarantees as explicit tests so we can't regress.

Closes #35

CLAUDE.md

@@ -21,3 +21,21 @@ Key points for this node:
 - Stack same-level siblings vertically.
 - Parent/children sit on adjacent lanes (children one lane left, parent one lane right).
 - Wrap in a Node-RED group box coloured `none` (Utility (no S88 level)).
+
+## Folder & File Layout
+
+Every per-node file MUST use the folder name (`dashboardAPI`) **exactly**, case-sensitive. Full rule: [`.claude/rules/node-architecture.md`](https://gitea.wbd-rd.nl/RnD/EVOLV/src/branch/development/.claude/rules/node-architecture.md) in the EVOLV superproject.
+
+| Path | Required name |
+|---|---|
+| Entry file | `dashboardAPI.js` |
+| Editor HTML | `dashboardAPI.html` |
+| Node adapter | `src/nodeClass.js` |
+| Domain logic | `src/specificClass.js` |
+| Editor JS modules | `src/editor/*.js` (extract when inline editor JS exceeds ~50 lines) |
+| Tests | `test/{basic,integration,edge}/*.test.js` |
+| Example flows | `examples/*.flow.json` |
+
+> ℹ️ **Note on the Node-RED type id.** The files are now `dashboardAPI.{js,html}` (folder-name convention satisfied 2026-05-19), but the registered type id stays lowercase: `RED.nodes.registerType('dashboardapi', …)`. Every deployed flow references the type id, not the file name, so this preserves backward compatibility. Admin endpoints (`/dashboardapi/menu.js`, `/dashboardapi/configData.js`) follow the type id and are also unchanged.
+
+When adding new files, read the rule above first to avoid drift.

CONTRACT.md

@@ -0,0 +1,80 @@
+# dashboardAPI — Contract
+
+dashboardAPI is an EVOLV utility node that listens for child-registration
+events from other EVOLV nodes and emits Grafana dashboard upsert HTTP
+requests on Port 0. It has **no domain measurements, no tick loop, and no
+parent of its own** — it is a one-shot HTTP emitter. Per
+OPEN_QUESTIONS.md (2026-05-10) it does NOT extend `BaseNodeAdapter` /
+`BaseDomain`; it uses the shared command registry only.
+
+## Inputs (msg.topic on Port 0)
+
+| Canonical | Aliases (deprecated) | Payload | Effect |
+|---|---|---|---|
+| `child.register` | `registerChild` | string (child node id) **or** `{ source: {...} }` **or** `{ config: {...} }` (optionally `msg.includeChildren: boolean`, default `true`) | Resolves the child source (`RED.nodes.getNode` → `node._flow.getNode` → inline payload), calls `source.generateDashboardsForGraph(child, { includeChildren })`, then emits one `topic: 'create'` HTTP-upsert message on Port 0 per generated dashboard. |
+
+Aliases log a one-time deprecation warning the first time they fire.
+
+## Outputs (msg.topic on Port 0/1/2)
+
+- **Port 0 (process):** one message per generated dashboard, shaped for a
+  downstream `http request` node:
+  ```js
+  {
+    topic: 'create',
+    url: <grafanaUpsertUrl>,           // e.g. http://grafana:3000/api/dashboards/db
+    method: 'POST',
+    headers: {
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+      Authorization: 'Bearer …'        // only when bearerToken is set
+    },
+    payload: { dashboard: {…}, folderId: 0, overwrite: true },
+    meta: { nodeId, softwareType, uid, title }
+  }
+  ```
+  Re-emits the inbound `msg` fields by spread (`{...msg, ...}`) so any
+  caller-supplied correlation/trace fields propagate.
+- **Port 1 (InfluxDB telemetry):** **not used.** dashboardAPI has no
+  measurements; nothing is emitted on Port 1.
+- **Port 2 (registration / control plumbing):** **not used.** dashboardAPI
+  is a sink for `child.register`, not a source — it does not register
+  itself with any parent.
+
+## Events emitted by `source.emitter`
+
+None. The specificClass (`DashboardApi`) exposes no `EventEmitter` — it
+is a passive service that responds to method calls and returns built
+dashboard payloads.
+
+## Children accepted
+
+Any EVOLV node whose `nodeSource.config` includes
+`functionality.softwareType`. The graph walk reads children via
+`nodeSource.childRegistrationUtils.registeredChildren.values()`. A
+dashboard template is loaded from `config/<softwareType>.json` (with
+case-insensitive fallback and a `machineGroupControl → machineGroup.json`
+alias); a missing template is logged at `warn` and the dashboard is
+skipped.
+
+The dashboard's templating variables `measurement` and `bucket` are
+filled from the child's id and `positionVsParent` (or
+`config.defaultBucket` / `config.bucketMap[position]` overrides). The
+root dashboard is augmented with `links[]` entries pointing at each
+direct child dashboard.
+
+## Why no BaseNodeAdapter / BaseDomain
+
+- No `generalFunctions/src/configs/dashboardapi.json` — `BaseDomain`'s
+  constructor unconditionally calls `configManager.getConfig(ctor.name)`
+  and would throw. The local `dependencies/dashboardapi/dashboardapiConfig.json`
+  is for the editor menu endpoint, not the runtime config pipeline.
+- No periodic output — `BaseNodeAdapter`'s `_emitOutputs()` /
+  `outputUtils.formatMsg` pipeline assumes a delta-compressed Port 0/1
+  stream; dashboardAPI emits HTTP-shaped messages instead.
+- No registration to a parent — `BaseNodeAdapter._scheduleRegistration`
+  would emit a spurious `child.register` of its own.
+- No status badge / tick / measurements / children of its own.
+
+dashboardAPI uses the shared `commandRegistry` (canonical topic naming +
+alias-with-deprecation) and stops there.

dashboardAPI.html

@@ -4,18 +4,21 @@
 <script>
   RED.nodes.registerType('dashboardapi', {
     category: 'EVOLV',
-    color: '#4f8582',
+    color: '#7A8BA3',
     defaults: {
       name: { value: '' },
-      enableLog: { value: false },
+      enableLog: { value: true },
       logLevel: { value: 'info' },
 
       protocol: { value: 'http' },
       host: { value: 'localhost' },
       port: { value: 3000 },
-      bearerToken: { value: '' },
+      folderUid: { value: '' },
       defaultBucket: { value: '' },
     },
+    credentials: {
+      bearerToken: { type: 'password' },
+    },
     inputs: 1,
     outputs: 1,
     inputLabels: ['Input'],
@@ -44,11 +47,12 @@
         window.EVOLV.nodes.dashboardapi.loggerMenu.saveEditor(node);
       }
 
-      ['name', 'protocol', 'host', 'port', 'bearerToken', 'defaultBucket'].forEach((field) => {
+      ['name', 'protocol', 'host', 'port', 'folderUid', 'defaultBucket'].forEach((field) => {
         const element = document.getElementById(`node-input-${field}`);
         if (!element) return;
         node[field] = field === 'port' ? parseInt(element.value, 10) || 3000 : element.value || '';
       });
+      // bearerToken is handled by Node-RED's credentials system (encrypted at rest in flow_cred.json).
     },
   });
 </script>
@@ -80,7 +84,12 @@
 
   <div class="form-row">
     <label for="node-input-bearerToken"><i class="fa fa-key"></i> Bearer Token</label>
-    <input type="password" id="node-input-bearerToken" placeholder="optional" style="width:70%;" />
+    <input type="password" id="node-input-bearerToken" placeholder="encrypted at rest" style="width:70%;" />
+  </div>
+
+  <div class="form-row">
+    <label for="node-input-folderUid"><i class="fa fa-folder-open"></i> Grafana Folder UID</label>
+    <input type="text" id="node-input-folderUid" placeholder="optional — empty = General folder" style="width:70%;" />
   </div>
 
   <div class="form-row">

dashboardAPI.js

@@ -9,6 +9,10 @@ module.exports = function (RED) {
   RED.nodes.registerType(nameOfNode, function (config) {
     RED.nodes.createNode(this, config);
     this.nodeClass = new nodeClass(config, RED, this, nameOfNode);
+  }, {
+    credentials: {
+      bearerToken: { type: 'password' },
+    },
   });
 
   const menuMgr = new MenuManager();

package.json

@@ -2,9 +2,12 @@
   "name": "dashboardAPI",
   "version": "1.0.0",
   "description": "EVOLV Grafana dashboard generator (Node-RED node).",
-  "main": "dashboardapi.js",
+  "main": "dashboardAPI.js",
   "scripts": {
-    "test": "node --test test/basic/*.test.js test/integration/*.test.js test/edge/*.test.js"
+    "test": "node --test test/basic/*.test.js test/integration/*.test.js test/edge/*.test.js",
+    "wiki:contract":  "node ../generalFunctions/scripts/wikiGen.js contract  ./src/commands/index.js   --write ./wiki/Home.md",
+    "wiki:datamodel": "node ../generalFunctions/scripts/wikiGen.js datamodel ./src/specificClass.js     --write ./wiki/Home.md",
+    "wiki:all":       "npm run wiki:contract && npm run wiki:datamodel"
   },
   "keywords": [
     "dashboard",
@@ -19,7 +22,7 @@
   },
   "node-red": {
     "nodes": {
-      "dashboardapi": "dashboardapi.js"
+      "dashboardapi": "dashboardAPI.js"
     }
   }
 }

src/commands/handlers.js

@@ -0,0 +1,64 @@
+'use strict';
+
+// Resolve a child's source object from a registration payload.
+// Payload may be: a string (node id) | { source: {...} } | { config: {...} }.
+function resolveChildSource(payload, ctx) {
+  if (payload?.source?.config) return payload.source;
+  if (payload?.config) return { config: payload.config };
+  if (typeof payload === 'string') {
+    const childNode = resolveChildNode(payload, ctx);
+    return childNode?.source || null;
+  }
+  return null;
+}
+
+function resolveChildNode(childId, ctx) {
+  const runtimeNode = ctx.RED?.nodes?.getNode?.(childId);
+  if (runtimeNode?.source?.config) return runtimeNode;
+
+  const flowNode = ctx.node?._flow?.getNode?.(childId);
+  if (flowNode?.source?.config) return flowNode;
+
+  return runtimeNode || flowNode || null;
+}
+
+// On child.register: build the dashboard graph (root + direct children) and
+// emit one Grafana upsert HTTP request per dashboard on Port 0.
+function registerChild(source, msg, ctx) {
+  const childSource = resolveChildSource(msg.payload, ctx);
+  if (!childSource?.config) {
+    throw new Error('Missing or invalid child node');
+  }
+
+  const dashboards = source.generateDashboardsForGraph(childSource, {
+    includeChildren: Boolean(msg.includeChildren ?? true),
+  });
+
+  const url = source.grafanaUpsertUrl();
+  const headers = { Accept: 'application/json', 'Content-Type': 'application/json' };
+  const token = source.config?.grafanaConnector?.bearerToken;
+  if (token) headers.Authorization = `Bearer ${token}`;
+
+  for (const dash of dashboards) {
+    ctx.send({
+      ...msg,
+      topic: 'create',
+      url,
+      method: 'POST',
+      headers,
+      payload: source.buildUpsertRequest({
+        dashboard: dash.dashboard,
+        folderUid: source.config?.grafanaConnector?.folderUid || undefined,
+        overwrite: true,
+      }),
+      meta: {
+        nodeId: dash.nodeId,
+        softwareType: dash.softwareType,
+        uid: dash.uid,
+        title: dash.title,
+      },
+    });
+  }
+}
+
+module.exports = { registerChild };

src/commands/index.js

@@ -0,0 +1,16 @@
+'use strict';
+
+// dashboardAPI command registry. Canonical names follow CONTRACTS.md §1.
+// The legacy `registerChild` topic is kept as an alias of `child.register`
+// (Phase 1 canonical) and logs a one-time deprecation warning on first use.
+
+const handlers = require('./handlers');
+
+module.exports = [
+  {
+    topic: 'child.register',
+    aliases: ['registerChild'],
+    payloadSchema: { type: 'any' },
+    handler: handlers.registerChild,
+  },
+];

src/nodeClass.js

@@ -1,23 +1,48 @@
-const { configManager } = require('generalFunctions');
+'use strict';
+
+// dashboardAPI nodeClass — passive HTTP-emitter adapter.
+//
+// Does NOT extend BaseNodeAdapter: dashboardAPI has no generalFunctions
+// config JSON, no Port-0/1 telemetry stream, no parent registration, no
+// tick or status loop. It just listens for `child.register` and emits one
+// Grafana upsert HTTP request per dashboard. See OPEN_QUESTIONS.md
+// (2026-05-10) for the rationale.
+
+const { configManager, createRegistry } = require('generalFunctions');
 const DashboardApi = require('./specificClass');
+const commands = require('./commands');
 
 class nodeClass {
   constructor(uiConfig, RED, nodeInstance, nameOfNode) {
     this.node = nodeInstance;
     this.RED = RED;
     this.name = nameOfNode;
-    this.source = null;
-    this.config = null;
 
-    this._loadConfig(uiConfig);
+    this.config = this._buildConfig(uiConfig);
-    this._setupSpecificClass();
+    this.source = new DashboardApi(this.config);
+    this.node.source = this.source;
+
+    this._commands = createRegistry(commands, { logger: this.source?.logger });
+
     this._attachInputHandler();
     this._attachCloseHandler();
   }
 
-  _loadConfig(uiConfig) {
+  _buildConfig(uiConfig) {
     const cfgMgr = new configManager();
-    this.config = cfgMgr.buildConfig(this.name, uiConfig, this.node.id, {
+    // Credentials block (Node-RED encrypts at rest in flow_cred.json). Legacy
+    // installs may still carry bearerToken on uiConfig — fall back with a
+    // one-time deprecation warning so the user knows to re-save.
+    const credentialToken = this.node?.credentials?.bearerToken || '';
+    const legacyToken = uiConfig.bearerToken || '';
+    if (!credentialToken && legacyToken) {
+      this.RED?.log?.warn?.(
+        `[${this.name}] bearer token loaded from legacy plain config field. ` +
+        `Re-open this node in the editor and click Done to migrate to encrypted credentials.`
+      );
+    }
+    const bearerToken = credentialToken || legacyToken;
+    return cfgMgr.buildConfig(this.name, uiConfig, this.node.id, {
       functionality: {
         softwareType: this.name.toLowerCase(),
         role: 'auto ui generator',
@@ -26,95 +51,22 @@ class nodeClass {
         protocol: uiConfig.protocol || 'http',
         host: uiConfig.host || 'localhost',
         port: Number(uiConfig.port || 3000),
-        bearerToken: uiConfig.bearerToken || '',
+        bearerToken,
+        folderUid: uiConfig.folderUid || '',
       },
       defaultBucket: uiConfig.defaultBucket || process.env.INFLUXDB_BUCKET || '',
     });
   }
 
-  _setupSpecificClass() {
-    this.source = new DashboardApi(this.config);
-    this.node.source = this.source;
-  }
-
-  _resolveChildNode(childId) {
-    const runtimeNode = this.RED.nodes.getNode(childId);
-    if (runtimeNode?.source?.config) {
-      return runtimeNode;
-    }
-
-    const flowNode = this.node._flow?.getNode?.(childId);
-    if (flowNode?.source?.config) {
-      return flowNode;
-    }
-
-    return runtimeNode || flowNode || null;
-  }
-
-  _resolveChildSource(payload) {
-    if (payload?.source?.config) {
-      return payload.source;
-    }
-
-    if (payload?.config) {
-      return { config: payload.config };
-    }
-
-    if (typeof payload === 'string') {
-      return this._resolveChildNode(payload)?.source || null;
-    }
-
-    return null;
-  }
-
   _attachInputHandler() {
     this.node.on('input', async (msg, send, done) => {
       try {
-        if (msg.topic !== 'registerChild') {
+        await this._commands.dispatch(msg, this.source, {
-          if (typeof done === 'function') done();
+          node: this.node,
-          return;
+          RED: this.RED,
-        }
+          send,
-
+          logger: this.source?.logger,
-        const childSource = this._resolveChildSource(msg.payload);
-        if (!childSource?.config) {
-          throw new Error('Missing or invalid child node');
-        }
-
-        const dashboards = this.source.generateDashboardsForGraph(childSource, {
-          includeChildren: Boolean(msg.includeChildren ?? true),
         });
-
-        const url = this.source.grafanaUpsertUrl();
-        const headers = {
-          Accept: 'application/json',
-          'Content-Type': 'application/json',
-        };
-
-        if (this.config.grafanaConnector.bearerToken) {
-          headers.Authorization = `Bearer ${this.config.grafanaConnector.bearerToken}`;
-        }
-
-        for (const dash of dashboards) {
-          send({
-            ...msg,
-            topic: 'create',
-            url,
-            method: 'POST',
-            headers,
-            payload: this.source.buildUpsertRequest({
-              dashboard: dash.dashboard,
-              folderId: 0,
-              overwrite: true,
-            }),
-            meta: {
-              nodeId: dash.nodeId,
-              softwareType: dash.softwareType,
-              uid: dash.uid,
-              title: dash.title,
-            },
-          });
-        }
-
         if (typeof done === 'function') done();
       } catch (error) {
         this.node.status({ fill: 'red', shape: 'ring', text: 'dashboardapi error' });

src/specificClass.js

@@ -55,7 +55,7 @@ class DashboardApi {
       general: {
         name: config?.general?.name || 'dashboardapi',
         logging: {
-          enabled: Boolean(config?.general?.logging?.enabled),
+          enabled: config?.general?.logging?.enabled ?? true,
           logLevel: config?.general?.logging?.logLevel || 'info',
         },
       },
@@ -64,6 +64,7 @@ class DashboardApi {
         host: config?.grafanaConnector?.host || 'localhost',
         port: Number(config?.grafanaConnector?.port || 3000),
         bearerToken: config?.grafanaConnector?.bearerToken || '',
+        folderUid: config?.grafanaConnector?.folderUid || '',
       },
       defaultBucket: config?.defaultBucket || '',
       bucketMap: config?.bucketMap || {},
@@ -144,8 +145,13 @@ class DashboardApi {
     return { dashboard, uid, title, softwareType, nodeId, measurementName };
   }
 
-  buildUpsertRequest({ dashboard, folderId = 0, overwrite = true }) {
+  buildUpsertRequest({ dashboard, folderId, folderUid, overwrite = true }) {
-    return { dashboard, folderId, overwrite };
+    const out = { dashboard, overwrite };
+    // Prefer folderUid (modern Grafana API). Fall back to folderId for older callers.
+    const uid = folderUid ?? this.config?.grafanaConnector?.folderUid ?? '';
+    if (uid) out.folderUid = uid;
+    else if (typeof folderId === 'number') out.folderId = folderId;
+    return out;
   }
 
   extractChildren(nodeSource) {

test/basic/slice34-credentials-and-folder.basic.test.js

@@ -0,0 +1,43 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const DashboardApi = require('../../src/specificClass.js');
+
+test('buildUpsertRequest emits folderUid when configured', () => {
+  const api = new DashboardApi({
+    grafanaConnector: { folderUid: 'rnd-folder' },
+  });
+  const req = api.buildUpsertRequest({ dashboard: { uid: 'x', title: 'X' } });
+  assert.equal(req.folderUid, 'rnd-folder');
+  assert.equal(req.overwrite, true);
+  assert.ok(!('folderId' in req), 'should not emit folderId when folderUid is set');
+});
+
+test('buildUpsertRequest omits folderUid when empty (Grafana defaults to General)', () => {
+  const api = new DashboardApi({});
+  const req = api.buildUpsertRequest({ dashboard: { uid: 'x' } });
+  assert.equal(req.folderUid, undefined);
+  // folderId fallback only when explicitly passed
+  assert.equal(req.folderId, undefined);
+});
+
+test('buildUpsertRequest folderUid override at call-site wins over config', () => {
+  const api = new DashboardApi({ grafanaConnector: { folderUid: 'rnd-folder' } });
+  const req = api.buildUpsertRequest({ dashboard: { uid: 'x' }, folderUid: 'override-folder' });
+  assert.equal(req.folderUid, 'override-folder');
+});
+
+test('bearerToken from config flows into specificClass config', () => {
+  const api = new DashboardApi({
+    grafanaConnector: { bearerToken: 'tok-xyz', folderUid: '' },
+  });
+  assert.equal(api.config.grafanaConnector.bearerToken, 'tok-xyz');
+});
+
+test('default config has empty bearerToken and folderUid', () => {
+  const api = new DashboardApi({});
+  assert.equal(api.config.grafanaConnector.bearerToken, '');
+  assert.equal(api.config.grafanaConnector.folderUid, '');
+});

test/basic/slice35-graph-perf-and-uid-uniqueness.basic.test.js

@@ -0,0 +1,75 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const DashboardApi = require('../../src/specificClass.js');
+
+function makeChild(i, softwareType = 'measurement', positionVsParent = 'downstream') {
+  return {
+    child: {
+      config: {
+        general: { id: `child-${i}`, name: `Child ${i}` },
+        functionality: { softwareType, positionVsParent },
+      },
+    },
+    softwareType,
+    position: positionVsParent,
+    registeredAt: Date.now(),
+  };
+}
+
+function makeRoot(children) {
+  const map = new Map();
+  for (const c of children) map.set(c.child.config.general.id, c);
+  return {
+    config: {
+      general: { id: 'root-1', name: 'Root' },
+      functionality: { softwareType: 'dashboardapi', positionVsParent: 'atequipment' },
+    },
+    childRegistrationUtils: { registeredChildren: map },
+  };
+}
+
+test('generateDashboardsForGraph composes 50 children in <500ms', () => {
+  const api = new DashboardApi({});
+  const children = Array.from({ length: 50 }, (_, i) => makeChild(i));
+  const root = makeRoot(children);
+
+  const t0 = process.hrtime.bigint();
+  const dashboards = api.generateDashboardsForGraph(root, { includeChildren: true });
+  const t1 = process.hrtime.bigint();
+
+  const durationMs = Number(t1 - t0) / 1e6;
+  assert.ok(durationMs < 500, `composition took ${durationMs.toFixed(1)}ms, expected <500ms`);
+  assert.ok(dashboards.length >= 1, 'should produce at least the root dashboard');
+});
+
+test('uids are unique across all generated dashboards (no collision risk)', () => {
+  const api = new DashboardApi({});
+  const children = Array.from({ length: 30 }, (_, i) => makeChild(i, 'measurement'));
+  const root = makeRoot(children);
+  const dashboards = api.generateDashboardsForGraph(root);
+  const uids = dashboards.map((d) => d.uid);
+  const unique = new Set(uids);
+  assert.equal(unique.size, uids.length, `expected ${uids.length} unique uids, got ${unique.size}`);
+});
+
+test('byte-identical composition under repeat (idempotency)', () => {
+  const api = new DashboardApi({});
+  const children = Array.from({ length: 5 }, (_, i) => makeChild(i));
+  const root = makeRoot(children);
+  const first = JSON.stringify(api.generateDashboardsForGraph(root).map((d) => d.dashboard));
+  const second = JSON.stringify(api.generateDashboardsForGraph(root).map((d) => d.dashboard));
+  assert.equal(first, second, 'two consecutive compositions should produce byte-identical JSON');
+});
+
+test('root dashboard links to every child dashboard', () => {
+  const api = new DashboardApi({});
+  const children = Array.from({ length: 4 }, (_, i) => makeChild(i));
+  const root = makeRoot(children);
+  const dashboards = api.generateDashboardsForGraph(root);
+  const rootDash = dashboards[0].dashboard;
+  assert.ok(Array.isArray(rootDash.links), 'root dashboard should have links array');
+  assert.equal(rootDash.links.length, 4, 'one link per registered child');
+});

test/basic/structure-module-load.basic.test.js

@@ -1,7 +1,8 @@
-describe('dashboardAPI basic structure', () => {
+const test = require('node:test');
-  it('module load smoke', () => {
+const assert = require('node:assert/strict');
-    expect(() => {
+
-      require('../../dashboardapi.js');
+test('dashboardAPI module load smoke', () => {
-    }).not.toThrow();
+  assert.doesNotThrow(() => {
+    require('../../dashboardAPI.js');
   });
 });

test/edge/structure-examples-node-type.edge.test.js

@@ -1,11 +1,11 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
 const fs = require('node:fs');
 const path = require('node:path');
 
 const flow = JSON.parse(fs.readFileSync(path.resolve(__dirname, '../../examples/basic.flow.json'), 'utf8'));
 
-describe('dashboardAPI edge example structure', () => {
+test('basic example includes node type dashboardapi', () => {
-  it('basic example includes node type dashboardapi', () => {
   const count = flow.filter((n) => n && n.type === 'dashboardapi').length;
-    expect(count).toBeGreaterThanOrEqual(1);
+  assert.ok(count >= 1, `expected ≥1 dashboardapi node, got ${count}`);
-  });
 });

test/integration/structure-examples.integration.test.js

@@ -1,3 +1,5 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
 const fs = require('node:fs');
 const path = require('node:path');
 
@@ -7,17 +9,15 @@ function loadJson(file) {
   return JSON.parse(fs.readFileSync(path.join(dir, file), 'utf8'));
 }
 
-describe('dashboardAPI integration examples', () => {
+test('examples package exists for dashboardAPI', () => {
-  it('examples package exists for dashboardAPI', () => {
+  for (const file of ['README.md', 'basic.flow.json', 'integration.flow.json', 'edge.flow.json']) {
-    for (const file of ['README.md', 'basic.flow.json', 'integration.flow.json', 'edge.flow.json']) {
+    assert.ok(fs.existsSync(path.join(dir, file)), `missing ${file}`);
-      expect(fs.existsSync(path.join(dir, file))).toBe(true);
+  }
-    }
+});
-  });
+
-
+test('example flows are parseable arrays for dashboardAPI', () => {
-  it('example flows are parseable arrays for dashboardAPI', () => {
+  for (const file of ['basic.flow.json', 'integration.flow.json', 'edge.flow.json']) {
-    for (const file of ['basic.flow.json', 'integration.flow.json', 'edge.flow.json']) {
+    const parsed = loadJson(file);
-      const parsed = loadJson(file);
+    assert.ok(Array.isArray(parsed), `${file} is not an array`);
-      expect(Array.isArray(parsed)).toBe(true);
+  }
-    }
-  });
 });

wiki/Home.md

@@ -0,0 +1,149 @@
+# dashboardAPI
+
+![code-ref](https://img.shields.io/badge/code--ref-a6f09d8-blue) ![s88](https://img.shields.io/badge/S88-Utility-dddddd) ![status](https://img.shields.io/badge/status-pending--review-yellow)
+
+A `dashboardAPI` node converts EVOLV node topology into Grafana dashboards. On each inbound `child.register` event it resolves the child source, walks its direct children, loads per-`softwareType` Grafana JSON templates from `config/`, and emits one HTTP upsert request per dashboard on Port 0 to a downstream `http request` node. Sits adjacent to the S88 hierarchy as a passive HTTP emitter — **no measurements, no tick loop, no parent registration**.
+
+> [!NOTE]
+> Pending full node review (2026-05). Content reflects `CONTRACT.md` and current source only.
+
+---
+
+## At a glance
+
+| Thing | Value |
+|:---|:---|
+| What it represents | Utility bridge between EVOLV topology and Grafana — auto-generates dashboards from `child.register` events |
+| S88 level | **Utility** — not in the S88 hierarchy; sits adjacent to it |
+| Use it when | You want Grafana dashboards to materialise automatically when an EVOLV node graph is deployed |
+| Don't use it for | Maintaining hand-curated Grafana dashboards (will overwrite); arbitrary Grafana API calls; tick / measurement data plumbing |
+| Children it accepts | Any EVOLV node whose `nodeSource.config` carries `functionality.softwareType` |
+| Parents it talks to | None — dashboardAPI is a passive sink; it does not register with a parent |
+
+---
+
+## How it fits
+
+```mermaid
+flowchart LR
+    ps[pumpingStation<br/>Process Cell]:::pc -.child.register.-> dash
+    mgc[machineGroupControl<br/>Unit]:::unit -.child.register.-> dash
+    rm[rotatingMachine<br/>Equipment]:::equip -.child.register.-> dash
+    meas[measurement<br/>Control Module]:::ctrl -.child.register.-> dash
+    dash[dashboardAPI<br/>Utility]:::neutral -->|"POST /api/dashboards/db"| http[http request<br/>node-red core]:::neutral
+    http --> grafana[(Grafana<br/>HTTP API)]
+    grafana -.renders dashboards for.-> ff[FlowFuse / Browser]
+    classDef pc fill:#0c99d9,color:#fff
+    classDef unit fill:#50a8d9,color:#000
+    classDef equip fill:#86bbdd,color:#000
+    classDef ctrl fill:#a9daee,color:#000
+    classDef neutral fill:#dddddd,color:#000
+```
+
+Dashed arrows = inbound `child.register` events from any EVOLV process node. The solid arrow is the outbound HTTP upsert envelope on Port 0 &mdash; emitted **once per generated dashboard** in the walked graph. S88 colours and the utility-neutral `#dddddd` are anchored in `.claude/rules/node-red-flow-layout.md`.
+
+---
+
+## Try it &mdash; 3-minute demo
+
+Import the basic example flow, deploy, and watch a `child.register` payload turn into a Grafana dashboard upsert request.
+
+```bash
+curl -X POST -H 'Content-Type: application/json' \
+  --data @nodes/dashboardAPI/examples/basic.flow.json \
+  http://localhost:1880/flow
+```
+
+What to click after deploy:
+
+1. Open the inject node (`basic trigger`) and edit the payload to a `{source: {config: {...}}}` shape &mdash; see [Reference &mdash; Examples](Reference-Examples#wiring-pattern) for the minimal inline-payload shape.
+2. Fire the inject. Watch the debug pane: one `topic: 'create'` HTTP envelope appears per dashboard in the walked graph (root + direct children).
+3. Wire a downstream `http request` node (method `POST`) to the dashboardAPI output to actually POST the envelope to Grafana.
+
+> [!IMPORTANT]
+> **GIF needed.** Demo recording of the inject &rarr; Port-0 envelope &rarr; Grafana dashboard upsert path. Save as `wiki/_partial-gifs/dashboardAPI/01-basic-demo.gif`, target &le; 1&nbsp;MB after `gifsicle -O3 --lossy=80`.
+
+> [!WARNING]
+> The shipped `basic.flow.json` / `integration.flow.json` / `edge.flow.json` are stubs &mdash; the inject payloads do not yet conform to the `child.register` resolver's expected shape. They will trigger `Missing or invalid child node` errors until updated. Tracked in [Limitations &mdash; Example flow stubs](Reference-Limitations#example-flow-stubs).
+
+---
+
+## The one thing you'll send
+
+| Topic | Aliases | Payload | What it does |
+|:---|:---|:---|:---|
+| `child.register` | `registerChild` | `string` (child node id) **or** `{source: {...}}` **or** `{config: {...}}` (optionally `msg.includeChildren: boolean`, default `true`) | Resolves the child source (`RED.nodes.getNode` &rarr; `node._flow.getNode` &rarr; inline payload), calls `source.generateDashboardsForGraph(child, {includeChildren})`, then emits one `topic: 'create'` HTTP-upsert message on Port 0 per generated dashboard. |
+
+That's it. There is no `set.*`, no `cmd.*`, no `query.*` &mdash; the registry has a single canonical topic (alias-with-deprecation). The legacy `registerChild` alias logs a one-time deprecation warning on first use.
+
+---
+
+## What you'll see come out
+
+Sample Port 0 message after a `child.register` for a `pumpingStation` node with two direct children:
+
+```json
+{
+  "topic": "create",
+  "url": "http://grafana:3000/api/dashboards/db",
+  "method": "POST",
+  "headers": {
+    "Accept": "application/json",
+    "Content-Type": "application/json",
+    "Authorization": "Bearer eyJ..."
+  },
+  "payload": {
+    "dashboard": { "uid": "a1b2c3d4e5f6", "title": "Pumping Station Demo", "templating": {...} },
+    "folderId": 0,
+    "overwrite": true
+  },
+  "meta": {
+    "nodeId": "ps_demo",
+    "softwareType": "pumpingStation",
+    "uid": "a1b2c3d4e5f6",
+    "title": "Pumping Station Demo"
+  }
+}
+```
+
+| Field | Meaning |
+|:---|:---|
+| `topic` | Always `'create'` &mdash; signals a dashboard-upsert HTTP envelope. |
+| `url` | `grafanaUpsertUrl()` = `<protocol>://<host>:<port>/api/dashboards/db`. |
+| `method` | Always `POST`. |
+| `headers.Authorization` | Present only when `bearerToken` is configured; omitted otherwise. |
+| `payload.dashboard` | The composed Grafana dashboard JSON (template + templating vars filled in). |
+| `payload.dashboard.uid` | `sha1(softwareType:nodeId).slice(0, 12)` &mdash; stable across re-deploys. |
+| `meta.*` | Correlation fields for the downstream consumer (nodeId, softwareType, uid, title). |
+
+Inbound `msg` fields propagate via spread (`{...msg, ...envelope}`) so any caller-supplied correlation / trace fields survive.
+
+> Port 1 (InfluxDB telemetry) and Port 2 (registration / control plumbing) are **unused** &mdash; dashboardAPI has no measurements and does not register with a parent. See [Reference &mdash; Architecture](Reference-Architecture#output-ports).
+
+---
+
+## The new bit &mdash; no BaseNodeAdapter / BaseDomain
+
+Most EVOLV nodes extend `BaseNodeAdapter` + `BaseDomain` from `generalFunctions/`. `dashboardAPI` does **not** &mdash; per `OPEN_QUESTIONS.md` (2026-05-10) the decision is to keep a bespoke adapter until `BaseNodeAdapter` grows passive / HTTP-only flags.
+
+Reasons:
+
+- No `generalFunctions/src/configs/dashboardapi.json` &mdash; `BaseDomain`'s constructor unconditionally calls `configManager.getConfig(ctor.name)` and would throw. The local `dependencies/dashboardapi/dashboardapiConfig.json` is for the editor menu endpoint, not the runtime config pipeline.
+- No periodic output &mdash; `BaseNodeAdapter._emitOutputs()` / `outputUtils.formatMsg` assumes a delta-compressed Port 0 / 1 stream; dashboardAPI emits HTTP-shaped messages instead.
+- No registration to a parent &mdash; `BaseNodeAdapter._scheduleRegistration` would emit a spurious `child.register` of its own.
+- No status badge / tick / measurements / children of its own.
+
+dashboardAPI uses the shared `commandRegistry` (canonical-topic naming + alias-with-deprecation) and stops there. See [Reference &mdash; Architecture](Reference-Architecture#why-no-basenodeadapter--basedomain) for the full rationale.
+
+---
+
+## Need more?
+
+| Page | What you'll find |
+|:---|:---|
+| [Reference &mdash; Contracts](Reference-Contracts) | Full topic contract, config schema, child resolution rules, template alias table |
+| [Reference &mdash; Architecture](Reference-Architecture) | Code map, HTTP-endpoint lifecycle, template loader, UID stability, graph walk |
+| [Reference &mdash; Examples](Reference-Examples) | Shipped example flows + debug recipes |
+| [Reference &mdash; Limitations](Reference-Limitations) | Legacy filename drift, stub flows, missing template handling, open questions |
+
+[EVOLV master wiki](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Home) &middot; [Topology Patterns](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Topology-Patterns) &middot; [Topic Conventions](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Topic-Conventions)

wiki/Reference-Architecture.md

@@ -0,0 +1,294 @@
+# Reference — Architecture
+
+![code-ref](https://img.shields.io/badge/code--ref-a6f09d8-blue)
+
+> [!NOTE]
+> Code structure for `dashboardAPI`: the (intentionally shallow) three-tier layout, the command registry, the dashboard composition pipeline, the HTTP-endpoint event lifecycle, and the output-port pipeline. For an intuitive overview, return to [Home](Home).
+>
+> Pending full node review (2026-05). Content reflects `CONTRACT.md` and current source only.
+
+---
+
+## Three-tier code layout
+
+```
+nodes/dashboardAPI/
+|
++-- dashboardapi.js                entry: RED.nodes.registerType('dashboardapi', NodeClass)
+|                                  (legacy lowercase filename — see Limitations)
+|
++-- dashboardapi.html              editor: form + oneditprepare / oneditsave
+|                                  (legacy lowercase filename — see Limitations)
+|
++-- src/
+|     nodeClass.js                 passive adapter — buildConfig + createRegistry + input dispatch
+|                                  DOES NOT extend BaseNodeAdapter
+|     specificClass.js             DashboardApi service — loadTemplate / buildDashboard /
+|                                  generateDashboardsForGraph / extractChildren
+|                                  DOES NOT extend BaseDomain
+|     |
+|     +-- commands/
+|           index.js               topic descriptors (child.register only)
+|           handlers.js            resolveChildSource + registerChild handler
+|
++-- config/                        Grafana JSON templates, one per softwareType
+|     aeration.json                machineGroup.json    pumpingStation.json
+|     dashboardapi.json            measurement.json     reactor.json
+|     machine.json                 monster.json         settler.json
+|                                  valve.json           valveGroupControl.json
+|
++-- dependencies/
+|     dashboardapi/
+|       dashboardapiConfig.json    editor menu config (NOT runtime config)
+|
++-- examples/
+|     basic.flow.json              currently stubs — see Examples & Limitations
+|     integration.flow.json
+|     edge.flow.json
+|
++-- test/
+      basic/                       structure-module-load test
+      integration/                 structure-examples test
+      edge/                        structure-examples-node-type test
+      helpers/
+```
+
+### Tier responsibilities
+
+| Tier | File | What it owns | Touches `RED.*` |
+|:---|:---|:---|:---:|
+| entry | `dashboardapi.js` | `RED.nodes.registerType('dashboardapi', ...)`. Admin endpoints: `GET /dashboardapi/menu.js` (logger menu) + `GET /dashboardapi/configData.js` (editor metadata). | Yes |
+| nodeClass | `src/nodeClass.js` | Builds runtime config via `configManager.buildConfig`. Creates command registry via `createRegistry(commands)`. Attaches `input` and `close` handlers. **No tick loop, no status badge, no Port 1 / 2 emissions.** Sets a one-shot red `dashboardapi error` status on dispatch failure. | Yes |
+| specificClass | `src/specificClass.js` | Pure dashboard composition: template loading, UID derivation, templating-var fill, child graph walk, links generation, upsert request shaping. No `RED.*` calls. | No |
+
+`specificClass` is small (~210 lines) and self-contained — no concern modules. The complexity surface is too narrow to warrant a `concerns/` split.
+
+---
+
+## Why no BaseNodeAdapter / BaseDomain
+
+The decision is documented in `OPEN_QUESTIONS.md` (2026-05-10) and surfaced in `CONTRACT.md`. Four concrete blockers:
+
+1. **No platform config JSON.** `BaseDomain`'s constructor unconditionally calls `configManager.getConfig(ctor.name)` against `generalFunctions/src/configs/<n>.json`. There is no `dashboardapi.json` in `generalFunctions` &mdash; the local `dependencies/dashboardapi/dashboardapiConfig.json` is for the editor menu endpoint only. Adding a platform config JUST to satisfy the base class would be a synthetic decision.
+2. **No periodic output.** `BaseNodeAdapter._emitOutputs()` and `outputUtils.formatMsg` assume a delta-compressed Port 0 / 1 telemetry stream tied to a tick loop. dashboardAPI emits HTTP envelopes asynchronously on inbound events; the formatter pipeline would coerce these into the wrong shape.
+3. **No parent registration.** `BaseNodeAdapter._scheduleRegistration` automatically emits a `child.register` on Port 2 at startup. dashboardAPI is a **sink** for `child.register`, not a source &mdash; emitting one of its own would feed into other dashboardAPI instances and cause loops.
+4. **No status badge, no tick, no measurements, no children of its own.** Most of the base-class machinery would be inert or actively harmful.
+
+What dashboardAPI **does** reuse from `generalFunctions/`:
+
+- `configManager` (for `buildConfig`)
+- `createRegistry` + the canonical-topic / alias-with-deprecation pattern
+- `logger`
+- `MenuManager` (for the editor menu endpoint)
+
+That's enough common platform surface to keep the node aligned with EVOLV conventions without inheriting machinery it can't use.
+
+---
+
+## Command registry
+
+`src/commands/index.js` declares one descriptor:
+
+```js
+module.exports = [
+  {
+    topic: 'child.register',
+    aliases: ['registerChild'],
+    payloadSchema: { type: 'any' },
+    handler: handlers.registerChild,
+  },
+];
+```
+
+`createRegistry(commands, { logger })` returns a dispatcher with built-in alias-with-deprecation: the first time `msg.topic === 'registerChild'` fires, the logger emits a one-time deprecation warning; thereafter the alias is silently mapped to the canonical handler.
+
+### `child.register` handler &mdash; resolution pipeline
+
+`src/commands/handlers.js` `registerChild(source, msg, ctx)`:
+
+1. **Resolve the child source** via `resolveChildSource(msg.payload, ctx)`:
+   - If `payload.source.config` exists &rarr; use `payload.source` directly (inline shape A).
+   - Else if `payload.config` exists &rarr; wrap as `{ config: payload.config }` (inline shape B).
+   - Else if `typeof payload === 'string'` &rarr; treat as a node id and resolve via `RED.nodes.getNode(id)` &rarr; fall back to `ctx.node._flow.getNode(id)`.
+2. **Throw** `Missing or invalid child node` if neither path yields a `.config` &mdash; the nodeClass's catch sets the red `dashboardapi error` status badge and re-throws via `node.error`.
+3. **Walk the graph** via `source.generateDashboardsForGraph(childSource, {includeChildren: msg.includeChildren ?? true})`.
+4. **Emit one Port-0 envelope** per generated dashboard, with the `{...msg, topic: 'create', ...}` spread so caller fields propagate.
+
+---
+
+## Dashboard composition pipeline
+
+```mermaid
+flowchart TB
+    in[child.register payload]:::input --> res[resolveChildSource<br/>RED.nodes.getNode → _flow.getNode → inline]
+    res --> walk[generateDashboardsForGraph<br/>root + direct children if includeChildren]
+    walk --> bld[buildDashboard per node]
+    bld --> tpl[loadTemplate softwareType<br/>config/-st-.json with case-insensitive fallback<br/>+ machineGroupControl → machineGroup.json alias]
+    tpl --> uid[stableUid<br/>sha1 softwareType:nodeId .slice 0,12]
+    bld --> vars[updateTemplatingVar<br/>measurement = softwareType_nodeId<br/>bucket = position-based default or override]
+    walk --> links[Add root.links of child uid + slugify title]
+    links --> shape[buildUpsertRequest<br/>dashboard + folderId 0 + overwrite true]
+    shape --> emit[ctx.send one msg per dashboard<br/>topic 'create', url, method, headers, payload, meta]
+    emit --> out[Port 0]
+    classDef input fill:#dddddd,color:#000
+```
+
+### Template selection
+
+`_templateFileForSoftwareType(softwareType)` tries these candidates in order:
+
+1. `config/<softwareType>.json` (exact case)
+2. `config/<softwareType.toLowerCase()>.json` (case-insensitive fallback)
+3. `config/machineGroup.json` &mdash; only when `softwareType === 'machineGroupControl'` (one-off alias)
+
+A missing template logs at `warn` level (`No dashboard template found for softwareType=<st>`) and the matching dashboard is skipped (no error thrown, the rest of the graph walk continues).
+
+Currently shipped templates in `config/`:
+
+| Template | Maps to softwareType |
+|:---|:---|
+| `aeration.json` | aeration |
+| `dashboardapi.json` | dashboardapi (this node) |
+| `machine.json` | (likely `rotatingmachine` / `machine` &mdash; verify when reviewing) |
+| `machineGroup.json` | `machineGroupControl` (via alias) |
+| `measurement.json` | measurement |
+| `monster.json` | monster |
+| `pumpingStation.json` | pumpingStation |
+| `reactor.json` | reactor |
+| `settler.json` | settler |
+| `valve.json` | valve |
+| `valveGroupControl.json` | valveGroupControl |
+
+> [!NOTE]
+> The exact softwareType &harr; template mapping (esp. `machine.json` vs the lowercase `rotatingmachine` softwareType emitted by `rotatingMachine`'s `functionality.softwareType`) needs verification during the full review &mdash; flagged.
+
+### UID stability
+
+`stableUid(input) = sha1(input).slice(0, 12)` &mdash; the same `softwareType:nodeId` always yields the same dashboard UID. Combined with `overwrite: true` in the upsert payload, this makes the operation idempotent: re-deploying the EVOLV flow re-runs the upsert with the same UID and Grafana replaces the existing dashboard rather than creating a duplicate.
+
+### Position-based bucket fallback
+
+When `defaultBucket` is empty AND `bucketMap[position]` has no entry:
+
+| `positionVsParent` | Bucket used |
+|:---|:---|
+| `upstream` (case-insensitive) | `lvl1` |
+| `downstream` (case-insensitive) | `lvl3` |
+| any other / absent | `lvl2` |
+
+Overridden by (in order): `config.defaultBucket` &rarr; `config.bucketMap[position]` &rarr; the table above. `INFLUXDB_BUCKET` env is read in `_buildConfig` and lands in `config.defaultBucket`.
+
+### Root &rarr; child links
+
+When `includeChildren=true` and the root has &ge; 1 direct child, the root dashboard's `links[]` is augmented with one entry per child:
+
+```js
+{
+  type: 'link',
+  title: childTitle,
+  url: `/d/${childUid}/${slugify(childTitle)}`,
+  tags: [],
+  targetBlank: false,
+  keepTime: true,
+  keepVariables: true,
+}
+```
+
+`slugify` is lowercase-kebab-case, truncated to 60 chars. `keepTime` and `keepVariables` are Grafana's "preserve dashboard state across navigation" flags &mdash; clicking a link keeps the time range and templating selections.
+
+---
+
+## Lifecycle &mdash; what one event does
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant emitter as any EVOLV node
+    participant dash as dashboardAPI (nodeClass)
+    participant cr as commandRegistry
+    participant api as DashboardApi (specificClass)
+    participant out as Port 0
+    participant http as http request (downstream)
+    participant grafana as Grafana HTTP API
+
+    emitter->>dash: msg{topic: 'child.register', payload}
+    dash->>cr: dispatch(msg, source, ctx)
+    cr->>cr: canonicalise topic (alias→canonical, log deprecation once)
+    cr->>api: handlers.registerChild(source, msg, ctx)
+    api->>api: resolveChildSource(payload, ctx)
+    alt source missing
+        api-->>dash: throw 'Missing or invalid child node'
+        dash->>dash: node.status({fill:'red','dashboardapi error'})
+        dash->>dash: node.error(err, msg)
+    else source resolved
+        api->>api: generateDashboardsForGraph(childSource, {includeChildren})
+        api->>api: buildDashboard(root) → loadTemplate + stableUid + templating
+        api->>api: extractChildren → buildDashboard per child
+        api->>api: rootDash.links += child links
+        loop per dashboard in results
+            api->>out: ctx.send({...msg, topic:'create', url, method, headers, payload, meta})
+            out->>http: msg flows to downstream http request node
+            http->>grafana: POST /api/dashboards/db
+        end
+    end
+```
+
+One inbound event yields **N outbound HTTP envelopes**, where N = 1 (root) + count(direct children) when `includeChildren=true`, or 1 when `includeChildren=false`.
+
+There is no FSM. There is no tick loop. There is no `state.emitter`. The node is event-driven and stateless &mdash; every `child.register` is handled independently and discarded.
+
+---
+
+## Output ports
+
+| Port | Carries | Sample shape |
+|:---|:---|:---|
+| 0 (process) | One `topic: 'create'` HTTP envelope per generated dashboard | `{topic:'create', url, method:'POST', headers, payload:{dashboard,folderId:0,overwrite:true}, meta}` |
+| 1 (telemetry) | **Unused.** No measurements; nothing emitted. | &mdash; |
+| 2 (registration / control) | **Unused.** dashboardAPI is a sink for `child.register`, not a source. | &mdash; |
+
+Port 0 deliberately diverges from the standard "process data + delta-compressed" convention: the envelope is a fully-formed HTTP request, shaped for a downstream `http request` core node. Caller-supplied `msg.*` fields propagate via the `{...msg, ...envelope}` spread so correlation / trace fields survive the hop.
+
+> Per `.claude/rules/output-coverage.md`: this node has a small output surface (one Port-0 msg shape), and no tick / FSM states &mdash; the manifest is correspondingly small. The standard "every output, every state" sweep collapses to "every key in the envelope is present whenever a dashboard is generated; nothing is emitted when resolution fails."
+
+---
+
+## Event sources
+
+| Source | Where it fires | What it triggers |
+|:---|:---|:---|
+| Inbound `msg.topic` | Node-RED input wire on Port 0 input | `commandRegistry.dispatch` &rarr; `handlers.registerChild` |
+| Admin HTTP `GET /dashboardapi/menu.js` | Editor first-load | `MenuManager.createEndpoint('dashboardapi', ['logger'])` returns JS bootstrap |
+| Admin HTTP `GET /dashboardapi/configData.js` | Editor first-load | Reads `dependencies/dashboardapi/dashboardapiConfig.json` and returns it as a JS-attached global on `window.EVOLV.nodes.dashboardapi.config` |
+| `node.on('close')` | Node-RED redeploy / shutdown | No-op (handler exists but only calls `done()`) |
+
+There is no `setInterval`, no `state.emitter`, no `child.measurements.emitter`. The node sleeps until `child.register` arrives.
+
+---
+
+## Where to start reading
+
+| If you're changing... | Read first |
+|:---|:---|
+| Adding a new topic / changing the alias map | `src/commands/index.js` + `src/commands/handlers.js` |
+| Payload resolution rules (string id / inline source / inline config) | `src/commands/handlers.js` `resolveChildSource` + `resolveChildNode` |
+| Grafana URL composition / bearer token / headers | `src/specificClass.js` `grafanaUpsertUrl` + `handlers.registerChild` header logic |
+| Template selection, alias rules, missing-template behaviour | `src/specificClass.js` `_templateFileForSoftwareType` + `loadTemplate` |
+| UID derivation, dashboard composition, links | `src/specificClass.js` `buildDashboard` + `generateDashboardsForGraph` |
+| Bucket fallback (position &rarr; lvl1/lvl2/lvl3) | `src/specificClass.js` `defaultBucketForPosition` |
+| Editor form &harr; config keys | `dashboardapi.html` + `src/nodeClass.js` `_buildConfig` |
+| Editor menu / config endpoints | `dashboardapi.js` (entry, admin endpoints) + `dependencies/dashboardapi/dashboardapiConfig.json` |
+| Template content for a new EVOLV node type | `config/<softwareType>.json` &mdash; copy the closest existing one and adjust |
+
+---
+
+## Related pages
+
+| Page | Why |
+|:---|:---|
+| [Home](Home) | Intuitive overview |
+| [Reference &mdash; Contracts](Reference-Contracts) | Topic + config + template alias map |
+| [Reference &mdash; Examples](Reference-Examples) | Shipped flows + debug recipes |
+| [Reference &mdash; Limitations](Reference-Limitations) | Filename drift, stub flows, open questions |
+| [EVOLV &mdash; Architecture](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Architecture) | Platform-wide three-tier pattern |
+| [EVOLV &mdash; Telemetry](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Telemetry) | Port 0 / 1 / 2 InfluxDB layout (dashboardAPI is an exception &mdash; Port 0 carries HTTP envelopes) |

wiki/Reference-Contracts.md

@@ -0,0 +1,243 @@
+# Reference — Contracts
+
+![code-ref](https://img.shields.io/badge/code--ref-a6f09d8-blue)
+
+> [!NOTE]
+> Full topic contract, configuration schema, child-resolution rules, and Port-0 envelope spec for `dashboardAPI`. Source of truth: `src/commands/index.js`, `src/commands/handlers.js`, `src/specificClass.js`, `src/nodeClass.js`, and `dependencies/dashboardapi/dashboardapiConfig.json`.
+>
+> Pending full node review (2026-05). Content reflects `CONTRACT.md` and current source only.
+>
+> For an intuitive overview, return to [Home](Home).
+
+---
+
+## Topic contract
+
+The registry lives in `src/commands/index.js`. dashboardAPI has **one** canonical input topic.
+
+<!-- BEGIN AUTOGEN: topic-contract -->
+
+| Canonical topic | Aliases | Payload | Unit | Effect |
+|---|---|---|---|---|
+| `child.register` | `registerChild` | any | — | — |
+
+<!-- END AUTOGEN: topic-contract -->
+
+The `registerChild` alias logs a one-time deprecation warning on first use. There is **no HTTP endpoint contract** for dashboardAPI as a Node-RED node &mdash; it is an input-on-wire only. The outbound HTTP call shape is documented in [Port-0 envelope](#port-0-envelope-data-model) below.
+
+### Payload resolution rules
+
+| Payload shape | Resolved as | Source code |
+|:---|:---|:---|
+| `{source: {config: {...}}, ...}` | `payload.source` &mdash; use directly | `handlers.js` `resolveChildSource` line 6 |
+| `{config: {...}}` | `{config: payload.config}` &mdash; wrap minimally | `handlers.js` `resolveChildSource` line 7 |
+| `"<node-id>"` (bare string) | `RED.nodes.getNode(id).source` &rarr; fallback `node._flow.getNode(id).source` | `handlers.js` `resolveChildNode` |
+| anything else | `null` &rarr; throws `'Missing or invalid child node'` | `handlers.js` `registerChild` line 30 |
+
+`msg.includeChildren` (default `true`) controls graph-walk depth: `true` walks `extractChildren(rootSource)` and emits one dashboard per discovered child plus the root; `false` emits just the root dashboard.
+
+---
+
+## Data model &mdash; Port-0 envelope
+
+<!-- BEGIN AUTOGEN: data-model — populate via wiki-gen tool (TODO) -->
+
+dashboardAPI **has no domain output** &mdash; it does not extend `BaseDomain` and does not implement `getOutput()`. Port 0 carries one **HTTP request envelope** per generated dashboard, shaped for a downstream `http request` core node:
+
+```js
+{
+  topic: 'create',
+  url: 'http://<grafana-host>:<grafana-port>/api/dashboards/db',
+  method: 'POST',
+  headers: {
+    Accept: 'application/json',
+    'Content-Type': 'application/json',
+    Authorization: 'Bearer <token>'   // only when grafanaConnector.bearerToken is set
+  },
+  payload: {
+    dashboard: { uid: '<12-char-sha1>', title: '<node-name>', templating: {...}, ... },
+    folderId: 0,
+    overwrite: true
+  },
+  meta: {
+    nodeId: '<from config.general.id or .name>',
+    softwareType: '<from config.functionality.softwareType>',
+    uid: '<same 12-char-sha1>',
+    title: '<same node name>'
+  }
+}
+```
+
+Port 1 (InfluxDB telemetry) and Port 2 (registration / control plumbing) are **unused** &mdash; dashboardAPI has no measurements and does not register with a parent.
+
+<!-- END AUTOGEN: data-model -->
+
+### Envelope fields
+
+| Key | Type | Source | Notes |
+|:---|:---|:---|:---|
+| `topic` | string | constant `'create'` | Signals "Grafana dashboard upsert". |
+| `url` | string | `grafanaUpsertUrl()` | `${protocol}://${host}:${port}/api/dashboards/db`. |
+| `method` | string | constant `'POST'` | &mdash; |
+| `headers.Accept` | string | constant | `application/json` |
+| `headers.Content-Type` | string | constant | `application/json` |
+| `headers.Authorization` | string &#124; absent | `Bearer ${bearerToken}` | **Omitted entirely** when `bearerToken` is empty. |
+| `payload.dashboard` | object | `buildUpsertRequest({dashboard, folderId, overwrite}).dashboard` | The composed Grafana dashboard JSON. |
+| `payload.folderId` | integer | constant `0` | Root folder. Not configurable. |
+| `payload.overwrite` | boolean | constant `true` | Required for idempotent re-deploys. |
+| `meta.nodeId` | string | `config.general.id` or `config.general.name` or `softwareType` | Correlation id. |
+| `meta.softwareType` | string | `config.functionality.softwareType` (case-insensitive lookup) | Used for template selection. |
+| `meta.uid` | string | `sha1(softwareType:nodeId).slice(0, 12)` | Stable across re-deploys &mdash; same `(softwareType, nodeId)` &rarr; same UID. |
+| `meta.title` | string | `config.general.name` or `nodeId` | Human-readable dashboard title. |
+
+**`msg` propagation:** inbound `msg.*` fields are merged via `{...msg, topic:'create', ...}` spread &mdash; caller-supplied correlation / trace fields (e.g. `msg._msgid`, `msg.requestId`) survive the hop.
+
+### Dashboard composition
+
+For each generated dashboard, `buildDashboard({nodeConfig, positionVsParent})` performs:
+
+1. **Template load** &mdash; `loadTemplate(softwareType)` from `config/<softwareType>.json` (case-insensitive fallback, `machineGroupControl &rarr; machineGroup.json` alias). Missing template &rarr; logs `warn` and returns `null` (the dashboard is skipped from the output).
+2. **UID stamp** &mdash; `dashboard.uid = stableUid(softwareType:nodeId)`.
+3. **Title stamp** &mdash; `dashboard.title = config.general.name || nodeId`.
+4. **Tags merge** &mdash; existing `template.tags` + `['EVOLV', softwareType, positionVsParent]` (deduplicated, empty values filtered).
+5. **Templating var fill** &mdash; `dashboard.templating.list[]` entries named `measurement` and `bucket` are mutated in place:
+   - `measurement` &larr; `${softwareType}_${nodeId}` (used as InfluxDB measurement name in panel queries).
+   - `bucket` &larr; resolved bucket (see [Bucket resolution](#bucket-resolution) below).
+6. **Links append** (root dashboard only, when `includeChildren=true` and `children.length > 0`) &mdash; one `{type:'link', title, url:'/d/<uid>/<slug>', keepTime, keepVariables}` entry per direct child.
+
+If `dashboard.templating.list` is not an array or the named variable doesn't exist, the templating step is a no-op (no error).
+
+### Bucket resolution
+
+`bucket` (the InfluxDB bucket templating var) is resolved in priority order:
+
+| Priority | Source | When applied |
+|:---:|:---|:---|
+| 1 | `config.defaultBucket` (editor field or `INFLUXDB_BUCKET` env) | When set to a non-empty string |
+| 2 | `config.bucketMap[positionVsParent]` | When the position has an entry |
+| 3 | `defaultBucketForPosition(positionVsParent)` | Falls through &mdash; `upstream &rarr; lvl1`, `downstream &rarr; lvl3`, else `lvl2` |
+
+> [!NOTE]
+> Priorities 1 and 2 read order from `specificClass.js` `buildDashboard`. Verify against the editor's intended semantics during full review &mdash; "global override beats per-position map" is the current behaviour. Flagged.
+
+---
+
+## Configuration schema &mdash; editor form to config keys
+
+Source of truth: `dependencies/dashboardapi/dashboardapiConfig.json` + `src/nodeClass.js` `_buildConfig`. The runtime config slice is built by `configManager.buildConfig(name, uiConfig, nodeId, overrides)`.
+
+### General (`config.general`)
+
+| Form field | Config key | Default | Notes |
+|:---|:---|:---|:---|
+| Name | `general.name` | `'dashboardapi'` | Display label; falls through to nodeId in `meta.title`. |
+| (auto-assigned) | `general.id` | `null` | Node-RED node id. |
+| Enable logging | `general.logging.enabled` | `false` (per `_buildConfig`) / `true` (per `dashboardapiConfig.json`) | **Mismatch** &mdash; see [Limitations](Reference-Limitations#config-default-mismatch). |
+| Log level | `general.logging.logLevel` | `'info'` | `debug` / `info` / `warn` / `error`. |
+
+### Functionality (`config.functionality`)
+
+| Form field | Config key | Default | Notes |
+|:---|:---|:---|:---|
+| (hidden) | `functionality.softwareType` | `'dashboardapi'` | Constant. Set in `_buildConfig` from `this.name.toLowerCase()`. |
+| (hidden) | `functionality.role` | `'auto ui generator'` | Constant. |
+
+### Grafana connector (`config.grafanaConnector`)
+
+| Form field | Config key | Default | Range / values | Where used |
+|:---|:---|:---|:---|:---|
+| Protocol | `grafanaConnector.protocol` | `'http'` | `http` / `https` | `grafanaUpsertUrl()` |
+| Grafana Host | `grafanaConnector.host` | `'localhost'` | hostname / IP | `grafanaUpsertUrl()` |
+| Grafana Port | `grafanaConnector.port` | `3000` | 1&ndash;65535 (`Number(uiConfig.port \|\| 3000)`) | `grafanaUpsertUrl()` |
+| Bearer Token | `grafanaConnector.bearerToken` | `''` | string (Grafana service-account token) | `Authorization: Bearer ...` header; omitted when empty |
+
+### Bucket configuration
+
+| Form field | Config key | Default | Notes |
+|:---|:---|:---|:---|
+| InfluxDB Bucket | `defaultBucket` | `''` &rarr; falls back to `process.env.INFLUXDB_BUCKET` &rarr; position default | Set in `_buildConfig`; consumed by `buildDashboard` templating fill. |
+| (no editor field) | `bucketMap` | `{}` | Programmatic only &mdash; pass via `uiConfig.bucketMap` or future editor field. |
+
+### Editor menu / logger fields
+
+The `dashboardapi.html` template invokes `window.EVOLV.nodes.dashboardapi.loggerMenu.initEditor / saveEditor` via the shared `MenuManager`-served `/dashboardapi/menu.js` endpoint. The logger fields (`enableLog`, `logLevel`) are persisted on the node via the standard EVOLV editor menu pattern.
+
+> [!WARNING]
+> **Editor `defaults` use legacy field names.** `dashboardapi.html` declares `{enableLog, logLevel}` as Node-RED defaults but the runtime config reads `general.logging.{enabled, logLevel}`. The bridge is the shared logger menu (`MenuManager`) &mdash; confirm during full review that the editor menu correctly maps `enableLog` &rarr; `general.logging.enabled`.
+
+---
+
+## Template alias map
+
+`_templateFileForSoftwareType(softwareType)` lookup order:
+
+| Order | Candidate filename | Notes |
+|:---:|:---|:---|
+| 1 | `<softwareType>.json` | Exact case. |
+| 2 | `<softwareType.toLowerCase()>.json` | Case-insensitive fallback. |
+| 3 | `machineGroup.json` | **Only** when `softwareType === 'machineGroupControl'` (one-off alias). |
+
+If none of the candidates exist in `config/`, the logger emits `No dashboard template found for softwareType=<st>` at `warn` level and `loadTemplate` returns `null`. `buildDashboard` then logs `Skipping dashboard generation: no template for softwareType=<st>` and returns `null`; `generateDashboardsForGraph` skips that node and continues with the rest of the graph walk.
+
+Currently shipped templates:
+
+| softwareType (canonical) | Template file | Notes |
+|:---|:---|:---|
+| `aeration` | `aeration.json` | &mdash; |
+| `dashboardapi` | `dashboardapi.json` | Self-template (when a dashboardAPI registers as a child of another dashboardAPI &mdash; unusual). |
+| `machine` (or `rotatingmachine`) | `machine.json` | softwareType to verify in full review &mdash; flagged. |
+| `machineGroupControl` | `machineGroup.json` | Via one-off alias. |
+| `measurement` | `measurement.json` | &mdash; |
+| `monster` | `monster.json` | &mdash; |
+| `pumpingStation` | `pumpingStation.json` | &mdash; |
+| `reactor` | `reactor.json` | &mdash; |
+| `settler` | `settler.json` | &mdash; |
+| `valve` | `valve.json` | &mdash; |
+| `valveGroupControl` | `valveGroupControl.json` | &mdash; |
+
+Adding support for a new EVOLV node type = drop a `config/<newType>.json` file matching the `softwareType` lowercase name (or add an alias arm to `_templateFileForSoftwareType`).
+
+---
+
+## Child resolution (NOT a registry)
+
+dashboardAPI does **not** maintain a child registry of its own. There is no `_registeredChildren` map, no `child.register` &rarr; `child.unregister` lifecycle, no parent &rarr; child emitter wiring. Every inbound `child.register` is a **one-shot** dashboard generation:
+
+```mermaid
+flowchart LR
+    src["any EVOLV node<br/>(has functionality.softwareType)"]:::other -->|child.register| dash[dashboardAPI<br/>Utility]:::neutral
+    dash --> resolve["resolveChildSource(payload, ctx)<br/>RED.nodes.getNode → _flow.getNode → inline"]
+    resolve --> walk["generateDashboardsForGraph(childSource, {includeChildren})"]
+    walk --> emit["emit one msg per dashboard<br/>topic='create'"]
+    emit --> http[(downstream<br/>http request node)]
+    classDef neutral fill:#dddddd,color:#000
+    classDef other fill:#ffffff,stroke:#666
+```
+
+### What graph walk reads from the child source
+
+`extractChildren(rootSource)` reads `rootSource.childRegistrationUtils.registeredChildren` (a Map). For each `entry`:
+
+- `entry.child` &mdash; the child source object (must have `.config`).
+- `entry.position` (or `child.positionVsParent`) &mdash; used for the bucket fallback and tag composition.
+
+Children without a `.config` are silently skipped. If `rootSource.childRegistrationUtils` is absent or `registeredChildren.values` is not a function, the result is an empty array &mdash; just the root dashboard is emitted.
+
+| Inbound softwareType | Filter | Side effect |
+|:---|:---|:---|
+| any | child has `functionality.softwareType` AND the matching `config/*.json` exists | Loads template; emits one upsert msg per dashboard in the walk. |
+| any | child has `functionality.softwareType` but the template is missing | Warns and skips that node's dashboard. No error thrown. Graph walk continues. |
+| absent / malformed | `resolveChildSource` returns null | Throws `Missing or invalid child node` &rarr; nodeClass sets red status, calls `node.error`. |
+
+---
+
+## Related pages
+
+| Page | Why |
+|:---|:---|
+| [Home](Home) | Intuitive overview |
+| [Reference &mdash; Architecture](Reference-Architecture) | Code map, lifecycle, graph walk |
+| [Reference &mdash; Examples](Reference-Examples) | Shipped flows + debug recipes |
+| [Reference &mdash; Limitations](Reference-Limitations) | Filename drift, stub flows, open questions |
+| [EVOLV &mdash; Topic Conventions](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Topic-Conventions) | Platform-wide topic rules |
+| [EVOLV &mdash; Telemetry](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Telemetry) | Port 0 / 1 / 2 layout (dashboardAPI is an exception &mdash; Port 0 carries HTTP envelopes) |

wiki/Reference-Examples.md

@@ -0,0 +1,171 @@
+# Reference — Examples
+
+![code-ref](https://img.shields.io/badge/code--ref-a6f09d8-blue)
+
+> [!NOTE]
+> Every example flow shipped under `nodes/dashboardAPI/examples/`, plus how to load them, what they show, and the debug recipes that go with them. Live source: `nodes/dashboardAPI/examples/`.
+>
+> Pending full node review (2026-05). The shipped example flows are **stubs** — they wire up the node but the inject payloads do not yet match the `child.register` resolver's expected shape. Working wiring patterns are documented inline below.
+
+---
+
+## Shipped examples
+
+| File | Tier | Dependencies | What it shows | Status |
+|:---|:---:|:---|:---|:---|
+| `basic.flow.json` | 1 | EVOLV only | Inject a `ping` topic into a stand-alone dashboardAPI node + debug tap on Port 0. | ⏳ **Stub** — inject topic is `ping`, not `child.register`; the registry will silently drop the msg. |
+| `integration.flow.json` | 2 | EVOLV only | Inject a `registerChild` alias topic with a bare-string node id (`'example-child-id'`) + debug tap. | ⏳ **Stub** — the bare-string id resolves to `null` via `RED.nodes.getNode`; throws `'Missing or invalid child node'`. |
+| `edge.flow.json` | 3 | EVOLV only | Inject an unknown topic to confirm the dispatcher silently drops it. | ✓ Works as a registry-coverage probe. |
+
+All three are tracked for replacement in the next wiki-cleanup pass — see [Limitations — Example flow stubs](Reference-Limitations#example-flow-stubs).
+
+---
+
+## 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/dashboardAPI/examples/basic.flow.json \
+  http://localhost:1880/flows
+```
+
+---
+
+## Working wiring patterns
+
+These are the shapes that actually exercise the resolver. Use them as the basis for any new example flow until the stubs above are replaced.
+
+### Wiring pattern A — inline `source` payload (no real EVOLV node needed)
+
+```json
+[
+  {
+    "type": "inject",
+    "topic": "child.register",
+    "props": [
+      {"p": "topic", "vt": "str"},
+      {"p": "payload", "v": "{\"source\":{\"config\":{\"functionality\":{\"softwareType\":\"measurement\"},\"general\":{\"id\":\"pump-a-flow\",\"name\":\"Pump A flow\"}}}}", "vt": "json"}
+    ]
+  },
+  { "type": "dashboardapi" },
+  { "type": "http request", "method": "POST" },
+  { "type": "debug", "complete": "true" }
+]
+```
+
+What happens:
+
+1. The inject fires a msg with `topic: 'child.register'` and `payload.source.config.functionality.softwareType = 'measurement'`.
+2. `resolveChildSource` matches the `payload.source.config` branch and returns `payload.source` directly.
+3. `loadTemplate('measurement')` reads `config/measurement.json`.
+4. `stableUid('measurement:pump-a-flow')` → deterministic 12-char hex.
+5. The Port-0 envelope flows to the debug node AND to the `http request` node which POSTs to Grafana.
+
+### Wiring pattern B — bare `config` payload
+
+Same as pattern A but with the outer `source` wrapper dropped:
+
+```json
+"payload": "{\"config\":{\"functionality\":{\"softwareType\":\"pumpingStation\"},\"general\":{\"id\":\"ps_demo\",\"name\":\"Pumping Station Demo\"}}}"
+```
+
+`resolveChildSource` falls through to the `payload.config` branch and wraps as `{config: payload.config}`. No `childRegistrationUtils` is present, so the graph walk emits only the root dashboard (no children even if `includeChildren=true`).
+
+### Wiring pattern C — real EVOLV node via Port 2
+
+The canonical production wiring: any EVOLV node's Port 2 (`registerChild` emission) wired into dashboardAPI's input.
+
+```text
+[rotatingMachine] Port 2 ──► [dashboardAPI] Port 0 ──► [http request] ──► Grafana
+                                                          │
+                                                          └─► [debug]
+```
+
+The emitting node's `child.register` payload is the bare node id (a string). `resolveChildNode` then runs `RED.nodes.getNode(id)` to fetch the live runtime node and reads `node.source.config`. Walks `node.source.childRegistrationUtils.registeredChildren` so direct children also get dashboards.
+
+> [!IMPORTANT]
+> **Example needed.** A Tier-2 example that wires a real `rotatingMachine` or `pumpingStation` Port 2 to dashboardAPI input is the missing canonical demo. Save as `nodes/dashboardAPI/examples/02-Integration-with-EVOLV-node.json`. Track in `IMPROVEMENTS_BACKLOG.md`.
+
+---
+
+## Docker compose snippet
+
+To bring up Node-RED + Grafana (+ optional InfluxDB) for end-to-end testing:
+
+```yaml
+services:
+  nodered:
+    build: ./docker/nodered
+    ports: ['1880:1880']
+    volumes:
+      - ./docker/nodered/data:/data/evolv
+    environment:
+      INFLUXDB_BUCKET: lvl2
+  grafana:
+    image: grafana/grafana:11.0.0
+    ports: ['3000:3000']
+    environment:
+      GF_SECURITY_ADMIN_PASSWORD: admin
+  influxdb:
+    image: influxdb:2.7
+    ports: ['8086:8086']
+```
+
+A Grafana service account token (created via Grafana UI → Administration → Service accounts) goes into the dashboardAPI's Bearer Token editor field.
+
+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 |
+|:---|:---|:---|
+| No HTTP message emitted on Port 0; node shows red `dashboardapi error` status | `resolveChildSource` returned `null`. Check payload shape against [Payload resolution rules](Reference-Contracts#payload-resolution-rules). The most common cause: bare-string id that doesn't match a live Node-RED node. | `src/commands/handlers.js` `resolveChildSource` + `resolveChildNode`. |
+| Dispatch silently drops msg (no error, no output) | Topic is not `child.register` and not the `registerChild` alias. The registry's catch-all is "no match → ignore". | `src/commands/index.js` + `createRegistry` source in `generalFunctions/`. |
+| `Skipping dashboard generation: no template for softwareType=<st>` warn | `config/<softwareType>.json` (or its lowercase variant or alias) doesn't exist. | `config/` directory &mdash; add a template JSON, or fix the emitting node's `functionality.softwareType`. |
+| `machineGroupControl` produces no dashboard | The alias maps to `machineGroup.json` &mdash; verify that file exists in `config/`. | `_templateFileForSoftwareType` in `src/specificClass.js`. |
+| Empty `Authorization` header | `bearerToken` not set in editor form &mdash; the header is omitted entirely when the token is empty, not set to `'Bearer '`. | Editor &rarr; Bearer Token field. |
+| Wrong InfluxDB bucket in Grafana template variables | `defaultBucket` config (or `INFLUXDB_BUCKET` env) overrides the position-based default. Priority order: `defaultBucket` &rarr; `bucketMap[position]` &rarr; `defaultBucketForPosition`. | `_buildConfig` in `nodeClass.js` + `defaultBucketForPosition` in `specificClass.js`. |
+| Dashboard UID changes between deploys | Node id or `softwareType` changed &mdash; UID is `sha1(softwareType:nodeId).slice(0, 12)`. Stable only if both are stable. | `stableUid` in `specificClass.js`. |
+| `registerChild` alias warns once | Expected &mdash; deprecation warning on first use only. Migrate caller to `child.register`. | Caller `msg.topic`. |
+| Grafana 404 on `POST /api/dashboards/db` | Wrong path = check Grafana version. The `/api/dashboards/db` endpoint exists in Grafana 7&ndash;11. For newer Grafana with org-scoped endpoints, the upsert URL may differ. | `grafanaUpsertUrl` in `specificClass.js`. |
+| Grafana 401 / 403 | Bearer token missing, expired, or insufficient permissions. The service account needs at least `Editor` role on the target folder. | Grafana UI &rarr; Administration &rarr; Service accounts. |
+| Root dashboard has no `links[]` to children | `includeChildren=false` was passed, OR the root source's `childRegistrationUtils.registeredChildren` is empty / absent. | `generateDashboardsForGraph` + `extractChildren`. |
+| Editor form shows blank fields after re-open | `oneditprepare` waits for `window.EVOLV.nodes.dashboardapi.loggerMenu` which is loaded by `/dashboardapi/menu.js`. If the menu endpoint 500s, the editor stays blank. | Browser devtools &rarr; Network &rarr; `menu.js`; check the entry file's logger menu endpoint. |
+
+> Never ship `enableLog: 'debug'` in a demo &mdash; fills the container log within seconds and obscures real errors. Use only for live debugging sessions.
+
+---
+
+## Quick smoke test (no Grafana required)
+
+To verify the node loads and the registry dispatches correctly without standing up Grafana:
+
+1. Import `examples/basic.flow.json` (or any of the stubs).
+2. Edit the inject node: set topic to `child.register` and payload to a JSON object matching wiring pattern A above.
+3. Deploy.
+4. Fire the inject. The debug pane should show a `topic: 'create'` envelope with a populated `payload.dashboard`.
+5. If `headers.Authorization` is absent, the editor's Bearer Token field is empty &mdash; that's correct behaviour.
+
+The downstream `http request` node is **optional** for the smoke test &mdash; the dashboardAPI emits regardless of whether anything POSTs the envelope to Grafana.
+
+---
+
+## Related pages
+
+| Page | Why |
+|:---|:---|
+| [Home](Home) | Intuitive overview |
+| [Reference &mdash; Contracts](Reference-Contracts) | Topic + payload resolution + envelope shape |
+| [Reference &mdash; Architecture](Reference-Architecture) | Code map, lifecycle, graph walk |
+| [Reference &mdash; Limitations](Reference-Limitations) | Stub flows, filename drift, open questions |
+| [EVOLV &mdash; Topology Patterns](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Topology-Patterns) | Where dashboardAPI fits in a larger plant |

wiki/Reference-Limitations.md

@@ -0,0 +1,156 @@
+# Reference — Limitations
+
+![code-ref](https://img.shields.io/badge/code--ref-a6f09d8-blue)
+
+> [!NOTE]
+> What `dashboardAPI` does not do, current rough edges, and open questions. Open items live in `.agents/improvements/IMPROVEMENTS_BACKLOG.md` and `.claude/refactor/OPEN_QUESTIONS.md` in the superproject.
+>
+> Pending full node review (2026-05). Content reflects `CONTRACT.md` and current source only.
+
+---
+
+## When you would not use this node
+
+| Scenario | Use instead |
+|:---|:---|
+| You maintain Grafana dashboards by hand | Skip dashboardAPI — it will overwrite your customisations on every `child.register` (upsert is `overwrite: true`). |
+| You need arbitrary Grafana API calls (annotations, alerts, data sources, folders) | A plain `http request` node. dashboardAPI only emits `POST /api/dashboards/db` envelopes. |
+| You want to forward tick / measurement data to Grafana | This is not what dashboardAPI does. Wire telemetry through Port 1 of an EVOLV process node directly into InfluxDB; Grafana queries InfluxDB. |
+| You want to use dashboardAPI as a BaseDomain-capable child of something else | Not supported — dashboardAPI does not extend `BaseDomain` and cannot register as a child of `machineGroupControl` / `pumpingStation` / similar. See [No BaseNodeAdapter / BaseDomain](#no-basenodeadapter--basedomain) below. |
+| You expect EVOLV nodes to auto-discover dashboardAPI | They don't. Port 2 of the emitter must be wired into dashboardAPI's input explicitly. |
+
+---
+
+## Known limitations
+
+### Legacy filename drift
+
+The entry file and editor HTML are currently lowercase — `dashboardapi.js` and `dashboardapi.html` — rather than `dashboardAPI.js` / `dashboardAPI.html` per the canonical folder-name convention in `.claude/rules/node-architecture.md`.
+
+The convention rule explicitly calls this out as legacy drift to fix when the file is next touched. A rename is a four-touch change:
+
+1. `dashboardapi.js` → `dashboardAPI.js`
+2. `dashboardapi.html` → `dashboardAPI.html`
+3. `package.json#node-red.nodes` — key remains `dashboardapi` (the Node-RED type id is independent of the filename) but the value becomes `dashboardAPI.js`.
+4. Superproject submodule references and any `require()` paths.
+
+The Node-RED **type id** (`dashboardapi`, lowercase, registered via `RED.nodes.registerType('dashboardapi', …)`) must stay `dashboardapi` to avoid breaking existing flows in the wild. The rename is purely the source-file path. Tracked.
+
+### Example flow stubs
+
+The three shipped flows (`basic.flow.json`, `integration.flow.json`, `edge.flow.json`) are placeholders. Their inject nodes don't fire a payload that matches the `child.register` resolver:
+
+| File | Current behaviour | What's wrong |
+|:---|:---|:---|
+| `basic.flow.json` | Inject `topic: 'ping'` | Not `child.register`; registry silently drops. |
+| `integration.flow.json` | Inject `topic: 'registerChild'` with `payload: 'example-child-id'` (string) | The string id has no live Node-RED node behind it; `RED.nodes.getNode('example-child-id')` returns null; throws `'Missing or invalid child node'`. |
+| `edge.flow.json` | Inject `topic: 'doesNotExist'` | Works as a registry-coverage probe (silent drop is correct) but exercises nothing. |
+
+Working wiring patterns are documented inline in [Reference — Examples](Reference-Examples#working-wiring-patterns). Replacement of the stubs is tracked in `IMPROVEMENTS_BACKLOG.md` (P9 wiki cleanup follow-up).
+
+### No BaseNodeAdapter / BaseDomain
+
+Most EVOLV nodes inherit a common adapter / domain base class. dashboardAPI does not. The decision is recorded in `OPEN_QUESTIONS.md` (2026-05-10) — four blockers (no platform config JSON, no periodic output, no parent registration, no status badge / tick / measurements). Until `BaseNodeAdapter` grows passive-mode flags (skip-registration + skip-output-stream), the bespoke adapter shape is the correct compromise.
+
+Consequence: dashboardAPI cannot be introspected via the standard `getOutput()` channel. Debugging relies on watching Port 0 in a debug node.
+
+### No domain output / no manifest
+
+Per `.claude/rules/output-coverage.md`, every node should ship a `test/_output-manifest.md` enumerating every Port-0/1/2 key in populated and degraded states. dashboardAPI's output surface is **one envelope shape**, emitted only when a dashboard is successfully generated — there is no degraded "partial envelope" state to test. The manifest collapses to:
+
+| Port | Output | Populated state | Degraded state |
+|:---|:---|:---|:---|
+| 0 | `{topic, url, method, headers, payload, meta}` envelope | Emitted once per generated dashboard | **Not emitted** — on resolution failure the handler throws and nodeClass sets a red status badge instead |
+| 1 | (unused) | — | — |
+| 2 | (unused) | — | — |
+
+The full output-coverage rule applies prospectively; no backfill manifest exists yet. Tracked.
+
+### Template discovery is filename-based
+
+The template lookup is `softwareType` ↔ filename. Renaming a node's `softwareType` (e.g. `rotatingmachine` → `rotatingMachine`) requires either renaming the template file or adding an alias arm in `_templateFileForSoftwareType`. The `machineGroupControl → machineGroup.json` mapping is a one-off alias because the historical filename was abbreviated.
+
+> [!NOTE]
+> Verify in full review: which softwareType does the current `rotatingMachine` emit? The shipped template is `config/machine.json` — if `rotatingMachine`'s `functionality.softwareType` is `'rotatingmachine'` (lowercase), the case-insensitive fallback won't find it and dashboard generation will warn-and-skip. Flagged.
+
+### No retry / circuit-breaker on downstream HTTP
+
+dashboardAPI emits the upsert envelope and is done. If the downstream `http request` node fails (Grafana down, 5xx, network timeout), the dashboard upsert is silently dropped — no retry, no DLQ, no status badge propagation back to dashboardAPI. The caller is responsible for wiring retry logic into the http-request path.
+
+### `oneditsave` doesn't read all editor fields uniformly
+
+`dashboardapi.html` `oneditsave` reads `['name', 'protocol', 'host', 'port', 'bearerToken', 'defaultBucket']` via direct DOM lookups, separately from the logger menu's `saveEditor`. Adding a new editor field requires touching both the form HTML and the `oneditsave` whitelist. Mild; not load-bearing.
+
+### Config default mismatch
+
+The runtime `_buildConfig` defaults `general.logging.enabled` to `Boolean(config?.general?.logging?.enabled)` — effectively `false` when the editor doesn't set it. But `dependencies/dashboardapi/dashboardapiConfig.json` declares the default as `true`. The editor menu (`loggerMenu`) bridges these via the standard EVOLV logger pattern, but the divergence is worth confirming — logger enabled vs disabled changes whether `Skipping dashboard generation: no template …` warns appear at all.
+
+> [!NOTE]
+> Confirm in full review which side wins by default for a freshly-dropped node. Flagged.
+
+### `bucket` resolution priority is global-then-per-position
+
+`buildDashboard` reads `this.config.defaultBucket || this.config.bucketMap[position] || defaultBucketForPosition(position)`. The global override fires **before** the per-position map. If you want per-position buckets to win over a global default, the current code doesn't do that — you'd need to leave `defaultBucket` empty and rely solely on `bucketMap` + the position fallback.
+
+Open question whether the "global beats per-position" priority is the intended semantics. Flagged.
+
+### No InfluxDB bucket validation
+
+The bucket name is templated into the Grafana dashboard JSON without any check that the bucket exists in InfluxDB. A typo produces a dashboard that renders panels saying "no data" with no upstream warning. Tracked.
+
+---
+
+## Open questions (tracked)
+
+| Question | Where it lives |
+|:---|:---|
+| Should `BaseNodeAdapter` grow a passive / HTTP-only mode (skip-registration + skip-output-stream) so dashboardAPI can extend it? | `.claude/refactor/OPEN_QUESTIONS.md` (2026-05-10) — "dashboardAPI skipped BaseNodeAdapter + BaseDomain" |
+| Confirm `rotatingMachine` softwareType ↔ `config/machine.json` mapping | Internal — flag during full review |
+| Bucket priority: should per-position `bucketMap` beat global `defaultBucket`? | Internal |
+| Should dashboardAPI emit a Port-2 status / health pulse so other EVOLV nodes can detect it? | Internal |
+| Should `child.register` aliases include older topic names (e.g. `RegisterChild`, `register-child`) for legacy compat? | Internal |
+| Add an explicit `child.unregister` / `dashboard.delete` topic to remove orphaned Grafana dashboards | Internal |
+| Provide a programmatic way to bulk-regenerate all dashboards for an existing deployment (e.g. `cmd.regenerate-all`) | Internal |
+| Retry / DLQ for failed Grafana upserts | TBD |
+
+---
+
+## Migration notes
+
+### From the `registerChild` alias
+
+The canonical topic since 2026-Q1 is `child.register`. The `registerChild` alias still works but logs a one-time deprecation warning on first use. Migrate callers when convenient:
+
+```diff
+- msg.topic = 'registerChild';
++ msg.topic = 'child.register';
+```
+
+Both topics accept identical payloads.
+
+### From bare-string node-id payloads
+
+The handler resolves bare-string payloads via `RED.nodes.getNode(id) → node._flow.getNode(id) → null`. This works at runtime but is brittle for tests and for flows where the emitter and dashboardAPI live on different `_flow` instances. Prefer the inline `{source: {config: {...}}}` or `{config: {...}}` shapes for tests and for any flow that imports both sides as JSON (no `RED.nodes` registry at compile time).
+
+### From hand-curated Grafana dashboards
+
+If you're moving from hand-curated dashboards to dashboardAPI-generated ones:
+
+1. Export your existing dashboard JSON from Grafana.
+2. Replace the templating-var values for `measurement` and `bucket` with placeholders.
+3. Save as `nodes/dashboardAPI/config/<softwareType>.json`.
+4. The next `child.register` for that softwareType will upsert (overwrite) the existing dashboard, preserving the UID if you set it to match `stableUid(softwareType:nodeId)`.
+
+If you want to **preserve the UID** of an existing hand-curated dashboard, compute `sha1(softwareType:nodeId).slice(0, 12)` and check it matches your existing UID. If not, either rename the node id, or accept that the first upsert will create a new dashboard alongside the old one.
+
+---
+
+## Related pages
+
+| Page | Why |
+|:---|:---|
+| [Home](Home) | Intuitive overview |
+| [Reference &mdash; Contracts](Reference-Contracts) | Topic + payload resolution + envelope shape |
+| [Reference &mdash; Architecture](Reference-Architecture) | Code map, lifecycle, "no BaseNodeAdapter" rationale |
+| [Reference &mdash; Examples](Reference-Examples) | Shipped flows + debug recipes + working wiring patterns |
+| [EVOLV &mdash; Open Questions](https://gitea.wbd-rd.nl/RnD/EVOLV/src/branch/development/.claude/refactor/OPEN_QUESTIONS.md) | Cross-node open questions and decisions log |

wiki/_Sidebar.md

@@ -0,0 +1,20 @@
+### dashboardAPI
+
+- [Home](Home)
+
+**Reference**
+
+- [Contracts](Reference-Contracts)
+- [Architecture](Reference-Architecture)
+- [Examples](Reference-Examples)
+- [Limitations](Reference-Limitations)
+
+**Related**
+
+- [EVOLV master wiki](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Home)
+- [rotatingMachine wiki](https://gitea.wbd-rd.nl/RnD/rotatingMachine/wiki/Home)
+- [pumpingStation wiki](https://gitea.wbd-rd.nl/RnD/pumpingStation/wiki/Home)
+- [machineGroupControl wiki](https://gitea.wbd-rd.nl/RnD/machineGroupControl/wiki/Home)
+- [Topology Patterns](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Topology-Patterns)
+- [Topic Conventions](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Topic-Conventions)
+- [Telemetry](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Telemetry)

wiki/_partial-datamodel.md.template

@@ -0,0 +1,18 @@
+No domain output. dashboardAPI emits **HTTP request envelopes on Port 0**, shaped for a downstream `http request` node:
+
+```js
+{
+  topic: 'create',
+  url: 'http://<grafana>:<port>/api/dashboards/db',
+  method: 'POST',
+  headers: {
+    Accept: 'application/json',
+    'Content-Type': 'application/json',
+    Authorization: 'Bearer …'   // only when bearerToken is set
+  },
+  payload: { dashboard: {…}, folderId: 0, overwrite: true },
+  meta: { nodeId, softwareType, uid, title }
+}
+```
+
+Port 1 (InfluxDB telemetry) and Port 2 (registration / control plumbing) are unused — dashboardAPI has no measurements and does not register with a parent.