diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index f1596e5..f074213 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -26,26 +26,11 @@ worker processes open it independently.
## Request path
-```mermaid
-flowchart LR
- C[Client] -->|Bearer key| A[api.py ThreadingHTTPServer]
- A --> K{auth.py HMAC lookup}
- K -->|missing, invalid, revoked| E401[401]
- K -->|tenant from key row| R{per-tenant token bucket}
- R -->|empty| E429[429]
- R --> T[Tracer span http.request]
- T --> AG[AgentRuntime.ask react_agent.ReActAgent]
- AG -->|every model call| GW[llm_gateway.Gateway for this tenant]
- GW -->|injection check, PII redaction, cache, output policy| P[GroundedPolicyProvider]
- GW -->|blocked| E422[422]
- AG -->|tool: search_knowledge_base| KB[KnowledgeBase tenant index only]
- KB --> HR[hybrid_rag.HybridRetriever BM25 + TF-IDF + HNSW]
- HR --> HN[ann_vector_search_library.HNSW]
- AG -->|tool: calculator| CALC[react_agent CalculatorTool]
- AG -->|optional schema| CG[constrained_generation_library]
- T --> TS[(spans table)]
- AG --> RESP[answer, citations, grounded, sources, trace_id]
-```
+
+
+
+
+Legend: amber = entry points and external systems, indigo = core logic, green = data and state, blue = validation and control, grey = observability and outputs.
1. `api.py` reads the `Authorization: Bearer` (or `X-API-Key`) header and calls
`KeyStore.verify`. The tenant comes from the stored key row. Request bodies never carry
@@ -66,41 +51,15 @@ flowchart LR
## Durable job lifecycle
-```mermaid
-stateDiagram-v2
- [*] --> queued: POST /v1/jobs
- queued --> running: claim (BEGIN IMMEDIATE) lease_owner, lease_expires, lease_token+1
- running --> running: heartbeat renews lease
- running --> running: step done: ledger row + board snapshot (one transaction, fenced by lease_token)
- running --> running: lease expired, worker dead: another worker claims, token+1, resumes from board
- running --> succeeded: report step checkpointed
- running --> failed: critic rejection, step error, or attempts > max_attempts
- succeeded --> [*]
- failed --> [*]
-```
-
-```mermaid
-sequenceDiagram
- participant API
- participant DB as SQLite
- participant WA as Worker A
- participant WB as Worker B
- API->>DB: INSERT job (queued)
- WA->>DB: claim: token=1, expires=now+L
- WA->>DB: save plan (blackboard snapshot)
- loop each step
- WA->>DB: record attempt (q1)
- WA->>WA: Orchestrator.attempt_subtask
- WA->>DB: save spans
- WA->>DB: ledger row q1 + board (only if owner and token=1)
- end
- Note over WA: SIGKILL. Heartbeats stop.
- WB->>DB: claim fails until expires < now
- WB->>DB: claim: token=2
- WB->>WB: Blackboard.restore(board)
- WB->>DB: record attempt (next incomplete step)
- WB->>DB: ledger rows, then status=succeeded
-```
+
+
+
+
+Legend: amber = entry points and external systems, indigo = core logic, green = data and state, blue = validation and control, grey = observability and outputs.
+
+
+
+
### Tables
diff --git a/docs/architecture/job-recovery.mmd b/docs/architecture/job-recovery.mmd
new file mode 100644
index 0000000..ee2e1db
--- /dev/null
+++ b/docs/architecture/job-recovery.mmd
@@ -0,0 +1,20 @@
+sequenceDiagram
+ participant API
+ participant DB as SQLite
+ participant WA as Worker A
+ participant WB as Worker B
+ API->>DB: INSERT job (queued)
+ WA->>DB: claim: token=1, expires=now+L
+ WA->>DB: save plan (blackboard snapshot)
+ loop each step
+ WA->>DB: record attempt (q1)
+ WA->>WA: Orchestrator.attempt_subtask
+ WA->>DB: save spans
+ WA->>DB: ledger row q1 + board (only if owner and token=1)
+ end
+ Note over WA: SIGKILL. Heartbeats stop.
+ WB->>DB: claim fails until expires < now
+ WB->>DB: claim: token=2
+ WB->>WB: Blackboard.restore(board)
+ WB->>DB: record attempt (next incomplete step)
+ WB->>DB: ledger rows, then status=succeeded
diff --git a/docs/architecture/job-recovery.svg b/docs/architecture/job-recovery.svg
new file mode 100644
index 0000000..732dd74
--- /dev/null
+++ b/docs/architecture/job-recovery.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/architecture/job-states.mmd b/docs/architecture/job-states.mmd
new file mode 100644
index 0000000..f793c26
--- /dev/null
+++ b/docs/architecture/job-states.mmd
@@ -0,0 +1,18 @@
+stateDiagram-v2
+ direction TB
+ classDef edge fill:#F59E0B,stroke:#1E293B,color:#1E293B,stroke-width:1px;
+ classDef core fill:#6366F1,stroke:#1E293B,color:#ffffff,stroke-width:1px;
+ classDef data fill:#10B981,stroke:#1E293B,color:#ffffff,stroke-width:1px;
+ classDef control fill:#0EA5E9,stroke:#1E293B,color:#ffffff,stroke-width:1px;
+ classDef obs fill:#CBD5E1,stroke:#1E293B,color:#1E293B,stroke-width:1px;
+ [*] --> queued: POST /v1/jobs
+ queued --> running: claim, lease_token + 1
+ running --> running: heartbeat, fenced step commit, reclaim after lease expiry
+ running --> succeeded: report checkpointed
+ running --> failed: rejected or out of attempts
+ succeeded --> [*]
+ failed --> [*]
+ class queued data
+ class running core
+ class succeeded obs
+ class failed edge
diff --git a/docs/architecture/job-states.svg b/docs/architecture/job-states.svg
new file mode 100644
index 0000000..3dcde91
--- /dev/null
+++ b/docs/architecture/job-states.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/architecture/request-path.mmd b/docs/architecture/request-path.mmd
new file mode 100644
index 0000000..d280999
--- /dev/null
+++ b/docs/architecture/request-path.mmd
@@ -0,0 +1,33 @@
+flowchart LR
+ classDef edge fill:#F59E0B,stroke:#1E293B,color:#1E293B,stroke-width:1px;
+ classDef core fill:#6366F1,stroke:#1E293B,color:#ffffff,stroke-width:1px;
+ classDef data fill:#10B981,stroke:#1E293B,color:#ffffff,stroke-width:1px;
+ classDef control fill:#0EA5E9,stroke:#1E293B,color:#ffffff,stroke-width:1px;
+ classDef obs fill:#CBD5E1,stroke:#1E293B,color:#1E293B,stroke-width:1px;
+ subgraph Edge["HTTP edge (api.py)"]
+ direction TB
+ C["Client"]:::edge -->|Bearer key| A["api.py ThreadingHTTPServer"]:::edge
+ A --> K["auth.py: HMAC key lookup 401 if missing or revoked"]:::control
+ K -->|tenant from key row| R["per-tenant token bucket 429 when empty"]:::control
+ end
+ subgraph Agent["Agent runtime"]
+ direction TB
+ T["Tracer span http.request"]:::obs --> AG["AgentRuntime.ask ReActAgent loop"]:::core
+ AG --> RESP["answer, citations, grounded, trace_id"]:::obs
+ end
+ subgraph Calls["Model, tools and retrieval"]
+ direction TB
+ GW["llm_gateway.Gateway 422 when blocked"]:::control --> P["GroundedPolicyProvider"]:::edge
+ CALC["CalculatorTool"]:::core ~~~ CG["constrained_generation optional schema"]:::control
+ KB["KnowledgeBase tenant index only"]:::data --> HR["HybridRetriever BM25 + TF-IDF + HNSW"]:::core
+ HR --> HN["ann_vector_search HNSW"]:::data
+ P ~~~ CALC
+ CG ~~~ KB
+ end
+ subgraph State["State"]
+ direction TB
+ TS[("spans table")]:::data
+ end
+ Edge -->|allowed request| Agent
+ Agent -->|model calls, tools, search| Calls
+ Agent -.->|spans| State
diff --git a/docs/architecture/request-path.svg b/docs/architecture/request-path.svg
new file mode 100644
index 0000000..549f475
--- /dev/null
+++ b/docs/architecture/request-path.svg
@@ -0,0 +1 @@
+
\ No newline at end of file