docs: README, ARCHITECTURE, roadmap futuro y manual de QA del dashboard

- README.md: pitch, arquitectura, quickstart, demo guiada en 3 pasos, tabla de
  capacidades, estructura del repo, comandos de tests.
- ARCHITECTURE.md: patrones (Strategy, config-over-code, fail-closed,
  trazabilidad), tabla de persistencia, patrón HITL, observabilidad, errores.
- docs/futuro.md: roadmap post-MVP.
- docs/manual_qa.md: checklist del smoke manual del dashboard (5 páginas + PII +
  persistencia).

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

ARCHITECTURE.md

@@ -0,0 +1,71 @@
+# AgentForge — Arquitectura técnica
+
+> Documento "vivo" con las decisiones técnicas. El spec original está en
+> [`docs/superpowers/specs/2026-05-09-agentforge-design.md`](docs/superpowers/specs/2026-05-09-agentforge-design.md).
+
+## Visión general
+
+Two-tier:
+- `agentforge-core` — FastAPI 8000. Dominio de gobierno, runtime LangGraph,
+  guardrails y persistencia.
+- `agentforge-dashboard` — Streamlit 8501. Cliente HTTP del core.
+
+## Diagrama
+
+```
+┌─────────────────────┐  HTTP/JSON  ┌─────────────────────┐
+│ Dashboard (Stream.) │ ───────────► │ Core (FastAPI)      │
+└─────────────────────┘              └─────────┬───────────┘
+                                               │
+            ┌─────────────────────────┬────────┴──────┬────────────┐
+            ▼                         ▼               ▼            ▼
+       LLM layer              Guardrails layer   LangGraph     State
+   (Strategy pattern)         (Strategy pattern)  Runtime      JSON+SQL+JSONL
+```
+
+## Patrones aplicados
+
+- **Strategy / Plugin**: `LLMProvider`, `GuardrailEngine`, `AgentRegistry`,
+  `PolicyStore` son `Protocol`s con varias implementaciones intercambiables
+  vía factory que lee `Settings`.
+- **Configuration over code**: agentes y políticas como YAML versionados;
+  cambios sin redeploy.
+- **Fail-closed por defecto**: errores en validadores cuentan como bloqueo.
+- **Trazabilidad obligatoria**: `trace_id` UUID propagado por
+  middleware → structlog → API → JSONL.
+
+## Persistencia
+
+| Capa | Tecnología | Por qué |
+|---|---|---|
+| Agent Registry | JSON + YAML | Humano lo escribe (YAML); máquina lo cataloga (index.yaml). |
+| Versionado | YAML por versión + index.yaml | Diff legible; hash SHA-256 normalizado. |
+| Logs de violaciones | JSONL append-only | Inmutable, auditable, fácil de shipear. |
+| Logs de ejecuciones | JSONL append-only | Idem. |
+| Checkpoints LangGraph | SQLite | Tool right; persistencia entre restarts (HITL). |
+
+## HITL — Patrón
+
+Se usa la API dinámica `interrupt(payload)` de LangGraph ≥0.2 dentro del
+nodo `approve_gate`. Sólo pausa cuando hay acciones de alto riesgo
+(`risk_score >= threshold` o `requires_approval=True`). El cliente envía
+`Command(resume={"approved_action_ids": [...]})` vía
+`POST /executions/{trace_id}/approve`.
+
+## Observabilidad
+
+- `structlog` con renderer JSON.
+- Middleware FastAPI inyecta `X-Trace-Id` y bind-ea contexto.
+- Cada nodo del grafo añade un step a `decision_path` con `duration_ms`.
+
+## Errores
+
+- Azure OpenAI / OpenAI: retry exponencial 1s/2s/4s, fallback opcional, luego
+  `status=failed`.
+- Validador: `fail_closed` por defecto.
+- Schema mismatch en LLM output: 1 retry, luego `failed`.
+- Checkpoint corrupto: 500 explícito (sin auto-recovery).
+
+## Decisiones pospuestas
+
+Ver [`docs/futuro.md`](docs/futuro.md).