@handsupmin/gc-tree 0.8.19 → 1.0.1

package/README.md

@@ -16,7 +16,7 @@
 
 <img src="./logo.png" alt="gc-tree logo" width="260" />
 
-### Global context, beyond the project.
+### Global context beyond CLAUDE.md and AGENTS.md.
 
 Attach durable, reusable context to your existing AI tools.
 Manage multiple contexts like Git branches.
@@ -35,16 +35,24 @@ Manage multiple contexts like Git branches.
 
 ## The problem
 
-You use Claude Code or Codex every day. But your real work spans multiple repos, products, and clients — and your AI tools only know about the current file.
+AI does not know you.
+
+It does not know how you work, which terms your team uses, how one repo connects to another, or which routines you repeat without thinking. If you do not explain those things precisely, you rarely get the result you actually wanted.
 
 So you end up doing this every session:
 
+- Re-introduce who you are and how you work
+- Re-explain the domain language your team uses
 - Re-explain which repos belong together
 - Paste the same architecture doc into the prompt again
 - Remind the agent about conventions it already "knew" last week
 - Manually strip context that's irrelevant to the current repo
 
-That's not an AI problem. It's a **context management problem**.
+That's not because AI is stupid. It's because this kind of context is hard to keep alive inside one workspace, especially when real work moves across multiple repos and projects.
+
+`CLAUDE.md` and `AGENTS.md` help a lot inside one repo. But once work crosses repo boundaries, shared background knowledge gets duplicated, repo relationships are hard to express, and every new session starts from too little.
+
+`gc-tree` exists to remove that repetition.
 
 ---
 
@@ -52,12 +60,12 @@ That's not an AI problem. It's a **context management problem**.
 
 You'll get the most out of `gc-tree` if you:
 
-- Work across **multiple repos** (monorepo teams, platform + client repos, backend + frontend stacks)
-- Switch between **multiple products or clients** in the same week
+- Work across **multiple repos** (monorepo teams, platform repos, backend + frontend stacks)
+- Move between **multiple products, projects, or workstreams**
 - Find yourself **re-explaining the same context** at the start of every AI session
-- Want AI tools to understand your **conventions, architecture, and domain knowledge** — not just the current file
+- Want AI tools to understand your **working style, team terminology, architecture, and domain knowledge** — not just the current file
 
-If you only ever work in one repo and one product, you probably don't need this. `CLAUDE.md` or `.cursorrules` is enough.
+If you only ever work in one repo and one product, you probably don't need this. `CLAUDE.md` or `AGENTS.md` is enough.
 
 ---
 
@@ -74,7 +82,7 @@ gctree init
 2. Scaffold the integration files into your current repo
 3. Run guided onboarding for the `main` gc-branch
 
-After that, your AI tool gets real SessionStart/UserPromptSubmit hook integration, so it auto-checks gc-tree before work and caches empty/no-match results for the session. Hook output stays compact: it reports found/no-match state plus matching document titles and IDs, and full docs stay behind `gctree resolve --id <id>`.
+After that, your AI tool gets real SessionStart/UserPromptSubmit hook integration, so it auto-checks gc-tree before work and caches empty/no-match results for the session. Hook output injects matched document summaries directly into context — so the AI sees actual patterns and commands, not just titles. Full docs are always available on demand via `gctree resolve --id <id>`.
 
 - **CLI:** `gctree`
 - **Requires:** Node.js 20+
@@ -83,7 +91,7 @@ After that, your AI tool gets real SessionStart/UserPromptSubmit hook integratio
 
 ## What gc-tree does
 
-`gc-tree` sits **above the repo level**. It stores durable context in structured markdown files and lets your AI tools pull only what's relevant — before each session, automatically.
+`gc-tree` sits **above the repo level**. It stores your working style, team terminology, repo relationships, and shared background knowledge as durable global context. Your AI tools then pull only what's relevant before each session, automatically.
 
 `gctree resolve` is the compact **index layer** in a progressive-disclosure workflow:
 
@@ -97,18 +105,10 @@ When no docs exist, a repo is excluded, or a query has no hits, gc-tree returns
 gctree resolve --query "auth token rotation policy"
 ```
 
-```json
-{
-  "gc_branch": "main",
-  "matches": [
-    {
-      "title": "Auth & Session Conventions",
-      "score": 4,
-      "summary": "JWT rotation on every request, refresh tokens stored in httpOnly cookies, 15-min access token TTL",
-      "excerpt": "## Auth Flow\nAccess token: 15-min TTL, rotated on every authenticated request..."
-    }
-  ]
-}
+```
+[gc-tree] 1 matching doc  gc-branch="main"  repo="my-repo"
+[Auth & Session Conventions] JWT rotation on every request, refresh tokens in httpOnly cookies, 15-min access token TTL
+[Auth & Session Conventions] show full doc: gctree show-doc --id "auth" --branch "main"
 ```
 
 Your AI tool gets the right context. Not the whole knowledge base — just the relevant slice.
@@ -117,17 +117,17 @@ Your AI tool gets the right context. Not the whole knowledge base — just the r
 
 ---
 
-## Why not just use CLAUDE.md or cursor rules?
+## Why not just use CLAUDE.md or AGENTS.md?
 
-`CLAUDE.md` is great — for one repo.
+`CLAUDE.md` and `AGENTS.md` are great — for one repo.
 
-The moment you have multiple repos, clients, or workstreams:
+The moment you have multiple repos, projects, or workstreams:
 
-|                        | `CLAUDE.md` / cursor rules | `gc-tree`                                    |
+|                        | `CLAUDE.md` / `AGENTS.md` | `gc-tree`                                    |
 | ---------------------- | -------------------------- | -------------------------------------------- |
 | Scope                  | One repo                   | Multiple repos, one context                  |
 | Persistence            | Per-repo file              | Stored outside repos, reused across sessions |
-| Switching contexts     | Manual file edits          | `gctree checkout client-b`                   |
+| Switching contexts     | Manual file edits          | `gctree checkout project-b`                  |
 | Relevance filtering    | Everything or nothing      | Only injects matching docs (~4% of total)    |
 | Onboarding             | Hand-written               | Guided by your AI tool                       |
 | Works with Codex       | ✅                         | ✅                                           |
@@ -137,7 +137,7 @@ The moment you have multiple repos, clients, or workstreams:
 
 ## Validated performance
 
-Tested against real internal documentation (4 Notion exports, Korean + English mixed queries):
+Tested against synthetic multi-domain fixtures and Korean + English mixed queries:
 
 | Metric                                       | Result           |
 | -------------------------------------------- | ---------------- |
@@ -167,9 +167,9 @@ Both providers use the same underlying context store. Onboard once, use from eit
 ```
 gctree status → gc_branch: main, doc_count: 2
 gctree resolve --query 'NestJS DTO plainToInstance'
-→ matched "Backend Coding Conventions" (score: 3)
-→ DTO: class-transformer plainToInstance, class-validator required
-→ Error handling: HttpException-based custom exceptions, no raw Error throws
+[gc-tree] 1 matching doc  gc-branch="main"  repo="my-repo"
+[Backend Coding Conventions] DTO: class-transformer plainToInstance, class-validator required. Error handling: HttpException-based custom exceptions, no raw Error throws.
+[Backend Coding Conventions] show full doc: gctree show-doc --id "backend-conventions" --branch "main"
 ```
 
 ---
@@ -179,7 +179,7 @@ gctree resolve --query 'NestJS DTO plainToInstance'
 ### Separate contexts for separate workstreams
 
 ```bash
-gctree checkout -b client-b
+gctree checkout -b project-b
 gctree onboard
 ```
 
@@ -201,11 +201,19 @@ 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
-gctree set-repo-scope --branch client-b --include   # include current repo
-gctree set-repo-scope --branch client-b --exclude   # exclude current repo
+gctree set-repo-scope --branch project-b --include   # include current repo
+gctree set-repo-scope --branch project-b --exclude   # exclude current repo
 ```
 
 `gc-tree` won't inject a context into repos where it doesn't belong.
@@ -222,7 +230,7 @@ gctree set-repo-scope --branch client-b --exclude   # exclude current repo
       docs/
         auth.md         ← full doc, read only when needed
         architecture.md
-    client-b/
+    project-b/
       index.md
       docs/
         ...
@@ -249,6 +257,7 @@ Context lives outside your repos — no `.gitignore` rules needed, no accidental
 | Include/exclude current repo for a gc-branch   | `gctree set-repo-scope --branch <name> --include` / `--exclude` |
 | Reset a gc-branch before re-onboarding         | `gctree reset-gc-branch --branch <name> --yes`                  |
 | Add a local override in one repo               | `gctree scaffold --host codex --target /path/to/repo`           |
+| Update gctree and re-scaffold all providers    | `gctree update`                                                 |
 | Remove global gc-tree activation and context   | `gctree uninstall --yes`                                        |
 
 ---

package/README.zh.md

@@ -16,7 +16,7 @@
 
 <img src="./logo.png" alt="gc-tree logo" width="260" />
 
-### 不止于项目内部的全局上下文。
+### 超越 CLAUDE.md 和 AGENTS.md 的全局上下文。
 
 在你现有的 AI 工具之上，再加一层可复用、能长期积累的上下文。
 像管理 Git 分支一样管理多条上下文线索。
@@ -35,16 +35,24 @@
 
 ## 问题所在
 
-你每天都在用 Claude Code 或 Codex。但你的实际工作横跨多个仓库、产品和客户——而 AI 工具只认识当前文件。
+AI 并不了解你。
+
+它不知道你做什么、怎样工作、团队里的术语是什么意思，也不知道那些你下意识重复的流程。如果你没有把想要的结果解释清楚，就很难得到真正符合预期的输出。
 
 于是你不得不一遍遍地做这些事：
 
+- 重新介绍你是谁、你如何工作
+- 重新解释团队使用的领域语言
 - 重新解释哪些仓库属于同一套系统
 - 把同一份架构文档反复粘贴进提示词
 - 提醒 AI 它上周"已经知道"的编码规范
 - 手动剔除与当前仓库无关的上下文
 
-这不是 AI 的问题，而是**上下文管理的问题**。
+这并不是因为 AI 太笨，而是因为这类上下文很难在一个 workspace 里持续保存。尤其真实工作往往不会停留在单个仓库里，而是在多个仓库和项目之间来回推进。
+
+`CLAUDE.md` 和 `AGENTS.md` 很适合描述一个仓库。但当你需要同时处理多个仓库时，仓库之间的关系很难表达，共用背景知识容易重复，新的会话又会从过少的上下文开始。
+
+`gc-tree` 就是为了解决这种重复而做的。
 
 ---
 
@@ -61,7 +69,7 @@ gctree init
 2. 在当前仓库安装集成文件
 3. 为 `main` gc-branch 完成引导式 onboarding
 
-之后，AI 工具会安装真正的 SessionStart / UserPromptSubmit hook 集成：在开始工作前自动检查 gc-tree，并在整个会话内缓存空结果和 no-match。Hook 输出保持紧凑：只显示 found/no-match 状态以及匹配文档的标题和 ID，完整文档需要时再通过 `gctree resolve --id <id>` 打开。
+之后，AI 工具会安装真正的 SessionStart / UserPromptSubmit hook 集成：在开始工作前自动检查 gc-tree，并在整个会话内缓存空结果和 no-match。Hook 输出会将匹配文档的摘要直接注入上下文——让 AI 看到的是真实的模式和命令，而不只是标题。完整文档随时可通过 `gctree resolve --id <id>` 按需获取。
 
 - **CLI：** `gctree`
 - **要求：** Node.js 20+
@@ -72,18 +80,18 @@ gctree init
 
 如果以下几条符合你的情况，gc-tree 会很适合你：
 
-- 工作横跨**多个仓库**（单体仓库团队、平台 + 客户仓库、后端 + 前端技术栈）
-- 同一周内要在**多个产品或客户**之间来回切换
+- 工作横跨**多个仓库**（单体仓库团队、平台仓库、后端 + 前端技术栈）
+- 需要在**多个产品、项目或工作线**之间来回切换
 - 每次开 AI 会话都要**重复解释相同的上下文**
-- 希望 AI 工具不只了解当前文件，还能理解**编码规范、架构和领域知识**
+- 希望 AI 工具不只了解当前文件，还能理解**你的工作方式、团队术语、架构和领域知识**
 
-如果你只在一个仓库、一个产品里工作，不需要这个工具。`CLAUDE.md` 或 `.cursorrules` 就够了。
+如果你只在一个仓库、一个产品里工作，不需要这个工具。`CLAUDE.md` 或 `AGENTS.md` 就够了。
 
 ---
 
 ## gc-tree 做什么
 
-`gc-tree` 工作在**仓库之上**。它把上下文存储为结构化的 Markdown 文件，让 AI 工具在每次会话前自动拉取相关内容。
+`gc-tree` 工作在**仓库之上**。它把你的工作方式、团队领域术语、仓库之间的关系和共用背景知识保存为持久的全局上下文，让 AI 工具在每次会话前自动拉取相关内容。
 
 `gctree resolve` 是 progressive-disclosure 工作流中的**紧凑索引层**：
 
@@ -97,18 +105,10 @@ gctree init
 gctree resolve --query "auth token rotation policy"
 ```
 
-```json
-{
-  "gc_branch": "main",
-  "matches": [
-    {
-      "title": "认证与 Session 规范",
-      "score": 4,
-      "summary": "每次请求都做 JWT rotation，refresh token 存在 httpOnly cookie 里，access token TTL 15 分钟",
-      "excerpt": "## 认证流程\nAccess token：15 分钟 TTL，每次认证请求都做 rotation..."
-    }
-  ]
-}
+```
+[gc-tree] 1 matching doc  gc-branch="main"  repo="my-repo"
+[Auth & Session Conventions] JWT rotation on every request, refresh tokens in httpOnly cookies, 15-min access token TTL
+[Auth & Session Conventions] show full doc: gctree show-doc --id "auth" --branch "main"
 ```
 
 AI 工具拿到的是正确的上下文——不是整个知识库，而是恰好相关的那一片。
@@ -117,17 +117,17 @@ AI 工具拿到的是正确的上下文——不是整个知识库，而是恰
 
 ---
 
-## 和 CLAUDE.md 或 cursor rules 有什么区别？
+## 和 CLAUDE.md、AGENTS.md 有什么区别？
 
-`CLAUDE.md` 很好用——在单个仓库里。
+`CLAUDE.md` 和 `AGENTS.md` 很好用——在单个仓库里。
 
-一旦你有了多个仓库、客户或工作线：
+一旦你有了多个仓库、项目或工作线：
 
-|                  | `CLAUDE.md` / cursor rules | `gc-tree`                  |
+|                  | `CLAUDE.md` / `AGENTS.md` | `gc-tree`                  |
 | ---------------- | -------------------------- | -------------------------- |
 | 作用范围         | 单个仓库                   | 多个仓库，一套上下文       |
 | 持久化方式       | 仓库内的文件               | 存储在仓库外，跨会话复用   |
-| 切换上下文       | 手动编辑文件               | `gctree checkout client-b` |
+| 切换上下文       | 手动编辑文件               | `gctree checkout project-b` |
 | 相关性过滤       | 全部或全无                 | 只注入匹配的文档（约 4%）  |
 | 初始化方式       | 手写                       | 由 AI 工具引导完成         |
 | 支持 Codex       | ✅                         | ✅                         |
@@ -137,7 +137,7 @@ AI 工具拿到的是正确的上下文——不是整个知识库，而是恰
 
 ## 经过验证的性能
 
-基于真实内部文档测试（4 份 Notion 导出，中英文混合查询）：
+基于合成多领域 fixture 以及中英文混合查询测试：
 
 | 指标                                  | 结果              |
 | ------------------------------------- | ----------------- |
@@ -165,11 +165,11 @@ gctree scaffold --host both          # 两者同时安装
 **Codex** — 使用 `$gc-resolve-context`、`$gc-onboard`、`$gc-update-global-context` skill。已通过 `codex exec` 实际验证：
 
 ```
-gctree status → gc_branch: main，doc_count: 2
+gctree status → gc_branch: main, doc_count: 2
 gctree resolve --query 'NestJS DTO plainToInstance'
-→ 匹配到"后端编码规范"（score: 3）
-→ DTO：class-transformer plainToInstance，class-validator 必填
-→ 错误处理：基于 HttpException 的自定义异常，禁止直接抛出 raw Error
+[gc-tree] 1 matching doc  gc-branch="main"  repo="my-repo"
+[Backend Coding Conventions] DTO: class-transformer plainToInstance, class-validator required. Error handling: HttpException-based custom exceptions, no raw Error throws.
+[Backend Coding Conventions] show full doc: gctree show-doc --id "backend-conventions" --branch "main"
 ```
 
 ---
@@ -179,7 +179,7 @@ gctree resolve --query 'NestJS DTO plainToInstance'
 ### 为不同工作线创建独立上下文
 
 ```bash
-gctree checkout -b client-b
+gctree checkout -b project-b
 gctree onboard
 ```
 
@@ -201,11 +201,19 @@ 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
-gctree set-repo-scope --branch client-b --include   # 包含当前仓库
-gctree set-repo-scope --branch client-b --exclude   # 排除当前仓库
+gctree set-repo-scope --branch project-b --include   # 包含当前仓库
+gctree set-repo-scope --branch project-b --exclude   # 排除当前仓库
 ```
 
 `gc-tree` 不会向不相关的仓库注入上下文。
@@ -222,7 +230,7 @@ gctree set-repo-scope --branch client-b --exclude   # 排除当前仓库
       docs/
         auth.md         ← 完整文档，按需读取
         architecture.md
-    client-b/
+    project-b/
       index.md
       docs/
         ...
@@ -249,6 +257,7 @@ gctree set-repo-scope --branch client-b --exclude   # 排除当前仓库
 | 为 gc-branch 包含或排除当前仓库      | `gctree set-repo-scope --branch <name> --include` / `--exclude` |
 | 重新 onboarding 前重置 gc-branch     | `gctree reset-gc-branch --branch <name> --yes`                  |
 | 在单个仓库中安装本地 override        | `gctree scaffold --host codex --target /path/to/repo`           |
+| 更新 gctree 并重新安装所有 provider  | `gctree update`                                                 |
 | 移除全局 gc-tree 激活和上下文        | `gctree uninstall --yes`                                        |
 
 ---

package/docs/concept.es.md

@@ -76,8 +76,8 @@ Un directorio de inicio típico tiene este aspecto:
 - `settings.json` almacena el modo de proveedor, el proveedor de onboarding elegido para el lanzamiento en tiempo de ejecución y el idioma de trabajo preferido.
 - `branch-repo-map.json` almacena qué repositorios están incluidos o excluidos para cada gc-branch.
 - `branch.json` almacena metadatos ligeros de la gc-branch.
-- `index.md` es el punto de entrada compacto para las herramientas — se mantiene por debajo de 2000 caracteres para que cargue rápido sin consumir un presupuesto significativo de tokens.
-- `docs/` contiene los documentos markdown que son la fuente de verdad.
+- `index.md` es el punto de entrada compacto para las herramientas — se mantiene compacto agrupando todas las palabras clave bajo cada ruta de documento en lugar de repetir la ruta por cada palabra clave.
+- `docs/` contiene los documentos markdown que son la fuente de verdad. Cada doc debe tener un `## Summary` accionable (patrones y comandos reales, no una descripción) y una sección `## Index Entries` con muchas palabras clave buscables.
 
 ## Comportamiento según el repositorio
 

package/docs/concept.ja.md

@@ -76,8 +76,8 @@
 - `settings.json` はプロバイダーモード、ランタイム起動時に選択したオンボーディングプロバイダー、および優先ワークフロー言語を保存します。
 - `branch-repo-map.json` は各 gc-branch に対してどのリポジトリを含むか・除外するかを保存します。
 - `branch.json` は軽量な gc-branch メタデータを保存します。
-- `index.md` はツール向けのコンパクトなエントリーポイントです。高速に読み込めるよう 2000 文字以内に収められており、トークンバジェットを大きく消費しません。
-- `docs/` は信頼できる情報源となるマークダウンドキュメントを格納します。
+- `index.md` はツール向けのコンパクトなエントリーポイントです。すべてのキーワードを各ドキュメントパスの下にグループ化し、キーワードごとにパスを繰り返す代わりにスリムに保ちます。
+- `docs/` は信頼できる情報源となるマークダウンドキュメントを格納します。各ドキュメントには実行可能な `## Summary`（説明ではなく実際のパターンとコマンド）と、多くの検索可能なキーワードを持つ `## Index Entries` セクションが必要です。
 
 ## リポジトリを意識した動作
 

package/docs/concept.ko.md

@@ -76,8 +76,8 @@
 - `settings.json`은 프로바이더 모드, 런타임 실행 시 선택된 온보딩 프로바이더, 선호 워크플로우 언어를 저장합니다.
 - `branch-repo-map.json`은 각 gc-branch에 대해 어떤 저장소가 포함되거나 제외되는지 저장합니다.
 - `branch.json`은 gc-branch의 경량 메타데이터를 저장합니다.
-- `index.md`는 도구를 위한 간결한 진입점으로, 2000자 이하로 유지되어 상당한 토큰 예산을 소비하지 않고 빠르게 로드됩니다.
-- `docs/`는 정보 소스가 되는 마크다운 문서들을 담습니다.
+- `index.md`는 도구를 위한 간결한 진입점으로, 모든 키워드를 각 문서 경로 아래에 그룹화하여 경로를 키워드마다 반복하는 대신 슬림하게 유지됩니다.
+- `docs/`는 정보 소스가 되는 마크다운 문서들을 담습니다. 각 문서에는 실행 가능한 `## Summary`(설명이 아닌 실제 패턴과 명령)와 검색 가능한 키워드가 많은 `## Index Entries` 섹션이 있어야 합니다.
 
 ## 저장소 인식 동작
 

package/docs/concept.md

@@ -76,8 +76,8 @@ A typical home directory looks like this:
 - `settings.json` stores the provider mode, the onboarding provider chosen for runtime launch, and the preferred workflow language.
 - `branch-repo-map.json` stores which repositories are included or excluded for each gc-branch.
 - `branch.json` stores lightweight gc-branch metadata.
-- `index.md` is the compact entry point for tools — kept under 2000 characters so it loads fast without consuming significant token budget.
-- `docs/` holds the source-of-truth markdown documents.
+- `index.md` is the compact entry point for tools — kept slim by grouping all keywords under each document path rather than repeating the path for every keyword.
+- `docs/` holds the source-of-truth markdown documents. Each doc should have an actionable `## Summary` (actual patterns and commands, not a description) and a `## Index Entries` section with many searchable keywords.
 
 ## Repo-aware behavior
 

package/docs/concept.zh.md

@@ -76,8 +76,8 @@
 - `settings.json` 存储提供商模式、运行时启动时选择的 onboarding 提供商，以及首选的工作流语言。
 - `branch-repo-map.json` 存储每个 gc-branch 包含或排除的代码仓库。
 - `branch.json` 存储轻量级的 gc-branch 元数据。
-- `index.md` 是工具的简洁入口点——保持在 2000 字符以内，以便快速加载而不消耗大量 token 预算。
-- `docs/` 存放作为可信来源的 Markdown 文档。
+- `index.md` 是工具的简洁入口点——通过将所有关键词归在每个文档路径下而非为每个关键词重复路径来保持精简。
+- `docs/` 存放作为可信来源的 Markdown 文档。每个文档都应有可执行的 `## Summary`（真实的模式和命令，而非描述）以及包含大量可搜索关键词的 `## Index Entries` 部分。
 
 ## 仓库感知行为
 

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

@@ -22,16 +22,32 @@ Una gc-branch no debería afectar silenciosamente a todos los repositorios de la
 
 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. Mantener `index.md` compacto
+## 3. Mantener `index.md` compacto y rico en palabras clave
 
 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. Hacer que los documentos fuente empiecen con el resumen
+El formato agrupa las palabras clave bajo cada ruta de documento, eliminando las entradas de ruta repetidas:
+
+```
+- docs/workflows/db.md
+  - DB migration
+  - prisma schema
+  - poetry run rev
+  - model.py
+```
+
+Esto mantiene el índice compacto a la vez que maximiza la superficie de búsqueda. Cada documento debe tener tantas palabras clave relevantes como sea posible — aliases, nombres de comandos, nombres de campos, acrónimos y términos relacionados — para que cualquier consulta razonable encuentre algo útil.
+
+## 4. Hacer que los documentos fuente empiecen con un resumen con contenido accionable
 
 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.
+Esa sección se inyecta en el contexto de la IA antes de cada tarea, por lo que debe contener **patrones, comandos y restricciones reales**, no una descripción de lo que cubre el documento.
+
+Mal resumen: `"This document describes the updateCollection pattern."`
+Buen resumen: `"updateCollection: spread { ...dto } into body. Return plainToInstance(Res, result satisfies Res). New field order: DTO → service → controller."`
+
+Un resumen que parece una entrada de tabla de contenidos es inútil. La IA lo ignorará y irá directo al código.
 
 ## 5. Hacer el onboarding explícito y guiado
 

package/docs/principles.ja.md

@@ -22,16 +22,32 @@ gc-branch がマシン上のすべてのリポジトリに黙って影響して
 
 `resolve` が未マップのリポジトリから呼ばれた場合、今回だけ続けるか、今後もその gc-branch をそこで使うか、そこで無視するかをユーザーが決められます。
 
-## 3. `index.md` は薄く保つ
+## 3. `index.md` は薄く、かつキーワードを豊富に保つ
 
 トップレベルの `index.md` は知識の置き場ではなく、あくまでインデックスです。
 役割は、人やツールが正しいソースドキュメントを素早く見つけられるようにすることです。
-**2000 文字** 以内に収め、全文の知識をその場に複製するのではなく、コンパクトでリンク中心に保つべきです。
 
-## 4. ソースドキュメントは summary-first にする
+形式は各ドキュメントパスの下にキーワードをグループ化し、パスの重複を排除します：
+
+```
+- docs/workflows/db.md
+  - DB migration
+  - prisma schema
+  - poetry run rev
+  - model.py
+```
+
+これによりインデックスをコンパクトに保ちながら、検索範囲を最大化できます。すべてのドキュメントには可能な限り多くの関連キーワードを含めるべきです — エイリアス、コマンド名、フィールド名、略語、関連用語など — どんな合理的なクエリでも有用な結果が得られるよう。
+
+## 4. ソースドキュメントは実行可能な内容を含む summary-first にする
 
 信頼できる情報源となるマークダウンドキュメントには、冒頭近くに `## Summary` セクションがあるべきです。
-そうしておけば、後段のツールはまず短い要約を読み、実際に詳細が必要になったときだけ展開できます。
+そのセクションはすべてのタスク前に AI コンテキストに注入されるため、ドキュメントが扱う内容の説明ではなく、**実際のパターン、コマンド、制約事項**を含んでいなければなりません。
+
+悪い例：`"This document describes the updateCollection pattern."`
+良い例：`"updateCollection: spread { ...dto } into body. Return plainToInstance(Res, result satisfies Res). New field order: DTO → service → controller."`
+
+目次エントリのような要約は役に立ちません。AI はそれをスキップしてコードに直行します。
 
 ## 5. オンボーディングは明示的かつガイド付きにする