@handsupmin/gc-tree 0.2.0 → 0.3.0

package/docs/usage.ko.md

@@ -1,48 +1,74 @@
-# 사용 방법
+# 사용법
 
 [English](usage.md) | [한국어](usage.ko.md) | [简体中文](usage.zh.md) | [日本語](usage.ja.md) | [Español](usage.es.md)
 
 ## 요약
 
-표준적인 `gctree` 흐름은 이렇습니다. gc-tree를 초기화하고, provider를 고르고, 기본 `main` gc-branch를 온보딩하고, 필요한 컨텍스트를 resolve로 불러오고, 필요할 때 새 gc-branch를 만들고, 각 레포를 맞는 gc-branch에 매핑하고, 나중에는 가이드형 업데이트로 장기 컨텍스트를 유지합니다.
+표준 `gctree` 워크플로우는 다음과 같습니다: gc-tree 초기화, 프로바이더 선택, 기본 `main` gc-branch 온보딩, 필요한 컨텍스트 resolve, 작업별로 새 gc-branch 생성, 저장소를 올바른 gc-branch에 매핑, 이후 지속 변경 시 안내된 업데이트 사용.
 
-## 기본 워크플로
+## 표준 워크플로우
 
 1. `gctree init` 실행
-2. 선호하는 provider 모드 선택 (`claude-code`, `codex`, `both`)
-3. 워크플로 언어 선택 (`English`, `Korean`, 또는 커스텀 언어)
-4. `both`를 골랐다면 이번 온보딩을 어느 provider로 시작할지 선택
-5. 기본 `main` gc-branch에 대한 가이드형 온보딩 완료
-6. `gctree resolve --query "..."`로 필요한 컨텍스트 조회
+2. 선호하는 프로바이더 모드 선택 (`claude-code`, `codex`, 또는 `both`)
+3. 워크플로우 언어 선택 (`English`, `Korean`, 또는 커스텀 언어)
+4. `both`를 선택한 경우, 지금 온보딩을 시작할 프로바이더 선택
+5. 기본 `main` gc-branch의 안내된 온보딩 완료
+6. `gctree resolve --query "..."`로 관련 컨텍스트 resolve
 7. `gctree checkout`으로 gc-branch 생성 또는 전환
-8. `gctree onboard`는 비어 있는 gc-branch에서만 실행
-9. repo scope 매핑으로 gc-branch가 자기 레포에서만 적용되게 유지
-10. 장기 변경은 나중에 `gctree update-global-context`로 반영
+8. 빈 gc-branch에만 `gctree onboard` 실행
+9. 저장소 범위 매핑으로 gc-branch가 해당하는 곳에만 적용되도록 설정
+10. 이후 지속 변경에는 `gctree update-global-context` 사용
 
-## 핵심 명령
+## 핵심 명령어
 
-| 명령 | 용도 |
+| 명령어 | 설명 |
 | --- | --- |
-| `gctree init` | `~/.gctree`를 만들고, 기본 `main` gc-branch를 만들고, provider 모드/온보딩 provider/선호 언어를 저장하고, 현재 환경을 스캐폴딩하고, `main`이 비어 있으면 가이드형 온보딩까지 시작합니다. |
-| `gctree checkout <branch>` | 활성 gc-branch를 전환합니다. |
-| `gctree checkout -b <branch>` | 새로운 빈 gc-branch를 만들고 바로 전환합니다. |
-| `gctree branches` | 사용 가능한 gc-branch 목록과 현재 활성 브랜치를 보여줍니다. |
-| `gctree status` | 활성 gc-branch, 현재 레포, 현재 repo-scope 상태, 경고, 선호 provider를 보여줍니다. |
-| `gctree resolve --query TEXT` | 관련 gc-branch에서 컨텍스트를 찾습니다. 현재 레포가 아직 매핑되지 않았다면, 이 레포를 어떻게 다룰지 물어볼 수 있습니다. |
-| `gctree repo-map` | 현재 `branch-repo-map.json` 내용을 보여줍니다. |
-| `gctree set-repo-scope --branch <name> --include` | 현재 레포를 해당 gc-branch에 포함된 것으로 표시합니다. |
-| `gctree set-repo-scope --branch <name> --exclude` | 현재 레포를 해당 gc-branch에서 무시할 레포로 표시합니다. |
-| `gctree onboard` | 활성 gc-branch에 대한 가이드형 온보딩을 시작합니다. 이 gc-branch가 비어 있을 때만 동작합니다. |
-| `gctree reset-gc-branch --branch <name> --yes` | gc-branch를 비워서 다시 온보딩할 수 있게 만듭니다. |
-| `gctree update-global-context` | 활성 gc-branch에 대한 가이드형 장기 업데이트를 시작합니다. |
-| `gctree update-gc` / `gctree ugc` | `gctree update-global-context`의 별칭입니다. |
-| `gctree scaffold --host <codex|claude-code>` | 다른 환경에도 provider용 명령 표면을 설치합니다. |
-
-## repo scope 예시 흐름
-
-gc-branch `A`가 `B`, `C`, `D` 레포에는 관련 있고 `F`에는 관련이 없다고 가정해봅시다.
-
-이 경우 다음 같은 구조로 관리할 수 있습니다.
+| `gctree init` | `~/.gctree` 생성, 기본 `main` gc-branch 생성, 프로바이더 모드·온보딩 프로바이더·선호 언어 저장, 현재 환경 scaffold, `main`이 비어 있으면 안내된 온보딩 시작. |
+| `gctree checkout <branch>` | 활성 gc-branch 전환. |
+| `gctree checkout -b <branch>` | 새 빈 gc-branch를 생성하고 전환. |
+| `gctree branches` | 사용 가능한 gc-branch 목록 표시 및 현재 활성 브랜치 표시. |
+| `gctree status` | 활성 gc-branch, 현재 저장소, 현재 저장소 범위 상태, 경고, 선호 프로바이더 표시. |
+| `gctree resolve --query TEXT` | 관련 gc-branch에서 컨텍스트 검색. 현재 저장소가 매핑되지 않은 경우, `gctree`가 해당 저장소 처리 방법을 물어볼 수 있습니다. |
+| `gctree repo-map` | `branch-repo-map.json`의 현재 내용 표시. |
+| `gctree set-repo-scope --branch <name> --include` | 현재 저장소를 해당 gc-branch에 포함으로 표시. |
+| `gctree set-repo-scope --branch <name> --exclude` | 현재 저장소를 해당 gc-branch에서 무시로 표시. |
+| `gctree onboard` | 활성 gc-branch의 안내된 온보딩 실행. 해당 gc-branch가 비어 있을 때만 동작. |
+| `gctree reset-gc-branch --branch <name> --yes` | gc-branch를 초기화하여 다시 온보딩할 수 있게 함. |
+| `gctree update-global-context` | 활성 gc-branch의 안내된 지속 업데이트 실행. |
+| `gctree update-gc` / `gctree ugc` | `gctree update-global-context`의 별칭. |
+| `gctree scaffold --host <codex\|claude-code>` | 다른 환경에 프로바이더 대면 명령 표면 설치. |
+
+## resolve가 반환하는 것
+
+`gctree resolve`는 활성 gc-branch의 모든 문서를 쿼리에 대해 점수를 매기고 매칭된 것만 반환합니다. 제목 매칭은 본문 매칭보다 두 배의 가중치를 가집니다.
+
+```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..."
+    }
+  ]
+}
+```
+
+도구는 먼저 요약과 발췌문을 받습니다. 요약만으로 충분하지 않을 때만 `path`의 전체 문서를 읽습니다. 아무것도 매칭되지 않는 쿼리는 `"matches": []`를 반환합니다.
+
+## 저장소 범위 설정 예시 흐름
+
+gc-branch `A`가 저장소 `B`, `C`, `D`에는 관련되지만 `F`에는 관련 없다고 가정합니다.
+
+다음과 같이 관리할 수 있습니다:
 
 ```json
 {
@@ -53,31 +79,31 @@ gc-branch `A`가 `B`, `C`, `D` 레포에는 관련 있고 `F`에는 관련이
 }
 ```
 
-이 정보는 다음 위치에 저장됩니다.
+저장 위치:
 
 ```text
 ~/.gctree/branch-repo-map.json
 ```
 
-`E` 레포에서 `resolve`를 실행했는데 branch `A`가 아직 거기에 매핑되지 않았다면, `gctree`는 다음 중 무엇을 할지 물어볼 수 있습니다.
+저장소 `E`에서 `resolve`를 실행할 때 브랜치 `A`가 아직 매핑되지 않은 경우, `gctree`가 다음 중 하나를 선택하도록 물어볼 수 있습니다:
 
-1. 이번만 계속하기
-2. `E`에서는 앞으로도 항상 `A` 사용하기
-3. `E`에서는 `A` 무시하기
+1. 한 번만 계속 진행
+2. `E`에서 항상 `A` 사용
+3. `E`에서 `A` 무시
 
-## 첫 실행 예시
+## 최초 실행 예시 흐름
 
 ```bash
 gctree init
 ```
 
-그다음:
+이후:
 
 1. `codex` 또는 `claude-code` 선택
-2. `gctree`가 현재 환경을 스캐폴딩하도록 두기
-3. `main` gc-branch에 대한 가이드형 온보딩 완료
+2. `gctree`가 현재 환경을 scaffold하도록 허용
+3. `main` gc-branch의 안내된 온보딩 완료
 
-## 여러 브랜치를 쓰는 예시
+## 다중 브랜치 예시 흐름
 
 ```bash
 gctree checkout -b client-b
@@ -85,37 +111,61 @@ gctree onboard
 gctree resolve --query "billing retry policy"
 ```
 
-## 업데이트 예시
+## 업데이트 예시 흐름
 
 ```bash
 gctree update-global-context
 ```
 
-짧은 별칭:
+단축 별칭:
 
 ```bash
 gctree update-gc
 gctree ugc
 ```
 
-새롭게 중요해진 레포를 장기 컨텍스트에도 포함시키고 싶다면, 자연스러운 흐름은 이렇습니다.
+새로 관련이 생긴 저장소를 지속 컨텍스트에도 포함해야 한다면, 자연스러운 흐름은 다음과 같습니다:
 
-1. 먼저 그 레포를 gc-branch에 매핑하고
-2. 그다음 `update-global-context`를 실행해서 그 레포가 무엇을 하는지, 왜 중요한지 같은 장기 지식을 추가하기
+1. 해당 저장소를 gc-branch에 매핑
+2. `update-global-context`를 실행하여 해당 저장소가 무엇을 하고 왜 중요한지에 대한 지속 지식 추가
 
 ## 통합 패턴
 
 ### Codex CLI / Claude Code CLI
 
-`gctree scaffold`는 가이드형 온보딩, 가이드형 업데이트 같은 provider 명령 표면을 설치합니다.
-이 명령들은 장기 컨텍스트를 수집하거나 반영하기 전에 현재 활성 gc-branch가 무엇인지 명시적으로 말해야 하고, 사용자가 따로 바꾸라고 하지 않는 한 저장된 워크플로 언어를 계속 사용해야 합니다.
+`gctree scaffold`는 대상 디렉토리에 프로바이더 대면 명령 파일을 설치합니다.
 
 ```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
+```
+
+**`--host codex`로 작성되는 파일:**
+
+```
+AGENTS.md                                  ← 에이전트 지시사항에 gctree 스니펫 추가
+.codex/hooks.json                         ← SessionStart/UserPromptSubmit 자동 resolve 훅
+.codex/prompts/gctree-bootstrap.md         ← Codex 세션의 부트스트랩 컨텍스트
+.codex/skills/gc-resolve-context/SKILL.md  ← resolve 스킬
+.codex/skills/gc-onboard/SKILL.md          ← 온보딩 스킬
+.codex/skills/gc-update-global-context/SKILL.md  ← 업데이트 스킬
 ```
 
+**`--host claude-code`로 작성되는 파일:**
+
+```
+CLAUDE.md                                        ← gctree 스니펫 추가
+.claude/hooks/hooks.json                         ← SessionStart/UserPromptSubmit 자동 resolve 훅
+.claude/hooks/gctree-session-start.md            ← 세션 시작 fallback 메모
+.claude/commands/gc-resolve-context.md           ← resolve 슬래시 명령
+.claude/commands/gc-onboard.md                   ← onboard 슬래시 명령
+.claude/commands/gc-update-global-context.md     ← 업데이트 슬래시 명령
+```
+
+`--force`를 전달하지 않으면 기존 파일은 그대로 유지됩니다.
+
 ### 런타임 동작
 
-기본적으로 활성 gc-branch는 `~/.gctree` 안의 `HEAD`가 가리키는 브랜치입니다. 다만 특정 레포가 다른 gc-branch에 명시적으로 묶여 있다면 repo mapping이 그 기본값을 덮어쓸 수 있습니다.
-덕분에 서로 무관한 세션을 많이 동시에 띄워두는 사용자에게도 gc-tree가 실용적으로 동작합니다.
+활성 gc-branch는 `~/.gctree` 내의 `HEAD`가 가리키는 브랜치이지만, 저장소가 다른 gc-branch에 명시적으로 바인딩된 경우 저장소 매핑이 해당 폴백을 재정의할 수 있습니다.
+이를 통해 관련 없는 여러 세션을 동시에 열어두는 헤비 유저에게도 gc-tree가 실용적으로 동작합니다.

package/docs/usage.md

@@ -36,7 +36,33 @@ A standard `gctree` workflow looks like this: initialize gc-tree, choose a provi
 | `gctree reset-gc-branch --branch <name> --yes` | Clear a gc-branch so it can be onboarded again. |
 | `gctree update-global-context` | Launch a guided durable update for the active gc-branch. |
 | `gctree update-gc` / `gctree ugc` | Aliases for `gctree update-global-context`. |
-| `gctree scaffold --host <codex|claude-code>` | Install the provider-facing command surface in another environment. |
+| `gctree scaffold --host <codex\|claude-code>` | Install the provider-facing command surface in another environment. |
+
+## What resolve returns
+
+`gctree resolve` scores every document in the active gc-branch against your query and returns only the matching ones. Title matches count twice as much as body matches.
+
+```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..."
+    }
+  ]
+}
+```
+
+The tool receives the summary and excerpt first. It reads the full document at `path` only when the summary is not enough. A query that matches nothing returns `"matches": []`.
 
 ## Example repo-scope flow
 
@@ -107,14 +133,38 @@ If a newly relevant repo should also become part of the durable context, the nat
 
 ### Codex CLI / Claude Code CLI
 
-`gctree scaffold` installs provider-facing commands such as guided onboarding and guided updates.
-Those commands should explicitly mention the current active gc-branch before they start gathering or applying durable context, and they should keep using the saved workflow language unless the user explicitly asks to switch.
+`gctree scaffold` installs provider-facing command files into the target directory.
 
 ```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
+```
+
+**Files written for `--host codex`:**
+
+```
+AGENTS.md                                  ← gctree snippet appended to agent instructions
+.codex/hooks.json                         ← SessionStart/UserPromptSubmit auto-resolve hooks
+.codex/prompts/gctree-bootstrap.md         ← bootstrap context for Codex sessions
+.codex/skills/gc-resolve-context/SKILL.md  ← resolve skill
+.codex/skills/gc-onboard/SKILL.md          ← onboarding skill
+.codex/skills/gc-update-global-context/SKILL.md  ← update skill
 ```
 
+**Files written for `--host claude-code`:**
+
+```
+CLAUDE.md                                        ← gctree snippet appended
+.claude/hooks/hooks.json                         ← SessionStart/UserPromptSubmit auto-resolve hooks
+.claude/hooks/gctree-session-start.md            ← session-start fallback note
+.claude/commands/gc-resolve-context.md           ← resolve slash command
+.claude/commands/gc-onboard.md                   ← onboard slash command
+.claude/commands/gc-update-global-context.md     ← update slash command
+```
+
+Existing files are left untouched unless you pass `--force`.
+
 ### Runtime behavior
 
 The active gc-branch is the one pointed to by `HEAD` inside `~/.gctree`, but repo mapping can override that fallback when a repository is explicitly bound to another gc-branch.

package/docs/usage.zh.md

@@ -1,48 +1,74 @@
-# 使用方法
+# 使用指南
 
 [English](usage.md) | [한국어](usage.ko.md) | [简体中文](usage.zh.md) | [日本語](usage.ja.md) | [Español](usage.es.md)
 
-## 摘要
+## 概述
 
-标准的 `gctree` 工作流大致是这样的：先初始化 gc-tree，选择 provider，为默认的 `main` gc-branch 完成 onboarding，用 resolve 拉取当前需要的上下文，在需要的时候创建新的 gc-branch，把仓库映射到正确的 gc-branch，后续再通过带引导的更新来维护长期上下文。
+标准的 `gctree` 工作流如下：初始化 gc-tree、选择提供商、对默认的 `main` gc-branch 执行 onboard、解析所需上下文、在工作需要独立空间时创建新的 gc-branch、将代码仓库映射到正确的 gc-branch，以及在后续使用有引导的更新流程进行持久化变更。
 
 ## 标准工作流
 
 1. 运行 `gctree init`
-2. 选择你偏好的 provider 模式（`claude-code`、`codex` 或 `both`）
+2. 选择首选的提供商模式（`claude-code`、`codex` 或 `both`）
 3. 选择工作流语言（`English`、`Korean` 或自定义语言）
-4. 如果你选择了 `both`，再决定这次 onboarding 由哪个 provider 先启动
-5. 完成默认 `main` gc-branch 的引导式 onboarding
-6. 用 `gctree resolve --query "..."` 拉取相关上下文
-7. 用 `gctree checkout` 创建或切换 gc-branch
-8. `gctree onboard` 只用于空的 gc-branch
-9. 通过 repo scope 映射，让 gc-branch 只在它该生效的仓库里生效
-10. 之后的长期变化用 `gctree update-global-context` 来补充
+4. 如果选择了 `both`，选择哪个提供商现在开始 onboarding
+5. 对默认的 `main` gc-branch 完成有引导的 onboarding
+6. 使用 `gctree resolve --query "..."` 解析相关上下文
+7. 使用 `gctree checkout` 创建或切换 gc-branch
+8. 仅对空的 gc-branch 运行 `gctree onboard`
+9. 使用仓库作用范围映射，使 gc-branch 只在其适用的地方生效
+10. 使用 `gctree update-global-context` 进行后续的持久化变更
 
 ## 核心命令
 
 | 命令 | 用途 |
 | --- | --- |
-| `gctree init` | 创建 `~/.gctree`，创建默认 `main` gc-branch，保存 provider 模式 / onboarding provider / 偏好语言，为当前环境安装 scaffold，并在 `main` 为空时启动引导式 onboarding。 |
-| `gctree checkout <branch>` | 切换当前激活的 gc-branch。 |
-| `gctree checkout -b <branch>` | 创建一个新的空 gc-branch 并立即切换过去。 |
-| `gctree branches` | 列出可用的 gc-branch，并标出当前激活的是哪一个。 |
-| `gctree status` | 显示当前 gc-branch、当前仓库、当前 repo-scope 状态、告警以及偏好的 provider。 |
-| `gctree resolve --query TEXT` | 从相关 gc-branch 中搜索上下文。如果当前仓库还没有映射，`gctree` 可能会询问应该如何处理这个仓库。 |
-| `gctree repo-map` | 显示当前 `branch-repo-map.json` 的内容。 |
-| `gctree set-repo-scope --branch <name> --include` | 把当前仓库标记为该 gc-branch 的包含仓库。 |
-| `gctree set-repo-scope --branch <name> --exclude` | 把当前仓库标记为该 gc-branch 下应忽略的仓库。 |
-| `gctree onboard` | 为当前激活的 gc-branch 启动引导式 onboarding。只有在该 gc-branch 为空时才可用。 |
-| `gctree reset-gc-branch --branch <name> --yes` | 清空某条 gc-branch，让它可以重新 onboarding。 |
-| `gctree update-global-context` | 为当前激活的 gc-branch 启动一次带引导的长期更新。 |
-| `gctree update-gc` / `gctree ugc` | `gctree update-global-context` 的简短别名。 |
-| `gctree scaffold --host <codex|claude-code>` | 在其他环境里安装 provider 对应的命令表面。 |
-
-## repo scope 示例流程
-
-假设 gc-branch `A` 与仓库 `B`、`C`、`D` 相关，但与 `F` 无关。
-
-你可以这样管理：
+| `gctree init` | 创建 `~/.gctree`，创建默认的 `main` gc-branch，保存提供商模式、onboarding 提供商及首选语言，scaffold 当前环境，并在 `main` 为空时启动有引导的 onboarding。 |
+| `gctree checkout <branch>` | 切换活跃的 gc-branch。 |
+| `gctree checkout -b <branch>` | 创建并切换到一个新的空 gc-branch。 |
+| `gctree branches` | 列出可用的 gc-branch 并显示当前活跃的那个。 |
+| `gctree status` | 显示活跃的 gc-branch、当前仓库、当前仓库的作用范围状态、警告信息及首选提供商。 |
+| `gctree resolve --query TEXT` | 在相关的 gc-branch 中搜索上下文。如果当前仓库尚未映射，`gctree` 会询问该如何处理这个仓库。 |
+| `gctree repo-map` | 显示 `branch-repo-map.json` 的当前内容。 |
+| `gctree set-repo-scope --branch <name> --include` | 将当前仓库标记为该 gc-branch 的包含仓库。 |
+| `gctree set-repo-scope --branch <name> --exclude` | 将当前仓库标记为该 gc-branch 的忽略仓库。 |
+| `gctree onboard` | 为活跃的 gc-branch 启动有引导的 onboarding。仅当该 gc-branch 为空时有效。 |
+| `gctree reset-gc-branch --branch <name> --yes` | 清空一个 gc-branch，使其可以重新 onboard。 |
+| `gctree update-global-context` | 为活跃的 gc-branch 启动有引导的持久化更新。 |
+| `gctree update-gc` / `gctree ugc` | `gctree update-global-context` 的别名。 |
+| `gctree scaffold --host <codex\|claude-code>` | 在另一个环境中安装面向提供商的命令接口。 |
+
+## resolve 返回的内容
+
+`gctree resolve` 对活跃 gc-branch 中的每个文档与查询内容进行评分，只返回匹配的文档。标题匹配的权重是正文匹配的两倍。
+
+```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..."
+    }
+  ]
+}
+```
+
+工具首先接收摘要和摘录。只有在摘要不足以满足需求时，才会读取 `path` 指向的完整文档。如果查询没有任何匹配，则返回 `"matches": []`。
+
+## 仓库作用范围示例流程
+
+假设 gc-branch `A` 与代码仓库 `B`、`C` 和 `D` 相关，但与 `F` 无关。
+
+可以通过以下方式管理：
 
 ```json
 {
@@ -53,19 +79,19 @@
 }
 ```
 
-这份配置保存在：
+存储在：
 
 ```text
 ~/.gctree/branch-repo-map.json
 ```
 
-当你在仓库 `E` 中执行 `resolve`，而 branch `A` 还没有映射到这里时，`gctree` 可以询问你是否要：
+当 `resolve` 在代码仓库 `E` 中运行，而分支 `A` 尚未在 `E` 中映射时，`gctree` 会询问：
 
-1. 只这一次继续
-2. 以后在 `E` 中始终使用 `A`
+1. 继续一次
+2. 始终在 `E` 中使用 `A`
 3. 在 `E` 中忽略 `A`
 
-## 首次运行示例
+## 首次运行示例流程
 
 ```bash
 gctree init
@@ -74,10 +100,10 @@ gctree init
 然后：
 
 1. 选择 `codex` 或 `claude-code`
-2. 让 `gctree` 为当前环境安装 scaffold
-3. 完成 `main` gc-branch 的引导式 onboarding
+2. 让 `gctree` scaffold 当前环境
+3. 对 `main` gc-branch 完成有引导的 onboarding
 
-## 多分支示例
+## 多分支示例流程
 
 ```bash
 gctree checkout -b client-b
@@ -85,7 +111,7 @@ gctree onboard
 gctree resolve --query "billing retry policy"
 ```
 
-## 更新示例
+## 更新示例流程
 
 ```bash
 gctree update-global-context
@@ -98,24 +124,48 @@ gctree update-gc
 gctree ugc
 ```
 
-如果某个新变得重要的仓库也应该进入长期上下文，更自然的流程是：
+如果一个新相关的代码仓库也需要成为持久化上下文的一部分，自然的流程是：
 
-1. 先把这个仓库映射到对应的 gc-branch
-2. 再执行 `update-global-context`，补充这个仓库做什么、为什么重要等长期知识
+1. 将该仓库映射到 gc-branch
+2. 然后运行 `update-global-context`，添加关于该仓库用途及重要性的持久化知识
 
 ## 集成模式
 
 ### Codex CLI / Claude Code CLI
 
-`gctree scaffold` 会安装面向 provider 的命令表面，比如引导式 onboarding 和引导式更新。
-这些命令在开始收集或应用长期上下文之前，都应该明确说明当前激活的是哪条 gc-branch，并且除非用户明确要求切换，否则应继续使用已经保存的工作流语言。
+`gctree scaffold` 将面向提供商的命令文件安装到目标目录中。
 
 ```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
+```
+
+**`--host codex` 写入的文件：**
+
+```
+AGENTS.md                                  ← gctree 代码片段追加到 agent 指令中
+.codex/hooks.json                         ← SessionStart / UserPromptSubmit 自动 resolve hook
+.codex/prompts/gctree-bootstrap.md         ← Codex 会话的引导上下文
+.codex/skills/gc-resolve-context/SKILL.md  ← resolve 技能
+.codex/skills/gc-onboard/SKILL.md          ← onboarding 技能
+.codex/skills/gc-update-global-context/SKILL.md  ← 更新技能
 ```
 
+**`--host claude-code` 写入的文件：**
+
+```
+CLAUDE.md                                        ← gctree 代码片段追加
+.claude/hooks/hooks.json                         ← SessionStart / UserPromptSubmit 自动 resolve hook
+.claude/hooks/gctree-session-start.md            ← 会话启动 fallback 说明
+.claude/commands/gc-resolve-context.md           ← resolve 斜杠命令
+.claude/commands/gc-onboard.md                   ← onboard 斜杠命令
+.claude/commands/gc-update-global-context.md     ← 更新斜杠命令
+```
+
+除非传入 `--force`，否则已有文件不会被修改。
+
 ### 运行时行为
 
-默认情况下，激活的 gc-branch 是 `~/.gctree` 中 `HEAD` 指向的那一条。但如果某个仓库被显式绑定到了另一条 gc-branch，repo mapping 就可以覆盖这个默认值。
-这使得 gc-tree 对那些同时在许多互不相关仓库里开很多会话的重度用户来说也依然实用。
+活跃的 gc-branch 由 `~/.gctree` 内的 `HEAD` 指向，但当一个代码仓库被显式绑定到另一个 gc-branch 时，仓库映射可以覆盖这一后备设置。
+这使得 gc-tree 对于同时保持大量无关会话的重度用户而言非常实用。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@handsupmin/gc-tree",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Global Context Tree, a lightweight branch-aware global context orchestrator for AI coding tools",
   "type": "module",
   "private": false,
@@ -24,6 +24,8 @@
     "eval:multi-repo": "node --import tsx tests/eval/multi-repo.ts",
     "eval:multi-repo:verbose": "node --import tsx tests/eval/multi-repo.ts --verbose",
     "eval:autoresearch": "node --import tsx tests/eval/autoresearch.ts",
+    "eval:multilingual": "node --import tsx tests/eval/multilingual.ts",
+    "eval:multilingual:verbose": "node --import tsx tests/eval/multilingual.ts --verbose",
     "eval:real-docs": "node --import tsx tests/eval/real-docs.ts",
     "eval:real-docs:verbose": "node --import tsx tests/eval/real-docs.ts --verbose"
   },