docs: render concept diagrams with mermaid

website/astro.config.mjs

@@ -4,12 +4,14 @@ import { defineConfig, envField } from 'astro/config';
 import tailwindcss from '@tailwindcss/vite';
 import starlight from '@astrojs/starlight';
 import cloudflare from '@astrojs/cloudflare';
+import mermaid from 'astro-mermaid';
 
 const astro_image_mode =
   process.env.BUB_ASTRO_IMAGE_MODE ?? (process.argv.includes('dev') ? 'dev' : 'build');
 
+/** @type {import('@astrojs/cloudflare').Options['imageService']} */
 const image_service =
-  astro_image_mode === 'dev' ? 'cloudflare' : { runtime: 'passthrough' };
+  astro_image_mode === 'dev' ? 'cloudflare' : { build: 'compile', runtime: 'passthrough' };
 
 export default defineConfig({
   // SSG by default; landing pages opt-in to SSR via `export const prerender = false`.
@@ -41,6 +43,12 @@ export default defineConfig({
     },
   },
   integrations: [
+    // Must come BEFORE starlight so its remark plugin transforms `mermaid`
+    // code blocks before Starlight's markdown pipeline highlights them.
+    mermaid({
+      theme: 'neutral',
+      autoTheme: true,
+    }),
     starlight({
       title: 'Bub',
       description: 'A common shape for agents that live alongside people.',
@@ -50,7 +58,13 @@ export default defineConfig({
         dark: './src/assets/bub-logo-dark.png',
         alt: 'Bub',
       },
-      customCss: ['./src/styles/global.css'],
+      // Use the resolved file URL so Vite's module graph reliably
+      // includes global.css on every Starlight docs page in dev mode.
+      // (Astro v6 scopes CSS per-page from the import graph; with a
+      // relative path Vite occasionally fails to resolve / dedupe in
+      // dev, leaving the docs route unstyled even though
+      // `astro build` + preview both work.)
+      customCss: [fileURLToPath(new URL('./src/styles/global.css', import.meta.url))],
       disable404Route: true,
       locales: {
         root: {

website/package.json

@@ -23,8 +23,10 @@
     "@fontsource/outfit": "^5.2.8",
     "@tailwindcss/vite": "^4.1.14",
     "astro": "^6.0.1",
+    "astro-mermaid": "^2.0.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
+    "mermaid": "^11.15.0",
     "motion": "^12.38.0",
     "satori": "^0.26.0",
     "sharp": "^0.34.2",

website/src/content/docs/docs/concepts/index.mdx

@@ -22,19 +22,23 @@ After your first pass, treat each page as a reference and return to specific sec
 
 This is the same diagram you will see expanded in [Turn pipeline](/docs/concepts/turn-pipeline/):
 
-```diagram
-inbound envelope
-         │
-         ▼
-╭─────────────────╮      ╭───────────────╮      ╭───────────────╮      ╭───────────────╮
-│ resolve_session │────▶│   load_state  │────▶│  build_prompt │────▶│   run_model   │
-│                 │      │               │      │               │      │   [_stream]   │
-╰─────────────────╯      ╰───────────────╯      ╰───────────────╯      ╰───────┬───────╯
-                                                                               │
-      ╭───────────────────╮    ╭─────────────────╮    ╭───────────────╮        │
-      │ dispatch_outbound │◀──│ render_outbound │◀──│   save_state  │◀──────╯
-      │                   │    │                 │    │   (finally)   │
-      ╰───────────────────╯    ╰─────────────────╯    ╰───────────────╯
+```mermaid
+flowchart TB
+  subgraph row1[" "]
+    direction LR
+    inbound(["inbound envelope"]) --> resolve["resolve_session"]
+    resolve --> load["load_state"]
+    load --> prompt["build_prompt"]
+    prompt --> model["run_model<br/>[_stream]"]
+  end
+  subgraph row2[" "]
+    direction RL
+    save["save_state<br/>(finally)"] --> render["render_outbound"]
+    render --> dispatch["dispatch_outbound"]
+  end
+  model --> save
+  style row1 fill:transparent,stroke:transparent
+  style row2 fill:transparent,stroke:transparent
 ```
 
 `save_state` always runs in a `finally` block; `render_outbound` and `dispatch_outbound` run only when the turn succeeds.

website/src/content/docs/docs/concepts/surfaces.mdx

@@ -11,16 +11,11 @@ Most agent frameworks conflate "talks to a chat platform", "knows how to do a pr
 
 ## The three surfaces
 
-```diagram
-          outward I/O              operator procedures        model-callable actions
-    ╭─────────────────────╮      ╭─────────────────────╮      ╭─────────────────────╮
-    │      Channels       │      │       Skills        │      │        Tools        │
-    ╰──────────┬──────────╯      ╰──────────┬──────────╯      ╰──────────┬──────────╯
-               │                            │                            │
-               ▼                            ▼                            ▼
-           Envelope                     Envelope                       State
-       (in & out of the             (loaded into the              (per-turn dict
-        turn pipeline)               prompt as text)            with `_runtime_*`)
+```mermaid
+flowchart LR
+  channels["Channels<br/>outward I/O"] --> envelope_io["Envelope<br/>(in & out of the<br/>turn pipeline)"]
+  skills["Skills<br/>operator procedures"] --> envelope_prompt["Envelope<br/>(loaded into the<br/>prompt as text)"]
+  tools["Tools<br/>model-callable actions"] --> state["State<br/>(per-turn dict<br/>with _runtime_*)"]
 ```
 
 All three surfaces meet on two shared types from [`bub.types`](https://github.com/bubbuild/bub/blob/main/src/bub/types.py):

website/src/content/docs/docs/concepts/turn-pipeline.mdx

@@ -11,48 +11,15 @@ A *turn* is one full pass: one inbound envelope in, zero or more outbound envelo
 
 ## End-to-end flow
 
-```diagram
-   inbound envelope
-           │
-           ▼
-╭─────────────────────╮
-│   resolve_session   │  firstresult
-│      (fallback:     │
-│     channel:chat)   │
-╰──────────┬──────────╯
-           ▼
-╭─────────────────────╮
-│      load_state     │  many → reverse → merge
-│   (seed _runtime_   │
-│      workspace)     │
-╰──────────┬──────────╯
-           ▼
-╭─────────────────────╮
-│     build_prompt    │  firstresult
-│      (fallback:     │
-│     inbound text)   │
-╰──────────┬──────────╯
-           ▼
-╭─────────────────────╮
-│   run_model_stream  │  firstresult
-│     ↕ adapts to     │
-│      run_model      │  firstresult
-╰──────────┬──────────╯
-           ▼  (always)
-╭─────────────────────╮
-│      save_state     │  many, in finally
-╰──────────┬──────────╯
-           ▼
-╭─────────────────────╮
-│   render_outbound   │  many → flatten
-│      (fallback:     │
-│     one envelope    │
-│     from output)    │
-╰──────────┬──────────╯
-           ▼
-╭─────────────────────╮
-│  dispatch_outbound  │  many, per outbound
-╰─────────────────────╯
+```mermaid
+flowchart TD
+  inbound(["inbound envelope"]) --> resolve["resolve_session<br/>firstresult<br/>(fallback: channel:chat)"]
+  resolve --> load["load_state<br/>many → reverse → merge<br/>(seed _runtime_ workspace)"]
+  load --> prompt["build_prompt<br/>firstresult<br/>(fallback: inbound text)"]
+  prompt --> model["run_model_stream<br/>↕ adapts to run_model<br/>firstresult"]
+  model -->|always| save["save_state<br/>many, in finally"]
+  save --> render["render_outbound<br/>many → flatten<br/>(fallback: one envelope from output)"]
+  render --> dispatch["dispatch_outbound<br/>many, per outbound"]
 ```
 
 ## Stages, in source order

website/src/content/docs/zh-cn/docs/concepts/index.mdx

@@ -22,19 +22,23 @@ sidebar:
 
 下面这张图会在 [Turn pipeline](/zh-cn/docs/concepts/turn-pipeline/) 中详细展开：
 
-```diagram
-inbound envelope
-         │
-         ▼
-╭─────────────────╮      ╭───────────────╮      ╭───────────────╮      ╭───────────────╮
-│ resolve_session │────▶│   load_state  │────▶│  build_prompt │────▶│   run_model   │
-│                 │      │               │      │               │      │   [_stream]   │
-╰─────────────────╯      ╰───────────────╯      ╰───────────────╯      ╰───────┬───────╯
-                                                                               │
-      ╭───────────────────╮    ╭─────────────────╮    ╭───────────────╮        │
-      │ dispatch_outbound │◀──│ render_outbound │◀──│   save_state  │◀──────╯
-      │                   │    │                 │    │   (finally)   │
-      ╰───────────────────╯    ╰─────────────────╯    ╰───────────────╯
+```mermaid
+flowchart TB
+  subgraph row1[" "]
+    direction LR
+    inbound(["inbound envelope"]) --> resolve["resolve_session"]
+    resolve --> load["load_state"]
+    load --> prompt["build_prompt"]
+    prompt --> model["run_model<br/>[_stream]"]
+  end
+  subgraph row2[" "]
+    direction RL
+    save["save_state<br/>(finally)"] --> render["render_outbound"]
+    render --> dispatch["dispatch_outbound"]
+  end
+  model --> save
+  style row1 fill:transparent,stroke:transparent
+  style row2 fill:transparent,stroke:transparent
 ```
 
 `save_state` 始终在 `finally` 块中执行；`render_outbound` 与 `dispatch_outbound` 仅在 turn 成功时执行。

website/src/content/docs/zh-cn/docs/concepts/surfaces.mdx

@@ -11,16 +11,11 @@ sidebar:
 
 ## 三个扩展面
 
-```diagram
-          outward I/O              operator procedures        model-callable actions
-    ╭─────────────────────╮      ╭─────────────────────╮      ╭─────────────────────╮
-    │      Channels       │      │       Skills        │      │        Tools        │
-    ╰──────────┬──────────╯      ╰──────────┬──────────╯      ╰──────────┬──────────╯
-               │                            │                            │
-               ▼                            ▼                            ▼
-           Envelope                     Envelope                       State
-       (in & out of the             (loaded into the              (per-turn dict
-        turn pipeline)               prompt as text)            with `_runtime_*`)
+```mermaid
+flowchart LR
+  channels["Channels<br/>outward I/O"] --> envelope_io["Envelope<br/>(in & out of the<br/>turn pipeline)"]
+  skills["Skills<br/>operator procedures"] --> envelope_prompt["Envelope<br/>(loaded into the<br/>prompt as text)"]
+  tools["Tools<br/>model-callable actions"] --> state["State<br/>(per-turn dict<br/>with _runtime_*)"]
 ```
 
 三者在来自 [`bub.types`](https://github.com/bubbuild/bub/blob/main/src/bub/types.py) 的两个共享类型上相遇：

website/src/content/docs/zh-cn/docs/concepts/turn-pipeline.mdx

@@ -11,48 +11,15 @@ sidebar:
 
 ## 端到端流程
 
-```diagram
-   inbound envelope
-           │
-           ▼
-╭─────────────────────╮
-│   resolve_session   │  firstresult
-│      (fallback:     │
-│     channel:chat)   │
-╰──────────┬──────────╯
-           ▼
-╭─────────────────────╮
-│      load_state     │  many → reverse → merge
-│   (seed _runtime_   │
-│      workspace)     │
-╰──────────┬──────────╯
-           ▼
-╭─────────────────────╮
-│     build_prompt    │  firstresult
-│      (fallback:     │
-│     inbound text)   │
-╰──────────┬──────────╯
-           ▼
-╭─────────────────────╮
-│   run_model_stream  │  firstresult
-│     ↕ adapts to     │
-│      run_model      │  firstresult
-╰──────────┬──────────╯
-           ▼  (always)
-╭─────────────────────╮
-│      save_state     │  many, in finally
-╰──────────┬──────────╯
-           ▼
-╭─────────────────────╮
-│   render_outbound   │  many → flatten
-│      (fallback:     │
-│     one envelope    │
-│     from output)    │
-╰──────────┬──────────╯
-           ▼
-╭─────────────────────╮
-│  dispatch_outbound  │  many, per outbound
-╰─────────────────────╯
+```mermaid
+flowchart TD
+  inbound(["inbound envelope"]) --> resolve["resolve_session<br/>firstresult<br/>(fallback: channel:chat)"]
+  resolve --> load["load_state<br/>many → reverse → merge<br/>(seed _runtime_ workspace)"]
+  load --> prompt["build_prompt<br/>firstresult<br/>(fallback: inbound text)"]
+  prompt --> model["run_model_stream<br/>↕ adapts to run_model<br/>firstresult"]
+  model -->|always| save["save_state<br/>many, in finally"]
+  save --> render["render_outbound<br/>many → flatten<br/>(fallback: one envelope from output)"]
+  render --> dispatch["dispatch_outbound<br/>many, per outbound"]
 ```
 
 ## 各阶段（按源码顺序）