docs: add Mermaid architecture diagrams

docs/contracts/workflow-observable-baseline.md

@@ -8,6 +8,28 @@ Changing an expectation in this baseline is a behavior change and requires an ex
 decision. Moving code between Workflow core, Disambiguation, Memory, and Evidence must keep the
 baseline green without weakening its assertions.
 
+```mermaid
+stateDiagram-v2
+    [*] --> F1
+    state "F1 Clarification" as F1
+    state "F2 Memory" as F2
+    state "F3 Question rewrite" as F3
+    state "F4 Evidence" as F4
+    state "F5 Schema linking" as F5
+    state "F6 SQL drafting" as F6
+    state "F7 Validation" as F7
+    state "F8 Promotion" as F8
+    F1 --> F2
+    F2 --> F3
+    F3 --> F4
+    F4 --> F5
+    F5 --> F6
+    F6 --> F7
+    F7 --> F8
+    F7 --> F6: correction
+    F8 --> [*]
+```
+
 ## Automated seams
 
 ### Pi gate

docs/contracts/workspace-evidence-v3.md

@@ -5,6 +5,21 @@ workspace descriptor. Evidence is optional: a valid v3 descriptor without it rem
 When present, `evidence` is strict: it contains `source` and a defaulted strict `policy`; every
 source variant and the policy reject unknown keys.
 
+```mermaid
+flowchart LR
+    REGISTRY["Workspace registry"] --> DESCRIPTOR["Evidence descriptor"]
+    DESCRIPTOR --> FILESYSTEM["Filesystem adapter"]
+    DESCRIPTOR --> HTTP["HTTP adapter"]
+    DESCRIPTOR --> S3["S3 adapter"]
+    FILESYSTEM --> CURATED["Curated markdown"]
+    HTTP --> CURATED
+    S3 --> CURATED
+    CURATED --> VALIDATE["Validate schema\nand provenance"]
+    VALIDATE --> PREPROCESS["Preprocess pinned\nrevision"]
+    PREPROCESS --> GENERATION["Versioned generation"]
+    GENERATION --> ACTIVE["Active corpus"]
+```
+
 ## Filesystem source
 
 A filesystem source uses the exact URI `<workspace.id>/evidence`. `patterns` is a nonempty list of

docs/contracts/workspace-preprocessing-cli.md

@@ -2,6 +2,18 @@
 
 `tht` is the only supported host entrypoint for workspace preprocessing.
 
+```mermaid
+flowchart LR
+    OP["Operator"] --> INVOKE["tht workspace preprocess"]
+    INVOKE --> VALIDATE["Validate descriptor\nand paths"]
+    VALIDATE --> SOURCE["Read source and\ncurated workspace"]
+    SOURCE --> NORMALIZE["Normalize and chunk"]
+    NORMALIZE --> INDEX["Update vector and\nBM25 indexes"]
+    INDEX --> VERIFY["Verify collection\nand generation"]
+    VERIFY --> READY["Generation ready"]
+    VALIDATE -->|"invalid"| STOP["Exit with diagnostic"]
+```
+
 ## Invocation
 
 ```text