@handsupmin/gc-tree 0.1.3 → 0.1.4

package/docs/local-development.zh.md

@@ -1,16 +1,16 @@
-# 本地运行方法
+# 本地开发
 
 [English](local-development.md) | [한국어](local-development.ko.md) | [简体中文](local-development.zh.md) | [日本語](local-development.ja.md) | [Español](local-development.es.md)
 
-## Summary
+## 摘要
 
-本地开发采用标准的 Node.js 20+ 工作流：安装依赖、构建 CLI、本地运行，并在提交前用现有测试套件进行验证。
+本地开发遵循一套标准的 Node.js 20+ 工作流：安装依赖、构建 CLI、在本地运行它，并且在提交修改前用现有测试套件完成验证。
 
 ## 前置条件
 
 - Node.js 20+
 - npm
-- 如果想手动验证 provider 启动流程，需要本地可用的 `codex` 或 `claude` 二进制
+- 如果你想手动体验 provider 启动流程，还需要本地的 `codex` 和 / 或 `claude` 可执行文件
 
 ## 设置
 
@@ -21,57 +21,57 @@ npm run build
 
 ## 在本地运行 CLI
 
-### 方法 1：直接运行构建后的入口
+### 方式 1：直接运行构建后的入口文件
 
 ```bash
 node dist/src/cli.js status
 ```
 
-### 方法 2：把 CLI 链接到你的 shell
+### 方式 2：把 CLI 链接到你的 shell 中
 
 ```bash
 npm link
 gctree status
 ```
 
-如果你修改了 TypeScript 源码，请在再次测试 CLI 之前重新构建。
+如果你改了 TypeScript 源码，在再次测试 CLI 之前记得重新 build 一次。
 
 ## 验证
 
-提交改动前请运行：
+在发起 PR 之前，请先运行：
 
 ```bash
 npm run build
 npm test
 ```
 
-## 仓库范围相关测试
+## repo-scope 测试
 
-目前测试套件会验证：
+当前测试套件覆盖了以下内容：
 
-- provider 模式（`claude-code`、`codex`、`both`）持久化
-- 首选语言持久化以及 launch prompt 中更强的语言约束
-- 根据仓库自动选择 gc-branch
-- `resolve` 过程中的 include/exclude 交互
+- provider 模式持久化（`claude-code`、`codex`、`both`）
+- 偏好语言持久化，以及 launch prompt 中的强语言约束
+- 面向仓库的 gc-branch 选择
+- `resolve` 过程中的 include / exclude 交互
 - branch repo map 更新
-- 引导式 onboarding/update 的边界条件
+- 带引导的 onboarding / update 流程边界
 
-## 手动 provider E2E 验证
+## provider 手动 E2E 检查
 
-自动测试会关闭 provider launch，只验证 launch plan，而不会真的打开 Codex 或 Claude Code 会话。
-如果你想亲自验证真实启动路径，可以在临时目录里运行：
+自动化测试会禁用 provider 启动，这样它们就能在不真正打开 Codex 或 Claude Code 会话的情况下验证 launch plan。
+如果你想亲自走一遍真实的启动路径，可以在一个临时目录里运行下面任意一个命令：
 
 ```bash
 gctree init --provider codex
 gctree init --provider claude-code
 ```
 
-正常情况下，provider 会真正启动，并立即收到 `$gc-onboard` 或 `/gc-onboard`。
+正常情况下，你会看到 provider 被拉起，并立刻收到 `$gc-onboard` 或 `/gc-onboard`。
 
 ## 项目结构
 
-- `src/` — CLI、上下文存储、provider 选择、仓库范围映射、引导式 onboarding/update 流程、scaffolding 逻辑
+- `src/` — CLI、本地上下文存储、provider 选择、repo-scope 映射、带引导的 onboarding / update 流程，以及 scaffolding 逻辑
 - `tests/` — CLI 与行为测试
-- `skills/` — 工具无关的工作流技能
-- `scaffolds/` — 宿主特定的 bootstrap 模板
-- `docs/` — concept、principles、usage 与 development 文档
+- `skills/` — 与工具无关的工作流技能
+- `scaffolds/` — 面向不同 host 的引导模板
+- `docs/` — 概念、原则、使用方式与开发文档

package/docs/principles.es.md

@@ -2,48 +2,49 @@
 
 [English](principles.md) | [한국어](principles.ko.md) | [简体中文](principles.zh.md) | [日本語](principles.ja.md) | [Español](principles.es.md)
 
-## Summary
+## Resumen
 
-`gctree` sigue un conjunto pequeño pero claro de principios de producto: separar el contexto por gc-branch, escribir documentos summary-first, mantener los índices livianos y hacer que cada gc-branch solo influya en los repositorios donde realmente corresponde.
+`gctree` sigue unas pocas reglas de producto muy claras: mantener el contexto con conciencia de rama, mantener los documentos source con enfoque summary-first, mantener los índices ligeros y hacer explícito el repo scope para que cada gc-branch solo influya donde realmente le toca.
 
-## 1. Separar el contexto por gc-branch
+## 1. Mantén el contexto con conciencia de rama
 
-Una sola máquina puede contener varios árboles de contexto global sin mezclarlos.
-Por eso `gctree` usa comandos al estilo git como `checkout` y `checkout -b`, pero en la interfaz deja claro que la rama activa se presenta como **gc-branch**.
+Una misma máquina debería poder contener varios árboles de contexto global sin mezclarlos.
+Por eso `gctree` usa lenguaje tipo Git como `checkout` y `checkout -b`, mientras que en la interfaz orientada al usuario se refiere a la rama activa como **gc-branch**.
 
-## 2. Gestionar explícitamente el alcance por repositorio
+## 2. Haz explícito el repo scope
 
 Un gc-branch no debería afectar en silencio a todos los repositorios de la máquina.
-`gctree` usa `branch-repo-map.json` para registrar el estado de un repo respecto a un gc-branch:
+`gctree` usa `branch-repo-map.json` para registrar si un repositorio está:
 
-- include
-- exclude
-- aún sin mapear
+- incluido para un gc-branch
+- excluido para un gc-branch
+- todavía sin mapear
 
-Si `resolve` se ejecuta en un repo sin mapear, el usuario puede decidir si quiere continuar solo esta vez, usar siempre ese gc-branch allí o ignorarlo allí.
+Si `resolve` se llama desde un repositorio no mapeado, la persona usuaria puede decidir si quiere continuar una vez, usar siempre ese gc-branch allí o ignorarlo en ese repo.
 
-## 3. Mantener `index.md` liviano
+## 3. Mantén `index.md` ligero
 
-El `index.md` de nivel superior es un índice, no un volcado de conocimiento.
-Su trabajo es llevar a herramientas y personas rápidamente al documento fuente correcto.
+El `index.md` de nivel superior es un índice, no un vertedero de contenido.
+Su trabajo es ayudar a herramientas y personas a encontrar rápido el documento source correcto.
+Debe seguir siendo compacto y orientado a enlaces, en lugar de duplicar todo el conocimiento en línea.
 
-## 4. Priorizar documentos summary-first
+## 4. Haz que los documentos source sean summary-first
 
-Cada documento markdown source-of-truth debería incluir una sección `## Summary` cerca del inicio.
-Así las herramientas pueden leer primero la versión corta y abrir el resto solo cuando haga falta.
+Todo documento markdown que actúe como source of truth debería incluir una sección `## Summary` cerca del inicio.
+Eso le da a las herramientas una ruta rápida: leer primero la versión corta y ampliar solo cuando haga falta más detalle.
 
-## 5. Hacer que el onboarding sea explícito y guiado
+## 5. Haz que el onboarding sea explícito y guiado
 
-El usuario no debería tener que escribir JSON a mano para crear un contexto global útil.
-`gctree init` y `gctree onboard` deberían guiar la conversación a través del provider elegido y guardar el resultado en el gc-branch activo.
+Una persona no debería tener que escribir a mano un JSON de onboarding solo para crear un árbol de contexto útil.
+`gctree init` y `gctree onboard` deberían guiar el flujo con el provider elegido y escribir el contexto resultante en el gc-branch activo.
 
 El onboarding solo aplica a gc-branches vacíos.
-Si un gc-branch ya tiene contexto, la ruta correcta es:
+Si un gc-branch ya contiene contexto, el camino correcto es uno de estos dos:
 
-- resetear ese gc-branch y volver a hacer onboarding
-- o ejecutar una actualización duradera guiada
+- restablecer ese gc-branch y volver a hacer onboarding
+- o lanzar una actualización duradera guiada
 
-## 6. Mantener las actualizaciones duraderas bajo control
+## 6. Haz que las actualizaciones duraderas sean intencionales
 
-El contexto duradero no debería cambiar por accidente ni por memoria oculta.
-El flujo de actualización debe ser explícito, guiado por el provider y siempre ligado al gc-branch activo.
+El contexto duradero no debería cambiar por accidente ni a través de memoria oculta.
+El flujo de actualización debe ser explícito, guiado por el provider y estar ligado al gc-branch activo en ese momento.

package/docs/principles.ja.md

@@ -2,48 +2,49 @@
 
 [English](principles.md) | [한국어](principles.ko.md) | [简体中文](principles.zh.md) | [日本語](principles.ja.md) | [Español](principles.es.md)
 
-## Summary
+## 要約
 
-`gctree` は、少数の明確な製品原則に基づいています。コンテキストは gc-branch 単位で分け、文書は summary-first で書き、インデックスは小さく保ち、各 gc-branch が本当に関係するリポジトリでだけ使われるようにします。
+`gctree` は少数のプロダクト原則に従っています。コンテキストはブランチ単位で扱うこと、source 文書は summary-first にすること、index は薄く保つこと、そして repo scope を明示して gc-branch が本来関係するリポジトリにだけ作用するようにすることです。
 
-## 1. コンテキストを gc-branch 単位で分ける
+## 1. コンテキストはブランチを意識して持つ
 
-1 台のマシン上に複数のグローバルコンテキストツリーを混在させずに保持できます。
-そのため `gctree` は `checkout` や `checkout -b` のような git ライクなコマンドを使いながら、ユーザー向けには現在のブランチを **gc-branch** と明示します。
+1 台のマシンの中に複数のグローバルコンテキストツリーがあっても、互いに混ざらないようにできるべきです。
+そのため `gctree` は `checkout` や `checkout -b` のような Git ライクな言葉を使いつつ、ユーザー向けの表現ではアクティブなブランチを **gc-branch** と呼びます。
 
-## 2. リポジトリ範囲を明示的に管理する
+## 2. repo scope は明示する
 
-ある gc-branch がマシン上のすべてのリポジトリへ静かに影響してはいけません。
-`gctree` は `branch-repo-map.json` によって、そのリポジトリがその gc-branch に対してどの状態かを記録します。
+gc-branch がマシン上のすべてのリポジトリに黙って影響してはいけません。
+`gctree` は `branch-repo-map.json` を使って、そのリポジトリが次のどれに当たるかを記録します。
 
-- include
-- exclude
-- まだ未設定
+- その gc-branch に含まれる
+- その gc-branch から除外される
+- まだマッピングされていない
 
-`resolve` が未設定のリポジトリで呼ばれた場合、今回だけ使うか、今後も使うか、ここでは無視するかを選べます。
+`resolve` が未マップのリポジトリから呼ばれた場合、今回だけ続けるか、今後もその gc-branch をそこで使うか、そこで無視するかをユーザーが決められます。
 
-## 3. `index.md` を小さく保つ
+## 3. `index.md` は薄く保つ
 
-トップレベルの `index.md` はダンプではなくインデックスです。
-役割は、ツールを適切な source document へ素早く導くことであり、知識をすべてインラインで複製することではありません。
+トップレベルの `index.md` は知識の置き場ではなく、あくまでインデックスです。
+役割は、人やツールが正しい source 文書を素早く見つけられるようにすることです。
+全文の知識をその場に複製するのではなく、コンパクトでリンク中心に保つべきです。
 
-## 4. summary-first 文書を優先する
+## 4. source 文書は summary-first にする
 
-すべての source-of-truth markdown 文書は、できるだけ冒頭近くに `## Summary` を置くべきです。
-これにより、ツールはまず短い要約を読み、要約だけで足りる場合は全文読み込みを避けられます。
+source-of-truth の markdown 文書には、冒頭近くに `## Summary` セクションがあるべきです。
+そうしておけば、後段のツールはまず短い要約を読み、必要なときだけ詳細を展開できます。
 
 ## 5. オンボーディングは明示的かつガイド付きにする
 
-有用なグローバルコンテキストを作るために、ユーザーが手で onboarding JSON を書く必要はありません。
-`gctree init` と `gctree onboard` は、ユーザーが選んだ provider を通じて対話し、その結果を現在の gc-branch に書き込みます。
+使えるコンテキストツリーを作るために、ユーザーがオンボーディング用 JSON を手書きしなければならないのはよくありません。
+`gctree init` と `gctree onboard` は、ユーザーが選んだ provider に沿って流れを案内し、その結果のコンテキストを現在アクティブな gc-branch に書き込むべきです。
 
-オンボーディングは空の gc-branch に対してのみ実行します。
-すでにコンテキストが入っている場合は、次のどちらかが正しい流れです。
+オンボーディングは空の gc-branch に対してだけ行うものです。
+すでにコンテキストが入っている gc-branch の場合、正しい道筋は次のどちらかです。
 
-- gc-branch をリセットしてから再オンボーディングする
-- またはガイド付きの永続更新を行う
+- その gc-branch をリセットして再オンボードする
+- またはガイド付きの長期更新を実行する
 
-## 6. 永続更新は意図的に行う
+## 6. 長期更新は意図を持って行う
 
-長期コンテキストは、隠れたメモリや偶発的な操作で変わるべきではありません。
-更新フローは明示的で、provider 主導で、常に現在アクティブな gc-branch に結びついている必要があります。
+長期コンテキストが事故的に変わったり、隠れメモリ経由で変わったりしてはいけません。
+更新フローは明示的で、provider 主導であり、かつ現在アクティブな gc-branch にしっかり結び付いているべきです。

package/docs/principles.ko.md

@@ -1,49 +1,50 @@
-# 원리
+# 원칙
 
 [English](principles.md) | [한국어](principles.ko.md) | [简体中文](principles.zh.md) | [日本語](principles.ja.md) | [Español](principles.es.md)
 
-## Summary
+## 요약
 
-`gctree`는 몇 가지 단순한 제품 원칙을 따릅니다. 컨텍스트는 gc-branch 단위로 분리하고, 문서는 summary-first로 작성하며, 인덱스는 작게 유지하고, 각 gc-branch가 실제로 관련 있는 레포에서만 영향을 주도록 범위를 명시합니다.
+`gctree`는 몇 가지 작은 제품 원칙 위에서 움직입니다. 컨텍스트는 브랜치 단위로 다루고, source 문서는 summary-first로 유지하고, index는 얇게 유지하고, repo scope는 명시적으로 관리해서 gc-branch가 자기 자리에만 영향을 주게 합니다.
 
-## 1. 컨텍스트는 gc-branch 단위로 분리한다
+## 1. 컨텍스트는 브랜치 단위로 다룬다
 
-한 머신 안에서도 여러 글로벌 컨텍스트 트리를 섞지 않고 운영할 수 있어야 합니다.
-그래서 `gctree`는 `checkout`, `checkout -b` 같은 git 스타일 명령을 쓰되, 사용자에게는 현재 브랜치를 **gc-branch**라고 명시합니다.
+한 대의 머신 안에서도 여러 글로벌 컨텍스트 트리를 서로 섞이지 않게 유지할 수 있어야 합니다.
+그래서 `gctree`는 `checkout`, `checkout -b` 같은 Git 스타일 언어를 쓰되, 사용자에게 보이는 표현에서는 활성 브랜치를 **gc-branch**라고 부릅니다.
 
-## 2. 레포 범위를 명시적으로 관리한다
+## 2. repo scope는 명시적으로 둔다
 
-어떤 gc-branch가 머신의 모든 레포에 조용히 영향을 주면 안 됩니다.
-`gctree`는 `branch-repo-map.json`을 통해 각 레포가 해당 gc-branch에 대해 어떤 상태인지 기록합니다.
+gc-branch가 머신 안의 모든 레포에 조용히 영향을 주면 안 됩니다.
+`gctree`는 `branch-repo-map.json`을 통해 각 레포가 다음 중 어디에 속하는지 기록합니다.
 
-- include
-- exclude
-- 아직 미지정
+- 특정 gc-branch에 포함됨
+- 특정 gc-branch에서 제외됨
+- 아직 매핑되지 않음
 
-`resolve`가 미지정 레포에서 호출되면, 이번만 사용할지 / 항상 사용할지 / 여기서는 무시할지를 고를 수 있습니다.
+`resolve`가 아직 매핑되지 않은 레포에서 호출되면, 사용자는 이번만 계속할지, 앞으로도 그 gc-branch를 여기서 쓸지, 아니면 여기서는 무시할지 결정할 수 있습니다.
 
-## 3. `index.md`는 작게 유지한다
+## 3. `index.md`는 얇게 유지한다
 
-최상위 `index.md`는 지식 덤프가 아니라 인덱스입니다.
-역할은 도구를 올바른 source document로 빠르게 안내하는 것이지, 모든 내용을 인라인으로 복제하는 것이 아닙니다.
+최상위 `index.md`는 지식 dump가 아니라 인덱스입니다.
+역할은 사람과 도구가 올바른 source 문서를 빠르게 찾도록 돕는 것입니다.
+본문 지식을 다 복붙해 넣기보다, 짧고 링크 중심의 구조를 유지해야 합니다.
 
-## 4. summary-first 문서를 우선한다
+## 4. source 문서는 summary-first로 만든다
 
-모든 source-of-truth markdown 문서는 상단 근처에 `## Summary` 섹션을 두는 것이 좋습니다.
-이렇게 하면 도구가 먼저 짧은 버전을 읽고, 요약만으로 충분할 때는 전체 문서를 읽지 않아도 됩니다.
+source-of-truth markdown 문서라면 상단 가까이에 `## Summary` 섹션이 있어야 합니다.
+그래야 도구가 먼저 짧은 버전을 읽고, 정말 더 자세한 내용이 필요할 때만 본문을 확장해서 볼 수 있습니다.
 
 ## 5. 온보딩은 명시적이고 가이드형이어야 한다
 
-유용한 글로벌 컨텍스트를 만들기 위해 사용자가 직접 onboarding JSON을 손으로 작성할 필요는 없어야 합니다.
-`gctree init`과 `gctree onboard`는 사용자가 고른 provider를 통해 질문을 주고받으며 활성 gc-branch에 결과를 기록해야 합니다.
+유용한 컨텍스트 트리를 만들기 위해 사용자가 온보딩용 JSON을 손으로 작성하게 하면 안 됩니다.
+`gctree init`과 `gctree onboard`는 사용자가 선호하는 provider를 기준으로 흐름을 안내하고, 결과 컨텍스트를 현재 활성 gc-branch에 써 넣어야 합니다.
 
-온보딩은 비어 있는 gc-branch에서만 실행합니다.
-이미 컨텍스트가 있다면 다음 중 하나가 올바른 경로입니다.
+온보딩은 비어 있는 gc-branch에서만 해야 합니다.
+이미 컨텍스트가 들어 있는 gc-branch라면 올바른 경로는 둘 중 하나입니다.
 
-- gc-branch를 리셋하고 다시 온보딩한다
-- 또는 가이드형 장기 업데이트를 실행한다
+- 그 gc-branch를 리셋하고 다시 온보딩하기
+- 혹은 가이드형 장기 업데이트를 실행하기
 
-## 6. 장기 업데이트는 의도적으로 수행한다
+## 6. 장기 업데이트는 의도적으로만 일어나야 한다
 
-장기 컨텍스트는 실수로 바뀌거나 숨겨진 메모리로 덮어써지면 안 됩니다.
-업데이트는 명시적이어야 하고, provider를 통해 진행되며, 항상 현재 활성 gc-branch에 연결되어야 합니다.
+장기 컨텍스트는 우연히 바뀌거나 숨겨진 메모리를 통해 바뀌면 안 됩니다.
+업데이트 흐름은 명시적이어야 하고, provider가 주도해야 하며, 현재 활성 gc-branch와 분명히 연결되어 있어야 합니다.

package/docs/principles.md

@@ -8,12 +8,12 @@
 
 ## 1. Keep context branch-aware
 
-A single machine should be able to hold multiple global-context trees without mixing them.
-That is why `gctree` uses git-like language such as `checkout` and `checkout -b`, while referring to the active branch as a **gc-branch** in user-facing language.
+One machine should be able to hold multiple global-context trees without mixing them together.
+That is why `gctree` uses git-like language such as `checkout` and `checkout -b`, while still referring to the active branch as a **gc-branch** in user-facing copy.
 
 ## 2. Keep repo scope explicit
 
-A gc-branch should not silently affect every repository on the machine.
+A gc-branch should not quietly affect every repository on the machine.
 `gctree` uses `branch-repo-map.json` to record whether a repository is:
 
 - included for a gc-branch
@@ -31,7 +31,7 @@ It should stay compact and link-oriented instead of duplicating full knowledge i
 ## 4. Make source docs summary-first
 
 Every source-of-truth markdown document should include a `## Summary` section near the top.
-That gives downstream tools a fast path: read the short version first, then expand only when more detail is necessary.
+That gives downstream tools a fast path: read the short version first, then expand only when more detail is actually needed.
 
 ## 5. Make onboarding explicit and guided
 

package/docs/principles.zh.md

@@ -1,49 +1,50 @@
-# 原理
+# 原则
 
 [English](principles.md) | [한국어](principles.ko.md) | [简体中文](principles.zh.md) | [日本語](principles.ja.md) | [Español](principles.es.md)
 
-## Summary
+## 摘要
 
-`gctree` 遵循一组简洁而明确的产品原则：上下文按 gc-branch 隔离、文档采用 summary-first 结构、索引保持精简，并且让每个 gc-branch 只在真正相关的仓库里生效。
+`gctree` 遵循几条很小但很明确的产品规则：上下文要有分支意识，source 文档要坚持 summary-first，index 要保持轻量，repo scope 要显式管理，这样每条 gc-branch 才只会影响它真正该影响的仓库。
 
-## 1. 按 gc-branch 隔离上下文
+## 1. 让上下文具备分支意识
 
-一台机器可以同时保存多个全局上下文树，而且彼此不混淆。
-因此 `gctree` 虽然使用 `checkout`、`checkout -b` 这样的 git 风格命令，但在用户界面里会明确把当前分支称为 **gc-branch**。
+一台机器上应该可以同时容纳多棵全局上下文树，而且彼此不混在一起。
+这也是为什么 `gctree` 使用 `checkout`、`checkout -b` 这类类似 Git 的语言，同时在面向用户的表达里把当前分支称为 **gc-branch**。
 
-## 2. 显式管理仓库范围
+## 2. 让 repo scope 保持显式
 
-某个 gc-branch 不应该悄悄影响整台机器上的所有仓库。
-`gctree` 通过 `branch-repo-map.json` 记录一个仓库相对于某个 gc-branch 的状态：
+gc-branch 不应该悄悄影响机器上的每一个仓库。
+`gctree` 用 `branch-repo-map.json` 来记录一个仓库对于某条 gc-branch 处于哪种状态：
 
-- include
-- exclude
-- 尚未映射
+- 被该 gc-branch 包含
+- 被该 gc-branch 排除
+- 还没有映射
 
-当 `resolve` 在一个尚未映射的仓库里被调用时，用户可以选择是仅本次继续、以后总是使用，还是在这里忽略它。
+如果从一个尚未映射的仓库里调用 `resolve`，用户可以决定是只继续这一次、以后都在这里使用该 gc-branch，还是在这里忽略它。
 
-## 3. 保持 `index.md` 精简
+## 3. 让 `index.md` 保持轻量
 
-顶层 `index.md` 是索引，不是内容堆积区。
-它的职责是把工具快速引导到正确的源文档，而不是把所有知识都内联复制进去。
+顶层的 `index.md` 是索引，不是内容倾倒区。
+它的职责是帮助工具和人快速找到正确的 source 文档。
+所以它应该保持紧凑、以链接为主，而不是把完整知识大段复制进去。
 
-## 4. 优先使用 summary-first 文档
+## 4. 让 source 文档遵循 summary-first
 
-每个 source-of-truth markdown 文档都应该在靠前位置包含 `## Summary`。
-这样工具可以先读取简短版本，如果摘要已经足够，就不必再读取整篇文档。
+每一份 source-of-truth markdown 文档，都应该在靠前的位置带上 `## Summary` 段落。
+这样下游工具就有一条快速路径：先读短版本，只有确实需要更多细节时再继续展开。
 
 ## 5. 让 onboarding 明确且有引导
 
-用户不应该为了创建可用的全局上下文而手写 onboarding JSON。
-`gctree init` 和 `gctree onboard` 应该通过用户选择的 provider 与用户对话，并把结果写入当前 gc-branch。
+为了创建一棵有用的上下文树，用户不应该被迫手写 onboarding JSON。
+`gctree init` 和 `gctree onboard` 应该围绕用户偏好的 provider 提供引导，并把结果写入当前激活的 gc-branch。
 
 onboarding 只适用于空的 gc-branch。
-如果该 gc-branch 已经有内容，正确做法是：
+如果某条 gc-branch 已经包含上下文，正确的路径只有两种：
 
-- 重置该 gc-branch 后重新 onboarding
-- 或者执行一次引导式长期更新
+- 重置这条 gc-branch，然后重新 onboarding
+- 或者执行一次带引导的长期更新
 
-## 6. 让长期更新保持可控
+## 6. 让长期更新保持有意图
 
-长期上下文不应该因为隐式记忆或误操作而被改写。
-更新流程应当是显式的、由 provider 驱动的，并且始终绑定到当前激活的 gc-branch。
+长期上下文不应该因为意外或隐藏式记忆而发生变化。
+更新流程必须是显式的、由 provider 驱动的，并且明确绑定到当前激活的 gc-branch 上。

package/docs/usage.es.md

@@ -2,45 +2,47 @@
 
 [English](usage.md) | [한국어](usage.ko.md) | [简体中文](usage.zh.md) | [日本語](usage.ja.md) | [Español](usage.es.md)
 
-## Summary
+## Resumen
 
-Un flujo estándar de `gctree` consiste en inicializar gc-tree, elegir un provider, completar el onboarding del gc-branch `main`, crear nuevos gc-branches cuando haga falta, asociar cada repositorio al gc-branch correcto y usar actualizaciones guiadas para los cambios duraderos.
+Un flujo estándar con `gctree` suele ser así: inicializar gc-tree, elegir un provider, hacer onboarding del gc-branch `main`, resolver el contexto activo cuando haga falta, crear nuevos gc-branches cuando el trabajo lo pida, mapear cada repo al gc-branch correcto y usar actualizaciones guiadas para los cambios duraderos.
 
 ## Flujo estándar
 
 1. ejecuta `gctree init`
 2. elige tu modo de provider preferido (`claude-code`, `codex` o `both`)
-3. elige el idioma del flujo (`English`, `Korean` o escribe tu propio idioma)
+3. elige el idioma del flujo (`English`, `Korean` o un idioma personalizado)
 4. si elegiste `both`, decide qué provider debe iniciar este onboarding
 5. completa el onboarding guiado del gc-branch `main`
-6. resuelve el contexto relevante con `gctree resolve --query "..."`
+6. usa `gctree resolve --query "..."` para recuperar el contexto relevante
 7. crea o cambia gc-branches con `gctree checkout`
-8. usa `gctree onboard` solo en gc-branches vacíos
-9. usa el mapeo por repositorio para que cada gc-branch solo aplique donde corresponde
-10. usa `gctree update-global-context` para cambios duraderos posteriores
+8. usa `gctree onboard` solo en un gc-branch vacío
+9. configura el repo scope para que cada gc-branch solo se aplique donde corresponde
+10. usa `gctree update-global-context` para los cambios duraderos posteriores
 
 ## Comandos clave
 
 | Comando | Propósito |
 | --- | --- |
-| `gctree init` | Crea `~/.gctree`, crea el gc-branch `main`, guarda el modo de provider, el provider real de onboarding y el idioma preferido, prepara el entorno actual y arranca el onboarding guiado si `main` está vacío. |
+| `gctree init` | Crea `~/.gctree`, crea el gc-branch `main`, guarda el modo de provider, el provider de onboarding y el idioma preferido, hace scaffold del entorno actual y arranca el onboarding guiado cuando `main` está vacío. |
 | `gctree checkout <branch>` | Cambia el gc-branch activo. |
 | `gctree checkout -b <branch>` | Crea un gc-branch vacío nuevo y cambia a él. |
-| `gctree branches` | Lista los gc-branches disponibles y muestra el activo. |
-| `gctree status` | Muestra el gc-branch activo, el repo actual, el estado de alcance para ese repo, las advertencias y el provider guardado. |
-| `gctree resolve --query TEXT` | Busca contexto en el gc-branch relevante. Si el repo actual aún no está mapeado, permite decidir interactivamente qué hacer. |
+| `gctree branches` | Lista los gc-branches disponibles y marca cuál está activo. |
+| `gctree status` | Muestra el gc-branch activo, el repo actual, el estado actual de repo scope, advertencias y el provider preferido. |
+| `gctree resolve --query TEXT` | Busca contexto en el gc-branch relevante. Si el repo actual no está mapeado, `gctree` puede preguntar cómo debe tratarse ese repo. |
 | `gctree repo-map` | Muestra el contenido actual de `branch-repo-map.json`. |
-| `gctree set-repo-scope --branch <name> --include` | Añade el repo actual al include de ese gc-branch. |
-| `gctree set-repo-scope --branch <name> --exclude` | Añade el repo actual al exclude de ese gc-branch. |
-| `gctree onboard` | Inicia el onboarding guiado del gc-branch activo. Solo funciona si ese gc-branch está vacío. |
-| `gctree reset-gc-branch --branch <name> --yes` | Limpia un gc-branch para poder volver a hacer onboarding. |
-| `gctree update-global-context` | Inicia una actualización duradera guiada para el gc-branch activo. |
+| `gctree set-repo-scope --branch <name> --include` | Marca el repo actual como incluido para ese gc-branch. |
+| `gctree set-repo-scope --branch <name> --exclude` | Marca el repo actual como ignorado para ese gc-branch. |
+| `gctree onboard` | Lanza el onboarding guiado para el gc-branch activo. Solo funciona si ese gc-branch está vacío. |
+| `gctree reset-gc-branch --branch <name> --yes` | Vacía un gc-branch para poder onboardearlo de nuevo. |
+| `gctree update-global-context` | Lanza una actualización duradera guiada para el gc-branch activo. |
 | `gctree update-gc` / `gctree ugc` | Alias de `gctree update-global-context`. |
 | `gctree scaffold --host <codex|claude-code>` | Instala la superficie de comandos del provider en otro entorno. |
 
-## Ejemplo de alcance por repositorio
+## Ejemplo de repo scope
 
-Por ejemplo, si el gc-branch `A` solo aplica a `B`, `C` y `D`, y no a `F`, puedes gestionarlo así:
+Supón que el gc-branch `A` es relevante para los repos `B`, `C` y `D`, pero no para `F`.
+
+Puedes gestionarlo así:
 
 ```json
 {
@@ -57,7 +59,7 @@ Guardado en:
 ~/.gctree/branch-repo-map.json
 ```
 
-Si luego llamas a `resolve` desde `E`, puedes elegir entre:
+Cuando ejecutas `resolve` desde el repo `E` y la rama `A` todavía no está mapeada allí, `gctree` puede preguntarte si quieres:
 
 1. continuar solo esta vez
 2. usar siempre `A` en `E`
@@ -69,13 +71,13 @@ Si luego llamas a `resolve` desde `E`, puedes elegir entre:
 gctree init
 ```
 
-Después:
+Luego:
 
 1. elige `codex` o `claude-code`
-2. deja que `gctree` prepare el entorno actual
-3. completa el onboarding del gc-branch `main`
+2. deja que `gctree` haga scaffold del entorno actual
+3. completa el onboarding guiado del gc-branch `main`
 
-## Ejemplo con varios gc-branches
+## Ejemplo con varias ramas
 
 ```bash
 gctree checkout -b client-b
@@ -96,17 +98,17 @@ gctree update-gc
 gctree ugc
 ```
 
-Si al trabajar descubres que un repo realmente pertenece al gc-branch actual, el flujo natural es:
+Si un repo recién relevante también debería formar parte del contexto duradero, el flujo natural es:
 
-1. primero añadir ese repo al branch repo map
-2. después ejecutar `update-global-context` para agregar contexto duradero sobre qué hace ese repo y por qué importa
+1. primero mapear ese repo al gc-branch
+2. después ejecutar `update-global-context` para añadir conocimiento duradero sobre qué hace ese repo y por qué importa
 
 ## Patrones de integración
 
 ### Codex CLI / Claude Code CLI
 
-`gctree scaffold` instala comandos del provider para onboarding y actualizaciones guiadas.
-Esos comandos deben dejar claro cuál es el gc-branch activo antes de empezar, y también deben mantener el idioma guardado durante todo el flujo salvo que el usuario pida cambiarlo explícitamente.
+`gctree scaffold` instala la superficie de comandos orientada al provider, como el onboarding guiado y las actualizaciones guiadas.
+Esos comandos deberían mencionar de forma explícita cuál es el gc-branch activo antes de empezar a recopilar o aplicar contexto duradero, y también deberían seguir usando el idioma guardado salvo que la persona usuaria pida cambiarlo.
 
 ```bash
 gctree scaffold --host codex --target /path/to/repo
@@ -115,5 +117,5 @@ gctree scaffold --host claude-code --target /path/to/repo
 
 ### Comportamiento en runtime
 
-El gc-branch activo es el fallback apuntado por `HEAD` dentro de `~/.gctree`.
-Pero si un repo está vinculado explícitamente a otro gc-branch, para ese repo el branch map tiene prioridad sobre HEAD.
+Por defecto, el gc-branch activo es el que apunta `HEAD` dentro de `~/.gctree`, pero el repo mapping puede sobrescribir ese valor si un repositorio está ligado explícitamente a otro gc-branch.
+Eso hace que gc-tree sea práctico incluso para quienes mantienen muchas sesiones abiertas a la vez en repositorios que no tienen relación entre sí.