@handsupmin/gc-tree 0.1.1

package/README.zh.md

@@ -0,0 +1,166 @@
+# gc-tree
+
+面向 AI 编码工具的分支化全局上下文层。
+
+[English](README.md) | [한국어](README.ko.md) | [简体中文](README.zh.md) | [日本語](README.ja.md) | [Español](README.es.md)
+
+## 介绍
+
+`gctree` 是一个面向 AI 编码工具的轻量级 **Global Context Tree**。
+它为长期上下文提供了一个可复用、基于文件、支持分支的明确归宿，而且可以自然接入现有工作流。
+
+当单个 `AGENTS.md`、`CLAUDE.md` 或一段提示词已经不够时，`gctree` 可以帮助你：
+
+- 按产品、客户或工作流隔离上下文
+- 用 markdown 文档保存 source of truth，而不是依赖隐藏记忆
+- 通过精简索引和 summary-first 文档更快定位当前上下文
+- 通过偏好的 LLM CLI 完成 onboarding 与长期更新
+- 让某个 gc-branch 只作用于真正相关的仓库
+
+## 简要特性
+
+- **Provider 驱动的 onboarding**  
+  `gctree init` 会先询问你想使用哪种 provider 模式（`claude-code`、`codex` 或 `both`），再询问响应语言，并保存这些选择，然后给当前环境安装对应的命令表面，并为默认 `main` gc-branch 启动引导式 onboarding。
+- **带仓库范围的 gc-branch**  
+  你可以通过 `~/.gctree/branch-repo-map.json` 把某个 gc-branch 绑定到指定仓库集合，比如让 A 只作用于 B/C/D，而在 F 中忽略。
+- **交互式范围保护**  
+  如果 `gctree resolve` 发现当前仓库还没有映射到这个 gc-branch，它可以询问是仅本次继续、以后总是使用，还是在这个仓库里忽略它。
+- **Summary-first 文档结构**  
+  工具可以先读取简短摘要，只有在需要时才展开完整文档。
+- **引导式长期更新**  
+  不需要手写 JSON 文件，也可以通过同样的 provider 流程更新全局上下文。
+
+## 安装与快速开始
+
+### 通过 npm 安装
+
+```bash
+npm install -g @handsupmin/gc-tree
+```
+
+如果你只想临时运行一次，也可以：
+
+```bash
+npx @handsupmin/gc-tree init
+```
+
+- **包名：** `@handsupmin/gc-tree`
+- **CLI 命令：** `gctree`
+- **要求：** Node.js 20+
+如果要从源码开发，请查看 [docs/local-development.md](docs/local-development.md)。
+
+### 快速开始
+
+#### 1) 初始化 gc-tree
+
+```bash
+gctree init
+```
+
+这个命令会：
+
+- 创建 `~/.gctree`
+- 创建默认 `main` gc-branch
+- 让你选择 provider 模式（`claude-code`、`codex` 或 `both`）
+- 如果你选择 `both`，再选择这次 onboarding 要由哪个 provider 启动
+- 让你选择语言（`English`、`Korean`，或手动输入语言）
+- 把 provider 模式、实际 onboarding provider 和语言保存到 `~/.gctree/settings.json`
+- 为当前环境安装对应的命令表面
+- 当 `main` 仍为空时，为当前 gc-branch 启动引导式 onboarding
+
+#### 2) 解析当前上下文
+
+```bash
+gctree resolve --query "auth token rotation"
+```
+
+如果当前仓库不在这个 gc-branch 的映射范围内，`gctree` 可以让你选择：
+
+1. 这次先继续
+2. 以后这个仓库总是使用这个 gc-branch
+3. 在这个仓库里忽略这个 gc-branch
+
+如果选择 2 或 3，`~/.gctree/branch-repo-map.json` 会被更新。
+
+#### 3) 需要独立上下文时创建新的 gc-branch
+
+```bash
+gctree checkout -b client-b
+```
+
+`checkout -b` 会创建一个**新的空 gc-branch**，不会复制已有分支里的文档。
+
+#### 4) 为一个空的 gc-branch 执行 onboarding
+
+```bash
+gctree onboard
+```
+
+#### 5) 后续执行长期上下文更新
+
+```bash
+gctree update-global-context
+```
+
+简短别名：
+
+```bash
+gctree update-gc
+gctree ugc
+```
+
+如果实际工作后发现某个仓库确实属于当前 gc-branch，更自然的流程是：
+
+1. 先把这个仓库加入 branch repo map
+2. 再用 `gctree update-global-context` 补充这个仓库是什么、为什么重要等长期上下文
+
+#### 6) 重新 onboarding 前先重置 gc-branch
+
+```bash
+gctree reset-gc-branch --branch client-b --yes
+```
+
+### 运行时可见的 provider 命令
+
+scaffold 之后，在运行时可见的命令是：
+
+- **Codex:** `$gc-onboard`, `$gc-update-global-context`
+- **Claude Code:** `/gc-onboard`, `/gc-update-global-context`
+
+这些命令在开始收集或更新长期上下文之前，都应该先明确说明当前激活的是哪个 gc-branch，并且除非用户明确要求切换，否则要始终使用保存下来的语言。
+
+### 核心命令速览
+
+| 目标 | 命令 |
+| --- | --- |
+| 初始化 gc-tree 并选择 provider | `gctree init` |
+| 确认当前 gc-branch | `gctree status` |
+| 搜索当前上下文 | `gctree resolve --query "..."` |
+| 查看仓库范围规则 | `gctree repo-map` |
+| 为 gc-branch 显式设置仓库包含/排除 | `gctree set-repo-scope --branch <name> --include` / `--exclude` |
+| 创建或切换 gc-branch | `gctree checkout <branch>` / `gctree checkout -b <branch>` |
+| 为一个空的 gc-branch 执行 onboarding | `gctree onboard` |
+| 为当前 gc-branch 执行长期更新 | `gctree update-global-context` / `gctree update-gc` / `gctree ugc` |
+| 重新 onboarding 前重置 gc-branch | `gctree reset-gc-branch --branch <name> --yes` |
+| 手动为其他环境安装 scaffold | `gctree scaffold --host codex --target /path/to/repo` |
+
+## 文档
+
+详细文档位于 [`docs/`](docs) 目录下。
+
+- **概念** — [`docs/concept.zh.md`](docs/concept.zh.md)  
+  说明 `gctree` 是什么、解决什么问题，以及全局上下文层的边界。
+- **原理** — [`docs/principles.zh.md`](docs/principles.zh.md)  
+  介绍 gc-branch、仓库范围、summary-first 文档和引导式更新等原则。
+- **使用方法** — [`docs/usage.zh.md`](docs/usage.zh.md)  
+  介绍标准 CLI 流程、provider 命令、仓库范围行为和集成方式。
+- **本地运行方法** — [`docs/local-development.zh.md`](docs/local-development.zh.md)  
+  说明依赖安装、本地运行 CLI 与提交前验证方式。
+
+## 贡献
+
+欢迎贡献。开发流程与 PR 检查清单位于英文文档 [CONTRIBUTING.md](CONTRIBUTING.md)。
+
+## 许可证
+
+MIT。详见 [`LICENSE`](LICENSE)。

package/dist/src/cli.js

@@ -0,0 +1,360 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import { stdin } from 'node:process';
+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 { scaffoldHostIntegration } from './scaffold.js';
+import { requirePreferredProvider, writeSettings, readSettings } from './settings.js';
+import { checkoutBranch, initHome, listBranches, readHead, resetBranchContext, statusForBranch, ensureBranchExists, isBranchContextEmpty } from './store.js';
+import { updateBranchContext } from './update.js';
+function readArg(flag) {
+    const index = process.argv.indexOf(flag);
+    return index === -1 ? undefined : process.argv[index + 1];
+}
+function hasFlag(flag) {
+    return process.argv.includes(flag);
+}
+function usage() {
+    console.error(`Usage:
+  gctree init [--home DIR] [--provider <claude-code|codex|both>] [--language TEXT] [--target DIR] [--no-launch]
+  gctree checkout <branch> [--home DIR]
+  gctree checkout -b <branch> [--home DIR]
+  gctree branches [--home DIR]
+  gctree repo-map [--home DIR]
+  gctree set-repo-scope --branch NAME [--repo NAME] [--cwd DIR] (--include|--exclude) [--home DIR]
+  gctree status [--home DIR] [--cwd DIR]
+  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 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]
+  gctree scaffold --host <codex|claude-code|both> [--target DIR] [--force]
+
+Internal commands:
+  gctree __apply-onboarding --input FILE [--home DIR] [--branch NAME]
+  gctree __apply-update --input FILE [--home DIR] [--branch NAME]
+`);
+    process.exit(1);
+}
+async function readJsonFile(path) {
+    return JSON.parse(await readFile(path, 'utf8'));
+}
+function normalizeProvider(value) {
+    if (!value)
+        return undefined;
+    if (value === 'codex' || value === 'claude-code')
+        return value;
+    throw new Error(`unsupported provider: ${value}`);
+}
+function normalizeProviderMode(value) {
+    if (!value)
+        return undefined;
+    if (value === 'codex' || value === 'claude-code' || value === 'both')
+        return value;
+    throw new Error(`unsupported provider mode: ${value}`);
+}
+async function resolvePreferredProvider(home, explicitProvider) {
+    return normalizeProvider(explicitProvider) || (await requirePreferredProvider(home));
+}
+async function ensureScaffold({ providerMode, targetDir, force = false, }) {
+    const hosts = providerMode === 'both' ? ['claude-code', 'codex'] : [providerMode];
+    const combined = { hosts: providerMode, target_dir: targetDir, written: [], skipped_existing: [] };
+    for (const host of hosts) {
+        const result = await scaffoldHostIntegration({ host, targetDir, force });
+        combined.written.push(...result.written);
+        combined.skipped_existing.push(...result.skipped_existing);
+    }
+    return combined;
+}
+async function maybePromptProviderMode(explicitProvider) {
+    const provider = normalizeProviderMode(explicitProvider);
+    if (provider)
+        return provider;
+    if (!stdin.isTTY)
+        return 'claude-code';
+    return promptProviderSelection();
+}
+async function maybePromptLanguage(explicitLanguage) {
+    if (explicitLanguage?.trim())
+        return explicitLanguage.trim();
+    if (!stdin.isTTY)
+        return 'English';
+    return promptLanguageSelection();
+}
+async function resolveLaunchProvider(providerMode) {
+    if (providerMode === 'both') {
+        if (!stdin.isTTY)
+            return 'claude-code';
+        return promptLaunchProviderSelection();
+    }
+    return providerMode;
+}
+async function launchGuidedFlow({ provider, providerMode, preferredLanguage, targetDir, gcBranch, command, noLaunch, }) {
+    const plan = buildProviderLaunchPlan({ provider, providerMode, preferredLanguage, targetDir, gcBranch, command });
+    if (noLaunch)
+        return plan;
+    return maybeLaunchProvider(plan);
+}
+async function main() {
+    const rawCommand = process.argv[2];
+    if (!rawCommand || rawCommand === '--help' || rawCommand === 'help')
+        usage();
+    const command = rawCommand === 'update-gc' || rawCommand === 'ugc' ? 'update-global-context' : rawCommand;
+    const home = resolveHome(readArg('--home'));
+    switch (command) {
+        case 'init': {
+            const providerMode = await maybePromptProviderMode(readArg('--provider'));
+            const provider = await resolveLaunchProvider(providerMode);
+            const preferredLanguage = await maybePromptLanguage(readArg('--language'));
+            const targetDir = readArg('--target') || process.cwd();
+            const result = await initHome(home);
+            const settings = await writeSettings({
+                home,
+                providerMode,
+                preferredProvider: provider,
+                preferredLanguage,
+            });
+            const scaffold = await ensureScaffold({ providerMode, targetDir, force: hasFlag('--force') });
+            const launch = (await isBranchContextEmpty(home, result.gc_branch))
+                ? await launchGuidedFlow({
+                    provider,
+                    providerMode,
+                    preferredLanguage,
+                    targetDir,
+                    gcBranch: result.gc_branch,
+                    command: 'gc-onboard',
+                    noLaunch: hasFlag('--no-launch'),
+                })
+                : null;
+            console.log(JSON.stringify({
+                ...result,
+                provider_mode: settings.provider_mode,
+                preferred_provider: settings.preferred_provider,
+                preferred_language: settings.preferred_language,
+                scaffold,
+                launch,
+            }, null, 2));
+            return;
+        }
+        case 'checkout': {
+            const create = hasFlag('-b');
+            const branch = create ? process.argv[4] : process.argv[3];
+            if (!branch)
+                usage();
+            const result = await checkoutBranch(home, branch, create);
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        case 'branches': {
+            const result = await listBranches(home);
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        case 'repo-map': {
+            const mapping = await readBranchRepoMap(home);
+            console.log(JSON.stringify({ path: branchRepoMapPath(home), mapping }, null, 2));
+            return;
+        }
+        case 'set-repo-scope': {
+            const gcBranch = readArg('--branch');
+            if (!gcBranch)
+                usage();
+            await ensureBranchExists(home, gcBranch);
+            const repo = readArg('--repo') || (await detectCurrentRepoId(readArg('--cwd') || process.cwd()));
+            if (!repo) {
+                throw new Error('could not determine the current repo. Pass --repo explicitly or run this inside a git repository.');
+            }
+            const include = hasFlag('--include');
+            const exclude = hasFlag('--exclude');
+            if (include === exclude) {
+                throw new Error('set-repo-scope requires exactly one of --include or --exclude.');
+            }
+            const mapping = await setRepoScopeForBranch({
+                home,
+                branch: gcBranch,
+                repo,
+                mode: include ? 'include' : 'exclude',
+            });
+            console.log(JSON.stringify({
+                path: branchRepoMapPath(home),
+                branch: gcBranch,
+                repo,
+                mode: include ? 'include' : 'exclude',
+                mapping,
+            }, null, 2));
+            return;
+        }
+        case 'status': {
+            const gcBranch = (await readHead(home)) || DEFAULT_BRANCH;
+            const result = await statusForBranch(home, gcBranch);
+            const settings = await readSettings(home);
+            const mapping = await readBranchRepoMap(home);
+            const currentRepo = await detectCurrentRepoId(readArg('--cwd') || process.cwd());
+            console.log(JSON.stringify({
+                ...result,
+                provider_mode: settings?.provider_mode || null,
+                preferred_provider: settings?.preferred_provider || null,
+                preferred_language: settings?.preferred_language || null,
+                current_repo: currentRepo,
+                branch_repo_map_path: branchRepoMapPath(home),
+                repo_scope_status: branchScopeStatus(mapping, gcBranch, currentRepo),
+            }, null, 2));
+            return;
+        }
+        case 'onboard': {
+            const gcBranch = readArg('--branch') || (await readHead(home)) || DEFAULT_BRANCH;
+            await ensureBranchExists(home, gcBranch);
+            if (!(await isBranchContextEmpty(home, gcBranch))) {
+                throw new Error(`gc-branch is not empty: ${gcBranch}. Run \`gctree reset-gc-branch --branch ${gcBranch} --yes\` to re-onboard it, or use \`gctree update-global-context\` to make a guided durable update.`);
+            }
+            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 launch = await launchGuidedFlow({
+                provider,
+                providerMode: settings?.provider_mode || provider,
+                preferredLanguage: settings?.preferred_language || 'English',
+                targetDir,
+                gcBranch,
+                command: 'gc-onboard',
+                noLaunch: hasFlag('--no-launch'),
+            });
+            console.log(JSON.stringify({ mode: 'guided_onboarding', gc_branch: gcBranch, preferred_provider: provider, scaffold, launch }, null, 2));
+            return;
+        }
+        case '__apply-onboarding': {
+            const inputPath = readArg('--input');
+            if (!inputPath)
+                usage();
+            const input = await readJsonFile(inputPath);
+            const gcBranch = readArg('--branch') || input.branch || (await readHead(home)) || DEFAULT_BRANCH;
+            if (!(await isBranchContextEmpty(home, gcBranch))) {
+                throw new Error(`gc-branch is not empty: ${gcBranch}. Run \`gctree reset-gc-branch --branch ${gcBranch} --yes\` to re-onboard it, or use \`gctree update-global-context\` instead.`);
+            }
+            const result = await onboardBranch({ home, input, branch: gcBranch });
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        case 'reset-gc-branch': {
+            if (!hasFlag('--yes')) {
+                throw new Error('reset-gc-branch is destructive. Re-run with --yes to confirm.');
+            }
+            const gcBranch = readArg('--branch') || (await readHead(home)) || DEFAULT_BRANCH;
+            const result = await resetBranchContext(home, gcBranch);
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        case 'resolve': {
+            const query = readArg('--query');
+            if (!query)
+                usage();
+            const head = (await readHead(home)) || DEFAULT_BRANCH;
+            const resolved = await resolveBranchForRepo({
+                home,
+                head,
+                explicitBranch: readArg('--branch') || undefined,
+                cwd: readArg('--cwd') || process.cwd(),
+            });
+            let gcBranch = resolved.gc_branch;
+            const currentRepo = resolved.current_repo;
+            let scopeStatus = resolved.scope_status;
+            const settings = await readSettings(home);
+            if (currentRepo && scopeStatus === 'unmapped') {
+                const decision = await promptResolveScopeDecision(gcBranch, currentRepo, settings?.preferred_language || 'English');
+                if (decision === 'always-use') {
+                    await setRepoScopeForBranch({ home, branch: gcBranch, repo: currentRepo, mode: 'include' });
+                    scopeStatus = 'included';
+                }
+                else if (decision === 'ignore') {
+                    await setRepoScopeForBranch({ home, branch: gcBranch, repo: currentRepo, mode: 'exclude' });
+                    console.log(JSON.stringify({
+                        gc_branch: gcBranch,
+                        query,
+                        current_repo: currentRepo,
+                        source: resolved.source,
+                        repo_scope_status: 'excluded',
+                        matches: [],
+                    }, null, 2));
+                    return;
+                }
+            }
+            if (currentRepo && scopeStatus === 'excluded') {
+                console.log(JSON.stringify({
+                    gc_branch: gcBranch,
+                    query,
+                    current_repo: currentRepo,
+                    source: resolved.source,
+                    repo_scope_status: 'excluded',
+                    matches: [],
+                }, null, 2));
+                return;
+            }
+            const result = await resolveContext({ home, branch: gcBranch, query });
+            console.log(JSON.stringify({
+                gc_branch: result.branch,
+                query: result.query,
+                current_repo: currentRepo,
+                source: resolved.source,
+                repo_scope_status: scopeStatus,
+                matches: result.matches,
+            }, null, 2));
+            return;
+        }
+        case 'update-global-context': {
+            const gcBranch = readArg('--branch') || (await readHead(home)) || DEFAULT_BRANCH;
+            await ensureBranchExists(home, gcBranch);
+            if (await isBranchContextEmpty(home, gcBranch)) {
+                throw new Error(`gc-branch is empty: ${gcBranch}. Run \`gctree onboard --branch ${gcBranch}\` to create its context first.`);
+            }
+            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 launch = await launchGuidedFlow({
+                provider,
+                providerMode: settings?.provider_mode || provider,
+                preferredLanguage: settings?.preferred_language || 'English',
+                targetDir,
+                gcBranch,
+                command: 'gc-update-global-context',
+                noLaunch: hasFlag('--no-launch'),
+            });
+            console.log(JSON.stringify({ mode: 'guided_update', gc_branch: gcBranch, preferred_provider: provider, scaffold, launch }, null, 2));
+            return;
+        }
+        case '__apply-update': {
+            const inputPath = readArg('--input');
+            if (!inputPath)
+                usage();
+            const input = await readJsonFile(inputPath);
+            const gcBranch = readArg('--branch') || input.branch || (await readHead(home)) || DEFAULT_BRANCH;
+            const result = await updateBranchContext({ home, input, branch: gcBranch });
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        case 'scaffold': {
+            const host = normalizeProviderMode(readArg('--host'));
+            if (!host)
+                usage();
+            const targetDir = readArg('--target') || process.cwd();
+            const result = await ensureScaffold({
+                providerMode: host,
+                targetDir,
+                force: hasFlag('--force'),
+            });
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        default:
+            usage();
+    }
+}
+await main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});

package/dist/src/markdown.js

@@ -0,0 +1,81 @@
+export function slugify(value) {
+    const normalized = String(value || '')
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '');
+    return normalized || 'doc';
+}
+export function ensureSummary(summary) {
+    const trimmed = String(summary || '').trim();
+    if (!trimmed) {
+        throw new Error('summary is required for every source-of-truth doc');
+    }
+    return trimmed;
+}
+export function renderDocMarkdown(doc) {
+    const summary = ensureSummary(doc.summary);
+    const body = String(doc.body || '').trim();
+    return [
+        `# ${doc.title.trim()}`,
+        '',
+        '## Summary',
+        '',
+        summary,
+        '',
+        ...(doc.tags && doc.tags.length > 0
+            ? ['## Tags', '', ...doc.tags.map((tag) => `- ${tag}`), '']
+            : []),
+        '## Details',
+        '',
+        body || '(no details yet)',
+        '',
+    ].join('\n');
+}
+export function renderIndexMarkdown(input) {
+    const lines = [
+        '# gc-tree Index',
+        '',
+        `- gc-branch: ${input.branch}`,
+        `- summary: ${input.branchSummary.trim()}`,
+        '',
+    ];
+    if (input.docs.length === 0) {
+        lines.push('- No source docs yet.', '');
+    }
+    else {
+        for (const doc of input.docs.sort((a, b) => a.title.localeCompare(b.title))) {
+            lines.push(`- ${doc.title} -> ${doc.path}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+export function parseIndexEntries(indexContent) {
+    return String(indexContent || '')
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => /^- .+ -> .+$/.test(line) && !line.startsWith('- gc-branch:') && !line.startsWith('- summary:'))
+        .map((line) => {
+        const body = line.slice(2);
+        const [title, path] = body.split('->').map((part) => part.trim());
+        return { title, path };
+    });
+}
+export function extractSummary(markdown) {
+    const match = String(markdown || '').match(/## Summary\s+([\s\S]*?)(?:\n## |$)/);
+    return match?.[1]?.trim() || '';
+}
+export function extractExcerpt(markdown, query) {
+    const content = String(markdown || '').replace(/\s+/g, ' ').trim();
+    if (!content)
+        return '';
+    const normalized = query.toLowerCase();
+    const index = content.toLowerCase().indexOf(normalized);
+    if (index === -1)
+        return content.slice(0, 140);
+    const start = Math.max(0, index - 40);
+    const end = Math.min(content.length, index + normalized.length + 80);
+    return content.slice(start, end).trim();
+}

package/dist/src/onboard.js

@@ -0,0 +1,36 @@
+import { mkdir, readdir, unlink, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { renderDocMarkdown } from './markdown.js';
+import { branchDocsDir, DEFAULT_BRANCH } from './paths.js';
+import { ensureBranchExists, updateBranchMeta, writeIndexFromDocs } from './store.js';
+export async function onboardBranch({ home, input, branch, }) {
+    const targetBranch = branch || input.branch || DEFAULT_BRANCH;
+    await ensureBranchExists(home, targetBranch);
+    await mkdir(branchDocsDir(home, targetBranch), { recursive: true });
+    const existing = await readdir(branchDocsDir(home, targetBranch)).catch(() => []);
+    await Promise.all(existing
+        .filter((file) => file.endsWith('.md'))
+        .map((file) => unlink(join(branchDocsDir(home, targetBranch), file))));
+    const written = [];
+    for (const doc of input.docs) {
+        const relativePath = `${doc.slug ? doc.slug : doc.title}`;
+        const fileName = `${relativePath
+            .trim()
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, '-')
+            .replace(/-+/g, '-')
+            .replace(/^-|-$/g, '') || 'doc'}.md`;
+        const fullPath = join(branchDocsDir(home, targetBranch), fileName);
+        await writeFile(fullPath, renderDocMarkdown(doc), 'utf8');
+        written.push(fullPath);
+    }
+    if (input.branchSummary?.trim()) {
+        await updateBranchMeta(home, targetBranch, { summary: input.branchSummary.trim() });
+    }
+    const index = await writeIndexFromDocs(home, targetBranch);
+    return {
+        gc_branch: targetBranch,
+        docs_written: written,
+        index_path: index.index_path,
+    };
+}

package/dist/src/onboarding-protocol.js

@@ -0,0 +1,38 @@
+export function onboardingProtocolLines() {
+    return [
+        'This is **global context onboarding**, not repo-local onboarding.',
+        'Ask **one question at a time** and keep using the saved workflow language all the way through.',
+        'Wait for the user\'s first answer before you inspect docs, repos, directories, or files on your own.',
+        'Start by asking the user to paste or share organized docs or reference material if they have any; otherwise ask what kind of work they mainly do.',
+        'Do **not** start with a repo scan, a company guess, or a broad hypothesis built from directories like `~/sources`.',
+        'Do **not** ask for a full information dump up front.',
+        'If docs, reference material, or reference paths are provided, read those first, summarize your understanding back, ask whether that summary is correct before continuing, and skip any questions the docs already answered well.',
+        'If no docs are available, continue from the user\'s own description first and ask for the most relevant repo, path, or file only when needed.',
+        'Only inspect docs, repos, directories, or files after the user has pointed you at them or confirmed they matter.',
+        'When you inspect, dig only through the user-provided material and the minimum related files needed for the next question.',
+        'Do **not** scan broad directories or inspect every source file; prefer docs, READMEs, summaries, and a few pointed paths first.',
+        'Then ask whether anything important is still missing or worth adding before you continue into deeper discovery.',
+        'When you do present a hypothesis, offer structured numbered confirmations such as: 1. This is basically correct. 2. Part of it is wrong. I will explain what differs. 3. This is the wrong frame. I will explain what you should inspect or how this gc-branch should be approached.',
+        'If the user picks 2 or 3, ask only for the delta, correction, or better pointer instead of restarting from scratch.',
+        'Do **not** start by asking what one repository does.',
+        'Only ask the user who they are, what kind of person they are in the organization, and what work they usually own or lead after the provided docs or description still leave real gaps.',
+        'Ask next for one core recurring work type only when the provided docs or description still do not make the work types clear, then ask whether there are more work types to capture.',
+        'For each work type, ask how that work shows up day to day.',
+        'Only after the work types are clear should you ask which repositories are involved in each work type.',
+        'For each repository, ask what role it plays in the work, what directories or files matter most, what the actual workflow is, and what hidden conventions, glossary terms, or boundaries matter.',
+        'If a relevant repo, path, or doc is available locally and the user has pointed you to it, inspect it and present a lightweight hypothesis before asking what is correct or wrong about that frame.',
+        'Ask whether there are additional repositories for the current work type before moving on.',
+        'After repository coverage, ask for company/domain glossary terms and acronyms that should become durable context.',
+        'Then ask which verification commands should be treated as defaults for this kind of work.',
+        'Synthesize the interview into durable docs such as a role/profile summary, work types, repository roles, glossary, and verification defaults.',
+    ];
+}
+export function onboardingCompletionLines() {
+    return [
+        'After applying the onboarding docs, explicitly list which durable docs were saved.',
+        'Then summarize what you now understand from the saved docs instead of stopping at the filenames alone.',
+        'Ask whether that final summary matches the user\'s reality, and capture any corrections before you wrap up.',
+        'Ask whether anything else should be saved while the context is still fresh.',
+        'End with remaining risks, blind spots, or details that still need confirmation, then remind the user that future changes belong in `gctree update-global-context`.',
+    ];
+}