From 4d99213d756b919191150c4c142cb7580a30cc29 Mon Sep 17 00:00:00 2001
From: Daniel Arroyo <darroylat@gmail.com>
Date: Mon, 23 Mar 2026 17:09:44 -0300
Subject: [PATCH] Update README.md with MVP-1 documentation

---
 README.md | 131 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 130 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index f875f66..a29e5b7 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,131 @@
-# tracker
+# Personal Tracker
 
+Herramienta CLI para seguimiento de proyectos personales con foco en continuidad entre sesiones.
+
+## Características
+
+- **Persistencia simple**: Archivos Markdown y YAML legibles
+- **Sin dependencias cloud**: Todo funciona offline
+- **Kanban liviano**: TASKS.md con estados (Inbox, Next, Active, Blocked, Waiting, Done)
+- **Bitácora por sesiones**: LOG.md y archivos de sesión detallados
+- **Changelog**: Registro de cambios relevantes
+- **CLI intuitiva**: Comandos para iniciar, pausar y documentar trabajo
+
+## Stack
+
+- Python 3.11+
+- [Typer](https://typer.tiangolo.com/) - CLI
+- [PyYAML](https://pyyaml.org/) - Metadatos
+- [Jinja2](https://jinja.palletsprojects.com/) - Plantillas
+- [Pydantic](https://docs.pydantic.dev/) - Modelos
+
+## Instalación
+
+```bash
+pip install -e .
+```
+
+## Comandos
+
+| Comando | Descripción |
+|---------|-------------|
+| `tracker init-project <slug>` | Crear nuevo proyecto |
+| `tracker list` | Listar todos los proyectos |
+| `tracker show <slug>` | Ver detalles de un proyecto |
+| `tracker start <slug>` | Iniciar sesión de trabajo |
+| `tracker note <text>` | Agregar nota a la sesión activa |
+| `tracker stop <slug>` | Finalizar sesión y generar resumen |
+| `tracker change <slug>` | Agregar entrada al changelog |
+| `tracker next <slug>` | Sugerir próximos pasos |
+| `tracker review` | Vista general de todos los proyectos |
+
+## Estructura de un Proyecto
+
+```
+projects/<slug>/
+├── README.md           # Documentación principal
+├── LOG.md              # Bitácora de sesiones (append-only)
+├── CHANGELOG.md        # Registro de cambios
+├── TASKS.md            # Kanban liviano
+├── sessions/           # Sesiones detalladas
+├── docs/               # Documentación técnica
+├── assets/             # Recursos
+└── meta/
+    └── project.yaml    # Metadatos
+```
+
+## Flujo de Uso
+
+```bash
+# 1. Crear proyecto
+tracker init-project mi-proyecto --name "Mi Proyecto" --type code
+
+# 2. Iniciar sesión
+tracker start mi-proyecto --objective "Implementar feature X"
+
+# 3. Agregar notas durante el trabajo
+tracker note "Implementé la función base" --type work
+tracker note "Decidí usar PostgreSQL en vez de SQLite" --type decision
+
+# 4. Finalizar sesión
+tracker stop mi-proyecto
+
+# 5. Ver estado
+tracker show mi-proyecto
+tracker list
+```
+
+## Tipos de Nota
+
+- `work` - Trabajo realizado
+- `change` - Cambio realizado
+- `blocker` - Bloqueo encontrado
+- `decision` - Decisión tomada
+- `idea` - Idea o pensamiento
+- `reference` - Referencia o link
+
+## Estados de Proyecto
+
+- `inbox` - Recibido/revisar
+- `next` - Próximo a trabajar
+- `active` - En desarrollo activo
+- `blocked` - Bloqueado
+- `waiting` - En espera
+- `done` - Completado
+- `archived` - Archivado
+
+## Tipos de Proyecto
+
+- `code` - Desarrollo de software
+- `homelab` - Infraestructura personal
+- `automation` - Automatización
+- `agent` - Agentes/IA
+- `research` - Investigación
+- `misc` - Misceláneo
+
+## Proyecto Demo
+
+Ver `examples/demo-project/` para un proyecto de ejemplo completo.
+
+## Tests
+
+```bash
+pytest tests/ -v
+```
+
+## Desarrollo
+
+```bash
+# Estructura del paquete
+tracker/
+├── cli/        # Comandos CLI
+├── models/     # Modelos de datos
+├── services/   # Lógica de negocio
+├── storage/    # Persistencia archivos
+├── utils/      # Utilidades
+└── templates/  # Plantillas
+```
+
+## Licencia
+
+MIT