@handsupmin/gc-tree 0.6.2 → 0.7.1

package/README.es.md

@@ -152,6 +152,7 @@ Probado con documentación interna real (4 exportaciones de Notion, consultas mi
 ## Funciona con Claude Code y Codex — ambos verificados
 
 ```bash
+gctree init                         # configura ~/.gctree y la activación global para el provider elegido
 gctree scaffold --host claude-code   # instala snippet en CLAUDE.md + /gc-onboard, /gc-update-global-context
 gctree scaffold --host codex         # instala snippet en AGENTS.md + $gc-onboard, $gc-update-global-context
 gctree scaffold --host both          # ambos a la vez
@@ -217,7 +218,7 @@ gctree set-repo-scope --branch client-b --exclude   # excluir el repo actual
 ~/.gctree/
   branches/
     main/
-      index.md          ← índice compacto, ≤2000 chars, se carga primero
+      index.md          ← índice compacto, se carga primero
       docs/
         auth.md         ← doc completo, se lee solo cuando hace falta
         architecture.md
@@ -247,7 +248,8 @@ El contexto vive fuera de tus repositorios — sin reglas de `.gitignore`, sin c
 | Ver reglas de alcance por repo                     | `gctree repo-map`                                               |
 | Incluir o excluir el repo actual para un gc-branch | `gctree set-repo-scope --branch <name> --include` / `--exclude` |
 | Resetear un gc-branch antes de re-onboard          | `gctree reset-gc-branch --branch <name> --yes`                  |
-| Instalar scaffold en un nuevo entorno              | `gctree scaffold --host codex --target /path/to/repo`           |
+| Instalar un override local en un repo              | `gctree scaffold --host codex --target /path/to/repo`           |
+| Quitar la activación global y el contexto          | `gctree uninstall --yes`                                        |
 
 ---
 

package/README.ja.md

@@ -152,6 +152,7 @@ AI ツールに渡るのは正しいコンテキスト——ナレッジベー
 ## Claude Code と Codex、両方で動作検証済み
 
 ```bash
+gctree init                         # ~/.gctree と選んだプロバイダーのグローバル有効化を設定
 gctree scaffold --host claude-code   # CLAUDE.md スニペット + /gc-onboard、/gc-update-global-context をインストール
 gctree scaffold --host codex         # AGENTS.md スニペット + $gc-onboard、$gc-update-global-context をインストール
 gctree scaffold --host both          # 両方同時に
@@ -217,7 +218,7 @@ gctree set-repo-scope --branch client-b --exclude   # 現在のリポジトリ
 ~/.gctree/
   branches/
     main/
-      index.md          ← 圧縮インデックス、≤2000 文字、最初にロード
+      index.md          ← 圧縮インデックス、最初にロード
       docs/
         auth.md         ← 全文、必要なときだけ読む
         architecture.md
@@ -247,7 +248,8 @@ gctree set-repo-scope --branch client-b --exclude   # 現在のリポジトリ
 | リポジトリ範囲ルールを確認する                   | `gctree repo-map`                                               |
 | 現在のリポジトリを gc-branch に含める / 除外する | `gctree set-repo-scope --branch <name> --include` / `--exclude` |
 | 再オンボーディング前に gc-branch をリセットする  | `gctree reset-gc-branch --branch <name> --yes`                  |
-| 別の環境に scaffold をインストールする           | `gctree scaffold --host codex --target /path/to/repo`           |
+| 1つのリポジトリにローカル override を入れる      | `gctree scaffold --host codex --target /path/to/repo`           |
+| グローバルな gc-tree 有効化とコンテキストを外す  | `gctree uninstall --yes`                                        |
 
 ---
 

package/README.ko.md

@@ -152,6 +152,7 @@ AI 도구가 올바른 컨텍스트를 가져옵니다. 지식 베이스 전체
 ## Claude Code와 Codex 양쪽 모두 검증 완료
 
 ```bash
+gctree init                         # ~/.gctree와 선택한 프로바이더의 전역 활성화 설정
 gctree scaffold --host claude-code   # CLAUDE.md 스니펫 + /gc-onboard, /gc-update-global-context 설치
 gctree scaffold --host codex         # AGENTS.md 스니펫 + $gc-onboard, $gc-update-global-context 설치
 gctree scaffold --host both          # 둘 다 한번에
@@ -217,7 +218,7 @@ gctree set-repo-scope --branch client-b --exclude   # 현재 레포 제외
 ~/.gctree/
   branches/
     main/
-      index.md          ← 압축 인덱스, ≤2000자, 먼저 로드됨
+      index.md          ← 압축 인덱스, 먼저 로드됨
       docs/
         auth.md         ← 전체 문서, 필요할 때만 읽음
         architecture.md
@@ -247,7 +248,8 @@ gctree set-repo-scope --branch client-b --exclude   # 현재 레포 제외
 | 레포 범위 규칙 확인               | `gctree repo-map`                                               |
 | 현재 레포 포함/제외 설정          | `gctree set-repo-scope --branch <name> --include` / `--exclude` |
 | 재온보딩 전 gc-branch 초기화      | `gctree reset-gc-branch --branch <name> --yes`                  |
-| 새 환경 스캐폴딩                  | `gctree scaffold --host codex --target /path/to/repo`           |
+| 특정 레포에 로컬 override 설치   | `gctree scaffold --host codex --target /path/to/repo`           |
+| 전역 gc-tree 활성화와 컨텍스트 제거 | `gctree uninstall --yes`                                     |
 
 ---
 

package/README.md

@@ -152,6 +152,7 @@ Tested against real internal documentation (4 Notion exports, Korean + English m
 ## Works with Claude Code and Codex — both verified
 
 ```bash
+gctree init                         # sets up ~/.gctree and global activation for your chosen provider(s)
 gctree scaffold --host claude-code   # installs CLAUDE.md snippet + /gc-onboard, /gc-update-global-context
 gctree scaffold --host codex         # installs AGENTS.md snippet + $gc-onboard, $gc-update-global-context
 gctree scaffold --host both          # both at once
@@ -217,7 +218,7 @@ gctree set-repo-scope --branch client-b --exclude   # exclude current repo
 ~/.gctree/
   branches/
     main/
-      index.md          ← compact index, ≤2000 chars, loaded first
+      index.md          ← compact index, loaded first
       docs/
         auth.md         ← full doc, read only when needed
         architecture.md
@@ -247,7 +248,8 @@ Context lives outside your repos — no `.gitignore` rules needed, no accidental
 | Show repo-scope rules                          | `gctree repo-map`                                               |
 | Include/exclude current repo for a gc-branch   | `gctree set-repo-scope --branch <name> --include` / `--exclude` |
 | Reset a gc-branch before re-onboarding         | `gctree reset-gc-branch --branch <name> --yes`                  |
-| Scaffold a new environment                     | `gctree scaffold --host codex --target /path/to/repo`           |
+| Add a local override in one repo               | `gctree scaffold --host codex --target /path/to/repo`           |
+| Remove global gc-tree activation and context   | `gctree uninstall --yes`                                        |
 
 ---
 

package/README.zh.md

@@ -152,6 +152,7 @@ AI 工具拿到的是正确的上下文——不是整个知识库，而是恰
 ## Claude Code 和 Codex 均已验证可用
 
 ```bash
+gctree init                         # 设置 ~/.gctree 和所选 provider 的全局激活
 gctree scaffold --host claude-code   # 安装 CLAUDE.md 片段 + /gc-onboard、/gc-update-global-context
 gctree scaffold --host codex         # 安装 AGENTS.md 片段 + $gc-onboard、$gc-update-global-context
 gctree scaffold --host both          # 两者同时安装
@@ -217,7 +218,7 @@ gctree set-repo-scope --branch client-b --exclude   # 排除当前仓库
 ~/.gctree/
   branches/
     main/
-      index.md          ← 压缩索引，≤2000 字符，优先加载
+      index.md          ← 压缩索引，优先加载
       docs/
         auth.md         ← 完整文档，按需读取
         architecture.md
@@ -247,7 +248,8 @@ gctree set-repo-scope --branch client-b --exclude   # 排除当前仓库
 | 查看仓库范围规则                     | `gctree repo-map`                                               |
 | 为 gc-branch 包含或排除当前仓库      | `gctree set-repo-scope --branch <name> --include` / `--exclude` |
 | 重新 onboarding 前重置 gc-branch     | `gctree reset-gc-branch --branch <name> --yes`                  |
-| 在新环境中安装 scaffold              | `gctree scaffold --host codex --target /path/to/repo`           |
+| 在单个仓库中安装本地 override        | `gctree scaffold --host codex --target /path/to/repo`           |
+| 移除全局 gc-tree 激活和上下文        | `gctree uninstall --yes`                                        |
 
 ---
 

package/dist/src/cli.js

@@ -7,7 +7,7 @@ import { dispatchGcTreeHook } from './hook.js';
 import { onboardBranch } from './onboard.js';
 import { buildProviderLaunchPlan, maybeLaunchProvider, promptLanguageSelection, promptLaunchProviderSelection, promptProviderSelection, } from './provider.js';
 import { DEFAULT_BRANCH, branchDir, resolveHome } from './paths.js';
-import { branchRepoMapPath, branchScopeStatus, detectCurrentRepoId, detectRepoRoot, promptResolveScopeDecision, readBranchRepoMap, resolveBranchForRepo, setRepoScopeForBranch, } from './repo-map.js';
+import { branchRepoMapPath, branchScopeStatus, detectCurrentRepoId, promptResolveScopeDecision, readBranchRepoMap, resolveBranchForRepo, setRepoScopeForBranch, } from './repo-map.js';
 import { findRelatedDocs, getDocById, resolveContext } from './resolve.js';
 import { scaffoldHostIntegration } from './scaffold.js';
 import { requirePreferredProvider, writeSettings, readSettings } from './settings.js';
@@ -100,21 +100,16 @@ function normalizeProviderMode(value) {
 async function resolvePreferredProvider(home, explicitProvider) {
     return normalizeProvider(explicitProvider) || (await requirePreferredProvider(home));
 }
-async function ensureScaffold({ providerMode, targetDir, force = false, }) {
+async function ensureScaffold({ providerMode, targetDir, force = false, scope = 'local', }) {
     const hosts = providerMode === 'both' ? ['claude-code', 'codex'] : [providerMode];
-    const combined = { hosts: providerMode, target_dir: targetDir, written: [], skipped_existing: [] };
+    const combined = { hosts: providerMode, target_dir: scope === 'global' ? '(global)' : (targetDir || process.cwd()), written: [], skipped_existing: [] };
     for (const host of hosts) {
-        const result = await scaffoldHostIntegration({ host, targetDir, force });
+        const result = await scaffoldHostIntegration({ host, targetDir, force, scope });
         combined.written.push(...result.written);
         combined.skipped_existing.push(...result.skipped_existing);
     }
     return combined;
 }
-async function resolveTargetDir(explicitTarget) {
-    if (explicitTarget)
-        return explicitTarget;
-    return (await detectRepoRoot(process.cwd())) || process.cwd();
-}
 async function maybePromptProviderMode(explicitProvider) {
     const provider = normalizeProviderMode(explicitProvider);
     if (provider)
@@ -170,7 +165,8 @@ async function main() {
             const providerMode = await maybePromptProviderMode(readArg('--provider'));
             const provider = await resolveLaunchProvider(providerMode);
             const preferredLanguage = await maybePromptLanguage(readArg('--language'));
-            const targetDir = readArg('--target') || process.cwd();
+            const explicitTargetDir = readArg('--target');
+            const launchTargetDir = explicitTargetDir || process.cwd();
             const result = await initHome(home);
             const settings = await writeSettings({
                 home,
@@ -178,13 +174,16 @@ async function main() {
                 preferredProvider: provider,
                 preferredLanguage,
             });
-            const scaffold = await ensureScaffold({ providerMode, targetDir, force: hasFlag('--force') });
+            const globalScaffold = await ensureScaffold({ providerMode, scope: 'global', force: hasFlag('--force') });
+            const scaffold = explicitTargetDir
+                ? await ensureScaffold({ providerMode, targetDir: explicitTargetDir, scope: 'local', force: hasFlag('--force') })
+                : null;
             const launch = (await isBranchContextEmpty(home, result.gc_branch))
                 ? await launchGuidedFlow({
                     provider,
                     providerMode,
                     preferredLanguage,
-                    targetDir,
+                    targetDir: launchTargetDir,
                     gcBranch: result.gc_branch,
                     command: 'gc-onboard',
                     noLaunch: hasFlag('--no-launch'),
@@ -195,6 +194,7 @@ async function main() {
                 provider_mode: settings.provider_mode,
                 preferred_provider: settings.preferred_provider,
                 preferred_language: settings.preferred_language,
+                global_scaffold: globalScaffold,
                 scaffold,
                 launch,
             }, null, 2));
@@ -277,7 +277,9 @@ async function main() {
             const provider = await resolvePreferredProvider(home, readArg('--provider'));
             const settings = await readSettings(home);
             const targetDir = readArg('--target') || process.cwd();
-            const scaffold = await ensureScaffold({ providerMode: settings?.provider_mode || provider, targetDir, force: hasFlag('--force') });
+            const scaffold = readArg('--target')
+                ? await ensureScaffold({ providerMode: settings?.provider_mode || provider, targetDir, scope: 'local', force: hasFlag('--force') })
+                : null;
             const launch = await launchGuidedFlow({
                 provider,
                 providerMode: settings?.provider_mode || provider,
@@ -323,10 +325,9 @@ async function main() {
                 throw new Error('uninstall is destructive. Re-run with --yes to confirm.');
             }
             const host = normalizeProviderMode(readArg('--host')) || 'both';
-            const targetDir = await resolveTargetDir(readArg('--target'));
             const result = await uninstallGcTree({
                 home,
-                targetDir,
+                targetDir: readArg('--target'),
                 host,
                 keepHome: hasFlag('--keep-home'),
             });
@@ -473,7 +474,9 @@ async function main() {
             const provider = await resolvePreferredProvider(home, readArg('--provider'));
             const settings = await readSettings(home);
             const targetDir = readArg('--target') || process.cwd();
-            const scaffold = await ensureScaffold({ providerMode: settings?.provider_mode || provider, targetDir, force: hasFlag('--force') });
+            const scaffold = readArg('--target')
+                ? await ensureScaffold({ providerMode: settings?.provider_mode || provider, targetDir, scope: 'local', force: hasFlag('--force') })
+                : null;
             const launch = await launchGuidedFlow({
                 provider,
                 providerMode: settings?.provider_mode || provider,

package/dist/src/integration-files.js

@@ -1,5 +1,6 @@
 import { access, readFile, rm, writeFile } from 'node:fs/promises';
 import { constants } from 'node:fs';
+import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { mkdir } from 'node:fs/promises';
 const MARKERS = {
@@ -168,3 +169,13 @@ export function gctreeHookJsonTargets(targetDir) {
         claude: join(targetDir, '.claude', 'hooks', 'hooks.json'),
     };
 }
+export function gctreeGlobalRoot(host) {
+    if (host === 'codex') {
+        return process.env.GCTREE_CODEX_GLOBAL_DIR || join(homedir(), '.codex');
+    }
+    return process.env.GCTREE_CLAUDE_GLOBAL_DIR || join(homedir(), '.claude');
+}
+export function gctreeGlobalHookJsonTarget(host) {
+    const root = gctreeGlobalRoot(host);
+    return host === 'codex' ? join(root, 'hooks.json') : join(root, 'hooks', 'hooks.json');
+}

package/dist/src/markdown.js

@@ -7,6 +7,29 @@ export function slugify(value) {
         .replace(/^-|-$/g, '');
     return normalized || 'doc';
 }
+function parseDocReference(value) {
+    const trimmed = String(value || '').trim().replace(/^\.?\//, '');
+    if (!trimmed)
+        return null;
+    const normalized = trimmed.replace(/\\/g, '/');
+    const docsMatch = normalized.match(/^docs\/([^/]+)\/([^/]+?)(?:\.md)?$/i);
+    if (docsMatch) {
+        const category = normalizeCategory(docsMatch[1]);
+        const slug = slugify(docsMatch[2]);
+        if (slug === 'index')
+            return null;
+        return { category, slug, label: docsMatch[2].replace(/\.md$/i, '').trim() };
+    }
+    const directMatch = normalized.match(/^(role|repos|domain|workflows|conventions|infra|verification)\/([^/]+?)(?:\.md)?$/i);
+    if (directMatch) {
+        const category = normalizeCategory(directMatch[1]);
+        const slug = slugify(directMatch[2]);
+        if (slug === 'index')
+            return null;
+        return { category, slug, label: directMatch[2].replace(/\.md$/i, '').trim() };
+    }
+    return null;
+}
 export function ensureSummary(summary) {
     const trimmed = String(summary || '').trim();
     if (!trimmed) {
@@ -158,6 +181,35 @@ export function extractIndexEntries(markdown) {
         .map((line) => line.slice(2).trim())
         .filter(Boolean);
 }
+export function normalizeIndexEntry(value, fallback) {
+    const reference = parseDocReference(value);
+    if (reference) {
+        return {
+            category: reference.category,
+            label: reference.label,
+        };
+    }
+    const trimmed = String(value || '').trim();
+    if (!trimmed)
+        return null;
+    if (/^docs\/index\.md$/i.test(trimmed) || /^index\.md$/i.test(trimmed))
+        return null;
+    return {
+        category: fallback.category,
+        label: trimmed,
+    };
+}
+export function inferDocPlacement(input) {
+    for (const candidate of [input.slug, input.indexLabel]) {
+        const reference = parseDocReference(candidate || '');
+        if (reference) {
+            return { category: reference.category, slug: reference.slug };
+        }
+    }
+    const explicitCategory = input.category ? slugify(input.category) : null;
+    const slug = slugify(input.slug || input.indexLabel || input.title);
+    return { category: explicitCategory, slug };
+}
 export function extractSummary(markdown) {
     const match = String(markdown || '').match(/## Summary\s+([\s\S]*?)(?:\n## |$)/);
     return match?.[1]?.trim() || '';

package/dist/src/onboard.js

@@ -1,13 +1,13 @@
 import { mkdir, rm, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
-import { renderDocMarkdown, slugify } from './markdown.js';
+import { inferDocPlacement, renderDocMarkdown } from './markdown.js';
 import { branchDocsDir, DEFAULT_BRANCH } from './paths.js';
 import { ensureBranchExists, updateBranchMeta, writeIndexFromDocs } from './store.js';
 function docRelativePath(doc) {
     if (doc.slug?.includes('/'))
         return `${doc.slug.replace(/\.md$/i, '')}.md`;
-    const fileBase = slugify(doc.slug || doc.indexLabel || doc.title);
-    const category = doc.category ? slugify(doc.category) : '';
+    const { category, slug } = inferDocPlacement(doc);
+    const fileBase = slug;
     return category ? `${category}/${fileBase}.md` : `${fileBase}.md`;
 }
 export async function onboardBranch({ home, input, branch, }) {

package/dist/src/scaffold.js

@@ -1,6 +1,6 @@
 import { access, mkdir, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
-import { gctreeHookJsonTargets, gctreeManagedMarkdownTargets, mergeGcTreeHooksJson, unmergeGcTreeHooksJson, upsertManagedMarkdownBlock, } from './integration-files.js';
+import { gctreeGlobalHookJsonTarget, gctreeGlobalRoot, gctreeHookJsonTargets, gctreeManagedMarkdownTargets, mergeGcTreeHooksJson, unmergeGcTreeHooksJson, upsertManagedMarkdownBlock, } from './integration-files.js';
 import { onboardingCompletionLines, onboardingProtocolLines } from './onboarding-protocol.js';
 function renderCodexAgentsSnippet() {
     return [
@@ -205,8 +205,17 @@ function renderClaudeUpdateCommand() {
         '',
     ].join('\n');
 }
-export function scaffoldFiles(host) {
+export function scaffoldFiles(host, scope = 'local') {
     if (host === 'codex') {
+        if (scope === 'global') {
+            return [
+                { path: 'hooks.json', content: renderCodexHooksJson() },
+                { path: 'prompts/gctree-bootstrap.md', content: renderCodexBootstrapPrompt() },
+                { path: 'skills/gc-resolve-context/SKILL.md', content: renderCodexResolveSkill() },
+                { path: 'skills/gc-onboard/SKILL.md', content: renderCodexOnboardSkill() },
+                { path: 'skills/gc-update-global-context/SKILL.md', content: renderCodexUpdateSkill() },
+            ];
+        }
         return [
             { path: 'AGENTS.md', content: renderCodexAgentsSnippet() },
             { path: '.codex/hooks.json', content: renderCodexHooksJson() },
@@ -216,6 +225,15 @@ export function scaffoldFiles(host) {
             { path: '.codex/skills/gc-update-global-context/SKILL.md', content: renderCodexUpdateSkill() },
         ];
     }
+    if (scope === 'global') {
+        return [
+            { path: 'hooks/hooks.json', content: renderClaudeHooksJson() },
+            { path: 'hooks/gctree-session-start.md', content: renderClaudeSessionStartHook() },
+            { path: 'commands/gc-resolve-context.md', content: renderClaudeResolveCommand() },
+            { path: 'commands/gc-onboard.md', content: renderClaudeOnboardCommand() },
+            { path: 'commands/gc-update-global-context.md', content: renderClaudeUpdateCommand() },
+        ];
+    }
     return [
         { path: 'CLAUDE.md', content: renderClaudeSnippet() },
         { path: '.claude/hooks/hooks.json', content: renderClaudeHooksJson() },
@@ -225,39 +243,48 @@ export function scaffoldFiles(host) {
         { path: '.claude/commands/gc-update-global-context.md', content: renderClaudeUpdateCommand() },
     ];
 }
-export async function scaffoldHostIntegration({ host, targetDir, force = false, }) {
-    const files = scaffoldFiles(host);
+export async function scaffoldHostIntegration({ host, targetDir, force = false, scope = 'local', }) {
+    const resolvedTargetDir = scope === 'global' ? gctreeGlobalRoot(host) : targetDir;
+    const files = scaffoldFiles(host, scope);
     const written = [];
     const skippedExisting = [];
-    const markdownTargets = gctreeManagedMarkdownTargets(targetDir);
-    const hookTargets = gctreeHookJsonTargets(targetDir);
     const isCodex = host === 'codex';
-    const managedMarkdownPath = isCodex ? markdownTargets.codex : markdownTargets.claude;
-    const managedMarkdownContent = isCodex ? renderCodexAgentsSnippet() : renderClaudeSnippet();
-    await upsertManagedMarkdownBlock({
-        filePath: managedMarkdownPath,
-        content: managedMarkdownContent,
-        marker: isCodex ? 'codex' : 'claude',
-    });
-    written.push(managedMarkdownPath);
-    const hookPath = isCodex ? hookTargets.codex : hookTargets.claude;
+    let managedMarkdownPath = null;
+    let hookPath;
+    if (scope === 'local') {
+        const markdownTargets = gctreeManagedMarkdownTargets(resolvedTargetDir);
+        const hookTargets = gctreeHookJsonTargets(resolvedTargetDir);
+        managedMarkdownPath = isCodex ? markdownTargets.codex : markdownTargets.claude;
+        const managedMarkdownContent = isCodex ? renderCodexAgentsSnippet() : renderClaudeSnippet();
+        await upsertManagedMarkdownBlock({
+            filePath: managedMarkdownPath,
+            content: managedMarkdownContent,
+            marker: isCodex ? 'codex' : 'claude',
+        });
+        written.push(managedMarkdownPath);
+        hookPath = isCodex ? hookTargets.codex : hookTargets.claude;
+        if (!isCodex) {
+            const oldHooksPath = join(resolvedTargetDir, '.claude', 'settings.json');
+            await unmergeGcTreeHooksJson(oldHooksPath);
+        }
+    }
+    else {
+        hookPath = gctreeGlobalHookJsonTarget(host);
+        if (!isCodex) {
+            const oldHooksPath = join(resolvedTargetDir, 'settings.json');
+            await unmergeGcTreeHooksJson(oldHooksPath);
+        }
+    }
     await mergeGcTreeHooksJson({
         filePath: hookPath,
         target: isCodex ? 'codex' : 'claude-code',
     });
     written.push(hookPath);
-    // Migrate: clean up gctree entries from old hooks.json location (claude-code only)
-    if (!isCodex) {
-        const oldHooksPath = join(targetDir, '.claude', 'settings.json');
-        await unmergeGcTreeHooksJson(oldHooksPath);
-    }
     const targets = files.map((file) => ({
         ...file,
-        fullPath: join(targetDir, file.path),
+        fullPath: join(resolvedTargetDir, file.path),
     })).filter((target) => {
-        if (isCodex)
-            return target.path !== 'AGENTS.md' && target.path !== '.codex/hooks.json';
-        return target.path !== 'CLAUDE.md' && target.path !== '.claude/hooks/hooks.json';
+        return target.fullPath !== hookPath && target.fullPath !== managedMarkdownPath;
     });
     for (const target of targets) {
         let exists = false;
@@ -279,7 +306,7 @@ export async function scaffoldHostIntegration({ host, targetDir, force = false,
     }
     return {
         host,
-        target_dir: targetDir,
+        target_dir: resolvedTargetDir,
         written,
         skipped_existing: skippedExisting,
     };

package/dist/src/store.js

@@ -2,7 +2,7 @@ import { cp, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { branchDir, branchDocsDir, branchIndexPath, branchMetaPath, branchesRoot, DEFAULT_BRANCH, headPath, } from './paths.js';
-import { extractIndexEntries, renderIndexMarkdown } from './markdown.js';
+import { extractIndexEntries, inferDocPlacement, normalizeIndexEntry, renderIndexMarkdown } from './markdown.js';
 async function listDocRelativePaths(dir, prefix = '') {
     const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
     const files = [];
@@ -113,14 +113,19 @@ export async function writeIndexFromDocs(home, branch) {
         const raw = await readFile(join(docsDir, file), 'utf8');
         const title = raw.match(/^#\s+(.+)$/m)?.[1]?.trim() || file.replace(/\.md$/i, '').replace(/-/g, ' ');
         const parts = file.replace(/\.md$/i, '').split('/').filter(Boolean);
-        const category = parts.length > 1 ? parts[0] : 'general';
-        const label = parts.length > 1 ? parts[parts.length - 1] : title;
-        const indexEntries = extractIndexEntries(raw);
-        const entryLabels = indexEntries.length > 0 ? indexEntries : [label];
-        return entryLabels.map((entryLabel) => ({
+        const fallbackCategory = parts.length > 1 ? parts[0] : 'general';
+        const fallbackLabel = parts.length > 1 ? parts[parts.length - 1] : title;
+        const inferred = inferDocPlacement({ title, indexLabel: title });
+        const docCategory = inferred.category || fallbackCategory;
+        const indexEntries = extractIndexEntries(raw)
+            .map((entry) => normalizeIndexEntry(entry, { category: docCategory, label: fallbackLabel }))
+            .filter((entry) => Boolean(entry));
+        const entryLabels = indexEntries.length > 0 ? indexEntries : [{ category: docCategory, label: fallbackLabel }];
+        const uniqueEntries = [...new Map(entryLabels.map((entry) => [`${entry.category}::${entry.label}`, entry])).values()];
+        return uniqueEntries.map((entry) => ({
             title,
-            label: entryLabel,
-            category,
+            label: entry.label,
+            category: entry.category,
             path: `docs/${file}`,
         }));
     }));

package/dist/src/uninstall.js

@@ -1,6 +1,6 @@
 import { readdir, rm } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
-import { gctreeHookJsonTargets, gctreeManagedMarkdownTargets, pathExists, removeManagedMarkdownBlock, unmergeGcTreeHooksJson, } from './integration-files.js';
+import { gctreeGlobalHookJsonTarget, gctreeGlobalRoot, gctreeHookJsonTargets, gctreeManagedMarkdownTargets, pathExists, removeManagedMarkdownBlock, unmergeGcTreeHooksJson, } from './integration-files.js';
 import { scaffoldFiles } from './scaffold.js';
 async function pathHasEntries(path) {
     const entries = await readdir(path).catch(() => []);
@@ -18,52 +18,56 @@ async function pruneEmptyParents(targetPath, stopDir) {
 function hostsFor(mode) {
     return mode === 'both' ? ['claude-code', 'codex'] : [mode];
 }
+async function uninstallHostScaffold({ host, scope, targetDir, removed, }) {
+    const isCodex = host === 'codex';
+    const managedMarkdownPath = scope === 'local'
+        ? (isCodex ? gctreeManagedMarkdownTargets(targetDir).codex : gctreeManagedMarkdownTargets(targetDir).claude)
+        : null;
+    const hookPath = scope === 'local'
+        ? (isCodex ? gctreeHookJsonTargets(targetDir).codex : gctreeHookJsonTargets(targetDir).claude)
+        : gctreeGlobalHookJsonTarget(host);
+    if (managedMarkdownPath) {
+        const markdownStatus = await removeManagedMarkdownBlock({
+            filePath: managedMarkdownPath,
+            marker: isCodex ? 'codex' : 'claude',
+        });
+        if (markdownStatus !== 'missing') {
+            removed.push(managedMarkdownPath);
+            await pruneEmptyParents(managedMarkdownPath, targetDir);
+        }
+    }
+    const hookStatus = await unmergeGcTreeHooksJson(hookPath);
+    if (hookStatus !== 'missing') {
+        removed.push(hookPath);
+        await pruneEmptyParents(hookPath, targetDir);
+    }
+    const extraTargets = scaffoldFiles(host, scope)
+        .map((file) => join(targetDir, file.path))
+        .filter((path) => path !== hookPath && path !== managedMarkdownPath);
+    for (const target of [...new Set(extraTargets)]) {
+        if (!(await pathExists(target)))
+            continue;
+        await rm(target, { recursive: true, force: true });
+        removed.push(target);
+        await pruneEmptyParents(target, targetDir);
+    }
+}
 export async function uninstallGcTree({ home, targetDir, host = 'both', keepHome = false, }) {
     const removed = [];
-    const markdownTargets = gctreeManagedMarkdownTargets(targetDir);
-    const hookTargets = gctreeHookJsonTargets(targetDir);
     for (const entry of hostsFor(host)) {
-        if (entry === 'codex') {
-            const markdownStatus = await removeManagedMarkdownBlock({
-                filePath: markdownTargets.codex,
-                marker: 'codex',
-            });
-            if (markdownStatus !== 'missing') {
-                removed.push(markdownTargets.codex);
-                await pruneEmptyParents(markdownTargets.codex, targetDir);
-            }
-            const hookStatus = await unmergeGcTreeHooksJson(hookTargets.codex);
-            if (hookStatus !== 'missing') {
-                removed.push(hookTargets.codex);
-                await pruneEmptyParents(hookTargets.codex, targetDir);
-            }
-        }
-        else {
-            const markdownStatus = await removeManagedMarkdownBlock({
-                filePath: markdownTargets.claude,
-                marker: 'claude',
+        await uninstallHostScaffold({
+            host: entry,
+            scope: 'global',
+            targetDir: gctreeGlobalRoot(entry),
+            removed,
+        });
+        if (targetDir) {
+            await uninstallHostScaffold({
+                host: entry,
+                scope: 'local',
+                targetDir,
+                removed,
             });
-            if (markdownStatus !== 'missing') {
-                removed.push(markdownTargets.claude);
-                await pruneEmptyParents(markdownTargets.claude, targetDir);
-            }
-            const hookStatus = await unmergeGcTreeHooksJson(hookTargets.claude);
-            if (hookStatus !== 'missing') {
-                removed.push(hookTargets.claude);
-                await pruneEmptyParents(hookTargets.claude, targetDir);
-            }
-        }
-        const extraTargets = scaffoldFiles(entry)
-            .map((file) => join(targetDir, file.path))
-            .filter((path) => entry === 'codex'
-            ? path !== markdownTargets.codex && path !== hookTargets.codex
-            : path !== markdownTargets.claude && path !== hookTargets.claude);
-        for (const target of [...new Set(extraTargets)]) {
-            if (!(await pathExists(target)))
-                continue;
-            await rm(target, { recursive: true, force: true });
-            removed.push(target);
-            await pruneEmptyParents(target, targetDir);
         }
     }
     let homeRemoved = false;
@@ -73,7 +77,7 @@ export async function uninstallGcTree({ home, targetDir, host = 'both', keepHome
         removed.push(home);
     }
     return {
-        target_dir: targetDir,
+        target_dir: targetDir || '(global)',
         home,
         host,
         home_removed: homeRemoved,

package/docs/principles.es.md

@@ -36,7 +36,7 @@ Esto le da a las herramientas aguas abajo un camino rápido: leer primero la ver
 ## 5. Hacer el onboarding explícito y guiado
 
 Un usuario no debería tener que escribir a mano JSON de onboarding solo para crear un árbol de contexto útil.
-`gctree init` y `gctree onboard` deben guiar al usuario a través de su proveedor preferido y escribir el contexto resultante en la gc-branch activa.
+`gctree init` y `gctree onboard` deben guiar al usuario a través de su proveedor preferido, habilitar ese proveedor globalmente y escribir el contexto resultante en la gc-branch activa.
 
 El onboarding es solo para gc-branches vacías.
 Si una gc-branch ya contiene contexto, el camino correcto es:
@@ -59,5 +59,5 @@ En la práctica, esto significa que se inyecta aproximadamente el 4 % del contex
 ## 8. Mantenerse agnóstico al proveedor
 
 `gctree` almacena el contexto en archivos markdown simples que cualquier herramienta puede leer.
-Claude Code y Codex hacen scaffold contra el mismo almacén subyacente mediante `gctree scaffold`.
+Claude Code y Codex usan el mismo almacén subyacente. `gctree init` instala la superficie global de hooks orientada al proveedor, y `gctree scaffold` es la ruta de override local para un repositorio o workspace concreto.
 Agregar soporte para un nuevo proveedor significa escribir una nueva plantilla de scaffold — sin cambios en la lógica central de almacenamiento ni de resolve.

package/docs/principles.ja.md

@@ -36,7 +36,7 @@ gc-branch がマシン上のすべてのリポジトリに黙って影響して
 ## 5. オンボーディングは明示的かつガイド付きにする
 
 使えるコンテキストツリーを作るために、ユーザーがオンボーディング用の JSON を手書きしなければならないのはよくありません。
-`gctree init` と `gctree onboard` は、ユーザーが選んだプロバイダーに沿って流れを案内し、その結果のコンテキストを現在アクティブな gc-branch に書き込むべきです。
+`gctree init` と `gctree onboard` は、ユーザーが選んだプロバイダーに沿って流れを案内し、そのプロバイダーをグローバル有効化し、その結果のコンテキストを現在アクティブな gc-branch に書き込むべきです。
 
 オンボーディングは空の gc-branch に対してだけ行うものです。
 すでにコンテキストが入っている gc-branch の場合、正しい道筋は次のどちらかです。
@@ -59,5 +59,5 @@ gc-branch がマシン上のすべてのリポジトリに黙って影響して
 ## 8. プロバイダーに依存しない設計を保つ
 
 `gctree` はコンテキストをプレーンなマークダウンファイルとして保存するため、どのツールでも読み込めます。
-Claude Code と Codex はどちらも `gctree scaffold` を通じて同じ基盤のストアに対して scaffold します。
+Claude Code と Codex はどちらも同じ基盤ストアを使います。`gctree init` はグローバルなプロバイダーフック面をインストールし、`gctree scaffold` は1つのリポジトリやワークスペース向けのローカル override 経路です。
 新しいプロバイダーのサポートを追加するには、新しい scaffold テンプレートを書くだけです。コアのストレージや resolve ロジックに変更は不要です。

package/docs/principles.ko.md

@@ -36,7 +36,7 @@ gc-branch가 머신의 모든 저장소에 조용히 영향을 미쳐서는 안
 ## 5. 온보딩을 명시적이고 안내된 방식으로 만든다
 
 사용자가 유용한 컨텍스트 트리를 만들기 위해 온보딩 JSON을 직접 작성하도록 요구해서는 안 됩니다.
-`gctree init`과 `gctree onboard`는 사용자가 선호하는 프로바이더를 안내하고, 결과 컨텍스트를 활성 gc-branch에 기록해야 합니다.
+`gctree init`과 `gctree onboard`는 사용자가 선호하는 프로바이더를 안내하고, 해당 프로바이더를 전역 활성화하며, 결과 컨텍스트를 활성 gc-branch에 기록해야 합니다.
 
 온보딩은 빈 gc-branch에만 적용됩니다.
 gc-branch에 이미 컨텍스트가 있다면, 올바른 경로는 다음 중 하나입니다:
@@ -59,5 +59,5 @@ gc-branch에 이미 컨텍스트가 있다면, 올바른 경로는 다음 중
 ## 8. 프로바이더에 종속되지 않는다
 
 `gctree`는 어떤 도구든 읽을 수 있는 일반 마크다운 파일에 컨텍스트를 저장합니다.
-Claude Code와 Codex 모두 `gctree scaffold`를 통해 동일한 기반 저장소에 대해 scaffold합니다.
+Claude Code와 Codex 모두 동일한 기반 저장소를 사용합니다. `gctree init`은 전역 프로바이더 훅 표면을 설치하고, `gctree scaffold`는 한 저장소나 워크스페이스를 위한 로컬 override 경로입니다.
 새로운 프로바이더 지원 추가는 새 scaffold 템플릿을 작성하는 것을 의미합니다 — 핵심 저장소나 resolve 로직은 변경이 필요 없습니다.

package/docs/principles.md

@@ -36,7 +36,7 @@ That gives downstream tools a fast path: read the short version first, then expa
 ## 5. Make onboarding explicit and guided
 
 A user should not have to hand-author onboarding JSON just to create a useful context tree.
-`gctree init` and `gctree onboard` should guide the user through their preferred provider and write the resulting context into the active gc-branch.
+`gctree init` and `gctree onboard` should guide the user through their preferred provider, enable that provider globally, and write the resulting context into the active gc-branch.
 
 Onboarding is only for empty gc-branches.
 If a gc-branch already contains context, the correct path is either:
@@ -59,5 +59,5 @@ In practice this means roughly 4% of total stored context is injected per query.
 ## 8. Stay provider-agnostic
 
 `gctree` stores context in plain markdown files that any tool can read.
-Claude Code and Codex both scaffold against the same underlying store via `gctree scaffold`.
+Claude Code and Codex both use the same underlying store. `gctree init` installs the global provider-facing hook surface, and `gctree scaffold` is the local override path for one repository or workspace.
 Adding support for a new provider means writing a new scaffold template — no changes to the core storage or resolve logic.

package/docs/principles.zh.md

@@ -36,7 +36,7 @@ gc-branch 不应该悄无声息地影响机器上的每一个代码仓库。
 ## 5. 让 onboarding 明确且有引导
 
 用户不应该仅仅为了创建一个有用的上下文树而手动编写 onboarding JSON。
-`gctree init` 和 `gctree onboard` 应该引导用户选择首选的提供商，并将生成的上下文写入活跃的 gc-branch。
+`gctree init` 和 `gctree onboard` 应该引导用户选择首选的提供商，为该提供商启用全局激活，并将生成的上下文写入活跃的 gc-branch。
 
 Onboarding 仅适用于空的 gc-branch。
 如果一个 gc-branch 已经包含上下文，正确的做法是：
@@ -59,5 +59,5 @@ Onboarding 仅适用于空的 gc-branch。
 ## 8. 保持提供商无关性
 
 `gctree` 将上下文存储在任何工具都能读取的纯 Markdown 文件中。
-Claude Code 和 Codex 都通过 `gctree scaffold` 对接同一个底层存储。
+Claude Code 和 Codex 使用同一个底层存储。`gctree init` 安装全局 provider hook 表面，`gctree scaffold` 则是针对单个仓库或工作区的本地 override 路径。
 添加对新提供商的支持，意味着编写一个新的 scaffold 模板——无需对核心存储或 resolve 逻辑做任何修改。

package/docs/usage.es.md

@@ -25,7 +25,7 @@ Un flujo de trabajo estándar con `gctree` tiene este aspecto: inicializar gc-tr
 
 | Comando | Propósito |
 | --- | --- |
-| `gctree init` | Crear `~/.gctree`, crear la gc-branch `main` predeterminada, guardar el modo de proveedor, el proveedor de onboarding y el idioma preferido, hacer scaffold del entorno actual y comenzar el onboarding guiado cuando `main` está vacía. |
+| `gctree init` | Crear `~/.gctree`, crear la gc-branch `main` predeterminada, guardar el modo de proveedor, el proveedor de onboarding y el idioma preferido, instalar hooks/comandos/skills globales del proveedor y comenzar el onboarding guiado cuando `main` está vacía. |
 | `gctree checkout <branch>` | Cambiar la gc-branch activa. |
 | `gctree checkout -b <branch>` | Crear y cambiar a una nueva gc-branch vacía. |
 | `gctree branches` | Listar las gc-branches disponibles y mostrar la activa. |
@@ -40,7 +40,8 @@ Un flujo de trabajo estándar con `gctree` tiene este aspecto: inicializar gc-tr
 | `gctree reset-gc-branch --branch <name> --yes` | Limpiar una gc-branch para poder hacer onboarding de nuevo. |
 | `gctree update-global-context` | Iniciar una actualización duradera guiada para la gc-branch activa. |
 | `gctree update-gc` / `gctree ugc` | Alias para `gctree update-global-context`. |
-| `gctree scaffold --host <codex\|claude-code>` | Instalar la interfaz de comandos orientada al proveedor en otro entorno. |
+| `gctree scaffold --host <codex\|claude-code>` | Instalar un override local orientado al proveedor en un repositorio o workspace concreto. |
+| `gctree uninstall --yes` | Eliminar `~/.gctree` y la activación global de gctree. |
 
 ## Qué devuelve resolve
 
@@ -121,7 +122,7 @@ gctree init
 Luego:
 
 1. elegir `codex` o `claude-code`
-2. dejar que `gctree` haga scaffold del entorno actual
+2. dejar que `gctree` instale la activación global para ese proveedor
 3. completar el onboarding guiado para la gc-branch `main`
 
 ## Ejemplo de flujo con múltiples branches
@@ -154,7 +155,7 @@ Si un repositorio recién relevante también debería pasar a formar parte del c
 
 ### Codex CLI / Claude Code CLI
 
-`gctree scaffold` instala archivos de comandos orientados al proveedor en el directorio de destino.
+`gctree init` instala la superficie global de hooks orientada al proveedor. `gctree scaffold` instala un override local en un directorio de destino cuando un repositorio concreto necesita sus propios snippets markdown o una superficie de comandos local.
 
 ```bash
 gctree scaffold --host codex --target /path/to/repo
@@ -162,7 +163,17 @@ gctree scaffold --host claude-code --target /path/to/repo
 gctree scaffold --host both --target /path/to/repo
 ```
 
-**Archivos escritos para `--host codex`:**
+**Archivos globales de Codex (`gctree init`):**
+
+```
+~/.codex/hooks.json                              ← hooks de auto-resolve para SessionStart/UserPromptSubmit
+~/.codex/prompts/gctree-bootstrap.md            ← contexto de arranque para sesiones de Codex
+~/.codex/skills/gc-resolve-context/SKILL.md     ← skill de resolve
+~/.codex/skills/gc-onboard/SKILL.md             ← skill de onboarding
+~/.codex/skills/gc-update-global-context/SKILL.md  ← skill de actualización
+```
+
+**Archivos de override local para `gctree scaffold --host codex`:**
 
 ```
 AGENTS.md                                  ← fragmento de gctree añadido a las instrucciones del agente
@@ -173,7 +184,17 @@ AGENTS.md                                  ← fragmento de gctree añadido a la
 .codex/skills/gc-update-global-context/SKILL.md  ← skill de actualización
 ```
 
-**Archivos escritos para `--host claude-code`:**
+**Archivos globales de Claude Code (`gctree init`):**
+
+```
+~/.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
+```
+
+**Archivos de override local para `gctree scaffold --host claude-code`:**
 
 ```
 CLAUDE.md                                        ← fragmento de gctree añadido
@@ -184,7 +205,7 @@ CLAUDE.md                                        ← fragmento de gctree añadid
 .claude/commands/gc-update-global-context.md     ← comando slash de actualización
 ```
 
-Los archivos existentes no se modifican a menos que pases `--force`.
+Los archivos locales existentes no se modifican a menos que pases `--force`.
 
 ### Comportamiento en tiempo de ejecución
 

package/docs/usage.ja.md

@@ -25,7 +25,7 @@
 
 | コマンド | 役割 |
 | --- | --- |
-| `gctree init` | `~/.gctree` を作成し、デフォルトの `main` gc-branch を作り、プロバイダーモード・オンボーディングプロバイダー・優先言語を保存し、現在の環境を scaffold し、`main` が空ならガイド付きオンボーディングまで開始します。 |
+| `gctree init` | `~/.gctree` を作成し、デフォルトの `main` gc-branch を作り、プロバイダーモード・オンボーディングプロバイダー・優先言語を保存し、グローバルなプロバイダーフック/コマンド/スキルをインストールし、`main` が空ならガイド付きオンボーディングまで開始します。 |
 | `gctree checkout <branch>` | アクティブな gc-branch を切り替えます。 |
 | `gctree checkout -b <branch>` | 新しい空の gc-branch を作成し、そのまま切り替えます。 |
 | `gctree branches` | 利用可能な gc-branch 一覧と、現在アクティブなものを表示します。 |
@@ -40,7 +40,8 @@
 | `gctree reset-gc-branch --branch <name> --yes` | gc-branch を空にして再オンボード可能な状態にします。 |
 | `gctree update-global-context` | アクティブな gc-branch に対するガイド付き永続的更新を開始します。 |
 | `gctree update-gc` / `gctree ugc` | `gctree update-global-context` の別名です。 |
-| `gctree scaffold --host <codex\|claude-code>` | 別の環境にプロバイダー向けコマンド面をインストールします。 |
+| `gctree scaffold --host <codex\|claude-code>` | 1つのリポジトリやワークスペースにローカルなプロバイダー override をインストールします。 |
+| `gctree uninstall --yes` | `~/.gctree` とグローバルな gctree 有効化を削除します。 |
 
 ## resolve が返す内容
 
@@ -121,7 +122,7 @@ gctree init
 そのあと:
 
 1. `codex` か `claude-code` を選ぶ
-2. `gctree` に現在の環境を scaffold させる
+2. `gctree` にそのプロバイダー向けのグローバル有効化をインストールさせる
 3. `main` gc-branch のガイド付きオンボーディングを完了する
 
 ## 複数ブランチを使う例
@@ -154,7 +155,7 @@ gctree ugc
 
 ### Codex CLI / Claude Code CLI
 
-`gctree scaffold` はプロバイダー向けのコマンドファイルをターゲットディレクトリにインストールします。
+`gctree init` はグローバルなプロバイダーフック面をインストールします。`gctree scaffold` は特定のリポジトリに独自の markdown スニペットやローカルなコマンド面が必要なときに、ターゲットディレクトリへローカル override をインストールします。
 
 ```bash
 gctree scaffold --host codex --target /path/to/repo
@@ -162,7 +163,17 @@ gctree scaffold --host claude-code --target /path/to/repo
 gctree scaffold --host both --target /path/to/repo
 ```
 
-**`--host codex` で書き込まれるファイル:**
+**Codex のグローバルファイル（`gctree init`）:**
+
+```
+~/.codex/hooks.json                              ← SessionStart / UserPromptSubmit の自動 resolve フック
+~/.codex/prompts/gctree-bootstrap.md            ← Codex セッション向けのブートストラップコンテキスト
+~/.codex/skills/gc-resolve-context/SKILL.md     ← resolve スキル
+~/.codex/skills/gc-onboard/SKILL.md             ← オンボーディングスキル
+~/.codex/skills/gc-update-global-context/SKILL.md  ← 更新スキル
+```
+
+**`gctree scaffold --host codex` のローカル override ファイル:**
 
 ```
 AGENTS.md                                  ← gctree のスニペットがエージェント指示に追記される
@@ -173,7 +184,17 @@ AGENTS.md                                  ← gctree のスニペットがエ
 .codex/skills/gc-update-global-context/SKILL.md  ← 更新スキル
 ```
 
-**`--host claude-code` で書き込まれるファイル:**
+**Claude Code のグローバルファイル（`gctree init`）:**
+
+```
+~/.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     ← 更新スラッシュコマンド
+```
+
+**`gctree scaffold --host claude-code` のローカル override ファイル:**
 
 ```
 CLAUDE.md                                        ← gctree のスニペットが追記される
@@ -184,7 +205,7 @@ CLAUDE.md                                        ← gctree のスニペット
 .claude/commands/gc-update-global-context.md     ← 更新スラッシュコマンド
 ```
 
-`--force` を渡さない限り、既存のファイルは変更されません。
+`--force` を渡さない限り、既存のローカルファイルは変更されません。
 
 ### ランタイムの動作
 

package/docs/usage.ko.md

@@ -25,7 +25,7 @@
 
 | 명령어 | 설명 |
 | --- | --- |
-| `gctree init` | `~/.gctree` 생성, 기본 `main` gc-branch 생성, 프로바이더 모드·온보딩 프로바이더·선호 언어 저장, 현재 환경 scaffold, `main`이 비어 있으면 안내된 온보딩 시작. |
+| `gctree init` | `~/.gctree` 생성, 기본 `main` gc-branch 생성, 프로바이더 모드·온보딩 프로바이더·선호 언어 저장, 전역 프로바이더 훅/명령/스킬 설치, `main`이 비어 있으면 안내된 온보딩 시작. |
 | `gctree checkout <branch>` | 활성 gc-branch 전환. |
 | `gctree checkout -b <branch>` | 새 빈 gc-branch를 생성하고 전환. |
 | `gctree branches` | 사용 가능한 gc-branch 목록 표시 및 현재 활성 브랜치 표시. |
@@ -40,7 +40,8 @@
 | `gctree reset-gc-branch --branch <name> --yes` | gc-branch를 초기화하여 다시 온보딩할 수 있게 함. |
 | `gctree update-global-context` | 활성 gc-branch의 안내된 지속 업데이트 실행. |
 | `gctree update-gc` / `gctree ugc` | `gctree update-global-context`의 별칭. |
-| `gctree scaffold --host <codex\|claude-code>` | 다른 환경에 프로바이더 대면 명령 표면 설치. |
+| `gctree scaffold --host <codex\|claude-code>` | 특정 저장소나 워크스페이스에 로컬 프로바이더 override 설치. |
+| `gctree uninstall --yes` | `~/.gctree`와 전역 gctree 활성화를 제거. |
 
 ## resolve가 반환하는 것
 
@@ -121,7 +122,7 @@ gctree init
 이후:
 
 1. `codex` 또는 `claude-code` 선택
-2. `gctree`가 현재 환경을 scaffold하도록 허용
+2. `gctree`가 해당 프로바이더에 대해 전역 활성화를 설치하도록 허용
 3. `main` gc-branch의 안내된 온보딩 완료
 
 ## 다중 브랜치 예시 흐름
@@ -154,7 +155,7 @@ gctree ugc
 
 ### Codex CLI / Claude Code CLI
 
-`gctree scaffold`는 대상 디렉토리에 프로바이더 대면 명령 파일을 설치합니다.
+`gctree init`은 전역 프로바이더 훅 표면을 설치합니다. `gctree scaffold`는 특정 저장소에 자체 markdown 스니펫이나 로컬 명령 표면이 필요할 때 대상 디렉토리에 로컬 override를 설치합니다.
 
 ```bash
 gctree scaffold --host codex --target /path/to/repo
@@ -162,7 +163,17 @@ gctree scaffold --host claude-code --target /path/to/repo
 gctree scaffold --host both --target /path/to/repo
 ```
 
-**`--host codex`로 작성되는 파일:**
+**Codex 전역 파일 (`gctree init`):**
+
+```
+~/.codex/hooks.json                              ← SessionStart/UserPromptSubmit 자동 resolve 훅
+~/.codex/prompts/gctree-bootstrap.md            ← Codex 세션 부트스트랩 컨텍스트
+~/.codex/skills/gc-resolve-context/SKILL.md     ← resolve 스킬
+~/.codex/skills/gc-onboard/SKILL.md             ← 온보딩 스킬
+~/.codex/skills/gc-update-global-context/SKILL.md  ← 업데이트 스킬
+```
+
+**`gctree scaffold --host codex` 로컬 override 파일:**
 
 ```
 AGENTS.md                                  ← 에이전트 지시사항에 gctree 스니펫 추가
@@ -173,7 +184,17 @@ AGENTS.md                                  ← 에이전트 지시사항에 gctr
 .codex/skills/gc-update-global-context/SKILL.md  ← 업데이트 스킬
 ```
 
-**`--host claude-code`로 작성되는 파일:**
+**Claude Code 전역 파일 (`gctree init`):**
+
+```
+~/.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     ← 업데이트 슬래시 명령
+```
+
+**`gctree scaffold --host claude-code` 로컬 override 파일:**
 
 ```
 CLAUDE.md                                        ← gctree 스니펫 추가
@@ -184,7 +205,7 @@ CLAUDE.md                                        ← gctree 스니펫 추가
 .claude/commands/gc-update-global-context.md     ← 업데이트 슬래시 명령
 ```
 
-`--force`를 전달하지 않으면 기존 파일은 그대로 유지됩니다.
+`--force`를 전달하지 않으면 기존 로컬 파일은 그대로 유지됩니다.
 
 ### 런타임 동작
 

package/docs/usage.md

@@ -25,7 +25,7 @@ A standard `gctree` workflow looks like this: initialize gc-tree, choose a provi
 
 | Command | Purpose |
 | --- | --- |
-| `gctree init` | Create `~/.gctree`, create the default `main` gc-branch, save the provider mode, onboarding provider, and preferred language, scaffold the current environment, and start guided onboarding when `main` is empty. |
+| `gctree init` | Create `~/.gctree`, create the default `main` gc-branch, save the provider mode, onboarding provider, and preferred language, install global provider hooks/commands/skills, and start guided onboarding when `main` is empty. |
 | `gctree checkout <branch>` | Switch the active gc-branch. |
 | `gctree checkout -b <branch>` | Create and switch to a new empty gc-branch. |
 | `gctree branches` | List available gc-branches and show the active one. |
@@ -40,7 +40,8 @@ A standard `gctree` workflow looks like this: initialize gc-tree, choose a provi
 | `gctree reset-gc-branch --branch <name> --yes` | Clear a gc-branch so it can be onboarded again. |
 | `gctree update-global-context` | Launch a guided durable update for the active gc-branch. |
 | `gctree update-gc` / `gctree ugc` | Aliases for `gctree update-global-context`. |
-| `gctree scaffold --host <codex\|claude-code>` | Install the provider-facing command surface in another environment. |
+| `gctree scaffold --host <codex\|claude-code>` | Install a local provider-facing override in one repository or workspace. |
+| `gctree uninstall --yes` | Remove `~/.gctree` and the global gctree activation for the configured providers. |
 
 ## What resolve returns
 
@@ -121,7 +122,7 @@ gctree init
 Then:
 
 1. choose `codex` or `claude-code`
-2. let `gctree` scaffold the current environment
+2. let `gctree` install global activation for that provider
 3. complete guided onboarding for the `main` gc-branch
 
 ## Example multi-branch flow
@@ -154,7 +155,7 @@ If a newly relevant repo should also become part of the durable context, the nat
 
 ### Codex CLI / Claude Code CLI
 
-`gctree scaffold` installs provider-facing command files into the target directory.
+`gctree init` installs the provider-facing hook surface globally. `gctree scaffold` installs a local override into one target directory when a specific repository needs its own markdown snippets or local command surface.
 
 ```bash
 gctree scaffold --host codex --target /path/to/repo
@@ -162,7 +163,17 @@ gctree scaffold --host claude-code --target /path/to/repo
 gctree scaffold --host both --target /path/to/repo
 ```
 
-**Files written for `--host codex`:**
+**Global files for Codex (`gctree init`):**
+
+```
+~/.codex/hooks.json                              ← SessionStart/UserPromptSubmit auto-resolve hooks
+~/.codex/prompts/gctree-bootstrap.md            ← bootstrap context for Codex sessions
+~/.codex/skills/gc-resolve-context/SKILL.md     ← resolve skill
+~/.codex/skills/gc-onboard/SKILL.md             ← onboarding skill
+~/.codex/skills/gc-update-global-context/SKILL.md  ← update skill
+```
+
+**Local override files for `gctree scaffold --host codex`:**
 
 ```
 AGENTS.md                                  ← gctree snippet appended to agent instructions
@@ -173,7 +184,17 @@ AGENTS.md                                  ← gctree snippet appended to agent
 .codex/skills/gc-update-global-context/SKILL.md  ← update skill
 ```
 
-**Files written for `--host claude-code`:**
+**Global files for Claude Code (`gctree init`):**
+
+```
+~/.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
+```
+
+**Local override files for `gctree scaffold --host claude-code`:**
 
 ```
 CLAUDE.md                                        ← gctree snippet appended
@@ -184,7 +205,7 @@ CLAUDE.md                                        ← gctree snippet appended
 .claude/commands/gc-update-global-context.md     ← update slash command
 ```
 
-Existing files are left untouched unless you pass `--force`.
+Existing local files are left untouched unless you pass `--force`.
 
 ### Runtime behavior
 

package/docs/usage.zh.md

@@ -25,7 +25,7 @@
 
 | 命令 | 用途 |
 | --- | --- |
-| `gctree init` | 创建 `~/.gctree`，创建默认的 `main` gc-branch，保存提供商模式、onboarding 提供商及首选语言，scaffold 当前环境，并在 `main` 为空时启动有引导的 onboarding。 |
+| `gctree init` | 创建 `~/.gctree`，创建默认的 `main` gc-branch，保存提供商模式、onboarding 提供商及首选语言，安装全局 provider hook/command/skill，并在 `main` 为空时启动有引导的 onboarding。 |
 | `gctree checkout <branch>` | 切换活跃的 gc-branch。 |
 | `gctree checkout -b <branch>` | 创建并切换到一个新的空 gc-branch。 |
 | `gctree branches` | 列出可用的 gc-branch 并显示当前活跃的那个。 |
@@ -40,7 +40,8 @@
 | `gctree reset-gc-branch --branch <name> --yes` | 清空一个 gc-branch，使其可以重新 onboard。 |
 | `gctree update-global-context` | 为活跃的 gc-branch 启动有引导的持久化更新。 |
 | `gctree update-gc` / `gctree ugc` | `gctree update-global-context` 的别名。 |
-| `gctree scaffold --host <codex\|claude-code>` | 在另一个环境中安装面向提供商的命令接口。 |
+| `gctree scaffold --host <codex\|claude-code>` | 在单个仓库或工作区中安装本地 provider override。 |
+| `gctree uninstall --yes` | 删除 `~/.gctree` 和全局 gctree 激活。 |
 
 ## resolve 返回的内容
 
@@ -121,7 +122,7 @@ gctree init
 然后：
 
 1. 选择 `codex` 或 `claude-code`
-2. 让 `gctree` scaffold 当前环境
+2. 让 `gctree` 为该 provider 安装全局激活
 3. 对 `main` gc-branch 完成有引导的 onboarding
 
 ## 多分支示例流程
@@ -154,7 +155,7 @@ gctree ugc
 
 ### Codex CLI / Claude Code CLI
 
-`gctree scaffold` 将面向提供商的命令文件安装到目标目录中。
+`gctree init` 会安装全局 provider hook 表面。`gctree scaffold` 则在某个仓库需要自己的 markdown 片段或本地命令表面时，将本地 override 安装到目标目录中。
 
 ```bash
 gctree scaffold --host codex --target /path/to/repo
@@ -162,7 +163,17 @@ gctree scaffold --host claude-code --target /path/to/repo
 gctree scaffold --host both --target /path/to/repo
 ```
 
-**`--host codex` 写入的文件：**
+**Codex 全局文件（`gctree init`）：**
+
+```
+~/.codex/hooks.json                              ← SessionStart / UserPromptSubmit 自动 resolve hook
+~/.codex/prompts/gctree-bootstrap.md            ← Codex 会话引导上下文
+~/.codex/skills/gc-resolve-context/SKILL.md     ← resolve 技能
+~/.codex/skills/gc-onboard/SKILL.md             ← onboarding 技能
+~/.codex/skills/gc-update-global-context/SKILL.md  ← 更新技能
+```
+
+**`gctree scaffold --host codex` 的本地 override 文件：**
 
 ```
 AGENTS.md                                  ← gctree 代码片段追加到 agent 指令中
@@ -173,7 +184,17 @@ AGENTS.md                                  ← gctree 代码片段追加到 agen
 .codex/skills/gc-update-global-context/SKILL.md  ← 更新技能
 ```
 
-**`--host claude-code` 写入的文件：**
+**Claude Code 全局文件（`gctree init`）：**
+
+```
+~/.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     ← 更新斜杠命令
+```
+
+**`gctree scaffold --host claude-code` 的本地 override 文件：**
 
 ```
 CLAUDE.md                                        ← gctree 代码片段追加
@@ -184,7 +205,7 @@ CLAUDE.md                                        ← gctree 代码片段追加
 .claude/commands/gc-update-global-context.md     ← 更新斜杠命令
 ```
 
-除非传入 `--force`，否则已有文件不会被修改。
+除非传入 `--force`，否则已有本地文件不会被修改。
 
 ### 运行时行为
 

package/package.json

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