@handsupmin/gc-tree 0.4.2 → 0.4.4

package/dist/src/cli.js

@@ -11,6 +11,7 @@ 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';
+import { uninstallGcTree } from './uninstall.js';
 import { verifyOnboarding } from './verify-onboarding.js';
 function readArg(flag) {
     const index = process.argv.indexOf(flag);
@@ -31,6 +32,7 @@ function usage() {
   gctree onboard [--home DIR] [--branch NAME] [--provider <codex|claude-code>] [--target DIR] [--no-launch]
   gctree verify-onboarding [--home DIR] [--branch NAME]
   gctree reset-gc-branch [--home DIR] [--branch NAME] --yes
+  gctree uninstall [--home DIR] [--target DIR] [--host <codex|claude-code|both>] [--keep-home] --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]
@@ -276,6 +278,21 @@ async function main() {
             console.log(JSON.stringify(result, null, 2));
             return;
         }
+        case 'uninstall': {
+            if (!hasFlag('--yes')) {
+                throw new Error('uninstall is destructive. Re-run with --yes to confirm.');
+            }
+            const host = normalizeProviderMode(readArg('--host')) || 'both';
+            const targetDir = readArg('--target') || process.cwd();
+            const result = await uninstallGcTree({
+                home,
+                targetDir,
+                host,
+                keepHome: hasFlag('--keep-home'),
+            });
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
         case 'resolve': {
             const query = readArg('--query');
             if (!query)

package/dist/src/integration-files.js

@@ -0,0 +1,167 @@
+import { access, readFile, rm, writeFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { mkdir } from 'node:fs/promises';
+const MARKERS = {
+    codex: {
+        start: '<!-- gctree:codex:start -->',
+        end: '<!-- gctree:codex:end -->',
+    },
+    claude: {
+        start: '<!-- gctree:claude:start -->',
+        end: '<!-- gctree:claude:end -->',
+    },
+};
+export async function pathExists(target) {
+    try {
+        await access(target, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function injectManagedBlock(existing, content, start, end) {
+    const block = `${start}\n${content.trimEnd()}\n${end}`;
+    const startIndex = existing.indexOf(start);
+    const endIndex = existing.indexOf(end);
+    if (startIndex !== -1 && endIndex !== -1 && endIndex > startIndex) {
+        return `${existing.slice(0, startIndex).trimEnd()}\n\n${block}\n${existing.slice(endIndex + end.length).trimStart()}`.trimEnd() + '\n';
+    }
+    const trimmed = existing.trimEnd();
+    return `${trimmed ? `${trimmed}\n\n` : ''}${block}\n`;
+}
+function removeManagedBlock(existing, start, end) {
+    const startIndex = existing.indexOf(start);
+    const endIndex = existing.indexOf(end);
+    if (startIndex === -1 || endIndex === -1 || endIndex < startIndex)
+        return existing;
+    const before = existing.slice(0, startIndex).trimEnd();
+    const after = existing.slice(endIndex + end.length).trimStart();
+    const merged = [before, after].filter(Boolean).join('\n\n');
+    return merged ? `${merged}\n` : '';
+}
+export async function upsertManagedMarkdownBlock({ filePath, content, marker, }) {
+    const { start, end } = MARKERS[marker];
+    const existing = (await pathExists(filePath)) ? await readFile(filePath, 'utf8') : '';
+    const next = injectManagedBlock(existing, content, start, end);
+    await mkdir(dirname(filePath), { recursive: true });
+    await writeFile(filePath, next, 'utf8');
+    return existing ? 'updated' : 'created';
+}
+export async function removeManagedMarkdownBlock({ filePath, marker, }) {
+    if (!(await pathExists(filePath)))
+        return 'missing';
+    const { start, end } = MARKERS[marker];
+    const existing = await readFile(filePath, 'utf8');
+    const next = removeManagedBlock(existing, start, end);
+    if (!next.trim()) {
+        await rm(filePath, { force: true });
+        return 'deleted';
+    }
+    if (next === existing)
+        return 'missing';
+    await writeFile(filePath, next, 'utf8');
+    return 'removed';
+}
+function buildHookEntry(event) {
+    return {
+        type: 'command',
+        command: `gctree __hook --event ${event}`,
+        metadata: {
+            owner: 'gctree',
+        },
+        ...(event === 'UserPromptSubmit' ? { timeout: 10 } : {}),
+    };
+}
+function ensureObject(value) {
+    return value && typeof value === 'object' ? value : {};
+}
+function isGcTreeHook(entry, event) {
+    const command = String(entry.command || '');
+    const owner = ensureObject(entry.metadata).owner;
+    return owner === 'gctree' || command === `gctree __hook --event ${event}`;
+}
+function mergeHookJson(raw, target) {
+    const parsed = raw ? ensureObject(JSON.parse(raw)) : {};
+    const hooks = ensureObject(parsed.hooks);
+    const sessionEvent = 'SessionStart';
+    const promptEvent = 'UserPromptSubmit';
+    const ensureEventArray = (event) => {
+        const current = Array.isArray(hooks[event]) ? hooks[event] : [];
+        hooks[event] = current;
+        return current;
+    };
+    const upsertGroup = (event, matcher) => {
+        const groups = ensureEventArray(event);
+        let group = groups.find((candidate) => {
+            const hooksArr = Array.isArray(candidate?.hooks) ? candidate.hooks : [];
+            return hooksArr.some((entry) => isGcTreeHook(ensureObject(entry), event));
+        });
+        if (!group) {
+            group = matcher ? { matcher, hooks: [] } : { hooks: [] };
+            groups.push(group);
+        }
+        if (!Array.isArray(group.hooks))
+            group.hooks = [];
+        group.hooks = group.hooks.filter((entry) => !isGcTreeHook(ensureObject(entry), event));
+        group.hooks.push(buildHookEntry(event));
+    };
+    upsertGroup(sessionEvent, target === 'codex' ? 'startup|resume' : '*');
+    upsertGroup(promptEvent, target === 'codex' ? undefined : '*');
+    return `${JSON.stringify({ hooks }, null, 2)}\n`;
+}
+function unmergeHookJson(raw, events) {
+    const parsed = ensureObject(JSON.parse(raw));
+    const hooks = ensureObject(parsed.hooks);
+    for (const event of events) {
+        const groups = Array.isArray(hooks[event]) ? hooks[event] : [];
+        const nextGroups = groups
+            .map((group) => {
+            const hooksArr = Array.isArray(group.hooks) ? group.hooks : [];
+            const nextHooks = hooksArr.filter((entry) => !isGcTreeHook(ensureObject(entry), event));
+            return nextHooks.length > 0 ? { ...group, hooks: nextHooks } : null;
+        })
+            .filter(Boolean);
+        if (nextGroups.length > 0)
+            hooks[event] = nextGroups;
+        else
+            delete hooks[event];
+    }
+    if (Object.keys(hooks).length === 0)
+        return '';
+    return `${JSON.stringify({ hooks }, null, 2)}\n`;
+}
+export async function mergeGcTreeHooksJson({ filePath, target, }) {
+    const existing = (await pathExists(filePath)) ? await readFile(filePath, 'utf8') : null;
+    const next = mergeHookJson(existing, target);
+    await mkdir(dirname(filePath), { recursive: true });
+    await writeFile(filePath, next, 'utf8');
+    return existing ? 'updated' : 'created';
+}
+export async function unmergeGcTreeHooksJson(filePath) {
+    if (!(await pathExists(filePath)))
+        return 'missing';
+    const existing = await readFile(filePath, 'utf8');
+    const next = unmergeHookJson(existing, ['SessionStart', 'UserPromptSubmit']);
+    if (!next.trim()) {
+        await rm(filePath, { force: true });
+        return 'deleted';
+    }
+    if (next === existing)
+        return 'missing';
+    await writeFile(filePath, next, 'utf8');
+    return 'removed';
+}
+export function gctreeManagedMarkdownTargets(targetDir) {
+    return {
+        codex: join(targetDir, 'AGENTS.md'),
+        claude: join(targetDir, 'CLAUDE.md'),
+    };
+}
+export function gctreeHookJsonTargets(targetDir) {
+    return {
+        codex: join(targetDir, '.codex', 'hooks.json'),
+        claude: join(targetDir, '.claude', 'hooks', 'hooks.json'),
+    };
+}

package/dist/src/markdown.js

@@ -45,35 +45,93 @@ export function renderIndexMarkdown(input) {
         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}`);
+        const categoryOrder = ['role', 'repos', 'domain', 'workflows', 'conventions', 'infra', 'verification', 'general'];
+        const grouped = new Map();
+        for (const doc of input.docs) {
+            const category = normalizeCategory(doc.category || deriveCategoryFromPath(doc.path));
+            if (!grouped.has(category))
+                grouped.set(category, []);
+            grouped.get(category).push(doc);
+        }
+        const categories = [...grouped.keys()].sort((a, b) => {
+            const ai = categoryOrder.indexOf(a);
+            const bi = categoryOrder.indexOf(b);
+            if (ai === -1 && bi === -1)
+                return a.localeCompare(b);
+            if (ai === -1)
+                return 1;
+            if (bi === -1)
+                return -1;
+            return ai - bi;
+        });
+        for (const category of categories) {
+            lines.push(`## ${displayCategory(category)}`, '');
+            for (const doc of grouped.get(category).sort((a, b) => (a.label || a.title).localeCompare(b.label || b.title))) {
+                lines.push(`- ${doc.label || doc.title} -> ${doc.path}`);
+            }
+            lines.push('');
         }
-        lines.push('');
     }
     return lines.join('\n');
 }
 export function docIdFromPath(docPath) {
-    const fileName = String(docPath || '')
-        .trim()
-        .split('/')
-        .pop() || '';
-    return fileName.replace(/\.md$/i, '') || 'doc';
+    const normalized = String(docPath || '').trim().replace(/^docs\//, '');
+    return normalized.replace(/\.md$/i, '') || 'doc';
+}
+export function normalizeCategory(value) {
+    return slugify(value || 'general');
+}
+export function deriveCategoryFromPath(docPath) {
+    const normalized = String(docPath || '').trim().replace(/^docs\//, '');
+    const parts = normalized.split('/').filter(Boolean);
+    if (parts.length > 1)
+        return normalizeCategory(parts[0]);
+    return 'general';
+}
+export function displayCategory(category) {
+    const normalized = normalizeCategory(category);
+    const predefined = {
+        role: 'Role',
+        repos: 'Repos',
+        domain: 'Domain',
+        workflows: 'Workflows',
+        conventions: 'Conventions',
+        infra: 'Infra',
+        verification: 'Verification',
+        general: 'General',
+    };
+    return predefined[normalized] || normalized.split('-').map((part) => part[0]?.toUpperCase() + part.slice(1)).join(' ');
 }
 export function parseIndexEntries(indexContent) {
+    let currentCategory = 'general';
     return String(indexContent || '')
         .split(/\r?\n/)
         .map((line) => line.trim())
-        .filter((line) => /^- .+ -> .+$/.test(line) && !line.startsWith('- gc-branch:') && !line.startsWith('- summary:'))
-        .map((line) => {
+        .flatMap((line) => {
+        if (!line)
+            return [];
+        const heading = line.match(/^##\s+(.+)$/);
+        if (heading) {
+            currentCategory = normalizeCategory(heading[1] || 'general');
+            return [];
+        }
+        if (!/^-\s+.+\s+->\s+.+$/.test(line) || line.startsWith('- gc-branch:') || line.startsWith('- summary:')) {
+            return [];
+        }
         const body = line.slice(2);
-        const [title, path] = body.split('->').map((part) => part.trim());
-        return { id: docIdFromPath(path), title, path };
+        const [label, path] = body.split('->').map((part) => part.trim());
+        const category = deriveCategoryFromPath(path) || currentCategory;
+        return [{ id: docIdFromPath(path), title: label, label, category, path }];
     });
 }
 export function extractSummary(markdown) {
     const match = String(markdown || '').match(/## Summary\s+([\s\S]*?)(?:\n## |$)/);
     return match?.[1]?.trim() || '';
 }
+export function extractTitle(markdown) {
+    const match = String(markdown || '').match(/^#\s+(.+)$/m);
+    return match?.[1]?.trim() || '';
+}
 export function extractExcerpt(markdown, query) {
     const content = String(markdown || '').replace(/\s+/g, ' ').trim();
     if (!content)

package/dist/src/onboard.js

@@ -1,26 +1,24 @@
-import { mkdir, readdir, unlink, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { renderDocMarkdown } from './markdown.js';
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { renderDocMarkdown, slugify } 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) : '';
+    return category ? `${category}/${fileBase}.md` : `${fileBase}.md`;
+}
 export async function onboardBranch({ home, input, branch, }) {
     const targetBranch = branch || input.branch || DEFAULT_BRANCH;
     await ensureBranchExists(home, targetBranch);
+    await rm(branchDocsDir(home, targetBranch), { recursive: true, force: true });
     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);
+        const fullPath = join(branchDocsDir(home, targetBranch), docRelativePath(doc));
+        await mkdir(dirname(fullPath), { recursive: true });
         await writeFile(fullPath, renderDocMarkdown(doc), 'utf8');
         written.push(fullPath);
     }

package/dist/src/onboarding-protocol.js

@@ -23,7 +23,11 @@ export function onboardingProtocolLines() {
         '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.',
+        'Synthesize the interview into an encyclopedia-style context set with many small docs instead of a few broad docs.',
+        'Prefer category directories such as `docs/role/`, `docs/repos/`, `docs/domain/`, `docs/workflows/`, `docs/conventions/`, and `docs/infra/` whenever that split fits the material.',
+        'Prefer one concept, one repository, one workflow, or one convention per file when possible.',
+        'Keep each doc summary-first so the top section gives the gist before deeper details.',
+        'Treat `index.md` as a human-readable dictionary-style table of contents grouped by category headings and `label -> path` entries.',
     ];
 }
 export function onboardingCompletionLines() {

package/dist/src/resolve.js

@@ -1,6 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { docIdFromPath, extractExcerpt, extractSummary, parseIndexEntries } from './markdown.js';
+import { deriveCategoryFromPath, docIdFromPath, extractExcerpt, extractSummary, extractTitle, 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([
@@ -49,7 +49,9 @@ async function readBranchDocs(home, branch) {
         const raw = await readFile(fullPath, 'utf8');
         return {
             id: entry.id || docIdFromPath(entry.path),
-            title: entry.title,
+            title: extractTitle(raw) || entry.title,
+            label: entry.label,
+            category: entry.category || deriveCategoryFromPath(entry.path),
             path: entry.path,
             summary: extractSummary(raw),
             content: raw,
@@ -69,6 +71,8 @@ export async function resolveContext({ home, branch, query, }) {
             continue;
         matches.push({
             id: entry.id,
+            label: entry.label,
+            category: entry.category,
             title: entry.title,
             path: entry.path,
             score,
@@ -105,6 +109,8 @@ export async function findRelatedDocs({ home, branch, id, limit = 5, }) {
         return score > 0
             ? {
                 id: doc.id,
+                label: doc.label,
+                category: doc.category,
                 title: doc.title,
                 path: doc.path,
                 score,

package/dist/src/scaffold.js

@@ -1,5 +1,6 @@
 import { access, mkdir, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
+import { gctreeHookJsonTargets, gctreeManagedMarkdownTargets, mergeGcTreeHooksJson, upsertManagedMarkdownBlock, } from './integration-files.js';
 import { onboardingCompletionLines, onboardingProtocolLines } from './onboarding-protocol.js';
 function renderCodexAgentsSnippet() {
     return [
@@ -204,7 +205,7 @@ function renderClaudeUpdateCommand() {
         '',
     ].join('\n');
 }
-function scaffoldFiles(host) {
+export function scaffoldFiles(host) {
     if (host === 'codex') {
         return [
             { path: 'AGENTS.md', content: renderCodexAgentsSnippet() },
@@ -228,10 +229,31 @@ export async function scaffoldHostIntegration({ host, targetDir, force = false,
     const files = scaffoldFiles(host);
     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;
+    await mergeGcTreeHooksJson({
+        filePath: hookPath,
+        target: isCodex ? 'codex' : 'claude-code',
+    });
+    written.push(hookPath);
     const targets = files.map((file) => ({
         ...file,
         fullPath: join(targetDir, 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';
+    });
     for (const target of targets) {
         let exists = false;
         try {

package/dist/src/store.js

@@ -3,6 +3,21 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { branchDir, branchDocsDir, branchIndexPath, branchMetaPath, branchesRoot, DEFAULT_BRANCH, headPath, INDEX_WARNING_CHARS, } from './paths.js';
 import { renderIndexMarkdown } from './markdown.js';
+async function listDocRelativePaths(dir, prefix = '') {
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+    const files = [];
+    for (const entry of entries) {
+        const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+        const fullPath = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await listDocRelativePaths(fullPath, relative)));
+        }
+        else if (entry.isFile() && entry.name.endsWith('.md')) {
+            files.push(relative);
+        }
+    }
+    return files.sort();
+}
 export async function ensureHome(home) {
     await mkdir(branchesRoot(home), { recursive: true });
 }
@@ -93,11 +108,14 @@ export async function checkoutBranch(home, branch, create = false) {
 export async function writeIndexFromDocs(home, branch) {
     const docsDir = branchDocsDir(home, branch);
     await mkdir(docsDir, { recursive: true });
-    const files = (await readdir(docsDir)).filter((file) => file.endsWith('.md')).sort();
+    const files = await listDocRelativePaths(docsDir);
     const docs = await Promise.all(files.map(async (file) => {
         const raw = await readFile(join(docsDir, file), 'utf8');
         const title = raw.match(/^#\s+(.+)$/m)?.[1]?.trim() || file.replace(/\.md$/i, '').replace(/-/g, ' ');
-        return { title, path: `docs/${file}` };
+        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;
+        return { title, label, category, path: `docs/${file}` };
     }));
     const meta = await readBranchMeta(home, branch);
     const index = renderIndexMarkdown({ branch, branchSummary: meta.summary, docs });
@@ -105,7 +123,7 @@ export async function writeIndexFromDocs(home, branch) {
     return { index_path: branchIndexPath(home, branch), doc_count: docs.length };
 }
 export async function isBranchContextEmpty(home, branch) {
-    const docs = (await readdir(branchDocsDir(home, branch)).catch(() => [])).filter((file) => file.endsWith('.md'));
+    const docs = await listDocRelativePaths(branchDocsDir(home, branch));
     return docs.length === 0;
 }
 export async function resetBranchContext(home, branch) {
@@ -122,7 +140,7 @@ export async function resetBranchContext(home, branch) {
 }
 export async function statusForBranch(home, branch) {
     const indexRaw = await readFile(branchIndexPath(home, branch), 'utf8');
-    const docs = (await readdir(branchDocsDir(home, branch)).catch(() => [])).filter((file) => file.endsWith('.md'));
+    const docs = await listDocRelativePaths(branchDocsDir(home, branch));
     const warnings = [];
     if (indexRaw.length > INDEX_WARNING_CHARS) {
         warnings.push(`index.md is ${indexRaw.length} chars; keep it closer to an index than a knowledge dump.`);

package/dist/src/uninstall.js

@@ -0,0 +1,82 @@
+import { readdir, rm } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { gctreeHookJsonTargets, gctreeManagedMarkdownTargets, pathExists, removeManagedMarkdownBlock, unmergeGcTreeHooksJson, } from './integration-files.js';
+import { scaffoldFiles } from './scaffold.js';
+async function pathHasEntries(path) {
+    const entries = await readdir(path).catch(() => []);
+    return entries.length > 0;
+}
+async function pruneEmptyParents(targetPath, stopDir) {
+    let current = dirname(targetPath);
+    while (current.startsWith(stopDir) && current !== stopDir) {
+        if (await pathHasEntries(current))
+            return;
+        await rm(current, { recursive: true, force: true });
+        current = dirname(current);
+    }
+}
+function hostsFor(mode) {
+    return mode === 'both' ? ['claude-code', 'codex'] : [mode];
+}
+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',
+            });
+            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;
+    if (!keepHome && (await pathExists(home))) {
+        await rm(home, { recursive: true, force: true });
+        homeRemoved = true;
+        removed.push(home);
+    }
+    return {
+        target_dir: targetDir,
+        home,
+        host,
+        home_removed: homeRemoved,
+        removed,
+    };
+}

package/dist/src/update.js

@@ -1,16 +1,23 @@
 import { mkdir, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { renderDocMarkdown, slugify } 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) : '';
+    return category ? `${category}/${fileBase}.md` : `${fileBase}.md`;
+}
 export async function updateBranchContext({ home, input, branch, }) {
     const targetBranch = branch || input.branch || DEFAULT_BRANCH;
     await ensureBranchExists(home, targetBranch);
     await mkdir(branchDocsDir(home, targetBranch), { recursive: true });
     const written = [];
     for (const doc of input.docs) {
-        const fileName = `${slugify(doc.slug || doc.title)}.md`;
-        const fullPath = join(branchDocsDir(home, targetBranch), fileName);
+        const fullPath = join(branchDocsDir(home, targetBranch), docRelativePath(doc));
+        await mkdir(dirname(fullPath), { recursive: true });
         await writeFile(fullPath, renderDocMarkdown(doc), 'utf8');
         written.push(fullPath);
     }

package/package.json

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

package/skills/onboard/SKILL.md

@@ -32,7 +32,10 @@ Use this when a user wants to create global context for a product, company, or w
 - ask for multiple work types if needed, then multiple repos inside each work type if needed
 - ask about glossary terms and default verification commands before you finish
 - write compact source docs with a required `## Summary` section near the top
-- keep `index.md` as an index only
+- prefer an encyclopedia-style context set with many small docs instead of a few broad docs
+- prefer category directories like `docs/role/`, `docs/repos/`, `docs/domain/`, `docs/workflows/`, `docs/conventions/`, and `docs/infra/`
+- prefer one concept, one repository, one workflow, or one convention per file when possible
+- keep `index.md` as a human-readable dictionary-style TOC grouped by category headings and `label -> path` entries
 - use onboarding only for an empty gc-branch
 
 ## Procedure
@@ -63,13 +66,15 @@ Use this when a user wants to create global context for a product, company, or w
 17. After the user's first answer, proactively inspect relevant local repos, docs, paths, and workflows whenever the connection is strong enough to test your current frame.
 18. Ask for company/domain glossary terms and acronyms that should become durable context.
 19. Ask which verification commands should be treated as defaults for this gc-branch.
-20. Launch the guided onboarding flow with `gctree onboard [--branch <name>]`.
-21. Before you claim onboarding is complete, run `gctree verify-onboarding --branch <current-gc-branch>` and inspect the real gc-tree files.
-22. Do not claim onboarding is complete unless verification returns `status: "complete"`.
-23. After the onboarding docs are written, explicitly list which durable docs were saved.
-24. Summarize what you now understand from the saved docs instead of ending at the filenames alone.
-25. Ask whether that final summary matches the user's reality, and capture any corrections before you wrap up.
-26. Ask whether anything else should be saved while the context is still fresh.
-27. Do not finish onboarding while material related repos, workflows, or domain terms remain uninspected when recoverable local evidence is still available.
-28. Only after the related repos, workflows, glossary, and default verification commands are either captured or explicitly unavailable should you wrap up, then remind the user that future changes belong in `gctree update-global-context`.
-29. Keep the current gc-branch explicit while gathering context.
+20. Structure the durable docs as a small encyclopedia: split by category directory, keep one concept/repo/workflow/convention per file when possible, and keep a short `## Summary` at the top of each doc.
+21. Render `index.md` as a category-grouped dictionary-style table of contents with `label -> path` entries.
+22. Launch the guided onboarding flow with `gctree onboard [--branch <name>]`.
+23. Before you claim onboarding is complete, run `gctree verify-onboarding --branch <current-gc-branch>` and inspect the real gc-tree files.
+24. Do not claim onboarding is complete unless verification returns `status: "complete"`.
+25. After the onboarding docs are written, explicitly list which durable docs were saved.
+26. Summarize what you now understand from the saved docs instead of ending at the filenames alone.
+27. Ask whether that final summary matches the user's reality, and capture any corrections before you wrap up.
+28. Ask whether anything else should be saved while the context is still fresh.
+29. Do not finish onboarding while material related repos, workflows, or domain terms remain uninspected when recoverable local evidence is still available.
+30. Only after the related repos, workflows, glossary, and default verification commands are either captured or explicitly unavailable should you wrap up, then remind the user that future changes belong in `gctree update-global-context`.
+31. Keep the current gc-branch explicit while gathering context.