@handsupmin/gc-tree 0.2.0 → 0.2.1

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

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.