diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
index 36af4f12..a7b185c7 100644
--- a/docs/astro.config.mjs
+++ b/docs/astro.config.mjs
@@ -18,21 +18,35 @@ export default defineConfig({
       // 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.
+      // cascade teal and 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.
+          // Cascade cyan-teal drives edges, focus accents, and active states.
           primaryColor: '#0E8B82',
           primaryBorderColor: '#36D0C4',
+          primaryTextColor: '#F8FAFC',
           lineColor: '#36D0C4',
-          // Cluster (subgraph) outline in teal; transparent fill keeps the
-          // Starlight surface showing through in either mode.
+          // The flowchart renderer keys node fill, border, and text off mainBkg,
+          // nodeBorder, and nodeTextColor rather than the primary* variables, so
+          // brand all three explicitly. A mid-tone teal fill with light text reads
+          // on both the dark slate and the light gray Starlight backgrounds and
+          // keeps the diagrams on the same palette as the README badges.
+          mainBkg: '#0E8B82',
+          nodeBorder: '#36D0C4',
+          nodeTextColor: '#F8FAFC',
+          // Subgraph (cluster) outline in teal with a transparent fill so the
+          // Starlight surface shows through in either mode; title in teal.
           clusterBorder: '#36D0C4',
           clusterBkg: 'transparent',
-          // Copper/ember secondary accent for highlighted nodes.
+          titleColor: '#36D0C4',
+          // Keep edge labels legible over either background.
+          edgeLabelBackground: '#0B1220',
+          // Copper and ember secondary accent for highlighted nodes.
+          secondaryColor: '#B87333',
+          secondaryBorderColor: '#E8702A',
           tertiaryColor: '#B87333',
           tertiaryBorderColor: '#E8702A',
         },
diff --git a/docs/src/content/docs/internals/architecture.md b/docs/src/content/docs/internals/architecture.md
index 56d145d0..605296ca 100644
--- a/docs/src/content/docs/internals/architecture.md
+++ b/docs/src/content/docs/internals/architecture.md
@@ -1,6 +1,6 @@
 ---
 title: Architecture
-description: How cascade is put together: the design principles, the shape of the system, and the seams built for extension.
+description: "How cascade is put together: the design principles, the shape of the system, and the seams built for extension."
 ---
 
 This page is for contributors and evaluators who want the internals: why cascade
diff --git a/docs/src/content/docs/reference/callbacks.md b/docs/src/content/docs/reference/callbacks.md
index 4f53013d..c16d425b 100644
--- a/docs/src/content/docs/reference/callbacks.md
+++ b/docs/src/content/docs/reference/callbacks.md
@@ -16,16 +16,24 @@ Cascade calls your workflows (callbacks) during pipeline execution. This page de
 
 Every callback is a reusable workflow you declare with `workflow:` in the manifest. Cascade invokes it with `workflow_call`.
 
-```
-Cascade                               Your Repository
-┌─────────────────┐                 ┌──────────────────┐
-│ orchestrate.yaml│──workflow_call──▶│ validate.yaml    │
-│                 │──workflow_call──▶│ build-app.yaml   │
-│                 │──workflow_call──▶│ deploy-cdk.yaml  │
-│                 │                 │                  │
-│ promote.yaml    │──workflow_call──▶│ deploy-svc.yaml  │
-│                 │──workflow_call──▶│ publish.yaml     │
-└─────────────────┘                 └──────────────────┘
+```mermaid
+flowchart LR
+    subgraph cascade["Cascade"]
+        orchestrate["orchestrate.yaml"]
+        promote["promote.yaml"]
+    end
+    subgraph yours["Your repository"]
+        validate["validate.yaml"]
+        build["build-app.yaml"]
+        deployCdk["deploy-cdk.yaml"]
+        deploySvc["deploy-svc.yaml"]
+        publish["publish.yaml"]
+    end
+    orchestrate -->|workflow_call| validate
+    orchestrate -->|workflow_call| build
+    orchestrate -->|workflow_call| deployCdk
+    promote -->|workflow_call| deploySvc
+    promote -->|workflow_call| publish
 ```
 
 ## Standard inputs