diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..eb06f34
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,40 @@
+# Claude Usage Tracker — extensión de Chrome (MV3)
+
+Extensión de navegador (Manifest V3) que **mejora la página de uso de Claude** (`https://claude.ai/settings/usage`): parte la barra de cuota semanal en los 7 días, muestra info de sesión, y añade un FAB con el uso usado/ideal. Todo local en el navegador; no manda nada a ningún servidor.
+
+**Objetivo de este proyecto**: iterar sobre la extensión para mejorarla. No hay build ni servidor — es JS/CSS vanilla que se **carga sin empaquetar** en Chrome/Edge y actúa como *content script* sobre claude.ai.
+
+## Tu rol
+
+Eres experto en **extensiones Chrome MV3** y en la estructura del DOM de la página de uso de claude.ai. Mejora la extensión con cambios mínimos y probados. No inventes un pipeline: aquí no hay npm, ni bundler, ni tests automatizados — se edita el fichero y se recarga en el navegador.
+
+## Ficheros
+
+| Fichero | Qué es |
+|---|---|
+| `manifest.json` | MV3. `permissions: ["storage"]`, `content_scripts` con `matches: ["https://claude.ai/*"]`, `run_at: document_idle`, inyecta `content.js` + `styles.css`. **No** declara iconos ni `action`/popup ni `background` → es puramente content script |
+| `content.js` (~38 KB) | El motor. Escanea el DOM de la página de uso, extrae el % de uso, dibuja el tracker semanal (7 días, verde/amarillo/rojo), la info de sesión (inicio/actual/duración) y el FAB miniatura (usado/ideal de sesión y semanal). Sesión guardada en `localStorage` (`claude_usage_tracker_session`, ventana de 4 h). Incluye una config de promo **"Boost 2×"** con fechas *hardcodeadas* (marzo 2026, peak hours ET) |
+| `styles.css` (~11 KB) | Estilos del tracker, FAB y modal |
+| `use.html` (~82 KB) | **Snapshot** de la página real de uso (`data-org-plan="claude_max"`, dark). Es el DOM que `content.js` debe parsear → úsalo como *fixture* para razonar sobre selectores sin depender de la web viva |
+| `icons/icon.svg` | Icono fuente. **No hacen falta PNGs** (el manifest v3 no referencia iconos; el README los pedía pero está obsoleto) |
+| `README.md` | Descripción de features + instalación (ojo: el paso "crear iconos PNG" está desfasado) |
+
+## Cómo desarrollar y probar
+
+1. Editar `content.js` / `styles.css`.
+2. Cargar sin empaquetar (una vez): `chrome://extensions` → **Modo de desarrollador** → **Cargar extensión sin empaquetar** → esta carpeta.
+3. Tras cada cambio: botón **↻ recargar** de la extensión en `chrome://extensions` **y** recargar la pestaña `https://claude.ai/settings/usage`.
+4. Para iterar sobre la lógica de parseo sin la web viva, abrir `use.html` en el navegador y probar contra ese DOM.
+
+"Instalar" (cuando esté lista) = exactamente el paso 2. No hay despliegue web.
+
+## Gotchas
+
+- **Frágil ante cambios de claude.ai**: los selectores de `content.js` dependen de la estructura real de `claude.ai/settings/usage`, que Anthropic cambia sin avisar. Si el tracker deja de pintar, lo primero es re-inspeccionar el DOM (y el `use.html` snapshot puede haber quedado desfasado → recapturarlo).
+- **Config "Boost 2×" caduca**: fechas de marzo 2026 hardcodeadas en `content.js` (`BOOST_END_DATE`, `PEAK_START_UTC`…). Revisar si sigue vigente o generalizar.
+- **Supuestos del cálculo**: asume reinicio semanal los **lunes** y uso ideal 100%/7 ≈ **14.29%/día**. El ciclo real de cuota de Anthropic puede no ser semanal-lunes; verificar antes de fiarse de los colores.
+- **Privacidad**: los datos de sesión viven solo en `localStorage`; nada sale a servidores. Mantenerlo así.
+
+## Git
+
+Repo privado en Gitea: `https://git.carlosnarro.com/carlos/claude-use-extension` (rama `main`). No hay CI/deploy — commit + push y ya.