@handsupmin/gc-tree 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 handsupmin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.es.md

@@ -0,0 +1,166 @@
+# gc-tree
+
+Una capa de contexto global con ramas para herramientas de programación con IA.
+
+[English](README.md) | [한국어](README.ko.md) | [简体中文](README.zh.md) | [日本語](README.ja.md) | [Español](README.es.md)
+
+## Introducción
+
+`gctree` es un **Global Context Tree** ligero para herramientas de programación con IA.
+Le da al contexto duradero un hogar reutilizable, basado en archivos y separado por ramas, sin obligarte a adoptar una plataforma completa de orquestación.
+
+Cuando un solo `AGENTS.md`, `CLAUDE.md` o fragmento de prompt ya no alcanza, `gctree` te ayuda a:
+
+- separar el contexto por producto, cliente o línea de trabajo
+- conservar el conocimiento fuente en markdown en lugar de depender de memoria oculta
+- resolver el contexto activo rápidamente con un índice liviano y documentos summary-first
+- hacer onboarding y actualizaciones duraderas desde tu CLI LLM preferida
+- hacer que un gc-branch solo se use en los repos realmente relacionados
+
+## Características rápidas
+
+- **Onboarding guiado por provider**  
+  `gctree init` primero te pregunta qué modo de provider quieres usar (`claude-code`, `codex` o `both`), luego qué idioma deben usar las respuestas, guarda esas decisiones, prepara la superficie de comandos adecuada y arranca el onboarding del gc-branch `main` por defecto.
+- **gc-branches con alcance por repositorio**  
+  Con `~/.gctree/branch-repo-map.json` puedes asociar un gc-branch solo a ciertos repositorios. Por ejemplo, hacer que A aplique a B/C/D y se ignore en F.
+- **Protección interactiva de alcance**  
+  Si `gctree resolve` detecta que el repositorio actual todavía no está asociado a ese gc-branch, puede preguntarte si quieres continuar una vez, usarlo siempre aquí o ignorarlo aquí.
+- **Documentación summary-first**  
+  Las herramientas pueden leer primero un resumen corto y abrir el documento completo solo cuando hace falta.
+- **Actualizaciones duraderas guiadas**  
+  Puedes actualizar el contexto global con el mismo flujo del provider, sin escribir JSON a mano.
+
+## Instalación y guía rápida
+
+### Instalar desde npm
+
+```bash
+npm install -g @handsupmin/gc-tree
+```
+
+Si solo quieres ejecutarlo una vez sin instalación global:
+
+```bash
+npx @handsupmin/gc-tree init
+```
+
+- **Nombre del paquete:** `@handsupmin/gc-tree`
+- **Comando CLI:** `gctree`
+- **Requisito:** Node.js 20+
+Para desarrollo desde el código fuente, consulta [docs/local-development.md](docs/local-development.md).
+
+### Inicio rápido
+
+#### 1) Inicializa gc-tree
+
+```bash
+gctree init
+```
+
+Este comando:
+
+- crea `~/.gctree`
+- crea el gc-branch `main` por defecto
+- te pide elegir un modo de provider (`claude-code`, `codex` o `both`)
+- si eliges `both`, te pregunta qué provider debe iniciar este onboarding
+- te pide elegir el idioma (`English`, `Korean` o escribir tu propio idioma)
+- guarda el modo de provider, el provider real de onboarding y el idioma en `~/.gctree/settings.json`
+- prepara la superficie de comandos adecuada en el entorno actual
+- inicia el onboarding guiado del gc-branch activo cuando `main` sigue vacío
+
+#### 2) Resuelve el contexto activo
+
+```bash
+gctree resolve --query "auth token rotation"
+```
+
+Si el repositorio actual aún no está asociado a ese gc-branch, `gctree` puede dejarte elegir entre:
+
+1. continuar solo esta vez
+2. usar siempre este gc-branch en este repo
+3. ignorar este gc-branch en este repo
+
+Si eliges 2 o 3, `~/.gctree/branch-repo-map.json` se actualiza.
+
+#### 3) Crea otro gc-branch si necesitas un contexto separado
+
+```bash
+gctree checkout -b client-b
+```
+
+`checkout -b` crea un **gc-branch vacío nuevo**. No copia los documentos de otra rama.
+
+#### 4) Haz onboarding de un gc-branch vacío
+
+```bash
+gctree onboard
+```
+
+#### 5) Actualiza el contexto duradero más adelante
+
+```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 `gctree update-global-context` para agregar contexto duradero sobre qué hace ese repo y por qué importa
+
+#### 6) Restablece un gc-branch antes de volver a hacer onboarding
+
+```bash
+gctree reset-gc-branch --branch client-b --yes
+```
+
+### Comandos visibles dentro del runtime
+
+Después del scaffold, los comandos visibles son:
+
+- **Codex:** `$gc-onboard`, `$gc-update-global-context`
+- **Claude Code:** `/gc-onboard`, `/gc-update-global-context`
+
+Esos comandos deben dejar claro cuál es el gc-branch activo antes de empezar a recoger o actualizar contexto duradero, y también deben mantener el idioma guardado hasta el final, salvo que el usuario pida cambiarlo explícitamente.
+
+### Comandos clave de un vistazo
+
+| Objetivo | Comando |
+| --- | --- |
+| Inicializar gc-tree y elegir provider | `gctree init` |
+| Confirmar el gc-branch activo | `gctree status` |
+| Buscar en el contexto activo | `gctree resolve --query "..."` |
+| Ver las reglas de alcance por repo | `gctree repo-map` |
+| Incluir o excluir un repo para un gc-branch | `gctree set-repo-scope --branch <name> --include` / `--exclude` |
+| Crear o cambiar gc-branches | `gctree checkout <branch>` / `gctree checkout -b <branch>` |
+| Hacer onboarding de un gc-branch vacío | `gctree onboard` |
+| Actualizar el gc-branch activo | `gctree update-global-context` / `gctree update-gc` / `gctree ugc` |
+| Restablecer un gc-branch antes de re-onboard | `gctree reset-gc-branch --branch <name> --yes` |
+| Instalar scaffold manualmente en otro entorno | `gctree scaffold --host codex --target /path/to/repo` |
+
+## Documentación
+
+La documentación detallada está en el directorio [`docs/`](docs).
+
+- **Concepto** — [`docs/concept.es.md`](docs/concept.es.md)  
+  Explica qué es `gctree`, qué problema resuelve y cuál es el alcance de la capa de contexto global.
+- **Principios** — [`docs/principles.es.md`](docs/principles.es.md)  
+  Resume las reglas de gc-branches, alcance por repositorio, documentos summary-first y actualizaciones guiadas.
+- **Uso** — [`docs/usage.es.md`](docs/usage.es.md)  
+  Describe el flujo CLI estándar, los comandos del provider, el comportamiento de alcance por repo y los patrones de integración.
+- **Desarrollo local** — [`docs/local-development.es.md`](docs/local-development.es.md)  
+  Explica cómo instalar dependencias, ejecutar la CLI localmente y verificar cambios.
+
+## Contribuir
+
+Las contribuciones son bienvenidas. Consulta el documento en inglés [CONTRIBUTING.md](CONTRIBUTING.md) para ver el flujo de desarrollo y la checklist de PR.
+
+## Licencia
+
+MIT. Consulta [`LICENSE`](LICENSE).

package/README.ja.md

@@ -0,0 +1,166 @@
+# gc-tree
+
+AI コーディングツール向けのブランチ対応グローバルコンテキストレイヤー。
+
+[English](README.md) | [한국어](README.ko.md) | [简体中文](README.zh.md) | [日本語](README.ja.md) | [Español](README.es.md)
+
+## 紹介
+
+`gctree` は AI コーディングツール向けの軽量な **Global Context Tree** です。
+長期的なコンテキストに、ファイルベースで再利用しやすく、ブランチ単位で切り替えられる明確な置き場所を与え、既存のワークフローにも自然に組み込めます。
+
+1 つの `AGENTS.md`、`CLAUDE.md`、あるいは短いプロンプト断片だけでは足りなくなったとき、`gctree` は次のことを助けます。
+
+- プロダクト、クライアント、作業トラックごとにコンテキストを分ける
+- 隠れたメモリではなく、markdown 文書を source of truth として管理する
+- 小さなインデックスと summary-first ドキュメントで必要なコンテキストを素早く見つける
+- 好みの LLM CLI を使ってオンボーディングと永続更新を進める
+- ある gc-branch が本当に関係するリポジトリでだけ使われるようにする
+
+## 簡単な特徴
+
+- **Provider 駆動のオンボーディング**  
+  `gctree init` はまず `claude-code`、`codex`、`both` のどの provider モードを使うかを聞き、その後に応答言語を選ばせ、選択内容を保存して必要なコマンド面を用意したうえで、デフォルトの `main` gc-branch のオンボーディングを開始します。
+- **リポジトリ範囲付き gc-branch**  
+  `~/.gctree/branch-repo-map.json` により、1 つの gc-branch を特定のリポジトリ群にだけ結びつけられます。たとえば A を B/C/D にだけ適用し、F では無視できます。
+- **対話的な範囲ガード**  
+  `gctree resolve` が現在のリポジトリをまだこの gc-branch に結び付けていないと判断した場合、今回だけ使うか、今後も使うか、ここでは無視するかを選べます。
+- **Summary-first ドキュメント構造**  
+  ツールはまず短い要約を読み、必要なときだけ全文を読み込めます。
+- **ガイド付きの永続更新**  
+  JSON ファイルを手で作らなくても、同じ provider フローでグローバルコンテキストを更新できます。
+
+## インストールとクイックスタート
+
+### npm からインストール
+
+```bash
+npm install -g @handsupmin/gc-tree
+```
+
+グローバルインストールなしで一度だけ実行する場合:
+
+```bash
+npx @handsupmin/gc-tree init
+```
+
+- **パッケージ名:** `@handsupmin/gc-tree`
+- **CLI コマンド:** `gctree`
+- **要件:** Node.js 20+
+ソースベースの開発は [docs/local-development.md](docs/local-development.md) を参照してください。
+
+### クイックスタート
+
+#### 1) gc-tree を初期化する
+
+```bash
+gctree init
+```
+
+このコマンドは次のことを行います。
+
+- `~/.gctree` を作成する
+- デフォルトの `main` gc-branch を作成する
+- provider モード（`claude-code`、`codex`、`both`）を選ばせる
+- `both` を選んだ場合は、今回のオンボーディングをどちらで始めるかをさらに選ばせる
+- 言語（`English`、`Korean`、または自由入力）を選ばせる
+- provider モード、実際のオンボーディング provider、言語を `~/.gctree/settings.json` に保存する
+- 現在の環境に必要なコマンド面を用意する
+- `main` が空であれば、アクティブな gc-branch のガイド付きオンボーディングを開始する
+
+#### 2) 現在のコンテキストを解決する
+
+```bash
+gctree resolve --query "auth token rotation"
+```
+
+現在のリポジトリがその gc-branch にまだ紐付いていない場合、`gctree` は次を選ばせます。
+
+1. 今回だけ続行する
+2. 今後もこのリポジトリでこの gc-branch を使う
+3. このリポジトリではこの gc-branch を無視する
+
+2 または 3 を選ぶと `~/.gctree/branch-repo-map.json` が更新されます。
+
+#### 3) 別のコンテキストが必要なら新しい gc-branch を作る
+
+```bash
+gctree checkout -b client-b
+```
+
+`checkout -b` は**新しい空の gc-branch**を作ります。既存のブランチ文書はコピーしません。
+
+#### 4) 空の gc-branch をオンボードする
+
+```bash
+gctree onboard
+```
+
+#### 5) 後から永続コンテキストを更新する
+
+```bash
+gctree update-global-context
+```
+
+短い別名:
+
+```bash
+gctree update-gc
+gctree ugc
+```
+
+実際に作業してみて、そのリポジトリが現在の gc-branch に属するべきだと分かった場合は、自然な流れはこうです。
+
+1. まずそのリポジトリを branch repo map に追加する
+2. その後 `gctree update-global-context` を実行して、そのリポジトリが何を担うのか、なぜ重要なのかといった長期コンテキストを追加する
+
+#### 6) 再オンボーディングの前に gc-branch をリセットする
+
+```bash
+gctree reset-gc-branch --branch client-b --yes
+```
+
+### ランタイムで見える provider コマンド
+
+scaffold 後に見えるコマンドは次の通りです。
+
+- **Codex:** `$gc-onboard`, `$gc-update-global-context`
+- **Claude Code:** `/gc-onboard`, `/gc-update-global-context`
+
+これらのコマンドは、長期コンテキストを集めたり更新したりする前に、現在の gc-branch を必ず明示し、ユーザーが明示的に切り替えを求めない限り、保存された言語を最後まで維持するべきです。
+
+### 主要コマンド一覧
+
+| 目的 | コマンド |
+| --- | --- |
+| gc-tree を初期化して provider を選ぶ | `gctree init` |
+| 現在の gc-branch を確認する | `gctree status` |
+| 現在のコンテキストを検索する | `gctree resolve --query "..."` |
+| リポジトリ範囲ルールを確認する | `gctree repo-map` |
+| gc-branch に対してリポジトリを明示的に含める/除外する | `gctree set-repo-scope --branch <name> --include` / `--exclude` |
+| gc-branch を作成/切り替えする | `gctree checkout <branch>` / `gctree checkout -b <branch>` |
+| 空の gc-branch をオンボードする | `gctree onboard` |
+| 現在の gc-branch を永続更新する | `gctree update-global-context` / `gctree update-gc` / `gctree ugc` |
+| 再オンボーディング前に gc-branch をリセットする | `gctree reset-gc-branch --branch <name> --yes` |
+| 別環境に手動で scaffold を入れる | `gctree scaffold --host codex --target /path/to/repo` |
+
+## ドキュメント
+
+詳細ドキュメントは [`docs/`](docs) にまとまっています。
+
+- **コンセプト** — [`docs/concept.ja.md`](docs/concept.ja.md)  
+  `gctree` が何であり、どの課題を解決し、どこまでを担当するのかを説明します。
+- **原則** — [`docs/principles.ja.md`](docs/principles.ja.md)  
+  gc-branch、リポジトリ範囲、summary-first 文書、ガイド付き更新の考え方をまとめています。
+- **使い方** — [`docs/usage.ja.md`](docs/usage.ja.md)  
+  標準 CLI フロー、provider コマンド、リポジトリ範囲の挙動、統合パターンを案内します。
+- **ローカル実行方法** — [`docs/local-development.ja.md`](docs/local-development.ja.md)  
+  依存関係のインストール、CLI のローカル実行、変更確認手順を説明します。
+
+## コントリビュート
+
+コントリビューション歓迎です。開発フローと PR チェックリストは英語ドキュメントの [CONTRIBUTING.md](CONTRIBUTING.md) を参照してください。
+
+## ライセンス
+
+MIT。詳細は [`LICENSE`](LICENSE) を参照してください。

package/README.ko.md

@@ -0,0 +1,166 @@
+# gc-tree
+
+AI 코딩 도구를 위한 브랜치 기반 글로벌 컨텍스트 레이어.
+
+[English](README.md) | [한국어](README.ko.md) | [简体中文](README.zh.md) | [日本語](README.ja.md) | [Español](README.es.md)
+
+## 소개
+
+`gctree`는 AI 코딩 도구를 위한 가벼운 **Global Context Tree**입니다.
+장기적으로 유지해야 하는 컨텍스트를 파일 기반으로 명시적으로 관리할 수 있게 해주며, 브랜치 단위로 분리해서 기존 워크플로에 자연스럽게 붙일 수 있습니다.
+
+하나의 `AGENTS.md`, `CLAUDE.md`, 혹은 짧은 프롬프트 파일만으로는 부족해질 때 `gctree`는 다음을 도와줍니다.
+
+- 제품, 고객사, 업무 트랙별로 컨텍스트를 분리하기
+- 숨겨진 메모리 대신 markdown 기반의 source-of-truth 문서로 관리하기
+- 작은 인덱스와 summary-first 문서 구조로 필요한 컨텍스트를 빠르게 찾기
+- 선호하는 LLM CLI를 통해 온보딩과 장기 업데이트를 진행하기
+- 특정 gc-branch가 실제로 관련 있는 레포에만 적용되게 하기
+
+## 간단 특징
+
+- **Provider 기반 온보딩**  
+  `gctree init`은 `claude-code`, `codex`, `both` 중 어떤 provider 모드를 쓸지 묻고, 이어서 응답 언어를 고르게 한 뒤, 그 선택을 저장하고 필요한 명령 표면을 스캐폴딩한 다음 기본 `main` gc-branch 온보딩을 시작합니다.
+- **레포 범위 인식 gc-branch**  
+  `~/.gctree/branch-repo-map.json`을 통해 하나의 gc-branch를 특정 레포 집합에만 연결할 수 있습니다. 예를 들어 A는 B/C/D에만 적용하고 F에서는 무시하게 만들 수 있습니다.
+- **인터랙티브 범위 가드**  
+  `gctree resolve`가 현재 레포가 아직 이 gc-branch에 매핑되지 않았다고 판단하면, 이번만 진행할지 / 항상 사용할지 / 여기서는 무시할지를 물어볼 수 있습니다.
+- **Summary-first 문서 구조**  
+  도구가 먼저 짧은 요약을 읽고, 필요할 때만 본문을 확장해서 읽을 수 있습니다.
+- **가이드형 장기 업데이트**  
+  JSON 파일을 직접 만들지 않아도 같은 provider 흐름으로 글로벌 컨텍스트를 갱신할 수 있습니다.
+
+## 설치 및 빠른 시작
+
+### npm으로 설치
+
+```bash
+npm install -g @handsupmin/gc-tree
+```
+
+글로벌 설치 없이 한 번만 실행하려면:
+
+```bash
+npx @handsupmin/gc-tree init
+```
+
+- **패키지 이름:** `@handsupmin/gc-tree`
+- **CLI 명령어:** `gctree`
+- **요구 사항:** Node.js 20+
+소스 기반 개발은 [docs/local-development.md](docs/local-development.md)를 참고하세요.
+
+### 빠른 시작
+
+#### 1) gc-tree 초기화
+
+```bash
+gctree init
+```
+
+이 명령은 다음을 수행합니다.
+
+- `~/.gctree` 생성
+- 기본 `main` gc-branch 생성
+- 사용할 provider 모드(`claude-code`, `codex`, `both`) 선택
+- `both`를 고르면 이번 온보딩을 어느 provider로 시작할지 한 번 더 선택
+- 사용할 언어(`English`, `Korean`, 또는 직접 입력한 언어) 선택
+- provider 모드, 실제 온보딩 provider, 언어를 `~/.gctree/settings.json`에 저장
+- 현재 환경에 맞는 명령 표면 스캐폴딩
+- `main`이 비어 있으면 활성 gc-branch에 대한 가이드형 온보딩 시작
+
+#### 2) 현재 컨텍스트 조회
+
+```bash
+gctree resolve --query "auth token rotation"
+```
+
+만약 현재 레포가 이 gc-branch의 매핑 범위 밖이라면, `gctree`는 다음 중 하나를 고르게 할 수 있습니다.
+
+1. 이번만 진행
+2. 이 레포에서 항상 이 gc-branch 사용
+3. 이 레포에서는 이 gc-branch 무시
+
+2번 또는 3번을 고르면 `~/.gctree/branch-repo-map.json`이 갱신됩니다.
+
+#### 3) 별도 컨텍스트가 필요하면 새 gc-branch 생성
+
+```bash
+gctree checkout -b client-b
+```
+
+`checkout -b`는 **새로운 빈 gc-branch**를 만듭니다. 기존 브랜치 문서를 복사하지 않습니다.
+
+#### 4) 비어 있는 gc-branch를 온보딩
+
+```bash
+gctree onboard
+```
+
+#### 5) 나중에 장기 컨텍스트 업데이트
+
+```bash
+gctree update-global-context
+```
+
+짧은 별칭:
+
+```bash
+gctree update-gc
+gctree ugc
+```
+
+만약 실제 작업을 하다 보니 어떤 레포가 현재 gc-branch에 포함되어야 할 것 같다면, 자연스러운 흐름은 이렇습니다.
+
+1. 먼저 그 레포를 branch repo map에 포함시키고
+2. 그 다음 `gctree update-global-context`로 이 레포가 어떤 역할을 하는지, 왜 중요한지 같은 장기 컨텍스트를 추가
+
+#### 6) 다시 온보딩하려면 먼저 gc-branch 리셋
+
+```bash
+gctree reset-gc-branch --branch client-b --yes
+```
+
+### 런타임에서 보이는 provider 명령
+
+스캐폴딩 이후 런타임에서 보이는 명령은 다음과 같습니다.
+
+- **Codex:** `$gc-onboard`, `$gc-update-global-context`
+- **Claude Code:** `/gc-onboard`, `/gc-update-global-context`
+
+이 명령들은 항상 현재 활성 gc-branch가 무엇인지 먼저 밝히고, 사용자가 명시적으로 바꾸라고 하지 않는 한 저장된 언어를 끝까지 유지하면서 컨텍스트를 수집하거나 업데이트해야 합니다.
+
+### 핵심 명령 한눈에 보기
+
+| 목적 | 명령 |
+| --- | --- |
+| gc-tree 초기화 및 provider 선택 | `gctree init` |
+| 현재 gc-branch 확인 | `gctree status` |
+| 현재 컨텍스트 검색 | `gctree resolve --query "..."` |
+| 레포 범위 규칙 확인 | `gctree repo-map` |
+| gc-branch에 레포 포함/제외 설정 | `gctree set-repo-scope --branch <name> --include` / `--exclude` |
+| gc-branch 생성/전환 | `gctree checkout <branch>` / `gctree checkout -b <branch>` |
+| 비어 있는 gc-branch 온보딩 | `gctree onboard` |
+| 활성 gc-branch 장기 업데이트 | `gctree update-global-context` / `gctree update-gc` / `gctree ugc` |
+| 다시 온보딩하기 전 gc-branch 초기화 | `gctree reset-gc-branch --branch <name> --yes` |
+| 다른 환경에 수동 스캐폴딩 | `gctree scaffold --host codex --target /path/to/repo` |
+
+## 문서
+
+자세한 문서는 [`docs/`](docs) 아래에 정리되어 있습니다.
+
+- **컨셉** — [`docs/concept.ko.md`](docs/concept.ko.md)  
+  `gctree`가 무엇인지, 어떤 문제를 해결하는지, 글로벌 컨텍스트 레이어의 범위를 설명합니다.
+- **원리** — [`docs/principles.ko.md`](docs/principles.ko.md)  
+  gc-branch, 레포 범위, slim index, summary-first 문서, 가이드형 업데이트 원칙을 정리합니다.
+- **사용방법** — [`docs/usage.ko.md`](docs/usage.ko.md)  
+  표준 CLI 흐름, provider 명령, 레포 범위 동작, 통합 패턴을 안내합니다.
+- **로컬 실행방법** — [`docs/local-development.ko.md`](docs/local-development.ko.md)  
+  의존성 설치, 로컬 CLI 실행, 변경 검증 방법을 설명합니다.
+
+## 기여하기
+
+기여는 언제든 환영합니다. 개발 흐름과 PR 체크리스트는 영어 문서인 [CONTRIBUTING.md](CONTRIBUTING.md)를 참고해주세요.
+
+## 라이선스
+
+MIT. 자세한 내용은 [`LICENSE`](LICENSE)를 참고하세요.

package/README.md

@@ -0,0 +1,166 @@
+# gc-tree
+
+Branch-aware global context for AI coding tools.
+
+[English](README.md) | [한국어](README.ko.md) | [简体中文](README.zh.md) | [日本語](README.ja.md) | [Español](README.es.md)
+
+## Introduction
+
+`gctree` is a lightweight **Global Context Tree** for AI coding tools.
+It gives long-lived context a reusable, file-backed home that stays explicit, branch-aware, and easy to plug into existing workflows.
+
+When a single `AGENTS.md`, `CLAUDE.md`, or prompt snippet is no longer enough, `gctree` helps you:
+
+- separate context by product, client, or workstream
+- keep source-of-truth knowledge in markdown instead of hidden memory
+- resolve the active context quickly with a slim index and summary-first docs
+- onboard and update durable context through your preferred LLM CLI provider
+- limit a gc-branch to the repositories where it actually applies
+
+## Key Features
+
+- **Provider-driven onboarding**  
+  `gctree init` asks which provider mode you want (`claude-code`, `codex`, or `both`), then asks which language to use for responses, saves both choices, scaffolds the right command surface, and starts guided onboarding for the default `main` gc-branch.
+- **Repo-aware gc-branch scope**  
+  `gctree` can map a gc-branch to specific repositories through `~/.gctree/branch-repo-map.json`, so one branch can apply to B/C/D while being ignored in F.
+- **Interactive scope guard**  
+  If `gctree resolve` runs in a repo that is not yet mapped to the current gc-branch, it can ask whether to continue once, always use this gc-branch here, or ignore it here.
+- **Summary-first documentation**  
+  Let tools read the short version first and expand only when they need more detail.
+- **Guided durable updates**  
+  Reuse the same provider-driven flow to update context without hand-authoring JSON files.
+
+## Install & Quick Start
+
+### Install from npm
+
+```bash
+npm install -g @handsupmin/gc-tree
+```
+
+Or run it once without a global install:
+
+```bash
+npx @handsupmin/gc-tree init
+```
+
+- **Package name:** `@handsupmin/gc-tree`
+- **CLI command:** `gctree`
+- **Requirements:** Node.js 20+
+For source-based development details, see [docs/local-development.md](docs/local-development.md).
+
+### Quick Start
+
+#### 1) Initialize gc-tree
+
+```bash
+gctree init
+```
+
+This command:
+
+- creates `~/.gctree`
+- creates the default `main` gc-branch
+- asks which provider mode you want to use (`claude-code`, `codex`, or `both`)
+- if you choose `both`, asks which provider should start onboarding now
+- asks which language the workflow should use (`English`, `Korean`, or a custom language)
+- saves provider mode, onboarding provider, and language in `~/.gctree/settings.json`
+- scaffolds the current environment for the selected provider mode
+- launches guided onboarding for the active gc-branch when `main` is still empty
+
+#### 2) Resolve the active context
+
+```bash
+gctree resolve --query "auth token rotation"
+```
+
+If the current repo is outside the mapped scope for the chosen gc-branch, `gctree` can ask whether to:
+
+1. continue once
+2. always use this gc-branch for this repo
+3. ignore this gc-branch for this repo
+
+Choosing 2 or 3 updates `~/.gctree/branch-repo-map.json`.
+
+#### 3) Create another gc-branch when you need a separate context tree
+
+```bash
+gctree checkout -b client-b
+```
+
+`checkout -b` creates a **new empty gc-branch**. It does not copy existing branch docs.
+
+#### 4) Onboard that empty gc-branch through the configured provider
+
+```bash
+gctree onboard
+```
+
+#### 5) Make a durable update later
+
+```bash
+gctree update-global-context
+```
+
+Short aliases:
+
+```bash
+gctree update-gc
+gctree ugc
+```
+
+If a repo turns out to belong to the current gc-branch after real work, the natural flow is:
+
+1. allow that repo in the branch repo map
+2. then run `gctree update-global-context` to add durable context about what that repo is and why it matters
+
+#### 6) Re-onboard only after resetting a gc-branch
+
+```bash
+gctree reset-gc-branch --branch client-b --yes
+```
+
+### Provider-facing commands inside the runtime
+
+After scaffolding, the visible commands are:
+
+- **Codex:** `$gc-onboard`, `$gc-update-global-context`
+- **Claude Code:** `/gc-onboard`, `/gc-update-global-context`
+
+Those commands should always mention the current active gc-branch before gathering or updating durable context, and they should keep using the saved workflow language unless the user explicitly asks to switch.
+
+### Core commands at a glance
+
+| Goal | Command |
+| --- | --- |
+| Initialize gc-tree and choose a provider | `gctree init` |
+| Confirm the active gc-branch | `gctree status` |
+| Search the active context | `gctree resolve --query "..."` |
+| Show repo-scope rules | `gctree repo-map` |
+| Explicitly include/exclude a repo for a gc-branch | `gctree set-repo-scope --branch <name> --include` / `--exclude` |
+| Create or switch gc-branches | `gctree checkout <branch>` / `gctree checkout -b <branch>` |
+| Guided onboarding for an empty gc-branch | `gctree onboard` |
+| Guided durable update for the active gc-branch | `gctree update-global-context` / `gctree update-gc` / `gctree ugc` |
+| Reset a gc-branch before re-onboarding | `gctree reset-gc-branch --branch <name> --yes` |
+| Scaffold another environment manually | `gctree scaffold --host codex --target /path/to/repo` |
+
+## Documentation
+
+Detailed docs live in the [`docs/`](docs) directory.
+
+- **Concept** — [`docs/concept.md`](docs/concept.md)  
+  Learn what `gctree` is, which problem it solves, and what belongs in the global-context layer.
+- **Principles** — [`docs/principles.md`](docs/principles.md)  
+  Read the rules behind gc-branches, repo scope, slim indexes, summary-first docs, and guided updates.
+- **Usage** — [`docs/usage.md`](docs/usage.md)  
+  See the standard CLI flow, provider-facing commands, repo-scope behavior, and integration patterns.
+- **Local development** — [`docs/local-development.md`](docs/local-development.md)  
+  Learn how to run the CLI locally and verify changes before contributing.
+
+## Contribution
+
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow and pull request checklist.
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).