@handsupmin/gc-tree 1.0.1 → 1.1.1

package/README.es.md

@@ -137,15 +137,18 @@ En el momento en que tienes múltiples repos, proyectos o workstreams:
 
 ## Rendimiento validado
 
-Probado con fixtures sintéticos multidominio y consultas mixtas en español e inglés:
-
-| 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            | ✅               |
+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                                            | 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).
 
 ---
 

package/README.ja.md

@@ -137,15 +137,18 @@ AI ツールに渡るのは正しいコンテキスト——ナレッジベー
 
 ## 検証済みのパフォーマンス
 
-合成マルチドメイン fixture と日本語・英語混合クエリでテスト：
-
-| 指標                                         | 結果              |
-| -------------------------------------------- | ----------------- |
-| Recall——関連クエリが正しい文書を見つける割合 | **100%**（16/16） |
-| Precision——無関係なクエリが空を返す割合      | **80%**（4/5）    |
-| F1 スコア                                    | **88.9%**         |
-| クエリあたりの注入トークン割合（全体比）     | **約 4%**         |
-| 日英混合クエリ対応                           | ✅                |
+二つの fixture による評価 — **DEV** はチューニングループから見える、**HOLDOUT** は誠実な報告用に分離（異なるドメイン、ハードネガティブ、言い換え、日英混合クエリを含む）。8 カテゴリ 38 ラベル付きケース: exact-keyword、paraphrase、glossary、mixed-language、same-domain distractor、same-domain negative、cross-branch negative。
+
+| 指標                                            | 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) を参照。
 
 ---
 

package/README.ko.md

@@ -137,15 +137,18 @@ AI 도구가 올바른 컨텍스트를 가져옵니다. 지식 베이스 전체
 
 ## 검증된 성능
 
-합성 멀티 도메인 fixture와 한국어 + 영어 혼합 쿼리 기준 테스트:
-
-| 지표                                            | 결과             |
-| ----------------------------------------------- | ---------------- |
-| Recall — 관련 쿼리가 올바른 문서를 찾는 비율    | **100%** (16/16) |
-| Precision — 무관 쿼리가 빈 결과를 반환하는 비율 | **80%** (4/5)    |
-| F1 점수                                         | **88.9%**        |
-| 쿼리당 주입 토큰 비율 (전체 컨텍스트 대비)      | **~4%**          |
-| 한국어 + 영어 혼합 쿼리 지원                    | ✅               |
+두 fixture 평가 — **DEV**는 튜닝 루프에 보이고, **HOLDOUT**은 정직한 보고용으로 분리 (다른 도메인, hard negative, 의역, 한국어+영어 혼합 쿼리 포함). 8개 카테고리 38개 라벨 케이스: exact-keyword, paraphrase, glossary, mixed-language, same-domain distractor, same-domain negative, cross-branch negative.
+
+| 지표                                            | 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) 참조.
 
 ---
 

package/README.md

@@ -137,15 +137,18 @@ The moment you have multiple repos, projects, or workstreams:
 
 ## Validated performance
 
-Tested against synthetic multi-domain fixtures and Korean + English mixed queries:
-
-| 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    | ✅               |
+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                                          | 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.
 
 ---
 

package/README.zh.md

@@ -137,15 +137,18 @@ AI 工具拿到的是正确的上下文——不是整个知识库，而是恰
 
 ## 经过验证的性能
 
-基于合成多领域 fixture 以及中英文混合查询测试：
-
-| 指标                                  | 结果              |
-| ------------------------------------- | ----------------- |
-| Recall——相关查询找到正确文档的比例    | **100%**（16/16） |
-| Precision——无关查询返回空结果的比例   | **80%**（4/5）    |
-| F1 分数                               | **88.9%**         |
-| 每次查询注入的 token 占总上下文的比例 | **约 4%**         |
-| 支持中英文混合查询                    | ✅                |
+双 fixture 评测 — **DEV** 对调优循环可见，**HOLDOUT** 仅用于诚实报告（不同领域、硬负例、释义、中英文混合查询）。8 个类别共 38 条带标签用例：exact-keyword、paraphrase、glossary、mixed-language、same-domain distractor、same-domain negative、cross-branch negative。
+
+| 指标                                       | 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)。
 
 ---
 

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@handsupmin/gc-tree",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "description": "Global Context Tree, a lightweight branch-aware global context orchestrator for AI coding tools",
   "type": "module",
   "private": false,
@@ -26,8 +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:multilingual:verbose": "node --import tsx tests/eval/multilingual.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