Etapa 0: entorno, configuración validada, modelo y entrenador

Base del proyecto ENLACE: un modelo de lenguaje propio entrenado desde cero,
en español, para asistencia general y familiar. El plan completo está en
docs/PLAN.md.

Esta etapa establece el andamiaje y lo verifica de punta a punta:

- Configuración por capas (hardware × model × train × data) validada con
  pydantic. Ningún hiperparámetro vive en el código y una config inválida
  falla al arrancar, no a las tres horas de entrenamiento.
- Perfiles de hardware que aíslan el salto de GPU: la RTX 2060 (Turing) no
  soporta bfloat16 ni FlashAttention-2, así que entrena en float16 con
  GradScaler y backend mem_efficient; el perfil de la 5090 ya está escrito.
  backends.py valida el perfil contra la GPU real antes de empezar.
- Transformer decoder-only estilo Llama: RMSNorm, SwiGLU, RoPE, GQA,
  embeddings atados, QK-norm y z-loss. Los dos últimos son lo que mantiene
  estable el entrenamiento en float16.
- Entrenador con schedule WSD, acumulación de gradiente, precisión mixta,
  checkpointing atómico y reanudación exacta.
- Cargadores de datos con estado serializable: bytes para el smoke test y
  shards uint16 para el corpus real.

48 tests, entre ellos el crítico: reanudar desde un checkpoint reproduce los
pesos de una corrida ininterrumpida, parámetro por parámetro.

Verificado en CPU: 300 pasos sobre texto en español, loss 3.07 -> 1.63.

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

README.md

@@ -0,0 +1,93 @@
+# ENLACE
+
+Modelo de lenguaje propio, entrenado desde cero, para asistencia general y
+familiar en español. No es fine-tuning de un modelo existente: tokenizer, datos
+y pesos son propios.
+
+El plan completo — etapas, presupuestos de cómputo, arquitectura de datos y
+criterios de verificación — está en `docs/PLAN.md`.
+
+## Estado
+
+Etapa 0 (entorno y validación del stack) implementada y verificada:
+
+- Capa de configuración validada, con composición por capas y perfiles de hardware.
+- Arquitectura del modelo: RMSNorm, SwiGLU, RoPE, GQA, QK-norm, z-loss.
+- Entrenador con WSD, precisión mixta, acumulación de gradiente y **reanudación exacta**.
+- Cargadores de datos: bytes (smoke test) y shards `uint16` (corpus real).
+- 48 tests, incluido el de reanudación exacta.
+
+Pendiente: Etapa 1 en adelante (corpus, tokenizer, pretraining, post-training,
+agente, bases del sistema, memoria, snapshots).
+
+## Puesta en marcha
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+
+scripts/prepare_smoke_data.sh          # texto en español de dominio público
+.venv/bin/python -m enlace.train.train configs/runs/smoke-cpu.yaml
+scripts/test.sh
+```
+
+En el servidor con GPU, por SSH (ver `.env.example`):
+
+```bash
+scripts/remote.sh sync
+scripts/remote.sh run configs/runs/smoke-2060.yaml     # smoke test, ~10 min
+scripts/remote.sh run configs/runs/pretrain-2060.yaml  # pretraining, 1-2 días
+scripts/remote.sh logs
+```
+
+Toda corrida larga arranca bajo `tmux`: cortar el SSH no mata el entrenamiento.
+
+## Configuración
+
+Ningún hiperparámetro vive en el código. Las configs se componen por capas:
+
+```yaml
+# configs/runs/pretrain-2060.yaml
+include:
+  hardware: hardware/turing-2060.yaml   # dtype, backend de atención, batch
+  model:    model/tiny-50m.yaml         # capas, dimensiones, contexto
+  train:    train/pretrain.yaml         # LR, schedule, intervalos
+  data:     data/corpus.yaml            # de dónde salen los tokens
+```
+
+Overrides puntuales desde la línea de comandos, para probar variantes sin editar
+archivos:
+
+```bash
+.venv/bin/python -m enlace.train.train configs/runs/smoke-cpu.yaml train.seed=99
+```
+
+Una config inválida falla al arrancar con un mensaje concreto, no a las tres
+horas de entrenamiento.
+
+## Hardware
+
+El perfil de hardware es la única capa que cambia al migrar de placa.
+
+| Perfil | Placa | dtype | Atención | Notas |
+|---|---|---|---|---|
+| `turing-2060` | RTX 2060 12 GB (sm_75) | float16 + GradScaler | mem_efficient | Turing no soporta bfloat16 ni FlashAttention-2 |
+| `blackwell-5090` | RTX 5090 32 GB (sm_120) | bfloat16 | flash | Requiere PyTorch ≥ 2.7 con CUDA 12.8 |
+| `cpu` | — | float32 | math | Solo desarrollo y tests |
+
+`enlace/train/backends.py` es el único archivo del entrenamiento que conoce
+diferencias entre placas, y valida el perfil contra la GPU real antes de
+empezar: pedir bfloat16 en Turing falla de inmediato en vez de degradarse en
+silencio.
+
+## Estructura
+
+```
+enlace/config/    Esquemas pydantic y composición de YAML
+enlace/model/     Transformer decoder-only y selección de backend de atención
+enlace/train/     Bucle, schedules, checkpointing, detección de hardware
+enlace/data/      Cargadores con reanudación exacta
+configs/          hardware × model × train × data, compuestos en configs/runs/
+scripts/          Utilidades: remote.sh, test.sh, prepare_smoke_data.sh
+tests/            Suite completa; test_resume.py es el crítico
+```