@handsupmin/gc-tree 1.0.0 → 1.1.0

package/README.es.md

@@ -137,15 +137,18 @@ En el momento en que tienes múltiples repos, proyectos o workstreams:
 
 ## Rendimiento validado
 
-Probado con documentación interna real (4 exportaciones de Notion, consultas mixtas en español e inglés):
+Evaluación con dos fixtures — **DEV** es visible para el bucle de tuning, **HOLDOUT** se reserva para reporte honesto (dominios distintos, negativos difíciles, paráfrasis, consultas mixtas español + inglés). 38 casos etiquetados en 8 categorías: exact-keyword, paraphrase, glossary, mixed-language, same-domain distractor, same-domain negative, cross-branch negative.
 
-| Métrica                                                      | Resultado        |
-| ------------------------------------------------------------ | ---------------- |
-| Recall — consultas relevantes que encuentran el doc correcto | **100%** (16/16) |
-| Precision — consultas irrelevantes que devuelven vacío       | **80%** (4/5)    |
-| F1 score                                                     | **88.9%**        |
-| Tokens inyectados por consulta vs. contexto total            | **~4%**          |
-| Compatible con consultas mixtas en varios idiomas            | ✅               |
+| Métrica                                            | DEV          | HOLDOUT      |
+| -------------------------------------------------- | ------------ | ------------ |
+| recall@1                                           | **100.0%**   | **85.7%**    |
+| recall@3                                           | **100.0%**   | **92.9%**    |
+| MRR                                                | **100.0%**   | **89.3%**    |
+| Consultas irrelevantes → vacío (neg. precision)    | **100.0%**   | **100.0%**   |
+| Tokens inyectados por consulta vs. contexto total  | **~7%**      | **~13%**     |
+| Consultas con scripts mixtos (varios idiomas)      | ✅           | ✅           |
+
+Brecha de generalización (DEV − HOLDOUT) = **10.0 pts**. El fixture HOLDOUT se reserva solo para reporte — el bucle de autoresearch nunca se ajusta contra él. Reproducible con `npm run eval:ranked`; reglas de scoring en [`tests/eval/RUBRIC.md`](https://github.com/handsupmin/gc-tree/blob/main/tests/eval/RUBRIC.md).
 
 ---
 
@@ -201,6 +204,14 @@ gctree update-global-context   # o: gctree update-gc / gctree ugc
 
 Flujo de actualización guiado — tu herramienta de IA pregunta qué ha cambiado y escribe el nuevo contexto de vuelta al gc-branch.
 
+### Mantener gc-tree actualizado
+
+```bash
+gctree update
+```
+
+Actualiza `@handsupmin/gc-tree` a la última versión de npm y vuelve a instalar todos los providers que ya habías configurado. Úsalo cuando gc-tree publique mejores hooks, comandos, skills o snippets de integración y quieras refrescar tu configuración en un solo paso.
+
 ### Acotar el contexto a repos específicos
 
 ```bash

package/README.ja.md

@@ -137,15 +137,18 @@ AI ツールに渡るのは正しいコンテキスト——ナレッジベー
 
 ## 検証済みのパフォーマンス
 
-実際の社内ドキュメントでテスト（Notion エクスポート 4 件、日本語・英語混合クエリ）：
+二つの fixture による評価 — **DEV** はチューニングループから見える、**HOLDOUT** は誠実な報告用に分離（異なるドメイン、ハードネガティブ、言い換え、日英混合クエリを含む）。8 カテゴリ 38 ラベル付きケース: exact-keyword、paraphrase、glossary、mixed-language、same-domain distractor、same-domain negative、cross-branch negative。
 
-| 指標                                         | 結果              |
-| -------------------------------------------- | ----------------- |
-| Recall——関連クエリが正しい文書を見つける割合 | **100%**（16/16） |
-| Precision——無関係なクエリが空を返す割合      | **80%**（4/5）    |
-| F1 スコア                                    | **88.9%**         |
-| クエリあたりの注入トークン割合（全体比）     | **約 4%**         |
-| 日英混合クエリ対応                           | ✅                |
+| 指標                                            | DEV          | HOLDOUT      |
+| ----------------------------------------------- | ------------ | ------------ |
+| recall@1                                        | **100.0%**   | **85.7%**    |
+| recall@3                                        | **100.0%**   | **92.9%**    |
+| MRR                                             | **100.0%**   | **89.3%**    |
+| 無関係クエリ → 空（negative precision）         | **100.0%**   | **100.0%**   |
+| クエリあたりの注入トークン割合（全体比）        | **約 7%**    | **約 13%**   |
+| 混合スクリプトクエリ（日本語 + 英語）           | ✅           | ✅           |
+
+汎化ギャップ（DEV − HOLDOUT）= **10.0 pt**。HOLDOUT fixture は報告専用 — autoresearch ループは決してこれに対してチューニングしません。`npm run eval:ranked` で再現可能。スコアリング規則は [`tests/eval/RUBRIC.md`](https://github.com/handsupmin/gc-tree/blob/main/tests/eval/RUBRIC.md) を参照。
 
 ---
 
@@ -201,6 +204,14 @@ gctree update-global-context   # または：gctree update-gc / gctree ugc
 
 ガイド付き更新フロー——AI ツールが何が変わったかを確認し、新しいコンテキストを gc-branch に書き戻します。
 
+### gc-tree 自体を最新に保つ
+
+```bash
+gctree update
+```
+
+`@handsupmin/gc-tree` を最新の npm バージョンに更新し、以前インストールしたすべてのプロバイダーを再スキャフォールドします。より良いフック、コマンド、スキル、統合スニペットが配布されたときに、既存の設定を一度で更新できます。
+
 ### コンテキストを特定のリポジトリに限定する
 
 ```bash

package/README.ko.md

@@ -137,15 +137,18 @@ AI 도구가 올바른 컨텍스트를 가져옵니다. 지식 베이스 전체
 
 ## 검증된 성능
 
-실제 내부 문서 기준 테스트 (Notion 내보내기 4종, 한국어 + 영어 혼합 쿼리):
+두 fixture 평가 — **DEV**는 튜닝 루프에 보이고, **HOLDOUT**은 정직한 보고용으로 분리 (다른 도메인, hard negative, 의역, 한국어+영어 혼합 쿼리 포함). 8개 카테고리 38개 라벨 케이스: exact-keyword, paraphrase, glossary, mixed-language, same-domain distractor, same-domain negative, cross-branch negative.
 
-| 지표                                            | 결과             |
-| ----------------------------------------------- | ---------------- |
-| Recall — 관련 쿼리가 올바른 문서를 찾는 비율    | **100%** (16/16) |
-| Precision — 무관 쿼리가 빈 결과를 반환하는 비율 | **80%** (4/5)    |
-| F1 점수                                         | **88.9%**        |
-| 쿼리당 주입 토큰 비율 (전체 컨텍스트 대비)      | **~4%**          |
-| 한국어 + 영어 혼합 쿼리 지원                    | ✅               |
+| 지표                                            | DEV          | HOLDOUT      |
+| ----------------------------------------------- | ------------ | ------------ |
+| recall@1                                        | **100.0%**   | **85.7%**    |
+| recall@3                                        | **100.0%**   | **92.9%**    |
+| MRR                                             | **100.0%**   | **89.3%**    |
+| 무관 쿼리 → 빈 결과 (negative precision)        | **100.0%**   | **100.0%**   |
+| 쿼리당 주입 토큰 비율 (전체 컨텍스트 대비)      | **~7%**      | **~13%**     |
+| 혼합 스크립트 쿼리 (한국어 + 영어)              | ✅           | ✅           |
+
+일반화 갭 (DEV − HOLDOUT) = **10.0 pt**. HOLDOUT fixture는 보고 전용 — autoresearch 루프가 절대 튜닝하지 않습니다. `npm run eval:ranked`로 재현 가능. 점수 규칙은 [`tests/eval/RUBRIC.md`](https://github.com/handsupmin/gc-tree/blob/main/tests/eval/RUBRIC.md) 참조.
 
 ---
 
@@ -201,6 +204,14 @@ gctree update-global-context   # 또는: gctree update-gc / gctree ugc
 
 가이드형 업데이트 플로우 — AI 도구가 무엇이 바뀌었는지 물어보고 새 컨텍스트를 gc-branch에 씁니다.
 
+### gc-tree 자체 최신 상태 유지
+
+```bash
+gctree update
+```
+
+`@handsupmin/gc-tree`를 최신 npm 버전으로 업데이트한 뒤, 이전에 설치한 모든 프로바이더를 다시 스캐폴드합니다. 더 나은 훅, 명령, 스킬, 통합 스니펫이 배포됐을 때 기존 설정을 한 번에 새로고침하는 흐름입니다.
+
 ### 특정 레포에 컨텍스트 범위 지정
 
 ```bash

package/README.md

@@ -137,15 +137,18 @@ The moment you have multiple repos, projects, or workstreams:
 
 ## Validated performance
 
-Tested against real internal documentation (4 Notion exports, Korean + English mixed queries):
+Two-fixture eval — **DEV** is visible to the tuning loop, **HOLDOUT** is reserved for honest reporting (different domains, hard negatives, paraphrase, mixed Korean+English queries). 38 labeled cases across 8 categories: exact-keyword, paraphrase, glossary, mixed-language, same-domain distractor, same-domain negative, cross-branch negative.
 
-| Metric                                       | Result           |
-| -------------------------------------------- | ---------------- |
-| Recall — relevant queries find the right doc | **100%** (16/16) |
-| Precision — irrelevant queries return empty  | **80%** (4/5)    |
-| F1 score                                     | **88.9%**        |
-| Tokens injected per query vs. total context  | **~4%**          |
-| Works with mixed Korean + English queries    | ✅               |
+| Metric                                          | DEV          | HOLDOUT      |
+| ----------------------------------------------- | ------------ | ------------ |
+| recall@1                                        | **100.0%**   | **85.7%**    |
+| recall@3                                        | **100.0%**   | **92.9%**    |
+| MRR                                             | **100.0%**   | **89.3%**    |
+| Negative precision (irrelevant queries → empty) | **100.0%**   | **100.0%**   |
+| Tokens injected per query vs. total context     | **~7%**      | **~13%**     |
+| Mixed-script queries (Korean + English)         | ✅           | ✅           |
+
+Generalization gap (DEV − HOLDOUT) = **10.0 pts**. The HOLDOUT fixture is reserved for reporting only — the autoresearch loop never tunes against it. Reproduce with `npm run eval:ranked`; see [`tests/eval/RUBRIC.md`](https://github.com/handsupmin/gc-tree/blob/main/tests/eval/RUBRIC.md) for the scoring rules.
 
 ---
 
@@ -201,6 +204,14 @@ gctree update-global-context   # or: gctree update-gc / gctree ugc
 
 Guided update flow — your AI tool asks what changed and writes the new context back to the gc-branch.
 
+### Keep gc-tree itself current
+
+```bash
+gctree update
+```
+
+Updates `@handsupmin/gc-tree` to the latest npm version, then re-scaffolds every provider you previously installed. Use it when gc-tree ships better hooks, commands, skills, or integration snippets and you want your existing setup refreshed in one move.
+
 ### Scope a context to specific repos
 
 ```bash

package/README.zh.md

@@ -137,15 +137,18 @@ AI 工具拿到的是正确的上下文——不是整个知识库，而是恰
 
 ## 经过验证的性能
 
-基于真实内部文档测试（4 份 Notion 导出，中英文混合查询）：
+双 fixture 评测 — **DEV** 对调优循环可见，**HOLDOUT** 仅用于诚实报告（不同领域、硬负例、释义、中英文混合查询）。8 个类别共 38 条带标签用例：exact-keyword、paraphrase、glossary、mixed-language、same-domain distractor、same-domain negative、cross-branch negative。
 
-| 指标                                  | 结果              |
-| ------------------------------------- | ----------------- |
-| Recall——相关查询找到正确文档的比例    | **100%**（16/16） |
-| Precision——无关查询返回空结果的比例   | **80%**（4/5）    |
-| F1 分数                               | **88.9%**         |
-| 每次查询注入的 token 占总上下文的比例 | **约 4%**         |
-| 支持中英文混合查询                    | ✅                |
+| 指标                                       | DEV          | HOLDOUT      |
+| ------------------------------------------ | ------------ | ------------ |
+| recall@1                                   | **100.0%**   | **85.7%**    |
+| recall@3                                   | **100.0%**   | **92.9%**    |
+| MRR                                        | **100.0%**   | **89.3%**    |
+| 无关查询 → 空（negative precision）         | **100.0%**   | **100.0%**   |
+| 每次查询注入的 token 占总上下文比例        | **约 7%**    | **约 13%**   |
+| 混合脚本查询（中文 + 英文）                | ✅           | ✅           |
+
+泛化差（DEV − HOLDOUT）= **10.0 pt**。HOLDOUT fixture 仅用于报告 — autoresearch 循环绝不会对它进行调优。运行 `npm run eval:ranked` 复现；评分规则见 [`tests/eval/RUBRIC.md`](https://github.com/handsupmin/gc-tree/blob/main/tests/eval/RUBRIC.md)。
 
 ---
 
@@ -201,6 +204,14 @@ gctree update-global-context   # 或：gctree update-gc / gctree ugc
 
 引导式更新流程——AI 工具询问发生了哪些变化，并将新上下文写回 gc-branch。
 
+### 保持 gc-tree 本身为最新
+
+```bash
+gctree update
+```
+
+将 `@handsupmin/gc-tree` 更新到最新 npm 版本，然后重新安装之前已安装的所有 provider。当 gc-tree 发布更好的 hook、command、skill 或集成片段时，可以用这一条命令刷新现有设置。
+
 ### 限定上下文作用的仓库范围
 
 ```bash

package/dist/src/onboarding-protocol.js

@@ -34,6 +34,8 @@ export function onboardingProtocolLines() {
         'Prefer category directories such as `docs/role/`, `docs/repos/`, `docs/domain/`, `docs/workflows/`, `docs/conventions/`, and `docs/infra/` whenever that split fits the material.',
         'Prefer one concept, one repository, one workflow, or one convention per file when possible.',
         'Index entries are the search surface — maximize keyword density. For each doc, generate index entries from: primary concept names, aliases, repo nicknames, workflow names, field names, command names, acronyms, related terms a developer might search for, and any term that would make someone want to open this doc. Do NOT be conservative — more keywords means more chances of being found.',
+        '**Bilingual index for retrieval**: gc-tree retrieval is token-overlap based and cannot translate at query time. Whenever the workflow language is not English, every doc\'s `## Index Entries` MUST include BOTH the workflow language AND English for every technical term, concept, repo nickname, workflow name, and glossary acronym. The same rule applies in reverse: if the workflow language is English but the team uses non-English domain terms (Korean, Japanese, Chinese product names, etc.), include those non-English forms too. Example for a Korean workflow language: a `netcode` doc must list `client-server authoritative model`, `authoritative server`, AND `클라이언트-서버 권위 모델`, `권위 서버`. Acronyms (JWT, EMPI, VCF, FHIR) stay in original form in both languages. Doc body and `## Summary` stay primarily in the workflow language; bilingual coverage lives in the index.',
+        '`## Summary` should keep canonical proper-noun technical terms in their original language (Stripe, MLflow, BAM, VCF, JWT, FHIR, Kubernetes, etc.) so token retrieval still hits when the user queries in English. Add the workflow-language paraphrase next to the term when the meaning is non-obvious — e.g. "JWT 토큰 무효화 (token invalidation)".',
         'The index format groups keywords under their path: top-level `- docs/path.md` with indented `  - keyword` lines under it. This keeps the index compact while allowing many keywords per doc.',
         'Split glossary docs when a concept is likely to be searched directly, needs more than a short definition, or carries workflow/constraint details; keep only low-value leftover terms in a shared glossary.',
         'The `## Summary` section of every doc must be actionable, not descriptive — write the actual patterns, commands, or constraints a developer needs, not a sentence about what the doc covers. Bad: "이 문서는 updateCollection 패턴을 설명합니다." Good: "updateCollection: { ...dto } spread 필수. return plainToInstance(Res, result satisfies Res). 새 필드 추가 = DTO → 서비스 → 컨트롤러 순서." The summary is injected into the AI context before every task — if it reads like a table of contents entry, it is useless.',

package/dist/src/resolve.js

@@ -33,10 +33,20 @@ function countTokenMatches(text, tokens) {
     const haystack = String(text || '').toLowerCase();
     return tokens.reduce((sum, token) => {
         try {
-            return sum + (makeTokenRegex(token).test(haystack) ? 1 : 0);
+            if (makeTokenRegex(token).test(haystack))
+                return sum + 1;
+            // Prefix-stem fallback for long ASCII tokens. Conservative: token must be
+            // >=9 chars and the prefix is 7 chars, so words like "Suspense" (8 chars)
+            // are skipped and cannot collide with unrelated stems like "suspension".
+            // Catches persists/persistence, reconciled/reconciliation, replicated/replication.
+            if (token.length >= 9 && /^[a-z]+$/.test(token)) {
+                const stem = token.slice(0, 7);
+                if (new RegExp(`\\b${stem}[a-z]*\\b`).test(haystack))
+                    return sum + 1;
+            }
+            return sum;
         }
         catch {
-            // Regex construction failed (e.g. special chars in token) — fall back to substring
             return sum + (haystack.includes(token) ? 1 : 0);
         }
     }, 0);

package/dist/src/scaffold.js

@@ -117,6 +117,7 @@ function renderUpdateProtocol() {
         '   - `docs/role/<name>.md` — team member roles, responsibilities',
         '4. Write a `## Summary` that is actionable: actual patterns/commands/constraints a developer needs — not a sentence about what the doc covers.',
         '5. Include a `## Index Entries` section in each doc\'s content with many keywords: aliases, related terms, command names, field names, workflow names, acronyms. More entries = more chances of being found by `gctree resolve`. Fewer than 5 entries almost always means more are needed.',
+        '5a. **Bilingual index entries**: when the workflow language is not English, every doc\'s `## Index Entries` MUST contain BOTH the workflow language AND English forms for every technical term, repo name, workflow name, and concept. gc-tree retrieval is token-overlap based and cannot translate at query time, so a Korean-language doc that omits English aliases will silently miss any English query (and vice versa). Acronyms (JWT, EMPI, VCF) stay in original form in both. Body and `## Summary` stay in the workflow language; bilingual coverage lives in the index.',
         '6. Create a temporary JSON file with the updated `docs[]` and run `gctree __apply-update --input <temp-file>`.',
         '7. Run `gctree verify-onboarding --branch <gc-branch>` and inspect the output:',
         '   - Check that every updated doc appears in the verified doc list.',

package/docs/local-development.es.md

@@ -52,8 +52,8 @@ Además de las pruebas unitarias, una suite de evaluación mide la calidad de re
 ```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:multi-repo       # prueba de aislamiento entre repositorios usando fixtures SaaS sintéticos
+npm run eval:multilingual     # comprobaciones de resolve multilingües
 npm run eval:autoresearch     # bucle iterativo de mejora de resolve (modifica src/resolve.ts en su lugar)
 ```
 
@@ -63,9 +63,9 @@ Líneas base esperadas (ejecuta `npm run eval` para verificar):
 | --- | --- |
 | Sintética (5 escenarios) | 5/5 PASS, media ≥ 90% |
 | Multi-repo | ≥ 80% en total |
-| Real-docs | Recall ≥ 90%, F1 ≥ 80% |
+| Multilingüe | ≥ 80% en total |
 
-Si modificas `src/resolve.ts`, ejecuta `npm test && npm run eval && npm run eval:real-docs` antes de abrir un PR.
+Si modificas `src/resolve.ts`, ejecuta `npm test && npm run eval && npm run eval:multi-repo && npm run eval:multilingual` antes de abrir un PR.
 
 ## Cobertura de pruebas
 

package/docs/local-development.ja.md

@@ -52,8 +52,8 @@ npm test
 ```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:multi-repo       # 合成 SaaS fixture を使ったクロスリポジトリ分離テスト
+npm run eval:multilingual     # 多言語 resolve チェック
 npm run eval:autoresearch     # 反復的な resolve 改善ループ（src/resolve.ts をその場で変更します）
 ```
 
@@ -63,9 +63,9 @@ npm run eval:autoresearch     # 反復的な resolve 改善ループ（src/resol
 | --- | --- |
 | 合成（5 シナリオ） | 5/5 PASS、平均 ≥ 90% |
 | マルチリポジトリ | 全体 ≥ 80% |
-| 実ドキュメント | 再現率 ≥ 90%、F1 ≥ 80% |
+| 多言語 | 全体 ≥ 80% |
 
-`src/resolve.ts` を変更した場合は、PR を開く前に `npm test && npm run eval && npm run eval:real-docs` を実行してください。
+`src/resolve.ts` を変更した場合は、PR を開く前に `npm test && npm run eval && npm run eval:multi-repo && npm run eval:multilingual` を実行してください。
 
 ## テストカバレッジ
 

package/docs/local-development.ko.md

@@ -52,8 +52,8 @@ npm test
 ```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:multi-repo       # 합성 SaaS fixture를 사용한 크로스 저장소 격리 테스트
+npm run eval:multilingual     # 다국어 resolve 확인
 npm run eval:autoresearch     # 반복적 resolve 개선 루프 (src/resolve.ts를 직접 수정함)
 ```
 
@@ -63,9 +63,9 @@ npm run eval:autoresearch     # 반복적 resolve 개선 루프 (src/resolve.ts
 | --- | --- |
 | 합성 (5 시나리오) | 5/5 PASS, 평균 ≥ 90% |
 | 다중 저장소 | 전체 ≥ 80% |
-| 실제 문서 | 재현율 ≥ 90%, F1 ≥ 80% |
+| 다국어 | 전체 ≥ 80% |
 
-`src/resolve.ts`를 수정한 경우, PR을 열기 전에 `npm test && npm run eval && npm run eval:real-docs`를 실행하세요.
+`src/resolve.ts`를 수정한 경우, PR을 열기 전에 `npm test && npm run eval && npm run eval:multi-repo && npm run eval:multilingual`을 실행하세요.
 
 ## 테스트 커버리지
 

package/docs/local-development.md

@@ -52,8 +52,8 @@ In addition to the unit tests, an eval suite measures resolve quality against re
 ```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:multi-repo       # cross-repo isolation test using synthetic SaaS fixtures
+npm run eval:multilingual     # mixed-language resolve checks
 npm run eval:autoresearch     # iterative resolve improvement loop (modifies src/resolve.ts in place)
 ```
 
@@ -63,9 +63,9 @@ Expected baselines (run `npm run eval` to verify):
 | --- | --- |
 | Synthetic (5 scenarios) | 5/5 PASS, mean ≥ 90% |
 | Multi-repo | ≥ 80% overall |
-| Real-docs | Recall ≥ 90%, F1 ≥ 80% |
+| Multilingual | ≥ 80% overall |
 
-If you modify `src/resolve.ts`, run `npm test && npm run eval && npm run eval:real-docs` before opening a PR.
+If you modify `src/resolve.ts`, run `npm test && npm run eval && npm run eval:multi-repo && npm run eval:multilingual` before opening a PR.
 
 ## Test coverage
 

package/docs/local-development.zh.md

@@ -52,8 +52,8 @@ npm test
 ```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:multi-repo       # 使用合成 SaaS fixture 的跨仓库隔离测试
+npm run eval:multilingual     # 多语言 resolve 检查
 npm run eval:autoresearch     # 迭代式 resolve 改进循环（会直接修改 src/resolve.ts）
 ```
 
@@ -63,9 +63,9 @@ npm run eval:autoresearch     # 迭代式 resolve 改进循环（会直接修改
 | --- | --- |
 | 综合（5 场景） | 5/5 PASS，均值 ≥ 90% |
 | 多仓库 | 整体 ≥ 80% |
-| 真实文档 | Recall ≥ 90%，F1 ≥ 80% |
+| 多语言 | 整体 ≥ 80% |
 
-如果你修改了 `src/resolve.ts`，在发 PR 之前请运行 `npm test && npm run eval && npm run eval:real-docs`。
+如果你修改了 `src/resolve.ts`，在发 PR 之前请运行 `npm test && npm run eval && npm run eval:multi-repo && npm run eval:multilingual`。
 
 ## 测试覆盖范围
 

package/docs/principles.es.md

@@ -77,3 +77,12 @@ En la práctica, esto significa que se inyecta aproximadamente el 4 % del contex
 `gctree` almacena el contexto en archivos markdown simples que cualquier herramienta puede leer.
 Claude Code y Codex usan el mismo almacén subyacente. `gctree init` instala la superficie global de hooks orientada al proveedor, y `gctree scaffold` es la ruta de override local para un repositorio o workspace concreto.
 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.
+
+## 9. Entradas de índice bilingües cuando el idioma del flujo no es inglés
+
+`gctree resolve` se basa en superposición de tokens — no traduce en el momento de la consulta.
+Un documento escrito solo en español (o coreano, japonés, chino) nunca coincidirá con una consulta en inglés, y viceversa.
+
+Para evitarlo, los flujos de onboarding y de actualización durable exigen **`## Index Entries` bilingües siempre que el idioma del flujo no sea inglés**. Cada término técnico, nombre de repositorio, nombre de workflow y concepto aparece tanto en el idioma del flujo como en inglés. Las siglas (JWT, EMPI, VCF, FHIR) se mantienen en su forma original en ambas listas.
+
+El cuerpo del documento y `## Summary` se mantienen en el idioma del flujo por legibilidad; la cobertura bilingüe vive en el índice, donde la recuperación la necesita. `## Summary` conserva los términos técnicos de nombre propio (Stripe, MLflow, JWT, FHIR, Kubernetes) en su idioma original y agrega una paráfrasis en el idioma del flujo solo cuando el significado no es obvio — p. ej. `invalidación de token JWT (token invalidation)`.

package/docs/principles.ja.md

@@ -77,3 +77,12 @@ gc-branch がマシン上のすべてのリポジトリに黙って影響して
 `gctree` はコンテキストをプレーンなマークダウンファイルとして保存するため、どのツールでも読み込めます。
 Claude Code と Codex はどちらも同じ基盤ストアを使います。`gctree init` はグローバルなプロバイダーフック面をインストールし、`gctree scaffold` は1つのリポジトリやワークスペース向けのローカル override 経路です。
 新しいプロバイダーのサポートを追加するには、新しい scaffold テンプレートを書くだけです。コアのストレージや resolve ロジックに変更は不要です。
+
+## 9. ワークフロー言語が英語でない場合、インデックスエントリは二言語で
+
+`gctree resolve` はトークン重なりベース — クエリ時に翻訳は行いません。
+日本語のみで書かれたドキュメントは英語クエリで決してヒットせず、その逆も同様です。
+
+この制約を防ぐため、オンボーディングと durable アップデートのフローは **ワークフロー言語が英語でない場合に `## Index Entries` を二言語で** 必須としています。すべての技術用語、リポジトリ名、ワークフロー名、概念を、ワークフロー言語と英語の両方で列挙します。略語（JWT、EMPI、VCF、FHIR）は両方とも原形のままです。
+
+ドキュメント本文と `## Summary` は可読性のためワークフロー言語を維持し、二言語カバレッジは検索が行われるインデックスにだけ置きます。`## Summary` は固有名詞の技術用語（Stripe、MLflow、JWT、FHIR、Kubernetes）を原語のまま残し、意味が自明でない場合にのみワークフロー言語の言い換えを併記します。例: `JWT トークン無効化 (token invalidation)`。

package/docs/principles.ko.md

@@ -77,3 +77,12 @@ gc-branch에 이미 컨텍스트가 있다면, 올바른 경로는 다음 중
 `gctree`는 어떤 도구든 읽을 수 있는 일반 마크다운 파일에 컨텍스트를 저장합니다.
 Claude Code와 Codex 모두 동일한 기반 저장소를 사용합니다. `gctree init`은 전역 프로바이더 훅 표면을 설치하고, `gctree scaffold`는 한 저장소나 워크스페이스를 위한 로컬 override 경로입니다.
 새로운 프로바이더 지원 추가는 새 scaffold 템플릿을 작성하는 것을 의미합니다 — 핵심 저장소나 resolve 로직은 변경이 필요 없습니다.
+
+## 9. 워크플로 언어가 영어가 아니라면 인덱스 항목은 이중 언어로
+
+`gctree resolve`는 토큰 오버랩 기반입니다 — 쿼리 시점에 번역하지 않습니다.
+한국어로만 작성된 문서는 영어 쿼리에 절대 매칭되지 않으며, 그 반대도 마찬가지입니다.
+
+이 한계를 막기 위해 온보딩과 durable 업데이트 플로우는 **워크플로 언어가 영어가 아닐 경우 `## Index Entries`를 이중 언어로** 강제합니다. 모든 기술 용어, 레포 이름, 워크플로 이름, 개념을 워크플로 언어와 영어 양쪽 모두로 나열합니다. 약어(JWT, EMPI, VCF, FHIR)는 양쪽 모두 원형 그대로 둡니다.
+
+문서 본문과 `## Summary`는 가독성을 위해 워크플로 언어를 유지하고, 이중 언어 커버리지는 인덱스 — 검색이 일어나는 곳 — 에만 둡니다. `## Summary`는 고유 명사 기술 용어(Stripe, MLflow, JWT, FHIR, Kubernetes)를 원어 그대로 유지하고, 의미가 불명확한 경우에만 워크플로 언어 보조 표현을 병기합니다. 예: `JWT 토큰 무효화 (token invalidation)`.

package/docs/principles.md

@@ -77,3 +77,12 @@ In practice this means roughly 4% of total stored context is injected per query.
 `gctree` stores context in plain markdown files that any tool can read.
 Claude Code and Codex both use the same underlying store. `gctree init` installs the global provider-facing hook surface, and `gctree scaffold` is the local override path for one repository or workspace.
 Adding support for a new provider means writing a new scaffold template — no changes to the core storage or resolve logic.
+
+## 9. Bilingual index entries when the workflow language is not English
+
+`gctree resolve` is token-overlap based — it does not translate at query time.
+A doc written purely in Korean (or Japanese, Chinese, Spanish, etc.) will silently miss any English query, and vice versa.
+
+The onboarding and durable-update flows enforce **bilingual `## Index Entries`** whenever the workflow language is not English. Every technical term, repo name, workflow name, and concept appears in BOTH the workflow language and English. Acronyms (JWT, EMPI, VCF, FHIR) stay in their original form in both lists.
+
+Doc body and `## Summary` stay in the workflow language for readability; bilingual coverage lives in the index, where retrieval needs it. `## Summary` preserves canonical proper-noun technical terms (Stripe, MLflow, JWT, FHIR, Kubernetes) in their original language and adds a workflow-language paraphrase only when the meaning is non-obvious — e.g. `JWT 토큰 무효화 (token invalidation)`.

package/docs/principles.zh.md

@@ -77,3 +77,12 @@ Onboarding 仅适用于空的 gc-branch。
 `gctree` 将上下文存储在任何工具都能读取的纯 Markdown 文件中。
 Claude Code 和 Codex 使用同一个底层存储。`gctree init` 安装全局 provider hook 表面，`gctree scaffold` 则是针对单个仓库或工作区的本地 override 路径。
 添加对新提供商的支持，意味着编写一个新的 scaffold 模板——无需对核心存储或 resolve 逻辑做任何修改。
+
+## 9. 工作流语言不是英文时，索引条目必须双语
+
+`gctree resolve` 基于 token 重叠匹配——查询时不做翻译。
+仅用中文撰写的文档不会匹配任何英文查询，反之亦然。
+
+为防止这种漏检，onboarding 和 durable 更新流程在 **工作流语言不是英文时强制 `## Index Entries` 双语**。每个技术术语、仓库名、工作流名和概念都同时列出工作流语言和英文。缩写（JWT、EMPI、VCF、FHIR）在两侧都保持原形。
+
+文档正文和 `## Summary` 保持工作流语言以便阅读；双语覆盖只放在检索发生的索引中。`## Summary` 保留专有名词技术术语（Stripe、MLflow、JWT、FHIR、Kubernetes）的原文形式，仅在含义不明显时附上工作流语言的同义表达。例如：`JWT 令牌失效 (token invalidation)`。

package/docs/usage.es.md

@@ -4,7 +4,7 @@
 
 ## Resumen
 
-Un flujo de trabajo estándar con `gctree` tiene este aspecto: inicializar gc-tree, elegir un proveedor, hacer onboarding de la gc-branch `main` predeterminada, hacer resolve del contexto que necesitas, crear nuevas gc-branches cuando el trabajo merece su propio carril, mapear los repositorios a las gc-branches correctas y usar actualizaciones guiadas para cambios duraderos más adelante.
+Un flujo de trabajo estándar con `gctree` tiene este aspecto: inicializar gc-tree, elegir un proveedor, hacer onboarding de la gc-branch `main` predeterminada, hacer resolve del contexto que necesitas, crear nuevas gc-branches cuando el trabajo merece su propio carril, mapear los repositorios a las gc-branches correctas, usar actualizaciones guiadas para cambios duraderos de contexto y ejecutar `gctree update` cuando quieras refrescar la CLI y las integraciones de providers instaladas.
 
 ## Flujo de trabajo estándar
 
@@ -19,7 +19,8 @@ Un flujo de trabajo estándar con `gctree` tiene este aspecto: inicializar gc-tr
 9. crear o cambiar de gc-branch con `gctree checkout`
 10. ejecutar `gctree onboard` solo para una gc-branch vacía
 11. usar el mapeo de alcance del repositorio para que una gc-branch solo aplique donde corresponde
-12. usar `gctree update-global-context` para cambios duraderos más adelante
+12. usar `gctree update-global-context` para cambios duraderos de contexto más adelante
+13. usar `gctree update` para actualizar gc-tree y reinstalar los providers instalados
 
 ## Comandos principales
 
@@ -111,7 +112,7 @@ Luego:
 ## Ejemplo de flujo con múltiples branches
 
 ```bash
-gctree checkout -b client-b
+gctree checkout -b project-b
 gctree onboard
 gctree resolve --query "billing retry policy"
 ```
@@ -134,6 +135,14 @@ Si un repositorio recién relevante también debería pasar a formar parte del c
 1. mapear ese repositorio a la gc-branch
 2. luego ejecutar `update-global-context` para agregar conocimiento duradero sobre qué hace ese repositorio y por qué es importante
 
+## Ejemplo de flujo de actualización de la herramienta
+
+```bash
+gctree update
+```
+
+Esto actualiza `@handsupmin/gc-tree` a la última versión de npm y reinstala todos los providers ya instalados mediante `gctree init` o `gctree scaffold`. Es el comando de mantenimiento para cuando se publiquen nuevos hooks, comandos, skills o snippets de integración.
+
 ## Patrones de integración
 
 ### Codex CLI / Claude Code CLI

package/docs/usage.ja.md

@@ -4,7 +4,7 @@
 
 ## 概要
 
-標準的な `gctree` の流れはこうです。gc-tree を初期化し、プロバイダーを選び、デフォルトの `main` gc-branch をオンボードし、必要なコンテキストを resolve で引き、作業に応じて新しい gc-branch を作り、リポジトリを適切な gc-branch に結び付け、後からの永続的な変更はガイド付き更新で反映していきます。
+標準的な `gctree` の流れはこうです。gc-tree を初期化し、プロバイダーを選び、デフォルトの `main` gc-branch をオンボードし、必要なコンテキストを resolve で引き、作業に応じて新しい gc-branch を作り、リポジトリを適切な gc-branch に結び付け、後からの永続的なコンテキスト変更はガイド付き更新で反映し、CLI とインストール済みプロバイダー統合を更新したいときは `gctree update` を実行します。
 
 ## 標準ワークフロー
 
@@ -19,7 +19,8 @@
 9. `gctree checkout` で gc-branch を作成または切り替える
 10. `gctree onboard` は空の gc-branch に対してだけ使う
 11. repo scope を設定して gc-branch が本来のリポジトリにだけ作用するようにする
-12. 後からの永続的な変更には `gctree update-global-context` を使う
+12. 後からの永続的なコンテキスト変更には `gctree update-global-context` を使う
+13. gc-tree 自体とインストール済みプロバイダーを更新するには `gctree update` を使う
 
 ## 主要コマンド
 
@@ -111,7 +112,7 @@ gctree init
 ## 複数ブランチを使う例
 
 ```bash
-gctree checkout -b client-b
+gctree checkout -b project-b
 gctree onboard
 gctree resolve --query "billing retry policy"
 ```
@@ -134,6 +135,14 @@ gctree ugc
 1. まずそのリポジトリを gc-branch にマップする
 2. その後 `update-global-context` を実行して、そのリポジトリが何を担い、なぜ重要なのかという永続的な知識を追加する
 
+## ツール更新の例
+
+```bash
+gctree update
+```
+
+`@handsupmin/gc-tree` を最新の npm バージョンに更新し、`gctree init` または `gctree scaffold` でインストール済みのすべてのプロバイダーを再スキャフォールドします。新しいフック、コマンド、スキル、統合スニペットが配布されたときに使うメンテナンスコマンドです。
+
 ## 統合パターン
 
 ### Codex CLI / Claude Code CLI

package/docs/usage.ko.md

@@ -4,7 +4,7 @@
 
 ## 요약
 
-표준 `gctree` 워크플로우는 다음과 같습니다: gc-tree 초기화, 프로바이더 선택, 기본 `main` gc-branch 온보딩, 필요한 컨텍스트 resolve, 작업별로 새 gc-branch 생성, 저장소를 올바른 gc-branch에 매핑, 이후 지속 변경 시 안내된 업데이트 사용.
+표준 `gctree` 워크플로우는 다음과 같습니다: gc-tree 초기화, 프로바이더 선택, 기본 `main` gc-branch 온보딩, 필요한 컨텍스트 resolve, 작업별로 새 gc-branch 생성, 저장소를 올바른 gc-branch에 매핑, 이후 지속 컨텍스트 변경 시 안내된 업데이트 사용, CLI와 설치된 프로바이더 통합을 새로고침할 때 `gctree update` 실행.
 
 ## 표준 워크플로우
 
@@ -19,7 +19,8 @@
 9. `gctree checkout`으로 gc-branch 생성 또는 전환
 10. 빈 gc-branch에만 `gctree onboard` 실행
 11. 저장소 범위 매핑으로 gc-branch가 해당하는 곳에만 적용되도록 설정
-12. 이후 지속 변경에는 `gctree update-global-context` 사용
+12. 이후 지속 컨텍스트 변경에는 `gctree update-global-context` 사용
+13. gc-tree 자체와 설치된 프로바이더를 새로고침하려면 `gctree update` 사용
 
 ## 핵심 명령어
 
@@ -111,7 +112,7 @@ gctree init
 ## 다중 브랜치 예시 흐름
 
 ```bash
-gctree checkout -b client-b
+gctree checkout -b project-b
 gctree onboard
 gctree resolve --query "billing retry policy"
 ```
@@ -134,6 +135,14 @@ gctree ugc
 1. 해당 저장소를 gc-branch에 매핑
 2. `update-global-context`를 실행하여 해당 저장소가 무엇을 하고 왜 중요한지에 대한 지속 지식 추가
 
+## 도구 업데이트 예시 흐름
+
+```bash
+gctree update
+```
+
+`@handsupmin/gc-tree`를 최신 npm 버전으로 업데이트하고, `gctree init` 또는 `gctree scaffold`로 이미 설치한 모든 프로바이더를 다시 스캐폴드합니다. 새 훅, 명령, 스킬, 통합 스니펫이 배포됐을 때 실행하는 유지보수 명령입니다.
+
 ## 통합 패턴
 
 ### Codex CLI / Claude Code CLI

package/docs/usage.md

@@ -4,7 +4,7 @@
 
 ## Summary
 
-A standard `gctree` workflow looks like this: initialize gc-tree, choose a provider, onboard the default `main` gc-branch, resolve the context you need, create new gc-branches when work deserves its own lane, map repositories to the right gc-branches, and use guided updates for durable changes later.
+A standard `gctree` workflow looks like this: initialize gc-tree, choose a provider, onboard the default `main` gc-branch, resolve the context you need, create new gc-branches when work deserves its own lane, map repositories to the right gc-branches, use guided updates for durable context changes, and run `gctree update` when you want the CLI plus installed provider integrations refreshed.
 
 ## Standard workflow
 
@@ -19,7 +19,8 @@ A standard `gctree` workflow looks like this: initialize gc-tree, choose a provi
 9. create or switch gc-branches with `gctree checkout`
 10. run `gctree onboard` only for an empty gc-branch
 11. use repo scope mapping so a gc-branch only applies where it belongs
-12. use `gctree update-global-context` for durable changes later
+12. use `gctree update-global-context` for durable context changes later
+13. use `gctree update` to update gc-tree itself and re-scaffold installed providers
 
 ## Core commands
 
@@ -111,7 +112,7 @@ Then:
 ## Example multi-branch flow
 
 ```bash
-gctree checkout -b client-b
+gctree checkout -b project-b
 gctree onboard
 gctree resolve --query "billing retry policy"
 ```
@@ -134,6 +135,14 @@ If a newly relevant repo should also become part of the durable context, the nat
 1. map that repo to the gc-branch
 2. then run `update-global-context` to add durable knowledge about what that repo does and why it matters
 
+## Example tool update flow
+
+```bash
+gctree update
+```
+
+This updates `@handsupmin/gc-tree` to the latest npm version and re-scaffolds every provider already installed through `gctree init` or `gctree scaffold`. It is the maintenance command to run when new provider hooks, commands, skills, or integration snippets ship.
+
 ## Integration patterns
 
 ### Codex CLI / Claude Code CLI

package/docs/usage.zh.md

@@ -4,7 +4,7 @@
 
 ## 概述
 
-标准的 `gctree` 工作流如下：初始化 gc-tree、选择提供商、对默认的 `main` gc-branch 执行 onboard、解析所需上下文、在工作需要独立空间时创建新的 gc-branch、将代码仓库映射到正确的 gc-branch，以及在后续使用有引导的更新流程进行持久化变更。
+标准的 `gctree` 工作流如下：初始化 gc-tree、选择提供商、对默认的 `main` gc-branch 执行 onboard、解析所需上下文、在工作需要独立空间时创建新的 gc-branch、将代码仓库映射到正确的 gc-branch、在后续使用有引导的流程更新持久化上下文，并在需要刷新 CLI 和已安装 provider 集成时运行 `gctree update`。
 
 ## 标准工作流
 
@@ -19,7 +19,8 @@
 9. 使用 `gctree checkout` 创建或切换 gc-branch
 10. 仅对空的 gc-branch 运行 `gctree onboard`
 11. 使用仓库作用范围映射，使 gc-branch 只在其适用的地方生效
-12. 使用 `gctree update-global-context` 进行后续的持久化变更
+12. 使用 `gctree update-global-context` 进行后续的持久化上下文变更
+13. 使用 `gctree update` 更新 gc-tree 本身并重新安装已安装的 provider
 
 ## 核心命令
 
@@ -111,7 +112,7 @@ gctree init
 ## 多分支示例流程
 
 ```bash
-gctree checkout -b client-b
+gctree checkout -b project-b
 gctree onboard
 gctree resolve --query "billing retry policy"
 ```
@@ -134,6 +135,14 @@ gctree ugc
 1. 将该仓库映射到 gc-branch
 2. 然后运行 `update-global-context`，添加关于该仓库用途及重要性的持久化知识
 
+## 工具更新示例流程
+
+```bash
+gctree update
+```
+
+这会将 `@handsupmin/gc-tree` 更新到最新 npm 版本，并重新安装通过 `gctree init` 或 `gctree scaffold` 已安装的所有 provider。当新的 hook、command、skill 或集成片段发布时，可以用它进行维护更新。
+
 ## 集成模式
 
 ### Codex CLI / Claude Code CLI

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@handsupmin/gc-tree",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Global Context Tree, a lightweight branch-aware global context orchestrator for AI coding tools",
   "type": "module",
   "private": false,
@@ -26,10 +26,12 @@
     "eval:multi-repo": "node --import tsx tests/eval/multi-repo.ts",
     "eval:multi-repo:verbose": "node --import tsx tests/eval/multi-repo.ts --verbose",
     "eval:autoresearch": "node --import tsx tests/eval/autoresearch.ts",
+    "eval:autoresearch:strict": "node --import tsx tests/eval/autoresearch.ts --strict",
     "eval:multilingual": "node --import tsx tests/eval/multilingual.ts",
     "eval:multilingual:verbose": "node --import tsx tests/eval/multilingual.ts --verbose",
-    "eval:real-docs": "node --import tsx tests/eval/real-docs.ts",
-    "eval:real-docs:verbose": "node --import tsx tests/eval/real-docs.ts --verbose"
+    "eval:ranked": "node --import tsx tests/eval/ranked.ts",
+    "eval:ranked:verbose": "node --import tsx tests/eval/ranked.ts --verbose",
+    "eval:ranked:variance": "node --import tsx tests/eval/ranked.ts --runs 3"
   },
   "engines": {
     "node": ">=20"

package/skills/onboard/SKILL.md

@@ -44,6 +44,8 @@ Use this when a user wants to create global context for a product, company, or w
 - prefer category directories like `docs/role/`, `docs/repos/`, `docs/domain/`, `docs/workflows/`, `docs/conventions/`, and `docs/infra/`
 - prefer one concept, one repository, one workflow, or one convention per file when possible
 - treat `index.md` as the search surface — maximize keyword density; for each doc generate entries from: primary names, aliases, nicknames, field names, command names, acronyms, related terms a developer might search for; do NOT be conservative — more keywords = more chances of being found; fewer than 5 index entries per doc almost certainly means more are needed
+- **bilingual index entries**: gc-tree retrieval is token-overlap based and cannot translate at query time. When the workflow language is not English, every doc's `## Index Entries` MUST include BOTH the workflow-language form AND the English form for every technical term, concept, repo nickname, workflow name, and glossary term. Same rule in reverse if the workflow language is English but team uses non-English domain terms. Acronyms (JWT, EMPI, VCF, FHIR) stay in original form in both lists. Doc body and `## Summary` remain in the workflow language; the bilingual coverage lives in the index. Example for Korean workflow language: a netcode doc must list both `authoritative server`, `client-server authoritative model` AND `권위 서버`, `클라이언트-서버 권위 모델`
+- in `## Summary`, keep canonical proper-noun technical terms in their original language (Stripe, MLflow, JWT, FHIR, Kubernetes, BAM, VCF) so English token queries still hit; add a workflow-language paraphrase next to any term whose meaning is non-obvious — e.g. "JWT 토큰 무효화 (token invalidation)"
 - generate index entries automatically from primary concept names, aliases, repository nicknames, and workflow labels when those are clear
 - split glossary docs when a concept is likely to be searched directly, needs more than a short definition, or carries workflow/constraint details; keep only low-value leftover terms in a shared glossary
 - index format: top-level `- docs/path.md` with indented `  - keyword` lines under it — groups all keywords per doc, eliminates path duplication