docs: add cascade-themed mermaid diagrams to readme and docs

README.md

@@ -36,36 +36,36 @@
 
 The **manifest** (`.github/manifest.yaml`) is the single source of truth. It holds both the pipeline configuration and the live deployment state for every environment. You run `cascade generate-workflow` once; after that the generated workflows own their own execution.
 
-```
-Merge to trunk
-      │
-      ▼
-┌─────────────────────────────────────────────────────────────┐
-│  Orchestrate workflow (generated)                           │
-│  Setup → Validate → Build(s) → Deploy(s) → Finalize         │
-│                                                             │
-│  • Change detection: only run what changed                  │
-│  • Version computation: next semver RC from commits         │
-│  • State written to manifest.yaml on every run              │
-└─────────────────────────────────────────────────────────────┘
-      │
-      ▼  state[dev] updated, draft release created
-      │
-      │  workflow_dispatch (promote)
-      ▼
-┌─────────────────────────────────────────────────────────────┐
-│  Promote workflow (generated)                               │
-│  Preflight → Deploy(s) → Publish callback → Finalize        │
-│                                                             │
-│  • Same artifacts, never rebuilt on promote                 │
-│  • Breaking-change gate at prerelease → release boundary    │
-│  • Per-deploy change detection: skip unchanged              │
-│  • Release published, RC tags cleaned up                    │
-└─────────────────────────────────────────────────────────────┘
-```
+```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
+    M["<b>.github/manifest.yaml</b><br/>config + live state"] --> G["<b>cascade generate-workflow</b>"]
+    G --> WF["Generated GitHub Actions<br/>orchestrate.yaml + promote.yaml"]
+
+    WF -- "merge to trunk" --> O
+
+    subgraph O["Orchestrate (on merge)"]
+        direction LR
+        O1["Setup"] --> O2["Validate"] --> O3["Build"] --> O4["Deploy first env"] --> O5["Finalize"]
+    end
+
+    O -- "workflow_dispatch · same artifacts, never rebuilt" --> P
 
-<!-- TODO(image): promote/cascade flow diagram. place at docs/images/promote-flow.png once generated -->
-<!-- ![cascade promotion flow](docs/images/promote-flow.png) -->
+    subgraph P["Promote (cascade through environments)"]
+        direction LR
+        dev["dev"] --> test["test"] --> staging["staging"] --> prod["prod"]
+    end
+
+    P --> R
+
+    subgraph R["Release lifecycle"]
+        direction LR
+        draft["draft"] --> pre["prerelease"] --> pub["published<br/>RC tags cleaned"]
+    end
+
+    classDef accent fill:#B87333,stroke:#E8702A,color:#FFF7F0;
+    class M accent;
+```
 
 ---
 

docs/astro.config.mjs

@@ -15,7 +15,28 @@ export default defineConfig({
     // mermaid auto-syncs when the reader toggles the theme.
     mermaid({
       theme: 'dark',
+      // Mermaid follows the Starlight light/dark toggle. We keep autoTheme so
+      // node fills and text stay legible in both modes, and brand only the
+      // accent surfaces (edges, borders, cluster outlines, active accent) with
+      // cascade teal/copper - colors that read on both the dark slate and the
+      // light gray Starlight backgrounds.
       autoTheme: true,
+      mermaidConfig: {
+        themeVariables: {
+          fontFamily: 'ui-sans-serif, system-ui, sans-serif',
+          // Cascade cyan-teal: drives edges, focus accents, and active states.
+          primaryColor: '#0E8B82',
+          primaryBorderColor: '#36D0C4',
+          lineColor: '#36D0C4',
+          // Cluster (subgraph) outline in teal; transparent fill keeps the
+          // Starlight surface showing through in either mode.
+          clusterBorder: '#36D0C4',
+          clusterBkg: 'transparent',
+          // Copper/ember secondary accent for highlighted nodes.
+          tertiaryColor: '#B87333',
+          tertiaryBorderColor: '#E8702A',
+        },
+      },
     }),
     starlight({
       title: 'Cascade',

docs/src/content/docs/architecture.md

@@ -15,39 +15,34 @@ System design and internals of cascade.
 
 ## System Overview
 
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│                              cascade                                  │
-├─────────────────────────────────────────────────────────────────────┤
-│                                                                       │
-│  ┌───────────────┐    ┌───────────────┐    ┌───────────────┐         │
-│  │   CLI Tool    │    │   Workflows   │    │    Actions    │         │
-│  │   (cascade)   │    │  (reusable)   │    │  (composite)  │         │
-│  └───────────────┘    └───────────────┘    └───────────────┘         │
-│          │                    │                    │                  │
-│          └────────────────────┼────────────────────┘                  │
-│                               │                                       │
-│  ┌───────────────────────────────────────────────────────────────┐   │
-│  │                          Go Packages                          │   │
-│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐  │   │
-│  │  │ config  │ │ changes │ │changelog│ │generate │ │ release │  │   │
-│  │  └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘  │   │
-│  │  ┌───────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐            │   │
-│  │  │orchestrate│ │ promote │ │ version │ │  reset  │            │   │
-│  │  └───────────┘ └─────────┘ └─────────┘ └─────────┘            │   │
-│  │  ┌─────────┐                                                  │   │
-│  │  │   git   │                                                  │   │
-│  │  └─────────┘                                                  │   │
-│  └───────────────────────────────────────────────────────────────┘   │
-│                                                                       │
-└─────────────────────────────────────────────────────────────────────┘
-                                │
-                    ┌───────────┴───────────┐
-                    ▼                       ▼
-            ┌───────────────┐       ┌───────────────┐
-            │Adopting Repos │       │   GitHub API  │
-            │  (callbacks)  │       │  (releases)   │
-            └───────────────┘       └───────────────┘
+```mermaid
+flowchart TD
+    subgraph cascade["cascade"]
+        direction TB
+        subgraph surfaces[" "]
+            direction LR
+            cli["CLI Tool<br/>(cascade)"]
+            wf["Workflows<br/>(reusable)"]
+            act["Actions<br/>(composite)"]
+        end
+        subgraph pkgs["Go Packages"]
+            direction LR
+            config["config"]
+            changes["changes"]
+            changelog["changelog"]
+            generate["generate"]
+            release["release"]
+            orchestrate["orchestrate"]
+            promote["promote"]
+            version["version"]
+            reset["reset"]
+            git["git"]
+        end
+        surfaces --> pkgs
+    end
+
+    cascade --> repos["Adopting Repos<br/>(callbacks)"]
+    cascade --> api["GitHub API<br/>(releases)"]
 ```
 
 ## Directory Structure
@@ -482,23 +477,13 @@ For deployments spanning multiple repositories (e.g., backend + CDK + K8s), the
 
 ### Primary/Satellite Model
 
-```
-                    ┌───────────────────────────────────────────┐
-                    │           Primary Repo (Backend)           │
-                    │  - Owns environment state machine          │
-                    │  - Coordinates all promotions              │
-                    │  - Tracks external deploy state            │
-                    └───────────────────────────────────────────┘
-                                        ▲
-                    ┌───────────────────┼───────────────────┐
-                    │                   │                   │
-            ┌───────┴────────┐  ┌───────┴────────┐  ┌───────┴────────┐
-            │  Satellite A   │  │  Satellite B   │  │  Satellite C   │
-            │  (CDK Infra)   │  │ (K8s Manifests)│  │  (Terraform)   │
-            │                │  │                │  │                │
-            │ Notifies after │  │ Notifies after │  │ Notifies after │
-            │ dev deploy     │  │ dev deploy     │  │ dev deploy     │
-            └────────────────┘  └────────────────┘  └────────────────┘
+```mermaid
+flowchart BT
+    satA["Satellite A<br/>(CDK Infra)"] -- "notify after dev deploy" --> primary
+    satB["Satellite B<br/>(K8s Manifests)"] -- "notify after dev deploy" --> primary
+    satC["Satellite C<br/>(Terraform)"] -- "notify after dev deploy" --> primary
+
+    primary["<b>Primary Repo (Backend)</b><br/>Owns environment state machine<br/>Coordinates all promotions<br/>Tracks external deploy state"]
 ```
 
 ### Communication Flow

docs/src/content/docs/workflows.md

@@ -11,33 +11,17 @@ Triggered on every merge to trunk. Handles the full CI/CD pipeline for the first
 
 ### Flow
 
-```
-Merge to Trunk
-      │
-      ▼
-┌──────────┐
-│  Setup   │ ← Parse config, detect changes, compute version
-└──────────┘
-      │
-      ▼
-┌──────────┐
-│ Validate │ ← Optional pre-build validation
-└──────────┘
-      │
-      ▼
-┌──────────┐
-│  Build   │ ← Matrix: triggered builds only
-└──────────┘
-      │
-      ▼
-┌──────────┐
-│  Deploy  │ ← Matrix: triggered deploys with dependency ordering
-└──────────┘
-      │
-      ▼
-┌──────────┐
-│ Finalize │ ← Update state, generate changelog, draft pre-release
-└──────────┘
+```mermaid
+flowchart TD
+    M["Merge to trunk"] --> S["Setup"] --> V["Validate"] --> B["Build"] --> D["Deploy"] --> F["Finalize"]
+    S -.-> sn["Parse config, detect changes,<br/>compute version"]
+    V -.-> vn["Optional pre-build validation"]
+    B -.-> bn["Matrix: triggered builds only"]
+    D -.-> dn["Matrix: triggered deploys,<br/>dependency-ordered"]
+    F -.-> fn["Update state, generate changelog,<br/>draft pre-release"]
+
+    classDef note fill:none,stroke:none,color:#8A929C;
+    class sn,vn,bn,dn,fn note;
 ```
 
 ### Triggering
@@ -109,28 +93,16 @@ Manual workflow to promote between environments.
 
 ### Flow
 
-```
-Default mode (one step at a time)
-      │
-      ▼
-┌──────────┐
-│ Preflight│ ← Validate source/target, check ancestry, gate breaking changes
-└──────────┘
-      │
-      ▼
-┌──────────┐
-│  Deploy  │ ← Matrix: per-deploy with change detection
-└──────────┘
-      │
-      ▼
-┌──────────┐
-│  Publish │ ← (only at prerelease → release boundary, if publish: configured)
-└──────────┘
-      │
-      ▼
-┌──────────┐
-│ Finalize │ ← Update state, publish release, dispatch Release workflow
-└──────────┘
+```mermaid
+flowchart TD
+    M["Default mode<br/>(one step at a time)"] --> P["Preflight"] --> D["Deploy"] --> Pub["Publish"] --> F["Finalize"]
+    P -.-> pn["Validate source/target, check ancestry,<br/>gate breaking changes"]
+    D -.-> dn["Matrix: per-deploy with change detection"]
+    Pub -.-> pubn["Only at prerelease to release boundary,<br/>if publish: configured"]
+    F -.-> fn["Update state, publish release,<br/>dispatch Release workflow"]
+
+    classDef note fill:none,stroke:none,color:#8A929C;
+    class pn,dn,pubn,fn note;
 ```
 
 A cascade mode (e.g., `dev-to-prod`) walks the chain step by step, running deploy/finalize for each intermediate environment, with the breaking-change gate enforced at the prerelease->release boundary.