@handsupmin/gc-tree 0.1.2 → 0.1.4

package/README.ko.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 로고" width="260" />
 
-## 소개
+### 프로젝트 밖까지 이어지는 글로벌 컨텍스트.
 
-`gctree`는 AI 코딩 도구를 위한 가벼운 **Global Context Tree**입니다.
-장기적으로 유지해야 하는 컨텍스트를 파일 기반으로 명시적으로 관리할 수 있게 해주며, 브랜치 단위로 분리해서 기존 워크플로에 자연스럽게 붙일 수 있습니다.
+기존 AI 도구 위에 오래 가는, 재사용 가능한 컨텍스트 레이어를 얹어보세요.
+Git 브랜치 다루듯 여러 컨텍스트를 나눠 관리할 수 있습니다.
 
-하나의 `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`을 통해 하나의 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 에이전트를 진짜 실무에 쓰기 시작하면 repo-local context만으로는 금방 한계가 옵니다.
 
-```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`를 고르면 이번 온보딩을 어느 provider로 시작할지 한 번 더 선택
-- 사용할 언어(`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.ko.md](https://github.com/handsupmin/gc-tree/blob/main/docs/local-development.ko.md)를 참고하세요.
+
+---
+
+## 자주 쓰는 흐름
 
-#### 4) 비어 있는 gc-branch를 온보딩
+### 작업 흐름이 갈라지면 새 컨텍스트 만들기
 
 ```bash
+gctree checkout -b client-b
 gctree onboard
 ```
 
-#### 5) 나중에 장기 컨텍스트 업데이트
+고객사, 제품, 마이그레이션, 특정 이니셔티브처럼 별도 맥락이 필요한 일은 gc-branch를 따로 파두면 됩니다.
+
+### 나중에 장기 컨텍스트 업데이트하기
 
 ```bash
 gctree update-global-context
 ```
 
+작업이 쌓이면 활성 gc-branch에 장기 컨텍스트를 덧붙이세요.
+
 짧은 별칭:
 
 ```bash
@@ -109,33 +103,102 @@ 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`는 그 컨텍스트를 관련 없는 것으로 판단하고 조용히 비켜날 수 있습니다. 덕분에 상관없는 컨텍스트가 엉뚱한 세션으로 새지 않습니다.
+
+즉, 여러 개의 장기 컨텍스트를 오래 들고 가면서도 매번 모든 세션에 다 끌고 들어갈 필요가 없습니다.
+
+---
+
+## 현실적인 워크플로
+
+예를 들어 이런 식으로 일한다고 해봅시다.
+
+- 공용 플랫폼 레포 하나
+- 고객사 레포 두 개
+- 사내 툴링 레포 하나
+
+`gc-tree`가 없으면 새 AI 세션을 열 때마다 다시 설명해야 합니다.
+
+- 지금 어느 고객사 얘기인지
+- 어떤 레포들이 한 묶음인지
+- 여기서 중요한 워크플로가 뭔지
+- 지금은 어떤 컨텍스트가 오히려 방해가 되는지
+
+`gc-tree`가 있으면 레인별로 컨텍스트를 따로 유지하고, 세션을 바꿔도 재사용하고, repo scope 규칙으로 불필요한 컨텍스트 유입도 막을 수 있습니다.
+
+결국 핵심은 이겁니다.
+
+> 프롬프트를 더 많이 저장하는 게 아니라,
+> **일의 단위에 맞는 컨텍스트를 올바른 레벨에서 관리하는 것.**
+
+---
+
+## 핵심 개념
+
+- **gc-branch**
+  제품, 고객사, 워크스트림, 도메인 하나를 위한 장기 컨텍스트 레인입니다.
+
+- **repo scope**
+  어떤 레포에서 이 컨텍스트를 적용할지 결정하는 규칙입니다.
+
+- **provider-guided flow**
+  JSON을 손으로 쓰는 대신, 선호하는 AI 코딩 도구를 통해 온보딩과 업데이트를 진행하는 방식입니다.
+
+- **context tree**
+  내부적으로 `gc-tree`는 브랜치 단위의 파일 기반 지식 트리로 컨텍스트를 관리합니다.
+  사용자가 체감하는 가치는 결국 프로젝트 밖까지 이어지는 재사용 가능한 컨텍스트입니다.
+
+---
+
+## 런타임에서 보이는 provider 명령
 
 스캐폴딩 이후 런타임에서 보이는 명령은 다음과 같습니다.
 
 - **Codex:** `$gc-onboard`, `$gc-update-global-context`
 - **Claude Code:** `/gc-onboard`, `/gc-update-global-context`
 
-이 명령들은 항상 현재 활성 gc-branch가 무엇인지 먼저 밝히고, 사용자가 명시적으로 바꾸라고 하지 않는 한 저장된 언어를 끝까지 유지하면서 컨텍스트를 수집하거나 업데이트해야 합니다.
+이 명령들은 항상 현재 활성 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>` |
@@ -144,23 +207,29 @@ gctree reset-gc-branch --branch client-b --yes
 | 다시 온보딩하기 전 gc-branch 초기화 | `gctree reset-gc-branch --branch <name> --yes` |
 | 다른 환경에 수동 스캐폴딩 | `gctree scaffold --host codex --target /path/to/repo` |
 
+---
+
 ## 문서
 
-자세한 문서는 [`docs/`](docs) 아래에 정리되어 있습니다.
+자세한 문서는 [`docs/`](https://github.com/handsupmin/gc-tree/tree/main/docs) 아래에 정리되어 있습니다.
 
-- **컨셉** — [`docs/concept.ko.md`](docs/concept.ko.md)  
+- **컨셉** — [`docs/concept.ko.md`](https://github.com/handsupmin/gc-tree/blob/main/docs/concept.ko.md)
   `gctree`가 무엇인지, 어떤 문제를 해결하는지, 글로벌 컨텍스트 레이어의 범위를 설명합니다.
-- **원리** — [`docs/principles.ko.md`](docs/principles.ko.md)  
+- **원리** — [`docs/principles.ko.md`](https://github.com/handsupmin/gc-tree/blob/main/docs/principles.ko.md)
   gc-branch, 레포 범위, slim index, summary-first 문서, 가이드형 업데이트 원칙을 정리합니다.
-- **사용방법** — [`docs/usage.ko.md`](docs/usage.ko.md)  
+- **사용방법** — [`docs/usage.ko.md`](https://github.com/handsupmin/gc-tree/blob/main/docs/usage.ko.md)
   표준 CLI 흐름, provider 명령, 레포 범위 동작, 통합 패턴을 안내합니다.
-- **로컬 실행방법** — [`docs/local-development.ko.md`](docs/local-development.ko.md)  
+- **로컬 실행방법** — [`docs/local-development.ko.md`](https://github.com/handsupmin/gc-tree/blob/main/docs/local-development.ko.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)를 참고하세요.

package/README.md

@@ -1,107 +1,101 @@
 # gc-tree
 
-Branch-aware global context for AI coding tools.
+<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" />
 
-## Introduction
+### Global context, beyond the project.
 
-`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.
+Attach durable, reusable context to your existing AI tools.
+Manage multiple contexts like Git branches.
 
-When a single `AGENTS.md`, `CLAUDE.md`, or prompt snippet is no longer enough, `gctree` helps you:
+[![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)
 
-- 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
+[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)
 
-## Key Features
+</div>
 
-- **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.
+Built for developers whose real work spans **multiple repos, products, clients, and workflows**.
 
-## Install & Quick Start
+`gc-tree` gives AI coding tools a reusable context layer **above the repo level**. Keep long-lived context across sessions, scope it to the right repos, and let `gc-tree` stay out of the way when the current repo is unrelated.
 
-### Install from npm
+---
 
-```bash
-npm install -g @handsupmin/gc-tree
-```
+## Why gc-tree?
 
-Or run it once without a global install:
+If you use AI agents seriously, repo-local context stops being enough.
 
-```bash
-npx @handsupmin/gc-tree init
-```
+Once your work spans multiple repos and workstreams, the usual setup starts to break:
 
-- **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).
+- durable context gets stuffed into prompts
+- unrelated context leaks into the wrong repo
+- every new session needs the same onboarding again
+- client or product knowledge lives in hidden chat history
+- switching workstreams means manually switching mental context too
 
-### Quick Start
+`gc-tree` is for the people who already use Codex, Claude Code, and other AI coding tools heavily — and want context management to stop being another manual workflow.
 
-#### 1) Initialize gc-tree
+---
 
-```bash
-gctree init
-```
+## What you get
 
-This command:
+- **Multiple durable contexts**
+  Keep separate context lanes for different products, clients, or workstreams.
 
-- 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
+- **Repo-scoped relevance**
+  Map each context to the repos where it actually belongs.
 
-#### 2) Resolve the active context
+- **Smart scope guard**
+  If you enter a repo that is not mapped yet, `gc-tree` can ask whether to continue once, always use this context here, or ignore it here.
 
-```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:
+- **Guided onboarding and updates**
+  Use Codex, Claude Code, or both to onboard and maintain context over time.
 
-1. continue once
-2. always use this gc-branch for this repo
-3. ignore this gc-branch for this repo
+- **Summary-first markdown knowledge**
+  Store reusable context in files, not hidden memory, and let tools read the short version first.
 
-Choosing 2 or 3 updates `~/.gctree/branch-repo-map.json`.
+---
 
-#### 3) Create another gc-branch when you need a separate context tree
+## Install & quick start
 
 ```bash
-gctree checkout -b client-b
+npm install -g @handsupmin/gc-tree
+gctree init
 ```
 
-`checkout -b` creates a **new empty gc-branch**. It does not copy existing branch docs.
+That is enough to get started.
+After that, keep working the way you already do — `gc-tree` adds a reusable global context lane around your normal workflow.
+
+- **CLI command:** `gctree`
+- **Requirements:** Node.js 20+
+
+For source-based development, see [docs/local-development.md](https://github.com/handsupmin/gc-tree/blob/main/docs/local-development.md).
+
+---
+
+## Common moves
 
-#### 4) Onboard that empty gc-branch through the configured provider
+### Create a new context when a workstream deserves its own lane
 
 ```bash
+gctree checkout -b client-b
 gctree onboard
 ```
 
-#### 5) Make a durable update later
+When a client, product, migration, or initiative deserves its own durable lane, give it its own gc-branch.
+
+### Update durable context later
 
 ```bash
 gctree update-global-context
 ```
 
+Refresh the active gc-branch as the work evolves.
+
 Short aliases:
 
 ```bash
@@ -109,18 +103,85 @@ gctree update-gc
 gctree ugc
 ```
 
-If a repo turns out to belong to the current gc-branch after real work, the natural flow is:
+### Resolve context when you need it
+
+```bash
+gctree resolve --query "auth token rotation"
+```
+
+Pull relevant context back into the current moment when you want it.
+
+---
+
+## Why it feels natural
+
+**Keep multiple contexts like Git branches — without babysitting them like Git branches.**
 
-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
+You can create separate contexts for:
 
-#### 6) Re-onboard only after resetting a gc-branch
+- a client
+- a product line
+- a platform team
+- a shared backend + frontend stack
+- a temporary initiative or migration
+
+Then switch between them with familiar branch-like commands:
 
 ```bash
-gctree reset-gc-branch --branch client-b --yes
+gctree checkout -b client-b
+gctree checkout main
 ```
 
-### Provider-facing commands inside the runtime
+But unlike Git, you do **not** have to manually manage that switch all the time.
+
+If the repo you are in is outside the scope of the current context, `gc-tree` can detect that and treat the context as irrelevant instead of leaking it into the wrong session.
+
+That means you can keep multiple long-lived contexts around without dragging unrelated context into every tool session.
+
+---
+
+## A realistic workflow
+
+You work across:
+
+- one shared platform repo
+- two client repos
+- one internal tooling repo
+
+Without `gc-tree`, every AI session has to be re-taught:
+
+- which client this is
+- which repos belong together
+- which workflows matter here
+- which context is irrelevant right now
+
+With `gc-tree`, you can keep separate contexts for each lane, reuse them across sessions, and let repo-scope rules prevent irrelevant context from showing up where it should not.
+
+This is the real job to be done:
+
+> not “store more prompt text,”
+> but **manage the right context at the right level of work**.
+
+---
+
+## Core concepts
+
+- **gc-branch**
+  A durable context lane for one product, client, workstream, or domain.
+
+- **repo scope**
+  Rules that decide which repos a context should apply to.
+
+- **provider-guided flow**
+  Use your preferred AI coding tool to onboard and update context instead of hand-authoring JSON.
+
+- **context tree**
+  Under the hood, `gc-tree` organizes context as branch-aware, file-backed knowledge.
+  The “tree” is the implementation model; the user-facing benefit is reusable context beyond the project.
+
+---
+
+## Provider-facing commands inside the runtime
 
 After scaffolding, the visible commands are:
 
@@ -129,38 +190,46 @@ After scaffolding, the visible commands are:
 
 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` |
+---
+
+## 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.
+Detailed docs live in the [`docs/`](https://github.com/handsupmin/gc-tree/tree/main/docs) directory.
 
-- **Concept** — [`docs/concept.md`](docs/concept.md)  
+- **Concept** — [`docs/concept.md`](https://github.com/handsupmin/gc-tree/blob/main/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)  
+- **Principles** — [`docs/principles.md`](https://github.com/handsupmin/gc-tree/blob/main/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)  
+- **Usage** — [`docs/usage.md`](https://github.com/handsupmin/gc-tree/blob/main/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)  
+- **Local development** — [`docs/local-development.md`](https://github.com/handsupmin/gc-tree/blob/main/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.
+Contributions are welcome. See [CONTRIBUTING.md](https://github.com/handsupmin/gc-tree/blob/main/CONTRIBUTING.md) for the development workflow and pull request checklist.
+
+---
 
 ## License
 
-MIT. See [`LICENSE`](LICENSE).
+MIT. See [`LICENSE`](https://github.com/handsupmin/gc-tree/blob/main/LICENSE).