@handsupmin/gc-tree 0.1.1

package/docs/usage.es.md

@@ -0,0 +1,119 @@
+# Uso
+
+[English](usage.md) | [한국어](usage.ko.md) | [简体中文](usage.zh.md) | [日本語](usage.ja.md) | [Español](usage.es.md)
+
+## Summary
+
+Un flujo estándar de `gctree` consiste en inicializar gc-tree, elegir un provider, completar el onboarding del gc-branch `main`, crear nuevos gc-branches cuando haga falta, asociar cada repositorio al gc-branch correcto y usar actualizaciones guiadas para los cambios duraderos.
+
+## Flujo 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 escribe tu propio idioma)
+4. si elegiste `both`, decide qué provider debe iniciar este onboarding
+5. completa el onboarding guiado del gc-branch `main`
+6. resuelve el contexto relevante con `gctree resolve --query "..."`
+7. crea o cambia gc-branches con `gctree checkout`
+8. usa `gctree onboard` solo en gc-branches vacíos
+9. usa el mapeo por repositorio para que cada gc-branch solo aplique donde corresponde
+10. usa `gctree update-global-context` para cambios duraderos posteriores
+
+## Comandos clave
+
+| Comando | Propósito |
+| --- | --- |
+| `gctree init` | Crea `~/.gctree`, crea el gc-branch `main`, guarda el modo de provider, el provider real de onboarding y el idioma preferido, prepara el entorno actual y arranca el onboarding guiado si `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 muestra el activo. |
+| `gctree status` | Muestra el gc-branch activo, el repo actual, el estado de alcance para ese repo, las advertencias y el provider guardado. |
+| `gctree resolve --query TEXT` | Busca contexto en el gc-branch relevante. Si el repo actual aún no está mapeado, permite decidir interactivamente qué hacer. |
+| `gctree repo-map` | Muestra el contenido actual de `branch-repo-map.json`. |
+| `gctree set-repo-scope --branch <name> --include` | Añade el repo actual al include de ese gc-branch. |
+| `gctree set-repo-scope --branch <name> --exclude` | Añade el repo actual al exclude de ese gc-branch. |
+| `gctree onboard` | Inicia el onboarding guiado del gc-branch activo. Solo funciona si ese gc-branch está vacío. |
+| `gctree reset-gc-branch --branch <name> --yes` | Limpia un gc-branch para poder volver a hacer onboarding. |
+| `gctree update-global-context` | Inicia 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 alcance por repositorio
+
+Por ejemplo, si el gc-branch `A` solo aplica a `B`, `C` y `D`, y no a `F`, puedes gestionarlo así:
+
+```json
+{
+  "A": {
+    "include": ["B", "C", "D"],
+    "exclude": ["F"]
+  }
+}
+```
+
+Guardado en:
+
+```text
+~/.gctree/branch-repo-map.json
+```
+
+Si luego llamas a `resolve` desde `E`, puedes elegir entre:
+
+1. continuar solo esta vez
+2. usar siempre `A` en `E`
+3. ignorar `A` en `E`
+
+## Ejemplo de primera ejecución
+
+```bash
+gctree init
+```
+
+Después:
+
+1. elige `codex` o `claude-code`
+2. deja que `gctree` prepare el entorno actual
+3. completa el onboarding del gc-branch `main`
+
+## Ejemplo con varios gc-branches
+
+```bash
+gctree checkout -b client-b
+gctree onboard
+gctree resolve --query "billing retry policy"
+```
+
+## Ejemplo de actualización
+
+```bash
+gctree update-global-context
+```
+
+Alias cortos:
+
+```bash
+gctree update-gc
+gctree ugc
+```
+
+Si al trabajar descubres que un repo realmente pertenece al gc-branch actual, el flujo natural es:
+
+1. primero añadir ese repo al branch repo map
+2. después ejecutar `update-global-context` para agregar contexto duradero sobre qué hace ese repo y por qué importa
+
+## Patrones de integración
+
+### Codex CLI / Claude Code CLI
+
+`gctree scaffold` instala comandos del provider para onboarding y actualizaciones guiadas.
+Esos comandos deben dejar claro cuál es el gc-branch activo antes de empezar, y también deben mantener el idioma guardado durante todo el flujo salvo que el usuario pida cambiarlo explícitamente.
+
+```bash
+gctree scaffold --host codex --target /path/to/repo
+gctree scaffold --host claude-code --target /path/to/repo
+```
+
+### Comportamiento en runtime
+
+El gc-branch activo es el fallback apuntado por `HEAD` dentro de `~/.gctree`.
+Pero si un repo está vinculado explícitamente a otro gc-branch, para ese repo el branch map tiene prioridad sobre HEAD.

package/docs/usage.ja.md

@@ -0,0 +1,119 @@
+# 使い方
+
+[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 に結び付け、その後の長期変更はガイド付き更新で処理する流れです。
+
+## 標準フロー
+
+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` を使う
+
+## 主要コマンド
+
+| コマンド | 説明 |
+| --- | --- |
+| `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 update-gc` / `gctree ugc` | `gctree update-global-context` の別名です。 |
+| `gctree scaffold --host <codex|claude-code>` | 別環境に provider 向けコマンド面をインストールします。 |
+
+## リポジトリ範囲の例
+
+たとえば gc-branch `A` が `B`、`C`、`D` にだけ関係し、`F` には関係しないなら、次のように管理できます。
+
+```json
+{
+  "A": {
+    "include": ["B", "C", "D"],
+    "exclude": ["F"]
+  }
+}
+```
+
+保存先:
+
+```text
+~/.gctree/branch-repo-map.json
+```
+
+この状態で `E` リポジトリから `resolve` を実行すると、次を選べます。
+
+1. 今回だけ続行する
+2. 今後も `E` で `A` を使う
+3. `E` では `A` を無視する
+
+## 初回実行の例
+
+```bash
+gctree init
+```
+
+その後:
+
+1. `codex` または `claude-code` を選ぶ
+2. `gctree` に現在の環境を scaffold させる
+3. `main` gc-branch のオンボーディングを完了する
+
+## 複数 gc-branch の例
+
+```bash
+gctree checkout -b client-b
+gctree onboard
+gctree resolve --query "billing retry policy"
+```
+
+## 更新の例
+
+```bash
+gctree update-global-context
+```
+
+短い別名:
+
+```bash
+gctree update-gc
+gctree ugc
+```
+
+実際に作業してみて、そのリポジトリが現在の gc-branch に属するべきだと分かった場合は、自然な流れはこうです。
+
+1. まずそのリポジトリを branch repo map に追加する
+2. その後 `update-global-context` を実行して、そのリポジトリが何を担うのか、なぜ重要なのかといった長期コンテキストを追加する
+
+## 統合パターン
+
+### Codex CLI / Claude Code CLI
+
+`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 より優先されます。

package/docs/usage.ko.md

@@ -0,0 +1,119 @@
+# 사용방법
+
+[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에 매핑하고, 이후 장기 변경은 가이드형 업데이트로 처리합니다.
+
+## 기본 흐름
+
+1. `gctree init` 실행
+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. 비어 있는 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와 현재 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 update-gc` / `gctree ugc` | `gctree update-global-context`의 별칭입니다. |
+| `gctree scaffold --host <codex|claude-code>` | 다른 환경에 provider용 명령 표면을 설치합니다. |
+
+## 레포 범위 예시
+
+예를 들어 gc-branch `A`가 `B`, `C`, `D` 레포에만 관련 있고 `F`와는 무관하다면, 다음과 같이 관리할 수 있습니다.
+
+```json
+{
+  "A": {
+    "include": ["B", "C", "D"],
+    "exclude": ["F"]
+  }
+}
+```
+
+저장 위치:
+
+```text
+~/.gctree/branch-repo-map.json
+```
+
+그 상태에서 `E` 레포에서 `resolve`를 호출하면 다음 중 하나를 고를 수 있습니다.
+
+1. 이번만 진행
+2. 앞으로 이 레포에서도 `A` 사용
+3. 이 레포에서는 `A` 무시
+
+## 최초 실행 예시
+
+```bash
+gctree init
+```
+
+그다음:
+
+1. `codex` 또는 `claude-code` 선택
+2. `gctree`가 현재 환경을 스캐폴딩하도록 둠
+3. `main` gc-branch 온보딩 완료
+
+## 다중 gc-branch 예시
+
+```bash
+gctree checkout -b client-b
+gctree onboard
+gctree resolve --query "billing retry policy"
+```
+
+## 업데이트 예시
+
+```bash
+gctree update-global-context
+```
+
+짧은 별칭:
+
+```bash
+gctree update-gc
+gctree ugc
+```
+
+만약 실제 작업을 하다 보니 어떤 레포가 현재 gc-branch에 포함되어야 할 것 같다면, 자연스러운 흐름은 이렇습니다.
+
+1. 먼저 branch repo map에 그 레포를 포함시키고
+2. 그 다음 `update-global-context`로 이 레포가 무엇을 하는지, 왜 중요한지 같은 장기 컨텍스트를 추가
+
+## 통합 패턴
+
+### Codex CLI / Claude Code CLI
+
+`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보다 우선합니다.

package/docs/usage.md

@@ -0,0 +1,121 @@
+# Usage
+
+[English](usage.md) | [한국어](usage.ko.md) | [简体中文](usage.zh.md) | [日本語](usage.ja.md) | [Español](usage.es.md)
+
+## 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.
+
+## Standard workflow
+
+1. run `gctree init`
+2. choose your preferred provider mode (`claude-code`, `codex`, or `both`)
+3. choose the workflow language (`English`, `Korean`, or a custom language)
+4. if you picked `both`, choose which provider should start onboarding now
+5. complete guided onboarding for the default `main` gc-branch
+6. resolve relevant context with `gctree resolve --query "..."`
+7. create or switch gc-branches with `gctree checkout`
+8. run `gctree onboard` only for an empty gc-branch
+9. use repo scope mapping so a gc-branch only applies where it belongs
+10. use `gctree update-global-context` for durable changes later
+
+## Core commands
+
+| Command | Purpose |
+| --- | --- |
+| `gctree init` | Create `~/.gctree`, create the default `main` gc-branch, save the provider mode, onboarding provider, and preferred language, scaffold the current environment, and start guided onboarding when `main` is empty. |
+| `gctree checkout <branch>` | Switch the active gc-branch. |
+| `gctree checkout -b <branch>` | Create and switch to a new empty gc-branch. |
+| `gctree branches` | List available gc-branches and show the active one. |
+| `gctree status` | Show the active gc-branch, the current repo, the current repo-scope status, warnings, and the preferred provider. |
+| `gctree resolve --query TEXT` | Search the relevant gc-branch for context. If the current repo is unmapped, `gctree` can ask how that repo should be treated. |
+| `gctree repo-map` | Show the current contents of `branch-repo-map.json`. |
+| `gctree set-repo-scope --branch <name> --include` | Mark the current repo as included for that gc-branch. |
+| `gctree set-repo-scope --branch <name> --exclude` | Mark the current repo as ignored for that gc-branch. |
+| `gctree onboard` | Launch guided onboarding for the active gc-branch. Works only when that gc-branch is empty. |
+| `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. |
+
+## Example repo-scope flow
+
+Suppose gc-branch `A` is relevant to repos `B`, `C`, and `D`, but not `F`.
+
+You can manage that through:
+
+```json
+{
+  "A": {
+    "include": ["B", "C", "D"],
+    "exclude": ["F"]
+  }
+}
+```
+
+stored in:
+
+```text
+~/.gctree/branch-repo-map.json
+```
+
+When `resolve` runs from repo `E` and branch `A` is not mapped there yet, `gctree` can ask whether to:
+
+1. continue once
+2. always use `A` in `E`
+3. ignore `A` in `E`
+
+## Example first-run flow
+
+```bash
+gctree init
+```
+
+Then:
+
+1. choose `codex` or `claude-code`
+2. let `gctree` scaffold the current environment
+3. complete guided onboarding for the `main` gc-branch
+
+## Example multi-branch flow
+
+```bash
+gctree checkout -b client-b
+gctree onboard
+gctree resolve --query "billing retry policy"
+```
+
+## Example update flow
+
+```bash
+gctree update-global-context
+```
+
+Short aliases:
+
+```bash
+gctree update-gc
+gctree ugc
+```
+
+If a newly relevant repo should also become part of the durable context, the natural flow is:
+
+1. map that repo to the gc-branch
+2. then run `update-global-context` to add durable knowledge about what that repo does and why it matters
+
+## Integration patterns
+
+### 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.
+
+```bash
+gctree scaffold --host codex --target /path/to/repo
+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.

package/docs/usage.zh.md

@@ -0,0 +1,119 @@
+# 使用方法
+
+[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，并把后续长期变更交给引导式更新流程。
+
+## 标准流程
+
+1. 运行 `gctree init`
+2. 选择偏好的 provider 模式（`claude-code`、`codex` 或 `both`）
+3. 选择工作流语言（`English`、`Korean`，或手动输入语言）
+4. 如果选择了 `both`，再选择这次 onboarding 要由哪个 provider 启动
+5. 完成默认 `main` gc-branch 的引导式 onboarding
+6. 用 `gctree resolve --query "..."` 解析相关上下文
+7. 用 `gctree checkout` 创建或切换 gc-branch
+8. 只有在 gc-branch 为空时才运行 `gctree onboard`
+9. 通过仓库范围映射，让 gc-branch 只作用于真正相关的仓库
+10. 后续长期变更使用 `gctree update-global-context`
+
+## 核心命令
+
+| 命令 | 说明 |
+| --- | --- |
+| `gctree init` | 创建 `~/.gctree` 和默认 `main` gc-branch，保存 provider 模式、实际 onboarding provider 和首选语言，给当前环境安装命令表面，并在 `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`，可以这样管理：
+
+```json
+{
+  "A": {
+    "include": ["B", "C", "D"],
+    "exclude": ["F"]
+  }
+}
+```
+
+保存位置：
+
+```text
+~/.gctree/branch-repo-map.json
+```
+
+此时如果在 `E` 仓库里调用 `resolve`，可以选择：
+
+1. 这次先继续
+2. 以后这个仓库总是使用 `A`
+3. 在这个仓库里忽略 `A`
+
+## 首次使用示例
+
+```bash
+gctree init
+```
+
+然后：
+
+1. 选择 `codex` 或 `claude-code`
+2. 让 `gctree` 为当前环境安装命令表面
+3. 完成 `main` gc-branch 的 onboarding
+
+## 多 gc-branch 示例
+
+```bash
+gctree checkout -b client-b
+gctree onboard
+gctree resolve --query "billing retry policy"
+```
+
+## 更新示例
+
+```bash
+gctree update-global-context
+```
+
+简短别名：
+
+```bash
+gctree update-gc
+gctree ugc
+```
+
+如果在实际工作中发现某个仓库其实应该属于当前 gc-branch，更自然的流程是：
+
+1. 先把这个仓库加入 branch repo map
+2. 然后用 `update-global-context` 补充这个仓库是什么、为什么重要等长期上下文
+
+## 集成模式
+
+### Codex CLI / Claude Code CLI
+
+`gctree scaffold` 会安装 provider 侧的 guided onboarding 和 guided update 命令。
+这些命令在开始前都应该明确说明当前激活的是哪个 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。

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@handsupmin/gc-tree",
+  "version": "0.1.1",
+  "description": "Global Context Tree, a lightweight branch-aware global context orchestrator for AI coding tools",
+  "type": "module",
+  "private": false,
+  "files": [
+    "dist",
+    "skills",
+    "scaffolds",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "gctree": "dist/src/cli.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --import tsx --test tests/*.test.ts",
+    "prepack": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  },
+  "license": "MIT"
+}

package/skills/checkout/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: checkout
+description: Switch or create a gctree gc-branch.
+---
+
+# gctree Checkout
+
+Use this when the user wants to separate global context for different products, clients, companies, or work modes.
+
+## Procedure
+- `gctree checkout <branch>` switches to an existing gc-branch.
+- `gctree checkout -b <branch>` creates a new empty gc-branch and switches to it.
+- After checkout, run `gctree status` so the user can see which gc-branch is active.
+
+## Notes
+- In user-facing language, call these **gc-branches** so they are not confused with git branches.
+- Keep gc-branch switching explicit so different products do not bleed into each other.