@handsupmin/gc-tree 0.5.4 → 0.6.1

package/dist/src/cli.js

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
+import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { stdin, stderr, stdout } from 'node:process';
 import { readAsciiLogo, readAsciiTree } from './ascii.js';
 import { dispatchGcTreeHook } from './hook.js';
 import { onboardBranch } from './onboard.js';
 import { buildProviderLaunchPlan, maybeLaunchProvider, promptLanguageSelection, promptLaunchProviderSelection, promptProviderSelection, } from './provider.js';
-import { DEFAULT_BRANCH, resolveHome } from './paths.js';
-import { branchRepoMapPath, branchScopeStatus, detectCurrentRepoId, promptResolveScopeDecision, readBranchRepoMap, resolveBranchForRepo, setRepoScopeForBranch, } from './repo-map.js';
+import { DEFAULT_BRANCH, branchDir, resolveHome } from './paths.js';
+import { branchRepoMapPath, branchScopeStatus, detectCurrentRepoId, detectRepoRoot, 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';
@@ -109,6 +110,11 @@ async function ensureScaffold({ providerMode, targetDir, force = false, }) {
     }
     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)
@@ -244,6 +250,9 @@ async function main() {
         }
         case 'status': {
             const gcBranch = (await readHead(home)) || DEFAULT_BRANCH;
+            if (!existsSync(branchDir(home, gcBranch))) {
+                throw new Error('gc-tree is not initialized. Run `gctree init` first.');
+            }
             const result = await statusForBranch(home, gcBranch);
             const settings = await readSettings(home);
             const mapping = await readBranchRepoMap(home);
@@ -314,7 +323,7 @@ async function main() {
                 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 targetDir = await resolveTargetDir(readArg('--target'));
             const result = await uninstallGcTree({
                 home,
                 targetDir,
@@ -499,7 +508,7 @@ async function main() {
                 payload,
             });
             if (result) {
-                stdout.write(`${result.hookSpecificOutput.additionalContext}\n`);
+                stdout.write(`${JSON.stringify(result, null, 2)}\n`);
             }
             return;
         }

package/dist/src/integration-files.js

@@ -165,6 +165,6 @@ export function gctreeManagedMarkdownTargets(targetDir) {
 export function gctreeHookJsonTargets(targetDir) {
     return {
         codex: join(targetDir, '.codex', 'hooks.json'),
-        claude: join(targetDir, '.claude', 'settings.json'),
+        claude: join(targetDir, '.claude', 'hooks', 'hooks.json'),
     };
 }

package/dist/src/markdown.js

@@ -70,7 +70,8 @@ export function renderIndexMarkdown(input) {
         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(`- ${doc.label || doc.title}`);
+                lines.push(`  - ${doc.path}`);
             }
             lines.push('');
         }
@@ -107,25 +108,44 @@ export function displayCategory(category) {
 }
 export function parseIndexEntries(indexContent) {
     let currentCategory = 'general';
-    return String(indexContent || '')
-        .split(/\r?\n/)
-        .map((line) => line.trim())
-        .flatMap((line) => {
-        if (!line)
-            return [];
-        const heading = line.match(/^##\s+(.+)$/);
+    let pendingLabel = null;
+    const entries = [];
+    for (const rawLine of String(indexContent || '').split(/\r?\n/)) {
+        const line = rawLine.trimEnd();
+        const trimmed = line.trim();
+        if (!trimmed) {
+            pendingLabel = null;
+            continue;
+        }
+        const heading = trimmed.match(/^##\s+(.+)$/);
         if (heading) {
             currentCategory = normalizeCategory(heading[1] || 'general');
-            return [];
+            pendingLabel = null;
+            continue;
         }
-        if (!/^-\s+.+\s+->\s+.+$/.test(line) || line.startsWith('- gc-branch:') || line.startsWith('- summary:')) {
-            return [];
+        if (trimmed.startsWith('- gc-branch:') || trimmed.startsWith('- summary:') || trimmed === '- No source docs yet.') {
+            pendingLabel = null;
+            continue;
         }
-        const body = line.slice(2);
-        const [label, path] = body.split('->').map((part) => part.trim());
-        const category = deriveCategoryFromPath(path) || currentCategory;
-        return [{ id: docIdFromPath(path), title: label, label, category, path }];
-    });
+        const pathMatch = rawLine.match(/^\s{2,}-\s+(docs\/.+)$/);
+        if (pathMatch && pendingLabel) {
+            const path = pathMatch[1].trim();
+            const category = deriveCategoryFromPath(path) || currentCategory;
+            entries.push({
+                id: docIdFromPath(path),
+                title: pendingLabel,
+                label: pendingLabel,
+                category,
+                path,
+            });
+            continue;
+        }
+        const labelMatch = trimmed.match(/^-\s+(.+)$/);
+        if (labelMatch) {
+            pendingLabel = labelMatch[1].trim();
+        }
+    }
+    return entries;
 }
 export function extractIndexEntries(markdown) {
     const match = String(markdown || '').match(/## Index Entries\s+([\s\S]*?)(?:\n## |$)/);

package/dist/src/onboarding-protocol.js

@@ -18,7 +18,11 @@ export function onboardingProtocolLines() {
         '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.',
+        'Once the user names concrete repositories, do not ask them to explain those repositories from scratch when recoverable local evidence exists.',
+        'For each repository that can be inspected locally, read the strongest available evidence first (README, docs, package metadata, top-level entrypoints, deployment/config files, and a few pointed paths), then present your current understanding back as a short hypothesis.',
+        'After that repository-level hypothesis, ask the user to choose only one structured confirmation: 1. This is mostly correct. 2. Some parts are wrong. Please explain what differs. 3. Most of this is wrong. Please explain the right frame.',
+        'When local evidence already covers the repository role, important paths, workflow, or conventions well enough, skip the open-ended questions and ask only for missing deltas.',
+        'Only ask open-ended repository questions when the needed detail cannot be recovered responsibly from local evidence.',
         '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.',
         '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.',

package/dist/src/paths.js

@@ -1,7 +1,6 @@
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 export const DEFAULT_BRANCH = 'main';
-export const INDEX_WARNING_CHARS = 2000;
 export function resolveHome(explicitHome) {
     return explicitHome || process.env.GCTREE_HOME || join(homedir(), '.gctree');
 }

package/dist/src/scaffold.js

@@ -248,7 +248,7 @@ export async function scaffoldHostIntegration({ host, targetDir, force = false,
     written.push(hookPath);
     // Migrate: clean up gctree entries from old hooks.json location (claude-code only)
     if (!isCodex) {
-        const oldHooksPath = join(targetDir, '.claude', 'hooks', 'hooks.json');
+        const oldHooksPath = join(targetDir, '.claude', 'settings.json');
         await unmergeGcTreeHooksJson(oldHooksPath);
     }
     const targets = files.map((file) => ({

package/dist/src/store.js

@@ -1,7 +1,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, INDEX_WARNING_CHARS, } from './paths.js';
+import { branchDir, branchDocsDir, branchIndexPath, branchMetaPath, branchesRoot, DEFAULT_BRANCH, headPath, } from './paths.js';
 import { extractIndexEntries, renderIndexMarkdown } from './markdown.js';
 async function listDocRelativePaths(dir, prefix = '') {
     const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
@@ -150,9 +150,6 @@ export async function statusForBranch(home, branch) {
     const indexRaw = await readFile(branchIndexPath(home, branch), 'utf8');
     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.`);
-    }
     for (const doc of docs) {
         const raw = await readFile(join(branchDocsDir(home, branch), doc), 'utf8');
         if (!/^## Summary$/m.test(raw)) {

package/package.json

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

package/skills/onboard/SKILL.md

@@ -30,6 +30,10 @@ Use this when a user wants to create global context for a product, company, or w
 - do not start by asking what one repo does
 - ask who the person is and what work they usually own only after the provided docs or description still leave real gaps
 - ask for multiple work types if needed, then multiple repos inside each work type if needed
+- once the user names concrete repositories, do not ask them to explain those repositories from scratch when recoverable local evidence exists
+- for each repository that can be inspected locally, read the strongest available evidence first, summarize your current understanding back, and have the user confirm with 1/2/3
+- when the inspected evidence already covers a repository well enough, ask only for missing deltas instead of re-asking role, paths, and workflow from scratch
+- only ask open-ended repository questions when the needed detail cannot be recovered responsibly from local evidence
 - ask about glossary terms and default verification commands before you finish
 - write compact source docs with a required `## Summary` section near the top
 - prefer an encyclopedia-style context set with many small docs instead of a few broad docs
@@ -61,24 +65,27 @@ Use this when a user wants to create global context for a product, company, or w
 13. Ask 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.
 14. For each work type, ask how it shows up in day-to-day work.
 15. Only after that ask which repositories are involved in that work type, and ask whether there are more repositories for that same work type.
-16. For each relevant repo, ask:
-   - what role it plays
-   - which paths matter most
-   - what the actual workflow is
-   - what hidden conventions, glossary terms, boundaries, or constraints matter
-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. 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. After docs are confirmed correct, ask which repositories discussed during onboarding should be explicitly mapped to this gc-branch. For each confirmed repo, navigate to that directory and run `gctree set-repo-scope --branch <gc-branch> --include`. Skip this step only if the user explicitly says repo mapping is not needed.
-30. Do not finish onboarding while material related repos, workflows, or domain terms remain uninspected when recoverable local evidence is still available.
-31. Only after the related repos, workflows, glossary, default verification commands, and repo-scope mapping are either captured or explicitly skipped should you wrap up, then remind the user that future changes belong in `gctree update-global-context`.
-32. Keep the current gc-branch explicit while gathering context.
+16. Once the user names concrete repositories, do not ask them to explain those repositories from scratch when recoverable local evidence exists.
+17. For each repository that can be inspected locally, read the strongest available evidence first, then present a short hypothesis covering repo role, important paths, workflow, and notable conventions.
+18. After each repository-level hypothesis, ask the user to choose only one:
+   - 1. This is mostly correct.
+   - 2. Some parts are wrong. Please explain what differs.
+   - 3. Most of this is wrong. Please explain the right frame.
+19. When the inspected evidence already covers the repository well enough, ask only for the missing deltas instead of re-asking role, paths, and workflow from scratch.
+20. Only ask open-ended repository questions when the needed detail cannot be recovered responsibly from local evidence.
+21. 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.
+22. Ask for company/domain glossary terms and acronyms that should become durable context.
+23. Ask which verification commands should be treated as defaults for this gc-branch.
+24. 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.
+25. Render `index.md` as a category-grouped dictionary-style table of contents with `label -> path` entries.
+26. Launch the guided onboarding flow with `gctree onboard [--branch <name>]`.
+27. Before you claim onboarding is complete, run `gctree verify-onboarding --branch <current-gc-branch>` and inspect the real gc-tree files.
+28. Do not claim onboarding is complete unless verification returns `status: "complete"`.
+29. After the onboarding docs are written, explicitly list which durable docs were saved.
+30. Summarize what you now understand from the saved docs instead of ending at the filenames alone.
+31. Ask whether that final summary matches the user's reality, and capture any corrections before you wrap up.
+32. Ask whether anything else should be saved while the context is still fresh.
+33. After docs are confirmed correct, ask which repositories discussed during onboarding should be explicitly mapped to this gc-branch. For each confirmed repo, navigate to that directory and run `gctree set-repo-scope --branch <gc-branch> --include`. Skip this step only if the user explicitly says repo mapping is not needed.
+34. Do not finish onboarding while material related repos, workflows, or domain terms remain uninspected when recoverable local evidence is still available.
+35. Only after the related repos, workflows, glossary, default verification commands, and repo-scope mapping are either captured or explicitly skipped should you wrap up, then remind the user that future changes belong in `gctree update-global-context`.
+36. Keep the current gc-branch explicit while gathering context.