@handsupmin/gc-tree 0.1.4 → 0.2.1

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,36 @@ 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/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/gctree-session-start.md            ← session-start hook
+.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,46 @@ 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/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/gctree-session-start.md            ← 会话启动钩子
+.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.1.4",
+  "version": "0.2.1",
   "description": "Global Context Tree, a lightweight branch-aware global context orchestrator for AI coding tools",
   "type": "module",
   "private": false,
@@ -18,7 +18,16 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "test": "node --import tsx --test tests/*.test.ts",
-    "prepack": "npm run build"
+    "prepack": "npm run build",
+    "eval": "node --import tsx tests/eval/index.ts",
+    "eval:verbose": "node --import tsx tests/eval/index.ts --verbose",
+    "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"
   },
   "engines": {
     "node": ">=20"