@handsupmin/gc-tree 0.2.0 → 0.3.0

package/docs/principles.zh.md

@@ -1,50 +1,63 @@
-# 原则
+# 设计原则
 
 [English](principles.md) | [한국어](principles.ko.md) | [简体中文](principles.zh.md) | [日本語](principles.ja.md) | [Español](principles.es.md)
 
-## 摘要
+## 概述
 
-`gctree` 遵循几条很小但很明确的产品规则：上下文要有分支意识，source 文档要坚持 summary-first，index 要保持轻量，repo scope 要显式管理，这样每条 gc-branch 才只会影响它真正该影响的仓库。
+`gctree` 遵循一套简明的产品准则：保持上下文的分支感知、让源文档以摘要为先、保持索引精简、明确仓库作用范围、只注入相关内容，并支持任何能够运行 shell 命令的提供商。
 
-## 1. 让上下文具备分支意识
+## 1. 保持上下文的分支感知
 
-一台机器上应该可以同时容纳多棵全局上下文树，而且彼此不混在一起。
-这也是为什么 `gctree` 使用 `checkout`、`checkout -b` 这类类似 Git 的语言，同时在面向用户的表达里把当前分支称为 **gc-branch**。
+一台机器应该能够同时持有多个全局上下文树，且互不混淆。
+这就是为什么 `gctree` 使用 `checkout` 和 `checkout -b` 这样类似 git 的语言，同时在面向用户的文案中将活跃分支称为 **gc-branch**。
 
-## 2. 让 repo scope 保持显式
+## 2. 明确仓库作用范围
 
-gc-branch 不应该悄悄影响机器上的每一个仓库。
-`gctree` 用 `branch-repo-map.json` 来记录一个仓库对于某条 gc-branch 处于哪种状态：
+gc-branch 不应该悄无声息地影响机器上的每一个代码仓库。
+`gctree` 使用 `branch-repo-map.json` 来记录某个代码仓库的状态：
 
-- 被该 gc-branch 包含
-- 被该 gc-branch 排除
-- 还没有映射
+- 已包含在某个 gc-branch 中
+- 已从某个 gc-branch 中排除
+- 尚未映射
 
-如果从一个尚未映射的仓库里调用 `resolve`，用户可以决定是只继续这一次、以后都在这里使用该 gc-branch，还是在这里忽略它。
+如果从未映射的代码仓库调用 `resolve`，用户可以决定是继续一次、始终在该仓库使用此 gc-branch，还是在该仓库忽略它。
 
-## 3. 让 `index.md` 保持轻量
+## 3. 保持 `index.md` 精简
 
-顶层的 `index.md` 是索引，不是内容倾倒区。
-它的职责是帮助工具和人快速找到正确的 source 文档。
-所以它应该保持紧凑、以链接为主，而不是把完整知识大段复制进去。
+顶层 `index.md` 是索引，而非内容转储。
+它的职责是帮助工具和人员快速找到正确的源文档。
+它应保持在 **2000 字符**以内，以链接为主，而不是将完整知识内联复制进来。
 
-## 4. 让 source 文档遵循 summary-first
+## 4. 让源文档以摘要为先
 
-每一份 source-of-truth markdown 文档，都应该在靠前的位置带上 `## Summary` 段落。
-这样下游工具就有一条快速路径：先读短版本，只有确实需要更多细节时再继续展开。
+每个作为可信来源的 Markdown 文档都应在靠近顶部的位置包含一个 `## Summary` 部分。
+这为下游工具提供了一条快速路径：先读取简短版本，只有在真正需要更多细节时才展开阅读。
 
 ## 5. 让 onboarding 明确且有引导
 
-为了创建一棵有用的上下文树，用户不应该被迫手写 onboarding JSON。
-`gctree init` 和 `gctree onboard` 应该围绕用户偏好的 provider 提供引导，并把结果写入当前激活的 gc-branch。
+用户不应该仅仅为了创建一个有用的上下文树而手动编写 onboarding JSON。
+`gctree init` 和 `gctree onboard` 应该引导用户选择首选的提供商，并将生成的上下文写入活跃的 gc-branch。
 
-onboarding 只适用于空的 gc-branch。
-如果某条 gc-branch 已经包含上下文，正确的路径只有两种：
+Onboarding 仅适用于空的 gc-branch。
+如果一个 gc-branch 已经包含上下文，正确的做法是：
 
-- 重置这条 gc-branch，然后重新 onboarding
-- 或者执行一次带引导的长期更新
+- 重置该 gc-branch 并重新 onboard
+- 或者执行一次有引导的持久化更新
 
-## 6. 让长期更新保持有意图
+## 6. 让持久化更新保持刻意为之
 
-长期上下文不应该因为意外或隐藏式记忆而发生变化。
-更新流程必须是显式的、由 provider 驱动的，并且明确绑定到当前激活的 gc-branch 上。
+持久化上下文不应该因意外或隐藏记忆而发生变更。
+更新流程应该是显式的、由提供商驱动的，并与当前活跃的 gc-branch 绑定。
+
+## 7. 只注入相关内容
+
+工具会话不应收到整个知识库。
+`gctree resolve` 对文档与查询进行评分，只返回匹配的文档——包含标题、摘要和摘录。只有在摘要不足时才读取完整文档。
+
+实际上，每次查询注入的上下文约占总存储量的 4%。其余 96% 保留在磁盘上，不进入 token 窗口，直到真正需要时才读取。
+
+## 8. 保持提供商无关性
+
+`gctree` 将上下文存储在任何工具都能读取的纯 Markdown 文件中。
+Claude Code 和 Codex 都通过 `gctree scaffold` 对接同一个底层存储。
+添加对新提供商的支持，意味着编写一个新的 scaffold 模板——无需对核心存储或 resolve 逻辑做任何修改。

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,48 @@ 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/hooks.json                         ← hooks de auto-resolve para SessionStart/UserPromptSubmit
+.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/hooks.json                         ← hooks de auto-resolve para SessionStart/UserPromptSubmit
+.claude/hooks/gctree-session-start.md            ← nota fallback 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,48 @@ 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/hooks.json                         ← SessionStart / UserPromptSubmit の自動 resolve フック
+.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/hooks.json                         ← SessionStart / UserPromptSubmit の自動 resolve フック
+.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 を実用的に使えます。