From 63b5f946e2bf508d98c6813cba3e6537f7f20fa2 Mon Sep 17 00:00:00 2001
From: znetsixe <zn375ix3@gmail.com>
Date: Mon, 11 May 2026 17:41:10 +0200
Subject: [PATCH] P11.5 + B2.1/B2.2: per-command units + description (where
 applicable)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds  to scalar setters whose payloads are
plain numbers OR {value, unit}. Skipped where payload is compound or
mode-dependent (control-%, {F, C: [...]}, etc.) — documented inline.
Every command gains a description field for wikiGen consumption.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/commands/index.js | 73 +++++++++++++++++++++++++++++++++++++------
 1 file changed, 64 insertions(+), 9 deletions(-)

diff --git a/src/commands/index.js b/src/commands/index.js
index c8d5ea1..602b22a 100644
--- a/src/commands/index.js
+++ b/src/commands/index.js
@@ -7,14 +7,69 @@
 const handlers = require('./handlers');
 
 module.exports = [
-  { topic: 'set.mode', aliases: ['setMode'], payloadSchema: { type: 'string' }, handler: handlers.setMode },
-  { topic: 'cmd.startup', payloadSchema: { type: 'any' }, handler: handlers.startup },
-  { topic: 'cmd.shutdown', payloadSchema: { type: 'any' }, handler: handlers.shutdown },
-  { topic: 'cmd.estop', aliases: ['emergencystop', 'emergencyStop'], payloadSchema: { type: 'any' }, handler: handlers.estop },
+  {
+    topic: 'set.mode',
+    aliases: ['setMode'],
+    payloadSchema: { type: 'string' },
+    description: 'Switch the valve between auto / manual control modes.',
+    handler: handlers.setMode,
+  },
+  {
+    topic: 'cmd.startup',
+    payloadSchema: { type: 'any' },
+    description: 'Initiate the valve startup sequence.',
+    handler: handlers.startup,
+  },
+  {
+    topic: 'cmd.shutdown',
+    payloadSchema: { type: 'any' },
+    description: 'Initiate the valve shutdown sequence.',
+    handler: handlers.shutdown,
+  },
+  {
+    topic: 'cmd.estop',
+    aliases: ['emergencystop', 'emergencyStop'],
+    payloadSchema: { type: 'any' },
+    description: 'Trigger an emergency stop on the valve.',
+    handler: handlers.estop,
+  },
   // Content-based demux; behaviour matches cmd.startup/cmd.shutdown exactly.
-  { topic: 'execSequence', payloadSchema: { type: 'object' }, handler: handlers.execSequenceAlias, _legacy: true },
-  { topic: 'set.position', aliases: ['execMovement'], payloadSchema: { type: 'object' }, handler: handlers.setPosition },
-  { topic: 'data.flow', aliases: ['updateFlow'], payloadSchema: { type: 'object' }, handler: handlers.dataFlow },
-  { topic: 'query.curve', aliases: ['showcurve'], payloadSchema: { type: 'any' }, handler: handlers.queryCurve },
-  { topic: 'child.register', aliases: ['registerChild'], payloadSchema: { type: 'string' }, handler: handlers.registerChild },
+  {
+    topic: 'execSequence',
+    payloadSchema: { type: 'object' },
+    description: 'Legacy umbrella that demuxes payload.action to startup / shutdown / estop.',
+    handler: handlers.execSequenceAlias,
+    _legacy: true,
+  },
+  {
+    topic: 'set.position',
+    aliases: ['execMovement'],
+    payloadSchema: { type: 'object' },
+    // Control-percent position — no units field (no `percent` measure in convert).
+    description: 'Move the valve to a control-% position via execMovement.',
+    handler: handlers.setPosition,
+  },
+  {
+    topic: 'data.flow',
+    aliases: ['updateFlow'],
+    payloadSchema: { type: 'object' },
+    // Compound payload `{variant, value, position, unit}` — handler converts
+    // internally via unitPolicy; registry normalisation is skipped.
+    description: 'Push a measured flow into the valve (variant + position + unit).',
+    handler: handlers.dataFlow,
+  },
+  {
+    topic: 'query.curve',
+    aliases: ['showcurve'],
+    payloadSchema: { type: 'any' },
+    description: 'Return the valve characteristic curve on the reply port.',
+    handler: handlers.queryCurve,
+  },
+  {
+    topic: 'child.register',
+    aliases: ['registerChild'],
+    payloadSchema: { type: 'string' },
+    description: 'Register a child measurement with this valve.',
+    handler: handlers.registerChild,
+  },
 ];