@handsupmin/gc-tree 0.1.2 → 0.1.4

package/docs/usage.ja.md

@@ -2,45 +2,47 @@
 
 [English](usage.md) | [한국어](usage.ko.md) | [简体中文](usage.zh.md) | [日本語](usage.ja.md) | [Español](usage.es.md)
 
-## Summary
+## 要約
 
-標準的な `gctree` の使い方は、gc-tree を初期化し、provider を選び、デフォルトの `main` gc-branch をオンボードし、必要に応じて新しい gc-branch を作り、リポジトリを正しい gc-branch に結び付け、その後の長期変更はガイド付き更新で処理する流れです。
+標準的な `gctree` の流れはこうです。gc-tree を初期化し、provider を選び、デフォルトの `main` gc-branch をオンボードし、必要な文脈を resolve で引き、必要になったら新しい gc-branch を作り、各リポジトリを正しい gc-branch に結び付け、長期的な変更はガイド付き更新で反映していきます。
 
-## 標準フロー
+## 標準ワークフロー
 
 1. `gctree init` を実行する
-2. 好みの provider モード（`claude-code`、`codex`、`both`）を選ぶ
-3. ワークフローで使う言語（`English`、`Korean`、または自由入力）を選ぶ
-4. `both` を選んだ場合は、今回のオンボーディングをどちらで始めるかを選ぶ
-5. デフォルトの `main` gc-branch のガイド付きオンボーディングを完了する
-6. `gctree resolve --query "..."` で関連コンテキストを解決する
-7. `gctree checkout` で gc-branch を作成または切り替える
-8. 空の gc-branch に対してのみ `gctree onboard` を実行する
-9. リポジトリ範囲のマッピングで、gc-branch が本当に関係するリポジトリにだけ適用されるようにする
-10. 以後の長期変更は `gctree update-global-context` を使う
+2. 好みの provider モードを選ぶ（`claude-code`、`codex`、`both`）
+3. ワークフロー言語を選ぶ（`English`、`Korean`、またはカスタム言語）
+4. `both` を選んだ場合は、今回のオンボーディングをどちらの provider で始めるか選ぶ
+5. デフォルトの `main` gc-branch に対するガイド付きオンボーディングを完了する
+6. `gctree resolve --query "..."` で必要なコンテキストを取り出す
+7. `gctree checkout` で gc-branch を作る / 切り替える
+8. `gctree onboard` は空の gc-branch に対してだけ使う
+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 を作り、provider モード / オンボーディング provider / 優先言語を保存し、現在の環境を scaffold し、`main` が空ならガイド付きオンボーディングまで開始します。 |
 | `gctree checkout <branch>` | アクティブな gc-branch を切り替えます。 |
-| `gctree checkout -b <branch>` | 新しい空の gc-branch を作成して切り替えます。 |
-| `gctree branches` | 利用可能な gc-branches と現在の gc-branch を表示します。 |
-| `gctree status` | アクティブな gc-branch、現在のリポジトリ、そのリポジトリの scope 状態、警告、保存された provider を表示します。 |
-| `gctree resolve --query TEXT` | 関連する gc-branch からコンテキストを検索します。現在のリポジトリが未マッピングなら、対話的に扱い方を決められます。 |
-| `gctree repo-map` | `branch-repo-map.json` の現在内容を表示します。 |
-| `gctree set-repo-scope --branch <name> --include` | 現在のリポジトリをその gc-branch の include に追加します。 |
-| `gctree set-repo-scope --branch <name> --exclude` | 現在のリポジトリをその gc-branch の exclude に追加します。 |
-| `gctree onboard` | アクティブな gc-branch に対してガイド付きオンボーディングを開始します。空の gc-branch でのみ利用できます。 |
-| `gctree reset-gc-branch --branch <name> --yes` | gc-branch を空に戻し、再オンボーディングできるようにします。 |
-| `gctree update-global-context` | アクティブな 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 向けコマンド面をインストールします。 |
+| `gctree scaffold --host <codex|claude-code>` | 別の環境に provider 向けコマンド面をインストールします。 |
 
-## リポジトリ範囲の例
+## repo scope の例
 
-たとえば gc-branch `A` が `B`、`C`、`D` にだけ関係し、`F` には関係しないなら、次のように管理できます。
+gc-branch `A` が repo `B`、`C`、`D` には関係し、`F` には関係しないとします。
+
+その場合は、たとえば次のように管理できます。
 
 ```json
 {
@@ -51,16 +53,16 @@
 }
 ```
 
-保存先:
+保存先は次のとおりです。
 
 ```text
 ~/.gctree/branch-repo-map.json
 ```
 
-この状態で `E` リポジトリから `resolve` を実行すると、次を選べます。
+repo `E` から `resolve` を実行し、branch `A` がまだそこにマップされていない場合、`gctree` は次のどれにするかを尋ねられます。
 
-1. 今回だけ続行する
-2. 今後も `E` で `A` を使う
+1. 今回だけ続ける
+2. `E` では今後も常に `A` を使う
 3. `E` では `A` を無視する
 
 ## 初回実行の例
@@ -69,13 +71,13 @@
 gctree init
 ```
 
-その後:
+そのあと:
 
-1. `codex` または `claude-code` を選ぶ
+1. `codex` か `claude-code` を選ぶ
 2. `gctree` に現在の環境を scaffold させる
-3. `main` gc-branch のオンボーディングを完了する
+3. `main` gc-branch のガイド付きオンボーディングを完了する
 
-## 複数 gc-branch の例
+## 複数ブランチを使う例
 
 ```bash
 gctree checkout -b client-b
@@ -96,24 +98,24 @@ gctree update-gc
 gctree ugc
 ```
 
-実際に作業してみて、そのリポジトリが現在の gc-branch に属するべきだと分かった場合は、自然な流れはこうです。
+新しく重要になったリポジトリを長期コンテキストにも組み込みたい場合、自然な流れは次のとおりです。
 
-1. まずそのリポジトリを branch repo map に追加する
-2. その後 `update-global-context` を実行して、そのリポジトリが何を担うのか、なぜ重要なのかといった長期コンテキストを追加する
+1. まずそのリポジトリを gc-branch にマップする
+2. その後 `update-global-context` を実行して、そのリポジトリが何を担い、なぜ重要なのかという長期知識を追加する
 
 ## 統合パターン
 
 ### Codex CLI / Claude Code CLI
 
-`gctree scaffold` は、ガイド付きオンボーディングやガイド付き更新などの provider 向けコマンドをインストールします。
-それらのコマンドは、開始前に必ず現在アクティブな gc-branch を明示するべきであり、ユーザーが明示的に変更を求めない限り、保存されたワークフロー言語を最後まで維持するべきです。
+`gctree scaffold` は、ガイド付きオンボーディングやガイド付き更新などの provider 向けコマンド面をインストールします。
+これらのコマンドは、長期コンテキストを集めたり適用したりする前に、現在アクティブな gc-branch を明示的に伝えるべきです。また、ユーザーが明示的に切り替えを求めない限り、保存されたワークフロー言語を使い続けるべきです。
 
 ```bash
 gctree scaffold --host codex --target /path/to/repo
 gctree scaffold --host claude-code --target /path/to/repo
 ```
 
-### ランタイム上の扱い
+### ランタイムの振る舞い
 
-現在の gc-branch は `~/.gctree` 内の `HEAD` が指す fallback ブランチです。
-ただし、あるリポジトリが別の gc-branch に明示的に結び付けられている場合、そのリポジトリでは branch map が HEAD より優先されます。
+デフォルトのアクティブ gc-branch は `~/.gctree` の `HEAD` が指しているものですが、特定のリポジトリが別の gc-branch に明示的に結び付けられている場合は、repo mapping がその既定値を上書きできます。
+このおかげで、互いに無関係なセッションをたくさん同時に開いているヘビーユーザーでも gc-tree を実用的に使えます。

package/docs/usage.ko.md

@@ -1,46 +1,48 @@
-# 사용방법
+# 사용 방법
 
 [English](usage.md) | [한국어](usage.ko.md) | [简体中文](usage.zh.md) | [日本語](usage.ja.md) | [Español](usage.es.md)
 
-## Summary
+## 요약
 
-기본적인 `gctree` 사용 흐름은 이렇습니다. gc-tree를 초기화하고, provider를 선택하고, 기본 `main` gc-branch를 온보딩한 뒤, 필요할 때 새 gc-branch를 만들고, 레포를 올바른 gc-branch에 매핑하고, 이후 장기 변경은 가이드형 업데이트로 처리합니다.
+표준적인 `gctree` 흐름은 이렇습니다. gc-tree를 초기화하고, provider를 고르고, 기본 `main` gc-branch를 온보딩하고, 필요한 컨텍스트를 resolve로 불러오고, 필요할 때 새 gc-branch를 만들고, 각 레포를 맞는 gc-branch에 매핑하고, 나중에는 가이드형 업데이트로 장기 컨텍스트를 유지합니다.
 
-## 기본 흐름
+## 기본 워크플로
 
 1. `gctree init` 실행
-2. 선호 provider 모드(`claude-code`, `codex`, `both`) 선택
-3. 사용할 언어(`English`, `Korean`, 또는 직접 입력한 언어) 선택
+2. 선호하는 provider 모드 선택 (`claude-code`, `codex`, `both`)
+3. 워크플로 언어 선택 (`English`, `Korean`, 또는 커스텀 언어)
 4. `both`를 골랐다면 이번 온보딩을 어느 provider로 시작할지 선택
 5. 기본 `main` gc-branch에 대한 가이드형 온보딩 완료
-6. `gctree resolve --query "..."`로 관련 컨텍스트 조회
+6. `gctree resolve --query "..."`로 필요한 컨텍스트 조회
 7. `gctree checkout`으로 gc-branch 생성 또는 전환
-8. 비어 있는 gc-branch에서만 `gctree onboard` 실행
-9. gc-branch가 실제 관련 레포에만 적용되도록 레포 범위 매핑 관리
-10. 이후 장기 변경은 `gctree update-global-context`로 반영
+8. `gctree onboard`는 비어 있는 gc-branch에서만 실행
+9. repo scope 매핑으로 gc-branch가 자기 레포에서만 적용되게 유지
+10. 장기 변경은 나중에 `gctree update-global-context`로 반영
 
 ## 핵심 명령
 
-| 명령 | 설명 |
+| 명령 | 용도 |
 | --- | --- |
-| `gctree init` | `~/.gctree`와 기본 `main` gc-branch를 만들고, provider 모드, 실제 온보딩 provider, 선호 언어를 저장하고, 현재 환경을 스캐폴딩한 뒤, `main`이 비어 있으면 가이드형 온보딩을 시작합니다. |
+| `gctree init` | `~/.gctree`를 만들고, 기본 `main` gc-branch를 만들고, provider 모드/온보딩 provider/선호 언어를 저장하고, 현재 환경을 스캐폴딩하고, `main`이 비어 있으면 가이드형 온보딩까지 시작합니다. |
 | `gctree checkout <branch>` | 활성 gc-branch를 전환합니다. |
-| `gctree checkout -b <branch>` | 새 빈 gc-branch를 만들고 전환합니다. |
-| `gctree branches` | 사용 가능한 gc-branch와 현재 gc-branch를 보여줍니다. |
-| `gctree status` | 활성 gc-branch, 현재 레포, 현재 레포의 scope 상태, 경고, 선호 provider를 보여줍니다. |
-| `gctree resolve --query TEXT` | 관련 gc-branch에서 컨텍스트를 검색합니다. 현재 레포가 미매핑이면 처리 방식을 물어볼 수 있습니다. |
-| `gctree repo-map` | `branch-repo-map.json` 현재 내용을 보여줍니다. |
-| `gctree set-repo-scope --branch <name> --include` | 현재 레포를 해당 gc-branch의 include로 등록합니다. |
-| `gctree set-repo-scope --branch <name> --exclude` | 현재 레포를 해당 gc-branch의 exclude로 등록합니다. |
-| `gctree onboard` | 활성 gc-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용 명령 표면을 설치합니다. |
+| `gctree scaffold --host <codex|claude-code>` | 다른 환경에도 provider용 명령 표면을 설치합니다. |
 
-## 레포 범위 예시
+## repo scope 예시 흐름
 
-예를 들어 gc-branch `A`가 `B`, `C`, `D` 레포에만 관련 있고 `F`와는 무관하다면, 다음과 같이 관리할 수 있습니다.
+gc-branch `A`가 `B`, `C`, `D` 레포에는 관련 있고 `F`에는 관련이 없다고 가정해봅시다.
+
+이 경우 다음 같은 구조로 관리할 수 있습니다.
 
 ```json
 {
@@ -51,19 +53,19 @@
 }
 ```
 
-저장 위치:
+이 정보는 다음 위치에 저장됩니다.
 
 ```text
 ~/.gctree/branch-repo-map.json
 ```
 
-그 상태에서 `E` 레포에서 `resolve`를 호출하면 다음 중 하나를 고를 수 있습니다.
+`E` 레포에서 `resolve`를 실행했는데 branch `A`가 아직 거기에 매핑되지 않았다면, `gctree`는 다음 중 무엇을 할지 물어볼 수 있습니다.
 
-1. 이번만 진행
-2. 앞으로 이 레포에서도 `A` 사용
-3. 이 레포에서는 `A` 무시
+1. 이번만 계속하기
+2. `E`에서는 앞으로도 항상 `A` 사용하기
+3. `E`에서는 `A` 무시하기
 
-## 최초 실행 예시
+## 첫 실행 예시
 
 ```bash
 gctree init
@@ -72,10 +74,10 @@ gctree init
 그다음:
 
 1. `codex` 또는 `claude-code` 선택
-2. `gctree`가 현재 환경을 스캐폴딩하도록 둠
-3. `main` gc-branch 온보딩 완료
+2. `gctree`가 현재 환경을 스캐폴딩하도록 두기
+3. `main` gc-branch에 대한 가이드형 온보딩 완료
 
-## 다중 gc-branch 예시
+## 여러 브랜치를 쓰는 예시
 
 ```bash
 gctree checkout -b client-b
@@ -96,17 +98,17 @@ gctree update-gc
 gctree ugc
 ```
 
-만약 실제 작업을 하다 보니 어떤 레포가 현재 gc-branch에 포함되어야 할 것 같다면, 자연스러운 흐름은 이렇습니다.
+새롭게 중요해진 레포를 장기 컨텍스트에도 포함시키고 싶다면, 자연스러운 흐름은 이렇습니다.
 
-1. 먼저 branch repo map에 그 레포를 포함시키고
-2. 그 다음 `update-global-context`로 이 레포가 무엇을 하는지, 왜 중요한지 같은 장기 컨텍스트를 추가
+1. 먼저 그 레포를 gc-branch에 매핑하고
+2. 그다음 `update-global-context`를 실행해서 그 레포가 무엇을 하는지, 왜 중요한지 같은 장기 지식을 추가하기
 
 ## 통합 패턴
 
 ### Codex CLI / Claude Code CLI
 
-`gctree scaffold`는 가이드형 온보딩과 가이드형 업데이트 같은 provider용 명령을 설치합니다.
-이 명령들은 항상 현재 활성 gc-branch가 무엇인지 먼저 명시해야 하며, 사용자가 명시적으로 바꾸라고 하지 않는 한 저장된 워크플로 언어를 끝까지 유지해야 합니다.
+`gctree scaffold`는 가이드형 온보딩, 가이드형 업데이트 같은 provider 명령 표면을 설치합니다.
+이 명령들은 장기 컨텍스트를 수집하거나 반영하기 전에 현재 활성 gc-branch가 무엇인지 명시적으로 말해야 하고, 사용자가 따로 바꾸라고 하지 않는 한 저장된 워크플로 언어를 계속 사용해야 합니다.
 
 ```bash
 gctree scaffold --host codex --target /path/to/repo
@@ -115,5 +117,5 @@ gctree scaffold --host claude-code --target /path/to/repo
 
 ### 런타임 동작
 
-활성 gc-branch는 `~/.gctree` 안의 `HEAD`가 가리키는 fallback 브랜치입니다.
-다만 어떤 레포가 다른 gc-branch에 명시적으로 묶여 있으면, 그 레포에 대해서는 branch map이 HEAD보다 우선합니다.
+기본적으로 활성 gc-branch는 `~/.gctree` 안의 `HEAD`가 가리키는 브랜치입니다. 다만 특정 레포가 다른 gc-branch에 명시적으로 묶여 있다면 repo mapping이 그 기본값을 덮어쓸 수 있습니다.
+덕분에 서로 무관한 세션을 많이 동시에 띄워두는 사용자에게도 gc-tree가 실용적으로 동작합니다.

package/docs/usage.md

@@ -4,7 +4,7 @@
 
 ## Summary
 
-A standard `gctree` workflow is: initialize gc-tree, choose a provider, onboard the default `main` gc-branch, resolve active context, create new gc-branches when needed, map repositories to the right gc-branches, and use guided updates for durable changes.
+A standard `gctree` workflow looks like this: initialize gc-tree, choose a provider, onboard the default `main` gc-branch, resolve the context you need, create new gc-branches when work deserves its own lane, map repositories to the right gc-branches, and use guided updates for durable changes later.
 
 ## Standard workflow
 
@@ -118,4 +118,4 @@ gctree scaffold --host claude-code --target /path/to/repo
 ### 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.
-This makes gc-tree practical for heavy users who keep many unrelated sessions open at the same time.
+That makes gc-tree practical for heavy users who keep many unrelated sessions open at the same time.

package/docs/usage.zh.md

@@ -2,45 +2,47 @@
 
 [English](usage.md) | [한국어](usage.ko.md) | [简体中文](usage.zh.md) | [日本語](usage.ja.md) | [Español](usage.es.md)
 
-## Summary
+## 摘要
 
-标准的 `gctree` 使用流程是：初始化 gc-tree、选择 provider、完成默认 `main` gc-branch 的 onboarding、在需要时创建新的 gc-branch、把仓库映射到正确的 gc-branch，并把后续长期变更交给引导式更新流程。
+标准的 `gctree` 工作流大致是这样的：先初始化 gc-tree，选择 provider，为默认的 `main` gc-branch 完成 onboarding，用 resolve 拉取当前需要的上下文，在需要的时候创建新的 gc-branch，把仓库映射到正确的 gc-branch，后续再通过带引导的更新来维护长期上下文。
 
-## 标准流程
+## 标准工作流
 
 1. 运行 `gctree init`
-2. 选择偏好的 provider 模式（`claude-code`、`codex` 或 `both`）
-3. 选择工作流语言（`English`、`Korean`，或手动输入语言）
-4. 如果选择了 `both`，再选择这次 onboarding 要由哪个 provider 启动
+2. 选择你偏好的 provider 模式（`claude-code`、`codex` 或 `both`）
+3. 选择工作流语言（`English`、`Korean` 或自定义语言）
+4. 如果你选择了 `both`，再决定这次 onboarding 由哪个 provider 先启动
 5. 完成默认 `main` gc-branch 的引导式 onboarding
-6. 用 `gctree resolve --query "..."` 解析相关上下文
+6. 用 `gctree resolve --query "..."` 拉取相关上下文
 7. 用 `gctree checkout` 创建或切换 gc-branch
-8. 只有在 gc-branch 为空时才运行 `gctree onboard`
-9. 通过仓库范围映射，让 gc-branch 只作用于真正相关的仓库
-10. 后续长期变更使用 `gctree update-global-context`
+8. `gctree onboard` 只用于空的 gc-branch
+9. 通过 repo scope 映射，让 gc-branch 只在它该生效的仓库里生效
+10. 之后的长期变化用 `gctree update-global-context` 来补充
 
 ## 核心命令
 
-| 命令 | 说明 |
+| 命令 | 用途 |
 | --- | --- |
-| `gctree init` | 创建 `~/.gctree` 和默认 `main` gc-branch，保存 provider 模式、实际 onboarding provider 和首选语言，给当前环境安装命令表面，并在 `main` 为空时启动引导式 onboarding。 |
+| `gctree init` | 创建 `~/.gctree`，创建默认 `main` gc-branch，保存 provider 模式 / onboarding provider / 偏好语言，为当前环境安装 scaffold，并在 `main` 为空时启动引导式 onboarding。 |
 | `gctree checkout <branch>` | 切换当前激活的 gc-branch。 |
-| `gctree checkout -b <branch>` | 创建新的空 gc-branch 并切换过去。 |
-| `gctree branches` | 列出可用 gc-branches 并显示当前 gc-branch。 |
-| `gctree status` | 显示当前 gc-branch、当前仓库、当前仓库的 scope 状态、警告和偏好 provider。 |
-| `gctree resolve --query TEXT` | 在相关 gc-branch 中搜索上下文。如果当前仓库还没映射，可以交互式决定如何处理。 |
-| `gctree repo-map` | 显示 `branch-repo-map.json` 的当前内容。 |
-| `gctree set-repo-scope --branch <name> --include` | 把当前仓库加入该 gc-branch 的 include。 |
-| `gctree set-repo-scope --branch <name> --exclude` | 把当前仓库加入该 gc-branch 的 exclude。 |
-| `gctree onboard` | 为当前 gc-branch 启动引导式 onboarding。只有该 gc-branch 为空时才可使用。 |
-| `gctree reset-gc-branch --branch <name> --yes` | 清空一个 gc-branch，使其可以重新 onboarding。 |
-| `gctree update-global-context` | 为当前 gc-branch 启动引导式长期更新。 |
-| `gctree update-gc` / `gctree ugc` | `gctree update-global-context` 的别名。 |
-| `gctree scaffold --host <codex|claude-code>` | 在其他环境中安装 provider 侧的命令表面。 |
-
-## 仓库范围示例
-
-例如 gc-branch `A` 只适用于 `B`、`C`、`D`，而不适用于 `F`，可以这样管理：
+| `gctree checkout -b <branch>` | 创建一个新的空 gc-branch 并立即切换过去。 |
+| `gctree branches` | 列出可用的 gc-branch，并标出当前激活的是哪一个。 |
+| `gctree status` | 显示当前 gc-branch、当前仓库、当前 repo-scope 状态、告警以及偏好的 provider。 |
+| `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 启动引导式 onboarding。只有在该 gc-branch 为空时才可用。 |
+| `gctree reset-gc-branch --branch <name> --yes` | 清空某条 gc-branch，让它可以重新 onboarding。 |
+| `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` 无关。
+
+你可以这样管理：
 
 ```json
 {
@@ -51,19 +53,19 @@
 }
 ```
 
-保存位置：
+这份配置保存在：
 
 ```text
 ~/.gctree/branch-repo-map.json
 ```
 
-此时如果在 `E` 仓库里调用 `resolve`，可以选择：
+当你在仓库 `E` 中执行 `resolve`，而 branch `A` 还没有映射到这里时，`gctree` 可以询问你是否要：
 
-1. 这次先继续
-2. 以后这个仓库总是使用 `A`
-3. 在这个仓库里忽略 `A`
+1. 只这一次继续
+2. 以后在 `E` 中始终使用 `A`
+3. 在 `E` 中忽略 `A`
 
-## 首次使用示例
+## 首次运行示例
 
 ```bash
 gctree init
@@ -72,10 +74,10 @@ gctree init
 然后：
 
 1. 选择 `codex` 或 `claude-code`
-2. 让 `gctree` 为当前环境安装命令表面
-3. 完成 `main` gc-branch 的 onboarding
+2. 让 `gctree` 为当前环境安装 scaffold
+3. 完成 `main` gc-branch 的引导式 onboarding
 
-## 多 gc-branch 示例
+## 多分支示例
 
 ```bash
 gctree checkout -b client-b
@@ -96,17 +98,17 @@ gctree update-gc
 gctree ugc
 ```
 
-如果在实际工作中发现某个仓库其实应该属于当前 gc-branch，更自然的流程是：
+如果某个新变得重要的仓库也应该进入长期上下文，更自然的流程是：
 
-1. 先把这个仓库加入 branch repo map
-2. 然后用 `update-global-context` 补充这个仓库是什么、为什么重要等长期上下文
+1. 先把这个仓库映射到对应的 gc-branch
+2. 再执行 `update-global-context`，补充这个仓库做什么、为什么重要等长期知识
 
 ## 集成模式
 
 ### Codex CLI / Claude Code CLI
 
-`gctree scaffold` 会安装 provider 侧的 guided onboarding 和 guided update 命令。
-这些命令在开始前都应该明确说明当前激活的是哪个 gc-branch，并且除非用户明确要求切换，否则要始终使用保存下来的工作流语言。
+`gctree scaffold` 会安装面向 provider 的命令表面，比如引导式 onboarding 和引导式更新。
+这些命令在开始收集或应用长期上下文之前，都应该明确说明当前激活的是哪条 gc-branch，并且除非用户明确要求切换，否则应继续使用已经保存的工作流语言。
 
 ```bash
 gctree scaffold --host codex --target /path/to/repo
@@ -115,5 +117,5 @@ gctree scaffold --host claude-code --target /path/to/repo
 
 ### 运行时行为
 
-当前激活的 gc-branch 是 `~/.gctree` 里的 `HEAD` 指向的 fallback 分支。
-但如果某个仓库被明确映射到另一个 gc-branch，那么对这个仓库来说，branch map 的优先级高于 HEAD。
+默认情况下，激活的 gc-branch 是 `~/.gctree` 中 `HEAD` 指向的那一条。但如果某个仓库被显式绑定到了另一条 gc-branch，repo mapping 就可以覆盖这个默认值。
+这使得 gc-tree 对那些同时在许多互不相关仓库里开很多会话的重度用户来说也依然实用。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@handsupmin/gc-tree",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Global Context Tree, a lightweight branch-aware global context orchestrator for AI coding tools",
   "type": "module",
   "private": false,