@handsupmin/gc-tree 0.2.0 → 0.3.0

package/docs/concept.es.md

@@ -4,49 +4,61 @@
 
 ## Resumen
 
-`gctree` es una capa ligera de contexto global para herramientas de programación con IA. Mantiene el contexto duradero en documentos markdown explícitos fuera de cualquier repositorio individual, permite cambiar entre gc-branches y puede limitar cada gc-branch a los repositorios donde realmente tiene sentido.
+`gctree` es una capa de contexto global ligera para herramientas de programación con IA. Mantiene el contexto de larga duración en documentos markdown explícitos fuera de cualquier repositorio individual, permite cambiar entre gc-branches y puede limitar cada gc-branch a los repositorios donde realmente corresponde.
 
 ## Qué es `gctree`
 
 `gctree` es una CLI para gestionar contexto global reutilizable.
-Está pensada para equipos y personas que quieren que el contexto de largo recorrido sobreviva entre repositorios, sesiones y herramientas, sin convertirlo en una memoria oculta imposible de inspeccionar.
+Está pensada para personas y equipos que quieren que el contexto importante persista entre repositorios, sesiones y herramientas sin convertirse en memoria oculta.
 
-En lugar de repartir el conocimiento importante entre archivos de prompt, notas locales al repo e instrucciones improvisadas, `gctree` le da a ese conocimiento un hogar estable, visible y respaldado por archivos.
+En lugar de dispersar conocimiento clave entre archivos de prompt, notas locales de cada repositorio e instrucciones puntuales, `gctree` le da a ese conocimiento un lugar estable y respaldado por archivos donde vivir.
 
 ## Qué problema resuelve
 
-Muchos entornos de programación con IA empiezan de forma bastante simple:
+Muchas configuraciones de programación con IA empiezan siendo pequeñas:
 
 - un `AGENTS.md`
 - un `CLAUDE.md`
-- un archivo de prompt dentro del repo
-- unas pocas notas que se copian al prompt cuando hacen falta
+- un archivo de prompt local en el repositorio
+- algunas notas copiadas en los prompts cuando se necesitan
 
-Eso funciona durante un tiempo. Pero cuando empiezan a aparecer necesidades reales, la misma configuración empieza a romperse:
+Eso funciona un tiempo. Luego llega el trabajo real y comienzan a aparecer las fisuras:
 
-- cada producto necesita un contexto distinto
-- el trabajo para clientes debe mantenerse aislado
-- la guía reutilizable debería vivir fuera de un único repositorio
-- varias herramientas deberían poder leer la misma source of truth
-- el contexto duradero debería evolucionar con un flujo seguro y revisable
-- una misma persona puede tener muchas sesiones abiertas en muchos repos a la vez
+- diferentes productos necesitan contexto diferente
+- el trabajo para clientes necesita un aislamiento limpio
+- las guías reutilizables deberían vivir fuera de cualquier repositorio individual
+- múltiples herramientas deberían poder leer la misma fuente de verdad
+- el contexto de larga duración debería cambiar mediante un flujo explícito y revisable
+- una persona puede tener muchas sesiones abiertas en varios repositorios al mismo tiempo
 
-`gctree` existe para resolver precisamente esa capa del problema, y hacerlo de forma limpia.
+`gctree` existe para gestionar esa capa de forma limpia.
+
+## Cómo funciona resolve
+
+Cuando una herramienta llama a `gctree resolve --query "..."`, gc-tree puntúa cada documento de la gc-branch activa contra la consulta usando coincidencia de palabras clave con soporte Unicode (las consultas en coreano, CJK e idiomas mixtos funcionan igual que en inglés). Las coincidencias en el título cuentan el doble que las coincidencias en el cuerpo.
+
+La herramienta recibe únicamente los documentos que coinciden — título, resumen y fragmento — no la base de conocimiento completa. En la práctica, esto significa que se inyecta aproximadamente el 4 % del contexto total por consulta. La herramienta lee el documento completo solo cuando el resumen no es suficiente.
+
+Esto mantiene el uso de tokens bajo sin ocultar nada. Todo el contexto sigue siendo explícito, respaldado por archivos y revisable.
+
+## Compatibilidad con proveedores
+
+`gctree` funciona tanto con Claude Code como con Codex. Ambos proveedores usan el mismo almacén de contexto subyacente. Haz scaffold una vez y ambas herramientas podrán hacer resolve, onboard y actualizar el contexto desde la misma gc-branch.
 
 ## Límite de alcance
 
-`gctree` no pretende ser:
+`gctree` intencionalmente no es:
 
-- un orquestador integral que lleve una petición hasta el commit
+- un orquestador de entregas de solicitud a commit
 - un sistema de memoria oculta
-- un runtime de colaboración en navegador
+- un entorno de colaboración en el navegador
 - un producto de base de conocimiento de propósito general
 
-Se concentra en una sola tarea: gestionar ramas de contexto global reutilizable y sus actualizaciones explícitas.
+Se centra en un único trabajo: gestionar gc-branches de contexto global reutilizable y actualizaciones duraderas explícitas.
 
 ## Modelo de archivos
 
-Un directorio personal típico queda así:
+Un directorio de inicio típico tiene este aspecto:
 
 ```text
 ~/.gctree/
@@ -60,22 +72,22 @@ Un directorio personal típico queda así:
       docs/
 ```
 
-- `HEAD` sigue el gc-branch activo por defecto.
-- `settings.json` guarda el modo de provider, el provider elegido para lanzar el onboarding en runtime y el idioma preferido del flujo.
-- `branch-repo-map.json` guarda qué repositorios están incluidos o excluidos para cada gc-branch.
-- `branch.json` guarda metadatos ligeros del gc-branch.
-- `index.md` es el punto de entrada compacto para herramientas y personas.
-- `docs/` contiene los documentos markdown que actúan como source of truth.
+- `HEAD` registra la gc-branch activa predeterminada.
+- `settings.json` almacena el modo de proveedor, el proveedor de onboarding elegido para el lanzamiento en tiempo de ejecución y el idioma de trabajo preferido.
+- `branch-repo-map.json` almacena qué repositorios están incluidos o excluidos para cada gc-branch.
+- `branch.json` almacena metadatos ligeros de la gc-branch.
+- `index.md` es el punto de entrada compacto para las herramientas — se mantiene por debajo de 2000 caracteres para que cargue rápido sin consumir un presupuesto significativo de tokens.
+- `docs/` contiene los documentos markdown que son la fuente de verdad.
 
-## Comportamiento con conciencia de repositorio
+## Comportamiento según el repositorio
 
-Un gc-branch no tiene por qué aplicarse en todas partes.
-Si la rama `A` solo es relevante para los repositorios `B`, `C` y `D`, `gctree` puede dejarlo registrado en `branch-repo-map.json`.
+Una gc-branch no tiene que aplicarse en todos lados.
+Si la branch `A` solo es relevante para los repositorios `B`, `C` y `D`, `gctree` puede registrar eso en `branch-repo-map.json`.
 
-Cuando `gctree resolve` se ejecuta desde otro repositorio, por ejemplo `F`, puede:
+Cuando `gctree resolve` se ejecuta en otro repositorio como `F`, puede:
 
-- continuar solo una vez
-- usar siempre ese gc-branch en `F`
-- ignorar ese gc-branch en `F`
+- continuar una vez
+- usar siempre esa gc-branch en `F`
+- ignorar esa gc-branch en `F`
 
-Eso hace que gc-tree sea mucho más seguro para quienes mantienen muchas sesiones paralelas abiertas en repositorios que no tienen relación entre sí.
+Esto hace que gc-tree sea mucho más seguro para usuarios avanzados que mantienen muchas sesiones paralelas abiertas en repositorios no relacionados.

package/docs/concept.ja.md

@@ -1,15 +1,15 @@
-# 概念
+# コンセプト
 
 [English](concept.md) | [한국어](concept.ko.md) | [简体中文](concept.zh.md) | [日本語](concept.ja.md) | [Español](concept.es.md)
 
-## 要約
+## 概要
 
-`gctree` は AI コーディングツール向けの軽量なグローバルコンテキストレイヤーです。単一リポジトリの外側に長期コンテキストを明示的な markdown 文書として置き、gc-branch を切り替えながら文脈を使い分けられるようにし、各 gc-branch が本当に関係あるリポジトリにだけ影響するよう制御できます。
+`gctree` は AI コーディングツール向けの軽量なグローバルコンテキスト層です。長期的なコンテキストを単一のリポジトリの外に置いた明示的なマークダウンドキュメントで管理し、gc-branch を切り替えながら文脈を使い分けられるようにし、各 gc-branch が本当に関係するリポジトリにだけ影響するよう制御できます。
 
 ## `gctree` とは何か
 
-`gctree` は再利用できるグローバルコンテキストを管理するための CLI です。
-複数のリポジトリ、複数のセッション、複数のツールをまたいでも長期コンテキストが生き残るようにしつつ、それをブラックボックスな隠れメモリにはしない、という前提で作られています。
+`gctree` は再利用可能なグローバルコンテキストを管理するための CLI です。
+複数のリポジトリ・セッション・ツールをまたいでも重要なコンテキストが生き残るようにしつつ、それを隠れたメモリにはしない、という前提で作られています。
 
 大事な知識がプロンプトファイル、リポジトリ内メモ、場当たり的な指示に散らばる代わりに、`gctree` はその知識に安定したファイルベースの置き場所を与えます。
 
@@ -22,31 +22,43 @@
 - リポジトリ内の短いプロンプトファイルが 1 つ
 - 必要なときだけプロンプトに貼り付けるメモが少し
 
-しばらくはそれで回ります。けれど実務が乗ってくると、同じやり方はすぐ苦しくなります。
+しばらくはそれで回ります。けれど実務が積み重なると、同じやり方はすぐ苦しくなります。
 
 - プロダクトごとに必要なコンテキストが違う
 - クライアント案件は互いに分離しておく必要がある
 - 再利用したいガイダンスは単一リポジトリの外に置きたい
-- 複数ツールが同じ source of truth を読めるべき
-- 長期コンテキストは安全でレビュー可能な流れで育てたい
-- 1 人のユーザーが同時に複数リポジトリで複数セッションを動かすことがある
+- 複数ツールが同じ信頼できる情報源を読めるべき
+- 長期コンテキストは明示的でレビュー可能な流れで変更すべき
+- 1 人のユーザーが複数のリポジトリで多くのセッションを同時に開くことがある
 
-`gctree` は、まさにそのレイヤーをきれいに扱うためのものです。
+`gctree` は、まさにそのレイヤーをきれいに扱うために存在します。
+
+## resolve の仕組み
+
+ツールが `gctree resolve --query "..."` を呼び出すと、gc-tree はアクティブな gc-branch 内のすべてのドキュメントをクエリに対してスコアリングします。スコアリングには Unicode 対応のキーワードマッチングを使用しており、韓国語・CJK 文字・多言語混在クエリも英語と同様に機能します。タイトルの一致はボディの一致の 2 倍の重みを持ちます。
+
+ツールが受け取るのは、マッチしたドキュメントのタイトル・サマリー・抜粋のみです。ナレッジベース全体は返されません。実際には 1 クエリあたり総コンテキストの約 4% が注入されます。サマリーだけでは不足する場合にのみ、ツールはフルドキュメントを読み込みます。
+
+これによりトークン使用量を低く抑えながら、何も隠しません。すべてのコンテキストは引き続き明示的で、ファイルに裏付けられており、レビュー可能です。
+
+## プロバイダーサポート
+
+`gctree` は Claude Code と Codex の両方で動作します。どちらのプロバイダーも同じ基盤のコンテキストストアを使用します。一度 scaffold すれば、両方のツールが同じ gc-branch から resolve・onboard・コンテキスト更新を行えます。
 
 ## スコープの境界
 
-`gctree` は意図的に、次のものではありません。
+`gctree` は意図的に以下のものではありません。
 
-- リクエストからコミットまでを一気通貫で回す実行オーケストレータ
-- 隠れメモリの仕組み
-- ブラウザ型のコラボレーションランタイム
+- リクエストからコミットまでの配信オーケストレーター
+- 隠れたメモリシステム
+- ブラウザ上のコラボレーションランタイム
 - 汎用ナレッジベース製品
 
-`gctree` が集中する仕事は 1 つです。再利用できるグローバルコンテキストブランチと、その明示的な更新を管理することです。
+一つの仕事に集中します：再利用可能なグローバルコンテキストブランチの管理と、明示的な永続的更新です。
 
 ## ファイルモデル
 
-典型的なホームディレクトリ配下の構成はこうなります。
+典型的なホームディレクトリの構成は次のとおりです。
 
 ```text
 ~/.gctree/
@@ -60,22 +72,22 @@
       docs/
 ```
 
-- `HEAD` はデフォルトでアクティブになる gc-branch を追跡します。
-- `settings.json` には provider モード、ランタイム起動に使うオンボーディング provider、優先するワークフロー言語が入ります。
-- `branch-repo-map.json` には各 gc-branch ごとのリポジトリの include / exclude 情報が入ります。
-- `branch.json` には軽量な gc-branch メタデータが入ります。
-- `index.md` はツールが最初に読むコンパクトな入口です。
-- `docs/` には source-of-truth の markdown 文書が入ります。
+- `HEAD` はフォールバックとしてアクティブな gc-branch を追跡します。
+- `settings.json` はプロバイダーモード、ランタイム起動時に選択したオンボーディングプロバイダー、および優先ワークフロー言語を保存します。
+- `branch-repo-map.json` は各 gc-branch に対してどのリポジトリを含むか・除外するかを保存します。
+- `branch.json` は軽量な gc-branch メタデータを保存します。
+- `index.md` はツール向けのコンパクトなエントリーポイントです。高速に読み込めるよう 2000 文字以内に収められており、トークンバジェットを大きく消費しません。
+- `docs/` は信頼できる情報源となるマークダウンドキュメントを格納します。
 
-## リポジトリを意識した振る舞い
+## リポジトリを意識した動作
 
-gc-branch はどこでも有効である必要はありません。
-たとえば branch `A` が repo `B`、`C`、`D` にしか関係しないなら、その事実を `branch-repo-map.json` に記録できます。
+gc-branch はすべての場所に適用する必要はありません。
+ブランチ `A` がリポジトリ `B`・`C`・`D` にのみ関係する場合、`gctree` はそれを `branch-repo-map.json` に記録できます。
 
-その状態で別の repo `F` から `gctree resolve` を実行した場合、`gctree` は次のように扱えます。
+別のリポジトリ `F` で `gctree resolve` が実行された場合、次のいずれかを選択できます。
 
-- 今回だけ続ける
-- 今後も `F` ではその gc-branch を使う
+- 一度だけ続行する
+- `F` でも常にその gc-branch を使用する
 - `F` ではその gc-branch を無視する
 
-これによって、無関係なリポジトリをまたいで多くの並行セッションを開いているヘビーユーザーでも、gc-tree をかなり安全に使えます。
+これにより、無関係な多数のリポジトリで並行セッションを維持するヘビーユーザーにとって、gc-tree はより安全に使えます。

package/docs/concept.ko.md

@@ -4,49 +4,61 @@
 
 ## 요약
 
-`gctree`는 AI 코딩 도구를 위한 가벼운 글로벌 컨텍스트 레이어입니다. 하나의 레포 밖에서 장기 컨텍스트를 명시적인 markdown 문서로 관리하고, gc-branch를 바꿔가며 맥락을 나눠 쓸 수 있게 해주며, 각 gc-branch가 실제로 관련 있는 레포에서만 적용되도록 제한할 수 있습니다.
+`gctree`는 AI 코딩 도구를 위한 경량 전역 컨텍스트 레이어입니다. 오래 유지되는 컨텍스트를 특정 저장소 바깥에 명시적인 마크다운 문서로 관리하고, gc-branch 간 전환을 지원하며, 각 gc-branch를 실제로 관련된 저장소로만 범위를 제한할 수 있습니다.
 
-## `gctree`는 무엇인가
+## `gctree`란 무엇인가
 
-`gctree`는 재사용 가능한 글로벌 컨텍스트를 관리하는 CLI입니다.
-여러 레포, 여러 세션, 여러 도구를 오가더라도 장기 컨텍스트가 사라지지 않게 하되, 그 컨텍스트가 숨겨진 메모리처럼 블랙박스에 갇히지 않도록 설계했습니다.
+`gctree`는 재사용 가능한 전역 컨텍스트를 관리하기 위한 CLI입니다.
+중요한 컨텍스트를 저장소, 세션, 도구를 가로질러 유지하되, 숨겨진 메모리처럼 블랙박스에 갇히지 않게 하려는 개인과 팀을 위해 만들어졌습니다.
 
-중요한 지식이 프롬프트 파일, 레포 내부 메모, 임시 지시문으로 흩어지는 대신, `gctree`는 그 지식이 머물 수 있는 안정적인 파일 기반 저장소를 제공합니다.
+핵심 지식을 프롬프트 파일, 저장소 로컬 메모, 그때그때 추가하는 지시사항에 흩어놓는 대신, `gctree`는 그 지식이 안정적으로 파일 기반으로 자리잡을 수 있는 공간을 제공합니다.
 
-## 어떤 문제를 해결하나
+## 어떤 문제를 해결하는가
 
-많은 AI 코딩 환경은 이렇게 작게 시작합니다.
+많은 AI 코딩 환경은 작게 시작합니다:
 
 - `AGENTS.md` 하나
 - `CLAUDE.md` 하나
-- 레포 안의 짧은 프롬프트 파일 하나
-- 필요할 때마다 프롬프트에 복붙하는 메모 몇 개
+- 저장소 로컬 프롬프트 파일 하나
+- 필요할 때 프롬프트에 복사해 넣는 메모 몇 가지
 
-처음에는 잘 돌아갑니다. 하지만 실제 업무가 얹히기 시작하면 금방 틀어집니다.
+한동안은 잘 작동합니다. 그러다 실제 업무가 쌓이면서 문제가 드러나기 시작합니다:
 
-- 제품마다 필요한 컨텍스트가 다르다
-- 고객사 작업은 서로 섞이면 안 된다
-- 재사용 가능한 가이드는 특정 레포 바깥에 있어야 한다
-- 여러 도구가 같은 source of truth를 읽을 수 있어야 한다
-- 장기 컨텍스트는 안전하고 검토 가능한 흐름으로 업데이트되어야 한다
-- 한 사람이 동시에 여러 레포에서 여러 세션을 돌릴 수 있다
+- 제품마다 서로 다른 컨텍스트가 필요함
+- 클라이언트 업무는 명확한 격리가 필요함
+- 재사용 가능한 지침은 특정 저장소 바깥에 존재해야 함
+- 여러 도구가 동일한 정보 소스를 읽을 수 있어야 함
+- 오래 유지되는 컨텍스트는 명시적이고 검토 가능한 흐름으로만 변경되어야 함
+- 한 사람이 여러 저장소에 걸쳐 많은 세션을 동시에 열어둘 수 있음
 
-`gctree`는 바로 그 레이어를 깔끔하게 해결하려고 존재합니다.
+`gctree`는 바로 이 레이어를 깔끔하게 처리하기 위해 만들어졌습니다.
+
+## resolve가 동작하는 방식
+
+도구가 `gctree resolve --query "..."`를 호출하면, gc-tree는 활성 gc-branch 내의 모든 문서를 쿼리와 대조해 유니코드를 지원하는 키워드 매칭으로 점수를 매깁니다. 한국어, CJK 문자, 혼합 언어 쿼리도 영어와 동일하게 처리됩니다. 제목 매칭은 본문 매칭보다 두 배의 가중치를 가집니다.
+
+도구는 전체 지식 베이스가 아닌 매칭된 문서만 받습니다 — 제목, 요약, 발췌문 형태로. 실제로 이는 쿼리당 전체 컨텍스트의 약 4%만 주입됨을 의미합니다. 도구는 요약만으로 충분하지 않을 때만 전체 문서를 읽습니다.
+
+이를 통해 아무것도 숨기지 않으면서 토큰 사용량을 낮게 유지합니다. 모든 컨텍스트는 여전히 명시적이고, 파일 기반이며, 검토 가능합니다.
+
+## 프로바이더 지원
+
+`gctree`는 Claude Code와 Codex 모두에서 동작합니다. 두 프로바이더는 동일한 기반 컨텍스트 저장소를 사용합니다. 한 번만 scaffold하면 두 도구 모두 같은 gc-branch에서 resolve, onboard, 컨텍스트 업데이트를 수행할 수 있습니다.
 
 ## 범위 경계
 
-`gctree`는 의도적으로 다음이 아닙니다.
+`gctree`는 의도적으로 다음을 지향하지 않습니다:
 
-- 요청부터 커밋까지 전 과정을 오케스트레이션하는 배달 시스템
+- 요청-커밋 배달 오케스트레이터
 - 숨겨진 메모리 시스템
-- 브라우저 기반 협업 런타임
+- 브라우저 협업 런타임
 - 범용 지식 베이스 제품
 
-`gctree`는 한 가지 일에 집중합니다. 재사용 가능한 글로벌 컨텍스트 브랜치를 관리하고, 그 변경을 명시적으로 다루는 일입니다.
+`gctree`는 한 가지 역할에 집중합니다: 재사용 가능한 전역 컨텍스트 브랜치 관리와 명시적인 지속 업데이트.
 
 ## 파일 모델
 
-보통 홈 디렉터리 아래 구조는 이렇게 생깁니다.
+일반적인 홈 디렉토리 구조는 다음과 같습니다:
 
 ```text
 ~/.gctree/
@@ -60,22 +72,22 @@
       docs/
 ```
 
-- `HEAD`는 기본으로 활성화되는 gc-branch를 가리킵니다.
-- `settings.json`에는 provider 모드, 런타임 시작에 사용할 온보딩 provider, 선호 워크플로 언어가 저장됩니다.
-- `branch-repo-map.json`에는 각 gc-branch별로 어떤 레포를 포함하거나 제외할지 저장됩니다.
-- `branch.json`에는 가벼운 gc-branch 메타데이터가 들어갑니다.
-- `index.md`는 도구가 먼저 들어오는 압축된 진입점입니다.
-- `docs/`에는 source-of-truth markdown 문서가 들어갑니다.
+- `HEAD`는 폴백 활성 gc-branch를 추적합니다.
+- `settings.json`은 프로바이더 모드, 런타임 실행 시 선택된 온보딩 프로바이더, 선호 워크플로우 언어를 저장합니다.
+- `branch-repo-map.json`은 각 gc-branch에 대해 어떤 저장소가 포함되거나 제외되는지 저장합니다.
+- `branch.json`은 gc-branch의 경량 메타데이터를 저장합니다.
+- `index.md`는 도구를 위한 간결한 진입점으로, 2000자 이하로 유지되어 상당한 토큰 예산을 소비하지 않고 빠르게 로드됩니다.
+- `docs/`는 정보 소스가 되는 마크다운 문서들을 담습니다.
 
-## 레포 인식 동작
+## 저장소 인식 동작
 
-gc-branch는 모든 곳에 적용될 필요가 없습니다.
-예를 들어 `A` 브랜치가 `B`, `C`, `D` 레포에서만 의미가 있다면, `gctree`는 그 사실을 `branch-repo-map.json`에 기록할 수 있습니다.
+gc-branch가 모든 곳에 적용될 필요는 없습니다.
+브랜치 `A`가 저장소 `B`, `C`, `D`에만 관련된다면, `gctree`는 이를 `branch-repo-map.json`에 기록할 수 있습니다.
 
-그 상태에서 다른 레포인 `F`에서 `gctree resolve`를 실행하면, 다음처럼 처리할 수 있습니다.
+다른 저장소 `F`에서 `gctree resolve`를 실행하면 다음 중 하나를 선택할 수 있습니다:
 
-- 이번 한 번만 계속하기
-- 앞으로 `F`에서도 그 gc-branch를 항상 사용하기
-- `F`에서는 그 gc-branch를 무시하기
+- 한 번만 계속 진행
+- `F`에서 항상 해당 gc-branch 사용
+- `F`에서 해당 gc-branch 무시
 
-이 덕분에 서로 무관한 레포들 사이에서 여러 세션을 동시에 많이 띄워두는 사용자에게도 gc-tree가 훨씬 안전하게 동작합니다.
+이를 통해 관련 없는 여러 저장소에 걸쳐 많은 병렬 세션을 유지하는 헤비 유저에게도 gc-tree가 훨씬 안전하게 동작합니다.

package/docs/concept.md

@@ -33,6 +33,18 @@ That works for a while. Then real work shows up and the cracks start to show:
 
 `gctree` exists to handle that layer cleanly.
 
+## How resolve works
+
+When a tool calls `gctree resolve --query "..."`, gc-tree scores every document in the active gc-branch against the query using keyword matching with Unicode support (Korean, CJK, and mixed-language queries work the same as English). Title matches count twice as much as body matches.
+
+The tool receives only the matching documents — title, summary, and excerpt — not the full knowledge base. In practice this means roughly 4% of total context is injected per query. The tool reads the full document only when the summary is not enough.
+
+This keeps token use low without hiding anything. All context is still explicit, file-backed, and reviewable.
+
+## Provider support
+
+`gctree` works with both Claude Code and Codex. Both providers use the same underlying context store. Scaffold once and both tools can resolve, onboard, and update context from the same gc-branch.
+
 ## Scope boundary
 
 `gctree` is intentionally not:
@@ -64,7 +76,7 @@ A typical home directory looks like this:
 - `settings.json` stores the provider mode, the onboarding provider chosen for runtime launch, and the preferred workflow language.
 - `branch-repo-map.json` stores which repositories are included or excluded for each gc-branch.
 - `branch.json` stores lightweight gc-branch metadata.
-- `index.md` is the compact entry point for tools.
+- `index.md` is the compact entry point for tools — kept under 2000 characters so it loads fast without consuming significant token budget.
 - `docs/` holds the source-of-truth markdown documents.
 
 ## Repo-aware behavior

package/docs/concept.zh.md

@@ -2,51 +2,63 @@
 
 [English](concept.md) | [한국어](concept.ko.md) | [简体中文](concept.zh.md) | [日本語](concept.ja.md) | [Español](concept.es.md)
 
-## 摘要
+## 概述
 
-`gctree` 是一层面向 AI 编码工具的轻量级全局上下文层。它把长期上下文放在单个仓库之外、以显式 markdown 文档的形式保存，让你可以在不同 gc-branch 之间切换，并且把每条 gc-branch 的影响范围限制在真正相关的仓库里。
+`gctree` 是一个为 AI 编程工具设计的轻量级全局上下文层。它将长期上下文保存在任何单一代码仓库之外的显式 Markdown 文档中，支持在 gc-branch 之间切换，并可将每个 gc-branch 的作用范围限制在真正需要它的代码仓库中。
 
 ## `gctree` 是什么
 
-`gctree` 是一个用来管理可复用全局上下文的 CLI。
-它面向的是这样一种需求：长期上下文需要在多个仓库、多个会话、多个工具之间持续存在，但又不能变成一个看不见、摸不着的“隐式记忆黑盒”。
+`gctree` 是一个用于管理可复用全局上下文的 CLI 工具。
+它专为希望重要上下文能够跨代码仓库、跨会话、跨工具持续存在，同时又不变成隐藏记忆的个人和团队而设计。
 
-与其把重要知识分散在提示词文件、仓库内笔记和临时指令里，不如让 `gctree` 给这些知识一个稳定、可追踪、由文件承载的家。
+与其将关键知识分散在提示词文件、仓库本地笔记和临时指令中，`gctree` 为这些知识提供了一个稳定的、以文件为载体的归宿。
 
-## 它解决什么问题
+## 它解决了什么问题
 
-很多 AI 编码环境一开始都很简单：
+许多 AI 编程环境最初规模都很小：
 
 - 一个 `AGENTS.md`
 - 一个 `CLAUDE.md`
-- 一个仓库内提示词文件
-- 几段需要时再复制进提示词里的笔记
+- 一个仓库本地提示词文件
+- 几条在需要时复制进提示词的笔记
 
-一开始这样完全够用。但一旦进入真实工作场景，这套做法很快就会吃力。
+这样的方式在一段时间内是可行的。但当真正的工作量到来时，裂缝就开始显现：
 
 - 不同产品需要不同的上下文
-- 客户项目之间必须隔离
-- 可复用的指导信息应该放在单个仓库之外
-- 多个工具应该能读取同一份 source of truth
-- 长期上下文应该通过安全、可审阅的流程来演进
-- 同一个人可能同时在多个仓库里跑很多个会话
+- 客户项目需要清晰的隔离
+- 可复用的指导内容应该存放在任何单一仓库之外
+- 多个工具应该能够读取同一个可信来源
+- 长期上下文应该通过明确的、可审查的流程来变更
+- 一个人可能同时跨多个代码仓库开启多个会话
 
-`gctree` 存在的目的，就是把这一层问题单独而清晰地解决掉。
+`gctree` 的存在，就是为了干净地处理这一层问题。
 
-## 边界在哪里
+## resolve 的工作原理
 
-`gctree` 有意不去做下面这些事：
+当工具调用 `gctree resolve --query "..."` 时，gc-tree 会使用支持 Unicode 的关键词匹配，对当前活跃 gc-branch 中的每个文档与查询内容进行评分（韩语、中日韩文字及混合语言查询与英语的处理方式完全相同）。标题匹配的权重是正文匹配的两倍。
 
-- 从需求一路编排到 commit 的交付系统
-- 隐藏式记忆系统
+工具只会收到匹配的文档——包含标题、摘要和摘录——而非完整的知识库。实际上，每次查询注入的上下文约占总量的 4%。只有在摘要不足以满足需求时，工具才会读取完整文档。
+
+这种方式在不遮蔽任何内容的前提下保持了较低的 token 消耗。所有上下文仍然是显式的、以文件为载体的，且可供审查。
+
+## 提供商支持
+
+`gctree` 同时支持 Claude Code 和 Codex。两个提供商使用相同的底层上下文存储。只需 scaffold 一次，两个工具便可从同一个 gc-branch 中执行 resolve、onboard 和上下文更新。
+
+## 范围边界
+
+`gctree` 有意不做以下事情：
+
+- 从需求到提交的交付编排器
+- 隐藏记忆系统
 - 浏览器协作运行时
 - 通用知识库产品
 
-它只专注一件事：管理可复用的全局上下文分支，以及这些分支上的显式更新。
+它专注于一件事：管理可复用的全局上下文分支，以及明确的持久化更新。
 
 ## 文件模型
 
-一个典型的主目录结构大致如下：
+一个典型的主目录结构如下：
 
 ```text
 ~/.gctree/
@@ -60,22 +72,22 @@
       docs/
 ```
 
-- `HEAD` 记录默认激活的 gc-branch。
-- `settings.json` 保存 provider 模式、运行时启动时选用的 onboarding provider，以及偏好的工作流语言。
-- `branch-repo-map.json` 保存每条 gc-branch 对哪些仓库包含或排除。
-- `branch.json` 保存轻量级的 gc-branch 元数据。
-- `index.md` 是工具首先进入的紧凑入口。
-- `docs/` 用来保存 source-of-truth markdown 文档。
+- `HEAD` 记录后备的活跃 gc-branch。
+- `settings.json` 存储提供商模式、运行时启动时选择的 onboarding 提供商，以及首选的工作流语言。
+- `branch-repo-map.json` 存储每个 gc-branch 包含或排除的代码仓库。
+- `branch.json` 存储轻量级的 gc-branch 元数据。
+- `index.md` 是工具的简洁入口点——保持在 2000 字符以内，以便快速加载而不消耗大量 token 预算。
+- `docs/` 存放作为可信来源的 Markdown 文档。
 
-## 面向仓库的行为
+## 仓库感知行为
 
-gc-branch 不需要在所有地方都生效。
-如果 branch `A` 只和仓库 `B`、`C`、`D` 有关，`gctree` 就可以把这件事记录到 `branch-repo-map.json` 里。
+gc-branch 不必应用于所有地方。
+如果分支 `A` 只与代码仓库 `B`、`C` 和 `D` 相关，`gctree` 可以将这一关系记录在 `branch-repo-map.json` 中。
 
-这样一来，当你在另一个仓库 `F` 里执行 `gctree resolve` 时，它可以这样处理：
+当 `gctree resolve` 在另一个代码仓库（例如 `F`）中运行时，它可以：
 
-- 只这一次继续
-- 以后在 `F` 里始终使用这条 gc-branch
-- 在 `F` 里忽略这条 gc-branch
+- 继续一次
+- 始终在 `F` 中使用该 gc-branch
+- 在 `F` 中忽略该 gc-branch
 
-对于那些同时在多个互不相关仓库里开很多并行会话的重度用户来说，这会让 gc-tree 安全得多，也更实用。
+这使得 gc-tree 对于同时跨多个无关代码仓库保持大量并行会话的重度用户来说更加安全。

package/docs/local-development.es.md

@@ -4,24 +4,24 @@
 
 ## Resumen
 
-El desarrollo local sigue un flujo estándar de Node.js 20+: instalar dependencias, compilar la CLI, ejecutarla localmente y verificar los cambios con la suite de tests existente antes de enviarlos.
+El desarrollo local sigue un flujo de trabajo estándar de Node.js 20+: instalar dependencias, compilar la CLI, ejecutarla localmente y verificar los cambios con el conjunto de pruebas existente antes de enviarlos.
 
 ## Requisitos previos
 
 - Node.js 20+
 - npm
-- binarios locales de `codex` y / o `claude` si quieres probar manualmente el arranque de providers
+- binarios locales de `codex` y/o `claude` si quieres hacer pruebas manuales con los lanzamientos de proveedores
 
-## Preparación
+## Configuración
 
 ```bash
 npm install
 npm run build
 ```
 
-## Ejecuta la CLI en local
+## Ejecutar la CLI localmente
 
-### Opción 1: ejecutar directamente la entrada ya compilada
+### Opción 1: ejecutar el punto de entrada compilado directamente
 
 ```bash
 node dist/src/cli.js status
@@ -34,7 +34,7 @@ npm link
 gctree status
 ```
 
-Si cambias archivos TypeScript, vuelve a compilar antes de probar otra vez la CLI.
+Si cambias archivos TypeScript, vuelve a compilar antes de probar la CLI de nuevo.
 
 ## Verificación
 
@@ -45,33 +45,55 @@ npm run build
 npm test
 ```
 
-## Tests de repo scope
+### Suite de evaluación
 
-La suite de tests cubre ahora:
+Además de las pruebas unitarias, una suite de evaluación mide la calidad de resolve contra fixtures realistas:
 
-- persistencia del modo de provider (`claude-code`, `codex`, `both`)
-- persistencia del idioma preferido y aplicación estricta del idioma en los launch prompts
-- selección de gc-branch con conciencia de repositorio
-- decisiones interactivas de include / exclude durante `resolve`
-- actualizaciones del branch repo map
-- límites del flujo guiado de onboarding / update
+```bash
+npm run eval                  # suite sintética de 5 escenarios (onboarding, resolve, eficiencia de tokens, actualización, aislamiento)
+npm run eval:verbose          # lo mismo, con detalle por caso
+npm run eval:multi-repo       # prueba de aislamiento entre repositorios usando fixtures de estilo cosmo
+npm run eval:real-docs        # recall y precisión contra exportaciones reales de Notion (requiere documentos locales)
+npm run eval:autoresearch     # bucle iterativo de mejora de resolve (modifica src/resolve.ts en su lugar)
+```
+
+Líneas base esperadas (ejecuta `npm run eval` para verificar):
+
+| Suite | Objetivo |
+| --- | --- |
+| Sintética (5 escenarios) | 5/5 PASS, media ≥ 90% |
+| Multi-repo | ≥ 80% en total |
+| Real-docs | Recall ≥ 90%, F1 ≥ 80% |
+
+Si modificas `src/resolve.ts`, ejecuta `npm test && npm run eval && npm run eval:real-docs` antes de abrir un PR.
+
+## Cobertura de pruebas
+
+El conjunto de pruebas unitarias cubre actualmente:
+
+- persistencia del modo de proveedor (`claude-code`, `codex`, `both`)
+- persistencia del idioma preferido y aplicación estricta del idioma en los prompts de lanzamiento
+- selección de gc-branch según el repositorio
+- decisiones interactivas de incluir/excluir durante `resolve`
+- actualizaciones del mapa de repositorios de la branch
+- límites del flujo guiado de onboarding/actualización
 
-## Comprobaciones manuales E2E de providers
+## Verificaciones E2E manuales del proveedor
 
-Los tests automatizados desactivan el lanzamiento de providers para poder verificar los launch plans sin abrir sesiones reales de Codex o Claude Code.
-Si quieres probar la ruta real de lanzamiento, ejecuta uno de estos comandos dentro de un directorio desechable:
+Las pruebas automatizadas deshabilitan el lanzamiento del proveedor para poder verificar los planes de lanzamiento sin abrir sesiones reales de Codex o Claude Code.
+Si quieres hacer pruebas con el camino de lanzamiento real, ejecuta uno de estos en un directorio de prueba:
 
 ```bash
 gctree init --provider codex
 gctree init --provider claude-code
 ```
 
-Deberías ver que el provider se abre y recibe inmediatamente `$gc-onboard` o `/gc-onboard`.
+Deberías ver cómo se abre el proveedor y recibe inmediatamente `$gc-onboard` o `/gc-onboard`.
 
 ## Estructura del proyecto
 
-- `src/` — CLI, almacenamiento de contexto, selección de provider, mapeo de repo scope, flujos guiados de onboarding / update y lógica de scaffolding
-- `tests/` — tests de CLI y de comportamiento
-- `skills/` — habilidades de flujo de trabajo independientes de la herramienta
-- `scaffolds/` — plantillas de arranque específicas por host
+- `src/` — CLI, almacenamiento de contexto, selección de proveedor, mapeo de alcance del repositorio, flujos guiados de onboarding/actualización y lógica de scaffolding
+- `tests/` — pruebas unitarias y scripts de evaluación
+- `skills/` — skills de flujo de trabajo agnósticas a la herramienta (usadas por Claude Code)
+- `scaffolds/` — directorios de marcador de posición; el contenido de los archivos de scaffold se genera programáticamente en `src/scaffold.ts`
 - `docs/` — documentación de concepto, principios, uso y desarrollo