docs: add rendered architecture diagrams

README.md

@@ -42,85 +42,19 @@ AI Puppet Theater is a Hugging Face Gradio Space for the Build Small Hackathon,
 
 ## Architecture
 
+The diagrams below are rendered PNGs from Mermaid sources in `assets/` so they display correctly on Hugging Face Spaces.
+
 ### System Flow
 
-```mermaid
-flowchart TD
-    A["User premise and audience actions"] --> B["Show Builder"]
-    B --> C["Director Agent"]
-    C --> D["Actor Agents"]
-    D --> E["Theatrical Tools"]
-    E --> F["Stage Renderer and TTS"]
-    F --> G["Transcript and Puppet Stage"]
-
-    C --> H["Behind the Curtain Trace"]
-    D --> H
-    E --> H
-    F --> H
-
-    R["Runtime and fallback layer"] --> C
-    R --> D
-    R --> F
-    R --> H
-
-    R1["HF API<br/>Qwen/Qwen3-4B-Instruct-2507:nscale"] --> R
-    R2["ZeroGPU or local OpenBMB path"] --> R
-    R3["Deterministic fallback"] --> R
-```
+![AI Puppet Theater system flow](assets/architecture-system-flow.png)
 
 ### Agent Loop
 
-```mermaid
-sequenceDiagram
-    participant U as Audience
-    participant S as Gradio Stage
-    participant D as Director Agent
-    participant A as Actor Agent
-    participant T as Theatrical Tools
-    participant L as Trace Log
-
-    U->>S: Create show or interrupt
-    S->>D: Current session state
-    D->>D: Choose phase, speaker, beat, effect
-    D->>A: Beat instruction
-    A->>A: Update intent, mood, memory
-    A->>T: Optional tool request
-    T-->>A: Tool result
-    A-->>S: Line, emotion, gesture, effect
-    S-->>U: Render puppet beat and voice
-    D-->>L: Director decision
-    A-->>L: Actor response
-    T-->>L: Tool result
-    S-->>L: Audience and render events
-```
+![AI Puppet Theater agent loop](assets/architecture-agent-loop.png)
 
 ### Runtime and Fallbacks
 
-```mermaid
-flowchart LR
-    M["Selected mode"] --> H{"HF API?"}
-    M --> O{"OpenBMB local?"}
-    M --> D["Deterministic mode"]
-
-    H -->|HF_TOKEN and model available| Q["Qwen/Qwen3-4B-Instruct-2507:nscale"]
-    H -->|missing token, timeout, invalid JSON| F["Deterministic fallback"]
-
-    O -->|USE_ZEROGPU=true and spaces available| Z["ZeroGPU generation"]
-    O -->|local CPU or unavailable GPU| L["Local Transformers attempt"]
-    O -->|load failure or invalid output| F
-    Z -->|failure| F
-    L -->|failure| F
-
-    Q --> V["Validate structured output"]
-    Z --> V
-    L --> V
-    D --> V
-    F --> V
-
-    V -->|valid| R["Stage beat"]
-    V -->|invalid after repair| F
-    R --> T["Sanitized trace export"]
-```
+![AI Puppet Theater runtime and fallbacks](assets/architecture-runtime-fallbacks.png)
 
 ## Agent Architecture
 

assets/architecture-agent-loop.mmd

@@ -0,0 +1,22 @@
+%%{init: {"theme": "base", "themeVariables": {"background": "#fffdf7", "primaryTextColor": "#222222", "actorBkg": "#fff2b8", "actorBorder": "#2c2c2c", "actorTextColor": "#222222", "activationBkgColor": "#d9f3df", "activationBorderColor": "#2c2c2c", "signalColor": "#565656", "signalTextColor": "#222222", "labelBoxBkgColor": "#dcecff", "labelBoxBorderColor": "#2c2c2c", "loopTextColor": "#222222", "fontFamily": "Arial, sans-serif"}}}%%
+sequenceDiagram
+    participant U as Audience
+    participant S as Gradio Stage
+    participant D as Director Agent
+    participant A as Actor Agent
+    participant T as Theatrical Tools
+    participant L as Trace Log
+
+    U->>S: Create show or interrupt
+    S->>D: Current session state
+    D->>D: Choose phase, speaker, beat, effect
+    D->>A: Beat instruction
+    A->>A: Update intent, mood, memory
+    A->>T: Optional tool request
+    T-->>A: Tool result
+    A-->>S: Line, emotion, gesture, effect
+    S-->>U: Render puppet beat and voice
+    D-->>L: Director decision
+    A-->>L: Actor response
+    T-->>L: Tool result
+    S-->>L: Audience and render events

assets/architecture-runtime-fallbacks.mmd

@@ -0,0 +1,30 @@
+%%{init: {"theme": "base", "themeVariables": {"background": "#fffdf7", "primaryTextColor": "#222222", "fontFamily": "Arial, sans-serif", "lineColor": "#565656"}}}%%
+flowchart TD
+    M["Selected backend mode"] --> API["HF API<br/>Qwen/Qwen3-4B"]
+    M --> Local["ZeroGPU or local<br/>OpenBMB"]
+    M --> D["Deterministic mode<br/>no token required"]
+
+    API --> V["Validate structured output"]
+    Local --> V
+    D --> V
+
+    API -->|"missing token<br/>timeout<br/>invalid JSON"| F["Deterministic fallback"]
+    Local -->|"GPU unavailable<br/>load failure<br/>invalid output"| F
+    V -->|"invalid after repair"| F
+    F --> V
+
+    V -->|"valid"| R["Stage beat"]
+    R --> T["Sanitized trace export"]
+
+    classDef stage fill:#fff2b8,stroke:#2c2c2c,color:#222222,stroke-width:2px;
+    classDef model fill:#dcecff,stroke:#2c2c2c,color:#222222,stroke-width:2px;
+    classDef runtime fill:#ece8ff,stroke:#2c2c2c,color:#222222,stroke-width:2px;
+    classDef fallback fill:#fbdada,stroke:#2c2c2c,color:#222222,stroke-width:2px;
+    classDef validate fill:#d9f3df,stroke:#2c2c2c,color:#222222,stroke-width:2px;
+    classDef trace fill:#f9e1ee,stroke:#2c2c2c,color:#222222,stroke-width:2px;
+    class M runtime;
+    class API,Local model;
+    class D,F fallback;
+    class V validate;
+    class R stage;
+    class T trace;

assets/architecture-system-flow.mmd

@@ -0,0 +1,31 @@
+%%{init: {"theme": "base", "themeVariables": {"background": "#fffdf7", "primaryTextColor": "#222222", "fontFamily": "Arial, sans-serif", "lineColor": "#565656"}}}%%
+flowchart TD
+    U["User premise<br/>+ audience actions"] --> B["Show Builder"]
+    B --> D["Director Agent"]
+    D --> A["Actor Agents"]
+    A --> Tools["Theatrical Tools"]
+    Tools --> Stage["Stage Renderer<br/>+ TTS"]
+    Stage --> Output["Transcript<br/>+ Puppet Stage"]
+
+    D --> Trace["Behind the Curtain Trace"]
+    A --> Trace
+    Tools --> Trace
+    Stage --> Trace
+
+    HF["HF API<br/>Qwen/Qwen3-4B-Instruct-2507:nscale"] --> Runtime["Runtime + fallback layer"]
+    ZG["ZeroGPU or local<br/>OpenBMB path"] --> Runtime
+    Fallback["Deterministic<br/>fallback"] --> Runtime
+    Runtime --> D
+    Runtime --> A
+
+    classDef stage fill:#fff2b8,stroke:#2c2c2c,color:#222222,stroke-width:2px;
+    classDef agent fill:#d9f3df,stroke:#2c2c2c,color:#222222,stroke-width:2px;
+    classDef tool fill:#dcecff,stroke:#2c2c2c,color:#222222,stroke-width:2px;
+    classDef trace fill:#f9e1ee,stroke:#2c2c2c,color:#222222,stroke-width:2px;
+    classDef runtime fill:#ece8ff,stroke:#2c2c2c,color:#222222,stroke-width:2px;
+    class U,B,Stage,Output stage;
+    class D,A agent;
+    class Tools tool;
+    class Trace trace;
+    class Runtime,HF,ZG runtime;
+    class Fallback runtime;

assets/puppeteer-config.json

@@ -0,0 +1,3 @@
+{
+  "args": ["--no-sandbox", "--disable-setuid-sandbox"]
+}