@handsupmin/gc-tree 0.1.4 → 0.2.1

package/README.es.md

@@ -19,44 +19,33 @@ Gestiona varios contextos con la misma naturalidad con la que manejas ramas de G
 
 </div>
 
-Hecho para quienes trabajan de verdad entre varios repositorios, productos, clientes y flujos de trabajo.
-
-`gc-tree` añade a tus herramientas de programación con IA una **capa de contexto reutilizable por encima del repo**. Conserva el contexto que dura, lo aplica solo donde corresponde y se aparta cuando el repositorio actual no tiene nada que ver.
-
 ---
 
-## Por qué gc-tree
+## El problema
 
-En cuanto empiezas a usar agentes de IA en trabajo real, el contexto local al repositorio se queda corto enseguida.
+Usas Claude Code o Codex a diario. Pero tu trabajo real se extiende por múltiples repositorios, productos y clientes — y tus herramientas de IA solo conocen el archivo actual.
 
-Cuando tu día a día se reparte entre varios repos y varias líneas de trabajo, suelen aparecer los mismos problemas:
+Así que acabas haciendo esto cada vez:
 
-- el contexto duradero acaba metido a la fuerza en los prompts
-- el contexto que no toca se cuela en repositorios donde no debería
-- cada sesión nueva obliga a repetir la misma explicación
-- el conocimiento de cliente o producto vive escondido en el historial del chat
-- cambiar de workstream significa cambiar de contexto a mano, en tu propia cabeza
+- Volver a explicar qué repositorios van juntos
+- Pegar el mismo documento de arquitectura en el prompt otra vez
+- Recordarle al agente las convenciones que ya "sabía" la semana pasada
+- Eliminar manualmente el contexto irrelevante para el repositorio actual
 
-`gc-tree` está pensado para gente que ya usa a fondo herramientas como Codex o Claude Code y no quiere seguir gestionando el contexto como una tarea manual más.
+Esto no es un problema de IA. Es un **problema de gestión del contexto**.
 
 ---
 
-## Qué te da
-
-- **Varios contextos duraderos**
-  Puedes mantener carriles separados por producto, cliente o workstream.
+## Para quién es esto
 
-- **Relevancia acotada por repositorio**
-  Puedes decidir con claridad qué contexto debe aplicarse solo a qué repos.
+Sacarás más partido a `gc-tree` si:
 
-- **Protección de alcance más inteligente**
-  Si entras en un repo todavía no asociado, puedes elegir si seguir solo esta vez, usar siempre ese contexto ahí o ignorarlo en ese repo.
+- Trabajas en **múltiples repositorios** (equipos con monorepo, repos de plataforma + cliente, stacks de backend + frontend)
+- Cambias entre **múltiples productos o clientes** en la misma semana
+- Te encuentras **explicando el mismo contexto** al inicio de cada sesión de IA
+- Quieres que tus herramientas de IA entiendan tus **convenciones, arquitectura y conocimiento de dominio** — no solo el archivo actual
 
-- **Onboarding y actualizaciones guiadas**
-  Puedes crear y mantener el contexto con Codex, Claude Code o ambos.
-
-- **Conocimiento en markdown, con enfoque summary-first**
-  El contexto vive en archivos visibles, no en memoria oculta, y las herramientas pueden leer primero el resumen corto.
+Si solo trabajas en un repositorio y un producto, no necesitas esto. `CLAUDE.md` o `.cursorrules` es suficiente.
 
 ---
 
@@ -67,166 +56,193 @@ npm install -g @handsupmin/gc-tree
 gctree init
 ```
 
-Con eso ya puedes arrancar.
-A partir de ahí, sigue trabajando como siempre: `gc-tree` simplemente añade una capa de contexto global reutilizable alrededor de tu flujo habitual.
+`gctree init` te guía a través de:
 
-- **Comando CLI:** `gctree`
-- **Requisito:** Node.js 20+
+1. Elegir provider: `claude-code`, `codex` o `both`
+2. Instalar los archivos de integración en el repositorio actual
+3. Completar el onboarding guiado para el gc-branch `main`
 
-Si quieres trabajar desde el código fuente, consulta [docs/local-development.es.md](https://github.com/handsupmin/gc-tree/blob/main/docs/local-development.es.md).
+Después, tu herramienta de IA aprenderá a llamar a `gctree resolve` antes de planificar o implementar.
+
+- **CLI:** `gctree`
+- **Requisito:** Node.js 20+
 
 ---
 
-## Movimientos habituales
+## Qué hace gc-tree
 
-### Crea un contexto nuevo cuando un workstream merezca su propio carril
+`gc-tree` opera **por encima del nivel del repositorio**. Almacena contexto en archivos Markdown estructurados y permite que tus herramientas de IA traigan solo lo relevante antes de cada sesión, de forma automática.
 
 ```bash
-gctree checkout -b client-b
-gctree onboard
+gctree resolve --query "auth token rotation policy"
 ```
 
-Si un cliente, un producto, una migración o una iniciativa concreta necesita su propio contexto duradero, dale su propio gc-branch.
-
-### Actualiza después el contexto duradero
-
-```bash
-gctree update-global-context
+```json
+{
+  "gc_branch": "main",
+  "matches": [
+    {
+      "title": "Convenciones de Auth y Sesión",
+      "score": 4,
+      "summary": "Rotation de JWT en cada petición, refresh tokens en cookies httpOnly, TTL de 15 min para access tokens",
+      "excerpt": "## Flujo de Auth\nAccess token: TTL 15 min, rotation en cada petición autenticada..."
+    }
+  ]
+}
 ```
 
-A medida que el trabajo avanza, añade al gc-branch activo lo que merece quedarse a largo plazo.
+Tu herramienta de IA recibe el contexto correcto — no toda la base de conocimiento, solo el fragmento relevante.
 
-Alias cortos:
+**En la práctica: solo ~4% del contexto total se inyecta por consulta.** El 96% restante permanece en disco, fuera de la ventana de tokens, hasta que de verdad haga falta.
 
-```bash
-gctree update-gc
-gctree ugc
-```
+---
 
-### Resuelve el contexto cuando de verdad lo necesites
+## ¿En qué se diferencia de CLAUDE.md o cursor rules?
 
-```bash
-gctree resolve --query "auth token rotation"
-```
+`CLAUDE.md` es genial — para un solo repositorio.
+
+En el momento en que tienes múltiples repos, clientes o workstreams:
 
-Trae de vuelta el contexto relevante justo en el momento en que hace falta.
+|                            | `CLAUDE.md` / cursor rules | `gc-tree`                                     |
+| -------------------------- | -------------------------- | --------------------------------------------- |
+| Alcance                    | Un repositorio             | Múltiples repos, un contexto                  |
+| Persistencia               | Archivo dentro del repo    | Almacenado fuera, reutilizable entre sesiones |
+| Cambio de contexto         | Edición manual de archivos | `gctree checkout client-b`                    |
+| Filtrado por relevancia    | Todo o nada                | Solo inyecta docs coincidentes (~4%)          |
+| Onboarding                 | Escrito a mano             | Guiado por tu herramienta de IA               |
+| Compatible con Codex       | ✅                         | ✅                                            |
+| Compatible con Claude Code | ✅                         | ✅                                            |
 
 ---
 
-## Por qué se siente natural
+## Rendimiento validado
 
-**Puedes manejar varios contextos como si fueran ramas de Git, pero sin tener que vivir pendiente de ellos.**
+Probado con documentación interna real (4 exportaciones de Notion, consultas mixtas en español e inglés):
 
-Puedes separar contextos para:
+| Métrica                                                      | Resultado        |
+| ------------------------------------------------------------ | ---------------- |
+| Recall — consultas relevantes que encuentran el doc correcto | **100%** (16/16) |
+| Precision — consultas irrelevantes que devuelven vacío       | **80%** (4/5)    |
+| F1 score                                                     | **88.9%**        |
+| Tokens inyectados por consulta vs. contexto total            | **~4%**          |
+| Compatible con consultas mixtas en varios idiomas            | ✅               |
 
-- un cliente
-- una línea de producto
-- un equipo de plataforma
-- un stack compartido de backend + frontend
-- una iniciativa temporal o una migración
+---
 
-Y moverte entre ellos con comandos familiares:
+## Funciona con Claude Code y Codex — ambos verificados
 
 ```bash
-gctree checkout -b client-b
-gctree checkout main
+gctree scaffold --host claude-code   # instala snippet en CLAUDE.md + /gc-onboard, /gc-update-global-context
+gctree scaffold --host codex         # instala snippet en AGENTS.md + $gc-onboard, $gc-update-global-context
+gctree scaffold --host both          # ambos a la vez
 ```
 
-Pero, a diferencia de Git, no tienes que vigilar ese cambio manualmente todo el tiempo.
+Los dos providers usan el mismo almacén de contexto. Haz el onboarding una vez y úsalo desde cualquiera de los dos.
 
-Si el repo en el que estás queda fuera del alcance del contexto activo, `gc-tree` puede tratar ese contexto como irrelevante en lugar de dejar que se cuele en la sesión equivocada.
+**Claude Code** — usa los slash commands `/gc-resolve-context`, `/gc-onboard`, `/gc-update-global-context`.
 
-Eso te permite mantener varios contextos a largo plazo sin arrastrarlos todos a cada sesión de trabajo.
+**Codex** — usa los skills `$gc-resolve-context`, `$gc-onboard`, `$gc-update-global-context`. Verificado con `codex exec`:
 
----
+```
+gctree status → gc_branch: main, doc_count: 2
+gctree resolve --query 'NestJS DTO plainToInstance'
+→ coincidencia con "Convenciones de Backend" (score: 3)
+→ DTO: class-transformer plainToInstance, class-validator obligatorio
+→ Manejo de errores: excepciones personalizadas basadas en HttpException, prohibido lanzar raw Error
+```
 
-## Un flujo de trabajo realista
+---
 
-Imagina que trabajas entre:
+## Movimientos habituales
 
-- un repo compartido de plataforma
-- dos repos de cliente
-- un repo de tooling interno
+### Contextos separados para workstreams distintos
 
-Sin `gc-tree`, cada sesión nueva con IA obliga a volver a explicar:
+```bash
+gctree checkout -b client-b
+gctree onboard
+```
 
-- de qué cliente estamos hablando ahora
-- qué repos forman realmente un mismo conjunto
-- qué flujo importa en este contexto
-- qué contexto sobra y solo mete ruido
+Cada gc-branch es un carril de contexto completamente independiente. Cambia entre ellos como con ramas de Git.
 
-Con `gc-tree`, puedes mantener contextos separados por carril, reutilizarlos entre sesiones y dejar que las reglas de repo scope bloqueen el contexto que no toca.
+### Traer contexto relevante cuando lo necesitas
 
-Ese es el trabajo real que resuelve:
+```bash
+gctree resolve --query "billing retry policy"
+```
 
-> no “guardar más texto de prompt”,
-> sino **gestionar el contexto correcto en el nivel correcto del trabajo**.
+Solo devuelve los docs que coinciden — título, resumen y fragmento. El tool lee el doc completo únicamente si el resumen no es suficiente.
 
----
+### Mantener el contexto al día
 
-## Conceptos clave
+```bash
+gctree update-global-context   # o: gctree update-gc / gctree ugc
+```
 
-- **gc-branch**
-  Un carril de contexto duradero para un producto, cliente, workstream o dominio.
+Flujo de actualización guiado — tu herramienta de IA pregunta qué ha cambiado y escribe el nuevo contexto de vuelta al gc-branch.
 
-- **repo scope**
-  Las reglas que deciden en qué repositorios debe aplicarse un contexto.
+### Acotar el contexto a repos específicos
 
-- **provider-guided flow**
-  En vez de escribir JSON a mano, haces onboarding y actualizaciones desde tu herramienta de IA preferida.
+```bash
+gctree set-repo-scope --branch client-b --include   # incluir el repo actual
+gctree set-repo-scope --branch client-b --exclude   # excluir el repo actual
+```
 
-- **context tree**
-  Por dentro, `gc-tree` organiza el contexto como conocimiento en archivos, consciente de las ramas.
-  Lo que tú ganas es contexto reutilizable más allá de un solo proyecto.
+`gc-tree` no inyectará un contexto en repos donde no corresponde.
 
 ---
 
-## Comandos visibles dentro del runtime
-
-Después del scaffold, los comandos visibles son:
+## Cómo se almacena el contexto
 
-- **Codex:** `$gc-onboard`, `$gc-update-global-context`
-- **Claude Code:** `/gc-onboard`, `/gc-update-global-context`
+```
+~/.gctree/
+  branches/
+    main/
+      index.md          ← índice compacto, ≤2000 chars, se carga primero
+      docs/
+        auth.md         ← doc completo, se lee solo cuando hace falta
+        architecture.md
+    client-b/
+      index.md
+      docs/
+        ...
+  branch-repo-map.json  ← qué repos pertenecen a qué gc-branch
+  settings.json         ← provider preferido, idioma
+```
 
-Esos comandos deben dejar claro cuál es el gc-branch activo antes de empezar a recoger o actualizar contexto duradero, y también deben mantener el idioma guardado hasta el final, salvo que el usuario pida cambiarlo explícitamente.
+El contexto vive fuera de tus repositorios — sin reglas de `.gitignore`, sin commits accidentales, reutilizable en todos los proyectos que usen el mismo gc-branch.
 
 ---
 
-## Comandos clave de un vistazo
-
-| Objetivo | Comando |
-| --- | --- |
-| Inicializar gc-tree y elegir provider | `gctree init` |
-| Confirmar el gc-branch activo | `gctree status` |
-| Buscar en el contexto activo | `gctree resolve --query "..."` |
-| Ver las reglas de alcance por repo | `gctree repo-map` |
-| Incluir o excluir un repo para un gc-branch | `gctree set-repo-scope --branch <name> --include` / `--exclude` |
-| Crear o cambiar gc-branches | `gctree checkout <branch>` / `gctree checkout -b <branch>` |
-| Hacer onboarding de un gc-branch vacío | `gctree onboard` |
-| Actualizar el gc-branch activo | `gctree update-global-context` / `gctree update-gc` / `gctree ugc` |
-| Restablecer un gc-branch antes de re-onboard | `gctree reset-gc-branch --branch <name> --yes` |
-| Instalar scaffold manualmente en otro entorno | `gctree scaffold --host codex --target /path/to/repo` |
+## Comandos principales
+
+| Objetivo                                           | Comando                                                         |
+| -------------------------------------------------- | --------------------------------------------------------------- |
+| Inicializar gc-tree y elegir provider              | `gctree init`                                                   |
+| Confirmar el gc-branch activo                      | `gctree status`                                                 |
+| Buscar en el contexto activo                       | `gctree resolve --query "..."`                                  |
+| Crear o cambiar gc-branches                        | `gctree checkout <branch>` / `gctree checkout -b <branch>`      |
+| Listar todos los gc-branches                       | `gctree branches`                                               |
+| Onboarding guiado de un gc-branch vacío            | `gctree onboard`                                                |
+| Actualización guiada del gc-branch activo          | `gctree update-global-context` / `gctree ugc`                   |
+| Ver reglas de alcance por repo                     | `gctree repo-map`                                               |
+| Incluir o excluir el repo actual para un gc-branch | `gctree set-repo-scope --branch <name> --include` / `--exclude` |
+| Resetear un gc-branch antes de re-onboard          | `gctree reset-gc-branch --branch <name> --yes`                  |
+| Instalar scaffold en un nuevo entorno              | `gctree scaffold --host codex --target /path/to/repo`           |
 
 ---
 
 ## Documentación
 
-La documentación detallada está en el directorio [`docs/`](https://github.com/handsupmin/gc-tree/tree/main/docs).
-
 - **Concepto** — [`docs/concept.es.md`](https://github.com/handsupmin/gc-tree/blob/main/docs/concept.es.md)
-  Explica qué es `gctree`, qué problema resuelve y cuál es el alcance de la capa de contexto global.
 - **Principios** — [`docs/principles.es.md`](https://github.com/handsupmin/gc-tree/blob/main/docs/principles.es.md)
-  Resume las reglas de gc-branches, alcance por repositorio, documentos summary-first y actualizaciones guiadas.
 - **Uso** — [`docs/usage.es.md`](https://github.com/handsupmin/gc-tree/blob/main/docs/usage.es.md)
-  Describe el flujo CLI estándar, los comandos del provider, el comportamiento de alcance por repo y los patrones de integración.
 - **Desarrollo local** — [`docs/local-development.es.md`](https://github.com/handsupmin/gc-tree/blob/main/docs/local-development.es.md)
-  Explica cómo instalar dependencias, ejecutar la CLI localmente y verificar cambios.
 
 ---
 
 ## Contribuir
 
-Las contribuciones son bienvenidas. Consulta el documento en inglés [CONTRIBUTING.md](https://github.com/handsupmin/gc-tree/blob/main/CONTRIBUTING.md) para ver el flujo de desarrollo y la checklist de PR.
+Las contribuciones son bienvenidas. Consulta [CONTRIBUTING.md](https://github.com/handsupmin/gc-tree/blob/main/CONTRIBUTING.md) para el flujo de desarrollo y la checklist de PR.
 
 ---