docs: render architecture and example flows as mermaid diagrams (#152)

Add an Architecture section to the root README describing the
source -> state -> sink spine, with a mermaid overview plus a small
diagram per core module. Convert the ASCII diagrams in the
fooddelivery and sinkflow examples and the statemachine handler-step
README to mermaid, and expand the fooddelivery narrative to spell out
the parallel Fulfillment/Watchdog regions and the compensation saga.

Documentation only; no code or API changes.

Signed-off-by: Joshua Temple <joshua.temple@stablekernel.com>

Author: joshua-temple

README.md

@@ -40,6 +40,57 @@ in the documentation site:
 
 ### **[stablekernel.github.io/crucible](https://stablekernel.github.io/crucible/)**
 
+## Architecture
+
+Three core modules form the **ingest → drive → emit** spine: `source` brings
+events in, `state` decides what happens, and `sink` fans the resulting effects
+out. Each is a thin seam you can adopt on its own, and none imports another.
+
+```mermaid
+flowchart LR
+    streams[(external streams)] -->|source| engine[state engine]
+    engine -->|sink| destinations[(destinations)]
+```
+
+### `state` — the statechart engine
+
+A stdlib-only statechart engine with no injected IO. Machines are pure: a `Fire`
+folds an event into a new instance and emits effects as plain data, leaving
+persistence and dispatch to the host.
+
+```mermaid
+stateDiagram-v2
+    [*] --> Idle
+    Idle --> Working: Start [guard]
+    Working --> Working: Progress / emit effect
+    Working --> Done: Finish
+    Working --> Idle: Reset
+    Done --> [*]
+```
+
+### `source` — the ingress seam
+
+Consumes external streams (Kafka, JetStream, Redis, CDC, and more) and drives a
+machine, with the ack tied to a durable transition so redelivery is safe.
+
+```mermaid
+flowchart LR
+    stream[(stream)] --> decode[decode / codec] --> route["route to (key, event)"] --> fire["Fire on instance"] --> commit[durable commit] --> ack[ack]
+```
+
+### `sink` — the egress seam
+
+Fans emitted effects out to many destinations through a `Manifold`,
+fire-and-forget; one outlet's failure never stops the rest.
+
+```mermaid
+flowchart LR
+    effect[emitted effect] --> manifold[Manifold]
+    manifold --> a[destination A]
+    manifold --> b[destination B]
+    manifold --> c[destination C]
+```
+
 ## Modules
 
 Each module is independently versioned (per-module SemVer) and carries its own

examples/fooddelivery/README.md

@@ -14,21 +14,40 @@ into your own domain.
 
 An `Order` moves through these stages:
 
+```mermaid
+stateDiagram-v2
+    [*] --> Placed
+    Placed --> Authorizing: Submit
+    Authorizing --> Rejected: decline
+    Authorizing --> Active: success [admit guard]
+
+    state Active {
+        [*] --> Cooking
+        Cooking --> AwaitingCourier
+        AwaitingCourier --> EnRoute
+        --
+        [*] --> OnTime
+        OnTime --> Overdue: after(SLA)
+    }
+
+    Active --> Settling: DroppedOff
+    Active --> Refunding: Cancel
+    Settling --> Delivered: always
+    Refunding --> Canceled: refund result
+
+    Rejected --> [*]
+    Delivered --> [*]
+    Canceled --> [*]
 ```
-Placed --Submit--> Authorizing
-  Authorizing invokes the payment "authorize" service.
-    on decline --> Rejected (terminal)
-    on success [admit guard] --> Active
-Active  (parallel superstate)
-  ├─ Fulfillment region: Cooking --> AwaitingCourier --> EnRoute
-  │     Cooking supervises the kitchen actor (it plates the meal).
-  │     EnRoute  supervises the courier actor (it delivers).
-  └─ Watchdog region:    OnTime --after(SLA)--> Overdue (records a breach)
-  Active --DroppedOff--> Settling   (courier completion exits the parallel state)
-  Active --Cancel-----> Refunding   (the compensation saga)
-Settling --always--> Delivered (terminal)   (captures the payment hold)
-Refunding invokes "refund"; on its result --> Canceled (terminal)
-```
+
+`Authorizing` invokes the payment `authorize` service. `Active` is a parallel
+superstate with two concurrent regions: a **Fulfillment** region
+(`Cooking → AwaitingCourier → EnRoute`, where `Cooking` supervises the kitchen
+actor and `EnRoute` the courier actor) and a **Watchdog** region (`OnTime`, which
+trips to `Overdue` and records a breach `after(SLA)`). `DroppedOff` exits the
+parallel state into `Settling`, which captures the payment hold and always lands
+in `Delivered`. `Cancel` routes into `Refunding`, the compensation saga, which
+invokes `refund` and ends in `Canceled`.
 
 Run it through the host `Rig` (the example's wiring of the Scheduler, ServiceRunner,
 and ActorSystem); see `rig.go`, or embed the pieces directly.

examples/sinkflow/README.md

@@ -7,11 +7,12 @@ one `log/slog` logger. It is the proof that `state`, `sink`, and `telemetry`
 compose through the [`sink/bridge`](../../sink/bridge) seam without any core
 importing another.
 
-```
-order machine ──(bridge.Middleware)──▶ Manifold ──┬─▶ analytics  (delivered)
-   Fire(Prepare)                                   ├─▶ audit      (delivered)
-   Fire(Dispatch)  ── warehouse rejects ──▶        └─▶ warehouse  (fails on Dispatch)
-   Fire(Deliver)
+```mermaid
+flowchart LR
+    M["order machine<br/>Fire(Prepare / Dispatch / Deliver)"] -->|bridge.Middleware| MAN[Manifold]
+    MAN --> A["analytics<br/>(delivered)"]
+    MAN --> AU["audit<br/>(delivered)"]
+    MAN --> W["warehouse<br/>(rejects Dispatch)"]
 ```
 
 What the test asserts (`sinkflow_test.go`), all hermetic and deterministic:

source/statemachine/README.md

@@ -23,8 +23,10 @@ sub.Receive(ctx, h) // each message: route → load → Fire → emit → persis
 
 The handler runs one declared step:
 
-    decode → route to (key, event) → load instance → Fire(event) →
-        emit effects → persist new state → ack
+```mermaid
+flowchart LR
+    decode --> route["route to (key, event)"] --> load["load instance"] --> fire["Fire(event)"] --> emit["emit effects"] --> persist["persist new state"] --> ack
+```
 
 The ack comes only after a successful durable `Store.Save`
 (ack-after-durable-commit).