@handsupmin/gc-tree 0.2.0 → 0.2.1

package/README.zh.md

@@ -36,6 +36,39 @@
 
 ---
 
+## 安装与快速开始
+
+```bash
+npm install -g @handsupmin/gc-tree
+gctree init
+```
+
+`gctree init` 会引导你：
+
+1. 选择 provider：`claude-code`、`codex` 或 `both`
+2. 在当前仓库安装集成文件
+3. 为 `main` gc-branch 完成引导式 onboarding
+
+之后，AI 工具会自动学会在规划或实现前调用 `gctree resolve`。
+
+- **CLI：** `gctree`
+- **要求：** Node.js 20+
+
+---
+
+## 适合哪些人
+
+如果以下几条符合你的情况，gc-tree 会很适合你：
+
+- 工作横跨**多个仓库**（单体仓库团队、平台 + 客户仓库、后端 + 前端技术栈）
+- 同一周内要在**多个产品或客户**之间来回切换
+- 每次开 AI 会话都要**重复解释相同的上下文**
+- 希望 AI 工具不只了解当前文件，还能理解**编码规范、架构和领域知识**
+
+如果你只在一个仓库、一个产品里工作，不需要这个工具。`CLAUDE.md` 或 `.cursorrules` 就够了。
+
+---
+
 ## gc-tree 做什么
 
 `gc-tree` 工作在**仓库之上**。它把上下文存储为结构化的 Markdown 文件，让 AI 工具在每次会话前自动拉取相关内容。
@@ -64,34 +97,21 @@ AI 工具拿到的是正确的上下文——不是整个知识库，而是恰
 
 ---
 
-## 适合哪些人
-
-如果以下几条符合你的情况，gc-tree 会很适合你：
-
-- 工作横跨**多个仓库**（单体仓库团队、平台 + 客户仓库、后端 + 前端技术栈）
-- 同一周内要在**多个产品或客户**之间来回切换
-- 每次开 AI 会话都要**重复解释相同的上下文**
-- 希望 AI 工具不只了解当前文件，还能理解**编码规范、架构和领域知识**
-
-如果你只在一个仓库、一个产品里工作，不需要这个工具。`CLAUDE.md` 或 `.cursorrules` 就够了。
-
----
-
 ## 和 CLAUDE.md 或 cursor rules 有什么区别？
 
 `CLAUDE.md` 很好用——在单个仓库里。
 
 一旦你有了多个仓库、客户或工作线：
 
-| | `CLAUDE.md` / cursor rules | `gc-tree` |
-|---|---|---|
-| 作用范围 | 单个仓库 | 多个仓库，一套上下文 |
-| 持久化方式 | 仓库内的文件 | 存储在仓库外，跨会话复用 |
-| 切换上下文 | 手动编辑文件 | `gctree checkout client-b` |
-| 相关性过滤 | 全部或全无 | 只注入匹配的文档（约 4%） |
-| 初始化方式 | 手写 | 由 AI 工具引导完成 |
-| 支持 Codex | ✅ | ✅ |
-| 支持 Claude Code | ✅ | ✅ |
+|                  | `CLAUDE.md` / cursor rules | `gc-tree`                  |
+| ---------------- | -------------------------- | -------------------------- |
+| 作用范围         | 单个仓库                   | 多个仓库，一套上下文       |
+| 持久化方式       | 仓库内的文件               | 存储在仓库外，跨会话复用   |
+| 切换上下文       | 手动编辑文件               | `gctree checkout client-b` |
+| 相关性过滤       | 全部或全无                 | 只注入匹配的文档（约 4%）  |
+| 初始化方式       | 手写                       | 由 AI 工具引导完成         |
+| 支持 Codex       | ✅                         | ✅                         |
+| 支持 Claude Code | ✅                         | ✅                         |
 
 ---
 
@@ -99,13 +119,13 @@ AI 工具拿到的是正确的上下文——不是整个知识库，而是恰
 
 基于真实内部文档测试（4 份 Notion 导出，中英文混合查询）：
 
-| 指标 | 结果 |
-|---|---|
-| Recall——相关查询找到正确文档的比例 | **100%**（16/16） |
-| Precision——无关查询返回空结果的比例 | **80%**（4/5） |
-| F1 分数 | **88.9%** |
-| 每次查询注入的 token 占总上下文的比例 | **约 4%** |
-| 支持中英文混合查询 | ✅ |
+| 指标                                  | 结果              |
+| ------------------------------------- | ----------------- |
+| Recall——相关查询找到正确文档的比例    | **100%**（16/16） |
+| Precision——无关查询返回空结果的比例   | **80%**（4/5）    |
+| F1 分数                               | **88.9%**         |
+| 每次查询注入的 token 占总上下文的比例 | **约 4%**         |
+| 支持中英文混合查询                    | ✅                |
 
 ---
 
@@ -133,25 +153,6 @@ gctree resolve --query 'NestJS DTO plainToInstance'
 
 ---
 
-## 安装与快速开始
-
-```bash
-npm install -g @handsupmin/gc-tree
-gctree init
-```
-
-`gctree init` 会引导你：
-1. 选择 provider：`claude-code`、`codex` 或 `both`
-2. 在当前仓库安装集成文件
-3. 为 `main` gc-branch 完成引导式 onboarding
-
-之后，AI 工具会自动学会在规划或实现前调用 `gctree resolve`。
-
-- **CLI：** `gctree`
-- **要求：** Node.js 20+
-
----
-
 ## 常用操作
 
 ### 为不同工作线创建独立上下文
@@ -214,19 +215,19 @@ gctree set-repo-scope --branch client-b --exclude   # 排除当前仓库
 
 ## 核心命令
 
-| 目标 | 命令 |
-|---|---|
-| 初始化 gc-tree 并选择 provider | `gctree init` |
-| 确认当前激活的 gc-branch | `gctree status` |
-| 搜索当前上下文 | `gctree resolve --query "..."` |
-| 创建或切换 gc-branch | `gctree checkout <branch>` / `gctree checkout -b <branch>` |
-| 列出所有 gc-branch | `gctree branches` |
-| 对空 gc-branch 进行引导式 onboarding | `gctree onboard` |
-| 对当前 gc-branch 进行引导式更新 | `gctree update-global-context` / `gctree ugc` |
-| 查看仓库范围规则 | `gctree repo-map` |
-| 为 gc-branch 包含或排除当前仓库 | `gctree set-repo-scope --branch <name> --include` / `--exclude` |
-| 重新 onboarding 前重置 gc-branch | `gctree reset-gc-branch --branch <name> --yes` |
-| 在新环境中安装 scaffold | `gctree scaffold --host codex --target /path/to/repo` |
+| 目标                                 | 命令                                                            |
+| ------------------------------------ | --------------------------------------------------------------- |
+| 初始化 gc-tree 并选择 provider       | `gctree init`                                                   |
+| 确认当前激活的 gc-branch             | `gctree status`                                                 |
+| 搜索当前上下文                       | `gctree resolve --query "..."`                                  |
+| 创建或切换 gc-branch                 | `gctree checkout <branch>` / `gctree checkout -b <branch>`      |
+| 列出所有 gc-branch                   | `gctree branches`                                               |
+| 对空 gc-branch 进行引导式 onboarding | `gctree onboard`                                                |
+| 对当前 gc-branch 进行引导式更新      | `gctree update-global-context` / `gctree ugc`                   |
+| 查看仓库范围规则                     | `gctree repo-map`                                               |
+| 为 gc-branch 包含或排除当前仓库      | `gctree set-repo-scope --branch <name> --include` / `--exclude` |
+| 重新 onboarding 前重置 gc-branch     | `gctree reset-gc-branch --branch <name> --yes`                  |
+| 在新环境中安装 scaffold              | `gctree scaffold --host codex --target /path/to/repo`           |
 
 ---
 

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