@handsupmin/gc-tree 0.1.3 → 0.1.4

package/README.zh.md

@@ -1,107 +1,101 @@
 # gc-tree
 
-面向 AI 编码工具的分支化全局上下文层。
+<div align="center">
+
+<img src="./logo.png" alt="gc-tree logo" width="260" />
+
+### 不止于项目内部的全局上下文。
+
+在你现有的 AI 工具之上，再加一层可复用、能长期积累的上下文。
+像管理 Git 分支一样管理多条上下文线索。
+
+[![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)
 
 [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>
 
-`gctree` 是一个面向 AI 编码工具的轻量级 **Global Context Tree**。
-它为长期上下文提供了一个可复用、基于文件、支持分支的明确归宿，而且可以自然接入现有工作流。
+这是为那些日常工作横跨多个仓库、产品、客户和工作流的开发者准备的。
 
-当单个 `AGENTS.md`、`CLAUDE.md` 或一段提示词已经不够时，`gctree` 可以帮助你：
+`gc-tree` 给 AI 编码工具补上了一层 **仓库之上的可复用上下文层**。该长期保留的上下文可以留下来，只在相关仓库里生效，不相关的时候就安静退场。
 
-- 按产品、客户或工作流隔离上下文
-- 用 markdown 文档保存 source of truth，而不是依赖隐藏记忆
-- 通过精简索引和 summary-first 文档更快定位当前上下文
-- 通过偏好的 LLM CLI 完成 onboarding 与长期更新
-- 让某个 gc-branch 只作用于真正相关的仓库
+---
 
-## 简要特性
+## 为什么是 gc-tree？
 
-- **Provider 驱动的 onboarding**
-  `gctree init` 会先询问你想使用哪种 provider 模式（`claude-code`、`codex` 或 `both`），再询问响应语言，并保存这些选择，然后给当前环境安装对应的命令表面，并为默认 `main` gc-branch 启动引导式 onboarding。
-- **带仓库范围的 gc-branch**
-  你可以通过 `~/.gctree/branch-repo-map.json` 把某个 gc-branch 绑定到指定仓库集合，比如让 A 只作用于 B/C/D，而在 F 中忽略。
-- **交互式范围保护**
-  如果 `gctree resolve` 发现当前仓库还没有映射到这个 gc-branch，它可以询问是仅本次继续、以后总是使用，还是在这个仓库里忽略它。
-- **Summary-first 文档结构**
-  工具可以先读取简短摘要，只有在需要时才展开完整文档。
-- **引导式长期更新**
-  不需要手写 JSON 文件，也可以通过同样的 provider 流程更新全局上下文。
+只要你开始认真把 AI 代理用进日常开发，repo-local context 很快就不够用了。
 
-## 安装与快速开始
+一旦工作同时分布在多个仓库和多个工作流上，常见问题就会一起出现：
 
-### 通过 npm 安装
+- 长期上下文被不断塞进提示词里
+- 不相关的上下文泄漏到别的仓库
+- 每开一个新会话都要重新讲一遍背景
+- 客户或产品知识只藏在聊天记录里
+- 每次切换工作流，都得靠人脑手动切换上下文
 
-```bash
-npm install -g @handsupmin/gc-tree
-```
+`gc-tree` 是给那些已经深度使用 Codex、Claude Code 等 AI 编码工具、但不想再手动维护上下文的人准备的。
 
-如果你只想临时运行一次，也可以：
+---
 
-```bash
-npx @handsupmin/gc-tree init
-```
+## 它能直接带来什么
 
-- **包名：** `@handsupmin/gc-tree`
-- **CLI 命令：** `gctree`
-- **要求：** Node.js 20+
-如果要从源码开发，请查看 [docs/local-development.md](https://github.com/handsupmin/gc-tree/blob/main/docs/local-development.md)。
+- **多条可长期维护的上下文**
+  你可以按产品、客户或工作流，分别维护自己的上下文线。
 
-### 快速开始
+- **按仓库控制相关性**
+  可以明确指定某条上下文只该作用于哪些仓库。
 
-#### 1) 初始化 gc-tree
+- **更聪明的范围保护**
+  当你进入一个尚未映射的仓库时，可以选择只继续这一次、以后都在这里启用，或者在这里忽略它。
 
-```bash
-gctree init
-```
+- **带引导的 onboarding 与更新**
+  可以用 Codex、Claude Code，或者两者一起，把上下文建立起来并持续维护。
 
-这个命令会：
+- **summary-first 的 markdown 知识结构**
+  知识留在文件里，而不是藏在隐式记忆里；工具可以先读摘要，再决定要不要展开全文。
 
-- 创建 `~/.gctree`
-- 创建默认 `main` gc-branch
-- 让你选择 provider 模式（`claude-code`、`codex` 或 `both`）
-- 如果你选择 `both`，再选择这次 onboarding 要由哪个 provider 启动
-- 让你选择语言（`English`、`Korean`，或手动输入语言）
-- 把 provider 模式、实际 onboarding provider 和语言保存到 `~/.gctree/settings.json`
-- 为当前环境安装对应的命令表面
-- 当 `main` 仍为空时，为当前 gc-branch 启动引导式 onboarding
+---
 
-#### 2) 解析当前上下文
+## 安装与快速开始
 
 ```bash
-gctree resolve --query "auth token rotation"
+npm install -g @handsupmin/gc-tree
+gctree init
 ```
 
-如果当前仓库不在这个 gc-branch 的映射范围内，`gctree` 可以让你选择：
+这样就可以开工了。
+之后照你原来的开发方式继续就行，`gc-tree` 只是把一层可复用的全局上下文加在你现有流程外面。
 
-1. 这次先继续
-2. 以后这个仓库总是使用这个 gc-branch
-3. 在这个仓库里忽略这个 gc-branch
+- **CLI 命令：** `gctree`
+- **要求：** Node.js 20+
 
-如果选择 2 或 3，`~/.gctree/branch-repo-map.json` 会被更新。
+如果你想从源码开发，请看 [docs/local-development.zh.md](https://github.com/handsupmin/gc-tree/blob/main/docs/local-development.zh.md)。
 
-#### 3) 需要独立上下文时创建新的 gc-branch
+---
 
-```bash
-gctree checkout -b client-b
-```
+## 常用操作
 
-`checkout -b` 会创建一个**新的空 gc-branch**，不会复制已有分支里的文档。
-
-#### 4) 为一个空的 gc-branch 执行 onboarding
+### 当一个工作流值得拥有自己的上下文时，先开一条新分支
 
 ```bash
+gctree checkout -b client-b
 gctree onboard
 ```
 
-#### 5) 后续执行长期上下文更新
+不管是客户项目、产品线、迁移工作，还是某个阶段性的专项，只要值得单独维护背景，就给它单开一个 gc-branch。
+
+### 之后再把长期上下文补进去
 
 ```bash
 gctree update-global-context
 ```
 
+随着工作推进，把真正值得长期保留的信息补到当前激活的 gc-branch 里。
+
 简短别名：
 
 ```bash
@@ -109,41 +103,111 @@ gctree update-gc
 gctree ugc
 ```
 
-如果实际工作后发现某个仓库确实属于当前 gc-branch，更自然的流程是：
+### 需要的时候再把上下文取出来
 
-1. 先把这个仓库加入 branch repo map
-2. 再用 `gctree update-global-context` 补充这个仓库是什么、为什么重要等长期上下文
+```bash
+gctree resolve --query "auth token rotation"
+```
 
-#### 6) 重新 onboarding 前先重置 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 会话都得重新交代：
+
+- 现在讨论的是哪个客户
+- 哪些仓库其实是一组
+- 当前最重要的工作流是什么
+- 哪些上下文放进来反而会干扰
 
-scaffold 之后，在运行时可见的命令是：
+有了 `gc-tree`，你就可以按工作线维护不同上下文，在会话之间复用，并用 repo scope 规则挡住那些不该混进来的背景。
+
+它真正解决的不是“多存一点提示词”，而是：
+
+> **在对的工作层级上，管理对的上下文。**
+
+---
+
+## 核心概念
+
+- **gc-branch**
+  面向某个产品、客户、工作流或领域的一条长期上下文线。
+
+- **repo scope**
+  决定这条上下文应该在哪些仓库里生效的规则。
+
+- **provider-guided flow**
+  不手写 JSON，而是借助你熟悉的 AI 编码工具完成 onboarding 和更新。
+
+- **context tree**
+  在实现上，`gc-tree` 把上下文组织成一棵按分支感知、由文件承载的知识树。
+  对用户来说，核心价值就是：项目之外也能复用的上下文。
+
+---
+
+## 运行时里可见的 provider 命令
+
+scaffold 完成后，运行时可见的命令是：
 
 - **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 set-repo-scope --branch <name> --include` / `--exclude` |
 | 创建或切换 gc-branch | `gctree checkout <branch>` / `gctree checkout -b <branch>` |
 | 为一个空的 gc-branch 执行 onboarding | `gctree onboard` |
 | 为当前 gc-branch 执行长期更新 | `gctree update-global-context` / `gctree update-gc` / `gctree ugc` |
 | 重新 onboarding 前重置 gc-branch | `gctree reset-gc-branch --branch <name> --yes` |
 | 手动为其他环境安装 scaffold | `gctree scaffold --host codex --target /path/to/repo` |
 
+---
+
 ## 文档
 
 详细文档位于 [`docs/`](https://github.com/handsupmin/gc-tree/tree/main/docs) 目录下。
@@ -157,10 +221,14 @@ scaffold 之后，在运行时可见的命令是：
 - **本地运行方法** — [`docs/local-development.zh.md`](https://github.com/handsupmin/gc-tree/blob/main/docs/local-development.zh.md)
   说明依赖安装、本地运行 CLI 与提交前验证方式。
 
+---
+
 ## 贡献
 
 欢迎贡献。开发流程与 PR 检查清单位于英文文档 [CONTRIBUTING.md](https://github.com/handsupmin/gc-tree/blob/main/CONTRIBUTING.md)。
 
+---
+
 ## 许可证
 
 MIT。详见 [`LICENSE`](https://github.com/handsupmin/gc-tree/blob/main/LICENSE)。

package/docs/concept.es.md

@@ -2,51 +2,51 @@
 
 [English](concept.md) | [한국어](concept.ko.md) | [简体中文](concept.zh.md) | [日本語](concept.ja.md) | [Español](concept.es.md)
 
-## Summary
+## Resumen
 
-`gctree` es una capa de contexto global pequeña y clara para herramientas de programación con IA. Mantiene el contexto duradero en documentos markdown fuera de un único repositorio, permite cambiarlo y consultarlo por gc-branch, y además puede limitar cada gc-branch a los repositorios donde realmente aplica.
+`gctree` es una capa ligera de contexto global para herramientas de programación con IA. Mantiene el contexto duradero en documentos markdown explícitos fuera de cualquier repositorio individual, permite cambiar entre gc-branches y puede limitar cada gc-branch a los repositorios donde realmente tiene sentido.
 
 ## Qué es `gctree`
 
-`gctree` es una CLI ligera para gestionar contexto global reutilizable.
-Está pensada para personas y equipos que necesitan conservar el mismo contexto duradero entre varios repositorios, sesiones y herramientas.
+`gctree` es una CLI para gestionar contexto global reutilizable.
+Está pensada para equipos y personas que quieren que el contexto de largo recorrido sobreviva entre repositorios, sesiones y herramientas, sin convertirlo en una memoria oculta imposible de inspeccionar.
 
-En lugar de dejar ese conocimiento repartido entre archivos de prompts o depender de memoria oculta, `gctree` le da un lugar claro, estable y basado en archivos.
+En lugar de repartir el conocimiento importante entre archivos de prompt, notas locales al repo e instrucciones improvisadas, `gctree` le da a ese conocimiento un hogar estable, visible y respaldado por archivos.
 
 ## Qué problema resuelve
 
-Muchos entornos de programación con IA empiezan con una de estas opciones:
+Muchos entornos de programación con IA empiezan de forma bastante simple:
 
-- un solo `AGENTS.md`
-- un solo `CLAUDE.md`
-- un archivo de prompts dentro del repositorio
-- un conjunto de notas copiadas manualmente en los prompts
+- un `AGENTS.md`
+- un `CLAUDE.md`
+- un archivo de prompt dentro del repo
+- unas pocas notas que se copian al prompt cuando hacen falta
 
-Eso funciona al principio, pero con el tiempo aparecen necesidades como estas:
+Eso funciona durante un tiempo. Pero cuando empiezan a aparecer necesidades reales, la misma configuración empieza a romperse:
 
-- separar el contexto por producto o cliente
-- mantener contexto fuera de un único repositorio
-- reutilizar la misma documentación duradera desde varias herramientas
-- encontrar el contexto correcto de forma rápida y consistente
-- actualizar el contexto duradero de una forma más segura
-- trabajar en paralelo en muchos repositorios y sesiones a la vez
+- cada producto necesita un contexto distinto
+- el trabajo para clientes debe mantenerse aislado
+- la guía reutilizable debería vivir fuera de un único repositorio
+- varias herramientas deberían poder leer la misma source of truth
+- el contexto duradero debería evolucionar con un flujo seguro y revisable
+- una misma persona puede tener muchas sesiones abiertas en muchos repos a la vez
 
-`gctree` se ocupa precisamente de esa capa.
+`gctree` existe para resolver precisamente esa capa del problema, y hacerlo de forma limpia.
 
 ## Límite de alcance
 
-`gctree` intencionalmente no es:
+`gctree` no pretende ser:
 
-- un orquestador de entrega request-to-commit
+- un orquestador integral que lleve una petición hasta el commit
 - un sistema de memoria oculta
 - un runtime de colaboración en navegador
-- un producto generalista de base de conocimiento
+- un producto de base de conocimiento de propósito general
 
-Se centra en ramas reutilizables de contexto global y en flujos de actualización explícitos.
+Se concentra en una sola tarea: gestionar ramas de contexto global reutilizable y sus actualizaciones explícitas.
 
-## Estructura de archivos
+## Modelo de archivos
 
-Un directorio home típico se ve así:
+Un directorio personal típico queda así:
 
 ```text
 ~/.gctree/
@@ -60,22 +60,22 @@ Un directorio home típico se ve así:
       docs/
 ```
 
-- `HEAD` indica el gc-branch activo de fallback.
-- `settings.json` guarda el modo de provider, el provider real usado para iniciar el onboarding y el idioma preferido del flujo.
-- `branch-repo-map.json` guarda las reglas include/exclude por gc-branch.
+- `HEAD` sigue el gc-branch activo por defecto.
+- `settings.json` guarda el modo de provider, el provider elegido para lanzar el onboarding en runtime y el idioma preferido del flujo.
+- `branch-repo-map.json` guarda qué repositorios están incluidos o excluidos para cada gc-branch.
 - `branch.json` guarda metadatos ligeros del gc-branch.
-- `index.md` es el punto de entrada compacto para las herramientas.
-- `docs/` guarda los documentos markdown source-of-truth.
+- `index.md` es el punto de entrada compacto para herramientas y personas.
+- `docs/` contiene los documentos markdown que actúan como source of truth.
 
-## Comportamiento con alcance por repositorio
+## Comportamiento con conciencia de repositorio
 
-Un gc-branch no tiene por qué aplicarse a todos los repositorios.
-Si la rama `A` solo es relevante para `B`, `C` y `D`, eso puede registrarse en `branch-repo-map.json`.
+Un gc-branch no tiene por qué aplicarse en todas partes.
+Si la rama `A` solo es relevante para los repositorios `B`, `C` y `D`, `gctree` puede dejarlo registrado en `branch-repo-map.json`.
 
-Entonces, si ejecutas `gctree resolve` desde `F`, puedes elegir entre:
+Cuando `gctree resolve` se ejecuta desde otro repositorio, por ejemplo `F`, puede:
 
-- continuar solo esta vez
-- usar siempre esa rama en ese repo
-- ignorarla en ese repo
+- continuar solo una vez
+- usar siempre ese gc-branch en `F`
+- ignorar ese gc-branch en `F`
 
-Eso vuelve a `gctree` mucho más seguro para usuarios intensivos que mantienen muchas sesiones paralelas abiertas sobre repositorios no relacionados.
+Eso hace que gc-tree sea mucho más seguro para quienes mantienen muchas sesiones paralelas abiertas en repositorios que no tienen relación entre sí.

package/docs/concept.ja.md

@@ -1,52 +1,52 @@
-# コンセプト
+# 概念
 
 [English](concept.md) | [한국어](concept.ko.md) | [简体中文](concept.zh.md) | [日本語](concept.ja.md) | [Español](concept.es.md)
 
-## Summary
+## 要約
 
-`gctree` は AI コーディングツール向けの、小さく明確なグローバルコンテキストレイヤーです。長期コンテキストを単一リポジトリの外にある markdown 文書として管理し、gc-branch 単位で切り替え・参照・維持でき、さらに実際に関係するリポジトリだけに適用範囲を絞れます。
+`gctree` は AI コーディングツール向けの軽量なグローバルコンテキストレイヤーです。単一リポジトリの外側に長期コンテキストを明示的な markdown 文書として置き、gc-branch を切り替えながら文脈を使い分けられるようにし、各 gc-branch が本当に関係あるリポジトリにだけ影響するよう制御できます。
 
-## `gctree` とは
+## `gctree` とは何か
 
-`gctree` は再利用可能なグローバルコンテキストを管理するための軽量 CLI です。
-複数のリポジトリ、セッション、ツールをまたいでも同じ長期コンテキストを使い続けたい個人やチームのために設計されています。
+`gctree` は再利用できるグローバルコンテキストを管理するための CLI です。
+複数のリポジトリ、複数のセッション、複数のツールをまたいでも長期コンテキストが生き残るようにしつつ、それをブラックボックスな隠れメモリにはしない、という前提で作られています。
 
-長期知識を隠れたメモリに任せたり、複数のプロンプトファイルへ散らしたりする代わりに、`gctree` はその知識に明確で安定したファイルベースの置き場所を与えます。
+大事な知識がプロンプトファイル、リポジトリ内メモ、場当たり的な指示に散らばる代わりに、`gctree` はその知識に安定したファイルベースの置き場所を与えます。
 
-## 解決する課題
+## 何の問題を解決するのか
 
-多くの AI コーディング環境は、次のいずれかから始まります。
+多くの AI コーディング環境は、最初はこんな形で始まります。
 
-- 1 つの `AGENTS.md`
-- 1 つの `CLAUDE.md`
-- リポジトリ内のローカルなプロンプトファイル
-- プロンプトに都度貼り付けるメモ
+- `AGENTS.md` が 1 つ
+- `CLAUDE.md` が 1 つ
+- リポジトリ内の短いプロンプトファイルが 1 つ
+- 必要なときだけプロンプトに貼り付けるメモが少し
 
-最初はそれで十分でも、やがて次のような要件が出てきます。
+しばらくはそれで回ります。けれど実務が乗ってくると、同じやり方はすぐ苦しくなります。
 
-- プロダクトやクライアントごとにコンテキストを分けたい
-- 1 つのリポジトリの外にコンテキストを保ちたい
-- 複数ツールが同じ長期文書を再利用できるようにしたい
-- 必要なコンテキストを一貫した方法で素早く見つけたい
-- 長期コンテキストをより安全に更新したい
-- 同じユーザーが複数のリポジトリ・複数のセッションで並行作業する
+- プロダクトごとに必要なコンテキストが違う
+- クライアント案件は互いに分離しておく必要がある
+- 再利用したいガイダンスは単一リポジトリの外に置きたい
+- 複数ツールが同じ source of truth を読めるべき
+- 長期コンテキストは安全でレビュー可能な流れで育てたい
+- 1 人のユーザーが同時に複数リポジトリで複数セッションを動かすことがある
 
-`gctree` は、まさにその層を扱います。
+`gctree` は、まさにそのレイヤーをきれいに扱うためのものです。
 
-## スコープ境界
+## スコープの境界
 
-`gctree` が意図的に担当しないものは次の通りです。
+`gctree` は意図的に、次のものではありません。
 
-- request-to-commit 型のデリバリーオーケストレータ
-- 隠れたメモリシステム
-- ブラウザ協業ランタイム
+- リクエストからコミットまでを一気通貫で回す実行オーケストレータ
+- 隠れメモリの仕組み
+- ブラウザ型のコラボレーションランタイム
 - 汎用ナレッジベース製品
 
-`gctree` は、再利用可能なグローバルコンテキストブランチと、明示的な更新フローに集中します。
+`gctree` が集中する仕事は 1 つです。再利用できるグローバルコンテキストブランチと、その明示的な更新を管理することです。
 
-## ファイル構成
+## ファイルモデル
 
-典型的なホームディレクトリ構成は次の通りです。
+典型的なホームディレクトリ配下の構成はこうなります。
 
 ```text
 ~/.gctree/
@@ -60,22 +60,22 @@
       docs/
 ```
 
-- `HEAD` は fallback のアクティブ gc-branch を指します。
-- `settings.json` は provider モード、実際のオンボーディング起動 provider、優先ワークフロー言語を保持します。
-- `branch-repo-map.json` は gc-branch ごとの include/exclude リポジトリ規則を保存します。
-- `branch.json` は軽量な gc-branch メタデータを保存します。
-- `index.md` はツール向けの小さな入口です。
-- `docs/` には source-of-truth の markdown 文書を保存します。
+- `HEAD` はデフォルトでアクティブになる gc-branch を追跡します。
+- `settings.json` には provider モード、ランタイム起動に使うオンボーディング provider、優先するワークフロー言語が入ります。
+- `branch-repo-map.json` には各 gc-branch ごとのリポジトリの include / exclude 情報が入ります。
+- `branch.json` には軽量な gc-branch メタデータが入ります。
+- `index.md` はツールが最初に読むコンパクトな入口です。
+- `docs/` には source-of-truth の markdown 文書が入ります。
 
-## リポジトリ範囲の振る舞い
+## リポジトリを意識した振る舞い
 
-ある gc-branch がすべてのリポジトリに適用される必要はありません。
-たとえば branch `A` が `B`、`C`、`D` にだけ関係するなら、その事実を `branch-repo-map.json` に記録できます。
+gc-branch はどこでも有効である必要はありません。
+たとえば branch `A` が repo `B`、`C`、`D` にしか関係しないなら、その事実を `branch-repo-map.json` に記録できます。
 
-その状態で `F` リポジトリから `gctree resolve` を実行すると、次を選べます。
+その状態で別の repo `F` から `gctree resolve` を実行した場合、`gctree` は次のように扱えます。
 
-- 今回だけ使う
-- 今後もこのリポジトリで使う
-- このリポジトリでは無視する
+- 今回だけ続ける
+- 今後も `F` ではその gc-branch を使う
+- `F` ではその gc-branch を無視する
 
-これにより、多数のセッションを開いて複数の無関係なリポジトリで並行作業する heavy ユーザーにも、より安全に使えるようになります。
+これによって、無関係なリポジトリをまたいで多くの並行セッションを開いているヘビーユーザーでも、gc-tree をかなり安全に使えます。