@handsupmin/gc-tree 1.1.1 → 1.1.3

package/dist/src/integration-files.js

@@ -65,14 +65,15 @@ export async function removeManagedMarkdownBlock({ filePath, marker, }) {
     await writeFile(filePath, next, 'utf8');
     return 'removed';
 }
-function buildHookEntry(event) {
+function buildHookEntry(event, target) {
     return {
         type: 'command',
         command: `gctree __hook --event ${event}`,
         metadata: {
             owner: 'gctree',
+            managed_by: '@handsupmin/gc-tree',
         },
-        ...(event === 'UserPromptSubmit' ? { timeout: 10 } : {}),
+        ...(target === 'claude-code' || event === 'UserPromptSubmit' ? { timeout: 10 } : {}),
     };
 }
 function ensureObject(value) {
@@ -95,21 +96,29 @@ function mergeHookJson(raw, target) {
     };
     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));
+        hooks[event] = groups
+            .map((candidate) => {
+            const group = ensureObject(candidate);
+            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);
+        let group = hooks[event].find((candidate) => {
+            if (matcher === undefined)
+                return candidate.matcher === undefined;
+            return String(candidate.matcher ?? '') === matcher;
         });
         if (!group) {
-            group = matcher ? { matcher, hooks: [] } : { hooks: [] };
-            groups.push(group);
+            group = matcher !== undefined ? { matcher, hooks: [] } : { hooks: [] };
+            hooks[event].push(group);
         }
         if (!Array.isArray(group.hooks))
             group.hooks = [];
-        group.hooks = group.hooks.filter((entry) => !isGcTreeHook(ensureObject(entry), event));
-        group.hooks.push(buildHookEntry(event));
+        group.hooks.push(buildHookEntry(event, target));
     };
-    upsertGroup(sessionEvent, target === 'codex' ? 'startup|resume' : '*');
-    upsertGroup(promptEvent, target === 'codex' ? undefined : '*');
+    upsertGroup(sessionEvent, target === 'codex' ? 'startup|resume' : '');
+    upsertGroup(promptEvent, target === 'codex' ? undefined : '');
     return `${JSON.stringify({ ...parsed, hooks }, null, 2)}\n`;
 }
 function unmergeHookJson(raw, events) {
@@ -166,7 +175,7 @@ export function gctreeManagedMarkdownTargets(targetDir) {
 export function gctreeHookJsonTargets(targetDir) {
     return {
         codex: join(targetDir, '.codex', 'hooks.json'),
-        claude: join(targetDir, '.claude', 'hooks', 'hooks.json'),
+        claude: join(targetDir, '.claude', 'settings.json'),
     };
 }
 export function gctreeGlobalRoot(host) {
@@ -177,5 +186,11 @@ export function gctreeGlobalRoot(host) {
 }
 export function gctreeGlobalHookJsonTarget(host) {
     const root = gctreeGlobalRoot(host);
-    return host === 'codex' ? join(root, 'hooks.json') : join(root, 'hooks', 'hooks.json');
+    return host === 'codex' ? join(root, 'hooks.json') : join(root, 'settings.json');
+}
+export function gctreeLegacyClaudeHooksJsonTarget(targetDir) {
+    return join(targetDir, 'hooks', 'hooks.json');
+}
+export function gctreeLegacyLocalClaudeHooksJsonTarget(targetDir) {
+    return join(targetDir, '.claude', 'hooks', 'hooks.json');
 }

package/dist/src/scaffold.js

@@ -1,6 +1,6 @@
 import { access, mkdir, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
-import { gctreeGlobalHookJsonTarget, gctreeGlobalRoot, gctreeHookJsonTargets, gctreeManagedMarkdownTargets, mergeGcTreeHooksJson, unmergeGcTreeHooksJson, upsertManagedMarkdownBlock, } from './integration-files.js';
+import { gctreeGlobalHookJsonTarget, gctreeGlobalRoot, gctreeHookJsonTargets, gctreeLegacyClaudeHooksJsonTarget, gctreeLegacyLocalClaudeHooksJsonTarget, gctreeManagedMarkdownTargets, mergeGcTreeHooksJson, unmergeGcTreeHooksJson, upsertManagedMarkdownBlock, } from './integration-files.js';
 import { onboardingCompletionLines, onboardingProtocolLines } from './onboarding-protocol.js';
 function renderCodexAgentsSnippet() {
     return [
@@ -107,25 +107,45 @@ function renderCodexOnboardSkill() {
 function renderUpdateProtocol() {
     return [
         '1. Run `gctree status` and state the active gc-branch.',
-        '2. Understand what changed — read the user\'s request, inspect relevant code or docs if needed, and determine the right content to capture.',
-        '3. Decide category and path automatically based on content — never ask the user about scope or placement:',
+        '2. Find the target doc before writing. Use `gctree resolve --query "<new fact or term>"`; if a match is incomplete, read the full doc with `gctree show-doc --id "<id>"`. For an existing doc, preserve useful existing details and index entries unless the user explicitly wants them removed.',
+        '3. Decide category and slug automatically based on content — never ask the user about scope or placement:',
         '   - `docs/workflows/<name>.md` — cross-repo action sequences, step-by-step procedures',
         '   - `docs/conventions/<repo>.md` — code patterns, naming, validation, DTO/service conventions for a repo',
         '   - `docs/repos/<repo>.md` — repo role, key paths, cross-repo dependencies',
         '   - `docs/domain/<concept>.md` — domain terms, acronyms, business logic',
         '   - `docs/infra/<topic>.md` — infra, deployment, environment config',
         '   - `docs/role/<name>.md` — team member roles, responsibilities',
-        '4. Write a `## Summary` that is actionable: actual patterns/commands/constraints a developer needs — not a sentence about what the doc covers.',
-        '5. Include a `## Index Entries` section in each doc\'s content with many keywords: aliases, related terms, command names, field names, workflow names, acronyms. More entries = more chances of being found by `gctree resolve`. Fewer than 5 entries almost always means more are needed.',
-        '5a. **Bilingual index entries**: when the workflow language is not English, every doc\'s `## Index Entries` MUST contain BOTH the workflow language AND English forms for every technical term, repo name, workflow name, and concept. gc-tree retrieval is token-overlap based and cannot translate at query time, so a Korean-language doc that omits English aliases will silently miss any English query (and vice versa). Acronyms (JWT, EMPI, VCF) stay in original form in both. Body and `## Summary` stay in the workflow language; bilingual coverage lives in the index.',
-        '6. Create a temporary JSON file with the updated `docs[]` and run `gctree __apply-update --input <temp-file>`.',
-        '7. Run `gctree verify-onboarding --branch <gc-branch>` and inspect the output:',
+        '4. In the update JSON, `slug` is the path without `docs/` and without `.md`. Example: existing file `docs/conventions/mvldev-assignment-backend-smson.md` must use `slug: "conventions/mvldev-assignment-backend-smson"`.',
+        '5. Use exactly this JSON schema. Unknown fields are rejected; do not use `id`, `path`, or `content`.',
+        '```json',
+        '{',
+        '  "branch": "<gc-branch>",',
+        '  "docs": [',
+        '    {',
+        '      "title": "conventions: example repo",',
+        '      "slug": "conventions/example-repo",',
+        '      "category": "conventions",',
+        '      "summary": "Actionable one-paragraph summary with patterns, commands, and constraints.",',
+        '      "body": "## Patterns\\n\\n- Details body only. Do not include # title, ## Summary, or ## Index Entries here.",',
+        '      "indexLabel": "example repo conventions",',
+        '      "indexEntries": ["example repo", "ExampleRepo", "주요 한국어 검색어", "command names", "field names"]',
+        '    }',
+        '  ]',
+        '}',
+        '```',
+        '6. Write an actionable `summary`: actual patterns/commands/constraints a developer needs — not a sentence about what the doc covers.',
+        '7. Put search terms in `indexEntries`, not inside `body`. Include aliases, related terms, command names, field names, workflow names, acronyms, and the exact phrases users are likely to ask. Fewer than 5 entries almost always means more are needed.',
+        '7a. **Bilingual index entries**: when the workflow language is not English, `indexEntries` MUST contain BOTH the workflow language AND English forms for every technical term, repo name, workflow name, and concept. gc-tree retrieval is token-overlap based and cannot translate at query time. Acronyms (JWT, EMPI, VCF) stay in original form in both. Body and summary stay in the workflow language; bilingual coverage lives in the index.',
+        '8. Create a temporary JSON file with the updated `docs[]` and run `gctree __apply-update --input <temp-file>`.',
+        '9. Run `gctree verify-onboarding --branch <gc-branch>` and inspect the output:',
         '   - Check that every updated doc appears in the verified doc list.',
         '   - Check that index entries for the new content exist and are searchable (not just generic titles).',
         '   - Check that no doc has `category: "general"` — reassign to correct category if so.',
         '   - Check that important concepts from the update are present as index labels — if missing, re-apply with added index entries.',
         '   - Self-heal any issues without asking the user: fix category, add index entries, re-run `gctree __apply-update`, re-verify.',
-        '8. Show the user which docs were updated and confirm the index now covers the new content.',
+        '10. Run `gctree resolve --query "<new keyword>"` and `gctree show-doc --id "<slug>"` for at least one new keyword/doc to prove retrieval and details are correct.',
+        '11. If you intended to update an existing doc and `doc_count` increased unexpectedly, do not report success. Inspect the duplicate, remove the accidental doc, then re-apply with the correct `slug`.',
+        '12. Show the user which docs were updated and confirm the index now covers the new content.',
     ];
 }
 function renderCodexUpdateSkill() {
@@ -181,11 +201,15 @@ function renderClaudeHooksJson() {
         hooks: {
             SessionStart: [
                 {
-                    matcher: '*',
+                    matcher: '',
                     hooks: [
                         {
                             type: 'command',
                             command: 'gctree __hook --event SessionStart',
+                            metadata: {
+                                owner: 'gctree',
+                                managed_by: '@handsupmin/gc-tree',
+                            },
                             timeout: 10,
                         },
                     ],
@@ -193,11 +217,15 @@ function renderClaudeHooksJson() {
             ],
             UserPromptSubmit: [
                 {
-                    matcher: '*',
+                    matcher: '',
                     hooks: [
                         {
                             type: 'command',
                             command: 'gctree __hook --event UserPromptSubmit',
+                            metadata: {
+                                owner: 'gctree',
+                                managed_by: '@handsupmin/gc-tree',
+                            },
                             timeout: 10,
                         },
                     ],
@@ -272,7 +300,7 @@ export function scaffoldFiles(host, scope = 'local') {
     }
     if (scope === 'global') {
         return [
-            { path: 'hooks/hooks.json', content: renderClaudeHooksJson() },
+            { path: 'settings.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() },
@@ -281,7 +309,7 @@ export function scaffoldFiles(host, scope = 'local') {
     }
     return [
         { path: 'CLAUDE.md', content: renderClaudeSnippet() },
-        { path: '.claude/hooks/hooks.json', content: renderClaudeHooksJson() },
+        { path: '.claude/settings.json', content: renderClaudeHooksJson() },
         { path: '.claude/hooks/gctree-session-start.md', content: renderClaudeSessionStartHook() },
         { path: '.claude/commands/gc-resolve-context.md', content: renderClaudeResolveCommand() },
         { path: '.claude/commands/gc-onboard.md', content: renderClaudeOnboardCommand() },
@@ -309,15 +337,21 @@ export async function scaffoldHostIntegration({ host, targetDir, force = false,
         written.push(managedMarkdownPath);
         hookPath = isCodex ? hookTargets.codex : hookTargets.claude;
         if (!isCodex) {
-            const oldHooksPath = join(resolvedTargetDir, '.claude', 'settings.json');
-            await unmergeGcTreeHooksJson(oldHooksPath);
+            const legacyHooksPath = gctreeLegacyLocalClaudeHooksJsonTarget(resolvedTargetDir);
+            const legacyStatus = await unmergeGcTreeHooksJson(legacyHooksPath);
+            if (legacyStatus !== 'missing') {
+                written.push(legacyHooksPath);
+            }
         }
     }
     else {
         hookPath = gctreeGlobalHookJsonTarget(host);
         if (!isCodex) {
-            const oldHooksPath = join(resolvedTargetDir, 'settings.json');
-            await unmergeGcTreeHooksJson(oldHooksPath);
+            const legacyHooksPath = gctreeLegacyClaudeHooksJsonTarget(resolvedTargetDir);
+            const legacyStatus = await unmergeGcTreeHooksJson(legacyHooksPath);
+            if (legacyStatus !== 'missing') {
+                written.push(legacyHooksPath);
+            }
         }
     }
     if (scope === 'local') {

package/dist/src/uninstall.js

@@ -1,6 +1,6 @@
 import { readdir, rm } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
-import { gctreeGlobalHookJsonTarget, gctreeGlobalRoot, gctreeHookJsonTargets, gctreeManagedMarkdownTargets, pathExists, removeManagedMarkdownBlock, unmergeGcTreeHooksJson, } from './integration-files.js';
+import { gctreeGlobalHookJsonTarget, gctreeGlobalRoot, gctreeHookJsonTargets, gctreeLegacyClaudeHooksJsonTarget, gctreeLegacyLocalClaudeHooksJsonTarget, gctreeManagedMarkdownTargets, pathExists, removeManagedMarkdownBlock, unmergeGcTreeHooksJson, } from './integration-files.js';
 import { scaffoldFiles } from './scaffold.js';
 async function pathHasEntries(path) {
     const entries = await readdir(path).catch(() => []);
@@ -26,6 +26,14 @@ async function uninstallHostScaffold({ host, scope, targetDir, removed, }) {
     const hookPath = scope === 'local'
         ? (isCodex ? gctreeHookJsonTargets(targetDir).codex : gctreeHookJsonTargets(targetDir).claude)
         : gctreeGlobalHookJsonTarget(host);
+    const hookPaths = isCodex
+        ? [hookPath]
+        : [
+            hookPath,
+            scope === 'local'
+                ? gctreeLegacyLocalClaudeHooksJsonTarget(targetDir)
+                : gctreeLegacyClaudeHooksJsonTarget(targetDir),
+        ];
     if (managedMarkdownPath) {
         const markdownStatus = await removeManagedMarkdownBlock({
             filePath: managedMarkdownPath,
@@ -36,14 +44,16 @@ async function uninstallHostScaffold({ host, scope, targetDir, removed, }) {
             await pruneEmptyParents(managedMarkdownPath, targetDir);
         }
     }
-    const hookStatus = await unmergeGcTreeHooksJson(hookPath);
-    if (hookStatus !== 'missing') {
-        removed.push(hookPath);
-        await pruneEmptyParents(hookPath, targetDir);
+    for (const candidate of [...new Set(hookPaths)]) {
+        const hookStatus = await unmergeGcTreeHooksJson(candidate);
+        if (hookStatus !== 'missing') {
+            removed.push(candidate);
+            await pruneEmptyParents(candidate, targetDir);
+        }
     }
     const extraTargets = scaffoldFiles(host, scope)
         .map((file) => join(targetDir, file.path))
-        .filter((path) => path !== hookPath && path !== managedMarkdownPath);
+        .filter((path) => !hookPaths.includes(path) && path !== managedMarkdownPath);
     for (const target of [...new Set(extraTargets)]) {
         if (!(await pathExists(target)))
             continue;

package/dist/src/update.js

@@ -4,6 +4,14 @@ import { dirname, join } from 'node:path';
 import { renderDocMarkdown, slugify } from './markdown.js';
 import { branchDocsDir, DEFAULT_BRANCH, settingsPath } from './paths.js';
 import { ensureBranchExists, updateBranchMeta, writeIndexFromDocs } from './store.js';
+const UPDATE_ROOT_KEYS = new Set(['branch', 'branchSummary', 'docs']);
+const UPDATE_DOC_KEYS = new Set(['title', 'slug', 'summary', 'body', 'tags', 'category', 'indexLabel', 'indexEntries']);
+const VALID_UPDATE_CATEGORIES = new Set(['role', 'repos', 'domain', 'workflows', 'conventions', 'infra', 'verification']);
+const LEGACY_DOC_FIELD_HINTS = {
+    id: 'use `slug` instead, without `docs/` or `.md`',
+    path: 'use `slug` instead, without `docs/` or `.md`',
+    content: 'use `body` instead, and put search terms in `indexEntries`',
+};
 function docRelativePath(doc) {
     if (doc.slug?.includes('/'))
         return `${doc.slug.replace(/\.md$/i, '')}.md`;
@@ -11,7 +19,118 @@ function docRelativePath(doc) {
     const category = doc.category ? slugify(doc.category) : '';
     return category ? `${category}/${fileBase}.md` : `${fileBase}.md`;
 }
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function unknownKeys(record, allowed) {
+    return Object.keys(record).filter((key) => !allowed.has(key));
+}
+function requireNonEmptyString(record, key, subject) {
+    const value = record[key];
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new Error(`Invalid gctree update input: ${subject}.${key} must be a non-empty string.`);
+    }
+    return value.trim();
+}
+function validateOptionalString(record, key, subject) {
+    const value = record[key];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new Error(`Invalid gctree update input: ${subject}.${key} must be a non-empty string when provided.`);
+    }
+    return value.trim();
+}
+function validateOptionalStringArray(record, key, subject) {
+    const value = record[key];
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string')) {
+        throw new Error(`Invalid gctree update input: ${subject}.${key} must be an array of strings when provided.`);
+    }
+    const entries = value.map((entry) => entry.trim()).filter(Boolean);
+    if (entries.length === 0) {
+        throw new Error(`Invalid gctree update input: ${subject}.${key} must contain at least one non-empty string when provided.`);
+    }
+    return entries;
+}
+function validateUpdateSlug(slug, subject) {
+    if (slug.startsWith('docs/')) {
+        throw new Error(`Invalid gctree update input: ${subject}.slug must omit the docs/ prefix. Example: use "conventions/example" instead of "docs/conventions/example.md".`);
+    }
+    if (slug.endsWith('.md')) {
+        throw new Error(`Invalid gctree update input: ${subject}.slug must omit the .md suffix. Example: use "conventions/example" instead of "conventions/example.md".`);
+    }
+    if (slug.startsWith('/') || slug.includes('\\') || slug.split('/').includes('..')) {
+        throw new Error(`Invalid gctree update input: ${subject}.slug must be a relative doc slug without absolute paths, backslashes, or "..".`);
+    }
+    if (slug.includes('/')) {
+        const category = slug.split('/')[0];
+        if (!VALID_UPDATE_CATEGORIES.has(category)) {
+            throw new Error(`Invalid gctree update input: ${subject}.slug category must be one of ${[...VALID_UPDATE_CATEGORIES].join(', ')}.`);
+        }
+    }
+}
+function validateUpdateBody(body, subject) {
+    if (/^\s*#\s+/.test(body)) {
+        throw new Error(`Invalid gctree update input: ${subject}.body must not include the top-level markdown title; use the title field.`);
+    }
+    if (/^## Summary\b/m.test(body)) {
+        throw new Error(`Invalid gctree update input: ${subject}.body must not include ## Summary; use the summary field.`);
+    }
+    if (/^## Index Entries\b/m.test(body)) {
+        throw new Error(`Invalid gctree update input: ${subject}.body must not include ## Index Entries; use the indexEntries array.`);
+    }
+}
+function validateContextUpdateInput(input) {
+    if (!isRecord(input)) {
+        throw new Error('Invalid gctree update input: root must be an object with docs[].');
+    }
+    const extraRootKeys = unknownKeys(input, UPDATE_ROOT_KEYS);
+    if (extraRootKeys.length > 0) {
+        throw new Error(`Invalid gctree update input: unsupported root field(s): ${extraRootKeys.join(', ')}.`);
+    }
+    validateOptionalString(input, 'branch', 'input');
+    validateOptionalString(input, 'branchSummary', 'input');
+    if (!Array.isArray(input.docs) || input.docs.length === 0) {
+        throw new Error('Invalid gctree update input: docs must be a non-empty array.');
+    }
+    input.docs.forEach((doc, index) => {
+        const subject = `docs[${index}]`;
+        if (!isRecord(doc)) {
+            throw new Error(`Invalid gctree update input: ${subject} must be an object.`);
+        }
+        const extraDocKeys = unknownKeys(doc, UPDATE_DOC_KEYS);
+        if (extraDocKeys.length > 0) {
+            const hints = extraDocKeys
+                .map((key) => LEGACY_DOC_FIELD_HINTS[key])
+                .filter((hint) => Boolean(hint));
+            const suffix = hints.length > 0 ? ` ${[...new Set(hints)].join('; ')}.` : '';
+            throw new Error(`Invalid gctree update input: ${subject} has unsupported field(s): ${extraDocKeys.join(', ')}.${suffix}`);
+        }
+        requireNonEmptyString(doc, 'title', subject);
+        const slug = requireNonEmptyString(doc, 'slug', subject);
+        requireNonEmptyString(doc, 'summary', subject);
+        const body = requireNonEmptyString(doc, 'body', subject);
+        const category = validateOptionalString(doc, 'category', subject);
+        validateOptionalString(doc, 'indexLabel', subject);
+        validateOptionalStringArray(doc, 'tags', subject);
+        const indexEntries = validateOptionalStringArray(doc, 'indexEntries', subject);
+        if (!indexEntries) {
+            throw new Error(`Invalid gctree update input: ${subject}.indexEntries must be a non-empty array of search terms.`);
+        }
+        validateUpdateSlug(slug, subject);
+        validateUpdateBody(body, subject);
+        if (category && !VALID_UPDATE_CATEGORIES.has(category)) {
+            throw new Error(`Invalid gctree update input: ${subject}.category must be one of ${[...VALID_UPDATE_CATEGORIES].join(', ')}.`);
+        }
+        if (category && slug.includes('/') && slug.split('/')[0] !== category) {
+            throw new Error(`Invalid gctree update input: ${subject}.category must match the first segment of slug "${slug}".`);
+        }
+    });
+}
 export async function updateBranchContext({ home, input, branch, }) {
+    validateContextUpdateInput(input);
     const targetBranch = branch || input.branch || DEFAULT_BRANCH;
     await ensureBranchExists(home, targetBranch);
     await mkdir(branchDocsDir(home, targetBranch), { recursive: true });

package/docs/usage.es.md

@@ -181,7 +181,7 @@ AGENTS.md                                  ← fragmento de gctree añadido a la
 **Archivos globales de Claude Code (`gctree init`):**
 
 ```
-~/.claude/hooks/hooks.json                         ← hooks de auto-resolve para SessionStart/UserPromptSubmit
+~/.claude/settings.json                            ← bloque de 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
@@ -190,9 +190,10 @@ AGENTS.md                                  ← fragmento de gctree añadido a la
 
 **Archivos de override local para `gctree scaffold --host claude-code`:**
 
+Los hooks de Claude Code permanecen en el `~/.claude/settings.json` global; el scaffold local no escribe un archivo de hooks duplicado.
+
 ```
 CLAUDE.md                                        ← fragmento de gctree añadido
-.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

package/docs/usage.ja.md

@@ -181,7 +181,7 @@ AGENTS.md                                  ← gctree のスニペットがエ
 **Claude Code のグローバルファイル（`gctree init`）:**
 
 ```
-~/.claude/hooks/hooks.json                         ← SessionStart / UserPromptSubmit の自動 resolve フック
+~/.claude/settings.json                            ← SessionStart / UserPromptSubmit の自動 resolve フックブロック
 ~/.claude/hooks/gctree-session-start.md            ← セッション開始のフォールバックメモ
 ~/.claude/commands/gc-resolve-context.md           ← resolve スラッシュコマンド
 ~/.claude/commands/gc-onboard.md                   ← onboard スラッシュコマンド
@@ -190,9 +190,10 @@ AGENTS.md                                  ← gctree のスニペットがエ
 
 **`gctree scaffold --host claude-code` のローカル override ファイル:**
 
+Claude Code のフックはグローバルの `~/.claude/settings.json` に残ります。ローカル scaffold は重複するフックファイルを書きません。
+
 ```
 CLAUDE.md                                        ← gctree のスニペットが追記される
-.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 スラッシュコマンド

package/docs/usage.ko.md

@@ -181,7 +181,7 @@ AGENTS.md                                  ← 에이전트 지시사항에 gctr
 **Claude Code 전역 파일 (`gctree init`):**
 
 ```
-~/.claude/hooks/hooks.json                         ← SessionStart/UserPromptSubmit 자동 resolve 훅
+~/.claude/settings.json                            ← SessionStart/UserPromptSubmit 자동 resolve 훅 블록
 ~/.claude/hooks/gctree-session-start.md            ← 세션 시작 fallback 메모
 ~/.claude/commands/gc-resolve-context.md           ← resolve 슬래시 명령
 ~/.claude/commands/gc-onboard.md                   ← onboard 슬래시 명령
@@ -190,9 +190,10 @@ AGENTS.md                                  ← 에이전트 지시사항에 gctr
 
 **`gctree scaffold --host claude-code` 로컬 override 파일:**
 
+Claude Code 훅은 전역 `~/.claude/settings.json`에 유지됩니다. 로컬 scaffold는 중복 훅 파일을 쓰지 않습니다.
+
 ```
 CLAUDE.md                                        ← gctree 스니펫 추가
-.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 슬래시 명령

package/docs/usage.md

@@ -181,7 +181,7 @@ AGENTS.md                                  ← gctree snippet appended to agent
 **Global files for Claude Code (`gctree init`):**
 
 ```
-~/.claude/hooks/hooks.json                         ← SessionStart/UserPromptSubmit auto-resolve hooks
+~/.claude/settings.json                            ← SessionStart/UserPromptSubmit auto-resolve hooks block
 ~/.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
@@ -190,9 +190,10 @@ AGENTS.md                                  ← gctree snippet appended to agent
 
 **Local override files for `gctree scaffold --host claude-code`:**
 
+Claude Code hooks remain in the global `~/.claude/settings.json`; local scaffolding does not write a duplicate hook file.
+
 ```
 CLAUDE.md                                        ← gctree snippet appended
-.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

package/docs/usage.zh.md

@@ -181,7 +181,7 @@ AGENTS.md                                  ← gctree 代码片段追加到 agen
 **Claude Code 全局文件（`gctree init`）：**
 
 ```
-~/.claude/hooks/hooks.json                         ← SessionStart / UserPromptSubmit 自动 resolve hook
+~/.claude/settings.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 斜杠命令
@@ -190,9 +190,10 @@ AGENTS.md                                  ← gctree 代码片段追加到 agen
 
 **`gctree scaffold --host claude-code` 的本地 override 文件：**
 
+Claude Code hook 保留在全局 `~/.claude/settings.json` 中；本地 scaffold 不写入重复的 hook 文件。
+
 ```
 CLAUDE.md                                        ← gctree 代码片段追加
-.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 斜杠命令

package/package.json

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

package/skills/update-global-context/SKILL.md

@@ -18,4 +18,34 @@ Use guided updates for durable changes and reserve onboarding for empty gc-branc
    - `gctree update-global-context`
    - `gctree update-gc`
    - `gctree ugc`
-4. Keep the current gc-branch explicit throughout the conversation.
+4. Before writing update JSON, find the target doc with `gctree resolve --query "<new fact or term>"`. If the summary is insufficient, read the full doc with `gctree show-doc --id "<id>"`.
+5. For an existing doc, preserve useful existing Details and Index Entries unless the user explicitly wants them removed.
+6. Use `slug` as the durable path without `docs/` and without `.md`. Example: `docs/conventions/mvldev-assignment-backend-smson.md` becomes `"slug": "conventions/mvldev-assignment-backend-smson"`.
+7. Use exactly this `gctree __apply-update` JSON schema. Do not invent fields. In particular, never use `id`, `path`, or `content`; use `slug`, `body`, and `indexEntries`.
+
+```json
+{
+  "branch": "<gc-branch>",
+  "docs": [
+    {
+      "title": "conventions: example repo",
+      "slug": "conventions/example-repo",
+      "category": "conventions",
+      "summary": "Actionable one-paragraph summary with patterns, commands, and constraints.",
+      "body": "## Patterns\n\n- Details body only. Do not include # title, ## Summary, or ## Index Entries here.",
+      "indexLabel": "example repo conventions",
+      "indexEntries": ["example repo", "ExampleRepo", "주요 한국어 검색어", "command names", "field names"]
+    }
+  ]
+}
+```
+
+8. `body` is only the Details body. It may contain useful second-level sections such as `## Patterns`, but must not contain the top-level title, `## Summary`, or `## Index Entries`.
+9. `indexEntries` is mandatory. Add aliases, related terms, command names, field names, workflow names, acronyms, Korean terms, and English terms so `gctree resolve` can find the doc without translation.
+10. Apply the update with `gctree __apply-update --input <temp-file>`.
+11. Verify immediately:
+    - `gctree verify-onboarding --branch <gc-branch>`
+    - `gctree resolve --query "<new keyword>"`
+    - `gctree show-doc --id "<slug>"`
+12. If you intended to update an existing doc and `doc_count` increases unexpectedly, do not report success. Inspect the duplicate, remove the accidental doc, and re-apply with the correct `slug`.
+13. Keep the current gc-branch explicit throughout the conversation and tell the user exactly which docs changed.