@handsupmin/gc-tree 0.8.19 → 1.0.1

package/README.es.md

@@ -16,7 +16,7 @@
 
 <img src="./logo.png" alt="logo de gc-tree" width="260" />
 
-### Contexto global, más allá del proyecto.
+### Contexto global más allá de CLAUDE.md y AGENTS.md.
 
 Añade a tus herramientas de IA una capa de contexto reutilizable y duradera.
 Gestiona varios contextos con la misma naturalidad con la que manejas ramas de Git.
@@ -35,16 +35,24 @@ Gestiona varios contextos con la misma naturalidad con la que manejas ramas de G
 
 ## El problema
 
-Usas Claude Code o Codex a diario. Pero tu trabajo real se extiende por múltiples repositorios, productos y clientes — y tus herramientas de IA solo conocen el archivo actual.
+La IA no te conoce.
+
+No sabe en qué trabajas, cómo trabajas, qué significan los términos de tu equipo ni cuáles son las rutinas que repites sin pensarlo. Si no explicas con precisión lo que quieres, rara vez obtienes el resultado que esperabas.
 
 Así que acabas haciendo esto cada vez:
 
+- Volver a presentarte y explicar cómo trabajas
+- Volver a explicar el lenguaje de dominio de tu equipo
 - Volver a explicar qué repositorios van juntos
 - Pegar el mismo documento de arquitectura en el prompt otra vez
 - Recordarle al agente las convenciones que ya "sabía" la semana pasada
 - Eliminar manualmente el contexto irrelevante para el repositorio actual
 
-Esto no es un problema de IA. Es un **problema de gestión del contexto**.
+No es porque la IA sea tonta. Es porque este tipo de contexto es difícil de mantener vivo dentro de un solo workspace, sobre todo cuando el trabajo real se mueve entre varios repositorios y proyectos.
+
+`CLAUDE.md` y `AGENTS.md` funcionan muy bien para describir un repositorio. Pero cuando el trabajo cruza límites entre repos, las relaciones entre repos son difíciles de expresar, el conocimiento compartido se duplica y cada sesión nueva empieza con demasiado poco contexto.
+
+`gc-tree` existe para eliminar esa repetición.
 
 ---
 
@@ -52,12 +60,12 @@ Esto no es un problema de IA. Es un **problema de gestión del contexto**.
 
 Sacarás más partido a `gc-tree` si:
 
-- Trabajas en **múltiples repositorios** (equipos con monorepo, repos de plataforma + cliente, stacks de backend + frontend)
-- Cambias entre **múltiples productos o clientes** en la misma semana
+- Trabajas en **múltiples repositorios** (equipos con monorepo, repos de plataforma, stacks de backend + frontend)
+- Cambias entre **múltiples productos, proyectos o workstreams**
 - Te encuentras **explicando el mismo contexto** al inicio de cada sesión de IA
-- Quieres que tus herramientas de IA entiendan tus **convenciones, arquitectura y conocimiento de dominio** — no solo el archivo actual
+- Quieres que tus herramientas de IA entiendan tu **forma de trabajar, terminología del equipo, arquitectura y conocimiento de dominio** — no solo el archivo actual
 
-Si solo trabajas en un repositorio y un producto, no necesitas esto. `CLAUDE.md` o `.cursorrules` es suficiente.
+Si solo trabajas en un repositorio y un producto, no necesitas esto. `CLAUDE.md` o `AGENTS.md` es suficiente.
 
 ---
 
@@ -74,7 +82,7 @@ gctree init
 2. Instalar los archivos de integración en el repositorio actual
 3. Completar el onboarding guiado para el gc-branch `main`
 
-Después, tu herramienta de IA instala integración real de hooks SessionStart/UserPromptSubmit: revisa gc-tree automáticamente antes de trabajar y cachea resultados vacíos/no-match durante la sesión. La salida del hook se mantiene compacta: muestra el estado found/no-match junto con títulos e IDs de documentos coincidentes, y deja el documento completo detrás de `gctree resolve --id <id>`.
+Después, tu herramienta de IA instala integración real de hooks SessionStart/UserPromptSubmit: revisa gc-tree automáticamente antes de trabajar y cachea resultados vacíos/no-match durante la sesión. La salida del hook inyecta los resúmenes de los documentos coincidentes directamente en el contexto — de modo que la IA ve patrones y comandos reales, no solo títulos. Los documentos completos siempre están disponibles bajo demanda mediante `gctree resolve --id <id>`.
 
 - **CLI:** `gctree`
 - **Requisito:** Node.js 20+
@@ -83,7 +91,7 @@ Después, tu herramienta de IA instala integración real de hooks SessionStart/U
 
 ## Qué hace gc-tree
 
-`gc-tree` opera **por encima del nivel del repositorio**. Almacena contexto en archivos Markdown estructurados y permite que tus herramientas de IA traigan solo lo relevante antes de cada sesión, de forma automática.
+`gc-tree` opera **por encima del nivel del repositorio**. Guarda tu forma de trabajar, la terminología del equipo, las relaciones entre repositorios y el conocimiento compartido como contexto global duradero. Tus herramientas de IA traen solo lo relevante antes de cada sesión, de forma automática.
 
 `gctree resolve` es la **capa de índice compacto** dentro de un flujo de progressive disclosure:
 
@@ -97,18 +105,10 @@ Además, cuando la branch está vacía, el repositorio está excluido o la consu
 gctree resolve --query "auth token rotation policy"
 ```
 
-```json
-{
-  "gc_branch": "main",
-  "matches": [
-    {
-      "title": "Convenciones de Auth y Sesión",
-      "score": 4,
-      "summary": "Rotation de JWT en cada petición, refresh tokens en cookies httpOnly, TTL de 15 min para access tokens",
-      "excerpt": "## Flujo de Auth\nAccess token: TTL 15 min, rotation en cada petición autenticada..."
-    }
-  ]
-}
+```
+[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"
 ```
 
 Tu herramienta de IA recibe el contexto correcto — no toda la base de conocimiento, solo el fragmento relevante.
@@ -117,17 +117,17 @@ Tu herramienta de IA recibe el contexto correcto — no toda la base de conocimi
 
 ---
 
-## ¿En qué se diferencia de CLAUDE.md o cursor rules?
+## ¿En qué se diferencia de CLAUDE.md o AGENTS.md?
 
-`CLAUDE.md` es genial — para un solo repositorio.
+`CLAUDE.md` y `AGENTS.md` son geniales — para un solo repositorio.
 
-En el momento en que tienes múltiples repos, clientes o workstreams:
+En el momento en que tienes múltiples repos, proyectos o workstreams:
 
-|                            | `CLAUDE.md` / cursor rules | `gc-tree`                                     |
+|                            | `CLAUDE.md` / `AGENTS.md` | `gc-tree`                                     |
 | -------------------------- | -------------------------- | --------------------------------------------- |
 | Alcance                    | Un repositorio             | Múltiples repos, un contexto                  |
 | Persistencia               | Archivo dentro del repo    | Almacenado fuera, reutilizable entre sesiones |
-| Cambio de contexto         | Edición manual de archivos | `gctree checkout client-b`                    |
+| Cambio de contexto         | Edición manual de archivos | `gctree checkout project-b`                   |
 | Filtrado por relevancia    | Todo o nada                | Solo inyecta docs coincidentes (~4%)          |
 | Onboarding                 | Escrito a mano             | Guiado por tu herramienta de IA               |
 | Compatible con Codex       | ✅                         | ✅                                            |
@@ -137,7 +137,7 @@ En el momento en que tienes múltiples repos, clientes o workstreams:
 
 ## Rendimiento validado
 
-Probado con documentación interna real (4 exportaciones de Notion, consultas mixtas en español e inglés):
+Probado con fixtures sintéticos multidominio y consultas mixtas en español e inglés:
 
 | Métrica                                                      | Resultado        |
 | ------------------------------------------------------------ | ---------------- |
@@ -167,9 +167,9 @@ Los dos providers usan el mismo almacén de contexto. Haz el onboarding una vez
 ```
 gctree status → gc_branch: main, doc_count: 2
 gctree resolve --query 'NestJS DTO plainToInstance'
-→ coincidencia con "Convenciones de Backend" (score: 3)
-→ DTO: class-transformer plainToInstance, class-validator obligatorio
-→ Manejo de errores: excepciones personalizadas basadas en HttpException, prohibido lanzar 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'
 ### Contextos separados para workstreams distintos
 
 ```bash
-gctree checkout -b client-b
+gctree checkout -b project-b
 gctree onboard
 ```
 
@@ -201,11 +201,19 @@ 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
-gctree set-repo-scope --branch client-b --include   # incluir el repo actual
-gctree set-repo-scope --branch client-b --exclude   # excluir el repo actual
+gctree set-repo-scope --branch project-b --include   # incluir el repo actual
+gctree set-repo-scope --branch project-b --exclude   # excluir el repo actual
 ```
 
 `gc-tree` no inyectará un contexto en repos donde no corresponde.
@@ -222,7 +230,7 @@ gctree set-repo-scope --branch client-b --exclude   # excluir el repo actual
       docs/
         auth.md         ← doc completo, se lee solo cuando hace falta
         architecture.md
-    client-b/
+    project-b/
       index.md
       docs/
         ...
@@ -249,6 +257,7 @@ El contexto vive fuera de tus repositorios — sin reglas de `.gitignore`, sin c
 | Incluir o excluir el repo actual para un gc-branch | `gctree set-repo-scope --branch <name> --include` / `--exclude` |
 | Resetear un gc-branch antes de re-onboard          | `gctree reset-gc-branch --branch <name> --yes`                  |
 | Instalar un override local en un repo              | `gctree scaffold --host codex --target /path/to/repo`           |
+| Actualizar gctree y reinstalar todos los providers | `gctree update`                                                 |
 | Quitar la activación global y el contexto          | `gctree uninstall --yes`                                        |
 
 ---

package/README.ja.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 @@ Git のブランチ感覚で、複数のコンテキストを分けて持てま
 
 ## 問題
 
-Claude Code や Codex を毎日使っています。でも実際の仕事は複数のリポジトリ、プロダクト、クライアントにまたがっていて——AI ツールは今開いているファイルしか知りません。
+AI はあなたのことを知りません。
+
+あなたが何をしているのか、どんなやり方で働くのか、チームの用語が何を意味するのか、無意識に繰り返しているルーティンが何なのかを知りません。欲しい結果を正確に説明しなければ、期待する水準の出力はなかなか返ってきません。
 
 だから毎回こうなってしまいます：
 
+- 自分が誰で、どう働くのかを説明し直す
+- チームで使うドメイン用語を説明し直す
 - どのリポジトリが一緒に動くか、また最初から説明する
 - 同じアーキテクチャ文書をプロンプトに貼り直す
 - 先週「もう知っていた」規約をもう一度教える
 - 今のリポジトリと無関係なコンテキストを手作業で取り除く
 
-これは AI の問題ではありません。**コンテキスト管理の問題**です。
+これは AI が賢くないからではありません。こうした文脈を一つのワークスペースの中で保ち続けるのが難しいからです。特に実際の仕事は一つのリポジトリで完結せず、複数のリポジトリやプロジェクトを行き来しながら進みます。
+
+`CLAUDE.md` と `AGENTS.md` は、一つのリポジトリを説明するにはよく合います。ただし複数のリポジトリを一緒に扱い始めると、リポジトリ間の関係を書きづらく、共通の背景知識は重複し、セッションが変わるたびに最初から説明し直すことになります。
+
+その繰り返しをなくすために作ったのが `gc-tree` です。
 
 ---
 
@@ -52,12 +60,12 @@ Claude Code や Codex を毎日使っています。でも実際の仕事は複
 
 以下に当てはまるなら、gc-tree が一番よく効きます：
 
-- **複数のリポジトリ**にまたがって仕事をしている（モノレポチーム、プラットフォーム + クライアントリポジトリ、バックエンド + フロントエンドスタック）
-- 同じ週に**複数のプロダクトやクライアント**を行き来している
+- **複数のリポジトリ**にまたがって仕事をしている（モノレポチーム、プラットフォームリポジトリ、バックエンド + フロントエンドスタック）
+- **複数のプロダクト、プロジェクト、ワークストリーム**を行き来している
 - AI セッションを開くたびに**同じコンテキストを繰り返し説明**している
-- AI ツールに今のファイルだけでなく**規約・アーキテクチャ・ドメイン知識**まで理解してほしい
+- AI ツールに今のファイルだけでなく**自分の働き方、チーム用語、アーキテクチャ、ドメイン知識**まで理解してほしい
 
-リポジトリ一つ、プロダクト一つで完結するなら、このツールは必要ありません。`CLAUDE.md` や `.cursorrules` で十分です。
+リポジトリ一つ、プロダクト一つで完結するなら、このツールは必要ありません。`CLAUDE.md` や `AGENTS.md` で十分です。
 
 ---
 
@@ -74,7 +82,7 @@ gctree init
 2. 現在のリポジトリへの統合ファイルのインストール
 3. `main` gc-branch のガイド付きオンボーディング実行
 
-その後は、AI ツールに実際の SessionStart / UserPromptSubmit フック統合が入り、作業前に gc-tree を自動確認し、空結果や no-match をセッション中キャッシュします。フック出力はコンパクトに保たれ、found/no-match 状態、マッチしたドキュメントのタイトルと ID だけを示し、全文は必要なときに `gctree resolve --id <id>` で開きます。
+その後は、AI ツールに実際の SessionStart / UserPromptSubmit フック統合が入り、作業前に gc-tree を自動確認し、空結果や no-match をセッション中キャッシュします。フック出力はマッチしたドキュメントの要約をコンテキストに直接注入します — AI がタイトルだけでなく実際のパターンとコマンドを見られるようにするためです。全文はいつでも `gctree resolve --id <id>` でオンデマンドに取得できます。
 
 - **CLI：** `gctree`
 - **動作条件：** Node.js 20+
@@ -83,7 +91,7 @@ gctree init
 
 ## gc-tree がやること
 
-`gc-tree` は**リポジトリより上のレイヤー**に位置します。コンテキストを構造化された Markdown ファイルに保存し、AI ツールがセッションのたびに関連するものだけを自動で引き出せるようにします。
+`gc-tree` は**リポジトリより上のレイヤー**に位置します。働き方、チームのドメイン用語、リポジトリ間の関係、共通の背景知識を長く使えるグローバルコンテキストとして保存し、AI ツールがセッションのたびに関連するものだけを自動で引き出せるようにします。
 
 `gctree resolve` は、progressive-disclosure ワークフローにおける **compact index layer** です。
 
@@ -97,18 +105,10 @@ gctree init
 gctree resolve --query "auth token rotation policy"
 ```
 
-```json
-{
-  "gc_branch": "main",
-  "matches": [
-    {
-      "title": "認証 & セッション規約",
-      "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 ツールに渡るのは正しいコンテキスト——ナレッジベー
 
 ## 検証済みのパフォーマンス
 
-実際の社内ドキュメントでテスト（Notion エクスポート 4 件、日本語・英語混合クエリ）：
+合成マルチドメイン fixture と日本語・英語混合クエリでテスト：
 
 | 指標                                         | 結果              |
 | -------------------------------------------- | ----------------- |
@@ -165,11 +165,11 @@ gctree scaffold --host both          # 両方同時に
 **Codex** — `$gc-resolve-context`、`$gc-onboard`、`$gc-update-global-context` スキルを使用。`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 の throw 禁止
+[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 バージョンに更新し、以前インストールしたすべてのプロバイダーを再スキャフォールドします。より良いフック、コマンド、スキル、統合スニペットが配布されたときに、既存の設定を一度で更新できます。
+
 ### コンテキストを特定のリポジトリに限定する
 
 ```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` |
 | 再オンボーディング前に gc-branch をリセットする  | `gctree reset-gc-branch --branch <name> --yes`                  |
 | 1つのリポジトリにローカル override を入れる      | `gctree scaffold --host codex --target /path/to/repo`           |
+| gctree を更新してすべてのプロバイダーを再スキャフォールドする | `gctree update`                                    |
 | グローバルな gc-tree 有効化とコンテキストを外す  | `gctree uninstall --yes`                                        |
 
 ---

package/README.ko.md

@@ -16,7 +16,7 @@
 
 <img src="./logo.png" alt="gc-tree 로고" width="260" />
 
-### 프로젝트 밖까지 이어지는 글로벌 컨텍스트.
+### CLAUDE.md와 AGENTS.md만으로 부족해서 만든 글로벌 컨텍스트.
 
 기존 AI 도구 위에 오래 가는, 재사용 가능한 컨텍스트 레이어를 얹어보세요.
 Git 브랜치 다루듯 여러 컨텍스트를 나눠 관리할 수 있습니다.
@@ -35,16 +35,24 @@ Git 브랜치 다루듯 여러 컨텍스트를 나눠 관리할 수 있습니다
 
 ## 문제
 
-Claude Code나 Codex를 매일 씁니다. 그런데 실제 업무는 여러 레포, 제품, 고객사에 걸쳐 있고 — AI 도구는 현재 파일밖에 모릅니다.
+AI는 당신을 모릅니다.
+
+당신이 무슨 일을 하는지, 어떤 방식으로 일하는지, 팀에서 쓰는 용어가 무엇을 뜻하는지, 무의식적으로 반복하던 루틴이 무엇인지 모릅니다. 원하는 바를 정확히 설명하지 않으면 원하는 수준의 결과물이 나오기 어렵습니다.
 
 그래서 매번 이렇게 됩니다:
 
+- 나는 어떤 사람이고 어떤 방식으로 일하는지 다시 설명
+- 우리 팀이 어떤 용어를 쓰는지 다시 설명
 - 어떤 레포들이 한 묶음인지 다시 설명
 - 같은 아키텍처 문서를 또 프롬프트에 붙여넣기
 - 지난주에 "이미 알던" 컨벤션을 다시 알려주기
 - 현재 레포와 무관한 컨텍스트를 손으로 걷어내기
 
-이건 AI 문제가 아닙니다. **컨텍스트 관리 문제**입니다.
+AI가 멍청해서가 아닙니다. 하나의 워크스페이스 안에서 이런 맥락을 계속 유지하기 어렵기 때문입니다. 특히 실제 업무는 한 레포 안에서 끝나지 않고 여러 레포와 프로젝트를 오가며 이어집니다.
+
+`CLAUDE.md`와 `AGENTS.md`는 레포 하나를 설명하는 데는 잘 맞습니다. 하지만 여러 레포를 함께 다루는 순간, 레포 간 관계를 담기 어렵고 공통 배경지식은 여기저기 중복되며 세션이 바뀌면 다시 처음부터 설명해야 합니다.
+
+이 반복을 없애기 위해 만든 도구가 `gc-tree`입니다.
 
 ---
 
@@ -52,12 +60,12 @@ Claude Code나 Codex를 매일 씁니다. 그런데 실제 업무는 여러 레
 
 다음에 해당하면 gc-tree를 제일 잘 쓸 수 있습니다:
 
-- **여러 레포**에 걸쳐 일하는 경우 (모노레포 팀, 플랫폼 + 클라이언트 레포, 백엔드 + 프론트엔드 스택)
-- 같은 주에 **여러 제품이나 고객사** 사이를 오가는 경우
+- **여러 레포**에 걸쳐 일하는 경우 (모노레포 팀, 플랫폼 레포, 백엔드 + 프론트엔드 스택)
+- **여러 제품, 프로젝트, 워크스트림** 사이를 오가는 경우
 - AI 세션 시작마다 **같은 컨텍스트를 반복 설명**하는 경우
-- AI 도구가 현재 파일뿐 아니라 **컨벤션, 아키텍처, 도메인 지식**도 알길 원하는 경우
+- AI 도구가 현재 파일뿐 아니라 **내 작업 방식, 팀 용어, 아키텍처, 도메인 지식**도 알길 원하는 경우
 
-레포 하나, 제품 하나에서만 일한다면 굳이 이 도구가 필요 없습니다. `CLAUDE.md`나 `.cursorrules`로 충분합니다.
+레포 하나, 제품 하나에서만 일한다면 굳이 이 도구가 필요 없습니다. `CLAUDE.md`나 `AGENTS.md`로 충분합니다.
 
 ---
 
@@ -74,7 +82,7 @@ gctree init
 2. 현재 레포에 통합 파일 스캐폴딩
 3. `main` gc-branch 가이드형 온보딩 실행
 
-이후 AI 도구에 실제 SessionStart/UserPromptSubmit 훅 통합이 설치되어, 작업 전에 gc-tree를 자동 확인하고 세션 동안 빈 결과·no-match를 캐시합니다. 훅 출력은 짧게 유지됩니다: 찾음/no-match 상태와 매칭된 문서 제목/ID만 보여주고 전체 문서는 `gctree resolve --id <id>`로 필요할 때 엽니다.
+이후 AI 도구에 실제 SessionStart/UserPromptSubmit 훅 통합이 설치되어, 작업 전에 gc-tree를 자동 확인하고 세션 동안 빈 결과·no-match를 캐시합니다. 훅 출력은 매칭된 문서 요약을 컨텍스트에 직접 주입합니다 — AI가 제목만이 아니라 실제 패턴과 명령을 볼 수 있도록. 전체 문서는 언제든 `gctree resolve --id <id>`로 필요할 때 확인할 수 있습니다.
 
 - **CLI:** `gctree`
 - **요구 사항:** Node.js 20+
@@ -83,7 +91,7 @@ gctree init
 
 ## gc-tree가 하는 일
 
-`gc-tree`는 **레포 위 레벨**에 위치합니다. 컨텍스트를 구조화된 마크다운 파일에 저장하고, AI 도구가 매 세션마다 관련된 것만 자동으로 가져오게 합니다.
+`gc-tree`는 **레포 위 레벨**에 위치합니다. 내 업무 스타일, 팀의 도메인 용어, 레포 간 관계, 공통 배경지식을 오래 가는 글로벌 컨텍스트로 저장하고, AI 도구가 매 세션마다 관련된 것만 자동으로 가져오게 합니다.
 
 `gctree resolve`는 progressive-disclosure 워크플로우의 **compact index layer**입니다:
 
@@ -97,18 +105,10 @@ gctree init
 gctree resolve --query "auth token rotation policy"
 ```
 
-```json
-{
-  "gc_branch": "main",
-  "matches": [
-    {
-      "title": "인증 & 세션 컨벤션",
-      "score": 4,
-      "summary": "모든 요청에서 JWT rotation, refresh token은 httpOnly 쿠키에 저장, 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 도구가 올바른 컨텍스트를 가져옵니다. 지식 베이스 전체
 
 ## 검증된 성능
 
-실제 내부 문서 기준 테스트 (Notion 내보내기 4종, 한국어 + 영어 혼합 쿼리):
+합성 멀티 도메인 fixture와 한국어 + 영어 혼합 쿼리 기준 테스트:
 
 | 지표                                            | 결과             |
 | ----------------------------------------------- | ---------------- |
@@ -167,9 +167,9 @@ gctree scaffold --host both          # 둘 다 한번에
 ```
 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 throw 금지
+[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 버전으로 업데이트한 뒤, 이전에 설치한 모든 프로바이더를 다시 스캐폴드합니다. 더 나은 훅, 명령, 스킬, 통합 스니펫이 배포됐을 때 기존 설정을 한 번에 새로고침하는 흐름입니다.
+
 ### 특정 레포에 컨텍스트 범위 지정
 
 ```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   # 현재 레포 제외
 ```
 
 관계없는 레포에는 컨텍스트가 주입되지 않습니다.
@@ -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   # 현재 레포 제외
 | 현재 레포 포함/제외 설정          | `gctree set-repo-scope --branch <name> --include` / `--exclude` |
 | 재온보딩 전 gc-branch 초기화      | `gctree reset-gc-branch --branch <name> --yes`                  |
 | 특정 레포에 로컬 override 설치   | `gctree scaffold --host codex --target /path/to/repo`           |
+| gctree 업데이트 및 모든 프로바이더 재스캐폴드 | `gctree update`                                        |
 | 전역 gc-tree 활성화와 컨텍스트 제거 | `gctree uninstall --yes`                                     |
 
 ---