@handsupmin/gc-tree 0.1.3 → 0.2.0

package/README.es.md

@@ -1,165 +1,249 @@
 # gc-tree
 
-Una capa de contexto global con ramas para herramientas de programación con IA.
+<div align="center">
+
+<img src="./logo.png" alt="logo de gc-tree" width="260" />
+
+### Contexto global, más allá del proyecto.
+
+Añade a tus herramientas de IA una capa de contexto reutilizable y duradera.
+Gestiona varios contextos con la misma naturalidad con la que manejas ramas de Git.
+
+[![npm version](https://img.shields.io/npm/v/%40handsupmin%2Fgc-tree)](https://www.npmjs.com/package/@handsupmin/gc-tree)
+[![npm downloads](https://img.shields.io/npm/dm/%40handsupmin%2Fgc-tree)](https://www.npmjs.com/package/@handsupmin/gc-tree)
+[![GitHub stars](https://img.shields.io/github/stars/handsupmin/gc-tree)](https://github.com/handsupmin/gc-tree/stargazers)
+[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](https://github.com/handsupmin/gc-tree/blob/main/LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
 
 [English](https://github.com/handsupmin/gc-tree/blob/main/README.md) | [한국어](https://github.com/handsupmin/gc-tree/blob/main/README.ko.md) | [简体中文](https://github.com/handsupmin/gc-tree/blob/main/README.zh.md) | [日本語](https://github.com/handsupmin/gc-tree/blob/main/README.ja.md) | [Español](https://github.com/handsupmin/gc-tree/blob/main/README.es.md)
 
-## Introducción
+</div>
 
-`gctree` es un **Global Context Tree** ligero para herramientas de programación con IA.
-Le da al contexto duradero un hogar reutilizable, basado en archivos y separado por ramas, sin obligarte a adoptar una plataforma completa de orquestación.
+---
 
-Cuando un solo `AGENTS.md`, `CLAUDE.md` o fragmento de prompt ya no alcanza, `gctree` te ayuda a:
+## El problema
 
-- separar el contexto por producto, cliente o línea de trabajo
-- conservar el conocimiento fuente en markdown en lugar de depender de memoria oculta
-- resolver el contexto activo rápidamente con un índice liviano y documentos summary-first
-- hacer onboarding y actualizaciones duraderas desde tu CLI LLM preferida
-- hacer que un gc-branch solo se use en los repos realmente relacionados
+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.
 
-## Características rápidas
+Así que acabas haciendo esto cada vez:
 
-- **Onboarding guiado por provider**
-  `gctree init` primero te pregunta qué modo de provider quieres usar (`claude-code`, `codex` o `both`), luego qué idioma deben usar las respuestas, guarda esas decisiones, prepara la superficie de comandos adecuada y arranca el onboarding del gc-branch `main` por defecto.
-- **gc-branches con alcance por repositorio**
-  Con `~/.gctree/branch-repo-map.json` puedes asociar un gc-branch solo a ciertos repositorios. Por ejemplo, hacer que A aplique a B/C/D y se ignore en F.
-- **Protección interactiva de alcance**
-  Si `gctree resolve` detecta que el repositorio actual todavía no está asociado a ese gc-branch, puede preguntarte si quieres continuar una vez, usarlo siempre aquí o ignorarlo aquí.
-- **Documentación summary-first**
-  Las herramientas pueden leer primero un resumen corto y abrir el documento completo solo cuando hace falta.
-- **Actualizaciones duraderas guiadas**
-  Puedes actualizar el contexto global con el mismo flujo del provider, sin escribir JSON a mano.
+- 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
 
-## Instalación y guía rápida
+Esto no es un problema de IA. Es un **problema de gestión del contexto**.
 
-### Instalar desde npm
+---
 
-```bash
-npm install -g @handsupmin/gc-tree
-```
+## Qué hace gc-tree
 
-Si solo quieres ejecutarlo una vez sin instalación global:
+`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
-npx @handsupmin/gc-tree init
+gctree resolve --query "auth token rotation policy"
 ```
 
-- **Nombre del paquete:** `@handsupmin/gc-tree`
-- **Comando CLI:** `gctree`
-- **Requisito:** Node.js 20+
-Para desarrollo desde el código fuente, consulta [docs/local-development.md](https://github.com/handsupmin/gc-tree/blob/main/docs/local-development.md).
+```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..."
+    }
+  ]
+}
+```
 
-### Inicio rápido
+Tu herramienta de IA recibe el contexto correcto — no toda la base de conocimiento, solo el fragmento relevante.
 
-#### 1) Inicializa gc-tree
+**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 init
-```
+---
+
+## Para quién es esto
+
+Sacarás más partido a `gc-tree` si:
+
+- 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
+
+Si solo trabajas en un repositorio y un producto, no necesitas esto. `CLAUDE.md` o `.cursorrules` es suficiente.
+
+---
+
+## ¿En qué se diferencia de CLAUDE.md o cursor rules?
+
+`CLAUDE.md` es genial — para un solo repositorio.
+
+En el momento en que tienes múltiples repos, clientes o workstreams:
+
+| | `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 | ✅ | ✅ |
+
+---
+
+## Rendimiento validado
+
+Probado con documentación interna real (4 exportaciones de Notion, consultas mixtas en español e inglés):
 
-Este comando:
+| 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 | ✅ |
 
-- crea `~/.gctree`
-- crea el gc-branch `main` por defecto
-- te pide elegir un modo de provider (`claude-code`, `codex` o `both`)
-- si eliges `both`, te pregunta qué provider debe iniciar este onboarding
-- te pide elegir el idioma (`English`, `Korean` o escribir tu propio idioma)
-- guarda el modo de provider, el provider real de onboarding y el idioma en `~/.gctree/settings.json`
-- prepara la superficie de comandos adecuada en el entorno actual
-- inicia el onboarding guiado del gc-branch activo cuando `main` sigue vacío
+---
 
-#### 2) Resuelve el contexto activo
+## Funciona con Claude Code y Codex — ambos verificados
 
 ```bash
-gctree resolve --query "auth token rotation"
+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
 ```
 
-Si el repositorio actual aún no está asociado a ese gc-branch, `gctree` puede dejarte elegir entre:
+Los dos providers usan el mismo almacén de contexto. Haz el onboarding una vez y úsalo desde cualquiera de los dos.
 
-1. continuar solo esta vez
-2. usar siempre este gc-branch en este repo
-3. ignorar este gc-branch en este repo
+**Claude Code** — usa los slash commands `/gc-resolve-context`, `/gc-onboard`, `/gc-update-global-context`.
 
-Si eliges 2 o 3, `~/.gctree/branch-repo-map.json` se actualiza.
+**Codex** — usa los skills `$gc-resolve-context`, `$gc-onboard`, `$gc-update-global-context`. Verificado con `codex exec`:
 
-#### 3) Crea otro gc-branch si necesitas un contexto separado
+```
+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
+```
+
+---
+
+## Instalación y arranque rápido
 
 ```bash
-gctree checkout -b client-b
+npm install -g @handsupmin/gc-tree
+gctree init
 ```
 
-`checkout -b` crea un **gc-branch vacío nuevo**. No copia los documentos de otra rama.
+`gctree init` te guía a través de:
+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`
+
+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
 
-#### 4) Haz onboarding de un gc-branch vacío
+### Contextos separados para workstreams distintos
 
 ```bash
+gctree checkout -b client-b
 gctree onboard
 ```
 
-#### 5) Actualiza el contexto duradero más adelante
+Cada gc-branch es un carril de contexto completamente independiente. Cambia entre ellos como con ramas de Git.
+
+### Traer contexto relevante cuando lo necesitas
 
 ```bash
-gctree update-global-context
+gctree resolve --query "billing retry policy"
 ```
 
-Alias cortos:
+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
 
 ```bash
-gctree update-gc
-gctree ugc
+gctree update-global-context   # o: gctree update-gc / gctree ugc
 ```
 
-Si al trabajar descubres que un repo realmente pertenece al gc-branch actual, el flujo natural es:
+Flujo de actualización guiado — tu herramienta de IA pregunta qué ha cambiado y escribe el nuevo contexto de vuelta al gc-branch.
 
-1. primero añadir ese repo al branch repo map
-2. después ejecutar `gctree update-global-context` para agregar contexto duradero sobre qué hace ese repo y por qué importa
-
-#### 6) Restablece un gc-branch antes de volver a hacer onboarding
+### Acotar el contexto a repos específicos
 
 ```bash
-gctree reset-gc-branch --branch client-b --yes
+gctree set-repo-scope --branch client-b --include   # incluir el repo actual
+gctree set-repo-scope --branch client-b --exclude   # excluir el repo actual
 ```
 
-### Comandos visibles dentro del runtime
+`gc-tree` no inyectará un contexto en repos donde no corresponde.
+
+---
+
+## Cómo se almacena el contexto
 
-Después del scaffold, los comandos visibles son:
+```
+~/.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
+```
 
-- **Codex:** `$gc-onboard`, `$gc-update-global-context`
-- **Claude Code:** `/gc-onboard`, `/gc-update-global-context`
+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.
 
-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.
+---
 
-### Comandos clave de un vistazo
+## 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 "..."` |
-| 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` |
+| 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).
+## Documentación
 
 - **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.
+
+---
 
 ## Licencia