docs: add Mermaid architecture diagrams

docs/architecture/authentication.md

@@ -5,6 +5,20 @@ surface is one CLI, `tht`; there is no separate authentication executable. The b
 opaque browser sessions and authorization, while `tht` owns protected configuration and local-user
 files.
 
+```mermaid
+flowchart TB
+    BROWSER["Browser"] --> BOUNDARY["Authentication boundary"]
+    BOUNDARY --> LOCAL["Local users\nArgon2id hashes"]
+    BOUNDARY --> OIDC["OIDC provider\nAuthorization Code PKCE"]
+    OIDC --> GROUPS["Groups claim\nexact mapping"]
+    LOCAL --> PRINCIPAL["Thoth principal"]
+    GROUPS --> PRINCIPAL
+    PRINCIPAL --> ROLES["Roles"]
+    ROLES --> PERMISSIONS["Permissions"]
+    PERMISSIONS --> ROUTES["Protected routes"]
+    SECRETS["Mounted secret bundle"] -.-> BOUNDARY
+```
+
 ## Configuration and trust boundaries
 
 The installation descriptor points to an operator-controlled authentication directory. It contains

docs/architecture/overview.md

@@ -10,6 +10,18 @@ ThothII è un **datamart builder human-in-the-loop**: trasforma una domanda in l
 L'autenticazione di produzione usa local oppure OIDC generico; il solo CLI operatore è tht.
 Per sessioni, ruoli, gruppi, diagnostica e ripristino vedere la [documentazione autenticazione](authentication.md).
 
+```mermaid
+flowchart LR
+    USER["Reviewer"] --> FE["Frontend\nReact and SSE"]
+    FE --> BE["Backend\nFastify"]
+    BE --> PI["Pi\nRPC per sessione"]
+    PI --> THT["tht and harness\nworkflow and persistence"]
+    THT --> DWH["DWH\nread only"]
+    THT --> EVIDENCE["Evidence\ncurated corpus"]
+    EVIDENCE --> THT
+    THT --> FE
+```
+
 ## I tre progetti indipendenti
 
 ```

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

docs/disambiguazione-iniziale.md

@@ -6,6 +6,23 @@ Il principio architetturale è **human-in-the-middle**: il modello propone inter
 
 La procedura è definita nella skill canonica [tht-sessione](../harness/.pi/skills/tht-sessione/SKILL.md), soprattutto nelle sezioni F1 e F2, ed è applicata dai widget in [tht-gate.js](../harness/.pi/extensions/tht-gate.js).
 
+```mermaid
+stateDiagram-v2
+    [*] --> DETECT
+    state "Detect ambiguity" as DETECT
+    state "Build reviewer options" as PROPOSE
+    state "Ask with reviewer_select" as ASK
+    state "Multiple valid answers" as MULTI
+    state "Record accepted decision" as ACCEPTED
+    DETECT --> PROPOSE: ambiguity found
+    DETECT --> ASK: safe default unavailable
+    PROPOSE --> ASK
+    ASK --> ACCEPTED: one option selected
+    ASK --> MULTI: multiple answers valid
+    MULTI --> ACCEPTED
+    ACCEPTED --> [*]
+```
+
 ## Dove avviene la disambiguazione
 
 La disambiguazione iniziale attraversa quattro passaggi distinti:

docs/gestione-memory.md

@@ -6,6 +6,16 @@ Questo documento descrive l'organizzazione attuale delle memory nel workflow Tho
 
 Una memory è conoscenza di dominio riutilizzabile tra domande. Non è una copia dello schema-linking di una singola domanda.
 
+```mermaid
+flowchart TB
+    CLARIFY["F1 concept clarified"] --> REVIEW["F8 reviewer review"]
+    REVIEW -->|"accepted"| REGISTRY["registry.jsonl"]
+    REVIEW -->|"declined"| LOCAL["Session decision only"]
+    REGISTRY --> VECTOR["Qdrant semantic index"]
+    VECTOR --> FUTURE["Future F2 retrieval"]
+    FUTURE --> PROPOSAL["Reviewer proposal"]
+```
+
 ```text
 F1: chiarimento di un concetto
         │

docs/installazione-docker-4-contesti.md

@@ -11,6 +11,20 @@ ThothII usa una topologia Compose unica:
 Qdrant e Ollama embedding sono servizi interni obbligatori del progetto Compose. Restano esterni solo DWH e LLM. Il modello fissato è `qwen3-embedding:0.6b` con 1024 dimensioni e distanza
 coseno; `embedding-model-init` lo prepara prima dell'avvio di `core`.
 
+```mermaid
+flowchart TB
+    INSTALL["Installation descriptor"] --> CONTEXT{Context}
+    CONTEXT --> LOCAL["Local\nCompose local"]
+    CONTEXT --> SERVER["Server\nCompose server"]
+    CONTEXT --> SESSION["Session server\noperator services"]
+    CONTEXT --> AUTH["Auth runtime\nprojection services"]
+    LOCAL --> BUNDLE["Common secret bundle"]
+    SERVER --> BUNDLE
+    SESSION --> BUNDLE
+    AUTH --> BUNDLE
+    BUNDLE --> SERVICES["Frontend, core, vector, embedding"]
+```
+
 ## Contratto sintetico di ownership
 
 | Componente | Ownership | Contratto operativo |

docs/skill-tht-sessione.md

@@ -5,4 +5,18 @@ La sorgente è [harness/.pi/skills/tht-sessione/SKILL.md](../harness/.pi/skills/
 
 Il blocco seguente viene incluso direttamente dal file sorgente durante il build MkDocs: non è una copia manuale.
 
+```mermaid
+flowchart LR
+    QUESTION["New question"] --> F1["F1 clarify"]
+    F1 --> F2["F2 memory"]
+    F2 --> F3["F3 rewrite"]
+    F3 --> F4["F4 evidence"]
+    F4 --> F5["F5 schema"]
+    F5 --> F6["F6 SQL"]
+    F6 --> F7["F7 validation"]
+    F7 --> F8["F8 promotion"]
+    F7 --> F6
+    F8 --> FINAL["Finalized session"]
+```
+
 --8<-- "harness/.pi/skills/tht-sessione/SKILL.md"