@handsupmin/gc-tree 0.8.18 → 1.0.0

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       | ✅                         | ✅                                           |
@@ -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
 ```
 
@@ -204,8 +204,8 @@ Guided update flow — your AI tool asks what changed and writes the new context
 ### 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 +222,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 +249,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       | ✅                         | ✅                         |
@@ -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
 ```
 
@@ -204,8 +204,8 @@ gctree update-global-context   # 或：gctree update-gc / gctree ugc
 ### 限定上下文作用的仓库范围
 
 ```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 +222,7 @@ gctree set-repo-scope --branch client-b --exclude   # 排除当前仓库
       docs/
         auth.md         ← 完整文档，按需读取
         architecture.md
-    client-b/
+    project-b/
       index.md
       docs/
         ...
@@ -249,6 +249,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/dist/src/scaffold.js

@@ -163,10 +163,15 @@ function renderClaudeSessionStartHook() {
     return [
         '# gctree Claude Code SessionStart note',
         '',
-        '- gctree init installs real SessionStart/UserPromptSubmit hooks via `.claude/hooks/hooks.json`.',
-        '- At session start, use the injected hook context to confirm the active gc-branch.',
-        '- Refer to gctree branches as **gc-branches** in user-facing language.',
-        '- If hook context is missing or stale, resolve summaries before planning or implementation when branch-level context may change the answer.',
+        '- Before any codebase task — feature, schema change, bug fix, admin work, or any question about how the codebase works — do **not** grep or read code first. Follow this exact order:',
+        '  1. Run `gctree resolve --query "<task or term>"`. If matched, use the result directly.',
+        '  2. Only if scope is **included**: if step 1 found nothing, try broader related queries.',
+        '  3. If concept exists in a doc but not indexed → propose adding an Index Entry.',
+        '  4. Only if gc-tree has nothing should you search code.',
+        '  — If scope is **unmapped** or **excluded**: do step 1 only; if no match, proceed normally.',
+        '- When a UserPromptSubmit hook provides `[gc-tree] USE FIRST`, treat matched docs as mandatory. Do not grep or Explore until you have read every injected summary.',
+        '- Only use tools if matched docs are clearly insufficient — meaning the answer cannot be derived from them.',
+        '- If hook context is missing, run `gctree resolve --query "<task>"` yourself before planning.',
         '',
     ].join('\n');
 }

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/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. オンボーディングは明示的かつガイド付きにする
 

package/docs/principles.ko.md

@@ -22,16 +22,32 @@ gc-branch가 머신의 모든 저장소에 조용히 영향을 미쳐서는 안
 
 매핑되지 않은 저장소에서 `resolve`가 호출되면, 사용자가 해당 저장소에서 한 번만 계속할지, 항상 해당 gc-branch를 사용할지, 아니면 무시할지 결정할 수 있습니다.
 
-## 3. `index.md`를 슬림하게 유지한다
+## 3. `index.md`를 슬림하고 키워드 풍부하게 유지한다
 
 최상위 `index.md`는 인덱스이지, 덤프가 아닙니다.
 도구와 사람이 올바른 소스 문서를 빠르게 찾을 수 있도록 돕는 것이 역할입니다.
-**2000자** 이하로 유지되어야 하며, 전체 지식을 인라인으로 복제하는 대신 링크 중심으로 구성되어야 합니다.
 
-## 4. 소스 문서를 요약 우선으로 구성한다
+형식은 각 문서 경로 아래에 키워드를 그룹화하여 경로 항목이 반복되는 것을 없앱니다:
+
+```
+- docs/workflows/db.md
+  - DB migration
+  - prisma schema
+  - poetry run rev
+  - model.py
+```
+
+이렇게 하면 인덱스를 간결하게 유지하면서 검색 범위를 최대화합니다. 모든 문서에는 가능한 많은 관련 키워드를 포함해야 합니다 — 별칭, 명령어 이름, 필드 이름, 약어, 관련 용어 등 — 어떤 합리적인 쿼리도 유용한 결과를 찾을 수 있도록.
+
+## 4. 소스 문서를 실행 가능한 내용이 담긴 요약 우선으로 구성한다
 
 모든 정보 소스 마크다운 문서는 상단 근처에 `## Summary` 섹션을 포함해야 합니다.
-이는 다운스트림 도구에게 빠른 경로를 제공합니다: 먼저 짧은 버전을 읽고, 실제로 더 많은 상세 내용이 필요할 때만 확장합니다.
+이 섹션은 매 작업 전에 AI 컨텍스트에 주입되므로, 문서가 다루는 내용에 대한 설명이 아니라 **실제 패턴, 명령, 제약사항**을 포함해야 합니다.
+
+나쁜 요약: `"이 문서는 updateCollection 패턴을 설명합니다."`
+좋은 요약: `"updateCollection: { ...dto } spread 필수. return plainToInstance(Res, result satisfies Res). 새 필드 추가 = DTO → 서비스 → 컨트롤러 순서."`
+
+목차 항목처럼 읽히는 요약은 쓸모없습니다. AI는 이를 건너뛰고 바로 코드로 갑니다.
 
 ## 5. 온보딩을 명시적이고 안내된 방식으로 만든다
 

package/docs/principles.md

@@ -22,16 +22,32 @@ A gc-branch should not quietly affect every repository on the machine.
 
 If `resolve` is called from an unmapped repository, the user can decide whether to continue once, always use that gc-branch there, or ignore it there.
 
-## 3. Keep `index.md` slim
+## 3. Keep `index.md` slim and keyword-rich
 
 The top-level `index.md` is an index, not a dump.
 Its job is to help tools and humans find the right source document quickly.
-It should stay under **2000 characters** and remain link-oriented instead of duplicating full knowledge inline.
 
-## 4. Make source docs summary-first
+The format groups keywords under each document path, eliminating repeated path entries:
+
+```
+- docs/workflows/db.md
+  - DB migration
+  - prisma schema
+  - poetry run rev
+  - model.py
+```
+
+This keeps the index compact while maximizing search surface. Every document should have as many relevant keywords as possible — aliases, command names, field names, acronyms, and related terms — so that any plausible query hits something useful.
+
+## 4. Make source docs summary-first with actionable content
 
 Every source-of-truth markdown document should include a `## Summary` section near the top.
-That gives downstream tools a fast path: read the short version first, then expand only when more detail is actually needed.
+That section is injected into the AI context before every task — so it must contain **actual patterns, commands, and constraints**, not a description of what the document covers.
+
+Bad summary: `"This document describes the updateCollection pattern."`
+Good summary: `"updateCollection: spread { ...dto } into body. Return plainToInstance(Res, result satisfies Res). New field order: DTO → service → controller."`
+
+A summary that reads like a table-of-contents entry is useless. The AI will skip it and go straight to code.
 
 ## 5. Make onboarding explicit and guided
 

package/docs/principles.zh.md

@@ -22,16 +22,32 @@ gc-branch 不应该悄无声息地影响机器上的每一个代码仓库。
 
 如果从未映射的代码仓库调用 `resolve`，用户可以决定是继续一次、始终在该仓库使用此 gc-branch，还是在该仓库忽略它。
 
-## 3. 保持 `index.md` 精简
+## 3. 保持 `index.md` 精简且关键词丰富
 
 顶层 `index.md` 是索引，而非内容转储。
 它的职责是帮助工具和人员快速找到正确的源文档。
-它应保持在 **2000 字符**以内，以链接为主，而不是将完整知识内联复制进来。
 
-## 4. 让源文档以摘要为先
+格式将关键词统一归在每个文档路径下，避免路径条目的重复：
+
+```
+- docs/workflows/db.md
+  - DB migration
+  - prisma schema
+  - poetry run rev
+  - model.py
+```
+
+这样既能保持索引紧凑，又能最大化搜索覆盖面。每个文档都应尽可能包含多个相关关键词——别名、命令名、字段名、缩写及关联术语——确保任何合理的查询都能找到有用的结果。
+
+## 4. 让源文档以包含可执行内容的摘要为先
 
 每个作为可信来源的 Markdown 文档都应在靠近顶部的位置包含一个 `## 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. 让 onboarding 明确且有引导