docs: add hotfix-any-environment Mermaid diagrams

README.md

@@ -104,6 +104,39 @@ flowchart TD
 
 ---
 
+## Hotfix any environment
+
+Most pipelines can only hotfix the tip, which in practice means production. cascade hotfixes **any** environment: it stages the fix on a per-environment integration branch, deploys that one environment with a clean `-rc.N.hotfix.M` version, and rejoins trunk the next time a trunk SHA that already contains the fix is promoted. The example below lands a fix on **staging** while dev, test, and prod stay exactly where they are.
+
+```mermaid
+%%{init: {'theme':'base','themeVariables':{'fontFamily':'ui-sans-serif, system-ui, sans-serif','primaryColor':'#0E8B82','primaryBorderColor':'#36D0C4','primaryTextColor':'#F4FBFA','lineColor':'#1F9B92','clusterBkg':'transparent','clusterBorder':'#36D0C4','tertiaryColor':'#B87333'}}}%%
+flowchart TD
+    T["<b>trunk tip</b><br/>fix already merged (roll forward first)"]
+
+    subgraph LADDER["Environments"]
+        direction LR
+        dev["dev"] --> test["test"] --> staging["staging"] --> prod["prod"]
+    end
+
+    T -- "cherry-pick fix onto env/staging<br/>at staging's recorded base_sha" --> CP["<b>hotfix/staging/&lt;short-sha&gt;</b><br/>base + fix, nothing else"]
+    CP --> RPR["<b>resolution PR</b> (base env/staging)<br/>cascade-hotfix · auto-merge on env checks"]
+    RPR -- "on merge: build -> deploy staging only -> finalize" --> DS
+
+    subgraph DS["staging diverged"]
+        direction TB
+        SV["<b>v1.4.0-rc.2.hotfix.1</b><br/>ref: env/staging<br/>base_sha: trunk SHA · patches: [fix]"]
+    end
+
+    DS -. "targets staging" .-> staging
+
+    DS == "later promotion of a trunk SHA containing the fix<br/>clears divergence (patch-containment guard)" ==> staging
+
+    classDef accent fill:#B87333,stroke:#E8702A,color:#FFF7F0;
+    class SV accent;
+```
+
+---
+
 ## Quick start
 
 ### 1. Install the CLI

docs/src/content/docs/workflows.md

@@ -254,6 +254,20 @@ The framework drops the RC suffix when crossing the prerelease->release boundary
 
 ## Hotfix
 
+```mermaid
+flowchart TD
+    RF["<b>Roll forward first (default)</b><br/>fix merged to trunk; refused if not an ancestor of trunk tip"]
+    RF -- "env must run base + fix only" --> IB["<b>env/&lt;env&gt;</b> integration branch<br/>created on demand at recorded state SHA"]
+    IB --> CP["cherry-pick onto <b>hotfix/&lt;env&gt;/&lt;short-sha&gt;</b>"]
+    CP -- "clean" --> PRclean["resolution PR · <b>cascade-hotfix</b><br/>auto-merge, gated by env checks"]
+    CP -- "conflict" --> PRconf["resolution PR · <b>cascade-hotfix-conflict</b><br/>markers committed; human force-pushes head"]
+    PRclean --> MERGE["on merge"]
+    PRconf --> MERGE
+    MERGE --> FIN["build -> deploy one env -> finalize<br/>vX.Y.Z-rc.N.hotfix.M · ref env/&lt;env&gt; · patches [fix]"]
+    FIN --> DIV["environment diverged<br/>other environments untouched"]
+    DIV == "promote a trunk SHA containing the fix<br/>patch-containment guard refuses dropping it" ==> REJOIN["rejoin trunk<br/>divergence cleared · env/&lt;env&gt; deleted"]
+```
+
 A hotfix applies a single trunk commit onto an environment that is pinned to an older trunk base, without dragging in the intervening commits. This is the case the standard promote flow cannot serve: promoting a pointer forward would advance the target environment past every commit between its base and the fix, which is exactly what an operator pinning that environment is trying to avoid.
 
 ### Roll forward on trunk first (the default)