@handsupmin/gc-tree 0.2.0 → 0.3.0

package/docs/local-development.ja.md

@@ -2,15 +2,15 @@
 
 [English](local-development.md) | [한국어](local-development.ko.md) | [简体中文](local-development.zh.md) | [日本語](local-development.ja.md) | [Español](local-development.es.md)
 
-## 要約
+## 概要
 
-ローカル開発は、一般的な Node.js 20+ の流れに沿っています。依存関係を入れ、CLI をビルドし、ローカルで実行し、変更を送る前に既存のテストスイートで検証します。
+ローカル開発は標準的な Node.js 20+ の流れに沿っています。依存関係をインストールし、CLI をビルドし、ローカルで実行し、変更を送る前に既存のテストスイートで検証します。
 
 ## 前提条件
 
 - Node.js 20+
 - npm
-- provider 起動を自分で試したい場合はローカルの `codex` と / または `claude` バイナリ
+- プロバイダー起動を手元で試したい場合はローカルの `codex` や `claude` バイナリ
 
 ## セットアップ
 
@@ -45,33 +45,55 @@ npm run build
 npm test
 ```
 
-## repo-scope テスト
+### eval スイート
 
-現在のテストスイートでは、次をカバーしています。
+ユニットテストに加えて、eval スイートがリアルなフィクスチャに対して resolve の品質を測定します。
 
-- provider モードの保存（`claude-code`、`codex`、`both`）
-- 優先言語の保存と launch prompt での強い言語維持
+```bash
+npm run eval                  # 5 シナリオの合成スイート（オンボーディング、resolve、トークン効率、更新、分離）
+npm run eval:verbose          # 同上、ケースごとの詳細付き
+npm run eval:multi-repo       # cosmo スタイルのフィクスチャを使ったクロスリポジトリ分離テスト
+npm run eval:real-docs        # 実際の Notion エクスポートに対する再現率と適合率（ローカルドキュメントが必要）
+npm run eval:autoresearch     # 反復的な resolve 改善ループ（src/resolve.ts をその場で変更します）
+```
+
+期待されるベースライン（`npm run eval` を実行して確認）:
+
+| スイート | 目標 |
+| --- | --- |
+| 合成（5 シナリオ） | 5/5 PASS、平均 ≥ 90% |
+| マルチリポジトリ | 全体 ≥ 80% |
+| 実ドキュメント | 再現率 ≥ 90%、F1 ≥ 80% |
+
+`src/resolve.ts` を変更した場合は、PR を開く前に `npm test && npm run eval && npm run eval:real-docs` を実行してください。
+
+## テストカバレッジ
+
+現在のユニットテストスイートでは次をカバーしています。
+
+- プロバイダーモードの永続化（`claude-code`、`codex`、`both`）
+- 優先言語の永続化と起動プロンプトでの言語強制
 - リポジトリを意識した gc-branch 選択
-- `resolve` 実行中の include / exclude の対話
+- `resolve` 実行中の include / exclude の対話的な決定
 - branch repo map の更新
-- ガイド付きオンボーディング / 更新の境界条件
+- ガイド付きオンボーディング・更新フローの境界条件
 
-## provider の手動 E2E チェック
+## プロバイダーの手動 E2E チェック
 
-自動テストでは、Codex や Claude Code のセッションを実際に開かなくても launch plan を検証できるよう、provider 起動を無効化しています。
-本物の launch path を試したい場合は、使い捨てディレクトリで次のどちらかを実行してください。
+自動テストでは、Codex や Claude Code のセッションを実際に開かなくても起動計画を検証できるよう、プロバイダー起動を無効化しています。
+本物の起動パスを試したい場合は、使い捨てディレクトリで次のどちらかを実行してください。
 
 ```bash
 gctree init --provider codex
 gctree init --provider claude-code
 ```
 
-正しく動けば、provider が起動し、すぐに `$gc-onboard` または `/gc-onboard` を受け取るはずです。
+正しく動けば、プロバイダーが起動し、すぐに `$gc-onboard` または `/gc-onboard` を受け取るはずです。
 
 ## プロジェクト構成
 
-- `src/` — CLI、本体のコンテキスト保存、provider 選択、repo-scope マッピング、ガイド付きオンボーディング / 更新フロー、scaffolding ロジック
-- `tests/` — CLI と振る舞いのテスト
-- `skills/` — ツール非依存のワークフロースキル
-- `scaffolds/` — ホスト別のブートストラップテンプレート
-- `docs/` — 概念、原則、使い方、開発ドキュメント
+- `src/` — CLI、コンテキストストレージ、プロバイダー選択、repo-scope マッピング、ガイド付きオンボーディング・更新フロー、および scaffolding ロジック
+- `tests/` — ユニットテストと eval スクリプト
+- `skills/` — ツールに依存しないワークフロースキル（Claude Code が使用）
+- `scaffolds/` — プレースホルダーディレクトリ。scaffold ファイルの内容は `src/scaffold.ts` でプログラム的に生成されます
+- `docs/` — コンセプト・原則・使い方・開発ドキュメント

package/docs/local-development.ko.md

@@ -4,13 +4,13 @@
 
 ## 요약
 
-로컬 개발은 일반적인 Node.js 20+ 흐름을 따릅니다. 의존성을 설치하고, CLI를 빌드하고, 로컬에서 실행해 보고, 변경을 보내기 전에 기존 테스트 스위트로 검증하면 됩니다.
+로컬 개발은 표준 Node.js 20+ 워크플로우를 따릅니다: 의존성 설치, CLI 빌드, 로컬 실행, 변경 사항을 내보내기 전에 기존 테스트 스위트로 검증.
 
-## 준비물
+## 사전 요구 사항
 
 - Node.js 20+
 - npm
-- provider 실행을 직접 확인해보고 싶다면 로컬 `codex` 및 / 또는 `claude` 바이너리
+- 프로바이더 실행을 직접 도그푸딩하려면 로컬에 `codex` 및/또는 `claude` 바이너리 필요
 
 ## 설정
 
@@ -19,59 +19,81 @@ npm install
 npm run build
 ```
 
-## 로컬에서 CLI 실행하기
+## CLI 로컬 실행
 
-### 방법 1: 빌드된 엔트리를 직접 실행
+### 옵션 1: 빌드된 엔트리를 직접 실행
 
 ```bash
 node dist/src/cli.js status
 ```
 
-### 방법 2: CLI를 셸에 링크해서 사용
+### 옵션 2: CLI를 셸에 링크
 
 ```bash
 npm link
 gctree status
 ```
 
-TypeScript 소스를 수정했다면 CLI를 다시 테스트하기 전에 한 번 더 빌드하세요.
+TypeScript 소스를 변경한 경우, CLI를 다시 테스트하기 전에 재빌드하세요.
 
 ## 검증
 
-PR을 열기 전에 아래 명령을 실행하세요.
+풀 리퀘스트를 열기 전에 다음을 실행하세요:
 
 ```bash
 npm run build
 npm test
 ```
 
-## repo-scope 테스트
+### 평가 스위트
 
-현재 테스트 스위트는 다음을 커버합니다.
+유닛 테스트 외에도, 현실적인 픽스처를 기반으로 resolve 품질을 측정하는 평가 스위트가 있습니다:
 
-- provider 모드 저장 (`claude-code`, `codex`, `both`)
-- 선호 언어 저장과 launch prompt에서의 강한 언어 유지
-- 레포 인식 gc-branch 선택
-- `resolve` 중 include / exclude 인터랙션
-- branch repo map 업데이트
-- 가이드형 온보딩 / 업데이트 경계
+```bash
+npm run eval                  # 5시나리오 합성 스위트 (온보딩, resolve, 토큰 효율성, 업데이트, 격리)
+npm run eval:verbose          # 동일, 케이스별 상세 출력
+npm run eval:multi-repo       # cosmo 스타일 픽스처를 사용한 크로스 저장소 격리 테스트
+npm run eval:real-docs        # 실제 Notion 익스포트에 대한 재현율 및 정밀도 측정 (로컬 문서 필요)
+npm run eval:autoresearch     # 반복적 resolve 개선 루프 (src/resolve.ts를 직접 수정함)
+```
+
+예상 기준선 (`npm run eval` 실행으로 확인):
+
+| 스위트 | 목표 |
+| --- | --- |
+| 합성 (5 시나리오) | 5/5 PASS, 평균 ≥ 90% |
+| 다중 저장소 | 전체 ≥ 80% |
+| 실제 문서 | 재현율 ≥ 90%, F1 ≥ 80% |
+
+`src/resolve.ts`를 수정한 경우, PR을 열기 전에 `npm test && npm run eval && npm run eval:real-docs`를 실행하세요.
+
+## 테스트 커버리지
+
+유닛 테스트 스위트가 현재 다루는 항목:
+
+- 프로바이더 모드 영속성 (`claude-code`, `codex`, `both`)
+- 선호 언어 영속성 및 실행 프롬프트에서의 강력한 언어 적용
+- 저장소 인식 gc-branch 선택
+- `resolve` 중 인터랙티브 포함/제외 결정
+- 브랜치 저장소 맵 업데이트
+- 안내된 온보딩/업데이트 흐름 경계
 
-## provider 수동 E2E 확인
+## 수동 프로바이더 E2E 확인
 
-자동화 테스트는 Codex나 Claude Code 세션을 실제로 열지 않고도 launch plan을 검증할 수 있도록 provider 실행을 비활성화해 둡니다.
-실제 launch 경로를 직접 확인해보고 싶다면, 임시 디렉터리에서 아래 중 하나를 실행해 보세요.
+자동화된 테스트는 실제 Codex나 Claude Code 세션을 열지 않고 실행 계획을 검증할 수 있도록 프로바이더 실행을 비활성화합니다.
+실제 실행 경로를 도그푸딩하려면 임시 디렉토리에서 다음 중 하나를 실행하세요:
 
 ```bash
 gctree init --provider codex
 gctree init --provider claude-code
 ```
 
-정상이라면 provider가 열리고 바로 `$gc-onboard` 또는 `/gc-onboard`를 받게 됩니다.
+프로바이더가 열리고 즉시 `$gc-onboard` 또는 `/gc-onboard`를 받는 것을 확인해야 합니다.
 
-## 프로젝트 구조
+## 프로젝트 레이아웃
 
-- `src/` — CLI, 컨텍스트 저장소, provider 선택, repo-scope 매핑, 가이드형 온보딩 / 업데이트 흐름, 스캐폴딩 로직
-- `tests/` — CLI 및 동작 테스트
-- `skills/` — 도구 비종속 워크플로 스킬
-- `scaffolds/` — 호스트별 부트스트랩 템플릿
+- `src/` — CLI, 컨텍스트 저장소, 프로바이더 선택, 저장소 범위 매핑, 안내된 온보딩/업데이트 흐름, scaffold 로직
+- `tests/` — 유닛 테스트 및 평가 스크립트
+- `skills/` — 도구에 구애받지 않는 워크플로우 스킬 (Claude Code에서 사용)
+- `scaffolds/` — 플레이스홀더 디렉토리; scaffold 파일 내용은 `src/scaffold.ts`에서 프로그래밍 방식으로 생성됨
 - `docs/` — 개념, 원칙, 사용법, 개발 문서

package/docs/local-development.md

@@ -45,9 +45,31 @@ npm run build
 npm test
 ```
 
-## Repo-scope tests
+### Eval suite
 
-The test suite currently covers:
+In addition to the unit tests, an eval suite measures resolve quality against realistic fixtures:
+
+```bash
+npm run eval                  # 5-scenario synthetic suite (onboarding, resolve, token efficiency, update, isolation)
+npm run eval:verbose          # same, with per-case detail
+npm run eval:multi-repo       # cross-repo isolation test using cosmo-style fixtures
+npm run eval:real-docs        # recall and precision against real Notion exports (requires local docs)
+npm run eval:autoresearch     # iterative resolve improvement loop (modifies src/resolve.ts in place)
+```
+
+Expected baselines (run `npm run eval` to verify):
+
+| Suite | Target |
+| --- | --- |
+| Synthetic (5 scenarios) | 5/5 PASS, mean ≥ 90% |
+| Multi-repo | ≥ 80% overall |
+| Real-docs | Recall ≥ 90%, F1 ≥ 80% |
+
+If you modify `src/resolve.ts`, run `npm test && npm run eval && npm run eval:real-docs` before opening a PR.
+
+## Test coverage
+
+The unit test suite currently covers:
 
 - provider mode persistence (`claude-code`, `codex`, `both`)
 - preferred language persistence and strong language enforcement in launch prompts
@@ -71,7 +93,7 @@ You should see the provider open and immediately receive `$gc-onboard` or `/gc-o
 ## Project layout
 
 - `src/` — CLI, context storage, provider selection, repo-scope mapping, guided onboarding/update flows, and scaffolding logic
-- `tests/` — CLI and behavior tests
-- `skills/` — tool-agnostic workflow skills
-- `scaffolds/` — host-specific bootstrap templates
+- `tests/` — unit tests and eval scripts
+- `skills/` — tool-agnostic workflow skills (used by Claude Code)
+- `scaffolds/` — placeholder directories; scaffold file content is generated programmatically in `src/scaffold.ts`
 - `docs/` — concept, principles, usage, and development documentation

package/docs/local-development.zh.md

@@ -45,9 +45,31 @@ npm run build
 npm test
 ```
 
-## repo-scope 测试
+### 评估套件
 
-当前测试套件覆盖了以下内容：
+除单元测试外，还有一套 eval 套件，用于衡量 resolve 在真实场景下的质量：
+
+```bash
+npm run eval                  # 5 场景综合测试（onboarding、resolve、token 效率、update、隔离性）
+npm run eval:verbose          # 同上，输出每条用例的详情
+npm run eval:multi-repo       # 跨仓库隔离测试，使用 cosmo 风格的 fixtures
+npm run eval:real-docs        # 基于真实 Notion 导出文件的 recall 和 precision 测试（需要本地文档）
+npm run eval:autoresearch     # 迭代式 resolve 改进循环（会直接修改 src/resolve.ts）
+```
+
+预期基线（运行 `npm run eval` 可验证）：
+
+| 套件 | 目标 |
+| --- | --- |
+| 综合（5 场景） | 5/5 PASS，均值 ≥ 90% |
+| 多仓库 | 整体 ≥ 80% |
+| 真实文档 | Recall ≥ 90%，F1 ≥ 80% |
+
+如果你修改了 `src/resolve.ts`，在发 PR 之前请运行 `npm test && npm run eval && npm run eval:real-docs`。
+
+## 测试覆盖范围
+
+当前单元测试套件覆盖了以下内容：
 
 - provider 模式持久化（`claude-code`、`codex`、`both`）
 - 偏好语言持久化，以及 launch prompt 中的强语言约束
@@ -71,7 +93,7 @@ gctree init --provider claude-code
 ## 项目结构
 
 - `src/` — CLI、本地上下文存储、provider 选择、repo-scope 映射、带引导的 onboarding / update 流程，以及 scaffolding 逻辑
-- `tests/` — CLI 与行为测试
-- `skills/` — 与工具无关的工作流技能
-- `scaffolds/` — 面向不同 host 的引导模板
+- `tests/` — 单元测试与 eval 脚本
+- `skills/` — 与工具无关的工作流技能（供 Claude Code 使用）
+- `scaffolds/` — 占位目录；scaffold 文件内容由 `src/scaffold.ts` 动态生成
 - `docs/` — 概念、原则、使用方式与开发文档

package/docs/principles.es.md

@@ -4,47 +4,60 @@
 
 ## Resumen
 
-`gctree` sigue unas pocas reglas de producto muy claras: mantener el contexto con conciencia de rama, mantener los documentos source con enfoque summary-first, mantener los índices ligeros y hacer explícito el repo scope para que cada gc-branch solo influya donde realmente le toca.
+`gctree` sigue un pequeño conjunto de reglas de producto: mantener el contexto consciente de las branches, mantener los documentos fuente con el resumen primero, mantener los índices compactos, hacer el alcance del repositorio explícito, inyectar solo lo relevante y admitir cualquier proveedor que pueda ejecutar comandos de shell.
 
-## 1. Mantén el contexto con conciencia de rama
+## 1. Mantener el contexto consciente de las branches
 
-Una misma máquina debería poder contener varios árboles de contexto global sin mezclarlos.
-Por eso `gctree` usa lenguaje tipo Git como `checkout` y `checkout -b`, mientras que en la interfaz orientada al usuario se refiere a la rama activa como **gc-branch**.
+Una misma máquina debe poder mantener múltiples árboles de contexto global sin mezclarlos entre sí.
+Por eso `gctree` usa terminología similar a git como `checkout` y `checkout -b`, aunque sigue refiriéndose a la branch activa como **gc-branch** en el texto orientado al usuario.
 
-## 2. Haz explícito el repo scope
+## 2. Mantener el alcance del repositorio explícito
 
-Un gc-branch no debería afectar en silencio a todos los repositorios de la máquina.
+Una gc-branch no debería afectar silenciosamente a todos los repositorios de la máquina.
 `gctree` usa `branch-repo-map.json` para registrar si un repositorio está:
 
-- incluido para un gc-branch
-- excluido para un gc-branch
-- todavía sin mapear
+- incluido para una gc-branch
+- excluido para una gc-branch
+- aún no mapeado
 
-Si `resolve` se llama desde un repositorio no mapeado, la persona usuaria puede decidir si quiere continuar una vez, usar siempre ese gc-branch allí o ignorarlo en ese repo.
+Si se llama a `resolve` desde un repositorio no mapeado, el usuario puede decidir si continuar una vez, usar siempre esa gc-branch allí o ignorarla.
 
-## 3. Mantén `index.md` ligero
+## 3. Mantener `index.md` compacto
 
-El `index.md` de nivel superior es un índice, no un vertedero de contenido.
-Su trabajo es ayudar a herramientas y personas a encontrar rápido el documento source correcto.
-Debe seguir siendo compacto y orientado a enlaces, en lugar de duplicar todo el conocimiento en línea.
+El `index.md` de nivel superior es un índice, no un volcado.
+Su función es ayudar a las herramientas y a las personas a encontrar rápidamente el documento fuente correcto.
+Debe mantenerse por debajo de **2000 caracteres** y orientarse a los enlaces en lugar de duplicar el conocimiento completo de forma inline.
 
-## 4. Haz que los documentos source sean summary-first
+## 4. Hacer que los documentos fuente empiecen con el resumen
 
-Todo documento markdown que actúe como source of truth debería incluir una sección `## Summary` cerca del inicio.
-Eso le da a las herramientas una ruta rápida: leer primero la versión corta y ampliar solo cuando haga falta más detalle.
+Cada documento markdown que sea fuente de verdad debe incluir una sección `## Summary` cerca del principio.
+Esto le da a las herramientas aguas abajo un camino rápido: leer primero la versión corta y expandir solo cuando realmente se necesite más detalle.
 
-## 5. Haz que el onboarding sea explícito y guiado
+## 5. Hacer el onboarding explícito y guiado
 
-Una persona no debería tener que escribir a mano un JSON de onboarding solo para crear un árbol de contexto útil.
-`gctree init` y `gctree onboard` deberían guiar el flujo con el provider elegido y escribir el contexto resultante en el gc-branch activo.
+Un usuario no debería tener que escribir a mano JSON de onboarding solo para crear un árbol de contexto útil.
+`gctree init` y `gctree onboard` deben guiar al usuario a través de su proveedor preferido y escribir el contexto resultante en la gc-branch activa.
 
-El onboarding solo aplica a gc-branches vacíos.
-Si un gc-branch ya contiene contexto, el camino correcto es uno de estos dos:
+El onboarding es solo para gc-branches vacías.
+Si una gc-branch ya contiene contexto, el camino correcto es:
 
-- restablecer ese gc-branch y volver a hacer onboarding
-- o lanzar una actualización duradera guiada
+- resetear esa gc-branch y hacer onboarding de nuevo
+- o ejecutar una actualización duradera guiada
 
-## 6. Haz que las actualizaciones duraderas sean intencionales
+## 6. Mantener las actualizaciones duraderas intencionales
 
 El contexto duradero no debería cambiar por accidente ni a través de memoria oculta.
-El flujo de actualización debe ser explícito, guiado por el provider y estar ligado al gc-branch activo en ese momento.
+El flujo de actualización debe ser explícito, impulsado por el proveedor y vinculado a la gc-branch actualmente activa.
+
+## 7. Inyectar solo lo relevante
+
+Una sesión de herramienta nunca debería recibir la base de conocimiento completa.
+`gctree resolve` puntúa los documentos contra la consulta y devuelve solo los que coinciden — título, resumen y fragmento. El documento completo se lee solo cuando el resumen no es suficiente.
+
+En la práctica, esto significa que se inyecta aproximadamente el 4 % del contexto almacenado total por consulta. El 96 % restante permanece en disco, fuera de la ventana de tokens, hasta que se necesite realmente.
+
+## 8. Mantenerse agnóstico al proveedor
+
+`gctree` almacena el contexto en archivos markdown simples que cualquier herramienta puede leer.
+Claude Code y Codex hacen scaffold contra el mismo almacén subyacente mediante `gctree scaffold`.
+Agregar soporte para un nuevo proveedor significa escribir una nueva plantilla de scaffold — sin cambios en la lógica central de almacenamiento ni de resolve.

package/docs/principles.ja.md

@@ -2,9 +2,9 @@
 
 [English](principles.md) | [한국어](principles.ko.md) | [简体中文](principles.zh.md) | [日本語](principles.ja.md) | [Español](principles.es.md)
 
-## 要約
+## 概要
 
-`gctree` は少数のプロダクト原則に従っています。コンテキストはブランチ単位で扱うこと、source 文書は summary-first にすること、index は薄く保つこと、そして repo scope を明示して gc-branch が本来関係するリポジトリにだけ作用するようにすることです。
+`gctree` は少数のプロダクト原則に従っています。コンテキストはブランチを意識して持つこと、ソースドキュメントは summary-first にすること、index は薄く保つこと、repo scope を明示すること、関連するものだけを注入すること、そしてシェルコマンドを実行できるあらゆるプロバイダーをサポートすることです。
 
 ## 1. コンテキストはブランチを意識して持つ
 
@@ -25,26 +25,39 @@ gc-branch がマシン上のすべてのリポジトリに黙って影響して
 ## 3. `index.md` は薄く保つ
 
 トップレベルの `index.md` は知識の置き場ではなく、あくまでインデックスです。
-役割は、人やツールが正しい source 文書を素早く見つけられるようにすることです。
-全文の知識をその場に複製するのではなく、コンパクトでリンク中心に保つべきです。
+役割は、人やツールが正しいソースドキュメントを素早く見つけられるようにすることです。
+**2000 文字** 以内に収め、全文の知識をその場に複製するのではなく、コンパクトでリンク中心に保つべきです。
 
-## 4. source 文書は summary-first にする
+## 4. ソースドキュメントは summary-first にする
 
-source-of-truth の markdown 文書には、冒頭近くに `## Summary` セクションがあるべきです。
-そうしておけば、後段のツールはまず短い要約を読み、必要なときだけ詳細を展開できます。
+信頼できる情報源となるマークダウンドキュメントには、冒頭近くに `## Summary` セクションがあるべきです。
+そうしておけば、後段のツールはまず短い要約を読み、実際に詳細が必要になったときだけ展開できます。
 
 ## 5. オンボーディングは明示的かつガイド付きにする
 
-使えるコンテキストツリーを作るために、ユーザーがオンボーディング用 JSON を手書きしなければならないのはよくありません。
-`gctree init` と `gctree onboard` は、ユーザーが選んだ provider に沿って流れを案内し、その結果のコンテキストを現在アクティブな gc-branch に書き込むべきです。
+使えるコンテキストツリーを作るために、ユーザーがオンボーディング用の JSON を手書きしなければならないのはよくありません。
+`gctree init` と `gctree onboard` は、ユーザーが選んだプロバイダーに沿って流れを案内し、その結果のコンテキストを現在アクティブな gc-branch に書き込むべきです。
 
 オンボーディングは空の gc-branch に対してだけ行うものです。
 すでにコンテキストが入っている gc-branch の場合、正しい道筋は次のどちらかです。
 
 - その gc-branch をリセットして再オンボードする
-- またはガイド付きの長期更新を実行する
+- またはガイド付きの永続的更新を実行する
 
-## 6. 長期更新は意図を持って行う
+## 6. 永続的な更新は意図を持って行う
 
-長期コンテキストが事故的に変わったり、隠れメモリ経由で変わったりしてはいけません。
-更新フローは明示的で、provider 主導であり、かつ現在アクティブな gc-branch にしっかり結び付いているべきです。
+永続的なコンテキストが事故的に変わったり、隠れたメモリ経由で変わったりしてはいけません。
+更新フローは明示的で、プロバイダー主導であり、かつ現在アクティブな gc-branch にしっかり結び付いているべきです。
+
+## 7. 関連するものだけを注入する
+
+ツールのセッションがナレッジベース全体を受け取るべきではありません。
+`gctree resolve` はドキュメントをクエリに対してスコアリングし、マッチしたもののタイトル・サマリー・抜粋だけを返します。フルドキュメントはサマリーだけでは不足するときにのみ読み込まれます。
+
+実際には 1 クエリあたり保存された総コンテキストの約 4% が注入されます。残りの 96% はディスク上に留まり、実際に必要になるまでトークンウィンドウには入りません。
+
+## 8. プロバイダーに依存しない設計を保つ
+
+`gctree` はコンテキストをプレーンなマークダウンファイルとして保存するため、どのツールでも読み込めます。
+Claude Code と Codex はどちらも `gctree scaffold` を通じて同じ基盤のストアに対して scaffold します。
+新しいプロバイダーのサポートを追加するには、新しい scaffold テンプレートを書くだけです。コアのストレージや resolve ロジックに変更は不要です。

package/docs/principles.ko.md

@@ -4,47 +4,60 @@
 
 ## 요약
 
-`gctree`는 몇 가지 작은 제품 원칙 위에서 움직입니다. 컨텍스트는 브랜치 단위로 다루고, source 문서는 summary-first로 유지하고, index는 얇게 유지하고, repo scope는 명시적으로 관리해서 gc-branch가 자기 자리에만 영향을 주게 합니다.
+`gctree`는 소수의 제품 원칙을 따릅니다: 컨텍스트는 브랜치 인식으로, 소스 문서는 요약 우선으로, 인덱스는 슬림하게, 저장소 범위는 명시적으로, 관련된 것만 주입하고, 셸 명령을 실행할 수 있는 모든 프로바이더를 지원합니다.
 
-## 1. 컨텍스트는 브랜치 단위로 다룬다
+## 1. 컨텍스트를 브랜치 인식으로 유지한다
 
-한 대의 머신 안에서도 여러 글로벌 컨텍스트 트리를 서로 섞이지 않게 유지할 수 있어야 합니다.
-그래서 `gctree`는 `checkout`, `checkout -b` 같은 Git 스타일 언어를 쓰되, 사용자에게 보이는 표현에서는 활성 브랜치를 **gc-branch**라고 부릅니다.
+한 대의 머신이 여러 전역 컨텍스트 트리를 서로 섞이지 않게 유지할 수 있어야 합니다.
+그래서 `gctree`는 `checkout`, `checkout -b` 같은 git 스타일의 언어를 사용하면서도, 사용자 대면 문구에서는 활성 브랜치를 **gc-branch**라고 부릅니다.
 
-## 2. repo scope는 명시적으로 둔다
+## 2. 저장소 범위를 명시적으로 유지한다
 
-gc-branch가 머신 안의 모든 레포에 조용히 영향을 주면 안 됩니다.
-`gctree`는 `branch-repo-map.json`을 통해 각 레포가 다음 중 어디에 속하는지 기록합니다.
+gc-branch가 머신의 모든 저장소에 조용히 영향을 미쳐서는 안 됩니다.
+`gctree`는 `branch-repo-map.json`을 사용해 저장소가 다음 상태 중 어느 것인지 기록합니다:
 
-- 특정 gc-branch에 포함됨
-- 특정 gc-branch에서 제외됨
+- gc-branch에 포함됨
+- gc-branch에서 제외됨
 - 아직 매핑되지 않음
 
-`resolve`가 아직 매핑되지 않은 레포에서 호출되면, 사용자는 이번만 계속할지, 앞으로도 그 gc-branch를 여기서 쓸지, 아니면 여기서는 무시할지 결정할 수 있습니다.
+매핑되지 않은 저장소에서 `resolve`가 호출되면, 사용자가 해당 저장소에서 한 번만 계속할지, 항상 해당 gc-branch를 사용할지, 아니면 무시할지 결정할 수 있습니다.
 
-## 3. `index.md`는 얇게 유지한다
+## 3. `index.md`를 슬림하게 유지한다
 
-최상위 `index.md`는 지식 dump가 아니라 인덱스입니다.
-역할은 사람과 도구가 올바른 source 문서를 빠르게 찾도록 돕는 것입니다.
-본문 지식을 다 복붙해 넣기보다, 짧고 링크 중심의 구조를 유지해야 합니다.
+최상위 `index.md`는 인덱스이지, 덤프가 아닙니다.
+도구와 사람이 올바른 소스 문서를 빠르게 찾을 수 있도록 돕는 것이 역할입니다.
+**2000자** 이하로 유지되어야 하며, 전체 지식을 인라인으로 복제하는 대신 링크 중심으로 구성되어야 합니다.
 
-## 4. source 문서는 summary-first로 만든다
+## 4. 소스 문서를 요약 우선으로 구성한다
 
-source-of-truth markdown 문서라면 상단 가까이에 `## Summary` 섹션이 있어야 합니다.
-그래야 도구가 먼저 짧은 버전을 읽고, 정말 더 자세한 내용이 필요할 때만 본문을 확장해서 볼 수 있습니다.
+모든 정보 소스 마크다운 문서는 상단 근처에 `## Summary` 섹션을 포함해야 합니다.
+이는 다운스트림 도구에게 빠른 경로를 제공합니다: 먼저 짧은 버전을 읽고, 실제로 더 많은 상세 내용이 필요할 때만 확장합니다.
 
-## 5. 온보딩은 명시적이고 가이드형이어야 한다
+## 5. 온보딩을 명시적이고 안내된 방식으로 만든다
 
-유용한 컨텍스트 트리를 만들기 위해 사용자가 온보딩용 JSON을 손으로 작성하게 하면 안 됩니다.
-`gctree init`과 `gctree onboard`는 사용자가 선호하는 provider를 기준으로 흐름을 안내하고, 결과 컨텍스트를 현재 활성 gc-branch에 써 넣어야 합니다.
+사용자가 유용한 컨텍스트 트리를 만들기 위해 온보딩 JSON을 직접 작성하도록 요구해서는 안 됩니다.
+`gctree init`과 `gctree onboard`는 사용자가 선호하는 프로바이더를 안내하고, 결과 컨텍스트를 활성 gc-branch에 기록해야 합니다.
 
-온보딩은 비어 있는 gc-branch에서만 해야 합니다.
-이미 컨텍스트가 들어 있는 gc-branch라면 올바른 경로는 둘 중 하나입니다.
+온보딩은 빈 gc-branch에만 적용됩니다.
+gc-branch에 이미 컨텍스트가 있다면, 올바른 경로는 다음 중 하나입니다:
 
-- 그 gc-branch를 리셋하고 다시 온보딩하기
-- 혹은 가이드형 장기 업데이트를 실행하기
+- 해당 gc-branch를 초기화하고 다시 온보딩
+- 또는 안내된 지속 업데이트 실행
 
-## 6. 장기 업데이트는 의도적으로만 일어나야 한다
+## 6. 지속 업데이트를 의도적으로 유지한다
 
-장기 컨텍스트는 우연히 바뀌거나 숨겨진 메모리를 통해 바뀌면 안 됩니다.
-업데이트 흐름은 명시적이어야 하고, provider가 주도해야 하며, 현재 활성 gc-branch와 분명히 연결되어 있어야 합니다.
+지속 컨텍스트는 우연히 또는 숨겨진 메모리를 통해 변경되어서는 안 됩니다.
+업데이트 흐름은 명시적이어야 하고, 프로바이더 주도로 이루어지며, 현재 활성 gc-branch에 연결되어야 합니다.
+
+## 7. 관련된 것만 주입한다
+
+도구 세션은 전체 지식 베이스를 절대 받아서는 안 됩니다.
+`gctree resolve`는 쿼리에 대해 문서에 점수를 매기고 매칭된 것만 반환합니다 — 제목, 요약, 발췌문 형태로. 전체 문서는 요약으로 충분하지 않을 때만 읽습니다.
+
+실제로 이는 쿼리당 저장된 전체 컨텍스트의 약 4%만 주입됨을 의미합니다. 나머지 96%는 실제로 필요할 때까지 디스크에 남아 토큰 윈도우 밖에 있습니다.
+
+## 8. 프로바이더에 종속되지 않는다
+
+`gctree`는 어떤 도구든 읽을 수 있는 일반 마크다운 파일에 컨텍스트를 저장합니다.
+Claude Code와 Codex 모두 `gctree scaffold`를 통해 동일한 기반 저장소에 대해 scaffold합니다.
+새로운 프로바이더 지원 추가는 새 scaffold 템플릿을 작성하는 것을 의미합니다 — 핵심 저장소나 resolve 로직은 변경이 필요 없습니다.

package/docs/principles.md

@@ -4,7 +4,7 @@
 
 ## Summary
 
-`gctree` follows a small set of product rules: keep context branch-aware, keep source docs summary-first, keep indexes slim, and make repo scope explicit so a gc-branch only influences the repositories where it belongs.
+`gctree` follows a small set of product rules: keep context branch-aware, keep source docs summary-first, keep indexes slim, make repo scope explicit, inject only what is relevant, and support any provider that can run shell commands.
 
 ## 1. Keep context branch-aware
 
@@ -26,7 +26,7 @@ If `resolve` is called from an unmapped repository, the user can decide whether
 
 The top-level `index.md` is an index, not a dump.
 Its job is to help tools and humans find the right source document quickly.
-It should stay compact and link-oriented instead of duplicating full knowledge inline.
+It should stay under **2000 characters** and remain link-oriented instead of duplicating full knowledge inline.
 
 ## 4. Make source docs summary-first
 
@@ -48,3 +48,16 @@ If a gc-branch already contains context, the correct path is either:
 
 Durable context should not change by accident or through hidden memory.
 The update flow should be explicit, provider-driven, and tied to the currently active gc-branch.
+
+## 7. Inject only what is relevant
+
+A tool session should never receive the entire knowledge base.
+`gctree resolve` scores documents against the query and returns only the matching ones — title, summary, and excerpt. The full document is read only when the summary is not enough.
+
+In practice this means roughly 4% of total stored context is injected per query. The remaining 96% stays on disk, out of the token window, until it is actually needed.
+
+## 8. Stay provider-agnostic
+
+`gctree` stores context in plain markdown files that any tool can read.
+Claude Code and Codex both scaffold against the same underlying store via `gctree scaffold`.
+Adding support for a new provider means writing a new scaffold template — no changes to the core storage or resolve logic.