feat: update model endpoint URLs and enhance documentation with mermaid diagrams

config/models.yaml

@@ -16,8 +16,10 @@
 # The LiteLLM model string for a custom OpenAI-compatible endpoint is
 # `openai/<served_model_id>` (the HF repo id) with `base_url` pointing at the
 # endpoint's /v1 URL.  Modal serves each endpoint at
-#   https://<workspace>--<endpoint_name>.modal.run/v1
-# so only the workspace is deploy-specific: it is templated from $MODAL_WORKSPACE
+#   https://<workspace>--<app_name>-<endpoint_name>.modal.run/v1
+# where <app_name> is the modal.App name (nvidia-llms / openbmb-llms / google-llms)
+# and <endpoint_name> is the per-model function slug.  So only the workspace is
+# deploy-specific: it is templated from $MODAL_WORKSPACE
 # and never hard-coded.  $MODAL_LLM_KEY is the endpoint key (vLLM accepts any
 # token, default "EMPTY").  Unset templates expand to "" → the offline stub is
 # used and these live bindings are ignored.
@@ -29,25 +31,25 @@ offline: null
 profiles:
   tiny:
     model: openai/nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16
-    base_url: https://${MODAL_WORKSPACE}--nemotron-3-nano-4b.modal.run/v1
+    base_url: https://${MODAL_WORKSPACE}--nvidia-llms-nemotron-3-nano-4b.modal.run/v1
     api_key: ${MODAL_LLM_KEY}
     temperature: 0.7
     max_tokens: 160
   fast:
     model: openai/openbmb/MiniCPM4.1-8B
-    base_url: https://${MODAL_WORKSPACE}--minicpm-4-1-8b.modal.run/v1
+    base_url: https://${MODAL_WORKSPACE}--openbmb-llms-minicpm-4-1-8b.modal.run/v1
     api_key: ${MODAL_LLM_KEY}
     temperature: 0.9
     max_tokens: 220
   balanced:
     model: openai/google/gemma-4-12B
-    base_url: https://${MODAL_WORKSPACE}--gemma-4-12b.modal.run/v1
+    base_url: https://${MODAL_WORKSPACE}--google-llms-gemma-4-12b.modal.run/v1
     api_key: ${MODAL_LLM_KEY}
     temperature: 0.8
     max_tokens: 320
   strong:
     model: openai/google/gemma-4-26B-A4B-it
-    base_url: https://${MODAL_WORKSPACE}--gemma-4-26b.modal.run/v1
+    base_url: https://${MODAL_WORKSPACE}--google-llms-gemma-4-26b.modal.run/v1
     api_key: ${MODAL_LLM_KEY}
     temperature: 0.6
     max_tokens: 480

docs/adr/0015-litellm-gateway-modal-models.md

@@ -51,9 +51,10 @@ self-served vLLM endpoint accepts any token, so the key defaults to the
 conventional `"EMPTY"` when unset.
 
 **Workspace is not hard-coded.** Modal serves each endpoint at a distinct
-subdomain `https://<workspace>--<endpoint>.modal.run/v1`, so a single base URL
-cannot address all four. `config/models.yaml` templates only the deploy-specific
-workspace: `base_url: https://${MODAL_WORKSPACE}--<endpoint>.modal.run/v1` and
+subdomain `https://<workspace>--<app>-<endpoint>.modal.run/v1` (app = nvidia-llms /
+openbmb-llms / google-llms), so a single base URL cannot address all four.
+`config/models.yaml` templates only the deploy-specific workspace:
+`base_url: https://${MODAL_WORKSPACE}--<app>-<endpoint>.modal.run/v1` and
 `api_key: ${MODAL_LLM_KEY}`. `Registry.from_dir()` expands these on load
 (`_expand_env`); if any referenced var is unset the whole string collapses to `""`
 (an incomplete binding is *not configured* rather than a broken half-URL) and a

docs/architecture/config-system.md

@@ -31,6 +31,16 @@ Drop a file in, and it exists.  No engine edit, no import to add.
 
 `src/core/registry.py` loads the directory and assembles live objects:
 
+```mermaid
+flowchart LR
+    Files["config/<br/>agents/*.yaml · scenarios/*.yaml · models.yaml"] --> Load["Registry.from_dir()"]
+    Load --> Val["validate_agent / validate_scenario<br/>Pydantic · extra=forbid"]
+    Val --> Reg["Registry<br/>agents · scenarios · models"]
+    Reg --> BS["build_scenario(name)"]
+    BS --> Cast["resolve cast → live ManifestAgents<br/>+ ModelRouter + ToolRegistry"]
+    Cast --> Scn["Scenario (runnable)"]
+```
+
 ```python
 reg = default_registry()                       # loads config/
 scenario = reg.build_scenario("mystery-roots") # cast names -> live agents

docs/architecture/long-running.md

@@ -19,6 +19,18 @@ time.  This is what lets the same scenario "run in realtime" for a demo and
 
 ## The ledger is the checkpoint
 
+```mermaid
+flowchart LR
+    Run["step(n_ticks=N)"] -->|append| L[("Ledger")]
+    L --> Snap{"turn % snapshot_every == 0?"}
+    Snap -->|yes| Backup["snapshot_to(path)"] --> Run
+    Snap -->|no| Run
+    Run -.->|crash| Crash([process dies])
+    Crash --> From["SQLiteLedger.from_file(db)"]
+    From --> Restore["conductor.restore()<br/>adopt run_id + last turn"]
+    Restore --> Run
+```
+
 Because all state derives from the append-only ledger, crash recovery is nearly
 free:
 

docs/architecture/memory-stack.md

@@ -15,6 +15,20 @@ This solves four problems at once:
 
 ## Three Layers
 
+```mermaid
+flowchart TD
+    L[("Append-only Ledger")] --> V["Visibility filter<br/>own events ∪ globally-visible kinds"]
+    V --> E["Layer 1 · EpisodicMemory<br/>recent window (always on)"]
+    V --> S["Layer 2 · SalienceMemory<br/>top-k: relevance × recency × importance"]
+    Idx["MemoryIndex · optional · ADR-0018<br/>semantic relevance"] -.->|upgrades relevance term| S
+    V --> Rf["Layer 3 · ReflectionMemory<br/>emits agent.reflected every N events"]
+    Rf -->|"agent.reflected (globally visible)"| L
+    E --> CB["ContextBuilder → prompt"]
+    S --> CB
+```
+
+All three layers are *views over the one ledger* — none holds separate state.
+
 ### Layer 1: EpisodicMemory (always on)
 
 The simplest layer.  An agent sees:

docs/architecture/model-routing.md

@@ -72,7 +72,7 @@ offline: null            # null=auto, true=stub everywhere, false=always live
 profiles:
   tiny:
     model: openai/nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16
-    base_url: https://${MODAL_WORKSPACE}--nemotron-3-nano-4b.modal.run/v1
+    base_url: https://${MODAL_WORKSPACE}--nvidia-llms-nemotron-3-nano-4b.modal.run/v1
     api_key: ${MODAL_LLM_KEY}
     temperature: 0.7
     max_tokens: 160

docs/architecture/next-steps/architecture-review-and-next-steps.md

@@ -71,6 +71,18 @@ Trace **Mystery Roots** (the "convergent blackboard swarm"):
 | `devils-advocate` | `agent.thought` (subscribes to `agent.spoke`) | ❌ — and it can't even see the hypothesis it's meant to rebut |
 | `mystery-judge` | `judge.verdict` | — but it sees **none** of the clues or hypotheses |
 
+```mermaid
+flowchart LR
+    CG["clue-gatherer<br/>emits agent.thought"]
+    HF["hypothesis-former<br/>emits agent.spoke"]
+    DA["devils-advocate"]
+    J["mystery-judge<br/>emits judge.verdict"]
+    HF -->|"triggers (subscribes_to agent.spoke)"| DA
+    HF -.->|"✗ but DA cannot read it"| DA
+    CG -.->|"✗ invisible"| J
+    HF -.->|"✗ invisible"| J
+```
+
 The judge reaches a verdict having seen only the genesis `world.observed` (the seed),
 its own prior verdicts, and visitor injections. The clue-gathering and
 hypothesis-forming machinery produces events **no one downstream reads.** The

docs/architecture/next-steps/phase-6-illustrated-serial.md

@@ -52,22 +52,18 @@ EventKind = Literal[
 
 ## The episode loop
 
-```
-episode.started
-    │
-    ├──→ Beat Proposer → beat.proposed
-    │         │
-    │         ├──→ Dialogue Writer → agent.spoke
-    │         ├──→ Scene Describer → world.observed
-    │         │         │
-    │         │         └──→ Artist → image.generated (MCP call)
-    │         │
-    │         └──→ Continuity Keeper → agent.thought (checks for errors)
-    │
-    └──→ Serial Judge reads all of the above
-          │
-          ├── judge.approved → Episode Publisher writes artifact
-          └── judge.rejected → Beat Proposer tries again (max 3 attempts)
+```mermaid
+flowchart TD
+    Start(["episode.started"]) --> Beat["Beat Proposer<br/>beat.proposed"]
+    Beat --> Dia["Dialogue Writer<br/>agent.spoke"]
+    Beat --> Scene["Scene Describer<br/>world.observed"]
+    Scene --> Art["Artist<br/>image.generated · MCP call"]
+    Beat --> Cont["Continuity Keeper<br/>agent.thought · checks errors"]
+    Dia --> Judge{"Serial Judge<br/>reads all of the above"}
+    Art --> Judge
+    Cont --> Judge
+    Judge -->|approved| Pub["Episode Publisher<br/>writes artifact"]
+    Judge -->|"rejected · retry ≤ 3"| Beat
 ```
 
 The judge holds the **publish gate**: no episode is published unless the judge approves.

docs/architecture/observer-pattern.md

@@ -4,15 +4,17 @@
 
 The observer is the camera crew.  It has exactly one rule: **never append events**.
 
+```mermaid
+flowchart LR
+    Conductor --> Agents
+    Agents -->|append| Ledger[("Ledger")]
+    Ledger -->|read only| Obs["Observer.consume()"]
+    Obs --> Diff["ViewDiff — the delta"]
+    Diff --> Out["UI callback · SSE · WebSocket"]
 ```
-COGNITIVE LOOP (conductor + agents)     RENDERING (observer)
-       ↓ appends                             ↓ reads
-   [ Ledger ]  ────────────────────────→  Observer.consume()
-                                              ↓
-                                         ViewDiff
-                                              ↓
-                                         UI callback / SSE / WebSocket
-```
+
+The cognitive loop (left) writes; the observer (right) only reads. The world runs
+identically whether or not any observer is attached.
 
 The cognitive loop runs identically whether or not any observer is attached.
 The world is not "observed into existence" — it runs, and the observer watches.

docs/architecture/overview.md

@@ -6,19 +6,21 @@ One event-sourced engine; every world is a *configuration* of it.  Agents on the
 left produce into a shared ledger; oversight and rendering on the right consume
 from it.  The two sides never call each other.
 
-```text
-                 config/ (YAML)  ─────────────────────────────┐
-                 agents · scenarios · models                  │ Registry
-                                                               ▼
-Visitor ─► Gradio UI ─► Conductor ─► ManifestAgent ─► ModelRouter ─► small model
-                          │  ▲           │  └─► ToolRegistry (capability-checked)
-                  Governor│  │           ▼
-              (calls/tokens) │      Event Ledger (append-only, idempotent)
-                             │           │
-                             │      Projections ──► Observer ──► Gradio UI
-                             └───────────┘
+```mermaid
+flowchart LR
+    Config["config/ YAML<br/>agents · scenarios · models"] --> Registry --> Conductor
+    Visitor --> UI["Gradio UI"] --> Conductor
+    Governor["Governor<br/>calls · tokens · spend"] -.->|checks| Conductor
+    Conductor --> Agent["ManifestAgent"]
+    Agent --> Router["ModelRouter → small model"]
+    Agent --> Tools["ToolRegistry<br/>capability-checked"]
+    Agent -->|append| Ledger[("Event Ledger<br/>append-only · idempotent")]
+    Ledger -->|read| Projections --> Observer --> UI
 ```
 
+*Producers (left of the ledger) only ever **append**; consumers (right) only ever
+**read**. The two sides communicate through the ledger and never call each other.*
+
 The ledger is the only source of truth.  Agent memory, world state, UI state, and
 bloggable traces are all projections derived from events.
 

docs/architecture/scenario-authoring.md

@@ -73,6 +73,16 @@ a tool grant + handler, salience memory, and the visibility gotcha.
 Three custom kinds (`rumor.whispered`, `fact.checked`, `news.published`) — none of
 which the engine has ever heard of.
 
+```mermaid
+flowchart TD
+    Seed(["genesis: world.observed (the seed)"]) --> RS["rumor-starter · tick 1<br/>rumor.whispered"]
+    RS --> G["gossip<br/>subscribes rumor.whispered<br/>emits rumor.whispered"]
+    RS --> FC["fact-checker<br/>subscribes rumor.whispered<br/>oracle tool → fact.checked"]
+    G -.->|begets more gossip| G
+    G --> GZ["gazette · tick 5<br/>news.published"]
+    FC --> GZ
+```
+
 ### Step 2 — Write the agent manifests
 
 `config/agents/rumor-starter.yaml`:

docs/architecture/structured-output.md

@@ -25,6 +25,24 @@ exposes `complete_structured`, it uses the validated path; otherwise it falls
 back to the prompt-and-parse path. Both feed the same `Event` construction, so
 the conductor, ledger, and projections are identical either way.
 
+```mermaid
+flowchart TD
+    A["act() → _resolve_payload()"] --> Q{"provider has<br/>complete_structured?"}
+    Q -->|"yes · live"| Live["Instructor + LiteLLM<br/>kind-constrained model"]
+    Live --> LV{"validates?"}
+    LV -->|yes| Out["typed Event payload"]
+    LV -->|"no · retry ≤ max_retries"| Live
+    LV -->|"error / gives up"| Parse
+    Q -->|"no · offline stub"| Inst["append OUTPUT FORMAT → complete()"]
+    Inst --> Parse["parse_agent_output()"]
+    Parse --> T1{"Tier 1: strict JSON?"}
+    T1 -->|yes| Out
+    T1 -->|no| T2{"Tier 2: extract JSON block?"}
+    T2 -->|yes| Out
+    T2 -->|no| T3["Tier 3: wrap raw text<br/>_raw_fallback = true"]
+    T3 --> Out
+```
+
 ---
 
 ## The constraint block

docs/architecture/subscription-routing.md

@@ -17,6 +17,16 @@ conductor routes accordingly.  Coupling is to the **event schema**, not to each
 
 The conductor runs **two tracks per step** in order:
 
+```mermaid
+flowchart TD
+    S(["step() → _tick(): turn += 1"]) --> Gov["governor.check()"]
+    Gov --> P1["Track 1 — drain trigger queue FIFO<br/>(agents whose subscribes_to matched)"]
+    P1 --> P2["Track 2 — run tick agents<br/>(schedule.tick_every fires)"]
+    P2 --> N["appended events → notify_subscribers<br/>queue matching agents"]
+    N -.->|feeds next step| P1
+    P2 --> Snap["maybe snapshot"]
+```
+
 ### Track 1: Event-triggered (subscriptions)
 
 When any event is appended to the ledger, the conductor checks which agents

docs/architecture/tool-contract.md

@@ -48,10 +48,20 @@ tool running out-of-process over the Model Context Protocol (MCP) — same contr
 swappable transport, invisible to agents.  The capability check is the security
 boundary; MCP is only transport.
 
+```mermaid
+flowchart TD
+    A["agent.call_tool(name, params)"] --> B["ToolRegistry.call()"]
+    B --> C{"name in manifest.tools?"}
+    C -->|no| X["raise CapabilityViolation"]
+    C -->|yes| D{"registered in-process?"}
+    D -->|yes| E["run() → dict (default)"]
+    D -->|no| F{"resolver has it?"}
+    F -->|yes| G["MCP client → stdio server → dict"]
+    F -->|no| Y["raise KeyError"]
 ```
-Agent ──call_tool──► ToolRegistry ──(grant check FIRST)──► in-process fn   (default)
-                                                       └──► MCP client ─► stdio server
-```
+
+The capability check (node C) runs **first** — before any transport is touched —
+so swapping in-process for MCP never weakens the security boundary.
 
 `ToolRegistry.call(...)` enforces `tool in manifest.tools` and raises
 `CapabilityViolation` on a denied call **before any transport is touched** — then

docs/architecture/turn-lifecycle.md

@@ -3,6 +3,31 @@
 One sim-tick, end to end.  `Conductor.step(n_ticks=1)` runs this loop; the model
 is stateless and all state is passed in per turn.
 
+```mermaid
+sequenceDiagram
+    participant C as Conductor
+    participant G as Governor
+    participant A as Agent
+    participant R as ModelRouter
+    participant L as Ledger
+    participant O as Observer
+    C->>G: begin_turn / check caps
+    Note over C,A: Phase 1 subscription agents, then Phase 2 tick agents
+    loop each acting agent
+        C->>G: check()
+        C->>A: act(projection, recent_events)
+        A->>A: ContextBuilder assembles prompt
+        A->>R: for_profile(model_profile)
+        R-->>A: small model -> typed event
+        A-->>C: Event (kind in may_emit)
+        C->>G: record_call(tokens, cost)
+        C->>L: append(event)
+        C->>O: consume(event) -> ViewDiff
+        Note over C: notify_subscribers queues agents for NEXT tick
+    end
+    C->>L: maybe snapshot every N
+```
+
 ```text
  0. step(n_ticks=N): repeat the tick body N times (two-clock: wall-clock maps to N).
  1. _tick(): turn += 1; governor.begin_turn(); governor.check() (turn/call/token caps).

docs/blog/engine-architecture.md

@@ -68,6 +68,15 @@ The window is capped at 8 events to stay within small-model context budgets.
 This is event sourcing plus CQRS in its simplest form: one write side (the ledger),
 many read sides (each agent's memory projection, the UI's stage view, the stats panel).
 
+```mermaid
+flowchart LR
+    Agents --> L[("Append-only Ledger<br/>one write side")]
+    L --> M1["each agent's memory"]
+    L --> M2["stage view · UI"]
+    L --> M3["stats panel"]
+    L --> M4["judge analysis"]
+```
+
 ---
 
 ## The Context Builder: Prompt Assembly as a Separate Concern