diff --git a/README.md b/README.md
new file mode 100644
index 0000000..80f4e20
--- /dev/null
+++ b/README.md
@@ -0,0 +1,85 @@
+# Task Challenge API
+
+Backend para gestión de tareas con máquina de estados y persistencia en PostgreSQL.
+
+## Stack
+
+- **Runtime:** Node.js + TypeScript
+- **Framework:** Hono
+- **ORM:** Prisma (PostgreSQL)
+- **Testing:** Jest
+- **Package Manager:** pnpm
+
+## Arquitectura
+
+Se optó por **Clean Architecture** con separación en capas:
+
+```
+src/
+├── domain/          # Entidades, interfaces de repositorio
+├── application/     # Casos de uso, lógica de negocio
+├── infrastructure/  # Implementaciones concretas (Prisma)
+├── presentation/    # Controllers, rutas, middleware
+└── shared/          # DTOs, errores, utilidades
+```
+
+**Por qué esta arquitectura:**
+
+- El dominio no depende de frameworks ni librerías externas. Si mañana cambiamos Prisma por Drizzle o Hono por Express, solo tocamos `infrastructure` y `presentation`.
+- Los tests unitarios mockean los repositorios sin necesidad de levantar una base de datos.
+- Cada capa tiene una responsabilidad clara, lo que facilita el onboarding y el mantenimiento a largo plazo.
+
+## Modelo de datos
+
+La entidad central es `Task` con una máquina de estados:
+
+```
+new → active → resolved → closed
+              ↑__________|
+```
+
+- Cada transición queda registrada en `StateHistory` con timestamp.
+- Las notas se persisten como relación hija de la tarea.
+- Soft delete mediante `deletedAt` (no se borra físicamente).
+
+## Endpoints
+
+| Método | Ruta | Descripción |
+|--------|------|-------------|
+| GET | `/api/tasks` | Listar tareas |
+| GET | `/api/tasks/:id` | Obtener tarea por ID |
+| POST | `/api/tasks` | Crear tarea |
+| PUT | `/api/tasks/:id` | Actualizar tarea |
+| DELETE | `/api/tasks/:id` | Soft delete |
+| PATCH | `/api/tasks/:id/transition` | Cambiar estado |
+| POST | `/api/tasks/:id/notes` | Agregar nota |
+| DELETE | `/api/tasks/:id/notes/:index` | Eliminar nota |
+| GET | `/api/states` | Listar estados válidos |
+
+## Variables de entorno
+
+```env
+DATABASE_URL=postgresql://user:password@host:5432/dbname?schema=public
+PORT=3000
+NODE_ENV=production
+```
+
+## Scripts
+
+```bash
+pnpm dev            # Desarrollo con hot reload
+pnpm build          # Compilar TypeScript
+pnpm start          # Ejecutar con tsx
+pnpm start:prod     # Ejecutar JS compilado
+pnpm test           # Tests unitarios
+pnpm test:watch     # Tests en modo watch
+pnpm db:migrate     # Ejecutar migraciones
+pnpm db:seed        # Seed de datos
+pnpm db:reset       # Reset DB + migraciones + seed
+```
+
+## Deploy
+
+El proyecto corre en Dokploy con Docker. El `Dockerfile` ejecuta `prisma migrate deploy` antes de levantar el servidor.
+
+CORS restringido a `https://emi.challenge.berand97.dev` en producción.