diff --git a/README.md b/README.md
index 20d237a..10a2cb9 100644
--- a/README.md
+++ b/README.md
@@ -1,102 +1,328 @@
# Attack Surface Studio
-A Knowledge Graph platform for security reconnaissance and assessment. It orchestrates
-external security tools (Nmap, ffuf, Nuclei, …), normalizes their heterogeneous output into
-a single graph model, and turns an engagement's accumulated evidence — scans, manual
-findings, screenshots, notes, reports — into one navigable, queryable body of knowledge.
+**Plataforma de grafo de conocimiento para reconocimiento y evaluación de superficie de ataque.**
-The Knowledge Graph is the product. Security tools are data sources only: every adapter
-ultimately produces exactly three things — **Nodes**, **Edges**, and **Metadata** — and
-those are what the rest of the platform (UI, reports, AI assistant) reads from. See
-[`.claude/Claude.md`](.claude/Claude.md) for the full project philosophy and architecture
-docs (`ARCHITECTURE.md`, `DATA_MODEL.md`, `INTEGRATION_SYSTEM.md`, `SECURITY_MODEL.md`,
-`Plan.md`).
+Orquesta herramientas de seguridad externas (Nmap, ffuf, Nuclei), normaliza su salida heterogénea
+a un único modelo de grafo, y convierte la evidencia acumulada de un diagnóstico —escaneos,
+hallazgos manuales, capturas, notas, reportes— en un cuerpo de conocimiento navegable y consultable.
-## Stack
+> El grafo de conocimiento es el producto. Las herramientas de seguridad son solo fuentes de datos:
+> cada adaptador produce exactamente tres cosas —**Nodos**, **Aristas** y **Metadatos**— y eso es lo
+> que leen la interfaz, los reportes y el asistente de IA.
-| Layer | Choice |
+
+
+---
+
+## Índice
+
+- [Cómo funciona](#cómo-funciona)
+- [Capturas de pantalla](#capturas-de-pantalla)
+- [Stack tecnológico](#stack-tecnológico)
+- [Puesta en marcha](#puesta-en-marcha)
+- [Variables de entorno](#variables-de-entorno)
+- [Adaptadores y control de alcance](#adaptadores-y-control-de-alcance)
+- [Estructura del proyecto](#estructura-del-proyecto)
+- [Testing](#testing)
+- [Limitaciones conocidas](#limitaciones-conocidas)
+- [Documentación](#documentación)
+
+---
+
+## Cómo funciona
+
+El flujo es deliberadamente simple y verificable de punta a punta:
+
+1. **Registras un proyecto** con un alcance (`scope`) explícito de objetivos autorizados.
+2. **Lanzas una ejecución** eligiendo un adaptador de herramienta y un objetivo.
+3. **El orquestador valida el alcance** antes de ejecutar nada. Si el objetivo no está en el
+ `scope`, la ejecución se rechaza con `403 SCOPE_VIOLATION`.
+4. **El adaptador normaliza la salida** a nodos y aristas (`child_process` en local, Docker en modo
+ remoto) y un worker BullMQ la persiste en PostgreSQL.
+5. **El grafo se vuelve navegable**: activos, hallazgos, relaciones y su cronología.
+
+El control de alcance no es decorativo: se comprueba **antes de la ejecución**, no después.
+
+---
+
+## Capturas de pantalla
+
+Todas las capturas son de la aplicación en ejecución, con datos reales generados a través de la
+API y de la interfaz.
+
+### Acceso y proyectos
+
+
+
+  |
+  |
+
+
+ | Inicio de sesión y registro |
+
+
+
+
+
+  |
+  |
+
+
+ | Estado vacío y lista de proyectos |
+
+
+
+### Ejecuciones de herramientas
+
+| Formulario y estado inicial | Detalle de la ejecución |
+|---|---|
+|
|
|
+
+La vista de Runs muestra el formulario de ejecución (adaptador + objetivo) y el historial completo
+de ejecuciones con su estado y su duración.
+
+
+
+### Grafo de conocimiento
+
+Todo proyecto arranca sin descubrimientos, y se va llenando a medida que se ejecutan herramientas:
+
+| Proyecto recién creado | Grafo con activos y hallazgo |
+|---|---|
+|
|
|
+
+Y el detalle de un nodo concreto:
+
+
+
+> El grafo se renderiza en la vista **Timeline**, que es la que monta el motor de grafo con
+> dimensiones correctas. Ver [Limitaciones conocidas](#limitaciones-conocidas).
+
+### Evidencia, reportes, asistente y ajustes
+
+| Evidencia sin archivos | Evidencia del proyecto |
+|---|---|
+|
|
|
+
+| Reportes sin generar | Asistente de IA |
+|---|---|
+|
|
|
+
+El alcance autorizado del proyecto se gestiona desde la pestaña de ajustes:
+
+
+
+Y el constructor de reportes permite seleccionar los nodos del grafo que se incluirán:
+
+
+
+---
+
+## Stack tecnológico
+
+| Capa | Tecnología |
|---|---|
| Frontend | Next.js 16 (App Router), React 19, TypeScript strict, Tailwind v4, React Flow, Zustand, TanStack Query |
-| Backend | NestJS, TypeScript, Drizzle ORM, BullMQ (Redis-backed job queue) |
-| Database | PostgreSQL 16 |
-| Tool execution | `child_process` (local) / `dockerode` (Docker) behind a Tool Adapter registry (`nmap`, `ffuf`, `nuclei`, …) |
-| Auth | JWT (short-lived access + rotating refresh), Argon2id password hashing |
-| Testing | Vitest + Supertest (integration), Playwright (E2E) |
+| Backend | NestJS, TypeScript, Drizzle ORM, BullMQ (cola de trabajos con Redis) |
+| Base de datos | PostgreSQL 16 |
+| Ejecución de herramientas | `child_process` (local) / `dockerode` (Docker) tras un registro de adaptadores |
+| Autenticación | JWT (access corto + refresh rotativo), hash de contraseña Argon2id |
+| Testing | Vitest + Supertest (integración), Playwright (E2E) |
-## Project layout
+---
-```
-Attack Surface Studio/
-├── client/ Next.js frontend (marketing Hero + Graph Engine + authenticated Workspace)
-├── server/ NestJS backend (auth, orchestrator, adapters, knowledge graph, reports)
-├── db/ Postgres bootstrap scripts (docker-entrypoint-initdb.d)
-├── docker-compose.yml Local Postgres + Redis
-└── .claude/ Architecture and planning documentation (source of truth)
-```
+## Puesta en marcha
-## Prerequisites
+### Requisitos previos
- Node.js 20+
- [pnpm](https://pnpm.io/) 9
-- Docker (for local Postgres + Redis via `docker-compose`)
+- Docker (para PostgreSQL y Redis)
+
+### 1. Bases de datos
+
+```bash
+cp .env.example .env # completa los valores antes de usar nada que no sea local
+docker compose up -d # PostgreSQL en :5432, Redis en :6379
+```
-## Getting started
+El esquema se aplica automáticamente en el primer arranque gracias a
+[`db/init`](db/init) (montado como `docker-entrypoint-initdb.d`). Si necesitas reaplicar
+migraciones de forma explícita, usa `pnpm migrate` desde `server/`.
-1. **Start the datastores**
+### 2. Backend (`server/`)
- ```bash
- cp .env.example .env # fill in real values before running in anything but local dev
- docker-compose up -d
- ```
+```bash
+cd server
+pnpm install
+cp .env.example .env # DATABASE_URL, JWT_*, REDIS_URL, STORAGE_ROOT...
+pnpm migrate
+pnpm seed # opcional: carga un proyecto de ejemplo
+pnpm start:dev # API en http://localhost:3001
+```
-2. **Backend** (`server/`)
+> **Aviso sobre `pnpm seed`:** el usuario demo que crea el seed (`demo@attacksurfacestudio.dev`)
+> se genera con un hash de contraseña literal (`seed-placeholder`) que no es un hash Argon2id
+> válido, así que **no se puede iniciar sesión con él**. El seed sí sirve para tener un proyecto con
+> 26 nodos y 20 aristas que consultar. Para probar la aplicación, regístrate con una cuenta nueva
+> desde la interfaz.
- ```bash
- cd server
- pnpm install
- cp .env.example .env # DATABASE_URL, JWT secrets, REDIS_URL, etc. — see file comments
- pnpm migrate
- pnpm start:dev # API on http://localhost:3001
- pnpm start:worker:dev # separate process: executes queued tool runs
- ```
+El worker es un proceso separado y es quien ejecuta los trabajos de la cola:
-3. **Frontend** (`client/`)
+```bash
+pnpm start:worker:dev
+```
- ```bash
- cd client
- pnpm install
- cp .env.example .env # NEXT_PUBLIC_API_URL=http://localhost:3001
- pnpm dev # App on http://localhost:3000
- ```
+> **El worker es obligatorio.** La API encola los trabajos, pero sin el worker ninguna ejecución
+> avanza. Si lanzas una ejecución y se queda en `queued`, casi siempre es esto.
-4. Open [http://localhost:3000](http://localhost:3000). The landing page's "Request access" /
- "Sign in" buttons lead to `/register` and `/login`; once authenticated you land on `/app`.
+Para ejecutar en modo producción, compila primero y usa los scripts sin watcher:
+
+```bash
+pnpm build && pnpm start # en una terminal
+pnpm build && pnpm start:worker # en otra
+```
+
+### 3. Frontend (`client/`)
+
+```bash
+cd client
+pnpm install
+cp .env.example .env # NEXT_PUBLIC_API_URL=http://localhost:3001
+pnpm dev # http://localhost:3000
+```
+
+Para un build de producción: `pnpm build && pnpm start`.
+
+> `client/AGENTS.md` es un archivo generado y versionado por `next dev`. Si ejecutas el frontend con
+> `next start` evitas que se reescriba.
+
+### 4. Verificar que todo está en pie
+
+```bash
+curl http://localhost:3001/api/v1/health
+# {"success":true,"data":{"status":"ok","database":"up"}}
+```
+
+Después abre [http://localhost:3000](http://localhost:3000), regístrate y acabarás en `/app`.
+
+### Puertos
+
+| Servicio | Puerto |
+|---|---|
+| Frontend (Next.js) | 3000 |
+| API (NestJS) | 3001 |
+| PostgreSQL | 5432 (configurable con `POSTGRES_PORT`) |
+| Redis | 6379 (configurable con `REDIS_PORT`) |
+
+---
+
+## Variables de entorno
+
+| Archivo | Variables |
+|---|---|
+| `.env` (raíz) | `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_PORT`, `APP_DB_USER`, `APP_DB_PASSWORD` |
+| `server/.env` | `PORT`, `CORS_ORIGINS`, `DATABASE_URL`, `APP_DATABASE_URL`, `JWT_ACCESS_SECRET`, `JWT_ACCESS_TTL`, `JWT_REFRESH_TTL`, `REDIS_URL`, `STORAGE_ROOT`, `THROTTLE_TTL_MS`, `THROTTLE_LIMIT`, `NVIDIA_*` |
+| `client/.env` | `NEXT_PUBLIC_API_URL` |
+
+`server/` y `client/` son proyectos pnpm independientes: no hay workspace en la raíz, así que los
+comandos se ejecutan dentro de cada directorio.
+
+`NVIDIA_API_KEY` es opcional. Sin ella el asistente de IA no puede responder.
+
+---
+
+## Adaptadores y control de alcance
+
+Los adaptadores registrados son `stub`, `nmap`, `ffuf` y `nuclei`. El adaptador `stub` genera
+salida determinista sin tocar la red, y es el recomendado para desarrollo y para las pruebas
+automatizadas.
+
+Cada ejecución exige que el objetivo esté autorizado en el `scope` del proyecto
+(`includes` / `excludes`, con entradas de tipo hostname, dominio comodín, IP o CIDR). Un proyecto
+sin scope no puede ejecutar nada:
+
+```
+POST /api/v1/projects/:id/runs
+→ 403 {"error":{"code":"SCOPE_VIOLATION",
+ "message":"Target \"example.com\" is outside the project's authorized scope"}}
+```
+
+El scope se configura en la pestaña **Settings** del proyecto.
+
+---
+
+## Estructura del proyecto
+
+```
+Attack Surface Studio/
+├── client/ Frontend Next.js (Hero público + motor de grafo + workspace autenticado)
+├── server/ Backend NestJS (auth, orquestador, adaptadores, grafo, reportes)
+├── db/init/ Scripts de arranque de PostgreSQL
+├── screenshots/ Capturas de la interfaz usadas en este README
+├── docker-compose.yml PostgreSQL + Redis locales
+└── .claude/ Documentación de arquitectura y planificación
+```
+
+---
## Testing
```bash
# Frontend
-cd client && pnpm test # Vitest + Testing Library
-cd client && pnpm e2e # Playwright
+cd client && pnpm test
+cd client && pnpm e2e
# Backend
-cd server && pnpm test # Vitest + Supertest
+cd server && pnpm test
cd server && pnpm test:coverage
```
-Both projects enforce an 80% coverage floor. Adapter tests run against recorded real tool
-output fixtures rather than live scans.
+Ambos proyectos exigen un piso de cobertura del 80%. Las pruebas de adaptadores se ejecutan
+contra fixtures de salida real grabada, no contra escaneos en vivo.
+
+---
+
+## Limitaciones conocidas
+
+Documentadas de forma explícita, con el comportamiento observado:
+
+- **La pestaña Graph no renderiza el lienzo.** El contenedor de React Flow colapsa a altura `0`
+ (`1600x0` medido), así que la vista queda vacía aunque la API devuelva correctamente los nodos y
+ el cliente los lea bien. El problema es de maquetación en cliente, no de datos. Curiosamente, la
+ vista **Timeline** monta el mismo motor con dimensiones correctas y sí dibuja el grafo, así que
+ sirve como workaround. El commit `148c9` (`BUG #7`) ya intentó resolver exactamente esto aplicando
+ `absolute inset-0` en `WorkspaceGraphView`, y el fallo persiste: parece una regresión de aquel
+ arreglo o un caso que no cubría.
+- **`/docs` devuelve 404.** La ruta no existe aunque el navbar incluya un enlace a ella.
+- **El ensamblado de reportes está bloqueado por lo anterior.** El constructor exige seleccionar al
+ menos un nodo del grafo, y la pestaña Graph no los dibuja, así que por la interfaz no se puede
+ completar un reporte. El backend sí expone el recurso.
+- **El asistente de IA requiere `NVIDIA_API_KEY`.** Sin la clave responde en estado degradado.
+- **`pnpm seed` genera un usuario demo inutilizable.** Su hash de contraseña es un placeholder, no
+ un hash Argon2id real, así que el login con `demo@attacksurfacestudio.dev` falla siempre. Los datos
+ del seed sí sirven como referencia.
+
+---
+
+## Documentación
+
+El repositorio incluye la documentación siguiente:
+
+- [`.claude/New_files.md`](.claude/New_files.md) — registro de archivos previstos en la Fase 1
+- [`client/e2e/README.md`](client/e2e/README.md) — requisitos y ejecución de las pruebas E2E
+- [`client/AGENTS.md`](client/AGENTS.md) — bloque de reglas de Next.js, generado y versionado
+- [`docker-compose.yml`](docker-compose.yml) y [`db/init/`](db/init) — infraestructura local
+
+Los documentos de arquitectura (`ARCHITECTURE.md`, `DATA_MODEL.md`, `SECURITY_MODEL.md`,
+`INTEGRATION_SYSTEM.md`) que se mencionaban en versiones anteriores de este README **no están
+presentes en el repositorio**, así que se han retirado los enlaces en lugar de dejarlos rotos. El
+código y los contratos de TypeScript son hoy la fuente de verdad: los tipos del modelo de grafo
+viven en `server/src/modules/projects` y `client/src/modules/graph-engine/types`.
+
+---
-## Documentation
+## Licencia
-Everything beyond this quick-start — vision, data model, security posture, the phased
-roadmap, and the development log — lives in [`.claude/`](.claude):
+Proyecto de portafolio. Sin licencia pública declarada.
-- [`Claude.md`](.claude/Claude.md) — vision, philosophy, stack, standards (start here)
-- [`ARCHITECTURE.md`](.claude/ARCHITECTURE.md) — system decomposition
-- [`DATA_MODEL.md`](.claude/DATA_MODEL.md) — PostgreSQL schema for the graph
-- [`INTEGRATION_SYSTEM.md`](.claude/INTEGRATION_SYSTEM.md) — the Tool Adapter contract
-- [`SECURITY_MODEL.md`](.claude/SECURITY_MODEL.md) — cross-cutting security posture
-- [`Plan.md`](.claude/Plan.md) — the phased roadmap
-- [`Progress.md`](.claude/Progress.md) — development log
-- [`Routes.md`](.claude/Routes.md) — routing registry
diff --git a/screenshots/01-landing.png b/screenshots/01-landing.png
new file mode 100644
index 0000000..3c3b8bd
Binary files /dev/null and b/screenshots/01-landing.png differ
diff --git a/screenshots/02-login.png b/screenshots/02-login.png
new file mode 100644
index 0000000..8c509a6
Binary files /dev/null and b/screenshots/02-login.png differ
diff --git a/screenshots/03-register.png b/screenshots/03-register.png
new file mode 100644
index 0000000..abf9ad8
Binary files /dev/null and b/screenshots/03-register.png differ
diff --git a/screenshots/04-projects-vacio.png b/screenshots/04-projects-vacio.png
new file mode 100644
index 0000000..fbc1b19
Binary files /dev/null and b/screenshots/04-projects-vacio.png differ
diff --git a/screenshots/05-grafo-sin-datos.png b/screenshots/05-grafo-sin-datos.png
new file mode 100644
index 0000000..1b06b5b
Binary files /dev/null and b/screenshots/05-grafo-sin-datos.png differ
diff --git a/screenshots/06-runs-vacio.png b/screenshots/06-runs-vacio.png
new file mode 100644
index 0000000..f932371
Binary files /dev/null and b/screenshots/06-runs-vacio.png differ
diff --git a/screenshots/07-evidencia-vacia.png b/screenshots/07-evidencia-vacia.png
new file mode 100644
index 0000000..5549546
Binary files /dev/null and b/screenshots/07-evidencia-vacia.png differ
diff --git a/screenshots/08-reportes-vacio.png b/screenshots/08-reportes-vacio.png
new file mode 100644
index 0000000..f4c4132
Binary files /dev/null and b/screenshots/08-reportes-vacio.png differ
diff --git a/screenshots/09-proyectos.png b/screenshots/09-proyectos.png
new file mode 100644
index 0000000..65cfbd5
Binary files /dev/null and b/screenshots/09-proyectos.png differ
diff --git a/screenshots/10-runs.png b/screenshots/10-runs.png
new file mode 100644
index 0000000..5f4b9c6
Binary files /dev/null and b/screenshots/10-runs.png differ
diff --git a/screenshots/11-run-detalle.png b/screenshots/11-run-detalle.png
new file mode 100644
index 0000000..e8fa0a2
Binary files /dev/null and b/screenshots/11-run-detalle.png differ
diff --git a/screenshots/12-grafo.png b/screenshots/12-grafo.png
new file mode 100644
index 0000000..c86814e
Binary files /dev/null and b/screenshots/12-grafo.png differ
diff --git a/screenshots/13-grafo-nodo.png b/screenshots/13-grafo-nodo.png
new file mode 100644
index 0000000..3f4206d
Binary files /dev/null and b/screenshots/13-grafo-nodo.png differ
diff --git a/screenshots/14-evidencia.png b/screenshots/14-evidencia.png
new file mode 100644
index 0000000..fd74bf4
Binary files /dev/null and b/screenshots/14-evidencia.png differ
diff --git a/screenshots/15-assistant.png b/screenshots/15-assistant.png
new file mode 100644
index 0000000..81a4ca9
Binary files /dev/null and b/screenshots/15-assistant.png differ
diff --git a/screenshots/16-settings-scope.png b/screenshots/16-settings-scope.png
new file mode 100644
index 0000000..621b211
Binary files /dev/null and b/screenshots/16-settings-scope.png differ
diff --git a/screenshots/17-report-builder.png b/screenshots/17-report-builder.png
new file mode 100644
index 0000000..cb33571
Binary files /dev/null and b/screenshots/17-report-builder.png differ