Actualizar documentación al stack nuevo

CLAUDE.md describía js/analisis.js y api/hf_proxy.php como vigentes; se
reescribe al flujo real (bundle TS → /api/interpret → RAG → modelo) y se añade
la sección de distribución del corpus.

README.md se marca como histórico: describe la entrega XAMPP del curso, cuyas
instrucciones de instalación ya no son válidas. No se reescribe entero porque
incluye la memoria académica del proyecto.

PLAN_MODERNIZACION.md refleja la auditoría del 2026-07-26: Fase 3 (RAG) pasa a
completa —búsqueda híbrida, rerank y corpus real de 6763 fragmentos— y se
detalla lo que sigue abierto en Fase 4 (Ragas sin implementar, split reservado,
human-in-the-loop).

.gitignore: books/* salvo el README, para que un formato nuevo de corpus no se
cuele por no estar listado; y .agents/ (tooling local del asistente).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

.gitignore

@@ -26,4 +26,28 @@ Temporary Items
 .apdisk
 
 
-.env
+.env
+backend/.env
+
+# Node / frontend
+node_modules/
+dist/
+
+# Python / backend (uv)
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+
+# Datos de ejecución (fuera del webroot): BD de usuarios e índice RAG
+instance/
+
+# Herramientas locales del asistente (skills instaladas con `hf skills add`), no son del proyecto
+.agents/
+
+# Corpus con licencia (no versionar contenido con copyright).
+# Se ignora todo el contenido de books/ salvo el README que documenta el layout de entrada,
+# para que un formato nuevo (.txt, .docx, texto extraido) no se cuele por no estar listado.
+books/*
+!books/README.md

CLAUDE.md

@@ -4,23 +4,36 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-Morphos is a veterinary diagnostic support tool — a single-page application (SPA) that performs real-time clinical pattern detection from lab values and optionally calls an AI model (HuggingFace or local Ollama) for clinical interpretation. It targets Canino and Felino patients.
+Morphos is a veterinary diagnostic support tool — a single-page application (SPA) that performs real-time clinical pattern detection from lab values and optionally calls an AI model (self-hosted medGemma, or Claude via the hybrid route) for clinical interpretation. It targets Canino and Felino patients.
 
-## Running the App
+## Migration in progress (see MIGRACION.md)
 
-This is a static frontend with a PHP proxy backend. No build step required.
+The project is being modernized from a static-JS + PHP-proxy app to:
+- **frontend/** — Vite + TypeScript. The vet-validated engine is ported to
+  `frontend/src/analisis.ts` with a Vitest regression suite (`frontend/tests/`).
+- **backend/** — FastAPI service (managed with **uv**). Structured AI output (Pydantic),
+  hybrid medGemma/Claude clients, RAG retrieval, and all security (auth guard on the AI
+  endpoint, rate limiting, locked CORS, secure sessions, security headers).
+- **evals/** — rigorous clinical eval harness with a CI gate (`.github/workflows/evals.yml`).
+- **RAG** — LlamaIndex + LanceDB; index built offline from `books/` and baked read-only
+  into the image (lives in `instance/`, outside the webroot).
 
-Serve it locally with PHP's built-in server from the project root:
-```bash
-php -S localhost:8000
-```
+El legacy `js/*.js` + `api/*.php` **ya se eliminó** (2026-07-26): `index.html` cargaba el bundle
+TS desde antes, así que eran código muerto. Todo el trabajo va en la estructura nueva. Ver
+`MIGRACION.md` para el estado completo y cómo ejecutar cada parte.
 
-Then open `http://localhost:8000` in a browser. The PHP proxy (`api/hf_proxy.php`) requires the API key in `api/.env`:
-```
-HF_API_KEY=<your_key>
+## Running the App
+
+### New stack (target)
+```bash
+make frontend-install && make frontend-build   # build the SPA → dist/
+make backend-sync && make dev                  # FastAPI on http://localhost:8000
 ```
+Secrets come from `backend/.env` (see `backend/.env.example`) or HF Space secrets — never
+from a file under the served root. For local AI, Ollama must run at
+`http://localhost:11434` with a medGemma model pulled.
 
-For local AI inference, Ollama must be running at `http://localhost:11434` with `medgemma:latest` pulled.
+No hay stack legacy: `php -S localhost:8000` y el proxy PHP ya no existen.
 
 ## Architecture
 
@@ -28,37 +41,45 @@ For local AI inference, Ollama must be running at `http://localhost:11434` with
 
 ```
 User form input
-  → analisis.js (real-time pattern detection, no server)
+  → analisis.ts (real-time pattern detection, no server)
   → UI updates (color-coded fields, pattern cards)
 
 User clicks "Análisis IA"
-  → ia.js (constructs prompt with patient data + flagged values)
-  → [HF route]    → api/hf_proxy.php → HF Space Gradio API (SSE response)
-  → [Local route] → Ollama chat completions API
-  → Display AI output in #salida-ia
+  → ia.ts (thin typed client, sends patient data + flagged values + CSRF token)
+  → POST /api/interpret (FastAPI: sesión + CSRF + rate limit)
+      → recuperación RAG (LanceDB, degrada a sin-RAG si no hay índice)
+      → prompt endurecido (app/ai/prompt.py)
+      → [ruta medgemma] → HF Space Gradio (texto libre) u Ollama (salida estructurada)
+      → [ruta claude]   → Anthropic SDK con tool use (salida estructurada validada)
+  → Render de la InterpretacionClinica en #salida-ia
 ```
 
 ### Key Files and Their Roles
 
-- **`js/analisis.js`** — Core engine (505 lines). Compares values against species-specific reference ranges, classifies severity (mild/moderate/severe), applies age/breed/sex adjustments, and identifies 50+ clinical patterns (anemia types, hepatic, renal, endocrine, etc.).
-- **`js/ia.js`** — AI abstraction layer. Builds the clinical prompt in Spanish, calls either HF Proxy or Ollama, and strips model-specific tokens from the response.
-- **`js/main.js`** — Orchestration: loads JSON data files, wires form events, triggers analysis, handles PDF export.
-- **`js/ui.js`** — Tab navigation (8 panels, 4 exam sub-tabs), swipe gestures, mobile/desktop field sync, collapsible panels.
-- **`js/pdf-parser.js`** — Client-side PDF extraction using PDF.js. 47 regex patterns to identify analytes in Spanish/English. Runs fully in the browser.
-- **`api/hf_proxy.php`** — PHP proxy that reads `api/.env`, forwards requests to HugginFace Space (`blackmistcode-morphos-medgemma.hf.space/gradio_api`), handles SSE polling, and returns `{text: ...}`.
-- **`data/valores_referencia.json`** — Reference ranges for 34 analytes per species.
-- **`data/alteraciones.json`** — 100+ clinical entities used to enrich AI prompts with etiologic context.
+- **`frontend/src/analisis.ts`** — Core engine (845 lines). Compares values against species-specific reference ranges, classifies severity (mild/moderate/severe), applies age/breed/sex adjustments, and identifies 50+ clinical patterns (anemia types, hepatic, renal, endocrine, etc.). Cubierto por 27 tests dorados en `frontend/tests/analisis.test.ts` — **es la red de regresión: no tocar sin ejecutarlos**.
+- **`frontend/src/ia.ts`** — Cliente tipado de `POST /api/interpret`; renderiza la salida estructurada (hallazgos, diferenciales con citas, banner de derivación). No construye el prompt (eso vive en el backend).
+- **`frontend/src/main.ts`** — Orquestación: carga los JSON, cablea eventos del formulario, dispara el análisis, exporta PDF.
+- **`frontend/src/ui.ts`** — Tab navigation (8 panels, 4 exam sub-tabs), swipe gestures, mobile/desktop field sync, collapsible panels.
+- **`frontend/src/pdf-parser.ts`** — Client-side PDF extraction using PDF.js. 47 regex patterns to identify analytes in Spanish/English. Runs fully in the browser.
+- **`backend/app/ai/hf_space.py`** — Cliente del HF Space (Gradio) donde vive medGemma. **Es la única ruta que NO da salida estructurada**: el Space devuelve texto libre, así que `limpiar_respuesta()` mantiene la limpieza de tokens del modelo y se envuelve en el campo `interpretacion`.
+- **`backend/app/ai/claude.py`** — Ruta Claude vía tool use forzado: el `input_schema` es el JSON Schema de `InterpretacionClinica`, así que valida contra Pydantic sin regex.
+- **`data/valores_referencia.json`** — Reference ranges for 90 analytes per species.
+- **`data/alteraciones.json`** — 78 clinical entities used to enrich AI prompts with etiologic context.
 
 ### AI Backend Configuration
 
-Stored in `localStorage`:
-- `mx-ia-backend`: `"hf"` (default) or `"local"`
-- `mx-ia-ollama-url`: custom Ollama endpoint
-- `mx-ia-ollama-model`: custom model name (default `medgemma:latest`)
+La selección de ruta se aplica **en el servidor** (`MORPHOS_IA_BACKEND_DEFECTO`: `medgemma` |
+`claude`), no en `localStorage` como en el legacy. Dentro de `medgemma`, si
+`MORPHOS_HF_SPACE_URL` está definida se usa el HF Space; si se vacía, cae a Ollama en
+`MORPHOS_MEDGEMMA_BASE_URL`. Ambas rutas aceptan hasta 4 imágenes (validadas en servidor:
+número, mime y tamaño).
 
-The HF route supports up to 4 images (vision model). The local route uses Ollama's OpenAI-compatible chat completions API, also with vision support.
+Para la ruta Claude el modelo por defecto es `claude-opus-5`. No cambiar a `claude-fable-5`:
+cuesta el doble, exige retención de datos de 30 días (incompatible con el posicionamiento de
+privacidad) y sus clasificadores pueden rechazar trabajo clínico legítimo con
+`stop_reason="refusal"` — ver el comentario en `backend/app/config.py`.
 
-### Pattern Detection Logic (`analisis.js`)
+### Pattern Detection Logic (`analisis.ts`)
 
 Severity thresholds are based on deviation from the reference range. Reference ranges are dynamically adjusted for:
 - **Age**: puppies, adults, seniors, geriatric (age in months)
@@ -69,7 +90,36 @@ The `analizarResultados()` function is called on every `input` event and returns
 
 ### CSS Notes
 
-Do not use `!important` — use specificity or cascade ordering instead. The stylesheet is `css/styles.css` (1796 lines). The desktop grid breakpoint is `>1100px`.
+Do not use `!important` — use specificity or cascade ordering instead. The stylesheet is `css/styles.css` (2742 lines). The desktop grid breakpoint is `>1100px`.
+
+### Distribución del corpus RAG
+
+Los libros con licencia y el índice **nunca** entran en git (`books/*` y `instance/` están en
+`.gitignore`). Viven en dos datasets **privados** del Hub, declarados en `scripts/hub.py` y en
+`backend/app/config.py`:
+
+| Artefacto | Repo | Tamaño | Para qué |
+|---|---|---|---|
+| Índice LanceDB | `blackmistcode/morphos-rag-index` | 70 MB | Lo consume la app; se hornea en la imagen |
+| PDFs originales | `blackmistcode/morphos-books` | 226 MB | Sólo para reingerir |
+
+```bash
+make ingest          # construye el índice desde books/ (local, requiere grupo rag)
+make publish-index   # sube instance/rag_index al dataset privado
+make fetch-index     # lo descarga (clon limpio, otra máquina, CI)
+make publish-books   # respalda los PDFs (no hace falta para desplegar)
+```
+
+Se usa la API de Python de `huggingface_hub`, **no el CLI `hf`**: en la versión instalada
+(1.16.1) el CLI devuelve código 1 aunque la operación vaya bien, por una incompatibilidad
+typer/click, y eso aborta cualquier Makefile o build.
+
+En Docker, `WITH_RAG=1` es el valor por defecto y los modelos (bge-m3 + bge-reranker-v2-m3,
+~6.4 GB) se hornean en `/opt/hf` con `HF_HUB_OFFLINE=1` en runtime, para que un fallo de red no
+degrade la recuperación en silencio. Si `instance/rag_index` no está en el contexto de build, la
+imagen lo descarga usando `HF_TOKEN` como **secreto de build** (nunca `--build-arg`, que quedaría
+en el historial de capas). Al arrancar, `_verificar_rag()` distingue en el log entre «RAG
+desactivado a propósito», «faltan dependencias» y «falta el índice».
 
 ### Coding notes
 

INTEGRACION_ANALIZADORES.md

@@ -0,0 +1,328 @@
+# Integración de analizadores de laboratorio en Morphos
+
+> Plan de integración para que los equipos de laboratorio envíen resultados directamente
+> a Morphos. Alcance actual: **Abaxis (VetScan), Scil/Horiba y Bionote Vcheck V200**.
+
+## Estado de implementación
+
+- ✅ **Fase 0 (contratos):** `backend/app/schemas_lab.py`, `backend/app/lab/mapeo.py` +
+  `data/lab_mapeos/generico.json` (387 códigos) + 33 pruebas.
+- ✅ **Fase 1 (MVP extremo-a-extremo):** auth de dispositivo (`security/device.py`), almacén
+  TTL (`lab/almacen.py`), endpoints `POST /api/lab/ingesta` + `GET /api/lab/resultados`
+  (`routers/lab.py`) + 6 pruebas; frontend `lab-import.ts` + `form-inject.ts` + campo de ID
+  de muestra en `index.html` + 5 pruebas; puente `bridge/` (transportes MLLP/serie,
+  adaptadores HL7 v2 y ASTM, reenviador con spool) + 8 pruebas. Verificado extremo-a-extremo:
+  HL7 del puente → validación + mapeo del backend (p. ej. `GLU 5.0 mmol/L → gluc 90.08`).
+- ✅ **Fase 2 (endurecimiento):** cola `GET /api/lab/pendientes` + UI "Ver resultados
+  recibidos"; persistencia SQLite opcional (`lab_persistir`, tabla `resultados_lab`, recarga
+  al arrancar); `no_mapeados` mostrados en el toast de importación; re-drenado periódico del
+  spool en el puente (`spool_reintento_s`). +3 pruebas backend.
+- ✅ **Fase 3 (listo para enchufar):** adaptadores por fabricante
+  `bridge/bridge/adaptadores/{abaxis,horiba,bionote}.py` + registro que selecciona el parser
+  por `fabricante`; tablas `data/lab_mapeos/{abaxis,horiba,bionote}.json` sembradas con los
+  códigos reales de cada panel; configuración **multi-equipo** (`MORPHOS_BRIDGE_INSTRUMENTOS`)
+  para varias máquinas en un puente. +3 pruebas backend, +5 puente.
+  **Pendiente sólo con hardware:** confirmar códigos OBX-3/R-3 y parámetros serie con una
+  captura real de cada equipo (ajuste = editar el JSON del fabricante).
+
+## Contexto
+
+Hoy el veterinario teclea los valores a mano (o importa un PDF). El objetivo es que los
+analizadores físicos alimenten los resultados directamente en la app. Los equipos objetivo
+(este alcance) son **Abaxis (VetScan), Scil/Horiba y Bionote Vcheck V200**. Decisiones del
+usuario: topología **nube + puente local**, **emparejamiento por ID de muestra/accesión**,
+**sólo entrada de resultados** (inbound).
+
+**IDEXX queda explícitamente fuera de alcance por ahora** (su ruta propietaria vía VetLab
+Station requeriría middleware/carpeta-drop y acceso al equipo real) — pero la capa de
+adaptadores se mantiene *pluggable* por fabricante para poder añadir IDEXX u otros más
+adelante sin rediseñar.
+
+Dos realidades condicionan el diseño:
+
+1. **Dos familias de protocolo entre los tres equipos.** Abaxis VetScan y Scil/Horiba
+   emiten **ASTM E1381/E1394 (LIS2-A2) sobre RS-232 / USB-serial** (el **Abaxis VS2 admite
+   ASCII Text / XML / ASTM**: se configura a **ASTM**, el formato que consume
+   `astm_generico.py`; ASCII/XML quedan como respaldo si un sitio no puede activar ASTM). El **Bionote
+   Vcheck V200 es estándar, no propietario: habla HL7 v2.6 PCD-01** (perfil IHE Patient
+   Care Device "Communicate PCD Data", es decir ORU^R01 sobre MLLP/TCP) **y POCT1-A**
+   (protocolo XML de punto de atención, CLSI POCT1-A2). Por tanto el puente necesita **dos
+   transportes**: `serial` (`pyserial`) para el ASTM de Abaxis/Horiba, y `mllp` (TCP) para
+   el HL7 v2.6 de Bionote. Un parser de registros ASTM se comparte entre Abaxis/Horiba; el
+   adaptador HL7 v2 (`hl7v2.py`) cubre Bionote con un manejo del perfil PCD-01 — **HL7 v2 ya
+   no es sólo "genérico/futuro", lo exige un equipo nombrado**. (POCT1-A queda como ruta
+   alternativa de Bionote, XML, diferida salvo que se prefiera sobre HL7.) Se necesita una
+   capa de adaptadores por analizador que normalice a un modelo de resultado canónico.
+2. **Morphos se despliega en HF Spaces** (un único puerto HTTP, sin alcance a la LAN, disco
+   efímero). El backend nunca debe abrir un listener TCP/MLLP crudo. En su lugar, un pequeño
+   **puente local** corre en la LAN de la clínica, habla el protocolo nativo de cada
+   analizador y reenvía los resultados normalizados al backend por HTTPS autenticado.
+
+La clave de unión en toda la app es la **clave de analito** (atributo `name` del input ==
+clave en `data/valores_referencia.json` == clave de entrada del motor de análisis; 90
+claves, idénticas para canino/felino). `frontend/src/pdf-parser.ts` ya codifica el
+vocabulario de alias + conversión de unidades y la ruta de inyección en el formulario
+(`aplicarAFormulario` → `evaluar()`); lo reutilizamos.
+
+```
+LAN de la clínica (bridge/)             HF Spaces (FastAPI, un puerto HTTP)
+ analizadores → adaptadores → normaliza --HTTPS--> POST /api/lab/ingesta  (API key equipo)
+   (HL7 MLLP / ASTM / serial)   Bearer key         GET  /api/lab/resultados (cookie sesión)
+                                                    almacén TTL en proceso (muestra_id → mapeado)
+                                              navegador consulta por ID de muestra → inyecta → evaluar()
+```
+
+Dos zonas de confianza, dos mecanismos de auth: **puente→backend** usa una **API key** de
+equipo (nunca la cookie del navegador); **navegador→backend** mantiene la cookie de sesión
++ CSRF existentes. El mapeo código→analito y la conversión de unidades ocurren **en el
+backend** (una única fuente de verdad, compartida por todo formato de entrada, testeable en
+pytest).
+
+## Alcance de este plan
+
+Las fases 0–1 (el MVP: contratos + extremo-a-extremo HL7 v2 / ASTM genérico → match por ID
+de muestra → autorrelleno del formulario) están totalmente especificadas. Los adaptadores
+por fabricante (fase 3) están estructurados pero cada uno depende de una captura del equipo
+real, que no puede hacerse sólo desde código.
+
+---
+
+## Backend
+
+### 1. Modelos canónicos — nuevo `backend/app/schemas_lab.py`
+Mantener los esquemas de lab fuera del ya enfocado `schemas.py`. Identificadores en español,
+mismas convenciones `str,Enum`/`Literal`/`Field`/`@field_validator` que `schemas.py`.
+
+- `ObservacionAnalizador`: `codigo_prueba: str` (código/nombre de prueba del fabricante,
+  crudo, sin mapear), `valor: str` (se mantiene como **string** en la ingesta — preserva
+  `"<0.1"`, `">1000"`, `"NEG"`, `"+++"`), `unidad: str = ""`, `rango_referencia`, `bandera`
+  (flag H/L de anormalidad, sólo informativo). `@field_validator` recorta + acota longitud.
+- `PacientePistas`: opcionales libres `nombre_mascota`, `especie_texto`, `raza`, `sexo`,
+  `edad_texto` (para prerrellenar `pt-*`, nunca por encima de lo que teclea el veterinario).
+- `ResultadoAnalizador` (una corrida de un instrumento): `muestra_id: str`
+  (`min_length=1, max_length=128` — la **clave de match**), `instrumento_id`,
+  `instrumento_modelo`, `fabricante`, `pistas_paciente: Optional[PacientePistas]`,
+  `observaciones: list[ObservacionAnalizador]`, `momento: datetime`,
+  `recibido_en` (default_factory ahora), `formato_origen: Literal["hl7v2","astm","json","manual"]`.
+- Extensibilidad hacia salida (outbound): añadir `DireccionMensaje(str,Enum) {entrada,salida}`
+  + `direccion = entrada` en el envelope, y un stub comentado `OrdenTrabajo` — reserva el
+  namespace `/api/lab/*` y el esquema de almacén para órdenes de trabajo sin construirlas.
+- Modelos de respuesta para el navegador: `ValorAnalito {clave, valor, unidad,
+  valor_original, unidad_original, es_semicuantitativo}` y `ResultadoMapeado {muestra_id,
+  instrumento_id, momento, analitos: dict[str, ValorAnalito], paciente: PacientePistas|None,
+  no_mapeados: list[str]}`. Esto es exactamente lo que inyecta el frontend.
+
+### 2. Capa de mapeo — nuevo paquete `backend/app/lab/` + datos `data/lab_mapeos/`
+Dirigida por datos, portada desde `frontend/src/pdf-parser.ts`; las claves de salida deben
+ser un subconjunto de las 90 claves canónicas (+ los nombres de select semicuantitativos
+`uri-*`).
+
+- `backend/app/lab/mapeo.py`:
+  - `mapear_observacion(obs, tabla)`: empareja `codigo_prueba` contra la tabla del fabricante
+    (código exacto primero, luego alias) → `clave` canónica (+ opcional `claveConv`).
+  - `convertir_unidad(clave, claveConv, valor_num, unidad)`: **port a Python de
+    `aplicarConversion` + `CONVERSIONES_UNIDADES`** (`pdf-parser.ts:107-186`) — factores
+    idénticos para que importación por PDF y por analizador coincidan.
+  - `parsear_valor(valor_str)`: port de `extraerValorYUnidad`/`parsearSemiCuantitativo`
+    (maneja `"<0.1"`, decimales con coma, `"NEG"`, `"+++"`→valores de opción `uri-*`);
+    descarta no-finitos / `<= 0` como el original.
+  - `mapear_resultado(res) -> ResultadoMapeado`: recorre observaciones, dedup primer-match-gana,
+    deriva % del diferencial de leucocitos desde absolutos + % de reticulocitos cuando sólo
+    hay absolutos (port del bloque de derivación en `parsearTextoLab`), recoge códigos
+    desconocidos en `no_mapeados`.
+- `data/lab_mapeos/generico.json` — tabla canónica sembrada de LOINC + las abreviaturas ya
+  presentes en las regex de `DEFS_ANALITOS`. Forma: `{ "clave": {"codigos": ["GLU","GLUC"],
+  "unidad_defecto": "mg/dL", "claveConv": "..."} }`.
+- `data/lab_mapeos/{abaxis,horiba,bionote}.json` — overrides por fabricante. El fabricante se
+  selecciona por `fabricante`/`instrumento_modelo`; desconocido → `generico.json`; código sin
+  match → genérico → `no_mapeados` (degradación elegante, refleja la filosofía RAG). Añadir un
+  equipo (incluido un futuro IDEXX) = soltar un nuevo JSON, no editar código. (Datos de
+  referencia no-PII; se cargan del lado del servidor vía `RAIZ_REPO / "data" / "lab_mapeos"`.)
+
+### 3. Almacén de resultados — nuevo `backend/app/lab/almacen.py`
+**Almacén TTL en proceso**, no SQLite, para el MVP. Justificación: el disco de HF Spaces es
+efímero, `instance/` se reconstruye al reiniciar, el Dockerfile corre **un único** worker de
+uvicorn, y los resultados son de vida corta (se emparejan en minutos). Singleton
+`AlmacenResultados` con `guardar`, `obtener`, `pendientes`, `_barrer` (TTL ~24 h + tope LRU),
+`threading.Lock`. La clave es `muestra_id.strip().lower()` normalizada en lectura y escritura.
+Importado como singleton de módulo por `routers/lab.py`; barrido periódico opcional vía una
+tarea `asyncio` en `_lifespan` (`main.py` ya lo señala como el sitio para tareas de fondo).
+- Durabilidad opcional (fase 2, tras `lab_persistir=False`): añadir una tabla `resultados_lab`
+  al `_ESQUEMA` de `db.py` y doble-escritura vía el patrón `_conexion()` existente. OFF por
+  defecto — sólo tiene sentido con un volumen persistente. Documentar el trade-off.
+
+### 4. Endpoints — nuevo `backend/app/routers/lab.py`, registrar en `main.py`
+Registrar como los demás: `from .routers import auth, interpret, lab, papers` +
+`app.include_router(lab.router, prefix="/api")`.
+
+- **`POST /api/lab/ingesta`** (puente → backend). Firma como `interpret.py`:
+  `request: Request` primero, `cuerpo: ResultadoAnalizador`,
+  `_disp = Depends(verificar_dispositivo)` (nuevo; §Seguridad). **Sin**
+  `usuario_actual`/`verificar_csrf` (puente headless, sin cookie).
+  `@limiter.limit(obtener_config().limite_lab_ingesta)` (p. ej. `"120/minute"`, ráfagas).
+  Ejecuta `mapear_resultado` → `almacen.guardar` → devuelve `{ok, muestra_id,
+  analitos_mapeados, no_mapeados}`. Rechaza `observaciones` vacías/desmesuradas con
+  `HTTPException(422, "…español")`.
+- **`GET /api/lab/resultados`** (navegador → backend). `request: Request`,
+  `muestra: str = Query(..., min_length=1, max_length=128)`,
+  `_sesion = Depends(usuario_actual)`, `@limiter.limit(...limite_lab_consulta)` (p. ej.
+  `"60/minute"`). Devuelve el `ResultadoMapeado` más reciente para `muestra` o `404` "No hay
+  resultados para esa muestra todavía."
+- **`GET /api/lab/pendientes`** (opcional, fase 2, auth de sesión): recientes sin reclamar
+  `{muestra_id, instrumento_id, momento}` para una UI de cola de selección.
+
+**Polling, no SSE**: el stack es request/response, HF Spaces complica el SSE de larga vida, y
+la UX es "arma un ID de muestra, espera segundos." El frontend consulta `GET …?muestra=<id>`
+cada ~3 s durante ~90 s; 404 = seguir esperando, 200 = aplicar. Cero infra de servidor nueva.
+(SSE anotado como optimización futura.)
+
+### 5. Seguridad — `backend/app/config.py`, `backend/app/security/`
+- Nueva dependencia `verificar_dispositivo(request, authorization: Header)` en `authz.py` (o
+  hermano `security/device.py`): `hmac.compare_digest` de tiempo constante de un token Bearer
+  contra las keys configuradas (misma disciplina que `verificar_password`).
+- Añadidos en `config.py`: `lab_api_keys: list[str]` (desde `MORPHOS_LAB_API_KEYS`; soporta
+  rotación/por-clínica), `limite_lab_ingesta`, `limite_lab_consulta`, `lab_persistir`.
+  `validar_prod()` exige ≥1 key cuando la ingesta de lab está activada. La ingesta es
+  sin-cookie/sin-CSRF **por diseño** — la API key es la auth, sólo por HTTPS.
+- **No aflojar CORS ni CSP.** El puente es servidor-a-servidor (CORS gobierna navegadores); el
+  navegador sólo llama a `/api/lab/*` del mismo origen con la cookie existente, así que
+  `connect-src 'self'` ya lo cubre — sin nueva cabecera de navegador, sin cambio de preflight.
+- Los valores del analizador son **datos, nunca instrucciones**: pueblan inputs numéricos y
+  llegan al modelo sólo como los mismos `hallazgos` estructurados que ya produce el motor
+  determinista. Acotar todas las longitudes de string en `schemas_lab.py`.
+
+---
+
+## Frontend — nuevo `frontend/src/lab-import.ts`, ediciones a `index.html` + `main.ts`
+Reflejar `pdf-parser.ts` exactamente (clave de unión = `name` de analito; `evaluar()` es el
+disparador reactivo). El mapeo es del lado del servidor, así que el lado TS es delgado.
+
+- `frontend/src/lab-import.ts` exporta `inicializarImportLab(evaluar)`:
+  - Input de ID de muestra + botón "Importar del analizador"; un lector de código de barras
+    simplemente teclea en el campo + Enter. Al armar, consulta `GET
+    /api/lab/resultados?muestra=<id>` con `fetch(..., {credentials:'include'})` cada 3 s hasta
+    ~90 s.
+  - En 200: inyecta `ResultadoMapeado.analitos` reusando la lógica de inyección —
+    `document.querySelector('[name="${clave}"]').value = valor` para números, match de opción
+    para selects `uri-*`, luego `evaluar()`; aplica las pistas `paciente` a `pt-*` como
+    `aplicarPacienteAFormulario`. **Refactor pequeño recomendado:** extraer
+    `aplicarAFormulario` + `aplicarPacienteAFormulario` de `pdf-parser.ts` a un
+    `frontend/src/form-inject.ts` compartido e importar desde ambos, evitando duplicación.
+    Reusar `mostrarToast` para "N valores importados del analizador."
+  - Marcar los campos importados con un resaltado transitorio para que el veterinario vea qué
+    cambió; el toast debe indicar que los valores se autorrellenaron y **deben verificarse**
+    (refuerza la postura de seguridad existente `requiere_derivacion`).
+- `index.html`: añadir un campo de ID de muestra + control de importación en el panel de
+  paciente (`#panel-paciente`, junto a `pt-*`), siguiendo la convención existente
+  `.btn-importar-pdf`/`data-panel`. Sin cambio de CSP.
+- `frontend/src/main.ts`: importar y llamar `inicializarImportLab(evaluar)` junto a la línea
+  existente `inicializarParserPdf(evaluar)` (~L169), pasando la misma referencia `evaluar`.
+
+---
+
+## Puente local — nuevo `bridge/` de nivel superior (proyecto uv separado)
+Python + uv para coincidir con el tooling del repo y reusar las formas canónicas; su propio
+`bridge/pyproject.toml` para que las deps de serial/HL7 nunca inflen la imagen de HF Spaces.
+
+```
+bridge/
+  pyproject.toml            # uv: httpx, pyserial, python-hl7 (o hl7apy); pytest grupo dev
+  bridge/config.py          # BridgeConfig(BaseSettings) env_prefix MORPHOS_BRIDGE_: morphos_url, api_key, instrumentos[]
+  bridge/modelo.py          # forma canónica ResultadoAnalizador
+  bridge/transporte/
+      serial.py             # lector pyserial → tramas crudas (Abaxis/Horiba ASTM)             [FASE 1]
+      mllp.py               # servidor MLLP TCP (\x0b..\x1c\x0d) → tramas crudas (Bionote HL7) [FASE 1]
+  bridge/adaptadores/
+      base.py               # AdaptadorBase: generador async → yields ResultadoAnalizador
+      astm_generico.py      # ASTM E1381/E1394 (STX/ETX/checksum, registros H/P/O/R/L)         [FASE 1]
+      hl7v2.py              # parsea ORU^R01 (v2.6 PCD-01) → canónico; requerido por Bionote    [FASE 1]
+      registro.py           # fabricante → parser (selección automática)                        [HECHO]
+      abaxis.py             # VetScan sobre astm_generico (fabricante=abaxis)                    [HECHO]
+      horiba.py             # Scil/Horiba sobre astm_generico (fabricante=horiba)                [HECHO]
+      bionote.py            # Vcheck V200 sobre hl7v2 (fabricante=bionote, PCD-01)               [HECHO]
+  bridge/normalizador.py    # salida del adaptador → ResultadoAnalizador validado (+ pistas de paciente)
+  bridge/reenviador.py      # httpx Bearer POST /api/lab/ingesta, backoff exp, cola spool en disco, idempotencia mensaje_id
+  bridge/main.py            # supervisa adaptadores configurados → normalizador → reenviador
+  bridge/tests/  bridge/README.md   # cableado por analizador + checklist de validación
+```
+- Separar **transporte** (serial / MLLP — cómo llegan los bytes) de **adaptador** (ASTM / HL7
+  / fabricante — cómo las tramas se vuelven un `ResultadoAnalizador`), de modo que
+  Abaxis/Horiba/Bionote reusen `transporte/serial.py` y difieran sólo en el parseo. Cada
+  adaptador es un generador async que emite `ResultadoAnalizador`.
+- `reenviador.py` es el núcleo de fiabilidad: spool local para no perder nada cuando HF esté
+  brevemente inalcanzable; reintentos idempotentes vía `mensaje_id` de cliente (el almacén es
+  último-gana por `muestra_id` de todos modos).
+- **Cada uno de Abaxis / Horiba / Bionote necesita su propio adaptador + validación en sitio
+  contra el instrumento físico**, pero el esfuerzo difiere: Abaxis y Horiba (ASTM sobre
+  serie) requieren confirmar parámetros serie — baud/paridad/framing — y el layout de
+  registros (y en el Abaxis VS2, seleccionar la salida **ASTM** frente a sus modos ASCII/XML);
+  **Bionote (HL7 v2.6 PCD-01 sobre MLLP)** sólo requiere confirmar el transporte
+  (puerto MLLP/IP), el juego de identificadores OBX-3 del perfil PCD-01 (a menudo LOINC o
+  nomenclatura IEEE 11073/MDC) y las unidades — no hay que revertir ningún formato
+  propietario. El README incluye un checklist por analizador (capturar 3–5 corridas reales,
+  confirmar transporte + campo de ID de muestra + unidades, diff al JSON del fabricante).
+  Abaxis y Horiba caen ambos en `astm_generico.py`; **Bionote se apoya en `hl7v2.py`** con un
+  fino mapeo del perfil PCD-01.
+
+---
+
+## Entrega por fases
+- **Fase 0 — Contratos (sólo backend, totalmente testeable):** `schemas_lab.py`,
+  `data/lab_mapeos/generico.json`, `lab/mapeo.py` + tests unitarios.
+- **Fase 1 — MVP extremo-a-extremo:** auth de equipo + config keys; `routers/lab.py`;
+  `lab/almacen.py`; registrar en `main.py`; frontend `lab-import.ts` + campo de ID de muestra
+  + cableado en `main.ts`; esqueleto del puente con `transporte/serial.py` +
+  `transporte/mllp.py` + `adaptadores/astm_generico.py` + `adaptadores/hl7v2.py` +
+  `reenviador.py`. Entregable: una máquina ASTM genérico (serial) o HL7 v2 → match por ID de
+  muestra → autorrelleno.
+- **Fase 2 — Endurecimiento:** durabilidad del spool, UI de cola `/api/lab/pendientes`, flag
+  opcional de persistencia SQLite, exponer `no_mapeados` al veterinario.
+- **Fase 3 — Adaptadores por fabricante:** `abaxis.py`, `horiba.py`, `bionote.py` + sus JSON,
+  cada uno condicionado a captura del equipo real. (IDEXX diferido, fuera de alcance.)
+
+## Riesgos
+1. **Dialectos ASTM de Abaxis/Horiba (el mayor, ahora reducido).** Quitar IDEXX elimina el
+   riesgo de middleware propietario, y confirmar que Bionote es HL7 v2.6 PCD-01 estándar (no
+   propietario) elimina el riesgo de revertir un formato de línea. Riesgo residual principal:
+   los dialectos ASTM de Abaxis/Horiba varían en layout de registro y parámetros serie
+   (baud/paridad), y necesitan una captura del equipo real para cerrarse. Para Bionote el
+   riesgo es menor y acotado: confirmar el transporte (puerto MLLP) y el juego de códigos
+   OBX-3 del perfil PCD-01. El JSON dirigido por datos + la separación transporte/adaptador
+   contienen el radio de impacto, pero el framing/las unidades aún se validan con capturas
+   físicas.
+2. **Efimeridad de HF Spaces:** el almacén en proceso pierde resultados al reiniciar.
+   Aceptable (resultados de vida corta + reenviables desde el spool del puente) pero debe
+   documentarse; no prometer historial durable sin un volumen persistente.
+3. **Disciplina de ID de muestra:** el match depende de que el mismo ID esté en la máquina y
+   en la UI; el escaneo de código de barras mitiga typos; normalización centralizada en
+   `almacen.py`.
+4. **Suposición de un solo worker:** el almacén en proceso sólo es correcto con un worker de
+   uvicorn (actualmente cierto). Si se añaden workers, mover el almacén a SQLite/caché
+   compartida — señalarlo en `almacen.py`.
+5. **Deriva en conversión de unidades:** los factores viven en `pdf-parser.ts` y en
+   `mapeo.py` — mitigar con tests de paridad.
+
+## Verificación
+- **pytest backend** (`TestClient(app)` + `monkeypatch`, reflejando `backend/tests/test_api.py`):
+  - `test_lab_mapeo.py`: código de fabricante → clave canónica; conversiones de unidad
+    aseverando **paridad** con los factores de `pdf-parser.ts` (p. ej. glucosa `mmol/L→mg/dL
+    ×18.016`, creatinina `µmol/L ÷88.4`); semicuant `"+++"→"+++"`; derivación del diferencial
+    de leucocitos; `no_mapeados`.
+  - `test_lab_ingesta.py`: ingesta con Bearer key válida → 200 + almacenado; key errónea/sin
+    key → 401; ingesta y luego `GET /api/lab/resultados?muestra=…` con cookie de sesión →
+    analitos mapeados; consulta sin sesión → 401; muestra desconocida → 404.
+  - Fixtures: tramas HL7 ORU^R01 (incl. una v2.6 PCD-01 estilo Bionote) + ASTM crudas y sus
+    dicts canónicos esperados en `backend/tests/fixtures/lab/`.
+- **pytest puente** (`bridge/tests/`): fixture HL7/ASTM cruda → `ResultadoAnalizador`
+  normalizado; lógica de reintento/idempotencia del `reenviador` con transporte httpx mockeado.
+- **Vitest frontend** (`frontend/src/lab-import.test.ts`, fixture de formulario jsdom como los
+  tests del motor): un JSON `ResultadoMapeado` fija los inputs `[name=…]` + selects `uri-*`
+  correctos y llama `evaluar` una vez.
+- **Extremo-a-extremo manual (MVP):** correr backend (`make dev`) + una instancia del puente
+  local; enviar una muestra HL7/ASTM capturada a través del puente; en la UI teclear el ID de
+  muestra y confirmar que el formulario se autorrellena, los campos se resaltan y el análisis
+  se re-ejecuta. Comandos: `make backend-test`, `make frontend-test`, `make frontend-build`.
+- **Fuera de alcance automatizado (explícito):** validación con equipo real de
+  Abaxis/Horiba/Bionote — la suite automatizada usa fixtures capturadas; la corrección final
+  de parámetros serie/campo/unidad/ID de muestra sólo se confirma contra los instrumentos
+  físicos en la LAN de la clínica.

MIGRACION.md

@@ -0,0 +1,101 @@
+# Migración de Morphos — estado y guía
+
+Modernización del stack según `PLAN_MODERNIZACION.md`. Decisiones: IA híbrida
+(medGemma privado por defecto + Claude opcional), backend **Python/FastAPI con uv**,
+frontend **incremental Vite + TypeScript**, despliegue en **HF Spaces** con índice RAG
+horneado en la imagen (sin almacenamiento persistente de pago).
+
+## Estructura nueva
+
+```
+frontend/          Vite + TS. Motor portado + suite de regresión (Vitest).
+  src/analisis.ts    Puerto fiel de js/analisis.js (tipado).
+  src/ia.ts          Cliente tipado de /api/interpret (render estructurado).
+  tests/             27 pruebas dorada s del motor.
+backend/           FastAPI (uv). IA estructurada, RAG, seguridad.
+  app/schemas.py     Salida clínica estructurada (Pydantic) → elimina limpiarRespuesta.
+  app/ai/            medgemma.py, claude.py, prompt.py, service.py.
+  app/rag/           retriever.py (degrada sin índice), ingest.py.
+  app/routers/       interpret.py, papers.py, auth.py.
+  app/security/      authz, rate_limit, session, headers.
+  tests/             15 pruebas (esquema, prompt, RAG, API+seguridad).
+evals/             Dataset dorado + run_evals.py (puerta CI) + juez LLM + promptfoo.
+books/             Corpus con licencia (gitignored). Ver books/README.md.
+instance/          BD de usuarios + índice RAG (fuera del webroot; gitignored).
+bridge/            Puente local (proyecto uv aparte): lee analizadores (ASTM/HL7 v2) en la
+                   LAN de la clínica y reenvía a /api/lab/ingesta. Ver INTEGRACION_ANALIZADORES.md.
+```
+
+## Integración de analizadores de laboratorio
+
+Fases 0-1 implementadas (ingesta de resultados de equipos → autorrelleno del formulario por
+ID de muestra). Backend: `app/schemas_lab.py`, `app/lab/` (mapeo + almacén TTL),
+`app/routers/lab.py`, `app/security/device.py` (auth por API key). Frontend: `lab-import.ts`
++ `form-inject.ts`. Puente: `bridge/`. Mapeos código→analito en `data/lab_mapeos/`. Detalle
+y fases pendientes en **INTEGRACION_ANALIZADORES.md**.
+
+## Cómo ejecutar
+
+```bash
+# Frontend: pruebas del motor y build
+make frontend-install
+make frontend-test          # 27/27
+make frontend-build         # → dist/
+
+# Backend: sync (uv) y pruebas
+make backend-sync
+make backend-test           # 15/15
+make dev                    # uvicorn en :8000
+
+# Evals (puerta de CI)
+make evals                  # run_evals.py --simular → ✅/❌ + exit code
+
+# RAG (cuando haya libros en books/)
+make ingest                 # construye instance/rag_index con el grupo 'rag'
+
+# Docker (multi-stage: build frontend + backend uv)
+make docker-build
+```
+
+## Qué se ha implementado y verificado
+
+- ✅ **Motor portado a TS** con 27 pruebas de regresión (parity con el JS original) y
+  typecheck limpio. Es la red de seguridad de la migración.
+- ✅ **Backend FastAPI** con **salida estructurada validada** (Pydantic) que sustituye la
+  limpieza por regex; clientes **medGemma** (Ollama, plantilla de chat + `format` JSON
+  Schema, sin inyección de `<unused95>`) y **Claude** (tool use). 15 pruebas verdes.
+- ✅ **Seguridad**: `/api/interpret` y `/api/papers` requieren sesión (cerrado el acceso
+  anónimo); CORS bloqueado; sesiones firmadas HttpOnly/SameSite/Secure; CSRF de doble
+  token; throttling de login; validación de imágenes; cabeceras de seguridad; BD e índice
+  RAG **fuera del webroot**. Verificado: 401 sin sesión, 403 sin CSRF, flujo completo OK.
+- ✅ **RAG**: pipeline de ingesta + recuperador con citas que **degrada a modo sin-RAG**
+  si faltan deps o índice (probado). Índice horneado en la imagen.
+- ✅ **Evals**: dataset dorado, comprobaciones deterministas (recall diferenciales,
+  cobertura, derivación, idioma, **seguridad tolerancia-cero**), juez LLM (Claude),
+  promptfoo y **puerta de CI** (exit≠0 ante regresión) — verificado que bloquea.
+- ✅ **Puente Node** que reusa `analisis.ts` como única fuente de verdad para generar los
+  hallazgos deterministas en las evals.
+
+## Hecho en el último incremento
+
+- ✅ **Puerto TS de todos los módulos UI** (`ui`, `pdf-parser`, `main`, `auth`, `papers`,
+  `tooltip`) + helper `dom.ts`. `auth.ts`/`papers.ts` usan los endpoints FastAPI.
+- ✅ **`index.html` recableado** a `/frontend/src/main.ts` (Vite lo empaqueta). La app corre
+  end-to-end sobre el stack nuevo — verificado en navegador: motor, PDF, registro/login
+  real (sesión + CSRF) y el botón IA llamando a `/api/interpret`.
+
+## Pendiente (siguiente incremento)
+
+- **Retirar** `api/*.php` y `js/*.js` legacy: ya son código muerto (no se cargan). Borrado
+  seguro cuando se confirme que no se necesitan de referencia.
+- ✅ **Ruta de IA funcionando en vivo**: la ruta `medgemma` usa por defecto el HF Space
+  (Gradio) donde está alojado el modelo — `app/ai/hf_space.py` porta el flujo de
+  `hf_proxy.php` (upload → analyze → SSE) y envuelve el texto en el esquema. Verificado en
+  navegador: interpretación real renderizada con el aviso de derivación. (Alternativas por
+  config: Ollama local si se vacía `MORPHOS_HF_SPACE_URL`, o Claude con API key.)
+- **Config ESLint/Prettier** (falta el archivo de configuración; ya está la dependencia).
+- **Retriever RAG**: añadir búsqueda híbrida BM25 + rerank.
+- **Ingesta real** de los libros con licencia (`make ingest`) y activar Ragas sobre el
+  índice poblado.
+- **Aumentar el dataset** de evals con más casos validados por veterinario.
+- Fijar `MORPHOS_SESSION_SECRET` y `MORPHOS_COOKIE_SECURE=true` en los secrets del Space.

PLAN_MODERNIZACION.md

@@ -0,0 +1,429 @@
+# Morphos — Modernization, AI/RAG, Evals & Security Plan
+
+> ## Estado de implementación (auditoría 2026-07-26)
+>
+> Leyenda: ✅ hecho y verificado · 🟡 parcial (núcleo hecho, falta un subpunto) · ⬜ pendiente
+>
+> | Fase | Estado | Resumen |
+> |---|---|---|
+> | 1 — Frontend (Vite/TS) | ✅ | **Todos** los módulos portados a TS (analisis, ui, pdf-parser, auth, papers, main, tooltip, ia); `index.html` recableado al bundle TS; 32 tests ✅. Menor: falta archivo de config ESLint/Prettier. |
+> | 2 — Capa IA (FastAPI) | ✅ | Endpoints, salida estructurada, clientes medGemma/Claude, prompt endurecido, validación imágenes. Orquestación con `ClienteModelo` propio (no la librería Pydantic AI). |
+> | 3 — RAG | ✅ | Ingesta + retriever con citas + degradación ✅. **Nuevo:** búsqueda híbrida (denso + BM25/FTS fusionados con RRF) + rerank cross-encoder `bge-reranker-v2-m3`, ambos conmutables; traducción ES→EN de consulta. **Corpus real ingerido**: 6763 fragmentos de 2 libros en `instance/rag_index/` (LanceDB, 69 MB, bge-m3). |
+> | 4 — Evals | 🟡 | Dataset dorado (17 casos), juez clínico, promptfoo, puerta CI ✅ (bloqueo verificado), arnés de evaluación de recuperación aislada (`run_retrieval_eval.py`). Faltan: **código Ragas (0 líneas)**, human-in-the-loop, split reservado, informe por-ruta/por-corpus. |
+> | 5 — Seguridad | ✅ | Guarda auth, rate limit, CORS, CSRF, BD/RAG fuera del webroot, cabeceras, validación imágenes — verificado. Menor: rate limit por-usuario y redirección HTTP→HTTPS. |
+>
+> **Verificado ejecutando (2026-07-26):** 32 tests frontend (Vitest), **97 tests backend**
+> (pytest, incluye retriever híbrido + integración con índice real + ingesta/troceo +
+> traducción de consulta), ruff limpio, typecheck limpio. Previamente verificado en el
+> navegador contra el backend FastAPI: motor de patrones (anemia microcítica), import de PDF
+> (parser TS portado), registro/login real (sesión + CSRF), y el botón "Análisis IA"
+> llamando a `POST /api/interpret` con token CSRF. Puerta de evals bloquea (exit≠0), 401 sin
+> sesión, 403 sin CSRF. **No verificado en vivo:** salida estructurada renderizada con un
+> modelo real (falta `ollama pull` de medGemma), promptfoo ejecutado, rechazo CORS de
+> orígenes externos, 429 bajo carga, `/security-review`.
+>
+> **Fuera de este plan:** la integración de analizadores de laboratorio (ASTM/HL7) ha
+> avanzado en paralelo — `backend/app/routers/lab.py`, `bridge/`, `data/lab_mapeos/`,
+> `tests/test_lab_*.py`, `frontend/tests/lab-import.test.ts`. Ver `INTEGRACION_ANALIZADORES.md`.
+>
+> **Legacy pendiente de retirar:** los 8 `js/*.js` y los 5 `api/*.php` siguen en el repo pero
+> YA NO se cargan (`index.html` no referencia ninguno). Son código muerto a eliminar.
+>
+> ### Lo que queda, en orden sugerido
+> 1. **Borrar el legacy** `js/` + `api/` — riesgo cero, ya es código muerto.
+> 2. **Ragas + split reservado**, y ejecutar la suite completa de evals contra el índice real
+>    — el mayor valor pendiente, y ya desbloqueado por el corpus ingerido.
+> 3. Config ESLint/Prettier; rate limit por-usuario en `/api/interpret`; informe de evals
+>    por-ruta-de-modelo y por-versión-de-corpus.
+> 4. Human-in-the-loop (mayor alcance, requiere decisiones de producto).
+>
+> Ver detalle marcado por tarea abajo y `MIGRACION.md` para el siguiente incremento.
+
+## Context
+
+Morphos is a veterinary diagnostic-support SPA (canine/feline) that detects clinical
+patterns from lab values in real time and optionally asks an AI model (medGemma 1.5 4B
+via a HuggingFace Gradio Space, or local Ollama) for a clinical interpretation. It ships
+as vanilla JS (no build step) + thin PHP proxies, deployed as Docker on HF Spaces.
+
+The app works, but three things block it from being a trustworthy diagnostic assistant:
+
+1. **The AI layer fights the model instead of controlling it.** `js/ia.js` builds the
+   prompt by string concatenation, injects a raw `<unused95>` control token, and post-
+   processes output through `limpiarRespuesta()` — ~70 lines of regex hacks stripping
+   control tokens, English-only reasoning, LaTeX, and looped paragraphs. These are
+   symptoms of an uncontrolled inference path (raw Gradio Space, no chat template, no
+   structured output, no grounding).
+2. **There are zero evals.** For a tool that suggests differentials on real patients,
+   there is no measurement of accuracy, groundedness, or safety. This is the highest-risk
+   gap.
+3. **Security holes**: the AI and papers proxies are unauthenticated with open CORS
+   (anyone can call `api/hf_proxy.php` and burn the HF key), there is no rate limiting
+   anywhere, the SQLite DB with password hashes may be web-reachable, and MySQL defaults
+   to `root`/empty-password.
+
+The vet-validated pattern engine (`js/analisis.js`, `data/*.json`) is the crown jewel and
+must be preserved exactly through the migration.
+
+### Decisions (confirmed with the user)
+
+- **AI model strategy: Hybrid.** Keep self-hosted medGemma/Ollama as the private default;
+  add an optional hosted frontier-model (Claude) route for higher accuracy. The eval judge
+  always uses a strong model.
+- **Backend: Python FastAPI** for the AI/RAG/eval service (best ecosystem).
+- **Frontend: Incremental.** Add Vite + TypeScript, port modules (especially `analisis.js`)
+  to typed TS with unit tests, keep the existing DOM UI. No React rewrite.
+- **Hosting: stay on HF Spaces (PRO).** Because the RAG corpus is static licensed books,
+  build the vector index offline and bake it read-only into the Docker image — **no paid
+  persistent storage needed**. App Space (CPU-basic, FastAPI + static assets) + the existing
+  ZeroGPU medGemma Space + optional Claude route.
+
+> **HF hosting check:** Free Spaces have an ephemeral filesystem; persistent storage is a
+> paid add-on ($5/mo for 20 GB up). PRO ($9/mo) gives 10 ZeroGPU/Docker Spaces + 1 TB repo
+> storage. Since the RAG corpus is static, the vector index is baked into the image and
+> needs no persistent-storage purchase — the plan fits inside the PRO subscription.
+
+---
+
+## Target Architecture
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│  App Space (HF, CPU-basic, Docker)                               │
+│                                                                  │
+│  Frontend (Vite build → static)          Backend (FastAPI)       │
+│  ├─ analisis.ts  (ported engine, tested) ├─ /api/auth   (session)│
+│  ├─ ui.ts / pdf-parser.ts / papers.ts    ├─ /api/interpret (AI)  │
+│  └─ ia.ts (calls /api/interpret)         ├─ /api/papers  (PubMed)│
+│                                          ├─ RAG retriever        │
+│                                          │   └─ baked vector idx │
+│                                          └─ rate limit + authz   │
+│                                                                  │
+│  Persistence: SQLite (users) outside webroot                     │
+└───────────────┬──────────────────────────────┬──────────────────┘
+                │ hybrid route                  │
+     ┌──────────▼─────────┐          ┌──────────▼──────────┐
+     │ medGemma ZeroGPU   │          │ Claude API (opt.)   │
+     │ Space (private)    │          │ (higher accuracy)   │
+     └────────────────────┘          └─────────────────────┘
+```
+
+Monorepo layout after migration:
+
+```
+morphos/
+├── frontend/         # Vite + TS; ported js/ modules, unit tests (Vitest)
+├── backend/          # FastAPI: auth, interpret, papers, rag, security
+│   ├── app/
+│   │   ├── main.py            # FastAPI app, middleware (CORS, rate limit)
+│   │   ├── routers/           # auth.py, interpret.py, papers.py
+│   │   ├── ai/                # model clients (medgemma, claude), prompt, schema
+│   │   ├── rag/               # ingestion, chunking, embeddings, retriever
+│   │   └── security/          # authz deps, rate limiter, session
+│   └── tests/
+├── evals/            # golden dataset, promptfoo + Ragas configs, CI gate
+├── data/             # valores_referencia.json, alteraciones.json (unchanged)
+│   └── rag_index/    # baked vector index (built in CI, shipped read-only)
+├── Dockerfile        # multi-stage: build frontend + index, run FastAPI+static
+└── docker-entrypoint.sh
+```
+
+---
+
+## Phase 1 — Frontend modernization (incremental, low risk) — ✅ (salvo config ESLint)
+
+Goal: add tooling and types **without changing behavior**. The engine is vet-validated;
+migration must be behavior-preserving and proven so by tests.
+
+- 🟡 Introduce `frontend/` with **Vite + TypeScript + Vitest**. Add `package.json`,
+  `tsconfig.json`, ESLint/Prettier. Keep Spanish naming per `CLAUDE.md`; no alignment
+  spaces; no `!important` in CSS.
+  — *Vite + TS + Vitest ✅ (`frontend/package.json`, `tsconfig.json`, `vite.config.ts`).
+  Falta: no hay archivo de config ESLint/Prettier (sólo la dependencia y el script `lint`).*
+- ✅ Port `js/analisis.js` → `frontend/src/analisis.ts` first. It is pure/stateless (single
+  export `analizarResultados`), so it types cleanly and is fully unit-testable. **Write a
+  golden test suite** that pins current behavior (severity classification, age/breed/sex
+  adjustments, all ~60 pattern rules) using fixtures derived from `data/*.json`. This suite
+  doubles as the regression net for the whole migration.
+  — *`analisis.ts` + `tipos.ts` + 27 tests Vitest (32 en total con `lab-import.test.ts`),
+  typecheck limpio. Verificado.*
+- ✅ Port remaining modules (`main.js`, `ui.js`, `ia.js`, `pdf-parser.js`, `auth.js`,
+  `papers.js`, `tooltip.js`) to `.ts`. Preserve the getter-callback wiring in `main.js` and
+  the `imagenesDataUrl` / `capturasMicroscopio` shared arrays in `ui.js`.
+  — *Todos portados (`frontend/src/*.ts`) + helper `dom.ts`. Typecheck limpio; verificados
+  en el navegador (motor, PDF, auth). `auth.ts`/`papers.ts` apuntan a los endpoints nuevos.*
+- ✅ Keep `index.html` markup and `css/styles.css` as-is initially; wire the Vite-built bundle
+  in place of the `?v=N` module tag. Remove the leftover `console.log` debug blocks in
+  `ia.js`.
+  — *`index.html` carga `/frontend/src/main.ts` (Vite lo empaqueta). El `ia.js` legacy ya no
+  se carga (código muerto); el nuevo `ia.ts` no tiene `console.log`.*
+- ✅ Update stale `CLAUDE.md` facts (analisis.js is 817 lines / 90 analytes / 78 clinical
+  entities; auth + papers layers exist).
+
+Files: new `frontend/**`; modify `index.html` script tag; delete debug logging in `ia.js`.
+
+---
+
+## Phase 2 — AI layer rebuilt on FastAPI (replaces the PHP proxy + regex cleanup) — ✅
+
+Goal: a controlled, model-agnostic inference path with **structured, validated output**,
+so `limpiarRespuesta()` becomes unnecessary.
+
+- ✅ New FastAPI service (`backend/`). Replace `api/hf_proxy.php` with `POST /api/interpret`
+  and `api/papers_proxy.php` with `GET /api/papers`. Keep the PubMed disk-cache logic
+  (port `papers_proxy.php` behavior). Keep `api/auth.php` semantics but reimplement in
+  FastAPI (Phase 5 hardens it).
+  — *Endpoints creados; caché de PubMed portada; auth reimplementada. Los `.php` legacy aún
+  no se han borrado (siguen en `api/`) — retirada pendiente hasta migrar la UI.*
+- 🟡 **Orchestration: Pydantic AI** (model-agnostic, typed, structured outputs). Define a
+  `ModelClient` interface with two implementations: `MedGemmaClient` (self-hosted default;
+  talk to the ZeroGPU Space / Ollama using the **proper chat template**, not raw
+  `<unused95>` injection) and `ClaudeClient` (hybrid opt-in via the Anthropic SDK). Backend
+  selection replaces the current `localStorage` `mx-ia-backend` toggle and is enforced
+  server-side.
+  — *Desviación: se implementó un protocolo `ClienteModelo` propio (`app/ai/base.py`) con
+  `MedGemmaClient` + `ClaudeClient` y selección server-side, en vez de la librería Pydantic
+  AI. Cumple el objetivo (salida tipada/validada) con menos dependencias.*
+- ✅ **Structured output schema** (Pydantic) — the core fix. Instead of free text, the model
+  returns:
+  `interpretacion` (es), `hallazgos_clave[]` (analyte, direccion, gravedad),
+  `diferenciales[]` (nombre, probabilidad, evidencia[], citas[] → RAG sources),
+  `siguientes_pruebas[]`, `confianza`, `requiere_derivacion` (safety flag), `idioma="es"`.
+  Enforce with structured/JSON output; validate server-side; on validation failure, retry
+  or return a typed error — **never** ship unparsed model text. This deletes the entire
+  `limpiarRespuesta` regex pile.
+  — *`app/schemas.py::InterpretacionClinica`; reintento + error tipado en `service.py`.*
+- ✅ Prompt construction moves server-side into `backend/app/ai/prompt.py`, assembled from
+  patient data + flagged findings + detected patterns (reuse the enrichment already in
+  `construirPrompt`) + **retrieved RAG context** (Phase 3). System prompt hardened: Spanish-
+  only, scope limits, mandatory hedging/deferral language, citation requirement,
+  injection resistance for free-text `signos-clinicos` and citology images.
+- ✅ Vision path preserved: medGemma multimodal for citology images; keep the 1024px client
+  resize and ≤4 images limit, but validate size/count/mime server-side (Phase 5).
+- ✅ Frontend `ia.ts` becomes a thin typed client of `/api/interpret` that renders the
+  structured result (findings, ranked differentials **with citations**, next steps, a
+  visible "requiere derivación veterinaria" banner when flagged).
+  — *Código completo (`frontend/src/ia.ts`), cableado vía el bundle TS y ejercitado en el
+  navegador. Falta ver el render con salida de un modelo real (`ollama pull` pendiente).*
+
+Files: new `backend/app/ai/**`, `backend/app/routers/interpret.py`, `.../papers.py`;
+rewrite `frontend/src/ia.ts`; remove `api/hf_proxy.php`, `api/papers_proxy.php`.
+
+---
+
+## Phase 3 — RAG layer (structure now; books ingested later) — ✅
+
+Goal: ground interpretations in the licensed veterinary literature with **verifiable
+citations**, built so the corpus can be dropped in when provided.
+
+- ✅ **Stack:** LlamaIndex for ingestion/retrieval; **LanceDB** (embedded, file-based → bakes
+  cleanly into the image, zero runtime services) as the vector store. Embeddings via a
+  **self-hosted multilingual model** (e.g. BGE-M3 through `sentence-transformers`) to keep
+  the privacy positioning — no document content leaves the box at index time.
+  — *Dependencias en el grupo `rag` de `pyproject.toml`; ingesta usa pypdf +
+  sentence-transformers + lancedb directamente (llama-index-core disponible).*
+- ✅ **Ingestion pipeline** (`backend/app/rag/ingest.py`, run offline/CI, not at request time):
+  PDF/EPUB → text extraction → **structure-aware chunking** (section/heading, ~512–1024
+  tokens, overlap) → metadata per chunk (`libro`, `edicion`, `capitulo`, `pagina`,
+  `especie?`) → embed → write LanceDB table under `data/rag_index/`. A manifest records
+  corpus version + hash for eval reproducibility.
+  — *Escribe en `instance/rag_index/` (no `data/`, por seguridad — ver Fase 5). Manifiesto ✅.*
+- ✅ **Retriever** (`backend/app/rag/retriever.py`): hybrid search (dense + BM25/keyword),
+  metadata filtering by species, top-k with a rerank step; returns chunks **with source
+  metadata** so the interpret schema's `citas[]` point to `libro/edicion/página`. Retrieval
+  is triggered by detected patterns + flagged analytes (reuse `ultimoAnalisis`), so it
+  targets the patient's actual findings.
+  — *Denso + BM25/FTS fusionados con RRF + rerank con cross-encoder `bge-reranker-v2-m3`,
+  filtro por especie y citas ✅. Conmutables por `rag_hibrido`/`rag_rerank` (`config.py`), con
+  degradación en cascada: rerank → RRF → sólo denso. Añadido `traduccion_consulta.py`
+  (consulta ES → corpus EN). Cubierto por `test_retriever_hibrido.py` +
+  `test_retriever_integracion.py`.*
+- ✅ **Copyright safety:** retrieval returns short grounding snippets to the model only; the
+  API never exposes full book text to the client, and the endpoint is auth-gated.
+- ✅ **Ship path:** index built in CI and copied into the Docker image read-only. No HF
+  persistent storage required. Rebuild only when the corpus changes.
+  — *Dockerfile copia `instance/` de sólo lectura.*
+- ✅ **Placeholder now:** commit the full pipeline + an empty/sample index and a
+  `books/README.md` describing the expected input layout, so ingesting the real books later
+  is a single `make ingest` step. The interpret path must degrade gracefully to no-RAG when
+  the index is empty.
+  — *Superado: ya no es un placeholder. **Corpus real ingerido** con `make ingest` — 6763
+  fragmentos de 2 libros (Fundamentals of Veterinary Clinical Pathology 3e; Veterinary
+  Hematology, Clinical Chemistry, and Cytology 3e) en `instance/rag_index/` (LanceDB 69 MB,
+  bge-m3, chunks 450 tok / solape 64, troceo estructural markdown, índice FTS, manifiesto con
+  `hash_corpus`). Degradación a sin-RAG sigue probada. El índice NO se comitea (queda fuera
+  del repo; se construye en CI y se copia a la imagen).*
+
+Files: new `backend/app/rag/**` (`ingest.py`, `retriever.py`, `traduccion_consulta.py`),
+`instance/rag_index/` (artefacto construido, gitignored — **no** `data/`, por seguridad),
+`books/README.md`, `Makefile` (`ingest`, `retrieval-eval`).
+
+---
+
+## Phase 4 — Rigorous evals (the core requirement for a diagnostic tool) — 🟡
+
+Goal: measure accuracy, groundedness, and safety continuously, and gate deploys on it.
+
+- 🟡 **Golden dataset** (`evals/dataset/`): curate expert-validated cases. The user already has
+  real lab results + citologies from practicing vets (per `USO_DE_IA.md`) — turn these into
+  labeled cases: patient signalment + lab values → expected key findings, expected
+  differentials (acceptable set), red-flag/safety expectations, and out-of-scope cases the
+  model must decline. Version the dataset; keep a held-out split.
+  — *`casos.jsonl` ampliado de 7 a **17 casos** (IMHA, hipertiroidismo, HAC, pancreatitis,
+  trombocitopenia, hipercalcemia, enteropatía perdedora, gammapatía, hepatocelular agudo,
+  leucocitosis inflamatoria… + el caso fuera-de-alcance) + README con esquema ✅.
+  Falta: **split reservado** (ningún caso lleva campo `split`) y casos reales del veterinario.*
+- **Frameworks (layered):**
+  - ✅ **promptfoo** — config-driven prompt/response regression in CI: deterministic assertions
+    (language = es, valid schema, required derivation flag present when expected, no
+    forbidden claims), plus LLM-rubric graders.
+    — *`evals/promptfooconfig.yaml` presente (no ejecutado aquí, requiere modelo).*
+  - ⬜ **Ragas** — RAG-specific metrics: faithfulness/groundedness (no claims beyond retrieved
+    context), context precision/recall, answer relevance, **citation correctness**.
+    — *Dependencia en el grupo `evals` (`pyproject.toml`) y mencionada en los READMEs, pero
+    **cero líneas de código Ragas** en el repo. Ya está desbloqueado: el índice está poblado.
+    Es el hueco más grande que queda del plan.*
+  - ✅ **Evaluación de recuperación aislada** (no estaba en el plan original, añadida para
+    decidir por datos): `evals/run_retrieval_eval.py` + `dump_retrieval.py` miden si los
+    fragmentos recuperados son relevantes al diagnóstico esperado, permitiendo A/B de
+    modelo de embeddings × idioma de consulta (bge-m3 ES vs EN vs MedCPT) antes de invertir
+    en rerank. Juzga con Claude si hay `ANTHROPIC_API_KEY`, si no con heurístico de solape.
+    Expuesto como `make retrieval-eval`.
+  - ✅ **Custom clinical rubric** (`evals/judge/`) — LLM-as-judge (strong model, e.g. Claude)
+    scoring: differential correctness vs. expected set, appropriate hedging, safety
+    (no dangerous/overconfident recommendations), completeness.
+    — *`evals/judge/clinical_judge.py` (se activa con ANTHROPIC_API_KEY).*
+- 🟡 **Metrics & thresholds:** per-metric pass bars (e.g. groundedness ≥ X, differential
+  recall ≥ Y, safety violations = 0). Track per model route (medGemma vs Claude) and per
+  corpus version so RAG changes are attributable.
+  — *Umbrales + agregación en `run_evals.py` ✅. Falta: informe explícito por-ruta/por-versión-de-corpus.*
+- ✅ **CI gate:** GitHub Actions runs the eval suite on PRs touching `backend/app/ai`,
+  `backend/app/rag`, prompts, or the index; **block merge/deploy on regression** or any
+  safety failure. Store run artifacts/scorecards.
+  — *`.github/workflows/evals.yml`; bloqueo verificado (exit=1 ante violación de seguridad).*
+- ⬜ **Human-in-the-loop:** a lightweight review workflow for a veterinarian to accept/correct
+  model outputs, feeding new cases back into the golden set. Log (privacy-safe) production
+  interpretations for periodic expert audit.
+  — *No implementado.*
+
+Files: new `evals/**`, `.github/workflows/evals.yml`.
+
+---
+
+## Phase 5 — Security audit & rate limiting — ✅
+
+Findings from the current code, severity-ranked, each with the fix folded into the new
+FastAPI backend.
+
+**Critical**
+1. ✅ **Unauthenticated AI/papers proxies + open CORS** (`api/hf_proxy.php`, `papers_proxy.php`
+   send `Access-Control-Allow-Origin: *`, no session check). Anyone can call them directly
+   and burn the HF key / abuse PubMed. → Require an authenticated session on `/api/interpret`
+   (and rate-limit papers); lock CORS to the app origin.
+   — *`Depends(usuario_actual)` en interpret/papers (401 verificado); CORS a orígenes fijos.*
+2. ✅ **Password-hash DB may be web-served.** SQLite fallback writes `data/morphos.db` under the
+   web root; `.htaccess` only denies `.env`/`setup.php`, so `/data/morphos.db` may be
+   downloadable, and `.htaccess` is Apache-only. → Move the DB **outside** the served root;
+   in FastAPI nothing under the DB path is a static route. Never rely on `.htaccess` for
+   secret protection.
+   — *BD en `instance/` (fuera del webroot); sólo `dist/` y `/data` (JSON) se montan.*
+
+**High**
+3. 🟡 **No rate limiting anywhere.** → Add **slowapi** (or Redis-backed) limits: per-IP + per-
+   user on `/api/interpret` (expensive), per-IP on `/api/auth` login (brute force) and
+   `/api/papers`. Return 429 with retry-after.
+   — *slowapi por-IP en interpret/login/papers + manejador 429 con Retry-After ✅.
+   Falta: límite adicional por-usuario (actualmente sólo por-IP).*
+4. ✅ **Login brute force** — no throttling/lockout. → Per-account + per-IP attempt throttling
+   with backoff; keep the already-generic "email o contraseña incorrectos" message.
+   — *Tabla `intentos_login` + throttle por email+IP; mensaje genérico.*
+5. ✅ **MySQL `root` / empty password default** (`conexion.php`). → Require DB credentials from
+   env; no hardcoded defaults; fail closed if unset.
+   — *El backend nuevo no tiene credenciales por defecto (config por entorno); SQLite por defecto.*
+
+**Medium**
+6. ✅ **Secrets via `.env` in webroot** guarded only by `.htaccess`. → Load secrets from real
+   env vars (HF Spaces secrets); keep `.env` out of any served directory.
+   — *pydantic-settings; `backend/.env` gitignored; nada bajo el root servido.*
+7. ✅ **No CSRF protection** on session POSTs. → `SameSite=Strict` + `Secure` + `HttpOnly`
+   session cookies, plus a CSRF token (or move to short-lived bearer tokens).
+   — *Cookie firmada HttpOnly/SameSite/Secure + CSRF de doble token (403 verificado).*
+8. ✅ **Server-side upload validation missing** for citology images (base64 decoded with no
+   size/count/mime cap → memory DoS). → Enforce ≤4 images, max bytes, allowed mime, safe
+   decode server-side.
+   — *`interpret.py::_validar_imagenes` (nº, mime, tamaño, decode seguro).*
+9. ✅ **Prompt-injection surface** via free-text `signos-clinicos` and citology images. →
+   Harden system prompt, treat user text as data, validate structured output, cap output
+   scope.
+   — *System prompt endurecido (trata el texto como datos) + salida estructurada validada.*
+
+**Low**
+10. ✅ Remove `console.log` prompt/PII leakage in `ia.js`.
+    — *El nuevo `ia.ts` (ya en uso) no registra el prompt. El `ia.js` legacy es código muerto
+    (no se carga) pendiente de borrar junto al resto de `js/*.js`.*
+11. 🟡 Raise password min length (6 → ≥8) + optional breach check; registration keeps 409 but
+    is now rate-limited (acceptable enumeration risk).
+    — *Mínimo 8 ✅ (`RegistroBody`). El chequeo de brechas (opcional) no se implementó.*
+12. 🟡 Add security headers (CSP, HSTS, X-Content-Type-Options, Referrer-Policy) and enforce
+    HTTPS.
+    — *Cabeceras ✅ (`headers.py`; HSTS en prod). Falta: redirección explícita HTTP→HTTPS
+    (se delega en la plataforma). Nota: CSP ajustada a `worker-src blob:` para PDF.js.*
+
+**New surface introduced by RAG:** ✅ licensed book text must never be exfiltratable —
+retrieval returns only short grounding snippets to the model, the API never serves full
+book content, and the corpus lives read-only in the image. — *Índice en `instance/`, endpoint auth-gated.*
+
+Files: `backend/app/security/**`, `backend/app/routers/auth.py`, DB path change in the
+connection layer, `Dockerfile`/entrypoint (secrets, DB location, headers).
+
+---
+
+## Verification
+
+- ✅ **Engine parity (Phase 1):** the `analisis.ts` golden test suite (Vitest) passes with
+  outputs identical to the current JS engine across fixture cases spanning both species and
+  all pattern rules. This is the gate that the migration preserved validated behavior.
+  — *27/27 verde (32/32 con los tests de import de laboratorio). Reejecutado 2026-07-26.*
+- 🟡 **AI path (Phase 2):** integration test that `/api/interpret` returns schema-valid
+  structured output for representative cases on both the medGemma and Claude routes; confirm
+  `limpiarRespuesta` is gone and no unparsed text can reach the client. Drive the real UI
+  to confirm findings, ranked differentials with citations, and the derivation banner render.
+  — *UI real verificada: el botón "Análisis IA" llama a `POST /api/interpret` con CSRF y el
+  backend alcanza el modelo (Ollama). Salida estructurada validada por test de integración;
+  `limpiarRespuesta` no existe en el código nuevo. Falta: `ollama pull` del modelo para ver
+  el render de diferenciales/citas con datos reales, y la ruta Claude ejercitada en vivo.*
+- ✅ **RAG (Phase 3):** with a small sample corpus, verify retrieved citations resolve to the
+  correct `libro/página` and that an empty index degrades gracefully to no-RAG.
+  — *Degradación a sin-RAG ✅. Resolución de citas ✅: `test_retriever_integracion.py` construye
+  un índice LanceDB real (con FTS) y comprueba recuperación end-to-end y filtro por especie;
+  el corpus real de 2 libros está ingerido. 97 tests backend verde (2026-07-26).*
+- 🟡 **Evals (Phase 4):** `promptfoo eval` + Ragas + the clinical rubric run green locally and
+  in CI; deliberately regress a prompt and confirm the CI gate blocks it; confirm a safety-
+  violation case fails the suite.
+  — *Puerta CI: bloqueo por violación de seguridad verificado (exit=1). Falta: ejecutar
+  promptfoo (requiere modelo) y Ragas (sin implementar).*
+- 🟡 **Security (Phase 5):** confirm unauthenticated `/api/interpret` returns 401; CORS
+  rejects foreign origins; rate limits return 429 under load; the DB path is not reachable
+  as a static route; MySQL refuses to start without credentials. Run `/security-review` on
+  the diff.
+  — *401 sin sesión ✅, 403 sin CSRF ✅, BD fuera del webroot ✅. Falta verificar en vivo:
+  rechazo CORS de orígenes externos, 429 bajo carga, y ejecutar `/security-review`.*
+
+---
+
+## Sequencing & risk notes
+
+- Ship in order: **Phase 1 → 5 → 2 → 3 → 4**. Rationale: lock behavior with tests first
+  (1), close the exploitable holes early (5), then rebuild the AI path (2), add grounding
+  (3), and stand up evals (4) — though the golden dataset from Phase 1 tests and the eval
+  dataset should be gathered in parallel from the start.
+- Biggest risk is **regressing the vet-validated engine**; the Phase 1 golden suite mitigates
+  it and must exist before any TS port lands.
+- ~~The real licensed books are pending~~ — **resuelto (2026-07-26)**: 2 libros ingeridos
+  (6763 fragmentos). Los PDF con licencia viven en `books/` **sin comitear** y el índice en
+  `instance/` (gitignored); ambos se reconstruyen con `make ingest`. Queda pendiente medir
+  con evals la mejora de exactitud que aporta el corpus (bloqueado por Ragas + promptfoo sin
+  ejecutar).
+- Hybrid model routing and the eval judge may use a hosted model; confirm a DPA covers any
+  patient data sent on the Claude route (the medGemma route stays fully self-hosted for the
+  privacy-default positioning).

README.md

@@ -8,6 +8,15 @@ pinned: false
 ---
 # Morphos — Intérprete de analíticas veterinarias asistido por I.A
 
+> ⚠️ **Este README describe la entrega original del curso (stack XAMPP: PHP + JS sin build).**
+> Ese stack ya no existe en el repo: `js/*.js`, `api/*.php` y `.htaccess` se eliminaron el
+> 2026-07-26 al completarse la migración a **Vite + TypeScript (`frontend/`) + FastAPI
+> (`backend/`)**. Las secciones de estructura, instalación (`setup.php`, XAMPP, MySQL) y
+> seguridad de abajo son **históricas, no instrucciones válidas**.
+>
+> Para ejecutar el proyecto hoy: `CLAUDE.md` (arquitectura actual) y `MIGRACION.md` (estado y
+> comandos). En resumen: `make frontend-install && make frontend-build && make backend-sync && make dev`.
+
 ## Proyecto final — Curso de Desarrollo Web 2026
 
 ---

books/README.md

@@ -0,0 +1,55 @@
+# Corpus de literatura veterinaria (RAG)
+
+Aquí van los libros con licencia que fundamentan las interpretaciones de la IA.
+**Este directorio se ignora en git** (contenido con derechos de autor) — ver `.gitignore`.
+
+## Layout esperado
+
+```
+books/
+├── Thrall_Veterinary_Hematology_ed3.pdf
+├── Thrall_Veterinary_Hematology_ed3.meta.json      (opcional, ver abajo)
+├── Weiss_Schalms_Veterinary_Hematology_ed7.pdf
+└── ...
+```
+
+## Convención de nombre
+
+`Autor_Titulo_edN.pdf` — la edición (`edN`) se detecta automáticamente.
+
+## Metadatos opcionales (sidecar)
+
+Para citas más precisas, añade un archivo hermano `<nombre>.meta.json`:
+
+```json
+{
+  "libro": "Thrall — Veterinary Hematology and Clinical Chemistry",
+  "edicion": "3.ª ed. (2022)",
+  "especie": ""
+}
+```
+
+- `especie`: dejar `""` si el libro cubre ambas; `"canino"` o `"felino"` si es específico
+  (permite filtrar la recuperación por especie del paciente).
+
+## Construir el índice
+
+Una vez colocados los PDFs:
+
+```bash
+make ingest        # equivale a: uv run --group rag python -m app.rag.ingest
+```
+
+Esto genera `instance/rag_index/` (LanceDB) con los fragmentos + embeddings y un
+`manifest.json` con la versión del corpus (para reproducibilidad de las evals).
+
+El índice se hornea de **sólo lectura** en la imagen Docker; no requiere almacenamiento
+persistente en HF Spaces. Reconstruir sólo cuando cambie el corpus.
+
+## Privacidad y copyright
+
+- El texto de los libros **nunca** se sirve al cliente ni sale del contenedor: la API
+  sólo pasa fragmentos cortos al modelo como contexto de fundamentación.
+- El índice vive en `instance/` (fuera del webroot), nunca bajo `data/` (que sí se sirve).
+- Los embeddings se generan con un modelo auto-alojado (`BAAI/bge-m3` por defecto), de modo
+  que el contenido no se envía a terceros durante la ingesta.