@handsupmin/gc-tree 0.1.4 → 0.2.1

package/docs/usage.es.md

@@ -4,45 +4,71 @@
 
 ## Resumen
 
-Un flujo estándar con `gctree` suele ser así: inicializar gc-tree, elegir un provider, hacer onboarding del gc-branch `main`, resolver el contexto activo cuando haga falta, crear nuevos gc-branches cuando el trabajo lo pida, mapear cada repo al gc-branch correcto y usar actualizaciones guiadas para los cambios duraderos.
+Un flujo de trabajo estándar con `gctree` tiene este aspecto: inicializar gc-tree, elegir un proveedor, hacer onboarding de la gc-branch `main` predeterminada, hacer resolve del contexto que necesitas, crear nuevas gc-branches cuando el trabajo merece su propio carril, mapear los repositorios a las gc-branches correctas y usar actualizaciones guiadas para cambios duraderos más adelante.
 
-## Flujo estándar
+## Flujo de trabajo estándar
 
-1. ejecuta `gctree init`
-2. elige tu modo de provider preferido (`claude-code`, `codex` o `both`)
-3. elige el idioma del flujo (`English`, `Korean` o un idioma personalizado)
-4. si elegiste `both`, decide qué provider debe iniciar este onboarding
-5. completa el onboarding guiado del gc-branch `main`
-6. usa `gctree resolve --query "..."` para recuperar el contexto relevante
-7. crea o cambia gc-branches con `gctree checkout`
-8. usa `gctree onboard` solo en un gc-branch vacío
-9. configura el repo scope para que cada gc-branch solo se aplique donde corresponde
-10. usa `gctree update-global-context` para los cambios duraderos posteriores
+1. ejecutar `gctree init`
+2. elegir el modo de proveedor preferido (`claude-code`, `codex` o `both`)
+3. elegir el idioma de trabajo (`English`, `Korean` o un idioma personalizado)
+4. si elegiste `both`, elegir qué proveedor debe iniciar el onboarding ahora
+5. completar el onboarding guiado para la gc-branch `main` predeterminada
+6. hacer resolve del contexto relevante con `gctree resolve --query "..."`
+7. crear o cambiar de gc-branch con `gctree checkout`
+8. ejecutar `gctree onboard` solo para una gc-branch vacía
+9. usar el mapeo de alcance del repositorio para que una gc-branch solo aplique donde corresponde
+10. usar `gctree update-global-context` para cambios duraderos más adelante
 
-## Comandos clave
+## Comandos principales
 
 | Comando | Propósito |
 | --- | --- |
-| `gctree init` | Crea `~/.gctree`, crea el gc-branch `main`, guarda el modo de provider, el provider de onboarding y el idioma preferido, hace scaffold del entorno actual y arranca el onboarding guiado cuando `main` está vacío. |
-| `gctree checkout <branch>` | Cambia el gc-branch activo. |
-| `gctree checkout -b <branch>` | Crea un gc-branch vacío nuevo y cambia a él. |
-| `gctree branches` | Lista los gc-branches disponibles y marca cuál está activo. |
-| `gctree status` | Muestra el gc-branch activo, el repo actual, el estado actual de repo scope, advertencias y el provider preferido. |
-| `gctree resolve --query TEXT` | Busca contexto en el gc-branch relevante. Si el repo actual no está mapeado, `gctree` puede preguntar cómo debe tratarse ese repo. |
-| `gctree repo-map` | Muestra el contenido actual de `branch-repo-map.json`. |
-| `gctree set-repo-scope --branch <name> --include` | Marca el repo actual como incluido para ese gc-branch. |
-| `gctree set-repo-scope --branch <name> --exclude` | Marca el repo actual como ignorado para ese gc-branch. |
-| `gctree onboard` | Lanza el onboarding guiado para el gc-branch activo. Solo funciona si ese gc-branch está vacío. |
-| `gctree reset-gc-branch --branch <name> --yes` | Vacía un gc-branch para poder onboardearlo de nuevo. |
-| `gctree update-global-context` | Lanza una actualización duradera guiada para el gc-branch activo. |
-| `gctree update-gc` / `gctree ugc` | Alias de `gctree update-global-context`. |
-| `gctree scaffold --host <codex|claude-code>` | Instala la superficie de comandos del provider en otro entorno. |
-
-## Ejemplo de repo scope
-
-Supón que el gc-branch `A` es relevante para los repos `B`, `C` y `D`, pero no para `F`.
-
-Puedes gestionarlo así:
+| `gctree init` | Crear `~/.gctree`, crear la gc-branch `main` predeterminada, guardar el modo de proveedor, el proveedor de onboarding y el idioma preferido, hacer scaffold del entorno actual y comenzar el onboarding guiado cuando `main` está vacía. |
+| `gctree checkout <branch>` | Cambiar la gc-branch activa. |
+| `gctree checkout -b <branch>` | Crear y cambiar a una nueva gc-branch vacía. |
+| `gctree branches` | Listar las gc-branches disponibles y mostrar la activa. |
+| `gctree status` | Mostrar la gc-branch activa, el repositorio actual, el estado del alcance del repositorio actual, advertencias y el proveedor preferido. |
+| `gctree resolve --query TEXT` | Buscar contexto en la gc-branch relevante. Si el repositorio actual no está mapeado, `gctree` puede preguntar cómo debe tratarse ese repositorio. |
+| `gctree repo-map` | Mostrar el contenido actual de `branch-repo-map.json`. |
+| `gctree set-repo-scope --branch <name> --include` | Marcar el repositorio actual como incluido para esa gc-branch. |
+| `gctree set-repo-scope --branch <name> --exclude` | Marcar el repositorio actual como ignorado para esa gc-branch. |
+| `gctree onboard` | Iniciar el onboarding guiado para la gc-branch activa. Solo funciona cuando esa gc-branch está vacía. |
+| `gctree reset-gc-branch --branch <name> --yes` | Limpiar una gc-branch para poder hacer onboarding de nuevo. |
+| `gctree update-global-context` | Iniciar una actualización duradera guiada para la gc-branch activa. |
+| `gctree update-gc` / `gctree ugc` | Alias para `gctree update-global-context`. |
+| `gctree scaffold --host <codex\|claude-code>` | Instalar la interfaz de comandos orientada al proveedor en otro entorno. |
+
+## Qué devuelve resolve
+
+`gctree resolve` puntúa cada documento de la gc-branch activa contra tu consulta y devuelve solo los que coinciden. Las coincidencias en el título cuentan el doble que las coincidencias en el cuerpo.
+
+```bash
+gctree resolve --query "auth token rotation policy"
+```
+
+```json
+{
+  "gc_branch": "main",
+  "query": "auth token rotation policy",
+  "matches": [
+    {
+      "title": "Auth & Session Conventions",
+      "path": "docs/auth.md",
+      "score": 4,
+      "summary": "JWT rotation on every request, refresh tokens in httpOnly cookies, 15-min access token TTL",
+      "excerpt": "## Auth Flow\nAccess token: 15-min TTL, rotated on every authenticated request..."
+    }
+  ]
+}
+```
+
+La herramienta recibe primero el resumen y el fragmento. Lee el documento completo en `path` solo cuando el resumen no es suficiente. Una consulta que no coincide con nada devuelve `"matches": []`.
+
+## Ejemplo de flujo de alcance del repositorio
+
+Supongamos que la gc-branch `A` es relevante para los repositorios `B`, `C` y `D`, pero no para `F`.
+
+Puedes gestionarlo mediante:
 
 ```json
 {
@@ -53,19 +79,19 @@ Puedes gestionarlo así:
 }
 ```
 
-Guardado en:
+almacenado en:
 
 ```text
 ~/.gctree/branch-repo-map.json
 ```
 
-Cuando ejecutas `resolve` desde el repo `E` y la rama `A` todavía no está mapeada allí, `gctree` puede preguntarte si quieres:
+Cuando `resolve` se ejecuta desde el repositorio `E` y la branch `A` todavía no está mapeada allí, `gctree` puede preguntar si:
 
-1. continuar solo esta vez
+1. continuar una vez
 2. usar siempre `A` en `E`
 3. ignorar `A` en `E`
 
-## Ejemplo de primera ejecución
+## Ejemplo de flujo en la primera ejecución
 
 ```bash
 gctree init
@@ -73,11 +99,11 @@ gctree init
 
 Luego:
 
-1. elige `codex` o `claude-code`
-2. deja que `gctree` haga scaffold del entorno actual
-3. completa el onboarding guiado del gc-branch `main`
+1. elegir `codex` o `claude-code`
+2. dejar que `gctree` haga scaffold del entorno actual
+3. completar el onboarding guiado para la gc-branch `main`
 
-## Ejemplo con varias ramas
+## Ejemplo de flujo con múltiples branches
 
 ```bash
 gctree checkout -b client-b
@@ -85,7 +111,7 @@ gctree onboard
 gctree resolve --query "billing retry policy"
 ```
 
-## Ejemplo de actualización
+## Ejemplo de flujo de actualización
 
 ```bash
 gctree update-global-context
@@ -98,24 +124,46 @@ gctree update-gc
 gctree ugc
 ```
 
-Si un repo recién relevante también debería formar parte del contexto duradero, el flujo natural es:
+Si un repositorio recién relevante también debería pasar a formar parte del contexto duradero, el flujo natural es:
 
-1. primero mapear ese repo al gc-branch
-2. después ejecutar `update-global-context` para añadir conocimiento duradero sobre qué hace ese repo y por qué importa
+1. mapear ese repositorio a la gc-branch
+2. luego ejecutar `update-global-context` para agregar conocimiento duradero sobre qué hace ese repositorio y por qué es importante
 
 ## Patrones de integración
 
 ### Codex CLI / Claude Code CLI
 
-`gctree scaffold` instala la superficie de comandos orientada al provider, como el onboarding guiado y las actualizaciones guiadas.
-Esos comandos deberían mencionar de forma explícita cuál es el gc-branch activo antes de empezar a recopilar o aplicar contexto duradero, y también deberían seguir usando el idioma guardado salvo que la persona usuaria pida cambiarlo.
+`gctree scaffold` instala archivos de comandos orientados al proveedor en el directorio de destino.
 
 ```bash
 gctree scaffold --host codex --target /path/to/repo
 gctree scaffold --host claude-code --target /path/to/repo
+gctree scaffold --host both --target /path/to/repo
+```
+
+**Archivos escritos para `--host codex`:**
+
+```
+AGENTS.md                                  ← fragmento de gctree añadido a las instrucciones del agente
+.codex/prompts/gctree-bootstrap.md         ← contexto de arranque para las sesiones de Codex
+.codex/skills/gc-resolve-context/SKILL.md  ← skill de resolve
+.codex/skills/gc-onboard/SKILL.md          ← skill de onboarding
+.codex/skills/gc-update-global-context/SKILL.md  ← skill de actualización
 ```
 
-### Comportamiento en runtime
+**Archivos escritos para `--host claude-code`:**
+
+```
+CLAUDE.md                                        ← fragmento de gctree añadido
+.claude/hooks/gctree-session-start.md            ← hook de inicio de sesión
+.claude/commands/gc-resolve-context.md           ← comando slash de resolve
+.claude/commands/gc-onboard.md                   ← comando slash de onboard
+.claude/commands/gc-update-global-context.md     ← comando slash de actualización
+```
+
+Los archivos existentes no se modifican a menos que pases `--force`.
+
+### Comportamiento en tiempo de ejecución
 
-Por defecto, el gc-branch activo es el que apunta `HEAD` dentro de `~/.gctree`, pero el repo mapping puede sobrescribir ese valor si un repositorio está ligado explícitamente a otro gc-branch.
-Eso hace que gc-tree sea práctico incluso para quienes mantienen muchas sesiones abiertas a la vez en repositorios que no tienen relación entre sí.
+La gc-branch activa es la apuntada por `HEAD` dentro de `~/.gctree`, pero el mapeo del repositorio puede anular ese valor predeterminado cuando un repositorio está vinculado explícitamente a otra gc-branch.
+Esto hace que gc-tree sea práctico para usuarios avanzados que mantienen muchas sesiones no relacionadas abiertas al mismo tiempo.

package/docs/usage.ja.md

@@ -2,47 +2,73 @@
 
 [English](usage.md) | [한국어](usage.ko.md) | [简体中文](usage.zh.md) | [日本語](usage.ja.md) | [Español](usage.es.md)
 
-## 要約
+## 概要
 
-標準的な `gctree` の流れはこうです。gc-tree を初期化し、provider を選び、デフォルトの `main` gc-branch をオンボードし、必要な文脈を resolve で引き、必要になったら新しい gc-branch を作り、各リポジトリを正しい gc-branch に結び付け、長期的な変更はガイド付き更新で反映していきます。
+標準的な `gctree` の流れはこうです。gc-tree を初期化し、プロバイダーを選び、デフォルトの `main` gc-branch をオンボードし、必要なコンテキストを resolve で引き、作業に応じて新しい gc-branch を作り、リポジトリを適切な gc-branch に結び付け、後からの永続的な変更はガイド付き更新で反映していきます。
 
 ## 標準ワークフロー
 
 1. `gctree init` を実行する
-2. 好みの provider モードを選ぶ（`claude-code`、`codex`、`both`）
+2. 好みのプロバイダーモードを選ぶ（`claude-code`、`codex`、`both`）
 3. ワークフロー言語を選ぶ（`English`、`Korean`、またはカスタム言語）
-4. `both` を選んだ場合は、今回のオンボーディングをどちらの provider で始めるか選ぶ
+4. `both` を選んだ場合は、今回のオンボーディングをどちらのプロバイダーで始めるか選ぶ
 5. デフォルトの `main` gc-branch に対するガイド付きオンボーディングを完了する
 6. `gctree resolve --query "..."` で必要なコンテキストを取り出す
-7. `gctree checkout` で gc-branch を作る / 切り替える
+7. `gctree checkout` で gc-branch を作成または切り替える
 8. `gctree onboard` は空の gc-branch に対してだけ使う
-9. repo scope を設定して gc-branch が本来のリポジトリにだけ効くようにする
-10. 後からの長期変更には `gctree update-global-context` を使う
+9. repo scope を設定して gc-branch が本来のリポジトリにだけ作用するようにする
+10. 後からの永続的な変更には `gctree update-global-context` を使う
 
 ## 主要コマンド
 
 | コマンド | 役割 |
 | --- | --- |
-| `gctree init` | `~/.gctree` を作成し、デフォルトの `main` gc-branch を作り、provider モード / オンボーディング provider / 優先言語を保存し、現在の環境を scaffold し、`main` が空ならガイド付きオンボーディングまで開始します。 |
+| `gctree init` | `~/.gctree` を作成し、デフォルトの `main` gc-branch を作り、プロバイダーモード・オンボーディングプロバイダー・優先言語を保存し、現在の環境を scaffold し、`main` が空ならガイド付きオンボーディングまで開始します。 |
 | `gctree checkout <branch>` | アクティブな gc-branch を切り替えます。 |
 | `gctree checkout -b <branch>` | 新しい空の gc-branch を作成し、そのまま切り替えます。 |
 | `gctree branches` | 利用可能な gc-branch 一覧と、現在アクティブなものを表示します。 |
-| `gctree status` | アクティブな gc-branch、現在のリポジトリ、現在の repo-scope 状態、警告、優先 provider を表示します。 |
+| `gctree status` | アクティブな gc-branch、現在のリポジトリ、現在の repo-scope 状態、警告、優先プロバイダーを表示します。 |
 | `gctree resolve --query TEXT` | 関係する gc-branch からコンテキストを検索します。現在のリポジトリが未マップなら、そのリポジトリをどう扱うかを尋ねる場合があります。 |
 | `gctree repo-map` | 現在の `branch-repo-map.json` の内容を表示します。 |
 | `gctree set-repo-scope --branch <name> --include` | 現在のリポジトリを、その gc-branch に含まれるものとして記録します。 |
 | `gctree set-repo-scope --branch <name> --exclude` | 現在のリポジトリを、その gc-branch では無視するものとして記録します。 |
 | `gctree onboard` | アクティブな gc-branch に対するガイド付きオンボーディングを開始します。空の gc-branch でのみ動作します。 |
-| `gctree reset-gc-branch --branch <name> --yes` | gc-branch を空にして再オンボード可能にします。 |
-| `gctree update-global-context` | アクティブな gc-branch に対するガイド付き長期更新を開始します。 |
+| `gctree reset-gc-branch --branch <name> --yes` | gc-branch を空にして再オンボード可能な状態にします。 |
+| `gctree update-global-context` | アクティブな gc-branch に対するガイド付き永続的更新を開始します。 |
 | `gctree update-gc` / `gctree ugc` | `gctree update-global-context` の別名です。 |
-| `gctree scaffold --host <codex|claude-code>` | 別の環境に provider 向けコマンド面をインストールします。 |
+| `gctree scaffold --host <codex\|claude-code>` | 別の環境にプロバイダー向けコマンド面をインストールします。 |
 
-## repo scope の例
+## resolve が返す内容
 
-gc-branch `A` が repo `B`、`C`、`D` には関係し、`F` には関係しないとします。
+`gctree resolve` はアクティブな gc-branch 内のすべてのドキュメントをクエリに対してスコアリングし、マッチしたものだけを返します。タイトルの一致はボディの一致の 2 倍の重みを持ちます。
 
-その場合は、たとえば次のように管理できます。
+```bash
+gctree resolve --query "auth token rotation policy"
+```
+
+```json
+{
+  "gc_branch": "main",
+  "query": "auth token rotation policy",
+  "matches": [
+    {
+      "title": "Auth & Session Conventions",
+      "path": "docs/auth.md",
+      "score": 4,
+      "summary": "JWT rotation on every request, refresh tokens in httpOnly cookies, 15-min access token TTL",
+      "excerpt": "## Auth Flow\nAccess token: 15-min TTL, rotated on every authenticated request..."
+    }
+  ]
+}
+```
+
+ツールはまずサマリーと抜粋を受け取ります。サマリーだけでは不足する場合にのみ、`path` にあるフルドキュメントを読み込みます。何もマッチしないクエリの場合は `"matches": []` が返ります。
+
+## repo scope の設定例
+
+gc-branch `A` がリポジトリ `B`・`C`・`D` には関係し、`F` には関係しないとします。
+
+その場合は次のように管理できます。
 
 ```json
 {
@@ -59,7 +85,7 @@ gc-branch `A` が repo `B`、`C`、`D` には関係し、`F` には関係しな
 ~/.gctree/branch-repo-map.json
 ```
 
-repo `E` から `resolve` を実行し、branch `A` がまだそこにマップされていない場合、`gctree` は次のどれにするかを尋ねられます。
+リポジトリ `E` から `resolve` を実行し、ブランチ `A` がまだそこにマップされていない場合、`gctree` は次のどれにするかを尋ねられます。
 
 1. 今回だけ続ける
 2. `E` では今後も常に `A` を使う
@@ -98,24 +124,46 @@ gctree update-gc
 gctree ugc
 ```
 
-新しく重要になったリポジトリを長期コンテキストにも組み込みたい場合、自然な流れは次のとおりです。
+新しく重要になったリポジトリを永続的なコンテキストにも組み込みたい場合、自然な流れは次のとおりです。
 
 1. まずそのリポジトリを gc-branch にマップする
-2. その後 `update-global-context` を実行して、そのリポジトリが何を担い、なぜ重要なのかという長期知識を追加する
+2. その後 `update-global-context` を実行して、そのリポジトリが何を担い、なぜ重要なのかという永続的な知識を追加する
 
 ## 統合パターン
 
 ### Codex CLI / Claude Code CLI
 
-`gctree scaffold` は、ガイド付きオンボーディングやガイド付き更新などの provider 向けコマンド面をインストールします。
-これらのコマンドは、長期コンテキストを集めたり適用したりする前に、現在アクティブな gc-branch を明示的に伝えるべきです。また、ユーザーが明示的に切り替えを求めない限り、保存されたワークフロー言語を使い続けるべきです。
+`gctree scaffold` はプロバイダー向けのコマンドファイルをターゲットディレクトリにインストールします。
 
 ```bash
 gctree scaffold --host codex --target /path/to/repo
 gctree scaffold --host claude-code --target /path/to/repo
+gctree scaffold --host both --target /path/to/repo
+```
+
+**`--host codex` で書き込まれるファイル:**
+
+```
+AGENTS.md                                  ← gctree のスニペットがエージェント指示に追記される
+.codex/prompts/gctree-bootstrap.md         ← Codex セッション向けのブートストラップコンテキスト
+.codex/skills/gc-resolve-context/SKILL.md  ← resolve スキル
+.codex/skills/gc-onboard/SKILL.md          ← オンボーディングスキル
+.codex/skills/gc-update-global-context/SKILL.md  ← 更新スキル
 ```
 
-### ランタイムの振る舞い
+**`--host claude-code` で書き込まれるファイル:**
+
+```
+CLAUDE.md                                        ← gctree のスニペットが追記される
+.claude/hooks/gctree-session-start.md            ← セッション開始フック
+.claude/commands/gc-resolve-context.md           ← resolve スラッシュコマンド
+.claude/commands/gc-onboard.md                   ← onboard スラッシュコマンド
+.claude/commands/gc-update-global-context.md     ← 更新スラッシュコマンド
+```
+
+`--force` を渡さない限り、既存のファイルは変更されません。
+
+### ランタイムの動作
 
-デフォルトのアクティブ gc-branch は `~/.gctree` の `HEAD` が指しているものですが、特定のリポジトリが別の gc-branch に明示的に結び付けられている場合は、repo mapping がその既定値を上書きできます。
-このおかげで、互いに無関係なセッションをたくさん同時に開いているヘビーユーザーでも gc-tree を実用的に使えます。
+デフォルトのアクティブ gc-branch は `~/.gctree` 内の `HEAD` が指しているものですが、リポジトリが別の gc-branch に明示的に結び付けられている場合は、repo mapping がそのフォールバックを上書きできます。
+これにより、互いに無関係なセッションを多数同時に開いているヘビーユーザーでも gc-tree を実用的に使えます。

package/docs/usage.ko.md

@@ -1,48 +1,74 @@
-# 사용 방법
+# 사용법
 
 [English](usage.md) | [한국어](usage.ko.md) | [简体中文](usage.zh.md) | [日本語](usage.ja.md) | [Español](usage.es.md)
 
 ## 요약
 
-표준적인 `gctree` 흐름은 이렇습니다. gc-tree를 초기화하고, provider를 고르고, 기본 `main` gc-branch를 온보딩하고, 필요한 컨텍스트를 resolve로 불러오고, 필요할 때 새 gc-branch를 만들고, 각 레포를 맞는 gc-branch에 매핑하고, 나중에는 가이드형 업데이트로 장기 컨텍스트를 유지합니다.
+표준 `gctree` 워크플로우는 다음과 같습니다: gc-tree 초기화, 프로바이더 선택, 기본 `main` gc-branch 온보딩, 필요한 컨텍스트 resolve, 작업별로 새 gc-branch 생성, 저장소를 올바른 gc-branch에 매핑, 이후 지속 변경 시 안내된 업데이트 사용.
 
-## 기본 워크플로
+## 표준 워크플로우
 
 1. `gctree init` 실행
-2. 선호하는 provider 모드 선택 (`claude-code`, `codex`, `both`)
-3. 워크플로 언어 선택 (`English`, `Korean`, 또는 커스텀 언어)
-4. `both`를 골랐다면 이번 온보딩을 어느 provider로 시작할지 선택
-5. 기본 `main` gc-branch에 대한 가이드형 온보딩 완료
-6. `gctree resolve --query "..."`로 필요한 컨텍스트 조회
+2. 선호하는 프로바이더 모드 선택 (`claude-code`, `codex`, 또는 `both`)
+3. 워크플로우 언어 선택 (`English`, `Korean`, 또는 커스텀 언어)
+4. `both`를 선택한 경우, 지금 온보딩을 시작할 프로바이더 선택
+5. 기본 `main` gc-branch의 안내된 온보딩 완료
+6. `gctree resolve --query "..."`로 관련 컨텍스트 resolve
 7. `gctree checkout`으로 gc-branch 생성 또는 전환
-8. `gctree onboard`는 비어 있는 gc-branch에서만 실행
-9. repo scope 매핑으로 gc-branch가 자기 레포에서만 적용되게 유지
-10. 장기 변경은 나중에 `gctree update-global-context`로 반영
+8. 빈 gc-branch에만 `gctree onboard` 실행
+9. 저장소 범위 매핑으로 gc-branch가 해당하는 곳에만 적용되도록 설정
+10. 이후 지속 변경에는 `gctree update-global-context` 사용
 
-## 핵심 명령
+## 핵심 명령어
 
-| 명령 | 용도 |
+| 명령어 | 설명 |
 | --- | --- |
-| `gctree init` | `~/.gctree`를 만들고, 기본 `main` gc-branch를 만들고, provider 모드/온보딩 provider/선호 언어를 저장하고, 현재 환경을 스캐폴딩하고, `main`이 비어 있으면 가이드형 온보딩까지 시작합니다. |
-| `gctree checkout <branch>` | 활성 gc-branch를 전환합니다. |
-| `gctree checkout -b <branch>` | 새로운 빈 gc-branch를 만들고 바로 전환합니다. |
-| `gctree branches` | 사용 가능한 gc-branch 목록과 현재 활성 브랜치를 보여줍니다. |
-| `gctree status` | 활성 gc-branch, 현재 레포, 현재 repo-scope 상태, 경고, 선호 provider를 보여줍니다. |
-| `gctree resolve --query TEXT` | 관련 gc-branch에서 컨텍스트를 찾습니다. 현재 레포가 아직 매핑되지 않았다면, 이 레포를 어떻게 다룰지 물어볼 수 있습니다. |
-| `gctree repo-map` | 현재 `branch-repo-map.json` 내용을 보여줍니다. |
-| `gctree set-repo-scope --branch <name> --include` | 현재 레포를 해당 gc-branch에 포함된 것으로 표시합니다. |
-| `gctree set-repo-scope --branch <name> --exclude` | 현재 레포를 해당 gc-branch에서 무시할 레포로 표시합니다. |
-| `gctree onboard` | 활성 gc-branch에 대한 가이드형 온보딩을 시작합니다. 이 gc-branch가 비어 있을 때만 동작합니다. |
-| `gctree reset-gc-branch --branch <name> --yes` | gc-branch를 비워서 다시 온보딩할 수 있게 만듭니다. |
-| `gctree update-global-context` | 활성 gc-branch에 대한 가이드형 장기 업데이트를 시작합니다. |
-| `gctree update-gc` / `gctree ugc` | `gctree update-global-context`의 별칭입니다. |
-| `gctree scaffold --host <codex|claude-code>` | 다른 환경에도 provider용 명령 표면을 설치합니다. |
-
-## repo scope 예시 흐름
-
-gc-branch `A`가 `B`, `C`, `D` 레포에는 관련 있고 `F`에는 관련이 없다고 가정해봅시다.
-
-이 경우 다음 같은 구조로 관리할 수 있습니다.
+| `gctree init` | `~/.gctree` 생성, 기본 `main` gc-branch 생성, 프로바이더 모드·온보딩 프로바이더·선호 언어 저장, 현재 환경 scaffold, `main`이 비어 있으면 안내된 온보딩 시작. |
+| `gctree checkout <branch>` | 활성 gc-branch 전환. |
+| `gctree checkout -b <branch>` | 새 빈 gc-branch를 생성하고 전환. |
+| `gctree branches` | 사용 가능한 gc-branch 목록 표시 및 현재 활성 브랜치 표시. |
+| `gctree status` | 활성 gc-branch, 현재 저장소, 현재 저장소 범위 상태, 경고, 선호 프로바이더 표시. |
+| `gctree resolve --query TEXT` | 관련 gc-branch에서 컨텍스트 검색. 현재 저장소가 매핑되지 않은 경우, `gctree`가 해당 저장소 처리 방법을 물어볼 수 있습니다. |
+| `gctree repo-map` | `branch-repo-map.json`의 현재 내용 표시. |
+| `gctree set-repo-scope --branch <name> --include` | 현재 저장소를 해당 gc-branch에 포함으로 표시. |
+| `gctree set-repo-scope --branch <name> --exclude` | 현재 저장소를 해당 gc-branch에서 무시로 표시. |
+| `gctree onboard` | 활성 gc-branch의 안내된 온보딩 실행. 해당 gc-branch가 비어 있을 때만 동작. |
+| `gctree reset-gc-branch --branch <name> --yes` | gc-branch를 초기화하여 다시 온보딩할 수 있게 함. |
+| `gctree update-global-context` | 활성 gc-branch의 안내된 지속 업데이트 실행. |
+| `gctree update-gc` / `gctree ugc` | `gctree update-global-context`의 별칭. |
+| `gctree scaffold --host <codex\|claude-code>` | 다른 환경에 프로바이더 대면 명령 표면 설치. |
+
+## resolve가 반환하는 것
+
+`gctree resolve`는 활성 gc-branch의 모든 문서를 쿼리에 대해 점수를 매기고 매칭된 것만 반환합니다. 제목 매칭은 본문 매칭보다 두 배의 가중치를 가집니다.
+
+```bash
+gctree resolve --query "auth token rotation policy"
+```
+
+```json
+{
+  "gc_branch": "main",
+  "query": "auth token rotation policy",
+  "matches": [
+    {
+      "title": "Auth & Session Conventions",
+      "path": "docs/auth.md",
+      "score": 4,
+      "summary": "JWT rotation on every request, refresh tokens in httpOnly cookies, 15-min access token TTL",
+      "excerpt": "## Auth Flow\nAccess token: 15-min TTL, rotated on every authenticated request..."
+    }
+  ]
+}
+```
+
+도구는 먼저 요약과 발췌문을 받습니다. 요약만으로 충분하지 않을 때만 `path`의 전체 문서를 읽습니다. 아무것도 매칭되지 않는 쿼리는 `"matches": []`를 반환합니다.
+
+## 저장소 범위 설정 예시 흐름
+
+gc-branch `A`가 저장소 `B`, `C`, `D`에는 관련되지만 `F`에는 관련 없다고 가정합니다.
+
+다음과 같이 관리할 수 있습니다:
 
 ```json
 {
@@ -53,31 +79,31 @@ gc-branch `A`가 `B`, `C`, `D` 레포에는 관련 있고 `F`에는 관련이
 }
 ```
 
-이 정보는 다음 위치에 저장됩니다.
+저장 위치:
 
 ```text
 ~/.gctree/branch-repo-map.json
 ```
 
-`E` 레포에서 `resolve`를 실행했는데 branch `A`가 아직 거기에 매핑되지 않았다면, `gctree`는 다음 중 무엇을 할지 물어볼 수 있습니다.
+저장소 `E`에서 `resolve`를 실행할 때 브랜치 `A`가 아직 매핑되지 않은 경우, `gctree`가 다음 중 하나를 선택하도록 물어볼 수 있습니다:
 
-1. 이번만 계속하기
-2. `E`에서는 앞으로도 항상 `A` 사용하기
-3. `E`에서는 `A` 무시하기
+1. 한 번만 계속 진행
+2. `E`에서 항상 `A` 사용
+3. `E`에서 `A` 무시
 
-## 첫 실행 예시
+## 최초 실행 예시 흐름
 
 ```bash
 gctree init
 ```
 
-그다음:
+이후:
 
 1. `codex` 또는 `claude-code` 선택
-2. `gctree`가 현재 환경을 스캐폴딩하도록 두기
-3. `main` gc-branch에 대한 가이드형 온보딩 완료
+2. `gctree`가 현재 환경을 scaffold하도록 허용
+3. `main` gc-branch의 안내된 온보딩 완료
 
-## 여러 브랜치를 쓰는 예시
+## 다중 브랜치 예시 흐름
 
 ```bash
 gctree checkout -b client-b
@@ -85,37 +111,59 @@ gctree onboard
 gctree resolve --query "billing retry policy"
 ```
 
-## 업데이트 예시
+## 업데이트 예시 흐름
 
 ```bash
 gctree update-global-context
 ```
 
-짧은 별칭:
+단축 별칭:
 
 ```bash
 gctree update-gc
 gctree ugc
 ```
 
-새롭게 중요해진 레포를 장기 컨텍스트에도 포함시키고 싶다면, 자연스러운 흐름은 이렇습니다.
+새로 관련이 생긴 저장소를 지속 컨텍스트에도 포함해야 한다면, 자연스러운 흐름은 다음과 같습니다:
 
-1. 먼저 그 레포를 gc-branch에 매핑하고
-2. 그다음 `update-global-context`를 실행해서 그 레포가 무엇을 하는지, 왜 중요한지 같은 장기 지식을 추가하기
+1. 해당 저장소를 gc-branch에 매핑
+2. `update-global-context`를 실행하여 해당 저장소가 무엇을 하고 왜 중요한지에 대한 지속 지식 추가
 
 ## 통합 패턴
 
 ### Codex CLI / Claude Code CLI
 
-`gctree scaffold`는 가이드형 온보딩, 가이드형 업데이트 같은 provider 명령 표면을 설치합니다.
-이 명령들은 장기 컨텍스트를 수집하거나 반영하기 전에 현재 활성 gc-branch가 무엇인지 명시적으로 말해야 하고, 사용자가 따로 바꾸라고 하지 않는 한 저장된 워크플로 언어를 계속 사용해야 합니다.
+`gctree scaffold`는 대상 디렉토리에 프로바이더 대면 명령 파일을 설치합니다.
 
 ```bash
 gctree scaffold --host codex --target /path/to/repo
 gctree scaffold --host claude-code --target /path/to/repo
+gctree scaffold --host both --target /path/to/repo
+```
+
+**`--host codex`로 작성되는 파일:**
+
+```
+AGENTS.md                                  ← 에이전트 지시사항에 gctree 스니펫 추가
+.codex/prompts/gctree-bootstrap.md         ← Codex 세션의 부트스트랩 컨텍스트
+.codex/skills/gc-resolve-context/SKILL.md  ← resolve 스킬
+.codex/skills/gc-onboard/SKILL.md          ← 온보딩 스킬
+.codex/skills/gc-update-global-context/SKILL.md  ← 업데이트 스킬
 ```
 
+**`--host claude-code`로 작성되는 파일:**
+
+```
+CLAUDE.md                                        ← gctree 스니펫 추가
+.claude/hooks/gctree-session-start.md            ← 세션 시작 훅
+.claude/commands/gc-resolve-context.md           ← resolve 슬래시 명령
+.claude/commands/gc-onboard.md                   ← onboard 슬래시 명령
+.claude/commands/gc-update-global-context.md     ← 업데이트 슬래시 명령
+```
+
+`--force`를 전달하지 않으면 기존 파일은 그대로 유지됩니다.
+
 ### 런타임 동작
 
-기본적으로 활성 gc-branch는 `~/.gctree` 안의 `HEAD`가 가리키는 브랜치입니다. 다만 특정 레포가 다른 gc-branch에 명시적으로 묶여 있다면 repo mapping이 그 기본값을 덮어쓸 수 있습니다.
-덕분에 서로 무관한 세션을 많이 동시에 띄워두는 사용자에게도 gc-tree가 실용적으로 동작합니다.
+활성 gc-branch는 `~/.gctree` 내의 `HEAD`가 가리키는 브랜치이지만, 저장소가 다른 gc-branch에 명시적으로 바인딩된 경우 저장소 매핑이 해당 폴백을 재정의할 수 있습니다.
+이를 통해 관련 없는 여러 세션을 동시에 열어두는 헤비 유저에게도 gc-tree가 실용적으로 동작합니다.