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/findings/bep-gravitation-proof.md

@@ -0,0 +1,38 @@
+---
+title: BEP-Gravitation Optimality Proof
+created: 2026-04-07
+updated: 2026-04-07
+status: proven
+tags: [machineGroupControl, optimization, BEP, brute-force]
+sources: [nodes/machineGroupControl/test/integration/distribution-power-table.integration.test.js]
+---
+
+# BEP-Gravitation vs Brute-Force Global Optimum
+
+## Claim
+The machineGroupControl BEP-Gravitation algorithm (with marginal-cost refinement) produces near-optimal flow distribution across a pump group.
+
+## Method
+Brute-force exhaustive search: 1000 steps per pump, all 2^n combinations, 0.05% flow tolerance. Station: 2x H05K-S03R + 1x C5-D03R-SHN1 @ ΔP=2000 mbar.
+
+## Results
+
+| Demand | Brute force | machineGroupControl | Gap |
+|--------|------------|--------------------|----|
+| 10% (71 m3/h) | 17.65 kW | 17.63 kW | -0.10% (MGC wins) |
+| 25% (136 m3/h) | 34.33 kW | 34.33 kW | +0.01% |
+| 50% (243 m3/h) | 61.62 kW | 61.62 kW | -0.00% |
+| 75% (351 m3/h) | 96.01 kW | 96.10 kW | +0.08% |
+| 90% (415 m3/h) | 122.17 kW | 122.26 kW | +0.07% |
+
+Maximum deviation: **0.1%** from proven global optimum.
+
+## Why the Refinement Matters
+
+Before the marginal-cost refinement loop, the gap at 50% demand was **2.12%**. The BEP-Gravitation slope estimate pushed 14.6 m3/h to C5 (costing 5.0 kW) when the optimum was 6.5 m3/h (0.59 kW). The refinement loop corrects this by shifting flow from highest actual dP/dQ to lowest until no improvement is possible.
+
+## Stability
+Sweep 5-95% in 2% steps: 1 switch (rising), 1 switch (falling), same transition point. No hysteresis. See [[Pump Switching Stability]].
+
+## Computational Cost
+0.027-0.153ms median per optimization call (3 pumps, 6 combinations). Uses 0.015% of the 1000ms tick budget.

wiki/findings/curve-non-convexity.md

@@ -0,0 +1,34 @@
+---
+title: Pump Curve Non-Convexity
+created: 2026-04-07
+updated: 2026-04-07
+status: proven
+tags: [curves, interpolation, C5, non-convex]
+sources: [nodes/generalFunctions/datasets/assetData/curves/hidrostal-C5-D03R-SHN1.json]
+---
+
+# Pump Curve Non-Convexity from Sparse Data
+
+## Finding
+The C5-D03R-SHN1 pump's power curve is non-convex after spline interpolation. The marginal cost (dP/dQ) shows a spike-then-valley pattern:
+
+```
+C5 dP/dQ across flow range @ ΔP=2000 mbar:
+  6.4 m3/h → 1,316,610  (high)
+ 10.2 m3/h → 2,199,349  (spikes UP)
+ 17.7 m3/h → 1,114,700  (dropping)
+ 21.5 m3/h →   453,316  (valley — cheapest)
+ 29.0 m3/h → 1,048,375  (rising again)
+ 44.1 m3/h → 1,107,708  (high)
+```
+
+## Root Cause
+The C5 curve has only **5 raw data points** per pressure level. The monotonic cubic spline (Fritsch-Carlson) creates a smooth curve through all 5 points, but with such sparse data it introduces non-convex regions that don't match the physical convexity of a real pump.
+
+## Impact
+- The equal-marginal-cost theorem (KKT conditions) does not apply — it requires convexity
+- The BEP-Gravitation slope estimate at a single point can be misleading in non-convex regions
+- The marginal-cost refinement loop fixes this by using actual power evaluations instead of slope assumptions
+
+## Recommendation
+Add more data points (15-20 per pressure level) to the C5 curve. This would make the spline track the real convex physics more closely, eliminating the non-convex artifacts.

wiki/findings/ncog-behavior.md

@@ -0,0 +1,42 @@
+---
+title: NCog Behavior and Limitations
+created: 2026-04-07
+updated: 2026-04-07
+status: evolving
+tags: [rotatingMachine, NCog, BEP, efficiency]
+sources: [nodes/rotatingMachine/src/specificClass.js]
+---
+
+# NCog — Normalized Center of Gravity
+
+## What It Is
+NCog is a 0-1 value indicating where on its flow range a pump operates most efficiently. Computed per tick from the current pressure slice of the 3D pump curve.
+
+```
+BEP_flow = minFlow + (maxFlow - minFlow) * NCog
+```
+
+## How It's Computed
+1. Pressure sensors update → `getMeasuredPressure()` computes differential
+2. `fDimension` locks the 2D slice at current system pressure
+3. `calcCog()` computes Q/P (specific flow) across the curve
+4. Peak Q/P index → `NCog = (flowAtPeak - flowMin) / (flowMax - flowMin)`
+
+## When NCog is Meaningful
+NCog requires **differential pressure** (upstream + downstream). With only one pressure sensor, fDimension is the raw sensor value (too high), producing a monotonic Q/P curve and NCog = 0.
+
+| Condition | NCog for H05K | NCog for C5 |
+|-----------|--------------|-------------|
+| ΔP = 400 mbar | 0.333 | 0.355 |
+| ΔP = 1000 mbar | 0.000 | 0.000 |
+| ΔP = 1500 mbar | 0.135 | 0.000 |
+| ΔP = 2000 mbar | 0.351 | 0.000 |
+
+## Why NCog = 0 Happens
+For variable-speed centrifugal pumps, Q/P is monotonically decreasing when the affinity laws dominate (P ∝ Q³). At certain pressure levels, the spline interpolation preserves this monotonicity and the peak is always at index 0 (minimum flow).
+
+## How the machineGroupControl Uses NCog
+The BEP-Gravitation algorithm seeds each pump at its BEP flow, then redistributes using slope-based weights + marginal-cost refinement. Even when NCog = 0, the slope redistribution produces near-optimal results because it uses actual power evaluations.
+
+> [!warning] Disproven: NCog as proportional weight
+> Using NCog directly as a flow-distribution weight (`flow = NCog/totalNCog * Qd`) is wrong. It starves pumps with NCog = 0 and overloads high-NCog pumps. See `calcBestCombination` in machineGroupControl.

wiki/findings/pump-switching-stability.md

@@ -0,0 +1,34 @@
+---
+title: Pump Switching Stability
+created: 2026-04-07
+updated: 2026-04-07
+status: proven
+tags: [machineGroupControl, stability, switching]
+sources: [nodes/machineGroupControl/test/integration/ncog-distribution.integration.test.js]
+---
+
+# Pump Switching Stability
+
+## Concern
+Frequent pump on/off cycling causes mechanical wear, water hammer, and process disturbance.
+
+## Test Method
+Sweep demand from 5% to 95% in 2% steps, count combination changes. Repeat in reverse to check for hysteresis.
+
+## Results — Mixed Station (2x H05K + 1x C5)
+
+Rising 5→95%: **1 switch** at 27% (H05K-1+C5 → all 3)
+Falling 95→5%: **1 switch** at 25% (all 3 → H05K-1+C5)
+
+Same transition zone, no hysteresis.
+
+## Results — Equal Station (3x H05K)
+
+Rising 5→95%: **2 switches**
+- 19%: 1 pump → 2 pumps
+- 37%: 2 pumps → 3 pumps
+
+Clean monotonic transitions, no flickering.
+
+## Why It's Stable
+The marginal-cost refinement only adjusts flow distribution WITHIN a combination — it never changes which pumps are selected. Combination selection is driven by total power comparison, which changes smoothly with demand.