@handsupmin/gc-tree 0.3.0 → 0.4.0

package/README.es.md

@@ -73,6 +73,14 @@ Después, tu herramienta de IA instala integración real de hooks SessionStart/U
 
 `gc-tree` opera **por encima del nivel del repositorio**. Almacena contexto en archivos Markdown estructurados y permite que tus herramientas de IA traigan solo lo relevante antes de cada sesión, de forma automática.
 
+`gctree resolve` es la **capa de índice compacto** dentro de un flujo de progressive disclosure:
+
+- `gctree resolve --query "..."` → lista compacta de coincidencias con IDs estables
+- `gctree related --id <match-id>` → documentos de apoyo alrededor de una coincidencia
+- `gctree show-doc --id <match-id>` → markdown completo de ese documento
+
+Además, cuando la branch está vacía, el repositorio está excluido o la consulta no tiene resultados, gc-tree devuelve un estado explícito en lugar de fallar de forma ambigua.
+
 ```bash
 gctree resolve --query "auth token rotation policy"
 ```

package/README.ja.md

@@ -73,6 +73,14 @@ gctree init
 
 `gc-tree` は**リポジトリより上のレイヤー**に位置します。コンテキストを構造化された Markdown ファイルに保存し、AI ツールがセッションのたびに関連するものだけを自動で引き出せるようにします。
 
+`gctree resolve` は、progressive-disclosure ワークフローにおける **compact index layer** です。
+
+- `gctree resolve --query "..."` → stable ID 付きの compact なマッチ一覧
+- `gctree related --id <match-id>` → そのマッチの周辺にある supporting docs
+- `gctree show-doc --id <match-id>` → そのドキュメントの完全な markdown
+
+また、文書が空・リポジトリが除外対象・クエリ結果なし、といった場合も曖昧に失敗せず、明示的な status を返します。
+
 ```bash
 gctree resolve --query "auth token rotation policy"
 ```

package/README.ko.md

@@ -73,6 +73,14 @@ gctree init
 
 `gc-tree`는 **레포 위 레벨**에 위치합니다. 컨텍스트를 구조화된 마크다운 파일에 저장하고, AI 도구가 매 세션마다 관련된 것만 자동으로 가져오게 합니다.
 
+`gctree resolve`는 progressive-disclosure 워크플로우의 **compact index layer**입니다:
+
+- `gctree resolve --query "..."` → stable ID가 포함된 compact match 목록
+- `gctree related --id <match-id>` → 특정 match 주변의 supporting docs
+- `gctree show-doc --id <match-id>` → 해당 문서의 전체 markdown
+
+또한 문서가 비어 있거나, 저장소가 제외되어 있거나, 쿼리 결과가 없을 때는 모호하게 실패하지 않고 명시적인 status를 반환합니다.
+
 ```bash
 gctree resolve --query "auth token rotation policy"
 ```

package/README.md

@@ -73,6 +73,14 @@ After that, your AI tool gets real SessionStart/UserPromptSubmit hook integratio
 
 `gc-tree` sits **above the repo level**. It stores durable context in structured markdown files and lets your AI tools pull only what's relevant — before each session, automatically.
 
+`gctree resolve` is the compact **index layer** in a progressive-disclosure workflow:
+
+- `gctree resolve --query "..."` → compact matches with stable IDs
+- `gctree related --id <match-id>` → supporting docs around one match
+- `gctree show-doc --id <match-id>` → full markdown for that doc
+
+When no docs exist, a repo is excluded, or a query has no hits, gc-tree returns an explicit status instead of failing ambiguously.
+
 ```bash
 gctree resolve --query "auth token rotation policy"
 ```

package/README.zh.md

@@ -73,6 +73,14 @@ gctree init
 
 `gc-tree` 工作在**仓库之上**。它把上下文存储为结构化的 Markdown 文件，让 AI 工具在每次会话前自动拉取相关内容。
 
+`gctree resolve` 是 progressive-disclosure 工作流中的**紧凑索引层**：
+
+- `gctree resolve --query "..."` → 返回带稳定 ID 的紧凑匹配列表
+- `gctree related --id <match-id>` → 返回某个匹配周围的 supporting docs
+- `gctree show-doc --id <match-id>` → 返回该文档的完整 markdown
+
+另外，当 gc-branch 为空、仓库被排除、或查询没有匹配时，gc-tree 会返回明确的状态，而不是模糊地失败。
+
 ```bash
 gctree resolve --query "auth token rotation policy"
 ```

package/dist/src/cli.js

@@ -6,7 +6,7 @@ import { onboardBranch } from './onboard.js';
 import { buildProviderLaunchPlan, maybeLaunchProvider, promptLanguageSelection, promptLaunchProviderSelection, promptProviderSelection, } from './provider.js';
 import { DEFAULT_BRANCH, resolveHome } from './paths.js';
 import { branchRepoMapPath, branchScopeStatus, detectCurrentRepoId, promptResolveScopeDecision, readBranchRepoMap, resolveBranchForRepo, setRepoScopeForBranch, } from './repo-map.js';
-import { resolveContext } from './resolve.js';
+import { findRelatedDocs, getDocById, resolveContext } from './resolve.js';
 import { scaffoldHostIntegration } from './scaffold.js';
 import { requirePreferredProvider, writeSettings, readSettings } from './settings.js';
 import { checkoutBranch, initHome, listBranches, readHead, resetBranchContext, statusForBranch, ensureBranchExists, isBranchContextEmpty } from './store.js';
@@ -30,6 +30,8 @@ function usage() {
   gctree onboard [--home DIR] [--branch NAME] [--provider <codex|claude-code>] [--target DIR] [--no-launch]
   gctree reset-gc-branch [--home DIR] [--branch NAME] --yes
   gctree resolve --query TEXT [--home DIR] [--branch NAME] [--cwd DIR]
+  gctree show-doc --id ID [--home DIR] [--branch NAME]
+  gctree related --id ID [--home DIR] [--branch NAME]
   gctree update-global-context [--home DIR] [--branch NAME] [--provider <codex|claude-code>] [--target DIR] [--no-launch]
   gctree update-gc [--home DIR] [--branch NAME] [--provider <codex|claude-code>] [--target DIR] [--no-launch]
   gctree ugc [--home DIR] [--branch NAME] [--provider <codex|claude-code>] [--target DIR] [--no-launch]
@@ -52,6 +54,14 @@ async function readStdinText() {
     }
     return Buffer.concat(chunks).toString('utf8');
 }
+function compactMatchCommands(id, home, branch) {
+    const homeArg = `--home ${JSON.stringify(home)}`;
+    const branchArg = `--branch ${JSON.stringify(branch)}`;
+    return {
+        show_doc: `gctree show-doc --id ${JSON.stringify(id)} ${homeArg} ${branchArg}`,
+        related: `gctree related --id ${JSON.stringify(id)} ${homeArg} ${branchArg}`,
+    };
+}
 function normalizeProvider(value) {
     if (!value)
         return undefined;
@@ -294,23 +304,98 @@ async function main() {
             }
             if (currentRepo && scopeStatus === 'excluded') {
                 console.log(JSON.stringify({
+                    status: 'excluded',
                     gc_branch: gcBranch,
                     query,
                     current_repo: currentRepo,
                     source: resolved.source,
                     repo_scope_status: 'excluded',
+                    message: `Repo "${currentRepo}" is excluded from gc-branch "${gcBranch}".`,
+                    matches: [],
+                }, null, 2));
+                return;
+            }
+            const branchStatus = await statusForBranch(home, gcBranch);
+            if (branchStatus.doc_count === 0) {
+                console.log(JSON.stringify({
+                    status: 'empty_branch',
+                    gc_branch: gcBranch,
+                    query,
+                    current_repo: currentRepo,
+                    source: resolved.source,
+                    repo_scope_status: scopeStatus,
+                    message: `gc-branch "${gcBranch}" has no docs yet. Run gctree onboard to add durable context.`,
                     matches: [],
                 }, null, 2));
                 return;
             }
             const result = await resolveContext({ home, branch: gcBranch, query });
             console.log(JSON.stringify({
+                status: result.matches.length > 0 ? 'matched' : 'no_match',
                 gc_branch: result.branch,
                 query: result.query,
                 current_repo: currentRepo,
                 source: resolved.source,
                 repo_scope_status: scopeStatus,
-                matches: result.matches,
+                message: result.matches.length > 0
+                    ? `Found ${result.matches.length} matching docs. Use show-doc/related for progressive disclosure.`
+                    : `No matching docs found in gc-branch "${gcBranch}" for this query.`,
+                matches: result.matches.map((match) => ({
+                    ...match,
+                    commands: compactMatchCommands(match.id, home, gcBranch),
+                })),
+            }, null, 2));
+            return;
+        }
+        case 'show-doc': {
+            const id = readArg('--id');
+            if (!id)
+                usage();
+            const gcBranch = readArg('--branch') || (await readHead(home)) || DEFAULT_BRANCH;
+            const branchStatus = await statusForBranch(home, gcBranch);
+            if (branchStatus.doc_count === 0) {
+                console.log(JSON.stringify({ status: 'empty_branch', gc_branch: gcBranch, id, message: `gc-branch "${gcBranch}" has no docs yet.`, doc: null }, null, 2));
+                return;
+            }
+            const doc = await getDocById({ home, branch: gcBranch, id });
+            console.log(JSON.stringify({
+                status: doc ? 'matched' : 'doc_not_found',
+                gc_branch: gcBranch,
+                id,
+                message: doc ? `Loaded doc "${id}".` : `Doc "${id}" was not found in gc-branch "${gcBranch}".`,
+                doc,
+            }, null, 2));
+            return;
+        }
+        case 'related': {
+            const id = readArg('--id');
+            if (!id)
+                usage();
+            const gcBranch = readArg('--branch') || (await readHead(home)) || DEFAULT_BRANCH;
+            const result = await findRelatedDocs({ home, branch: gcBranch, id });
+            console.log(JSON.stringify({
+                status: result.status,
+                gc_branch: gcBranch,
+                id,
+                message: result.status === 'matched'
+                    ? `Found ${result.matches.length} related docs for "${id}".`
+                    : result.status === 'no_related_docs'
+                        ? `No related docs found for "${id}".`
+                        : result.status === 'doc_not_found'
+                            ? `Doc "${id}" was not found in gc-branch "${gcBranch}".`
+                            : `gc-branch "${gcBranch}" has no docs yet.`,
+                selected: result.selected
+                    ? {
+                        id: result.selected.id,
+                        title: result.selected.title,
+                        path: result.selected.path,
+                        summary: result.selected.summary,
+                    }
+                    : null,
+                matches: result.matches.map((match) => ({
+                    ...match,
+                    commands: compactMatchCommands(match.id, home, gcBranch),
+                })),
             }, null, 2));
             return;
         }

package/dist/src/hook.js

@@ -17,7 +17,7 @@ function limitMatches(matches, max = 3) {
 }
 function formatMatches(matches) {
     return limitMatches(matches)
-        .map((match, index) => `${index + 1}. ${match.title}\n   Summary: ${match.summary}\n   Excerpt: ${match.excerpt}`)
+        .map((match, index) => `${index + 1}. ${match.title} [id=${match.id}]\n   Summary: ${match.summary}\n   Excerpt: ${match.excerpt}`)
         .join('\n');
 }
 function buildSessionStartContext({ gcBranch, currentRepo, repoScopeStatus, }) {

package/dist/src/markdown.js

@@ -52,6 +52,13 @@ export function renderIndexMarkdown(input) {
     }
     return lines.join('\n');
 }
+export function docIdFromPath(docPath) {
+    const fileName = String(docPath || '')
+        .trim()
+        .split('/')
+        .pop() || '';
+    return fileName.replace(/\.md$/i, '') || 'doc';
+}
 export function parseIndexEntries(indexContent) {
     return String(indexContent || '')
         .split(/\r?\n/)
@@ -60,7 +67,7 @@ export function parseIndexEntries(indexContent) {
         .map((line) => {
         const body = line.slice(2);
         const [title, path] = body.split('->').map((part) => part.trim());
-        return { title, path };
+        return { id: docIdFromPath(path), title, path };
     });
 }
 export function extractSummary(markdown) {

package/dist/src/resolve.js

@@ -1,6 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { extractExcerpt, extractSummary, parseIndexEntries } from './markdown.js';
+import { docIdFromPath, extractExcerpt, extractSummary, parseIndexEntries } from './markdown.js';
 import { branchDir, branchIndexPath } from './paths.js';
 // Common English stop words that are too short or generic to be meaningful query signals.
 const STOP_WORDS = new Set([
@@ -41,27 +41,39 @@ function scoreText(text, query) {
         }
     }, 0);
 }
-export async function resolveContext({ home, branch, query, }) {
+async function readBranchDocs(home, branch) {
     const indexRaw = await readFile(branchIndexPath(home, branch), 'utf8');
     const entries = parseIndexEntries(indexRaw);
-    const matches = [];
-    for (const entry of entries) {
+    return Promise.all(entries.map(async (entry) => {
         const fullPath = join(branchDir(home, branch), entry.path);
         const raw = await readFile(fullPath, 'utf8');
-        const summary = extractSummary(raw);
-        const combined = `${entry.title}\n${summary}\n${raw}`;
+        return {
+            id: entry.id || docIdFromPath(entry.path),
+            title: entry.title,
+            path: entry.path,
+            summary: extractSummary(raw),
+            content: raw,
+        };
+    }));
+}
+export async function resolveContext({ home, branch, query, }) {
+    const entries = await readBranchDocs(home, branch);
+    const matches = [];
+    for (const entry of entries) {
+        const combined = `${entry.title}\n${entry.summary}\n${entry.content}`;
         // Title matches count double (higher signal density)
         const titleScore = scoreText(entry.title, query);
-        const bodyScore = scoreText(`${summary}\n${raw}`, query);
+        const bodyScore = scoreText(`${entry.summary}\n${entry.content}`, query);
         const score = titleScore * 2 + bodyScore;
         if (score <= 0)
             continue;
         matches.push({
+            id: entry.id,
             title: entry.title,
             path: entry.path,
             score,
-            summary,
-            excerpt: extractExcerpt(raw, query),
+            summary: entry.summary,
+            excerpt: extractExcerpt(entry.content, query),
         });
     }
     return {
@@ -70,3 +82,43 @@ export async function resolveContext({ home, branch, query, }) {
         matches: matches.sort((a, b) => b.score - a.score || a.title.localeCompare(b.title)),
     };
 }
+export async function getDocById({ home, branch, id, }) {
+    const docs = await readBranchDocs(home, branch);
+    return docs.find((doc) => doc.id === id) || null;
+}
+export async function findRelatedDocs({ home, branch, id, limit = 5, }) {
+    const docs = await readBranchDocs(home, branch);
+    if (docs.length === 0) {
+        return { status: 'empty_branch', selected: null, matches: [] };
+    }
+    const selected = docs.find((doc) => doc.id === id) || null;
+    if (!selected) {
+        return { status: 'doc_not_found', selected: null, matches: [] };
+    }
+    const query = `${selected.title}\n${selected.summary}`;
+    const matches = docs
+        .filter((doc) => doc.id !== selected.id)
+        .map((doc) => {
+        const titleScore = scoreText(doc.title, query);
+        const bodyScore = scoreText(`${doc.summary}\n${doc.content}`, query);
+        const score = titleScore * 2 + bodyScore;
+        return score > 0
+            ? {
+                id: doc.id,
+                title: doc.title,
+                path: doc.path,
+                score,
+                summary: doc.summary,
+                excerpt: extractExcerpt(doc.content, query),
+            }
+            : null;
+    })
+        .filter((match) => Boolean(match))
+        .sort((a, b) => b.score - a.score || a.title.localeCompare(b.title))
+        .slice(0, limit);
+    return {
+        status: matches.length > 0 ? 'matched' : 'no_related_docs',
+        selected,
+        matches,
+    };
+}

package/docs/usage.es.md

@@ -14,10 +14,12 @@ Un flujo de trabajo estándar con `gctree` tiene este aspecto: inicializar gc-tr
 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
+7. inspeccionar documentos de apoyo con `gctree related --id <match-id>`
+8. leer el documento completo solo cuando haga falta con `gctree show-doc --id <match-id>`
+9. crear o cambiar de gc-branch con `gctree checkout`
+10. ejecutar `gctree onboard` solo para una gc-branch vacía
+11. usar el mapeo de alcance del repositorio para que una gc-branch solo aplique donde corresponde
+12. usar `gctree update-global-context` para cambios duraderos más adelante
 
 ## Comandos principales
 
@@ -28,7 +30,9 @@ Un flujo de trabajo estándar con `gctree` tiene este aspecto: inicializar gc-tr
 | `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 resolve --query TEXT` | Devuelve la capa de índice compacto para una consulta. Las coincidencias incluyen IDs estables y comandos de seguimiento para profundizar. |
+| `gctree related --id <match-id>` | Devuelve documentos de apoyo relacionados con una coincidencia resuelta, sin expandir todavía el markdown completo. |
+| `gctree show-doc --id <match-id>` | Devuelve el documento source-of-truth en markdown completo para un ID estable. |
 | `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. |
@@ -40,7 +44,7 @@ Un flujo de trabajo estándar con `gctree` tiene este aspecto: inicializar gc-tr
 
 ## 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.
+`gctree resolve` es ahora la **capa de índice compacto** dentro de un flujo de progressive disclosure. Puntúa cada documento de la gc-branch activa contra tu consulta y devuelve solo coincidencias con IDs estables. Las coincidencias en el título cuentan el doble que las coincidencias en el cuerpo.
 
 ```bash
 gctree resolve --query "auth token rotation policy"
@@ -50,19 +54,36 @@ gctree resolve --query "auth token rotation policy"
 {
   "gc_branch": "main",
   "query": "auth token rotation policy",
+  "status": "matched",
   "matches": [
     {
+      "id": "auth",
       "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..."
+      "excerpt": "## Auth Flow\nAccess token: 15-min TTL, rotated on every authenticated request...",
+      "commands": {
+        "show_doc": "gctree show-doc --id \"auth\" --home \"~/.gctree\" --branch \"main\"",
+        "related": "gctree related --id \"auth\" --home \"~/.gctree\" --branch \"main\""
+      }
     }
   ]
 }
 ```
 
-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": []`.
+El flujo recomendado es:
+
+1. `resolve` → índice compacto
+2. `related` → documentos de apoyo alrededor de una coincidencia
+3. `show-doc` → markdown completo solo cuando hace falta
+
+La degradación elegante también es explícita:
+
+- gc-branch vacía → `status: "empty_branch"`
+- repo excluido → `status: "excluded"`
+- sin resultados → `status: "no_match"`
+- ID de documento inexistente → `status: "doc_not_found"`
 
 ## Ejemplo de flujo de alcance del repositorio
 

package/docs/usage.ja.md

@@ -14,10 +14,12 @@
 4. `both` を選んだ場合は、今回のオンボーディングをどちらのプロバイダーで始めるか選ぶ
 5. デフォルトの `main` gc-branch に対するガイド付きオンボーディングを完了する
 6. `gctree resolve --query "..."` で必要なコンテキストを取り出す
-7. `gctree checkout` で gc-branch を作成または切り替える
-8. `gctree onboard` は空の gc-branch に対してだけ使う
-9. repo scope を設定して gc-branch が本来のリポジトリにだけ作用するようにする
-10. 後からの永続的な変更には `gctree update-global-context` を使う
+7. `gctree related --id <match-id>` で supporting docs を確認する
+8. `gctree show-doc --id <match-id>` で必要なときだけフルドキュメントを読む
+9. `gctree checkout` で gc-branch を作成または切り替える
+10. `gctree onboard` は空の gc-branch に対してだけ使う
+11. repo scope を設定して gc-branch が本来のリポジトリにだけ作用するようにする
+12. 後からの永続的な変更には `gctree update-global-context` を使う
 
 ## 主要コマンド
 
@@ -28,7 +30,9 @@
 | `gctree checkout -b <branch>` | 新しい空の gc-branch を作成し、そのまま切り替えます。 |
 | `gctree branches` | 利用可能な gc-branch 一覧と、現在アクティブなものを表示します。 |
 | `gctree status` | アクティブな gc-branch、現在のリポジトリ、現在の repo-scope 状態、警告、優先プロバイダーを表示します。 |
-| `gctree resolve --query TEXT` | 関係する gc-branch からコンテキストを検索します。現在のリポジトリが未マップなら、そのリポジトリをどう扱うかを尋ねる場合があります。 |
+| `gctree resolve --query TEXT` | クエリに対する compact index layer を返します。各 match には stable ID と次の確認コマンドが含まれます。 |
+| `gctree related --id <match-id>` | 1つの resolved match に関連する supporting docs を、フル markdown を開かずに返します。 |
+| `gctree show-doc --id <match-id>` | stable match ID に対応するフル markdown の source-of-truth ドキュメントを返します。 |
 | `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 では無視するものとして記録します。 |
@@ -40,7 +44,7 @@
 
 ## resolve が返す内容
 
-`gctree resolve` はアクティブな gc-branch 内のすべてのドキュメントをクエリに対してスコアリングし、マッチしたものだけを返します。タイトルの一致はボディの一致の 2 倍の重みを持ちます。
+`gctree resolve` は progressive-disclosure ワークフローにおける **compact index layer** です。アクティブな gc-branch 内のドキュメントをクエリに対してスコアリングし、stable ID 付きの match だけを返します。タイトルの一致は本文の一致の 2 倍の重みを持ちます。
 
 ```bash
 gctree resolve --query "auth token rotation policy"
@@ -50,19 +54,36 @@ gctree resolve --query "auth token rotation policy"
 {
   "gc_branch": "main",
   "query": "auth token rotation policy",
+  "status": "matched",
   "matches": [
     {
+      "id": "auth",
       "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..."
+      "excerpt": "## Auth Flow\nAccess token: 15-min TTL, rotated on every authenticated request...",
+      "commands": {
+        "show_doc": "gctree show-doc --id \"auth\" --home \"~/.gctree\" --branch \"main\"",
+        "related": "gctree related --id \"auth\" --home \"~/.gctree\" --branch \"main\""
+      }
     }
   ]
 }
 ```
 
-ツールはまずサマリーと抜粋を受け取ります。サマリーだけでは不足する場合にのみ、`path` にあるフルドキュメントを読み込みます。何もマッチしないクエリの場合は `"matches": []` が返ります。
+推奨フローは次のとおりです。
+
+1. `resolve` → compact index
+2. `related` → その match の周辺にある supporting docs
+3. `show-doc` → 必要なときだけフル markdown
+
+Graceful degradation も明示的です。
+
+- 空の gc-branch → `status: "empty_branch"`
+- 除外された repo → `status: "excluded"`
+- ヒットなし → `status: "no_match"`
+- 文書 ID が見つからない → `status: "doc_not_found"`
 
 ## repo scope の設定例
 

package/docs/usage.ko.md

@@ -14,10 +14,12 @@
 4. `both`를 선택한 경우, 지금 온보딩을 시작할 프로바이더 선택
 5. 기본 `main` gc-branch의 안내된 온보딩 완료
 6. `gctree resolve --query "..."`로 관련 컨텍스트 resolve
-7. `gctree checkout`으로 gc-branch 생성 또는 전환
-8. 빈 gc-branch에만 `gctree onboard` 실행
-9. 저장소 범위 매핑으로 gc-branch가 해당하는 곳에만 적용되도록 설정
-10. 이후 지속 변경에는 `gctree update-global-context` 사용
+7. `gctree related --id <match-id>`로 supporting docs 확인
+8. `gctree show-doc --id <match-id>`로 필요할 때만 전체 문서 읽기
+9. `gctree checkout`으로 gc-branch 생성 또는 전환
+10. 빈 gc-branch에만 `gctree onboard` 실행
+11. 저장소 범위 매핑으로 gc-branch가 해당하는 곳에만 적용되도록 설정
+12. 이후 지속 변경에는 `gctree update-global-context` 사용
 
 ## 핵심 명령어
 
@@ -28,7 +30,9 @@
 | `gctree checkout -b <branch>` | 새 빈 gc-branch를 생성하고 전환. |
 | `gctree branches` | 사용 가능한 gc-branch 목록 표시 및 현재 활성 브랜치 표시. |
 | `gctree status` | 활성 gc-branch, 현재 저장소, 현재 저장소 범위 상태, 경고, 선호 프로바이더 표시. |
-| `gctree resolve --query TEXT` | 관련 gc-branch에서 컨텍스트 검색. 현재 저장소가 매핑되지 않은 경우, `gctree`가 해당 저장소 처리 방법을 물어볼 수 있습니다. |
+| `gctree resolve --query TEXT` | 쿼리에 대한 compact index layer를 반환합니다. match에는 stable ID와 후속 조회 명령이 포함됩니다. |
+| `gctree related --id <match-id>` | 하나의 resolved match 주변 supporting docs를 전체 markdown 없이 반환합니다. |
+| `gctree show-doc --id <match-id>` | stable match ID 하나에 대한 전체 markdown source-of-truth 문서를 반환합니다. |
 | `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에서 무시로 표시. |
@@ -40,7 +44,7 @@
 
 ## resolve가 반환하는 것
 
-`gctree resolve`는 활성 gc-branch의 모든 문서를 쿼리에 대해 점수를 매기고 매칭된 것만 반환합니다. 제목 매칭은 본문 매칭보다 두 배의 가중치를 가집니다.
+`gctree resolve`는 progressive-disclosure 워크플로우의 **compact index layer**입니다. 활성 gc-branch의 문서를 쿼리에 대해 점수화하고 stable ID가 포함된 match만 반환합니다. 제목 매칭은 본문 매칭보다 두 배의 가중치를 가집니다.
 
 ```bash
 gctree resolve --query "auth token rotation policy"
@@ -50,19 +54,36 @@ gctree resolve --query "auth token rotation policy"
 {
   "gc_branch": "main",
   "query": "auth token rotation policy",
+  "status": "matched",
   "matches": [
     {
+      "id": "auth",
       "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..."
+      "excerpt": "## Auth Flow\nAccess token: 15-min TTL, rotated on every authenticated request...",
+      "commands": {
+        "show_doc": "gctree show-doc --id \"auth\" --home \"~/.gctree\" --branch \"main\"",
+        "related": "gctree related --id \"auth\" --home \"~/.gctree\" --branch \"main\""
+      }
     }
   ]
 }
 ```
 
-도구는 먼저 요약과 발췌문을 받습니다. 요약만으로 충분하지 않을 때만 `path`의 전체 문서를 읽습니다. 아무것도 매칭되지 않는 쿼리는 `"matches": []`를 반환합니다.
+권장 흐름은 다음과 같습니다:
+
+1. `resolve` → compact index
+2. `related` → 특정 match 주변 supporting docs
+3. `show-doc` → 필요할 때만 전체 markdown
+
+Graceful degradation도 명시적입니다:
+
+- 빈 gc-branch → `status: "empty_branch"`
+- 제외된 repo → `status: "excluded"`
+- 결과 없음 → `status: "no_match"`
+- 문서 ID 없음 → `status: "doc_not_found"`
 
 ## 저장소 범위 설정 예시 흐름
 

package/docs/usage.md

@@ -14,10 +14,12 @@ A standard `gctree` workflow looks like this: initialize gc-tree, choose a provi
 4. if you picked `both`, choose which provider should start onboarding now
 5. complete guided onboarding for the default `main` gc-branch
 6. resolve relevant context with `gctree resolve --query "..."`
-7. create or switch gc-branches with `gctree checkout`
-8. run `gctree onboard` only for an empty gc-branch
-9. use repo scope mapping so a gc-branch only applies where it belongs
-10. use `gctree update-global-context` for durable changes later
+7. inspect supporting docs with `gctree related --id <match-id>`
+8. read the full doc only when needed with `gctree show-doc --id <match-id>`
+9. create or switch gc-branches with `gctree checkout`
+10. run `gctree onboard` only for an empty gc-branch
+11. use repo scope mapping so a gc-branch only applies where it belongs
+12. use `gctree update-global-context` for durable changes later
 
 ## Core commands
 
@@ -28,7 +30,9 @@ A standard `gctree` workflow looks like this: initialize gc-tree, choose a provi
 | `gctree checkout -b <branch>` | Create and switch to a new empty gc-branch. |
 | `gctree branches` | List available gc-branches and show the active one. |
 | `gctree status` | Show the active gc-branch, the current repo, the current repo-scope status, warnings, and the preferred provider. |
-| `gctree resolve --query TEXT` | Search the relevant gc-branch for context. If the current repo is unmapped, `gctree` can ask how that repo should be treated. |
+| `gctree resolve --query TEXT` | Return the compact index layer for a query. Matches include stable IDs plus follow-up commands for deeper inspection. |
+| `gctree related --id <match-id>` | Return supporting docs related to one resolved match without expanding the full markdown yet. |
+| `gctree show-doc --id <match-id>` | Return the full markdown source-of-truth doc for one stable match ID. |
 | `gctree repo-map` | Show the current contents of `branch-repo-map.json`. |
 | `gctree set-repo-scope --branch <name> --include` | Mark the current repo as included for that gc-branch. |
 | `gctree set-repo-scope --branch <name> --exclude` | Mark the current repo as ignored for that gc-branch. |
@@ -40,7 +44,7 @@ A standard `gctree` workflow looks like this: initialize gc-tree, choose a provi
 
 ## 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.
+`gctree resolve` is the compact **index layer** in a progressive-disclosure workflow. It scores every document in the active gc-branch against your query and returns only matching docs with stable IDs. Title matches count twice as much as body matches.
 
 ```bash
 gctree resolve --query "auth token rotation policy"
@@ -50,19 +54,36 @@ gctree resolve --query "auth token rotation policy"
 {
   "gc_branch": "main",
   "query": "auth token rotation policy",
+  "status": "matched",
   "matches": [
     {
+      "id": "auth",
       "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..."
+      "excerpt": "## Auth Flow\nAccess token: 15-min TTL, rotated on every authenticated request...",
+      "commands": {
+        "show_doc": "gctree show-doc --id \"auth\" --home \"~/.gctree\" --branch \"main\"",
+        "related": "gctree related --id \"auth\" --home \"~/.gctree\" --branch \"main\""
+      }
     }
   ]
 }
 ```
 
-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": []`.
+The intended flow is:
+
+1. `resolve` → compact index
+2. `related` → supporting docs around one match
+3. `show-doc` → full markdown only when needed
+
+Graceful degradation is explicit:
+
+- empty gc-branch → `status: "empty_branch"`
+- excluded repo → `status: "excluded"`
+- no hits → `status: "no_match"`
+- missing doc id → `status: "doc_not_found"`
 
 ## Example repo-scope flow
 

package/docs/usage.zh.md

@@ -14,10 +14,12 @@
 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` 进行后续的持久化变更
+7. 使用 `gctree related --id <match-id>` 查看 supporting docs
+8. 仅在需要时使用 `gctree show-doc --id <match-id>` 读取完整文档
+9. 使用 `gctree checkout` 创建或切换 gc-branch
+10. 仅对空的 gc-branch 运行 `gctree onboard`
+11. 使用仓库作用范围映射，使 gc-branch 只在其适用的地方生效
+12. 使用 `gctree update-global-context` 进行后续的持久化变更
 
 ## 核心命令
 
@@ -28,7 +30,9 @@
 | `gctree checkout -b <branch>` | 创建并切换到一个新的空 gc-branch。 |
 | `gctree branches` | 列出可用的 gc-branch 并显示当前活跃的那个。 |
 | `gctree status` | 显示活跃的 gc-branch、当前仓库、当前仓库的作用范围状态、警告信息及首选提供商。 |
-| `gctree resolve --query TEXT` | 在相关的 gc-branch 中搜索上下文。如果当前仓库尚未映射，`gctree` 会询问该如何处理这个仓库。 |
+| `gctree resolve --query TEXT` | 返回查询的紧凑索引层。匹配项包含稳定 ID 和后续深入查看的命令。 |
+| `gctree related --id <match-id>` | 返回某个 resolved 匹配周围的 supporting docs，而不立即展开完整 markdown。 |
+| `gctree show-doc --id <match-id>` | 返回某个稳定匹配 ID 对应的完整 markdown source-of-truth 文档。 |
 | `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 的忽略仓库。 |
@@ -40,7 +44,7 @@
 
 ## resolve 返回的内容
 
-`gctree resolve` 对活跃 gc-branch 中的每个文档与查询内容进行评分，只返回匹配的文档。标题匹配的权重是正文匹配的两倍。
+`gctree resolve` 是 progressive-disclosure 工作流中的**紧凑索引层**。它对活跃 gc-branch 中的每个文档与查询内容进行评分，只返回带稳定 ID 的匹配文档。标题匹配的权重是正文匹配的两倍。
 
 ```bash
 gctree resolve --query "auth token rotation policy"
@@ -50,19 +54,36 @@ gctree resolve --query "auth token rotation policy"
 {
   "gc_branch": "main",
   "query": "auth token rotation policy",
+  "status": "matched",
   "matches": [
     {
+      "id": "auth",
       "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..."
+      "excerpt": "## Auth Flow\nAccess token: 15-min TTL, rotated on every authenticated request...",
+      "commands": {
+        "show_doc": "gctree show-doc --id \"auth\" --home \"~/.gctree\" --branch \"main\"",
+        "related": "gctree related --id \"auth\" --home \"~/.gctree\" --branch \"main\""
+      }
     }
   ]
 }
 ```
 
-工具首先接收摘要和摘录。只有在摘要不足以满足需求时，才会读取 `path` 指向的完整文档。如果查询没有任何匹配，则返回 `"matches": []`。
+推荐的流程是：
+
+1. `resolve` → 紧凑索引
+2. `related` → 某个匹配周围的 supporting docs
+3. `show-doc` → 仅在需要时读取完整 markdown
+
+Graceful degradation 也是显式的：
+
+- 空 gc-branch → `status: "empty_branch"`
+- 被排除的 repo → `status: "excluded"`
+- 无匹配结果 → `status: "no_match"`
+- 文档 ID 不存在 → `status: "doc_not_found"`
 
 ## 仓库作用范围示例流程
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@handsupmin/gc-tree",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Global Context Tree, a lightweight branch-aware global context orchestrator for AI coding tools",
   "type": "module",
   "private": false,