@handsupmin/gc-tree 0.2.0 → 0.2.1

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가 실용적으로 동작합니다.

package/docs/usage.md

@@ -36,7 +36,33 @@ A standard `gctree` workflow looks like this: initialize gc-tree, choose a provi
 | `gctree reset-gc-branch --branch <name> --yes` | Clear a gc-branch so it can be onboarded again. |
 | `gctree update-global-context` | Launch a guided durable update for the active gc-branch. |
 | `gctree update-gc` / `gctree ugc` | Aliases for `gctree update-global-context`. |
-| `gctree scaffold --host <codex|claude-code>` | Install the provider-facing command surface in another environment. |
+| `gctree scaffold --host <codex\|claude-code>` | Install the provider-facing command surface in another environment. |
+
+## What resolve returns
+
+`gctree resolve` scores every document in the active gc-branch against your query and returns only the matching ones. Title matches count twice as much as body matches.
+
+```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..."
+    }
+  ]
+}
+```
+
+The tool receives the summary and excerpt first. It reads the full document at `path` only when the summary is not enough. A query that matches nothing returns `"matches": []`.
 
 ## Example repo-scope flow
 
@@ -107,14 +133,36 @@ If a newly relevant repo should also become part of the durable context, the nat
 
 ### Codex CLI / Claude Code CLI
 
-`gctree scaffold` installs provider-facing commands such as guided onboarding and guided updates.
-Those commands should explicitly mention the current active gc-branch before they start gathering or applying durable context, and they should keep using the saved workflow language unless the user explicitly asks to switch.
+`gctree scaffold` installs provider-facing command files into the target directory.
 
 ```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
+```
+
+**Files written for `--host codex`:**
+
+```
+AGENTS.md                                  ← gctree snippet appended to agent instructions
+.codex/prompts/gctree-bootstrap.md         ← bootstrap context for Codex sessions
+.codex/skills/gc-resolve-context/SKILL.md  ← resolve skill
+.codex/skills/gc-onboard/SKILL.md          ← onboarding skill
+.codex/skills/gc-update-global-context/SKILL.md  ← update skill
 ```
 
+**Files written for `--host claude-code`:**
+
+```
+CLAUDE.md                                        ← gctree snippet appended
+.claude/hooks/gctree-session-start.md            ← session-start hook
+.claude/commands/gc-resolve-context.md           ← resolve slash command
+.claude/commands/gc-onboard.md                   ← onboard slash command
+.claude/commands/gc-update-global-context.md     ← update slash command
+```
+
+Existing files are left untouched unless you pass `--force`.
+
 ### Runtime behavior
 
 The active gc-branch is the one pointed to by `HEAD` inside `~/.gctree`, but repo mapping can override that fallback when a repository is explicitly bound to another gc-branch.