@handsupmin/gc-tree 0.2.0 → 0.2.1

package/docs/principles.ja.md

@@ -2,9 +2,9 @@
 
 [English](principles.md) | [한국어](principles.ko.md) | [简体中文](principles.zh.md) | [日本語](principles.ja.md) | [Español](principles.es.md)
 
-## 要約
+## 概要
 
-`gctree` は少数のプロダクト原則に従っています。コンテキストはブランチ単位で扱うこと、source 文書は summary-first にすること、index は薄く保つこと、そして repo scope を明示して gc-branch が本来関係するリポジトリにだけ作用するようにすることです。
+`gctree` は少数のプロダクト原則に従っています。コンテキストはブランチを意識して持つこと、ソースドキュメントは summary-first にすること、index は薄く保つこと、repo scope を明示すること、関連するものだけを注入すること、そしてシェルコマンドを実行できるあらゆるプロバイダーをサポートすることです。
 
 ## 1. コンテキストはブランチを意識して持つ
 
@@ -25,26 +25,39 @@ gc-branch がマシン上のすべてのリポジトリに黙って影響して
 ## 3. `index.md` は薄く保つ
 
 トップレベルの `index.md` は知識の置き場ではなく、あくまでインデックスです。
-役割は、人やツールが正しい source 文書を素早く見つけられるようにすることです。
-全文の知識をその場に複製するのではなく、コンパクトでリンク中心に保つべきです。
+役割は、人やツールが正しいソースドキュメントを素早く見つけられるようにすることです。
+**2000 文字** 以内に収め、全文の知識をその場に複製するのではなく、コンパクトでリンク中心に保つべきです。
 
-## 4. source 文書は summary-first にする
+## 4. ソースドキュメントは summary-first にする
 
-source-of-truth の markdown 文書には、冒頭近くに `## Summary` セクションがあるべきです。
-そうしておけば、後段のツールはまず短い要約を読み、必要なときだけ詳細を展開できます。
+信頼できる情報源となるマークダウンドキュメントには、冒頭近くに `## Summary` セクションがあるべきです。
+そうしておけば、後段のツールはまず短い要約を読み、実際に詳細が必要になったときだけ展開できます。
 
 ## 5. オンボーディングは明示的かつガイド付きにする
 
-使えるコンテキストツリーを作るために、ユーザーがオンボーディング用 JSON を手書きしなければならないのはよくありません。
-`gctree init` と `gctree onboard` は、ユーザーが選んだ provider に沿って流れを案内し、その結果のコンテキストを現在アクティブな gc-branch に書き込むべきです。
+使えるコンテキストツリーを作るために、ユーザーがオンボーディング用の JSON を手書きしなければならないのはよくありません。
+`gctree init` と `gctree onboard` は、ユーザーが選んだプロバイダーに沿って流れを案内し、その結果のコンテキストを現在アクティブな gc-branch に書き込むべきです。
 
 オンボーディングは空の gc-branch に対してだけ行うものです。
 すでにコンテキストが入っている gc-branch の場合、正しい道筋は次のどちらかです。
 
 - その gc-branch をリセットして再オンボードする
-- またはガイド付きの長期更新を実行する
+- またはガイド付きの永続的更新を実行する
 
-## 6. 長期更新は意図を持って行う
+## 6. 永続的な更新は意図を持って行う
 
-長期コンテキストが事故的に変わったり、隠れメモリ経由で変わったりしてはいけません。
-更新フローは明示的で、provider 主導であり、かつ現在アクティブな gc-branch にしっかり結び付いているべきです。
+永続的なコンテキストが事故的に変わったり、隠れたメモリ経由で変わったりしてはいけません。
+更新フローは明示的で、プロバイダー主導であり、かつ現在アクティブな gc-branch にしっかり結び付いているべきです。
+
+## 7. 関連するものだけを注入する
+
+ツールのセッションがナレッジベース全体を受け取るべきではありません。
+`gctree resolve` はドキュメントをクエリに対してスコアリングし、マッチしたもののタイトル・サマリー・抜粋だけを返します。フルドキュメントはサマリーだけでは不足するときにのみ読み込まれます。
+
+実際には 1 クエリあたり保存された総コンテキストの約 4% が注入されます。残りの 96% はディスク上に留まり、実際に必要になるまでトークンウィンドウには入りません。
+
+## 8. プロバイダーに依存しない設計を保つ
+
+`gctree` はコンテキストをプレーンなマークダウンファイルとして保存するため、どのツールでも読み込めます。
+Claude Code と Codex はどちらも `gctree scaffold` を通じて同じ基盤のストアに対して scaffold します。
+新しいプロバイダーのサポートを追加するには、新しい scaffold テンプレートを書くだけです。コアのストレージや resolve ロジックに変更は不要です。

package/docs/principles.ko.md

@@ -4,47 +4,60 @@
 
 ## 요약
 
-`gctree`는 몇 가지 작은 제품 원칙 위에서 움직입니다. 컨텍스트는 브랜치 단위로 다루고, source 문서는 summary-first로 유지하고, index는 얇게 유지하고, repo scope는 명시적으로 관리해서 gc-branch가 자기 자리에만 영향을 주게 합니다.
+`gctree`는 소수의 제품 원칙을 따릅니다: 컨텍스트는 브랜치 인식으로, 소스 문서는 요약 우선으로, 인덱스는 슬림하게, 저장소 범위는 명시적으로, 관련된 것만 주입하고, 셸 명령을 실행할 수 있는 모든 프로바이더를 지원합니다.
 
-## 1. 컨텍스트는 브랜치 단위로 다룬다
+## 1. 컨텍스트를 브랜치 인식으로 유지한다
 
-한 대의 머신 안에서도 여러 글로벌 컨텍스트 트리를 서로 섞이지 않게 유지할 수 있어야 합니다.
-그래서 `gctree`는 `checkout`, `checkout -b` 같은 Git 스타일 언어를 쓰되, 사용자에게 보이는 표현에서는 활성 브랜치를 **gc-branch**라고 부릅니다.
+한 대의 머신이 여러 전역 컨텍스트 트리를 서로 섞이지 않게 유지할 수 있어야 합니다.
+그래서 `gctree`는 `checkout`, `checkout -b` 같은 git 스타일의 언어를 사용하면서도, 사용자 대면 문구에서는 활성 브랜치를 **gc-branch**라고 부릅니다.
 
-## 2. repo scope는 명시적으로 둔다
+## 2. 저장소 범위를 명시적으로 유지한다
 
-gc-branch가 머신 안의 모든 레포에 조용히 영향을 주면 안 됩니다.
-`gctree`는 `branch-repo-map.json`을 통해 각 레포가 다음 중 어디에 속하는지 기록합니다.
+gc-branch가 머신의 모든 저장소에 조용히 영향을 미쳐서는 안 됩니다.
+`gctree`는 `branch-repo-map.json`을 사용해 저장소가 다음 상태 중 어느 것인지 기록합니다:
 
-- 특정 gc-branch에 포함됨
-- 특정 gc-branch에서 제외됨
+- gc-branch에 포함됨
+- gc-branch에서 제외됨
 - 아직 매핑되지 않음
 
-`resolve`가 아직 매핑되지 않은 레포에서 호출되면, 사용자는 이번만 계속할지, 앞으로도 그 gc-branch를 여기서 쓸지, 아니면 여기서는 무시할지 결정할 수 있습니다.
+매핑되지 않은 저장소에서 `resolve`가 호출되면, 사용자가 해당 저장소에서 한 번만 계속할지, 항상 해당 gc-branch를 사용할지, 아니면 무시할지 결정할 수 있습니다.
 
-## 3. `index.md`는 얇게 유지한다
+## 3. `index.md`를 슬림하게 유지한다
 
-최상위 `index.md`는 지식 dump가 아니라 인덱스입니다.
-역할은 사람과 도구가 올바른 source 문서를 빠르게 찾도록 돕는 것입니다.
-본문 지식을 다 복붙해 넣기보다, 짧고 링크 중심의 구조를 유지해야 합니다.
+최상위 `index.md`는 인덱스이지, 덤프가 아닙니다.
+도구와 사람이 올바른 소스 문서를 빠르게 찾을 수 있도록 돕는 것이 역할입니다.
+**2000자** 이하로 유지되어야 하며, 전체 지식을 인라인으로 복제하는 대신 링크 중심으로 구성되어야 합니다.
 
-## 4. source 문서는 summary-first로 만든다
+## 4. 소스 문서를 요약 우선으로 구성한다
 
-source-of-truth markdown 문서라면 상단 가까이에 `## Summary` 섹션이 있어야 합니다.
-그래야 도구가 먼저 짧은 버전을 읽고, 정말 더 자세한 내용이 필요할 때만 본문을 확장해서 볼 수 있습니다.
+모든 정보 소스 마크다운 문서는 상단 근처에 `## Summary` 섹션을 포함해야 합니다.
+이는 다운스트림 도구에게 빠른 경로를 제공합니다: 먼저 짧은 버전을 읽고, 실제로 더 많은 상세 내용이 필요할 때만 확장합니다.
 
-## 5. 온보딩은 명시적이고 가이드형이어야 한다
+## 5. 온보딩을 명시적이고 안내된 방식으로 만든다
 
-유용한 컨텍스트 트리를 만들기 위해 사용자가 온보딩용 JSON을 손으로 작성하게 하면 안 됩니다.
-`gctree init`과 `gctree onboard`는 사용자가 선호하는 provider를 기준으로 흐름을 안내하고, 결과 컨텍스트를 현재 활성 gc-branch에 써 넣어야 합니다.
+사용자가 유용한 컨텍스트 트리를 만들기 위해 온보딩 JSON을 직접 작성하도록 요구해서는 안 됩니다.
+`gctree init`과 `gctree onboard`는 사용자가 선호하는 프로바이더를 안내하고, 결과 컨텍스트를 활성 gc-branch에 기록해야 합니다.
 
-온보딩은 비어 있는 gc-branch에서만 해야 합니다.
-이미 컨텍스트가 들어 있는 gc-branch라면 올바른 경로는 둘 중 하나입니다.
+온보딩은 빈 gc-branch에만 적용됩니다.
+gc-branch에 이미 컨텍스트가 있다면, 올바른 경로는 다음 중 하나입니다:
 
-- 그 gc-branch를 리셋하고 다시 온보딩하기
-- 혹은 가이드형 장기 업데이트를 실행하기
+- 해당 gc-branch를 초기화하고 다시 온보딩
+- 또는 안내된 지속 업데이트 실행
 
-## 6. 장기 업데이트는 의도적으로만 일어나야 한다
+## 6. 지속 업데이트를 의도적으로 유지한다
 
-장기 컨텍스트는 우연히 바뀌거나 숨겨진 메모리를 통해 바뀌면 안 됩니다.
-업데이트 흐름은 명시적이어야 하고, provider가 주도해야 하며, 현재 활성 gc-branch와 분명히 연결되어 있어야 합니다.
+지속 컨텍스트는 우연히 또는 숨겨진 메모리를 통해 변경되어서는 안 됩니다.
+업데이트 흐름은 명시적이어야 하고, 프로바이더 주도로 이루어지며, 현재 활성 gc-branch에 연결되어야 합니다.
+
+## 7. 관련된 것만 주입한다
+
+도구 세션은 전체 지식 베이스를 절대 받아서는 안 됩니다.
+`gctree resolve`는 쿼리에 대해 문서에 점수를 매기고 매칭된 것만 반환합니다 — 제목, 요약, 발췌문 형태로. 전체 문서는 요약으로 충분하지 않을 때만 읽습니다.
+
+실제로 이는 쿼리당 저장된 전체 컨텍스트의 약 4%만 주입됨을 의미합니다. 나머지 96%는 실제로 필요할 때까지 디스크에 남아 토큰 윈도우 밖에 있습니다.
+
+## 8. 프로바이더에 종속되지 않는다
+
+`gctree`는 어떤 도구든 읽을 수 있는 일반 마크다운 파일에 컨텍스트를 저장합니다.
+Claude Code와 Codex 모두 `gctree scaffold`를 통해 동일한 기반 저장소에 대해 scaffold합니다.
+새로운 프로바이더 지원 추가는 새 scaffold 템플릿을 작성하는 것을 의미합니다 — 핵심 저장소나 resolve 로직은 변경이 필요 없습니다.

package/docs/principles.md

@@ -4,7 +4,7 @@
 
 ## Summary
 
-`gctree` follows a small set of product rules: keep context branch-aware, keep source docs summary-first, keep indexes slim, and make repo scope explicit so a gc-branch only influences the repositories where it belongs.
+`gctree` follows a small set of product rules: keep context branch-aware, keep source docs summary-first, keep indexes slim, make repo scope explicit, inject only what is relevant, and support any provider that can run shell commands.
 
 ## 1. Keep context branch-aware
 
@@ -26,7 +26,7 @@ If `resolve` is called from an unmapped repository, the user can decide whether
 
 The top-level `index.md` is an index, not a dump.
 Its job is to help tools and humans find the right source document quickly.
-It should stay compact and link-oriented instead of duplicating full knowledge inline.
+It should stay under **2000 characters** and remain link-oriented instead of duplicating full knowledge inline.
 
 ## 4. Make source docs summary-first
 
@@ -48,3 +48,16 @@ If a gc-branch already contains context, the correct path is either:
 
 Durable context should not change by accident or through hidden memory.
 The update flow should be explicit, provider-driven, and tied to the currently active gc-branch.
+
+## 7. Inject only what is relevant
+
+A tool session should never receive the entire knowledge base.
+`gctree resolve` scores documents against the query and returns only the matching ones — title, summary, and excerpt. The full document is read only when the summary is not enough.
+
+In practice this means roughly 4% of total stored context is injected per query. The remaining 96% stays on disk, out of the token window, until it is actually needed.
+
+## 8. Stay provider-agnostic
+
+`gctree` stores context in plain markdown files that any tool can read.
+Claude Code and Codex both scaffold against the same underlying store via `gctree scaffold`.
+Adding support for a new provider means writing a new scaffold template — no changes to the core storage or resolve logic.

package/docs/principles.zh.md

@@ -1,50 +1,63 @@
-# 原则
+# 设计原则
 
 [English](principles.md) | [한국어](principles.ko.md) | [简体中文](principles.zh.md) | [日本語](principles.ja.md) | [Español](principles.es.md)
 
-## 摘要
+## 概述
 
-`gctree` 遵循几条很小但很明确的产品规则：上下文要有分支意识，source 文档要坚持 summary-first，index 要保持轻量，repo scope 要显式管理，这样每条 gc-branch 才只会影响它真正该影响的仓库。
+`gctree` 遵循一套简明的产品准则：保持上下文的分支感知、让源文档以摘要为先、保持索引精简、明确仓库作用范围、只注入相关内容，并支持任何能够运行 shell 命令的提供商。
 
-## 1. 让上下文具备分支意识
+## 1. 保持上下文的分支感知
 
-一台机器上应该可以同时容纳多棵全局上下文树，而且彼此不混在一起。
-这也是为什么 `gctree` 使用 `checkout`、`checkout -b` 这类类似 Git 的语言，同时在面向用户的表达里把当前分支称为 **gc-branch**。
+一台机器应该能够同时持有多个全局上下文树，且互不混淆。
+这就是为什么 `gctree` 使用 `checkout` 和 `checkout -b` 这样类似 git 的语言，同时在面向用户的文案中将活跃分支称为 **gc-branch**。
 
-## 2. 让 repo scope 保持显式
+## 2. 明确仓库作用范围
 
-gc-branch 不应该悄悄影响机器上的每一个仓库。
-`gctree` 用 `branch-repo-map.json` 来记录一个仓库对于某条 gc-branch 处于哪种状态：
+gc-branch 不应该悄无声息地影响机器上的每一个代码仓库。
+`gctree` 使用 `branch-repo-map.json` 来记录某个代码仓库的状态：
 
-- 被该 gc-branch 包含
-- 被该 gc-branch 排除
-- 还没有映射
+- 已包含在某个 gc-branch 中
+- 已从某个 gc-branch 中排除
+- 尚未映射
 
-如果从一个尚未映射的仓库里调用 `resolve`，用户可以决定是只继续这一次、以后都在这里使用该 gc-branch，还是在这里忽略它。
+如果从未映射的代码仓库调用 `resolve`，用户可以决定是继续一次、始终在该仓库使用此 gc-branch，还是在该仓库忽略它。
 
-## 3. 让 `index.md` 保持轻量
+## 3. 保持 `index.md` 精简
 
-顶层的 `index.md` 是索引，不是内容倾倒区。
-它的职责是帮助工具和人快速找到正确的 source 文档。
-所以它应该保持紧凑、以链接为主，而不是把完整知识大段复制进去。
+顶层 `index.md` 是索引，而非内容转储。
+它的职责是帮助工具和人员快速找到正确的源文档。
+它应保持在 **2000 字符**以内，以链接为主，而不是将完整知识内联复制进来。
 
-## 4. 让 source 文档遵循 summary-first
+## 4. 让源文档以摘要为先
 
-每一份 source-of-truth markdown 文档，都应该在靠前的位置带上 `## Summary` 段落。
-这样下游工具就有一条快速路径：先读短版本，只有确实需要更多细节时再继续展开。
+每个作为可信来源的 Markdown 文档都应在靠近顶部的位置包含一个 `## Summary` 部分。
+这为下游工具提供了一条快速路径：先读取简短版本，只有在真正需要更多细节时才展开阅读。
 
 ## 5. 让 onboarding 明确且有引导
 
-为了创建一棵有用的上下文树，用户不应该被迫手写 onboarding JSON。
-`gctree init` 和 `gctree onboard` 应该围绕用户偏好的 provider 提供引导，并把结果写入当前激活的 gc-branch。
+用户不应该仅仅为了创建一个有用的上下文树而手动编写 onboarding JSON。
+`gctree init` 和 `gctree onboard` 应该引导用户选择首选的提供商，并将生成的上下文写入活跃的 gc-branch。
 
-onboarding 只适用于空的 gc-branch。
-如果某条 gc-branch 已经包含上下文，正确的路径只有两种：
+Onboarding 仅适用于空的 gc-branch。
+如果一个 gc-branch 已经包含上下文，正确的做法是：
 
-- 重置这条 gc-branch，然后重新 onboarding
-- 或者执行一次带引导的长期更新
+- 重置该 gc-branch 并重新 onboard
+- 或者执行一次有引导的持久化更新
 
-## 6. 让长期更新保持有意图
+## 6. 让持久化更新保持刻意为之
 
-长期上下文不应该因为意外或隐藏式记忆而发生变化。
-更新流程必须是显式的、由 provider 驱动的，并且明确绑定到当前激活的 gc-branch 上。
+持久化上下文不应该因意外或隐藏记忆而发生变更。
+更新流程应该是显式的、由提供商驱动的，并与当前活跃的 gc-branch 绑定。
+
+## 7. 只注入相关内容
+
+工具会话不应收到整个知识库。
+`gctree resolve` 对文档与查询进行评分，只返回匹配的文档——包含标题、摘要和摘录。只有在摘要不足时才读取完整文档。
+
+实际上，每次查询注入的上下文约占总存储量的 4%。其余 96% 保留在磁盘上，不进入 token 窗口，直到真正需要时才读取。
+
+## 8. 保持提供商无关性
+
+`gctree` 将上下文存储在任何工具都能读取的纯 Markdown 文件中。
+Claude Code 和 Codex 都通过 `gctree scaffold` 对接同一个底层存储。
+添加对新提供商的支持，意味着编写一个新的 scaffold 模板——无需对核心存储或 resolve 逻辑做任何修改。

package/docs/usage.es.md

@@ -4,45 +4,71 @@
 
 ## Resumen
 
-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.
+Un flujo de trabajo estándar con `gctree` tiene este aspecto: inicializar gc-tree, elegir un proveedor, hacer onboarding de la gc-branch `main` predeterminada, hacer resolve del contexto que necesitas, crear nuevas gc-branches cuando el trabajo merece su propio carril, mapear los repositorios a las gc-branches correctas y usar actualizaciones guiadas para cambios duraderos más adelante.
 
-## Flujo estándar
+## Flujo de trabajo 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 un idioma personalizado)
-4. si elegiste `both`, decide qué provider debe iniciar este onboarding
-5. completa el onboarding guiado del gc-branch `main`
-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 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
+1. ejecutar `gctree init`
+2. elegir el modo de proveedor preferido (`claude-code`, `codex` o `both`)
+3. elegir el idioma de trabajo (`English`, `Korean` o un idioma personalizado)
+4. si elegiste `both`, elegir qué proveedor debe iniciar el onboarding ahora
+5. completar el onboarding guiado para la gc-branch `main` predeterminada
+6. hacer resolve del contexto relevante con `gctree resolve --query "..."`
+7. crear o cambiar de gc-branch con `gctree checkout`
+8. ejecutar `gctree onboard` solo para una gc-branch vacía
+9. usar el mapeo de alcance del repositorio para que una gc-branch solo aplique donde corresponde
+10. usar `gctree update-global-context` para cambios duraderos más adelante
 
-## Comandos clave
+## Comandos principales
 
 | Comando | Propósito |
 | --- | --- |
-| `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 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` | 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 repo scope
-
-Supón que el gc-branch `A` es relevante para los repos `B`, `C` y `D`, pero no para `F`.
-
-Puedes gestionarlo así:
+| `gctree init` | Crear `~/.gctree`, crear la gc-branch `main` predeterminada, guardar el modo de proveedor, el proveedor de onboarding y el idioma preferido, hacer scaffold del entorno actual y comenzar el onboarding guiado cuando `main` está vacía. |
+| `gctree checkout <branch>` | Cambiar la gc-branch activa. |
+| `gctree checkout -b <branch>` | Crear y cambiar a una nueva gc-branch vacía. |
+| `gctree branches` | Listar las gc-branches disponibles y mostrar la activa. |
+| `gctree status` | Mostrar la gc-branch activa, el repositorio actual, el estado del alcance del repositorio actual, advertencias y el proveedor preferido. |
+| `gctree resolve --query TEXT` | Buscar contexto en la gc-branch relevante. Si el repositorio actual no está mapeado, `gctree` puede preguntar cómo debe tratarse ese repositorio. |
+| `gctree repo-map` | Mostrar el contenido actual de `branch-repo-map.json`. |
+| `gctree set-repo-scope --branch <name> --include` | Marcar el repositorio actual como incluido para esa gc-branch. |
+| `gctree set-repo-scope --branch <name> --exclude` | Marcar el repositorio actual como ignorado para esa gc-branch. |
+| `gctree onboard` | Iniciar el onboarding guiado para la gc-branch activa. Solo funciona cuando esa gc-branch está vacía. |
+| `gctree reset-gc-branch --branch <name> --yes` | Limpiar una gc-branch para poder hacer onboarding de nuevo. |
+| `gctree update-global-context` | Iniciar una actualización duradera guiada para la gc-branch activa. |
+| `gctree update-gc` / `gctree ugc` | Alias para `gctree update-global-context`. |
+| `gctree scaffold --host <codex\|claude-code>` | Instalar la interfaz de comandos orientada al proveedor en otro entorno. |
+
+## Qué devuelve resolve
+
+`gctree resolve` puntúa cada documento de la gc-branch activa contra tu consulta y devuelve solo los que coinciden. Las coincidencias en el título cuentan el doble que las coincidencias en el cuerpo.
+
+```bash
+gctree resolve --query "auth token rotation policy"
+```
+
+```json
+{
+  "gc_branch": "main",
+  "query": "auth token rotation policy",
+  "matches": [
+    {
+      "title": "Auth & Session Conventions",
+      "path": "docs/auth.md",
+      "score": 4,
+      "summary": "JWT rotation on every request, refresh tokens in httpOnly cookies, 15-min access token TTL",
+      "excerpt": "## Auth Flow\nAccess token: 15-min TTL, rotated on every authenticated request..."
+    }
+  ]
+}
+```
+
+La herramienta recibe primero el resumen y el fragmento. Lee el documento completo en `path` solo cuando el resumen no es suficiente. Una consulta que no coincide con nada devuelve `"matches": []`.
+
+## Ejemplo de flujo de alcance del repositorio
+
+Supongamos que la gc-branch `A` es relevante para los repositorios `B`, `C` y `D`, pero no para `F`.
+
+Puedes gestionarlo mediante:
 
 ```json
 {
@@ -53,19 +79,19 @@ Puedes gestionarlo así:
 }
 ```
 
-Guardado en:
+almacenado en:
 
 ```text
 ~/.gctree/branch-repo-map.json
 ```
 
-Cuando ejecutas `resolve` desde el repo `E` y la rama `A` todavía no está mapeada allí, `gctree` puede preguntarte si quieres:
+Cuando `resolve` se ejecuta desde el repositorio `E` y la branch `A` todavía no está mapeada allí, `gctree` puede preguntar si:
 
-1. continuar solo esta vez
+1. continuar una vez
 2. usar siempre `A` en `E`
 3. ignorar `A` en `E`
 
-## Ejemplo de primera ejecución
+## Ejemplo de flujo en la primera ejecución
 
 ```bash
 gctree init
@@ -73,11 +99,11 @@ gctree init
 
 Luego:
 
-1. elige `codex` o `claude-code`
-2. deja que `gctree` haga scaffold del entorno actual
-3. completa el onboarding guiado del gc-branch `main`
+1. elegir `codex` o `claude-code`
+2. dejar que `gctree` haga scaffold del entorno actual
+3. completar el onboarding guiado para la gc-branch `main`
 
-## Ejemplo con varias ramas
+## Ejemplo de flujo con múltiples branches
 
 ```bash
 gctree checkout -b client-b
@@ -85,7 +111,7 @@ gctree onboard
 gctree resolve --query "billing retry policy"
 ```
 
-## Ejemplo de actualización
+## Ejemplo de flujo de actualización
 
 ```bash
 gctree update-global-context
@@ -98,24 +124,46 @@ gctree update-gc
 gctree ugc
 ```
 
-Si un repo recién relevante también debería formar parte del contexto duradero, el flujo natural es:
+Si un repositorio recién relevante también debería pasar a formar parte del contexto duradero, el flujo natural es:
 
-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
+1. mapear ese repositorio a la gc-branch
+2. luego ejecutar `update-global-context` para agregar conocimiento duradero sobre qué hace ese repositorio y por qué es importante
 
 ## Patrones de integración
 
 ### Codex CLI / Claude Code CLI
 
-`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.
+`gctree scaffold` instala archivos de comandos orientados al proveedor en el directorio de destino.
 
 ```bash
 gctree scaffold --host codex --target /path/to/repo
 gctree scaffold --host claude-code --target /path/to/repo
+gctree scaffold --host both --target /path/to/repo
+```
+
+**Archivos escritos para `--host codex`:**
+
+```
+AGENTS.md                                  ← fragmento de gctree añadido a las instrucciones del agente
+.codex/prompts/gctree-bootstrap.md         ← contexto de arranque para las sesiones de Codex
+.codex/skills/gc-resolve-context/SKILL.md  ← skill de resolve
+.codex/skills/gc-onboard/SKILL.md          ← skill de onboarding
+.codex/skills/gc-update-global-context/SKILL.md  ← skill de actualización
 ```
 
-### Comportamiento en runtime
+**Archivos escritos para `--host claude-code`:**
+
+```
+CLAUDE.md                                        ← fragmento de gctree añadido
+.claude/hooks/gctree-session-start.md            ← hook de inicio de sesión
+.claude/commands/gc-resolve-context.md           ← comando slash de resolve
+.claude/commands/gc-onboard.md                   ← comando slash de onboard
+.claude/commands/gc-update-global-context.md     ← comando slash de actualización
+```
+
+Los archivos existentes no se modifican a menos que pases `--force`.
+
+### Comportamiento en tiempo de ejecución
 
-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í.
+La gc-branch activa es la apuntada por `HEAD` dentro de `~/.gctree`, pero el mapeo del repositorio puede anular ese valor predeterminado cuando un repositorio está vinculado explícitamente a otra gc-branch.
+Esto hace que gc-tree sea práctico para usuarios avanzados que mantienen muchas sesiones no relacionadas abiertas al mismo tiempo.