docs: initialize project wiki from production hardening session

12 pages covering architecture, findings, and metrics from the
rotatingMachine + machineGroupControl hardening work:

- Overview: node inventory, what works/doesn't, current scale
- Architecture: 3D pump curves, group optimization algorithm
- Findings: BEP-Gravitation proof (0.1% of optimum), NCog behavior,
  curve non-convexity, pump switching stability
- Metrics: test counts, power comparison table, performance numbers
- Knowledge graph: structured YAML with all data points and provenance
- Session log: 2026-04-07 production hardening
- Tools: query.py, search.sh, lint.sh

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

wiki/architecture/3d-pump-curves.md

@@ -0,0 +1,56 @@
+---
+title: 3D Pump Curve Architecture
+created: 2026-04-07
+updated: 2026-04-07
+status: proven
+tags: [predict, curves, interpolation, rotatingMachine]
+sources: [nodes/generalFunctions/src/predict/predict_class.js, nodes/rotatingMachine/src/specificClass.js]
+---
+
+# 3D Pump Curve Prediction
+
+## Data Structure
+A family of 2D curves indexed by pressure (f-dimension):
+- **X-axis**: control position (0-100%)
+- **Y-axis**: flow (nq) or power (np) in canonical units
+- **F-dimension**: pressure (Pa) — the 3rd dimension
+
+Raw curves are in curve units (m3/h, kW, mbar). `_normalizeMachineCurve()` converts to canonical (m3/s, W, Pa).
+
+## Interpolation
+Monotonic cubic spline (Fritsch-Carlson) in both dimensions:
+- **X-Y splines**: at each discrete pressure level
+- **F-splines**: across pressure levels for intermediate pressure interpolation
+
+## Prediction Flow
+```
+predict.y(x):
+  1. Clamp x to [currentFxyXMin, currentFxyXMax]
+  2. Normalize x to [normMin, normMax]
+  3. Evaluate spline at normalized x for current fDimension
+  4. Return y in canonical units (m3/s or W)
+```
+
+## Unit Conversion Chain
+```
+Raw curve (m3/h, kW, mbar)
+  → _normalizeMachineCurve → canonical (m3/s, W, Pa)
+  → predict class → canonical output
+  → MeasurementContainer.getCurrentValue(outputUnit) → output units
+```
+
+No double-conversion. Clean separation: specificClass handles units, predict handles normalization/interpolation.
+
+## Three Predict Instances per Machine
+- `predictFlow`: control % → flow (nq curve)
+- `predictPower`: control % → power (np curve)
+- `predictCtrl`: flow → control % (reversed nq curve)
+
+## Boundary Behavior
+- Below/above curve X range: flat extrapolation (clamped)
+- Below/above f-dimension range: clamped to min/max pressure level
+
+## Performance
+- `y(x)`: O(log n), effectively O(1) for 5-10 data points
+- `buildAllFxyCurves`: sub-10ms for typical curves
+- Full caching of normalized curves, splines, and calculated curves

wiki/architecture/group-optimization.md

@@ -0,0 +1,45 @@
+---
+title: Group Optimization Architecture
+created: 2026-04-07
+updated: 2026-04-07
+status: proven
+tags: [machineGroupControl, optimization, BEP-Gravitation]
+sources: [nodes/machineGroupControl/src/specificClass.js]
+---
+
+# machineGroupControl Optimization
+
+## Algorithm: BEP-Gravitation + Marginal-Cost Refinement
+
+### Step 1 — Pressure Equalization
+Sets all non-operational pumps to the group's max downstream / min upstream pressure. Ensures fair curve evaluation across combinations.
+
+### Step 2 — Combination Enumeration
+Generates all 2^n pump subsets (n = number of machines). Filters by:
+- Machine state (excludes off, cooling, stopping, emergency)
+- Mode compatibility (`execsequence` allowed in auto)
+- Flow bounds: `sumMinFlow ≤ Qd ≤ sumMaxFlow`
+- Optional power cap
+
+### Step 3 — BEP-Gravitation Distribution (per combination)
+1. **BEP seed**: `estimatedBEP = minFlow + span * NCog` per pump
+2. **Slope estimation**: samples dP/dQ at BEP ± delta (directional: slopeLeft, slopeRight)
+3. **Slope redistribution**: iteratively shifts flow from steep to flat curves (weight = 1/slope)
+4. **Marginal-cost refinement**: after slope redistribution, shifts flow from highest actual dP/dQ to lowest using real `inputFlowCalcPower` evaluations. Converges regardless of curve convexity. Max 50 iterations, typically 5-15.
+
+### Step 4 — Best Selection
+Pick combination with lowest total power. Tiebreak by deviation from BEP.
+
+### Step 5 — Execution
+Start/stop pumps as needed, send `flowmovement` commands in output units via `_canonicalToOutputFlow()`.
+
+## Three Control Modes
+
+| Mode | Distribution | Combination Selection |
+|------|-------------|----------------------|
+| optimalControl | BEP-Gravitation + refinement | exhaustive 2^n |
+| priorityControl | equal split, priority-ordered | sequential add/remove |
+| priorityPercentageControl | percentage-based, normalized | count-based |
+
+## Key Design Decision
+The `flowmovement` command sends flow in the **machine's output units** (m3/h), not canonical (m3/s). The `_canonicalToOutputFlow()` helper converts before sending. Without this conversion, every pump stays at minimum flow (the critical bug fixed on 2026-04-07).