@handsupmin/gc-tree 0.2.1 → 0.4.0

package/README.es.md

@@ -62,7 +62,7 @@ gctree init
 2. Instalar los archivos de integración en el repositorio actual
 3. Completar el onboarding guiado para el gc-branch `main`
 
-Después, tu herramienta de IA aprenderá a llamar a `gctree resolve` antes de planificar o implementar.
+Después, tu herramienta de IA instala integración real de hooks SessionStart/UserPromptSubmit: revisa gc-tree automáticamente antes de trabajar y cachea resultados vacíos/no-match durante la sesión.
 
 - **CLI:** `gctree`
 - **Requisito:** Node.js 20+
@@ -73,6 +73,14 @@ Después, tu herramienta de IA aprenderá a llamar a `gctree resolve` antes de p
 
 `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

@@ -62,7 +62,7 @@ gctree init
 2. 現在のリポジトリへの統合ファイルのインストール
 3. `main` gc-branch のガイド付きオンボーディング実行
 
-その後は、AI ツールが計画・実装の前に `gctree resolve` を呼ぶ流れを自然に覚えます。
+その後は、AI ツールに実際の SessionStart / UserPromptSubmit フック統合が入り、作業前に gc-tree を自動確認し、空結果や no-match をセッション中キャッシュします。
 
 - **CLI：** `gctree`
 - **動作条件：** Node.js 20+
@@ -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

@@ -62,7 +62,7 @@ gctree init
 2. 현재 레포에 통합 파일 스캐폴딩
 3. `main` gc-branch 가이드형 온보딩 실행
 
-이후 AI 도구가 계획·구현 전에 `gctree resolve`를 호출하는 법을 자동으로 알게 됩니다.
+이후 AI 도구에 실제 SessionStart/UserPromptSubmit 훅 통합이 설치되어, 작업 전에 gc-tree를 자동 확인하고 세션 동안 빈 결과·no-match를 캐시합니다.
 
 - **CLI:** `gctree`
 - **요구 사항:** Node.js 20+
@@ -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

@@ -62,7 +62,7 @@ gctree init
 2. Scaffold the integration files into your current repo
 3. Run guided onboarding for the `main` gc-branch
 
-After that, your AI tool will know to call `gctree resolve` before planning or implementing.
+After that, your AI tool gets real SessionStart/UserPromptSubmit hook integration, so it auto-checks gc-tree before work and caches empty/no-match results for the session.
 
 - **CLI:** `gctree`
 - **Requires:** Node.js 20+
@@ -73,6 +73,14 @@ After that, your AI tool will know to call `gctree resolve` before planning or i
 
 `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

@@ -49,7 +49,7 @@ gctree init
 2. 在当前仓库安装集成文件
 3. 为 `main` gc-branch 完成引导式 onboarding
 
-之后，AI 工具会自动学会在规划或实现前调用 `gctree resolve`。
+之后，AI 工具会安装真正的 SessionStart / UserPromptSubmit hook 集成：在开始工作前自动检查 gc-tree，并在整个会话内缓存空结果和 no-match。
 
 - **CLI：** `gctree`
 - **要求：** Node.js 20+
@@ -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

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 import { readFile } from 'node:fs/promises';
 import { stdin } from 'node:process';
+import { dispatchGcTreeHook } from './hook.js';
 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';
@@ -29,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]
@@ -37,12 +40,28 @@ function usage() {
 Internal commands:
   gctree __apply-onboarding --input FILE [--home DIR] [--branch NAME]
   gctree __apply-update --input FILE [--home DIR] [--branch NAME]
+  gctree __hook --event <SessionStart|UserPromptSubmit> [--home DIR]
 `);
     process.exit(1);
 }
 async function readJsonFile(path) {
     return JSON.parse(await readFile(path, 'utf8'));
 }
+async function readStdinText() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+    }
+    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;
@@ -285,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;
         }
@@ -337,6 +431,22 @@ async function main() {
             console.log(JSON.stringify(result, null, 2));
             return;
         }
+        case '__hook': {
+            const event = readArg('--event');
+            if (event !== 'SessionStart' && event !== 'UserPromptSubmit')
+                usage();
+            const raw = await readStdinText();
+            const payload = raw.trim() ? JSON.parse(raw) : {};
+            const result = await dispatchGcTreeHook({
+                event,
+                home,
+                payload,
+            });
+            if (result) {
+                console.log(JSON.stringify(result, null, 2));
+            }
+            return;
+        }
         case 'scaffold': {
             const host = normalizeProviderMode(readArg('--host'));
             if (!host)

package/dist/src/hook.js

@@ -0,0 +1,209 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { dirname } from 'node:path';
+import { DEFAULT_BRANCH } from './paths.js';
+import { hookCachePath, } from './paths.js';
+import { branchScopeStatus, readBranchRepoMap, resolveBranchForRepo } from './repo-map.js';
+import { resolveContext } from './resolve.js';
+import { readHead, statusForBranch } from './store.js';
+function normalizeText(value) {
+    return value.trim().replace(/\s+/g, ' ');
+}
+function hashQuery(query) {
+    return createHash('sha1').update(normalizeText(query).toLowerCase()).digest('hex');
+}
+function limitMatches(matches, max = 3) {
+    return matches.slice(0, max);
+}
+function formatMatches(matches) {
+    return limitMatches(matches)
+        .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, }) {
+    return [
+        `gc-tree auto-resolve is active for this session.`,
+        `Active gc-branch: "${gcBranch}".`,
+        `Current repo: ${currentRepo || 'unscoped'}.`,
+        `Repo scope status: ${repoScopeStatus}.`,
+        `Before acting on new user prompts, use gc-tree hook context first. If the hook reports no reusable global context, avoid redundant resolve calls for the same session state unless the repo, gc-branch, or task changes materially.`,
+    ].join(' ');
+}
+function buildEmptyBranchContext({ gcBranch, currentRepo, cached, }) {
+    return [
+        `gc-tree auto-resolve ${cached ? 'used cached state' : 'checked the active gc-branch'} and found no reusable global context for this session because gc-branch "${gcBranch}" currently has 0 docs.`,
+        `Repo: ${currentRepo || 'unscoped'}.`,
+        `Treat this as "no reusable global context yet" until the gc-branch content changes or a different repo/gc-branch is active.`,
+    ].join(' ');
+}
+function buildExcludedContext({ gcBranch, currentRepo, cached, }) {
+    return [
+        `gc-tree auto-resolve ${cached ? 'used cached state' : 'checked the active gc-branch'} and found that repo "${currentRepo || 'unknown'}" is excluded from gc-branch "${gcBranch}".`,
+        `No reusable global context applies here unless the branch-repo mapping changes.`,
+    ].join(' ');
+}
+function buildNoMatchContext({ gcBranch, currentRepo, query, cached, }) {
+    return [
+        `gc-tree auto-resolve ${cached ? 'skipped a redundant lookup using cached no-match state' : 'checked the active gc-branch'} and found no reusable global context for this prompt in gc-branch "${gcBranch}".`,
+        `Repo: ${currentRepo || 'unscoped'}.`,
+        `Query: "${query}".`,
+        `Only re-run resolve if the repo, gc-branch, or task changes materially.`,
+    ].join(' ');
+}
+function buildMatchContext({ gcBranch, currentRepo, repoScopeStatus, query, matches, }) {
+    return [
+        `gc-tree auto-resolve checked gc-branch "${gcBranch}" for repo "${currentRepo || 'unscoped'}" (scope: ${repoScopeStatus}) before this prompt.`,
+        `Query: "${query}".`,
+        `Use these matching gc-tree summaries before planning or implementation:`,
+        formatMatches(matches),
+        `Read full docs only if the summaries are insufficient.`,
+    ].join('\n');
+}
+async function readHookCache(home, sessionId) {
+    try {
+        const raw = await readFile(hookCachePath(home, sessionId), 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+async function writeHookCache(home, cache) {
+    const path = hookCachePath(home, cache.session_id);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(cache, null, 2)}\n`, 'utf8');
+}
+function nextCacheState(previous, { sessionId, gcBranch, currentRepo, repoScopeStatus, }) {
+    const changed = !previous ||
+        previous.gc_branch !== gcBranch ||
+        previous.current_repo !== currentRepo ||
+        previous.repo_scope_status !== repoScopeStatus;
+    return {
+        version: 1,
+        session_id: sessionId,
+        gc_branch: gcBranch,
+        current_repo: currentRepo,
+        repo_scope_status: repoScopeStatus,
+        branch_empty: changed ? false : previous.branch_empty,
+        branch_excluded: changed ? false : previous.branch_excluded,
+        no_match_signatures: changed ? [] : previous.no_match_signatures,
+        updated_at: new Date().toISOString(),
+    };
+}
+function readSessionId(payload) {
+    const raw = normalizeText(payload.session_id || '');
+    return raw || 'default-session';
+}
+export async function dispatchGcTreeHook({ event, home, payload, }) {
+    const cwd = payload.cwd || process.cwd();
+    const head = (await readHead(home)) || DEFAULT_BRANCH;
+    const resolved = await resolveBranchForRepo({ home, head, cwd });
+    const gcBranch = resolved.gc_branch;
+    const currentRepo = resolved.current_repo;
+    const mapping = await readBranchRepoMap(home);
+    const repoScopeStatus = branchScopeStatus(mapping, gcBranch, currentRepo);
+    const sessionId = readSessionId(payload);
+    if (event === 'SessionStart') {
+        return {
+            hookSpecificOutput: {
+                hookEventName: event,
+                additionalContext: buildSessionStartContext({
+                    gcBranch,
+                    currentRepo,
+                    repoScopeStatus,
+                }),
+            },
+        };
+    }
+    const prompt = normalizeText(payload.user_prompt || '');
+    if (!prompt)
+        return null;
+    const branchStatus = await statusForBranch(home, gcBranch);
+    const previousCache = await readHookCache(home, sessionId);
+    const cache = nextCacheState(previousCache, {
+        sessionId,
+        gcBranch,
+        currentRepo,
+        repoScopeStatus,
+    });
+    if (repoScopeStatus === 'excluded') {
+        cache.branch_excluded = true;
+        cache.updated_at = new Date().toISOString();
+        await writeHookCache(home, cache);
+        return {
+            hookSpecificOutput: {
+                hookEventName: event,
+                additionalContext: buildExcludedContext({
+                    gcBranch,
+                    currentRepo,
+                    cached: previousCache?.branch_excluded === true,
+                }),
+            },
+        };
+    }
+    if (branchStatus.doc_count === 0) {
+        const wasCached = cache.branch_empty;
+        cache.branch_empty = true;
+        cache.updated_at = new Date().toISOString();
+        await writeHookCache(home, cache);
+        return {
+            hookSpecificOutput: {
+                hookEventName: event,
+                additionalContext: buildEmptyBranchContext({
+                    gcBranch,
+                    currentRepo,
+                    cached: wasCached,
+                }),
+            },
+        };
+    }
+    const query = currentRepo ? `${currentRepo} ${prompt}` : prompt;
+    const signature = hashQuery(query);
+    if (cache.no_match_signatures.includes(signature)) {
+        cache.updated_at = new Date().toISOString();
+        await writeHookCache(home, cache);
+        return {
+            hookSpecificOutput: {
+                hookEventName: event,
+                additionalContext: buildNoMatchContext({
+                    gcBranch,
+                    currentRepo,
+                    query,
+                    cached: true,
+                }),
+            },
+        };
+    }
+    const result = await resolveContext({ home, branch: gcBranch, query });
+    if (result.matches.length === 0) {
+        cache.no_match_signatures = [...new Set([...cache.no_match_signatures, signature])];
+        cache.updated_at = new Date().toISOString();
+        await writeHookCache(home, cache);
+        return {
+            hookSpecificOutput: {
+                hookEventName: event,
+                additionalContext: buildNoMatchContext({
+                    gcBranch,
+                    currentRepo,
+                    query,
+                    cached: false,
+                }),
+            },
+        };
+    }
+    cache.no_match_signatures = cache.no_match_signatures.filter((entry) => entry !== signature);
+    cache.updated_at = new Date().toISOString();
+    await writeHookCache(home, cache);
+    return {
+        hookSpecificOutput: {
+            hookEventName: event,
+            additionalContext: buildMatchContext({
+                gcBranch,
+                currentRepo,
+                repoScopeStatus,
+                query,
+                matches: result.matches,
+            }),
+        },
+    };
+}

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/paths.js

@@ -26,3 +26,9 @@ export function branchIndexPath(home, branch) {
 export function branchDocsDir(home, branch) {
     return join(branchDir(home, branch), 'docs');
 }
+export function hookCacheDir(home) {
+    return join(home, 'hook-cache');
+}
+export function hookCachePath(home, sessionId) {
+    return join(hookCacheDir(home), `${sessionId}.json`);
+}

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/dist/src/scaffold.js

@@ -6,8 +6,8 @@ function renderCodexAgentsSnippet() {
         '# gctree Codex integration snippet',
         '',
         '- Treat the active gctree branch as a **gc-branch** when you describe it to users.',
-        '- Before planning or implementation, run `gctree status` to confirm the active gc-branch if it is unclear.',
-        '- Use `gctree resolve --query "<task>"` when reusable global context may matter.',
+        '- gctree init installs SessionStart and UserPromptSubmit hooks that auto-check gc-tree before work.',
+        '- Use the hook-injected gc-tree context first. If hooks are unavailable or clearly stale, run `gctree status` and `gctree resolve --query "<task>"` yourself before planning or implementation.',
         '- Use `$gc-onboard` only for an empty gc-branch.',
         '- Use `$gc-update-global-context` when durable context in the active gc-branch should change.',
         '',
@@ -18,12 +18,39 @@ function renderCodexBootstrapPrompt() {
         '# gctree Bootstrap',
         '',
         '- Keep the active gc-branch explicit whenever global context matters.',
-        '- Resolve reusable global context before planning or implementation when it may change the answer.',
+        '- Trust auto-resolved gc-tree hook context first; if it is missing, resolve reusable global context before planning or implementation.',
         '- Read summaries first and only open full docs when needed.',
         '- Treat gctree docs as explicit source-of-truth markdown, not hidden memory.',
         '',
     ].join('\n');
 }
+function renderCodexHooksJson() {
+    return JSON.stringify({
+        hooks: {
+            SessionStart: [
+                {
+                    matcher: 'startup|resume',
+                    hooks: [
+                        {
+                            type: 'command',
+                            command: 'gctree __hook --event SessionStart',
+                        },
+                    ],
+                },
+            ],
+            UserPromptSubmit: [
+                {
+                    hooks: [
+                        {
+                            type: 'command',
+                            command: 'gctree __hook --event UserPromptSubmit',
+                        },
+                    ],
+                },
+            ],
+        },
+    }, null, 2);
+}
 function renderCodexResolveSkill() {
     return [
         '---',
@@ -80,8 +107,8 @@ function renderClaudeSnippet() {
         '# gctree Claude Code integration snippet',
         '',
         '- Treat the active gctree branch as a **gc-branch** in user-facing language.',
-        '- Run `gctree status` before relying on global context if the active gc-branch is unclear.',
-        '- Use `gctree resolve --query "<task>"` when reusable global context may matter.',
+        '- gctree init installs SessionStart and UserPromptSubmit hooks that auto-check gc-tree before work.',
+        '- Use the hook-injected gc-tree context first. If hooks are unavailable or clearly stale, run `gctree status` and `gctree resolve --query "<task>"` yourself before planning or implementation.',
         '- Use `/gc-onboard` only for an empty gc-branch.',
         '- Use `/gc-update-global-context` when durable context in the active gc-branch should change.',
         '',
@@ -91,12 +118,43 @@ function renderClaudeSessionStartHook() {
     return [
         '# gctree Claude Code SessionStart note',
         '',
-        '- At session start, confirm the active gc-branch with `gctree status` when reusable global context may matter.',
+        '- gctree init installs real SessionStart/UserPromptSubmit hooks via `.claude/hooks/hooks.json`.',
+        '- At session start, use the injected hook context to confirm the active gc-branch.',
         '- Refer to gctree branches as **gc-branches** in user-facing language.',
-        '- Resolve summaries before planning or implementation when branch-level context may change the answer.',
+        '- If hook context is missing or stale, resolve summaries before planning or implementation when branch-level context may change the answer.',
         '',
     ].join('\n');
 }
+function renderClaudeHooksJson() {
+    return JSON.stringify({
+        hooks: {
+            SessionStart: [
+                {
+                    matcher: '*',
+                    hooks: [
+                        {
+                            type: 'command',
+                            command: 'gctree __hook --event SessionStart',
+                            timeout: 10,
+                        },
+                    ],
+                },
+            ],
+            UserPromptSubmit: [
+                {
+                    matcher: '*',
+                    hooks: [
+                        {
+                            type: 'command',
+                            command: 'gctree __hook --event UserPromptSubmit',
+                            timeout: 10,
+                        },
+                    ],
+                },
+            ],
+        },
+    }, null, 2);
+}
 function renderClaudeResolveCommand() {
     return [
         '---',
@@ -150,6 +208,7 @@ function scaffoldFiles(host) {
     if (host === 'codex') {
         return [
             { path: 'AGENTS.md', content: renderCodexAgentsSnippet() },
+            { path: '.codex/hooks.json', content: renderCodexHooksJson() },
             { path: '.codex/prompts/gctree-bootstrap.md', content: renderCodexBootstrapPrompt() },
             { path: '.codex/skills/gc-resolve-context/SKILL.md', content: renderCodexResolveSkill() },
             { path: '.codex/skills/gc-onboard/SKILL.md', content: renderCodexOnboardSkill() },
@@ -158,6 +217,7 @@ function scaffoldFiles(host) {
     }
     return [
         { path: 'CLAUDE.md', content: renderClaudeSnippet() },
+        { path: '.claude/hooks/hooks.json', content: renderClaudeHooksJson() },
         { path: '.claude/hooks/gctree-session-start.md', content: renderClaudeSessionStartHook() },
         { path: '.claude/commands/gc-resolve-context.md', content: renderClaudeResolveCommand() },
         { path: '.claude/commands/gc-onboard.md', content: renderClaudeOnboardCommand() },

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
 
@@ -145,6 +166,7 @@ gctree scaffold --host both --target /path/to/repo
 
 ```
 AGENTS.md                                  ← fragmento de gctree añadido a las instrucciones del agente
+.codex/hooks.json                         ← hooks de auto-resolve para SessionStart/UserPromptSubmit
 .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
@@ -155,7 +177,8 @@ AGENTS.md                                  ← fragmento de gctree añadido a la
 
 ```
 CLAUDE.md                                        ← fragmento de gctree añadido
-.claude/hooks/gctree-session-start.md            ← hook de inicio de sesión
+.claude/hooks/hooks.json                         ← hooks de auto-resolve para SessionStart/UserPromptSubmit
+.claude/hooks/gctree-session-start.md            ← nota fallback 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

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 の設定例
 
@@ -145,6 +166,7 @@ gctree scaffold --host both --target /path/to/repo
 
 ```
 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          ← オンボーディングスキル
@@ -155,7 +177,8 @@ AGENTS.md                                  ← gctree のスニペットがエ
 
 ```
 CLAUDE.md                                        ← gctree のスニペットが追記される
-.claude/hooks/gctree-session-start.md            ← セッション開始フック
+.claude/hooks/hooks.json                         ← SessionStart / UserPromptSubmit の自動 resolve フック
+.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     ← 更新スラッシュコマンド

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"`
 
 ## 저장소 범위 설정 예시 흐름
 
@@ -145,6 +166,7 @@ gctree scaffold --host both --target /path/to/repo
 
 ```
 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          ← 온보딩 스킬
@@ -155,7 +177,8 @@ AGENTS.md                                  ← 에이전트 지시사항에 gctr
 
 ```
 CLAUDE.md                                        ← gctree 스니펫 추가
-.claude/hooks/gctree-session-start.md            ← 세션 시작 훅
+.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     ← 업데이트 슬래시 명령

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
 
@@ -145,6 +166,7 @@ gctree scaffold --host both --target /path/to/repo
 
 ```
 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
@@ -155,7 +177,8 @@ AGENTS.md                                  ← gctree snippet appended to agent
 
 ```
 CLAUDE.md                                        ← gctree snippet appended
-.claude/hooks/gctree-session-start.md            ← session-start hook
+.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

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"`
 
 ## 仓库作用范围示例流程
 
@@ -145,6 +166,7 @@ gctree scaffold --host both --target /path/to/repo
 
 ```
 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 技能
@@ -155,7 +177,8 @@ AGENTS.md                                  ← gctree 代码片段追加到 agen
 
 ```
 CLAUDE.md                                        ← gctree 代码片段追加
-.claude/hooks/gctree-session-start.md            ← 会话启动钩子
+.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     ← 更新斜杠命令

package/package.json

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