@handsupmin/gc-tree 0.1.3 → 0.2.0

package/README.zh.md

@@ -1,165 +1,249 @@
 # 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` 可以帮助你：
+## 问题所在
 
-- 按产品、客户或工作流隔离上下文
-- 用 markdown 文档保存 source of truth，而不是依赖隐藏记忆
-- 通过精简索引和 summary-first 文档更快定位当前上下文
-- 通过偏好的 LLM CLI 完成 onboarding 与长期更新
-- 让某个 gc-branch 只作用于真正相关的仓库
+你每天都在用 Claude Code 或 Codex。但你的实际工作横跨多个仓库、产品和客户——而 AI 工具只认识当前文件。
 
-## 简要特性
+于是你不得不一遍遍地做这些事：
 
-- **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 它上周"已经知道"的编码规范
+- 手动剔除与当前仓库无关的上下文
 
-## 安装与快速开始
+这不是 AI 的问题，而是**上下文管理的问题**。
 
-### 通过 npm 安装
+---
 
-```bash
-npm install -g @handsupmin/gc-tree
-```
+## gc-tree 做什么
 
-如果你只想临时运行一次，也可以：
+`gc-tree` 工作在**仓库之上**。它把上下文存储为结构化的 Markdown 文件，让 AI 工具在每次会话前自动拉取相关内容。
 
 ```bash
-npx @handsupmin/gc-tree init
+gctree resolve --query "auth token rotation policy"
 ```
 
-- **包名：** `@handsupmin/gc-tree`
-- **CLI 命令：** `gctree`
-- **要求：** Node.js 20+
-如果要从源码开发，请查看 [docs/local-development.md](https://github.com/handsupmin/gc-tree/blob/main/docs/local-development.md)。
+```json
+{
+  "gc_branch": "main",
+  "matches": [
+    {
+      "title": "认证与 Session 规范",
+      "score": 4,
+      "summary": "每次请求都做 JWT rotation，refresh token 存在 httpOnly cookie 里，access token TTL 15 分钟",
+      "excerpt": "## 认证流程\nAccess token：15 分钟 TTL，每次认证请求都做 rotation..."
+    }
+  ]
+}
+```
 
-### 快速开始
+AI 工具拿到的是正确的上下文——不是整个知识库，而是恰好相关的那一片。
 
-#### 1) 初始化 gc-tree
+**实测：每次查询只注入约 4% 的总上下文。** 其余 96% 留在磁盘上，真正需要时才进入 token 窗口。
 
-```bash
-gctree init
-```
+---
 
-这个命令会：
+## 适合哪些人
 
-- 创建 `~/.gctree`
-- 创建默认 `main` gc-branch
-- 让你选择 provider 模式（`claude-code`、`codex` 或 `both`）
-- 如果你选择 `both`，再选择这次 onboarding 要由哪个 provider 启动
-- 让你选择语言（`English`、`Korean`，或手动输入语言）
-- 把 provider 模式、实际 onboarding provider 和语言保存到 `~/.gctree/settings.json`
-- 为当前环境安装对应的命令表面
-- 当 `main` 仍为空时，为当前 gc-branch 启动引导式 onboarding
+如果以下几条符合你的情况，gc-tree 会很适合你：
 
-#### 2) 解析当前上下文
+- 工作横跨**多个仓库**（单体仓库团队、平台 + 客户仓库、后端 + 前端技术栈）
+- 同一周内要在**多个产品或客户**之间来回切换
+- 每次开 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 | ✅ | ✅ |
+
+---
+
+## 经过验证的性能
+
+基于真实内部文档测试（4 份 Notion 导出，中英文混合查询）：
+
+| 指标 | 结果 |
+|---|---|
+| Recall——相关查询找到正确文档的比例 | **100%**（16/16） |
+| Precision——无关查询返回空结果的比例 | **80%**（4/5） |
+| F1 分数 | **88.9%** |
+| 每次查询注入的 token 占总上下文的比例 | **约 4%** |
+| 支持中英文混合查询 | ✅ |
+
+---
+
+## Claude Code 和 Codex 均已验证可用
 
 ```bash
-gctree resolve --query "auth token rotation"
+gctree scaffold --host claude-code   # 安装 CLAUDE.md 片段 + /gc-onboard、/gc-update-global-context
+gctree scaffold --host codex         # 安装 AGENTS.md 片段 + $gc-onboard、$gc-update-global-context
+gctree scaffold --host both          # 两者同时安装
 ```
 
-如果当前仓库不在这个 gc-branch 的映射范围内，`gctree` 可以让你选择：
+两个 provider 使用同一个底层上下文存储。onboard 一次，两个工具都能用。
+
+**Claude Code** — 使用 `/gc-resolve-context`、`/gc-onboard`、`/gc-update-global-context` 斜杠命令。
 
-1. 这次先继续
-2. 以后这个仓库总是使用这个 gc-branch
-3. 在这个仓库里忽略这个 gc-branch
+**Codex** — 使用 `$gc-resolve-context`、`$gc-onboard`、`$gc-update-global-context` skill。已通过 `codex exec` 实际验证：
 
-如果选择 2 或 3，`~/.gctree/branch-repo-map.json` 会被更新。
+```
+gctree status → gc_branch: main，doc_count: 2
+gctree resolve --query 'NestJS DTO plainToInstance'
+→ 匹配到"后端编码规范"（score: 3）
+→ DTO：class-transformer plainToInstance，class-validator 必填
+→ 错误处理：基于 HttpException 的自定义异常，禁止直接抛出 raw Error
+```
 
-#### 3) 需要独立上下文时创建新的 gc-branch
+---
+
+## 安装与快速开始
 
 ```bash
-gctree checkout -b client-b
+npm install -g @handsupmin/gc-tree
+gctree init
 ```
 
-`checkout -b` 会创建一个**新的空 gc-branch**，不会复制已有分支里的文档。
+`gctree init` 会引导你：
+1. 选择 provider：`claude-code`、`codex` 或 `both`
+2. 在当前仓库安装集成文件
+3. 为 `main` gc-branch 完成引导式 onboarding
 
-#### 4) 为一个空的 gc-branch 执行 onboarding
+之后，AI 工具会自动学会在规划或实现前调用 `gctree resolve`。
+
+- **CLI：** `gctree`
+- **要求：** Node.js 20+
+
+---
+
+## 常用操作
+
+### 为不同工作线创建独立上下文
 
 ```bash
+gctree checkout -b client-b
 gctree onboard
 ```
 
-#### 5) 后续执行长期上下文更新
+每个 gc-branch 都是完全独立的上下文通道，像 Git 分支一样自由切换。
+
+### 按需拉取相关上下文
 
 ```bash
-gctree update-global-context
+gctree resolve --query "billing retry policy"
 ```
 
-简短别名：
+只返回匹配的文档——标题、摘要和摘录。摘要不够用时，工具才会读完整文档。
+
+### 保持上下文与时俱进
 
 ```bash
-gctree update-gc
-gctree ugc
+gctree update-global-context   # 或：gctree update-gc / gctree ugc
 ```
 
-如果实际工作后发现某个仓库确实属于当前 gc-branch，更自然的流程是：
+引导式更新流程——AI 工具询问发生了哪些变化，并将新上下文写回 gc-branch。
 
-1. 先把这个仓库加入 branch repo map
-2. 再用 `gctree update-global-context` 补充这个仓库是什么、为什么重要等长期上下文
-
-#### 6) 重新 onboarding 前先重置 gc-branch
+### 限定上下文作用的仓库范围
 
 ```bash
-gctree reset-gc-branch --branch client-b --yes
+gctree set-repo-scope --branch client-b --include   # 包含当前仓库
+gctree set-repo-scope --branch client-b --exclude   # 排除当前仓库
 ```
 
-### 运行时可见的 provider 命令
+`gc-tree` 不会向不相关的仓库注入上下文。
+
+---
 
-scaffold 之后，在运行时可见的命令是：
+## 上下文的存储结构
+
+```
+~/.gctree/
+  branches/
+    main/
+      index.md          ← 压缩索引，≤2000 字符，优先加载
+      docs/
+        auth.md         ← 完整文档，按需读取
+        architecture.md
+    client-b/
+      index.md
+      docs/
+        ...
+  branch-repo-map.json  ← 哪些仓库属于哪个 gc-branch
+  settings.json         ← 首选 provider、语言
+```
 
-- **Codex:** `$gc-onboard`, `$gc-update-global-context`
-- **Claude Code:** `/gc-onboard`, `/gc-update-global-context`
+上下文存储在仓库之外——无需 `.gitignore` 规则，不会误提交，使用同一 gc-branch 的所有项目都可复用。
 
-这些命令在开始收集或更新长期上下文之前，都应该先明确说明当前激活的是哪个 gc-branch，并且除非用户明确要求切换，否则要始终使用保存下来的语言。
+---
 
-### 核心命令速览
+## 核心命令
 
 | 目标 | 命令 |
-| --- | --- |
+|---|---|
 | 初始化 gc-tree 并选择 provider | `gctree init` |
-| 确认当前 gc-branch | `gctree status` |
+| 确认当前激活的 gc-branch | `gctree status` |
 | 搜索当前上下文 | `gctree resolve --query "..."` |
-| 查看仓库范围规则 | `gctree repo-map` |
-| 为 gc-branch 显式设置仓库包含/排除 | `gctree set-repo-scope --branch <name> --include` / `--exclude` |
 | 创建或切换 gc-branch | `gctree checkout <branch>` / `gctree checkout -b <branch>` |
-| 为一个空的 gc-branch 执行 onboarding | `gctree onboard` |
-| 为当前 gc-branch 执行长期更新 | `gctree update-global-context` / `gctree update-gc` / `gctree ugc` |
+| 列出所有 gc-branch | `gctree branches` |
+| 对空 gc-branch 进行引导式 onboarding | `gctree onboard` |
+| 对当前 gc-branch 进行引导式更新 | `gctree update-global-context` / `gctree ugc` |
+| 查看仓库范围规则 | `gctree repo-map` |
+| 为 gc-branch 包含或排除当前仓库 | `gctree set-repo-scope --branch <name> --include` / `--exclude` |
 | 重新 onboarding 前重置 gc-branch | `gctree reset-gc-branch --branch <name> --yes` |
-| 手动为其他环境安装 scaffold | `gctree scaffold --host codex --target /path/to/repo` |
+| 在新环境中安装 scaffold | `gctree scaffold --host codex --target /path/to/repo` |
 
-## 文档
+---
 
-详细文档位于 [`docs/`](https://github.com/handsupmin/gc-tree/tree/main/docs) 目录下。
+## 文档
 
 - **概念** — [`docs/concept.zh.md`](https://github.com/handsupmin/gc-tree/blob/main/docs/concept.zh.md)
-  说明 `gctree` 是什么、解决什么问题，以及全局上下文层的边界。
 - **原理** — [`docs/principles.zh.md`](https://github.com/handsupmin/gc-tree/blob/main/docs/principles.zh.md)
-  介绍 gc-branch、仓库范围、summary-first 文档和引导式更新等原则。
 - **使用方法** — [`docs/usage.zh.md`](https://github.com/handsupmin/gc-tree/blob/main/docs/usage.zh.md)
-  介绍标准 CLI 流程、provider 命令、仓库范围行为和集成方式。
-- **本地运行方法** — [`docs/local-development.zh.md`](https://github.com/handsupmin/gc-tree/blob/main/docs/local-development.zh.md)
-  说明依赖安装、本地运行 CLI 与提交前验证方式。
+- **本地开发** — [`docs/local-development.zh.md`](https://github.com/handsupmin/gc-tree/blob/main/docs/local-development.zh.md)
+
+---
 
 ## 贡献
 
-欢迎贡献。开发流程与 PR 检查清单位于英文文档 [CONTRIBUTING.md](https://github.com/handsupmin/gc-tree/blob/main/CONTRIBUTING.md)。
+欢迎贡献。开发流程与 PR 检查清单见 [CONTRIBUTING.md](https://github.com/handsupmin/gc-tree/blob/main/CONTRIBUTING.md)。
+
+---
 
 ## 许可证
 

package/dist/src/resolve.js

@@ -2,13 +2,44 @@ import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { extractExcerpt, extractSummary, parseIndexEntries } from './markdown.js';
 import { branchDir, branchIndexPath } from './paths.js';
-function scoreText(text, query) {
-    const tokens = String(query || '')
+// Common English stop words that are too short or generic to be meaningful query signals.
+const STOP_WORDS = new Set([
+    'a', 'an', 'the', 'and', 'or', 'but', 'if', 'in', 'on', 'at', 'to', 'for',
+    'of', 'with', 'by', 'as', 'is', 'it', 'its', 'be', 'was', 'are', 'were',
+    'do', 'did', 'has', 'had', 'not', 'no', 'so', 'up', 'out', 'off', 'via',
+    'vs', 'per', 'set', 'get', 'run', 'add', 'use', 'new', 'old', 'all', 'any',
+]);
+function tokenize(text) {
+    // Split on whitespace, punctuation, and symbols — preserving Unicode letters
+    // and digits (including Korean, Japanese, CJK, etc.).
+    return String(text || '')
         .toLowerCase()
-        .split(/[^a-z0-9]+/)
-        .filter((token) => token.length >= 2);
+        .split(/[^\p{L}\p{N}]+/u)
+        .filter((t) => t.length >= 2 && !STOP_WORDS.has(t));
+}
+function makeTokenRegex(token) {
+    // ASCII-only token: use \b word boundary (prevents "store" → "storefront").
+    // Non-ASCII token (Korean, CJK, etc.): use Unicode letter lookbehind/lookahead
+    // because \b doesn't work for non-ASCII characters.
+    const isAscii = /^[a-z0-9]+$/.test(token);
+    return isAscii
+        ? new RegExp(`\\b${token}\\b`)
+        : new RegExp(`(?<!\\p{L})${token}(?!\\p{L})`, 'u');
+}
+function scoreText(text, query) {
+    const tokens = tokenize(query);
+    if (tokens.length === 0)
+        return 0;
     const haystack = String(text || '').toLowerCase();
-    return tokens.reduce((sum, token) => sum + (haystack.includes(token) ? 1 : 0), 0);
+    return tokens.reduce((sum, token) => {
+        try {
+            return sum + (makeTokenRegex(token).test(haystack) ? 1 : 0);
+        }
+        catch {
+            // Regex construction failed (e.g. special chars in token) — fall back to substring
+            return sum + (haystack.includes(token) ? 1 : 0);
+        }
+    }, 0);
 }
 export async function resolveContext({ home, branch, query, }) {
     const indexRaw = await readFile(branchIndexPath(home, branch), 'utf8');
@@ -19,7 +50,10 @@ export async function resolveContext({ home, branch, query, }) {
         const raw = await readFile(fullPath, 'utf8');
         const summary = extractSummary(raw);
         const combined = `${entry.title}\n${summary}\n${raw}`;
-        const score = scoreText(combined, query);
+        // Title matches count double (higher signal density)
+        const titleScore = scoreText(entry.title, query);
+        const bodyScore = scoreText(`${summary}\n${raw}`, query);
+        const score = titleScore * 2 + bodyScore;
         if (score <= 0)
             continue;
         matches.push({

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 をかなり安全に使えます。