docs: add Mermaid architecture diagrams

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