@handsupmin/gc-tree 0.2.0 → 0.3.0

package/README.es.md

@@ -36,6 +36,39 @@ Esto no es un problema de IA. Es un **problema de gestión del contexto**.
 
 ---
 
+## Para quién es esto
+
+Sacarás más partido a `gc-tree` si:
+
+- Trabajas en **múltiples repositorios** (equipos con monorepo, repos de plataforma + cliente, stacks de backend + frontend)
+- Cambias entre **múltiples productos o clientes** en la misma semana
+- Te encuentras **explicando el mismo contexto** al inicio de cada sesión de IA
+- Quieres que tus herramientas de IA entiendan tus **convenciones, arquitectura y conocimiento de dominio** — no solo el archivo actual
+
+Si solo trabajas en un repositorio y un producto, no necesitas esto. `CLAUDE.md` o `.cursorrules` es suficiente.
+
+---
+
+## Instalación y arranque rápido
+
+```bash
+npm install -g @handsupmin/gc-tree
+gctree init
+```
+
+`gctree init` te guía a través de:
+
+1. Elegir provider: `claude-code`, `codex` o `both`
+2. Instalar los archivos de integración en el repositorio actual
+3. Completar el onboarding guiado para el gc-branch `main`
+
+Después, tu herramienta de IA instala integración real de hooks SessionStart/UserPromptSubmit: revisa gc-tree automáticamente antes de trabajar y cachea resultados vacíos/no-match durante la sesión.
+
+- **CLI:** `gctree`
+- **Requisito:** Node.js 20+
+
+---
+
 ## Qué hace gc-tree
 
 `gc-tree` opera **por encima del nivel del repositorio**. Almacena contexto en archivos Markdown estructurados y permite que tus herramientas de IA traigan solo lo relevante antes de cada sesión, de forma automática.
@@ -64,34 +97,21 @@ Tu herramienta de IA recibe el contexto correcto — no toda la base de conocimi
 
 ---
 
-## Para quién es esto
-
-Sacarás más partido a `gc-tree` si:
-
-- Trabajas en **múltiples repositorios** (equipos con monorepo, repos de plataforma + cliente, stacks de backend + frontend)
-- Cambias entre **múltiples productos o clientes** en la misma semana
-- Te encuentras **explicando el mismo contexto** al inicio de cada sesión de IA
-- Quieres que tus herramientas de IA entiendan tus **convenciones, arquitectura y conocimiento de dominio** — no solo el archivo actual
-
-Si solo trabajas en un repositorio y un producto, no necesitas esto. `CLAUDE.md` o `.cursorrules` es suficiente.
-
----
-
 ## ¿En qué se diferencia de CLAUDE.md o cursor rules?
 
 `CLAUDE.md` es genial — para un solo repositorio.
 
 En el momento en que tienes múltiples repos, clientes o workstreams:
 
-| | `CLAUDE.md` / cursor rules | `gc-tree` |
-|---|---|---|
-| Alcance | Un repositorio | Múltiples repos, un contexto |
-| Persistencia | Archivo dentro del repo | Almacenado fuera, reutilizable entre sesiones |
-| Cambio de contexto | Edición manual de archivos | `gctree checkout client-b` |
-| Filtrado por relevancia | Todo o nada | Solo inyecta docs coincidentes (~4%) |
-| Onboarding | Escrito a mano | Guiado por tu herramienta de IA |
-| Compatible con Codex | ✅ | ✅ |
-| Compatible con Claude Code | ✅ | ✅ |
+|                            | `CLAUDE.md` / cursor rules | `gc-tree`                                     |
+| -------------------------- | -------------------------- | --------------------------------------------- |
+| Alcance                    | Un repositorio             | Múltiples repos, un contexto                  |
+| Persistencia               | Archivo dentro del repo    | Almacenado fuera, reutilizable entre sesiones |
+| Cambio de contexto         | Edición manual de archivos | `gctree checkout client-b`                    |
+| Filtrado por relevancia    | Todo o nada                | Solo inyecta docs coincidentes (~4%)          |
+| Onboarding                 | Escrito a mano             | Guiado por tu herramienta de IA               |
+| Compatible con Codex       | ✅                         | ✅                                            |
+| Compatible con Claude Code | ✅                         | ✅                                            |
 
 ---
 
@@ -99,13 +119,13 @@ En el momento en que tienes múltiples repos, clientes o workstreams:
 
 Probado con documentación interna real (4 exportaciones de Notion, consultas mixtas en español e inglés):
 
-| Métrica | Resultado |
-|---|---|
+| Métrica                                                      | Resultado        |
+| ------------------------------------------------------------ | ---------------- |
 | Recall — consultas relevantes que encuentran el doc correcto | **100%** (16/16) |
-| Precision — consultas irrelevantes que devuelven vacío | **80%** (4/5) |
-| F1 score | **88.9%** |
-| Tokens inyectados por consulta vs. contexto total | **~4%** |
-| Compatible con consultas mixtas en varios idiomas | ✅ |
+| Precision — consultas irrelevantes que devuelven vacío       | **80%** (4/5)    |
+| F1 score                                                     | **88.9%**        |
+| Tokens inyectados por consulta vs. contexto total            | **~4%**          |
+| Compatible con consultas mixtas en varios idiomas            | ✅               |
 
 ---
 
@@ -133,25 +153,6 @@ gctree resolve --query 'NestJS DTO plainToInstance'
 
 ---
 
-## Instalación y arranque rápido
-
-```bash
-npm install -g @handsupmin/gc-tree
-gctree init
-```
-
-`gctree init` te guía a través de:
-1. Elegir provider: `claude-code`, `codex` o `both`
-2. Instalar los archivos de integración en el repositorio actual
-3. Completar el onboarding guiado para el gc-branch `main`
-
-Después, tu herramienta de IA aprenderá a llamar a `gctree resolve` antes de planificar o implementar.
-
-- **CLI:** `gctree`
-- **Requisito:** Node.js 20+
-
----
-
 ## Movimientos habituales
 
 ### Contextos separados para workstreams distintos
@@ -214,19 +215,19 @@ El contexto vive fuera de tus repositorios — sin reglas de `.gitignore`, sin c
 
 ## Comandos principales
 
-| 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 "..."` |
-| Crear o cambiar gc-branches | `gctree checkout <branch>` / `gctree checkout -b <branch>` |
-| Listar todos los gc-branches | `gctree branches` |
-| Onboarding guiado de un gc-branch vacío | `gctree onboard` |
-| Actualización guiada del gc-branch activo | `gctree update-global-context` / `gctree ugc` |
-| Ver reglas de alcance por repo | `gctree repo-map` |
+| 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 "..."`                                  |
+| Crear o cambiar gc-branches                        | `gctree checkout <branch>` / `gctree checkout -b <branch>`      |
+| Listar todos los gc-branches                       | `gctree branches`                                               |
+| Onboarding guiado de un gc-branch vacío            | `gctree onboard`                                                |
+| Actualización guiada del gc-branch activo          | `gctree update-global-context` / `gctree ugc`                   |
+| Ver reglas de alcance por repo                     | `gctree repo-map`                                               |
 | Incluir o excluir el repo actual para un gc-branch | `gctree set-repo-scope --branch <name> --include` / `--exclude` |
-| Resetear un gc-branch antes de re-onboard | `gctree reset-gc-branch --branch <name> --yes` |
-| Instalar scaffold en un nuevo entorno | `gctree scaffold --host codex --target /path/to/repo` |
+| Resetear un gc-branch antes de re-onboard          | `gctree reset-gc-branch --branch <name> --yes`                  |
+| Instalar scaffold en un nuevo entorno              | `gctree scaffold --host codex --target /path/to/repo`           |
 
 ---
 

package/README.ja.md

@@ -36,6 +36,39 @@ Claude Code や Codex を毎日使っています。でも実際の仕事は複
 
 ---
 
+## こんな人に向いています
+
+以下に当てはまるなら、gc-tree が一番よく効きます：
+
+- **複数のリポジトリ**にまたがって仕事をしている（モノレポチーム、プラットフォーム + クライアントリポジトリ、バックエンド + フロントエンドスタック）
+- 同じ週に**複数のプロダクトやクライアント**を行き来している
+- AI セッションを開くたびに**同じコンテキストを繰り返し説明**している
+- AI ツールに今のファイルだけでなく**規約・アーキテクチャ・ドメイン知識**まで理解してほしい
+
+リポジトリ一つ、プロダクト一つで完結するなら、このツールは必要ありません。`CLAUDE.md` や `.cursorrules` で十分です。
+
+---
+
+## インストール & クイックスタート
+
+```bash
+npm install -g @handsupmin/gc-tree
+gctree init
+```
+
+`gctree init` が次のことを案内してくれます：
+
+1. プロバイダーの選択：`claude-code`、`codex`、または `both`
+2. 現在のリポジトリへの統合ファイルのインストール
+3. `main` gc-branch のガイド付きオンボーディング実行
+
+その後は、AI ツールに実際の SessionStart / UserPromptSubmit フック統合が入り、作業前に gc-tree を自動確認し、空結果や no-match をセッション中キャッシュします。
+
+- **CLI：** `gctree`
+- **動作条件：** Node.js 20+
+
+---
+
 ## gc-tree がやること
 
 `gc-tree` は**リポジトリより上のレイヤー**に位置します。コンテキストを構造化された Markdown ファイルに保存し、AI ツールがセッションのたびに関連するものだけを自動で引き出せるようにします。
@@ -64,34 +97,21 @@ AI ツールに渡るのは正しいコンテキスト——ナレッジベー
 
 ---
 
-## こんな人に向いています
-
-以下に当てはまるなら、gc-tree が一番よく効きます：
-
-- **複数のリポジトリ**にまたがって仕事をしている（モノレポチーム、プラットフォーム + クライアントリポジトリ、バックエンド + フロントエンドスタック）
-- 同じ週に**複数のプロダクトやクライアント**を行き来している
-- AI セッションを開くたびに**同じコンテキストを繰り返し説明**している
-- AI ツールに今のファイルだけでなく**規約・アーキテクチャ・ドメイン知識**まで理解してほしい
-
-リポジトリ一つ、プロダクト一つで完結するなら、このツールは必要ありません。`CLAUDE.md` や `.cursorrules` で十分です。
-
----
-
 ## CLAUDE.md や cursor rules との違いは？
 
 `CLAUDE.md` は優れています——一つのリポジトリにおいては。
 
 複数のリポジトリ・クライアント・ワークストリームが増えた瞬間：
 
-| | `CLAUDE.md` / cursor rules | `gc-tree` |
-|---|---|---|
-| スコープ | リポジトリ一つ | 複数リポジトリ、コンテキスト一つ |
-| 永続化 | リポジトリ内のファイル | リポジトリ外に保存、セッション間で再利用 |
-| コンテキスト切り替え | ファイルを手で編集 | `gctree checkout client-b` |
-| 関連性フィルタリング | 全部か何もないか | 一致したドキュメントだけ注入（約 4%） |
-| オンボーディング | 手書き | AI ツールがガイド |
-| Codex 対応 | ✅ | ✅ |
-| Claude Code 対応 | ✅ | ✅ |
+|                      | `CLAUDE.md` / cursor rules | `gc-tree`                                |
+| -------------------- | -------------------------- | ---------------------------------------- |
+| スコープ             | リポジトリ一つ             | 複数リポジトリ、コンテキスト一つ         |
+| 永続化               | リポジトリ内のファイル     | リポジトリ外に保存、セッション間で再利用 |
+| コンテキスト切り替え | ファイルを手で編集         | `gctree checkout client-b`               |
+| 関連性フィルタリング | 全部か何もないか           | 一致したドキュメントだけ注入（約 4%）    |
+| オンボーディング     | 手書き                     | AI ツールがガイド                        |
+| Codex 対応           | ✅                         | ✅                                       |
+| Claude Code 対応     | ✅                         | ✅                                       |
 
 ---
 
@@ -99,13 +119,13 @@ AI ツールに渡るのは正しいコンテキスト——ナレッジベー
 
 実際の社内ドキュメントでテスト（Notion エクスポート 4 件、日本語・英語混合クエリ）：
 
-| 指標 | 結果 |
-|---|---|
+| 指標                                         | 結果              |
+| -------------------------------------------- | ----------------- |
 | Recall——関連クエリが正しい文書を見つける割合 | **100%**（16/16） |
-| Precision——無関係なクエリが空を返す割合 | **80%**（4/5） |
-| F1 スコア | **88.9%** |
-| クエリあたりの注入トークン割合（全体比） | **約 4%** |
-| 日英混合クエリ対応 | ✅ |
+| Precision——無関係なクエリが空を返す割合      | **80%**（4/5）    |
+| F1 スコア                                    | **88.9%**         |
+| クエリあたりの注入トークン割合（全体比）     | **約 4%**         |
+| 日英混合クエリ対応                           | ✅                |
 
 ---
 
@@ -133,25 +153,6 @@ gctree resolve --query 'NestJS DTO plainToInstance'
 
 ---
 
-## インストール & クイックスタート
-
-```bash
-npm install -g @handsupmin/gc-tree
-gctree init
-```
-
-`gctree init` が次のことを案内してくれます：
-1. プロバイダーの選択：`claude-code`、`codex`、または `both`
-2. 現在のリポジトリへの統合ファイルのインストール
-3. `main` gc-branch のガイド付きオンボーディング実行
-
-その後は、AI ツールが計画・実装の前に `gctree resolve` を呼ぶ流れを自然に覚えます。
-
-- **CLI：** `gctree`
-- **動作条件：** Node.js 20+
-
----
-
 ## よく使う流れ
 
 ### ワークストリームごとに別々のコンテキストを持つ
@@ -214,19 +215,19 @@ gctree set-repo-scope --branch client-b --exclude   # 現在のリポジトリ
 
 ## 主要コマンド
 
-| 目的 | コマンド |
-|---|---|
-| gc-tree を初期化してプロバイダーを選ぶ | `gctree init` |
-| アクティブな gc-branch を確認する | `gctree status` |
-| アクティブなコンテキストを検索する | `gctree resolve --query "..."` |
-| gc-branch を作成または切り替える | `gctree checkout <branch>` / `gctree checkout -b <branch>` |
-| 全 gc-branch を一覧表示する | `gctree branches` |
-| 空の gc-branch をガイド付きオンボーディングする | `gctree onboard` |
-| アクティブな gc-branch をガイド付き更新する | `gctree update-global-context` / `gctree ugc` |
-| リポジトリ範囲ルールを確認する | `gctree repo-map` |
+| 目的                                             | コマンド                                                        |
+| ------------------------------------------------ | --------------------------------------------------------------- |
+| gc-tree を初期化してプロバイダーを選ぶ           | `gctree init`                                                   |
+| アクティブな gc-branch を確認する                | `gctree status`                                                 |
+| アクティブなコンテキストを検索する               | `gctree resolve --query "..."`                                  |
+| gc-branch を作成または切り替える                 | `gctree checkout <branch>` / `gctree checkout -b <branch>`      |
+| 全 gc-branch を一覧表示する                      | `gctree branches`                                               |
+| 空の gc-branch をガイド付きオンボーディングする  | `gctree onboard`                                                |
+| アクティブな gc-branch をガイド付き更新する      | `gctree update-global-context` / `gctree ugc`                   |
+| リポジトリ範囲ルールを確認する                   | `gctree repo-map`                                               |
 | 現在のリポジトリを gc-branch に含める / 除外する | `gctree set-repo-scope --branch <name> --include` / `--exclude` |
-| 再オンボーディング前に gc-branch をリセットする | `gctree reset-gc-branch --branch <name> --yes` |
-| 別の環境に scaffold をインストールする | `gctree scaffold --host codex --target /path/to/repo` |
+| 再オンボーディング前に gc-branch をリセットする  | `gctree reset-gc-branch --branch <name> --yes`                  |
+| 別の環境に scaffold をインストールする           | `gctree scaffold --host codex --target /path/to/repo`           |
 
 ---
 

package/README.ko.md

@@ -36,6 +36,39 @@ Claude Code나 Codex를 매일 씁니다. 그런데 실제 업무는 여러 레
 
 ---
 
+## 이 도구가 맞는 사람
+
+다음에 해당하면 gc-tree를 제일 잘 쓸 수 있습니다:
+
+- **여러 레포**에 걸쳐 일하는 경우 (모노레포 팀, 플랫폼 + 클라이언트 레포, 백엔드 + 프론트엔드 스택)
+- 같은 주에 **여러 제품이나 고객사** 사이를 오가는 경우
+- AI 세션 시작마다 **같은 컨텍스트를 반복 설명**하는 경우
+- AI 도구가 현재 파일뿐 아니라 **컨벤션, 아키텍처, 도메인 지식**도 알길 원하는 경우
+
+레포 하나, 제품 하나에서만 일한다면 굳이 이 도구가 필요 없습니다. `CLAUDE.md`나 `.cursorrules`로 충분합니다.
+
+---
+
+## 설치 & 빠른 시작
+
+```bash
+npm install -g @handsupmin/gc-tree
+gctree init
+```
+
+`gctree init`이 안내합니다:
+
+1. 프로바이더 선택: `claude-code`, `codex`, 또는 `both`
+2. 현재 레포에 통합 파일 스캐폴딩
+3. `main` gc-branch 가이드형 온보딩 실행
+
+이후 AI 도구에 실제 SessionStart/UserPromptSubmit 훅 통합이 설치되어, 작업 전에 gc-tree를 자동 확인하고 세션 동안 빈 결과·no-match를 캐시합니다.
+
+- **CLI:** `gctree`
+- **요구 사항:** Node.js 20+
+
+---
+
 ## gc-tree가 하는 일
 
 `gc-tree`는 **레포 위 레벨**에 위치합니다. 컨텍스트를 구조화된 마크다운 파일에 저장하고, AI 도구가 매 세션마다 관련된 것만 자동으로 가져오게 합니다.
@@ -64,34 +97,21 @@ AI 도구가 올바른 컨텍스트를 가져옵니다. 지식 베이스 전체
 
 ---
 
-## 이 도구가 맞는 사람
-
-다음에 해당하면 gc-tree를 제일 잘 쓸 수 있습니다:
-
-- **여러 레포**에 걸쳐 일하는 경우 (모노레포 팀, 플랫폼 + 클라이언트 레포, 백엔드 + 프론트엔드 스택)
-- 같은 주에 **여러 제품이나 고객사** 사이를 오가는 경우
-- AI 세션 시작마다 **같은 컨텍스트를 반복 설명**하는 경우
-- AI 도구가 현재 파일뿐 아니라 **컨벤션, 아키텍처, 도메인 지식**도 알길 원하는 경우
-
-레포 하나, 제품 하나에서만 일한다면 굳이 이 도구가 필요 없습니다. `CLAUDE.md`나 `.cursorrules`로 충분합니다.
-
----
-
 ## CLAUDE.md나 cursor rules와 뭐가 다른가요?
 
 `CLAUDE.md`는 훌륭합니다 — 레포 하나에서는요.
 
 여러 레포, 고객사, 워크스트림이 생기는 순간:
 
-| | `CLAUDE.md` / cursor rules | `gc-tree` |
-|---|---|---|
-| 범위 | 레포 하나 | 여러 레포, 컨텍스트 하나 |
-| 지속성 | 레포 내 파일 | 레포 밖 저장, 세션 간 재사용 |
-| 컨텍스트 전환 | 파일 직접 수정 | `gctree checkout client-b` |
-| 관련성 필터링 | 전부 아니면 없음 | 매칭 문서만 주입 (~4%) |
-| 온보딩 | 손으로 작성 | AI 도구가 가이드 |
-| Codex 지원 | ✅ | ✅ |
-| Claude Code 지원 | ✅ | ✅ |
+|                  | `CLAUDE.md` / cursor rules | `gc-tree`                    |
+| ---------------- | -------------------------- | ---------------------------- |
+| 범위             | 레포 하나                  | 여러 레포, 컨텍스트 하나     |
+| 지속성           | 레포 내 파일               | 레포 밖 저장, 세션 간 재사용 |
+| 컨텍스트 전환    | 파일 직접 수정             | `gctree checkout client-b`   |
+| 관련성 필터링    | 전부 아니면 없음           | 매칭 문서만 주입 (~4%)       |
+| 온보딩           | 손으로 작성                | AI 도구가 가이드             |
+| Codex 지원       | ✅                         | ✅                           |
+| Claude Code 지원 | ✅                         | ✅                           |
 
 ---
 
@@ -99,13 +119,13 @@ AI 도구가 올바른 컨텍스트를 가져옵니다. 지식 베이스 전체
 
 실제 내부 문서 기준 테스트 (Notion 내보내기 4종, 한국어 + 영어 혼합 쿼리):
 
-| 지표 | 결과 |
-|---|---|
-| Recall — 관련 쿼리가 올바른 문서를 찾는 비율 | **100%** (16/16) |
-| Precision — 무관 쿼리가 빈 결과를 반환하는 비율 | **80%** (4/5) |
-| F1 점수 | **88.9%** |
-| 쿼리당 주입 토큰 비율 (전체 컨텍스트 대비) | **~4%** |
-| 한국어 + 영어 혼합 쿼리 지원 | ✅ |
+| 지표                                            | 결과             |
+| ----------------------------------------------- | ---------------- |
+| Recall — 관련 쿼리가 올바른 문서를 찾는 비율    | **100%** (16/16) |
+| Precision — 무관 쿼리가 빈 결과를 반환하는 비율 | **80%** (4/5)    |
+| F1 점수                                         | **88.9%**        |
+| 쿼리당 주입 토큰 비율 (전체 컨텍스트 대비)      | **~4%**          |
+| 한국어 + 영어 혼합 쿼리 지원                    | ✅               |
 
 ---
 
@@ -133,25 +153,6 @@ gctree resolve --query 'NestJS DTO plainToInstance'
 
 ---
 
-## 설치 & 빠른 시작
-
-```bash
-npm install -g @handsupmin/gc-tree
-gctree init
-```
-
-`gctree init`이 안내합니다:
-1. 프로바이더 선택: `claude-code`, `codex`, 또는 `both`
-2. 현재 레포에 통합 파일 스캐폴딩
-3. `main` gc-branch 가이드형 온보딩 실행
-
-이후 AI 도구가 계획·구현 전에 `gctree resolve`를 호출하는 법을 자동으로 알게 됩니다.
-
-- **CLI:** `gctree`
-- **요구 사항:** Node.js 20+
-
----
-
 ## 자주 쓰는 흐름
 
 ### 워크스트림마다 별도 컨텍스트
@@ -214,19 +215,19 @@ gctree set-repo-scope --branch client-b --exclude   # 현재 레포 제외
 
 ## 핵심 명령
 
-| 목적 | 명령 |
-|---|---|
-| gc-tree 초기화 및 프로바이더 선택 | `gctree init` |
-| 활성 gc-branch 확인 | `gctree status` |
-| 활성 컨텍스트 검색 | `gctree resolve --query "..."` |
-| gc-branch 생성 또는 전환 | `gctree checkout <branch>` / `gctree checkout -b <branch>` |
-| 모든 gc-branch 목록 | `gctree branches` |
-| 빈 gc-branch 가이드형 온보딩 | `gctree onboard` |
-| 활성 gc-branch 가이드형 업데이트 | `gctree update-global-context` / `gctree ugc` |
-| 레포 범위 규칙 확인 | `gctree repo-map` |
-| 현재 레포 포함/제외 설정 | `gctree set-repo-scope --branch <name> --include` / `--exclude` |
-| 재온보딩 전 gc-branch 초기화 | `gctree reset-gc-branch --branch <name> --yes` |
-| 새 환경 스캐폴딩 | `gctree scaffold --host codex --target /path/to/repo` |
+| 목적                              | 명령                                                            |
+| --------------------------------- | --------------------------------------------------------------- |
+| gc-tree 초기화 및 프로바이더 선택 | `gctree init`                                                   |
+| 활성 gc-branch 확인               | `gctree status`                                                 |
+| 활성 컨텍스트 검색                | `gctree resolve --query "..."`                                  |
+| gc-branch 생성 또는 전환          | `gctree checkout <branch>` / `gctree checkout -b <branch>`      |
+| 모든 gc-branch 목록               | `gctree branches`                                               |
+| 빈 gc-branch 가이드형 온보딩      | `gctree onboard`                                                |
+| 활성 gc-branch 가이드형 업데이트  | `gctree update-global-context` / `gctree ugc`                   |
+| 레포 범위 규칙 확인               | `gctree repo-map`                                               |
+| 현재 레포 포함/제외 설정          | `gctree set-repo-scope --branch <name> --include` / `--exclude` |
+| 재온보딩 전 gc-branch 초기화      | `gctree reset-gc-branch --branch <name> --yes`                  |
+| 새 환경 스캐폴딩                  | `gctree scaffold --host codex --target /path/to/repo`           |
 
 ---
 

package/README.md

@@ -36,6 +36,39 @@ That's not an AI problem. It's a **context management problem**.
 
 ---
 
+## Who this is for
+
+You'll get the most out of `gc-tree` if you:
+
+- Work across **multiple repos** (monorepo teams, platform + client repos, backend + frontend stacks)
+- Switch between **multiple products or clients** in the same week
+- Find yourself **re-explaining the same context** at the start of every AI session
+- Want AI tools to understand your **conventions, architecture, and domain knowledge** — not just the current file
+
+If you only ever work in one repo and one product, you probably don't need this. `CLAUDE.md` or `.cursorrules` is enough.
+
+---
+
+## Install & quick start
+
+```bash
+npm install -g @handsupmin/gc-tree
+gctree init
+```
+
+`gctree init` walks you through:
+
+1. Choose provider: `claude-code`, `codex`, or `both`
+2. Scaffold the integration files into your current repo
+3. Run guided onboarding for the `main` gc-branch
+
+After that, your AI tool gets real SessionStart/UserPromptSubmit hook integration, so it auto-checks gc-tree before work and caches empty/no-match results for the session.
+
+- **CLI:** `gctree`
+- **Requires:** Node.js 20+
+
+---
+
 ## What gc-tree does
 
 `gc-tree` sits **above the repo level**. It stores durable context in structured markdown files and lets your AI tools pull only what's relevant — before each session, automatically.
@@ -64,34 +97,21 @@ Your AI tool gets the right context. Not the whole knowledge base — just the r
 
 ---
 
-## Who this is for
-
-You'll get the most out of `gc-tree` if you:
-
-- Work across **multiple repos** (monorepo teams, platform + client repos, backend + frontend stacks)
-- Switch between **multiple products or clients** in the same week
-- Find yourself **re-explaining the same context** at the start of every AI session
-- Want AI tools to understand your **conventions, architecture, and domain knowledge** — not just the current file
-
-If you only ever work in one repo and one product, you probably don't need this. `CLAUDE.md` or `.cursorrules` is enough.
-
----
-
 ## Why not just use CLAUDE.md or cursor rules?
 
 `CLAUDE.md` is great — for one repo.
 
 The moment you have multiple repos, clients, or workstreams:
 
-| | `CLAUDE.md` / cursor rules | `gc-tree` |
-|---|---|---|
-| Scope | One repo | Multiple repos, one context |
-| Persistence | Per-repo file | Stored outside repos, reused across sessions |
-| Switching contexts | Manual file edits | `gctree checkout client-b` |
-| Relevance filtering | Everything or nothing | Only injects matching docs (~4% of total) |
-| Onboarding | Hand-written | Guided by your AI tool |
-| Works with Codex | ✅ | ✅ |
-| Works with Claude Code | ✅ | ✅ |
+|                        | `CLAUDE.md` / cursor rules | `gc-tree`                                    |
+| ---------------------- | -------------------------- | -------------------------------------------- |
+| Scope                  | One repo                   | Multiple repos, one context                  |
+| Persistence            | Per-repo file              | Stored outside repos, reused across sessions |
+| Switching contexts     | Manual file edits          | `gctree checkout client-b`                   |
+| Relevance filtering    | Everything or nothing      | Only injects matching docs (~4% of total)    |
+| Onboarding             | Hand-written               | Guided by your AI tool                       |
+| Works with Codex       | ✅                         | ✅                                           |
+| Works with Claude Code | ✅                         | ✅                                           |
 
 ---
 
@@ -99,13 +119,13 @@ The moment you have multiple repos, clients, or workstreams:
 
 Tested against real internal documentation (4 Notion exports, Korean + English mixed queries):
 
-| Metric | Result |
-|---|---|
+| Metric                                       | Result           |
+| -------------------------------------------- | ---------------- |
 | Recall — relevant queries find the right doc | **100%** (16/16) |
-| Precision — irrelevant queries return empty | **80%** (4/5) |
-| F1 score | **88.9%** |
-| Tokens injected per query vs. total context | **~4%** |
-| Works with mixed Korean + English queries | ✅ |
+| Precision — irrelevant queries return empty  | **80%** (4/5)    |
+| F1 score                                     | **88.9%**        |
+| Tokens injected per query vs. total context  | **~4%**          |
+| Works with mixed Korean + English queries    | ✅               |
 
 ---
 
@@ -133,25 +153,6 @@ gctree resolve --query 'NestJS DTO plainToInstance'
 
 ---
 
-## Install & quick start
-
-```bash
-npm install -g @handsupmin/gc-tree
-gctree init
-```
-
-`gctree init` walks you through:
-1. Choose provider: `claude-code`, `codex`, or `both`
-2. Scaffold the integration files into your current repo
-3. Run guided onboarding for the `main` gc-branch
-
-After that, your AI tool will know to call `gctree resolve` before planning or implementing.
-
-- **CLI:** `gctree`
-- **Requires:** Node.js 20+
-
----
-
 ## Common moves
 
 ### Separate contexts for separate workstreams
@@ -214,19 +215,19 @@ Context lives outside your repos — no `.gitignore` rules needed, no accidental
 
 ## Core commands
 
-| 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 "..."` |
-| Create or switch gc-branches | `gctree checkout <branch>` / `gctree checkout -b <branch>` |
-| List all gc-branches | `gctree branches` |
-| Guided onboarding for an empty gc-branch | `gctree onboard` |
-| Guided durable update for the active gc-branch | `gctree update-global-context` / `gctree ugc` |
-| Show repo-scope rules | `gctree repo-map` |
-| Include/exclude current repo for a gc-branch | `gctree set-repo-scope --branch <name> --include` / `--exclude` |
-| Reset a gc-branch before re-onboarding | `gctree reset-gc-branch --branch <name> --yes` |
-| Scaffold a new environment | `gctree scaffold --host codex --target /path/to/repo` |
+| 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 "..."`                                  |
+| Create or switch gc-branches                   | `gctree checkout <branch>` / `gctree checkout -b <branch>`      |
+| List all gc-branches                           | `gctree branches`                                               |
+| Guided onboarding for an empty gc-branch       | `gctree onboard`                                                |
+| Guided durable update for the active gc-branch | `gctree update-global-context` / `gctree ugc`                   |
+| Show repo-scope rules                          | `gctree repo-map`                                               |
+| Include/exclude current repo for a gc-branch   | `gctree set-repo-scope --branch <name> --include` / `--exclude` |
+| Reset a gc-branch before re-onboarding         | `gctree reset-gc-branch --branch <name> --yes`                  |
+| Scaffold a new environment                     | `gctree scaffold --host codex --target /path/to/repo`           |
 
 ---