docs: arquitectura con seguridad en CLAUDE.md + SECURITY.md dedicado

CLAUDE.md: diagrama Mermaid reemplaza file-tree desactualizado; incluye
todos los componentes actuales con controles de seguridad anotados.
Stack actualizado con aiohttp y Docker. Referencia a SECURITY.md.

SECURITY.md (nuevo): diagrama defensa en profundidad (7 vectores → controles),
diagrama vault.py v3 con capas KEK+DEK, diagrama de ciclo de vida de
credenciales (secuencia), tabla de controles transversales y limitaciones.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

CLAUDE.md

@@ -47,16 +47,55 @@ Toda llamada a `logger.*()` con datos externos pasa por acá.
 
 ## Arquitectura
 
+```mermaid
+graph TD
+    ABOGADO["👤 Abogado"]
+    TG(["Telegram API"])
+    CSJ(["apps.csj.gov.py · PJ"])
+
+    subgraph VPS ["VPS — Ubuntu 22.04"]
+        NGX["🔐 Nginx\nSSL · 30 r/s webhook · 10 r/min health\nX-Content-Type-Options · X-Frame-Options"]
+
+        subgraph DOCKER ["🐳 Docker container"]
+            WH["POST /webhook\n→ 404 si token inválido\nsecrets.compare_digest"]
+            HL["GET /health\npúblico: status + timestamp"]
+            HH["GET /health/history\nBearer auth · chat_id enmascarado SHA256"]
+            ONB["Onboarding FSM · 8 pasos\ninvite atómico UPDATE WHERE usado=0\ntiming ≥800ms · compare_digest"]
+            CMD["Comandos\n/notif · /exp · /pdf · /estado · /ayuda"]
+            POLLER["Poller · APScheduler\nmulti-tenant · lun-vie 7-18h"]
+            VAULT["🔐 vault.py\nPBKDF2-SHA256 600k iter\nDEK 32B por cifrado · envelope v3"]
+            CFG["🔐 config.py · Settings\nenv vars borradas post-init"]
+            SCRUB["scrub()\ntodo dato externo a logs\npasa por acá antes de escribir"]
+        end
+
+        DB[("pasante.db\ntenants · audit_log\ninvite_codes · migrations")]
+        SNAP["snapshot_{chat_id}.json\ndiff notificaciones por tenant"]
+    end
+
+    ABOGADO <-->|"HTTPS"| TG
+    TG -->|"HTTPS + X-Secret-Token"| NGX
+    NGX --> WH
+    NGX --> HL
+    NGX --> HH
+    WH --> ONB
+    WH --> CMD
+    ONB -->|"cifra credenciales"| VAULT
+    VAULT <-->|"credentials_enc"| DB
+    CMD --> DB
+    HH -->|"audit_log — chat_id enmascarado"| DB
+    POLLER -->|"HTTPS + Bearer + usuario-rol:16"| CSJ
+    CSJ -->|"notificaciones JSON"| POLLER
+    POLLER --> SNAP
+    POLLER -->|"alertas"| TG
+    POLLER -->|"descifra por tenant"| VAULT
+    CFG -.->|"configura"| VAULT
+    CFG -.->|"configura"| POLLER
+
+    classDef secure fill:#fef2f2,stroke:#991b1b,color:#450a0a
+    class NGX,VAULT,CFG,SCRUB secure
 ```
-main.py               ← entrypoint, arranca bot + poller en paralelo
-config.py             ← Settings via pydantic-settings (ÚNICA fuente de config)
-csj_client.py         ← HTTP client del PJ (login + notificaciones, read-only)
-poller.py             ← loop de polling + diff + dispara alertas
-telegram_bot.py       ← envía mensajes y maneja /comandos básicos
-storage.py            ← snapshot en JSON local (sin DB por ahora)
-utils/
-  sanitize.py         ← credential_scrubber() — NUNCA loggear sin pasar por acá
-```
+
+Ver [SECURITY.md](SECURITY.md) para el diagrama de arquitectura de seguridad detallado.
 
 ---
 
@@ -68,11 +107,13 @@ utils/
 | HTTP client | `httpx` async |
 | Bot | `python-telegram-bot v21` async |
 | Scheduler | `APScheduler 3` |
-| Cifrado | `cryptography` (Fernet) |
+| Cifrado | `cryptography` (Fernet + PBKDF2) |
+| HTTP server | `aiohttp>=3.9` (health check + webhook) |
 | Config | `pydantic-settings` |
 | Logging | `structlog` (JSON en prod, ConsoleRenderer en dev) |
+| Infraestructura | Docker + docker-compose |
 
-Sin Playwright. Sin Postgres. Sin Redis. Sin LLM. Sin Docker por ahora (opcional).
+Sin Playwright. Sin Postgres. Sin Redis. Sin LLM.
 
 **No introducir librerías fuera de esta lista sin justificación explícita.**