@handsupmin/gc-tree 0.1.2 → 0.1.4

package/README.es.md

@@ -1,107 +1,101 @@
 # gc-tree
 
-Una capa de contexto global con ramas para herramientas de programación con IA.
+<div align="center">
 
-[English](README.md) | [한국어](README.ko.md) | [简体中文](README.zh.md) | [日本語](README.ja.md) | [Español](README.es.md)
+<img src="./logo.png" alt="logo de gc-tree" width="260" />
 
-## Introducción
+### Contexto global, más allá del proyecto.
 
-`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.
+Añade a tus herramientas de IA una capa de contexto reutilizable y duradera.
+Gestiona varios contextos con la misma naturalidad con la que manejas ramas de Git.
 
-Cuando un solo `AGENTS.md`, `CLAUDE.md` o fragmento de prompt ya no alcanza, `gctree` te ayuda a:
+[![npm version](https://img.shields.io/npm/v/%40handsupmin%2Fgc-tree)](https://www.npmjs.com/package/@handsupmin/gc-tree)
+[![npm downloads](https://img.shields.io/npm/dm/%40handsupmin%2Fgc-tree)](https://www.npmjs.com/package/@handsupmin/gc-tree)
+[![GitHub stars](https://img.shields.io/github/stars/handsupmin/gc-tree)](https://github.com/handsupmin/gc-tree/stargazers)
+[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](https://github.com/handsupmin/gc-tree/blob/main/LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
 
-- 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
+[English](https://github.com/handsupmin/gc-tree/blob/main/README.md) | [한국어](https://github.com/handsupmin/gc-tree/blob/main/README.ko.md) | [简体中文](https://github.com/handsupmin/gc-tree/blob/main/README.zh.md) | [日本語](https://github.com/handsupmin/gc-tree/blob/main/README.ja.md) | [Español](https://github.com/handsupmin/gc-tree/blob/main/README.es.md)
 
-## Características rápidas
+</div>
 
-- **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.
+Hecho para quienes trabajan de verdad entre varios repositorios, productos, clientes y flujos de trabajo.
 
-## Instalación y guía rápida
+`gc-tree` añade a tus herramientas de programación con IA una **capa de contexto reutilizable por encima del repo**. Conserva el contexto que dura, lo aplica solo donde corresponde y se aparta cuando el repositorio actual no tiene nada que ver.
 
-### Instalar desde npm
+---
 
-```bash
-npm install -g @handsupmin/gc-tree
-```
+## Por qué gc-tree
 
-Si solo quieres ejecutarlo una vez sin instalación global:
+En cuanto empiezas a usar agentes de IA en trabajo real, el contexto local al repositorio se queda corto enseguida.
 
-```bash
-npx @handsupmin/gc-tree init
-```
+Cuando tu día a día se reparte entre varios repos y varias líneas de trabajo, suelen aparecer los mismos problemas:
 
-- **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).
+- el contexto duradero acaba metido a la fuerza en los prompts
+- el contexto que no toca se cuela en repositorios donde no debería
+- cada sesión nueva obliga a repetir la misma explicación
+- el conocimiento de cliente o producto vive escondido en el historial del chat
+- cambiar de workstream significa cambiar de contexto a mano, en tu propia cabeza
 
-### Inicio rápido
+`gc-tree` está pensado para gente que ya usa a fondo herramientas como Codex o Claude Code y no quiere seguir gestionando el contexto como una tarea manual más.
 
-#### 1) Inicializa gc-tree
+---
 
-```bash
-gctree init
-```
+## Qué te da
 
-Este comando:
+- **Varios contextos duraderos**
+  Puedes mantener carriles separados por producto, cliente o workstream.
 
-- 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
+- **Relevancia acotada por repositorio**
+  Puedes decidir con claridad qué contexto debe aplicarse solo a qué repos.
 
-#### 2) Resuelve el contexto activo
+- **Protección de alcance más inteligente**
+  Si entras en un repo todavía no asociado, puedes elegir si seguir solo esta vez, usar siempre ese contexto ahí o ignorarlo en ese repo.
 
-```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:
+- **Onboarding y actualizaciones guiadas**
+  Puedes crear y mantener el contexto con Codex, Claude Code o ambos.
 
-1. continuar solo esta vez
-2. usar siempre este gc-branch en este repo
-3. ignorar este gc-branch en este repo
+- **Conocimiento en markdown, con enfoque summary-first**
+  El contexto vive en archivos visibles, no en memoria oculta, y las herramientas pueden leer primero el resumen corto.
 
-Si eliges 2 o 3, `~/.gctree/branch-repo-map.json` se actualiza.
+---
 
-#### 3) Crea otro gc-branch si necesitas un contexto separado
+## Instalación y arranque rápido
 
 ```bash
-gctree checkout -b client-b
+npm install -g @handsupmin/gc-tree
+gctree init
 ```
 
-`checkout -b` crea un **gc-branch vacío nuevo**. No copia los documentos de otra rama.
+Con eso ya puedes arrancar.
+A partir de ahí, sigue trabajando como siempre: `gc-tree` simplemente añade una capa de contexto global reutilizable alrededor de tu flujo habitual.
+
+- **Comando CLI:** `gctree`
+- **Requisito:** Node.js 20+
+
+Si quieres trabajar desde el código fuente, consulta [docs/local-development.es.md](https://github.com/handsupmin/gc-tree/blob/main/docs/local-development.es.md).
+
+---
+
+## Movimientos habituales
 
-#### 4) Haz onboarding de un gc-branch vacío
+### Crea un contexto nuevo cuando un workstream merezca su propio carril
 
 ```bash
+gctree checkout -b client-b
 gctree onboard
 ```
 
-#### 5) Actualiza el contexto duradero más adelante
+Si un cliente, un producto, una migración o una iniciativa concreta necesita su propio contexto duradero, dale su propio gc-branch.
+
+### Actualiza después el contexto duradero
 
 ```bash
 gctree update-global-context
 ```
 
+A medida que el trabajo avanza, añade al gc-branch activo lo que merece quedarse a largo plazo.
+
 Alias cortos:
 
 ```bash
@@ -109,18 +103,85 @@ gctree update-gc
 gctree ugc
 ```
 
-Si al trabajar descubres que un repo realmente pertenece al gc-branch actual, el flujo natural es:
+### Resuelve el contexto cuando de verdad lo necesites
+
+```bash
+gctree resolve --query "auth token rotation"
+```
 
-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
+Trae de vuelta el contexto relevante justo en el momento en que hace falta.
 
-#### 6) Restablece un gc-branch antes de volver a hacer onboarding
+---
+
+## Por qué se siente natural
+
+**Puedes manejar varios contextos como si fueran ramas de Git, pero sin tener que vivir pendiente de ellos.**
+
+Puedes separar contextos para:
+
+- un cliente
+- una línea de producto
+- un equipo de plataforma
+- un stack compartido de backend + frontend
+- una iniciativa temporal o una migración
+
+Y moverte entre ellos con comandos familiares:
 
 ```bash
-gctree reset-gc-branch --branch client-b --yes
+gctree checkout -b client-b
+gctree checkout main
 ```
 
-### Comandos visibles dentro del runtime
+Pero, a diferencia de Git, no tienes que vigilar ese cambio manualmente todo el tiempo.
+
+Si el repo en el que estás queda fuera del alcance del contexto activo, `gc-tree` puede tratar ese contexto como irrelevante en lugar de dejar que se cuele en la sesión equivocada.
+
+Eso te permite mantener varios contextos a largo plazo sin arrastrarlos todos a cada sesión de trabajo.
+
+---
+
+## Un flujo de trabajo realista
+
+Imagina que trabajas entre:
+
+- un repo compartido de plataforma
+- dos repos de cliente
+- un repo de tooling interno
+
+Sin `gc-tree`, cada sesión nueva con IA obliga a volver a explicar:
+
+- de qué cliente estamos hablando ahora
+- qué repos forman realmente un mismo conjunto
+- qué flujo importa en este contexto
+- qué contexto sobra y solo mete ruido
+
+Con `gc-tree`, puedes mantener contextos separados por carril, reutilizarlos entre sesiones y dejar que las reglas de repo scope bloqueen el contexto que no toca.
+
+Ese es el trabajo real que resuelve:
+
+> no “guardar más texto de prompt”,
+> sino **gestionar el contexto correcto en el nivel correcto del trabajo**.
+
+---
+
+## Conceptos clave
+
+- **gc-branch**
+  Un carril de contexto duradero para un producto, cliente, workstream o dominio.
+
+- **repo scope**
+  Las reglas que deciden en qué repositorios debe aplicarse un contexto.
+
+- **provider-guided flow**
+  En vez de escribir JSON a mano, haces onboarding y actualizaciones desde tu herramienta de IA preferida.
+
+- **context tree**
+  Por dentro, `gc-tree` organiza el contexto como conocimiento en archivos, consciente de las ramas.
+  Lo que tú ganas es contexto reutilizable más allá de un solo proyecto.
+
+---
+
+## Comandos visibles dentro del runtime
 
 Después del scaffold, los comandos visibles son:
 
@@ -129,7 +190,9 @@ Después del scaffold, los comandos visibles son:
 
 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
+---
+
+## Comandos clave de un vistazo
 
 | Objetivo | Comando |
 | --- | --- |
@@ -144,23 +207,29 @@ Esos comandos deben dejar claro cuál es el gc-branch activo antes de empezar a
 | 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).
+La documentación detallada está en el directorio [`docs/`](https://github.com/handsupmin/gc-tree/tree/main/docs).
 
-- **Concepto** — [`docs/concept.es.md`](docs/concept.es.md)  
+- **Concepto** — [`docs/concept.es.md`](https://github.com/handsupmin/gc-tree/blob/main/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)  
+- **Principios** — [`docs/principles.es.md`](https://github.com/handsupmin/gc-tree/blob/main/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)  
+- **Uso** — [`docs/usage.es.md`](https://github.com/handsupmin/gc-tree/blob/main/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)  
+- **Desarrollo local** — [`docs/local-development.es.md`](https://github.com/handsupmin/gc-tree/blob/main/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.
+Las contribuciones son bienvenidas. Consulta el documento en inglés [CONTRIBUTING.md](https://github.com/handsupmin/gc-tree/blob/main/CONTRIBUTING.md) para ver el flujo de desarrollo y la checklist de PR.
+
+---
 
 ## Licencia
 
-MIT. Consulta [`LICENSE`](LICENSE).
+MIT. Consulta [`LICENSE`](https://github.com/handsupmin/gc-tree/blob/main/LICENSE).

package/README.ja.md

@@ -1,107 +1,101 @@
 # gc-tree
 
-AI コーディングツール向けのブランチ対応グローバルコンテキストレイヤー。
+<div align="center">
 
-[English](README.md) | [한국어](README.ko.md) | [简体中文](README.zh.md) | [日本語](README.ja.md) | [Español](README.es.md)
+<img src="./logo.png" alt="gc-tree logo" width="260" />
 
-## 紹介
+### プロジェクトの外まで届くグローバルコンテキスト。
 
-`gctree` は AI コーディングツール向けの軽量な **Global Context Tree** です。
-長期的なコンテキストに、ファイルベースで再利用しやすく、ブランチ単位で切り替えられる明確な置き場所を与え、既存のワークフローにも自然に組み込めます。
+今使っている AI ツールに、長く使える再利用可能なコンテキストレイヤーを重ねましょう。
+Git のブランチ感覚で、複数のコンテキストを分けて持てます。
 
-1 つの `AGENTS.md`、`CLAUDE.md`、あるいは短いプロンプト断片だけでは足りなくなったとき、`gctree` は次のことを助けます。
+[![npm version](https://img.shields.io/npm/v/%40handsupmin%2Fgc-tree)](https://www.npmjs.com/package/@handsupmin/gc-tree)
+[![npm downloads](https://img.shields.io/npm/dm/%40handsupmin%2Fgc-tree)](https://www.npmjs.com/package/@handsupmin/gc-tree)
+[![GitHub stars](https://img.shields.io/github/stars/handsupmin/gc-tree)](https://github.com/handsupmin/gc-tree/stargazers)
+[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](https://github.com/handsupmin/gc-tree/blob/main/LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
 
-- プロダクト、クライアント、作業トラックごとにコンテキストを分ける
-- 隠れたメモリではなく、markdown 文書を source of truth として管理する
-- 小さなインデックスと summary-first ドキュメントで必要なコンテキストを素早く見つける
-- 好みの LLM CLI を使ってオンボーディングと永続更新を進める
-- ある gc-branch が本当に関係するリポジトリでだけ使われるようにする
+[English](https://github.com/handsupmin/gc-tree/blob/main/README.md) | [한국어](https://github.com/handsupmin/gc-tree/blob/main/README.ko.md) | [简体中文](https://github.com/handsupmin/gc-tree/blob/main/README.zh.md) | [日本語](https://github.com/handsupmin/gc-tree/blob/main/README.ja.md) | [Español](https://github.com/handsupmin/gc-tree/blob/main/README.es.md)
 
-## 簡単な特徴
+</div>
 
-- **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 フローでグローバルコンテキストを更新できます。
+日々の仕事が複数のリポジトリ、プロダクト、クライアント、ワークフローにまたがっている開発者のために作りました。
 
-## インストールとクイックスタート
+`gc-tree` は、AI コーディングツールに **リポジトリの外側で再利用できるコンテキストレイヤー** を足してくれます。長く使う前提の文脈は残しつつ、関係あるリポジトリにだけ効かせ、無関係な場所では静かに引っ込みます。
 
-### npm からインストール
+---
 
-```bash
-npm install -g @handsupmin/gc-tree
-```
+## なぜ gc-tree なのか
 
-グローバルインストールなしで一度だけ実行する場合:
+AI エージェントを本気で実務に入れると、リポジトリローカルのコンテキストだけではすぐ足りなくなります。
 
-```bash
-npx @handsupmin/gc-tree init
-```
+作業が複数のリポジトリやワークストリームに広がると、たとえばこんなことが起きがちです。
 
-- **パッケージ名:** `@handsupmin/gc-tree`
-- **CLI コマンド:** `gctree`
-- **要件:** Node.js 20+
-ソースベースの開発は [docs/local-development.md](docs/local-development.md) を参照してください。
+- 長期コンテキストがプロンプトの中に押し込まれていく
+- 無関係な文脈が別のリポジトリまで漏れてしまう
+- 新しいセッションを開くたびに同じ説明をやり直すことになる
+- クライアントやプロダクトの知識がチャット履歴の中に埋もれる
+- 作業を切り替えるたびに頭の中で手動で文脈を切り替える必要がある
 
-### クイックスタート
+`gc-tree` は、Codex や Claude Code のような AI コーディングツールをすでにしっかり使っていて、コンテキスト管理まで手作業で回したくない人のための道具です。
 
-#### 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` は次を選ばせます。
+- **ガイド付きでオンボードと更新ができる**
+  Codex、Claude Code、あるいは両方を使いながら、コンテキストを育てていけます。
 
-1. 今回だけ続行する
-2. 今後もこのリポジトリでこの gc-branch を使う
-3. このリポジトリではこの gc-branch を無視する
+- **summary-first の markdown ナレッジとして残せる**
+  隠れたメモリではなくファイルに残し、ツールにはまず短い要約から読ませられます。
 
-2 または 3 を選ぶと `~/.gctree/branch-repo-map.json` が更新されます。
+---
 
-#### 3) 別のコンテキストが必要なら新しい gc-branch を作る
+## インストール & クイックスタート
 
 ```bash
-gctree checkout -b client-b
+npm install -g @handsupmin/gc-tree
+gctree init
 ```
 
-`checkout -b` は**新しい空の gc-branch**を作ります。既存のブランチ文書はコピーしません。
+これでスタート準備は完了です。
+あとはいつもどおり開発を進めれば大丈夫。`gc-tree` が普段の流れにグローバルコンテキストのレーンを足してくれます。
+
+- **CLI コマンド:** `gctree`
+- **要件:** Node.js 20+
+
+ソースから試す場合は [docs/local-development.ja.md](https://github.com/handsupmin/gc-tree/blob/main/docs/local-development.ja.md) を参照してください。
+
+---
+
+## よく使う流れ
 
-#### 4) 空の gc-branch をオンボードする
+### 作業に専用レーンが欲しくなったら新しいコンテキストを切る
 
 ```bash
+gctree checkout -b client-b
 gctree onboard
 ```
 
-#### 5) 後から永続コンテキストを更新する
+クライアント、プロダクト、移行案件、期間限定の施策など、文脈を分けておきたい仕事は gc-branch を切っておくと楽です。
+
+### 後から長期コンテキストを育てる
 
 ```bash
 gctree update-global-context
 ```
 
+作業が進んだら、アクティブな gc-branch に長く効く文脈を足していきます。
+
 短い別名:
 
 ```bash
@@ -109,18 +103,85 @@ gctree update-gc
 gctree ugc
 ```
 
-実際に作業してみて、そのリポジトリが現在の gc-branch に属するべきだと分かった場合は、自然な流れはこうです。
+### 必要になったタイミングでコンテキストを引く
+
+```bash
+gctree resolve --query "auth token rotation"
+```
 
-1. まずそのリポジトリを branch repo map に追加する
-2. その後 `gctree update-global-context` を実行して、そのリポジトリが何を担うのか、なぜ重要なのかといった長期コンテキストを追加する
+必要な瞬間だけ、関係ある文脈を呼び戻せば十分です。
 
-#### 6) 再オンボーディングの前に gc-branch をリセットする
+---
+
+## しっくりくる理由
+
+**Git のブランチみたいに複数のコンテキストを持てるのに、Git のブランチみたいに逐一面倒を見る必要はありません。**
+
+たとえば次のようにコンテキストを分けられます。
+
+- クライアントごと
+- プロダクトラインごと
+- プラットフォームチームごと
+- バックエンドとフロントエンドをまとめた共有スタック
+- 一時的な施策や移行プロジェクト
+
+そして、ブランチ感覚のコマンドで行き来できます。
 
 ```bash
-gctree reset-gc-branch --branch client-b --yes
+gctree checkout -b client-b
+gctree checkout main
 ```
 
-### ランタイムで見える provider コマンド
+ただし Git と違って、その切り替えを常に人が意識して管理する必要はありません。
+
+今いるリポジトリが現在のコンテキストのスコープ外なら、`gc-tree` はその文脈を「今は関係ないもの」として扱えます。だから、無関係なコンテキストが別のセッションに混ざり込みません。
+
+その結果、長く使うコンテキストを複数抱えたままでも、毎回すべてを全部のセッションに持ち込まずに済みます。
+
+---
+
+## 現実的なワークフロー
+
+たとえば、こんな構成で仕事をしているとします。
+
+- 共通のプラットフォームリポジトリが 1 つ
+- クライアント向けリポジトリが 2 つ
+- 社内ツール用リポジトリが 1 つ
+
+`gc-tree` がないと、新しい AI セッションを開くたびに説明し直すことになります。
+
+- 今どのクライアントの話なのか
+- どのリポジトリ同士がひとまとまりなのか
+- ここで重要なワークフローは何か
+- 今はどの文脈がむしろノイズになるのか
+
+`gc-tree` があれば、レーンごとにコンテキストを持ち分けて、セッションをまたいで再利用し、repo scope のルールで不要な文脈の流入も防げます。
+
+要するに、本当にやりたいのはこういうことです。
+
+> プロンプトをもっと溜め込むことではなく、
+> **仕事の単位に合ったコンテキストを、正しいレイヤーで管理すること。**
+
+---
+
+## コア概念
+
+- **gc-branch**
+  1 つのプロダクト、クライアント、ワークストリーム、ドメインのための長期コンテキストレーンです。
+
+- **repo scope**
+  そのコンテキストをどのリポジトリで効かせるかを決めるルールです。
+
+- **provider-guided flow**
+  JSON を手で書く代わりに、好みの AI コーディングツールでオンボードと更新を進める流れです。
+
+- **context tree**
+  `gc-tree` は内部的には、ブランチを意識したファイルベースの知識ツリーとしてコンテキストを整理します。
+  ユーザーが得る価値は、プロジェクトの外までつながる再利用可能なコンテキストです。
+
+---
+
+## ランタイムで見える provider コマンド
 
 scaffold 後に見えるコマンドは次の通りです。
 
@@ -129,38 +190,46 @@ scaffold 後に見えるコマンドは次の通りです。
 
 これらのコマンドは、長期コンテキストを集めたり更新したりする前に、現在の gc-branch を必ず明示し、ユーザーが明示的に切り替えを求めない限り、保存された言語を最後まで維持するべきです。
 
-### 主要コマンド一覧
+---
+
+## 主要コマンド一覧
 
 | 目的 | コマンド |
 | --- | --- |
 | gc-tree を初期化して provider を選ぶ | `gctree init` |
 | 現在の gc-branch を確認する | `gctree status` |
-| 現在のコンテキストを検索する | `gctree resolve --query "..."` |
+| アクティブなコンテキストを検索する | `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 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 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/`](https://github.com/handsupmin/gc-tree/tree/main/docs) にまとまっています。
 
-- **コンセプト** — [`docs/concept.ja.md`](docs/concept.ja.md)  
+- **コンセプト** — [`docs/concept.ja.md`](https://github.com/handsupmin/gc-tree/blob/main/docs/concept.ja.md)
   `gctree` が何であり、どの課題を解決し、どこまでを担当するのかを説明します。
-- **原則** — [`docs/principles.ja.md`](docs/principles.ja.md)  
+- **原則** — [`docs/principles.ja.md`](https://github.com/handsupmin/gc-tree/blob/main/docs/principles.ja.md)
   gc-branch、リポジトリ範囲、summary-first 文書、ガイド付き更新の考え方をまとめています。
-- **使い方** — [`docs/usage.ja.md`](docs/usage.ja.md)  
+- **使い方** — [`docs/usage.ja.md`](https://github.com/handsupmin/gc-tree/blob/main/docs/usage.ja.md)
   標準 CLI フロー、provider コマンド、リポジトリ範囲の挙動、統合パターンを案内します。
-- **ローカル実行方法** — [`docs/local-development.ja.md`](docs/local-development.ja.md)  
+- **ローカル実行方法** — [`docs/local-development.ja.md`](https://github.com/handsupmin/gc-tree/blob/main/docs/local-development.ja.md)
   依存関係のインストール、CLI のローカル実行、変更確認手順を説明します。
 
+---
+
 ## コントリビュート
 
-コントリビューション歓迎です。開発フローと PR チェックリストは英語ドキュメントの [CONTRIBUTING.md](CONTRIBUTING.md) を参照してください。
+コントリビューション歓迎です。開発フローと PR チェックリストは英語ドキュメントの [CONTRIBUTING.md](https://github.com/handsupmin/gc-tree/blob/main/CONTRIBUTING.md) を参照してください。
+
+---
 
 ## ライセンス
 
-MIT。詳細は [`LICENSE`](LICENSE) を参照してください。
+MIT。詳細は [`LICENSE`](https://github.com/handsupmin/gc-tree/blob/main/LICENSE) を参照してください。