From 61e0688f737d3ca90e837953f949951d780c62ca Mon Sep 17 00:00:00 2001
From: znetsixe <zn375ix3@gmail.com>
Date: Wed, 22 Apr 2026 13:00:16 +0200
Subject: [PATCH] Make starter SVG diagrams round-trippable in draw.io
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Each <name>.drawio.svg now has the corresponding <name>.drawio XML
embedded as content="..." on the root <svg> element. Opening the
SVG in draw.io (File → Open, or drag-drop) loads the full editable
model — no need to keep the .drawio file around for editing.

Updated diagrams/README.md to reflect that both file formats are
now round-trippable from the start.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 wiki/diagrams/README.md                |   4 +-
 wiki/diagrams/basin-model.drawio.svg   | 110 ++++++++++++++++++++++++-
 wiki/diagrams/control-zones.drawio.svg | 103 ++++++++++++++++++++++-
 wiki/diagrams/safety-rules.drawio.svg  |  59 ++++++++++++-
 4 files changed, 272 insertions(+), 4 deletions(-)

diff --git a/wiki/diagrams/README.md b/wiki/diagrams/README.md
index 92f4d66..34f7841 100644
--- a/wiki/diagrams/README.md
+++ b/wiki/diagrams/README.md
@@ -66,4 +66,6 @@ Use a descriptive `alt` text; it's the fallback if the SVG fails and it shows up
 
 ## These starters are rough
 
-The `.drawio` files committed here by Claude are **placeholders** — layout is approximate, colors and fonts are defaults, no fine alignment. They compile to a valid SVG you can see rendered on the page, but they're meant to be a starting point. Open them in draw.io, refine the layout, re-export.
+The `.drawio` files and their matching `.drawio.svg` exports committed here are **placeholders** — layout is approximate, colors and fonts are defaults, no fine alignment. They're meant to be a starting point; open them in draw.io and refine.
+
+Both formats are round-trippable: open either the `.drawio` or the `.drawio.svg` in draw.io and it will load the editable model. (The SVG has the drawio XML embedded in a `content="…"` attribute on the root `<svg>` element — that's what lets draw.io re-open its own SVG exports.)
diff --git a/wiki/diagrams/basin-model.drawio.svg b/wiki/diagrams/basin-model.drawio.svg
index ab0dd8f..b21784b 100644
--- a/wiki/diagrams/basin-model.drawio.svg
+++ b/wiki/diagrams/basin-model.drawio.svg
@@ -1,5 +1,113 @@
 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 850 660" font-family="Arial, sans-serif" font-size="13">
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 850 660" font-family="Arial, sans-serif" font-size="13" content="&lt;mxfile host=&quot;app.diagrams.net&quot; modified=&quot;2026-04-22T12:00:00.000Z&quot; agent=&quot;Claude Code placeholder&quot; etag=&quot;initial&quot; version=&quot;22.0.0&quot; type=&quot;device&quot;&gt;
+  &lt;diagram name=&quot;basin-model&quot; id=&quot;basinModel&quot;&gt;
+    &lt;mxGraphModel dx=&quot;1200&quot; dy=&quot;900&quot; grid=&quot;1&quot; gridSize=&quot;10&quot; guides=&quot;1&quot; tooltips=&quot;1&quot; connect=&quot;1&quot; arrows=&quot;1&quot; fold=&quot;1&quot; page=&quot;1&quot; pageScale=&quot;1&quot; pageWidth=&quot;850&quot; pageHeight=&quot;900&quot; math=&quot;0&quot; shadow=&quot;0&quot;&gt;
+      &lt;root&gt;
+        &lt;mxCell id=&quot;0&quot; /&gt;
+        &lt;mxCell id=&quot;1&quot; parent=&quot;0&quot; /&gt;
+        &lt;mxCell id=&quot;title&quot; value=&quot;Basin model — physical layout + control thresholds&quot; style=&quot;text;html=1;fontSize=16;fontStyle=1;align=center;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;200&quot; y=&quot;20&quot; width=&quot;500&quot; height=&quot;30&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;tank&quot; value=&quot;&quot; style=&quot;rounded=0;whiteSpace=wrap;html=1;fillColor=#E6F2FF;strokeColor=#000000;strokeWidth=2;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;300&quot; y=&quot;80&quot; width=&quot;260&quot; height=&quot;520&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;deadvol&quot; value=&quot;&quot; style=&quot;rounded=0;whiteSpace=wrap;html=1;fillColor=#9FC5E8;strokeColor=none;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;302&quot; y=&quot;550&quot; width=&quot;256&quot; height=&quot;48&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;freeboard_label&quot; value=&quot;freeboard&quot; style=&quot;text;html=1;fontSize=11;fontStyle=2;align=center;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;310&quot; y=&quot;90&quot; width=&quot;240&quot; height=&quot;20&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;overflow_line&quot; value=&quot;&quot; style=&quot;endArrow=none;html=1;strokeColor=#B22222;dashed=1;strokeWidth=2;&quot; edge=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry relative=&quot;1&quot; as=&quot;geometry&quot;&gt;
+            &lt;mxPoint x=&quot;250&quot; y=&quot;145&quot; as=&quot;sourcePoint&quot; /&gt;
+            &lt;mxPoint x=&quot;620&quot; y=&quot;145&quot; as=&quot;targetPoint&quot; /&gt;
+          &lt;/mxGeometry&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;overflow_label_l&quot; value=&quot;heightOverflow&quot; style=&quot;text;html=1;fontSize=12;align=right;fontColor=#B22222;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;140&quot; y=&quot;130&quot; width=&quot;100&quot; height=&quot;20&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;overflow_label_r&quot; value=&quot;spill → measure&quot; style=&quot;text;html=1;fontSize=12;align=left;fontColor=#B22222;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;630&quot; y=&quot;130&quot; width=&quot;140&quot; height=&quot;20&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;maxflow_line&quot; value=&quot;&quot; style=&quot;endArrow=none;html=1;strokeColor=#D68910;dashed=1;strokeWidth=2;&quot; edge=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry relative=&quot;1&quot; as=&quot;geometry&quot;&gt;
+            &lt;mxPoint x=&quot;250&quot; y=&quot;200&quot; as=&quot;sourcePoint&quot; /&gt;
+            &lt;mxPoint x=&quot;620&quot; y=&quot;200&quot; as=&quot;targetPoint&quot; /&gt;
+          &lt;/mxGeometry&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;maxflow_label_l&quot; value=&quot;maxFlowLevel&quot; style=&quot;text;html=1;fontSize=12;align=right;fontColor=#D68910;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;140&quot; y=&quot;185&quot; width=&quot;100&quot; height=&quot;20&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;scaling_label&quot; value=&quot;SCALING RANGE&amp;#10;(levelbased: demand ramps 0→100%)&quot; style=&quot;text;html=1;fontSize=11;fontStyle=2;align=center;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;310&quot; y=&quot;255&quot; width=&quot;240&quot; height=&quot;40&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;startlevel_line&quot; value=&quot;&quot; style=&quot;endArrow=none;html=1;strokeColor=#1E8449;dashed=1;strokeWidth=2;&quot; edge=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry relative=&quot;1&quot; as=&quot;geometry&quot;&gt;
+            &lt;mxPoint x=&quot;250&quot; y=&quot;345&quot; as=&quot;sourcePoint&quot; /&gt;
+            &lt;mxPoint x=&quot;620&quot; y=&quot;345&quot; as=&quot;targetPoint&quot; /&gt;
+          &lt;/mxGeometry&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;startlevel_label_l&quot; value=&quot;startLevel&quot; style=&quot;text;html=1;fontSize=12;align=right;fontColor=#1E8449;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;140&quot; y=&quot;330&quot; width=&quot;100&quot; height=&quot;20&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;deadzone_label&quot; value=&quot;DEAD ZONE&amp;#10;(hysteresis — keep last cmd)&quot; style=&quot;text;html=1;fontSize=11;fontStyle=2;align=center;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;310&quot; y=&quot;360&quot; width=&quot;240&quot; height=&quot;40&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;inflow_arrow&quot; value=&quot;&quot; style=&quot;endArrow=classic;html=1;strokeColor=#1F4E79;strokeWidth=3;&quot; edge=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry relative=&quot;1&quot; as=&quot;geometry&quot;&gt;
+            &lt;mxPoint x=&quot;150&quot; y=&quot;410&quot; as=&quot;sourcePoint&quot; /&gt;
+            &lt;mxPoint x=&quot;300&quot; y=&quot;410&quot; as=&quot;targetPoint&quot; /&gt;
+          &lt;/mxGeometry&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;inflow_label&quot; value=&quot;INFLOW&quot; style=&quot;text;html=1;fontSize=13;fontStyle=1;align=left;fontColor=#1F4E79;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;90&quot; y=&quot;395&quot; width=&quot;70&quot; height=&quot;20&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;inlet_label&quot; value=&quot;heightInlet&quot; style=&quot;text;html=1;fontSize=12;align=left;fontColor=#1F4E79;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;570&quot; y=&quot;400&quot; width=&quot;90&quot; height=&quot;20&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;stoplevel_line&quot; value=&quot;&quot; style=&quot;endArrow=none;html=1;strokeColor=#6C3483;dashed=1;strokeWidth=2;&quot; edge=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry relative=&quot;1&quot; as=&quot;geometry&quot;&gt;
+            &lt;mxPoint x=&quot;250&quot; y=&quot;465&quot; as=&quot;sourcePoint&quot; /&gt;
+            &lt;mxPoint x=&quot;620&quot; y=&quot;465&quot; as=&quot;targetPoint&quot; /&gt;
+          &lt;/mxGeometry&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;stoplevel_label_l&quot; value=&quot;stopLevel&quot; style=&quot;text;html=1;fontSize=12;align=right;fontColor=#6C3483;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;140&quot; y=&quot;450&quot; width=&quot;100&quot; height=&quot;20&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;stoplevel_label_r&quot; value=&quot;unconditional STOP&quot; style=&quot;text;html=1;fontSize=12;align=left;fontColor=#6C3483;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;630&quot; y=&quot;450&quot; width=&quot;160&quot; height=&quot;20&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;buffer_label&quot; value=&quot;BUFFER&quot; style=&quot;text;html=1;fontSize=11;fontStyle=2;align=center;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;310&quot; y=&quot;490&quot; width=&quot;240&quot; height=&quot;20&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;outflow_arrow&quot; value=&quot;&quot; style=&quot;endArrow=classic;html=1;strokeColor=#1F4E79;strokeWidth=3;&quot; edge=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry relative=&quot;1&quot; as=&quot;geometry&quot;&gt;
+            &lt;mxPoint x=&quot;560&quot; y=&quot;540&quot; as=&quot;sourcePoint&quot; /&gt;
+            &lt;mxPoint x=&quot;720&quot; y=&quot;540&quot; as=&quot;targetPoint&quot; /&gt;
+          &lt;/mxGeometry&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;outflow_label&quot; value=&quot;OUTFLOW&quot; style=&quot;text;html=1;fontSize=13;fontStyle=1;align=left;fontColor=#1F4E79;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;730&quot; y=&quot;525&quot; width=&quot;80&quot; height=&quot;20&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;outlet_label_l&quot; value=&quot;heightOutlet&quot; style=&quot;text;html=1;fontSize=12;align=right;fontColor=#B22222;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;140&quot; y=&quot;525&quot; width=&quot;100&quot; height=&quot;20&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;outlet_label_r&quot; value=&quot;dry-run trip&quot; style=&quot;text;html=1;fontSize=12;align=left;fontColor=#B22222;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;730&quot; y=&quot;550&quot; width=&quot;120&quot; height=&quot;20&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;deadvol_label&quot; value=&quot;dead volume&quot; style=&quot;text;html=1;fontSize=11;fontStyle=2;align=center;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;310&quot; y=&quot;560&quot; width=&quot;240&quot; height=&quot;20&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;floor_label&quot; value=&quot;floor (0)&quot; style=&quot;text;html=1;fontSize=11;align=right;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;190&quot; y=&quot;590&quot; width=&quot;50&quot; height=&quot;20&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;basin_label&quot; value=&quot;heightBasin&quot; style=&quot;text;html=1;fontSize=11;align=right;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;180&quot; y=&quot;70&quot; width=&quot;60&quot; height=&quot;20&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+      &lt;/root&gt;
+    &lt;/mxGraphModel&gt;
+  &lt;/diagram&gt;
+&lt;/mxfile&gt;">
   <title>Basin model — physical layout + control thresholds</title>
   <defs>
     <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse">
diff --git a/wiki/diagrams/control-zones.drawio.svg b/wiki/diagrams/control-zones.drawio.svg
index 4016861..2ffdfb0 100644
--- a/wiki/diagrams/control-zones.drawio.svg
+++ b/wiki/diagrams/control-zones.drawio.svg
@@ -1,5 +1,106 @@
 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 700 660" font-family="Arial, sans-serif" font-size="13">
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 700 660" font-family="Arial, sans-serif" font-size="13" content="&lt;mxfile host=&quot;app.diagrams.net&quot; modified=&quot;2026-04-22T12:00:00.000Z&quot; agent=&quot;Claude Code placeholder&quot; etag=&quot;initial&quot; version=&quot;22.0.0&quot; type=&quot;device&quot;&gt;
+  &lt;diagram name=&quot;control-zones&quot; id=&quot;controlZones&quot;&gt;
+    &lt;mxGraphModel dx=&quot;1000&quot; dy=&quot;800&quot; grid=&quot;1&quot; gridSize=&quot;10&quot; guides=&quot;1&quot; tooltips=&quot;1&quot; connect=&quot;1&quot; arrows=&quot;1&quot; fold=&quot;1&quot; page=&quot;1&quot; pageScale=&quot;1&quot; pageWidth=&quot;700&quot; pageHeight=&quot;800&quot; math=&quot;0&quot; shadow=&quot;0&quot;&gt;
+      &lt;root&gt;
+        &lt;mxCell id=&quot;0&quot; /&gt;
+        &lt;mxCell id=&quot;1&quot; parent=&quot;0&quot; /&gt;
+        &lt;mxCell id=&quot;title&quot; value=&quot;levelbased mode — three zones&quot; style=&quot;text;html=1;fontSize=16;fontStyle=1;align=center;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;100&quot; y=&quot;20&quot; width=&quot;500&quot; height=&quot;30&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;axis&quot; value=&quot;&quot; style=&quot;endArrow=classic;html=1;strokeColor=#000;strokeWidth=2;&quot; edge=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry relative=&quot;1&quot; as=&quot;geometry&quot;&gt;
+            &lt;mxPoint x=&quot;280&quot; y=&quot;600&quot; as=&quot;sourcePoint&quot; /&gt;
+            &lt;mxPoint x=&quot;280&quot; y=&quot;80&quot; as=&quot;targetPoint&quot; /&gt;
+          &lt;/mxGeometry&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;axis_label&quot; value=&quot;level&quot; style=&quot;text;html=1;fontSize=13;fontStyle=1;align=left;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;240&quot; y=&quot;60&quot; width=&quot;50&quot; height=&quot;20&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+
+        &lt;mxCell id=&quot;overflow&quot; value=&quot;heightOverflow — weir crest (spill → measure)&quot; style=&quot;text;html=1;fontSize=12;align=left;fontColor=#B22222;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;300&quot; y=&quot;130&quot; width=&quot;380&quot; height=&quot;20&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;overflow_tick&quot; value=&quot;&quot; style=&quot;endArrow=none;html=1;strokeColor=#B22222;&quot; edge=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry relative=&quot;1&quot; as=&quot;geometry&quot;&gt;
+            &lt;mxPoint x=&quot;270&quot; y=&quot;140&quot; as=&quot;sourcePoint&quot; /&gt;
+            &lt;mxPoint x=&quot;290&quot; y=&quot;140&quot; as=&quot;targetPoint&quot; /&gt;
+          &lt;/mxGeometry&gt;
+        &lt;/mxCell&gt;
+
+        &lt;mxCell id=&quot;run_band&quot; value=&quot;RUN  — linear 0 → 100 %&quot; style=&quot;rounded=0;whiteSpace=wrap;html=1;fillColor=#E8F5E9;strokeColor=#1E8449;fontSize=12;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;300&quot; y=&quot;160&quot; width=&quot;220&quot; height=&quot;110&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+
+        &lt;mxCell id=&quot;maxflow&quot; value=&quot;maxFlowLevel — 100 % demand&quot; style=&quot;text;html=1;fontSize=12;align=left;fontColor=#D68910;fontStyle=1;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;300&quot; y=&quot;265&quot; width=&quot;300&quot; height=&quot;20&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;maxflow_tick&quot; value=&quot;&quot; style=&quot;endArrow=none;html=1;strokeColor=#D68910;strokeWidth=2;&quot; edge=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry relative=&quot;1&quot; as=&quot;geometry&quot;&gt;
+            &lt;mxPoint x=&quot;265&quot; y=&quot;275&quot; as=&quot;sourcePoint&quot; /&gt;
+            &lt;mxPoint x=&quot;295&quot; y=&quot;275&quot; as=&quot;targetPoint&quot; /&gt;
+          &lt;/mxGeometry&gt;
+        &lt;/mxCell&gt;
+
+        &lt;mxCell id=&quot;ramp_label&quot; value=&quot;(ramp — demand scales linearly with level)&quot; style=&quot;text;html=1;fontSize=11;align=left;fontStyle=2;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;300&quot; y=&quot;300&quot; width=&quot;320&quot; height=&quot;20&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+
+        &lt;mxCell id=&quot;startlevel&quot; value=&quot;startLevel — 0 % demand (ramp starts)&quot; style=&quot;text;html=1;fontSize=12;align=left;fontColor=#1E8449;fontStyle=1;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;300&quot; y=&quot;335&quot; width=&quot;340&quot; height=&quot;20&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;start_tick&quot; value=&quot;&quot; style=&quot;endArrow=none;html=1;strokeColor=#1E8449;strokeWidth=2;&quot; edge=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry relative=&quot;1&quot; as=&quot;geometry&quot;&gt;
+            &lt;mxPoint x=&quot;265&quot; y=&quot;345&quot; as=&quot;sourcePoint&quot; /&gt;
+            &lt;mxPoint x=&quot;295&quot; y=&quot;345&quot; as=&quot;targetPoint&quot; /&gt;
+          &lt;/mxGeometry&gt;
+        &lt;/mxCell&gt;
+
+        &lt;mxCell id=&quot;dead_band&quot; value=&quot;DEAD ZONE — hysteresis, keep last cmd&quot; style=&quot;rounded=0;whiteSpace=wrap;html=1;fillColor=#FFF8E1;strokeColor=#F57C00;fontSize=12;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;300&quot; y=&quot;360&quot; width=&quot;220&quot; height=&quot;80&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+
+        &lt;mxCell id=&quot;inlet&quot; value=&quot;heightInlet — inflow pipe&quot; style=&quot;text;html=1;fontSize=12;align=left;fontColor=#1F4E79;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;300&quot; y=&quot;395&quot; width=&quot;300&quot; height=&quot;20&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;inlet_tick&quot; value=&quot;&quot; style=&quot;endArrow=none;html=1;strokeColor=#1F4E79;&quot; edge=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry relative=&quot;1&quot; as=&quot;geometry&quot;&gt;
+            &lt;mxPoint x=&quot;270&quot; y=&quot;405&quot; as=&quot;sourcePoint&quot; /&gt;
+            &lt;mxPoint x=&quot;290&quot; y=&quot;405&quot; as=&quot;targetPoint&quot; /&gt;
+          &lt;/mxGeometry&gt;
+        &lt;/mxCell&gt;
+
+        &lt;mxCell id=&quot;stoplevel&quot; value=&quot;stopLevel — unconditional STOP&quot; style=&quot;text;html=1;fontSize=12;align=left;fontColor=#6C3483;fontStyle=1;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;300&quot; y=&quot;440&quot; width=&quot;300&quot; height=&quot;20&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;stop_tick&quot; value=&quot;&quot; style=&quot;endArrow=none;html=1;strokeColor=#6C3483;strokeWidth=2;&quot; edge=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry relative=&quot;1&quot; as=&quot;geometry&quot;&gt;
+            &lt;mxPoint x=&quot;265&quot; y=&quot;450&quot; as=&quot;sourcePoint&quot; /&gt;
+            &lt;mxPoint x=&quot;295&quot; y=&quot;450&quot; as=&quot;targetPoint&quot; /&gt;
+          &lt;/mxGeometry&gt;
+        &lt;/mxCell&gt;
+
+        &lt;mxCell id=&quot;stop_band&quot; value=&quot;pumps OFF (MGC shutdown)&quot; style=&quot;rounded=0;whiteSpace=wrap;html=1;fillColor=#F4ECF7;strokeColor=#6C3483;fontSize=12;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;300&quot; y=&quot;465&quot; width=&quot;220&quot; height=&quot;80&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+
+        &lt;mxCell id=&quot;outlet&quot; value=&quot;heightOutlet — outflow pipe (dry-run trip here)&quot; style=&quot;text;html=1;fontSize=12;align=left;fontColor=#B22222;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;300&quot; y=&quot;510&quot; width=&quot;360&quot; height=&quot;20&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;outlet_tick&quot; value=&quot;&quot; style=&quot;endArrow=none;html=1;strokeColor=#B22222;&quot; edge=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry relative=&quot;1&quot; as=&quot;geometry&quot;&gt;
+            &lt;mxPoint x=&quot;270&quot; y=&quot;520&quot; as=&quot;sourcePoint&quot; /&gt;
+            &lt;mxPoint x=&quot;290&quot; y=&quot;520&quot; as=&quot;targetPoint&quot; /&gt;
+          &lt;/mxGeometry&gt;
+        &lt;/mxCell&gt;
+
+        &lt;mxCell id=&quot;floor&quot; value=&quot;0 (floor)&quot; style=&quot;text;html=1;fontSize=11;align=left;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;300&quot; y=&quot;580&quot; width=&quot;60&quot; height=&quot;20&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+      &lt;/root&gt;
+    &lt;/mxGraphModel&gt;
+  &lt;/diagram&gt;
+&lt;/mxfile&gt;">
   <title>levelbased mode — three zones</title>
   <defs>
     <marker id="arr" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse">
diff --git a/wiki/diagrams/safety-rules.drawio.svg b/wiki/diagrams/safety-rules.drawio.svg
index b1bae39..7866580 100644
--- a/wiki/diagrams/safety-rules.drawio.svg
+++ b/wiki/diagrams/safety-rules.drawio.svg
@@ -1,5 +1,62 @@
 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 900 620" font-family="Arial, sans-serif" font-size="13">
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 900 620" font-family="Arial, sans-serif" font-size="13" content="&lt;mxfile host=&quot;app.diagrams.net&quot; modified=&quot;2026-04-22T12:00:00.000Z&quot; agent=&quot;Claude Code placeholder&quot; etag=&quot;initial&quot; version=&quot;22.0.0&quot; type=&quot;device&quot;&gt;
+  &lt;diagram name=&quot;safety-rules&quot; id=&quot;safetyRules&quot;&gt;
+    &lt;mxGraphModel dx=&quot;1200&quot; dy=&quot;700&quot; grid=&quot;1&quot; gridSize=&quot;10&quot; guides=&quot;1&quot; tooltips=&quot;1&quot; connect=&quot;1&quot; arrows=&quot;1&quot; fold=&quot;1&quot; page=&quot;1&quot; pageScale=&quot;1&quot; pageWidth=&quot;900&quot; pageHeight=&quot;700&quot; math=&quot;0&quot; shadow=&quot;0&quot;&gt;
+      &lt;root&gt;
+        &lt;mxCell id=&quot;0&quot; /&gt;
+        &lt;mxCell id=&quot;1&quot; parent=&quot;0&quot; /&gt;
+        &lt;mxCell id=&quot;title&quot; value=&quot;Safety rules — asymmetric by direction&quot; style=&quot;text;html=1;fontSize=16;fontStyle=1;align=center;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;150&quot; y=&quot;20&quot; width=&quot;600&quot; height=&quot;30&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+
+        &lt;mxCell id=&quot;dryrun_box&quot; value=&quot;DRY-RUN&amp;#10;(direction = draining)&quot; style=&quot;rounded=0;whiteSpace=wrap;html=1;fillColor=#FFF3E0;strokeColor=#E65100;strokeWidth=2;fontSize=14;fontStyle=1;verticalAlign=top;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;80&quot; y=&quot;80&quot; width=&quot;340&quot; height=&quot;340&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;dr_upstream&quot; value=&quot;upstream children  —  KEEP&quot; style=&quot;text;html=1;fontSize=13;align=left;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;100&quot; y=&quot;140&quot; width=&quot;300&quot; height=&quot;24&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;dr_downstream&quot; value=&quot;downstream children  —  STOP&quot; style=&quot;text;html=1;fontSize=13;align=left;fontStyle=1;fontColor=#E65100;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;100&quot; y=&quot;170&quot; width=&quot;300&quot; height=&quot;24&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;dr_machinegroups&quot; value=&quot;machineGroups  —  STOP&quot; style=&quot;text;html=1;fontSize=13;align=left;fontStyle=1;fontColor=#E65100;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;100&quot; y=&quot;200&quot; width=&quot;300&quot; height=&quot;24&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;dr_control&quot; value=&quot;control loop  —  BLOCKED&quot; style=&quot;text;html=1;fontSize=13;align=left;fontStyle=1;fontColor=#E65100;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;100&quot; y=&quot;230&quot; width=&quot;300&quot; height=&quot;24&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;dr_note&quot; value=&quot;safetyControllerActive = true&amp;#10;&amp;#10;Pumps must stop before sucking air.&quot; style=&quot;text;html=1;fontSize=12;align=left;fontStyle=2;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;100&quot; y=&quot;290&quot; width=&quot;300&quot; height=&quot;80&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+
+        &lt;mxCell id=&quot;overfill_box&quot; value=&quot;OVERFILL&amp;#10;(direction = filling)&quot; style=&quot;rounded=0;whiteSpace=wrap;html=1;fillColor=#FFEBEE;strokeColor=#C62828;strokeWidth=2;fontSize=14;fontStyle=1;verticalAlign=top;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;480&quot; y=&quot;80&quot; width=&quot;340&quot; height=&quot;340&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;of_upstream&quot; value=&quot;upstream children  —  STOP  ⚠&quot; style=&quot;text;html=1;fontSize=13;align=left;fontStyle=1;fontColor=#C62828;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;500&quot; y=&quot;140&quot; width=&quot;300&quot; height=&quot;24&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;of_downstream&quot; value=&quot;downstream children  —  KEEP&quot; style=&quot;text;html=1;fontSize=13;align=left;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;500&quot; y=&quot;170&quot; width=&quot;300&quot; height=&quot;24&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;of_machinegroups&quot; value=&quot;machineGroups  —  KEEP&quot; style=&quot;text;html=1;fontSize=13;align=left;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;500&quot; y=&quot;200&quot; width=&quot;300&quot; height=&quot;24&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;of_control&quot; value=&quot;control loop  —  ACTIVE&quot; style=&quot;text;html=1;fontSize=13;align=left;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;500&quot; y=&quot;230&quot; width=&quot;300&quot; height=&quot;24&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;of_note&quot; value=&quot;Level control keeps commanding downstream MGC.&amp;#10;&amp;#10;⚠ &amp;quot;upstream STOP&amp;quot; is only correct in a cascaded layout. In a gravity-sewer station the inflow can&amp;apos;t be stopped — log the spill instead.&quot; style=&quot;text;html=1;fontSize=12;align=left;fontStyle=2;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;500&quot; y=&quot;290&quot; width=&quot;300&quot; height=&quot;120&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+
+        &lt;mxCell id=&quot;trigger_title&quot; value=&quot;Triggers (either condition fires the rule):&quot; style=&quot;text;html=1;fontSize=13;fontStyle=1;align=left;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;80&quot; y=&quot;450&quot; width=&quot;740&quot; height=&quot;20&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+        &lt;mxCell id=&quot;trigger_list&quot; value=&quot;• vol &amp;lt; triggerLowVol     (triggerLowVol  = minVol × (1 + pct/100))&amp;#10;• vol &amp;gt; triggerHighVol    (triggerHighVol = maxVolOverflow × pct/100)&amp;#10;• remainingTime &amp;lt; timeleftToFullOrEmptyThresholdSeconds (if enabled)&quot; style=&quot;text;html=1;fontSize=12;align=left;&quot; vertex=&quot;1&quot; parent=&quot;1&quot;&gt;
+          &lt;mxGeometry x=&quot;80&quot; y=&quot;480&quot; width=&quot;740&quot; height=&quot;80&quot; as=&quot;geometry&quot; /&gt;
+        &lt;/mxCell&gt;
+      &lt;/root&gt;
+    &lt;/mxGraphModel&gt;
+  &lt;/diagram&gt;
+&lt;/mxfile&gt;">
   <title>Safety rules — asymmetric by direction</title>
 
   <text x="450" y="30" text-anchor="middle" font-weight="bold" font-size="16">Safety rules — asymmetric by direction</text>