opentology 0.3.6 → 0.3.7

package/dist/lib/deep-scanner.d.ts

@@ -48,12 +48,19 @@ export interface MethodCallInfo {
     caller: string;
     callee: string;
 }
+export interface UnsupportedFileGroup {
+    extension: string;
+    language: string;
+    files: string[];
+    count: number;
+}
 export interface DeepScanResult {
     deepScanAvailable: true;
     classes: ClassInfo[];
     interfaces: InterfaceInfo[];
     functions: FunctionInfo[];
     methodCalls: MethodCallInfo[];
+    unsupportedFiles: UnsupportedFileGroup[];
     fileCount: number;
     symbolCount: number;
     scanDurationMs: number;

package/dist/lib/deep-scanner.js

@@ -43,6 +43,66 @@ async function discoverFiles(rootDir, extensions, maxFiles) {
         .filter(f => !f.includes('node_modules') && !f.includes('/dist/'));
     return { files: allFiles.slice(0, maxFiles), total: allFiles.length };
 }
+// ── Unsupported language detection ─────────────────────────────
+const EXTENSION_LANGUAGE_MAP = {
+    '.rb': 'ruby', '.kt': 'kotlin', '.kts': 'kotlin',
+    '.cs': 'csharp', '.cpp': 'cpp', '.cc': 'cpp', '.cxx': 'cpp',
+    '.c': 'c', '.h': 'c-header', '.hpp': 'cpp-header',
+    '.php': 'php', '.lua': 'lua', '.dart': 'dart',
+    '.scala': 'scala', '.ex': 'elixir', '.exs': 'elixir',
+    '.zig': 'zig', '.jl': 'julia', '.r': 'r',
+    '.clj': 'clojure', '.erl': 'erlang', '.hs': 'haskell',
+    '.ml': 'ocaml', '.nim': 'nim', '.cr': 'crystal',
+    '.pl': 'perl', '.pm': 'perl',
+};
+const SKIP_EXTENSIONS = new Set([
+    '.json', '.yaml', '.yml', '.toml', '.xml', '.ini', '.cfg', '.conf',
+    '.md', '.txt', '.rst', '.csv', '.tsv', '.adoc',
+    '.css', '.scss', '.less', '.sass', '.styl',
+    '.html', '.htm', '.svg', '.png', '.jpg', '.jpeg', '.gif', '.ico', '.webp', '.avif',
+    '.woff', '.woff2', '.ttf', '.eot', '.otf',
+    '.lock', '.log', '.map', '.d.ts',
+    '.wasm', '.bin', '.exe', '.dll', '.so', '.dylib', '.a',
+    '.env', '.gitignore', '.gitattributes', '.editorconfig',
+    '.prettierrc', '.eslintrc', '.babelrc',
+    '.sh', '.bash', '.zsh', '.fish', '.bat', '.cmd', '.ps1',
+]);
+async function discoverUnsupportedFiles(rootDir, supportedExtensions) {
+    const { execSync } = await import('node:child_process');
+    const { extname } = await import('node:path');
+    let stdout;
+    try {
+        stdout = execSync(`git -C "${rootDir}" ls-files`, {
+            encoding: 'utf-8',
+            maxBuffer: 10 * 1024 * 1024,
+        });
+    }
+    catch {
+        return [];
+    }
+    const allFiles = stdout.trim().split('\n').filter(Boolean)
+        .filter(f => !f.includes('node_modules') && !f.includes('/dist/'));
+    const groups = new Map();
+    for (const file of allFiles) {
+        const ext = extname(file).toLowerCase();
+        if (!ext || supportedExtensions.has(ext) || SKIP_EXTENSIONS.has(ext))
+            continue;
+        if (!EXTENSION_LANGUAGE_MAP[ext])
+            continue; // only known source languages
+        if (!groups.has(ext))
+            groups.set(ext, []);
+        groups.get(ext).push(file);
+    }
+    return Array.from(groups.entries())
+        .map(([ext, files]) => ({
+        extension: ext,
+        language: EXTENSION_LANGUAGE_MAP[ext] ?? ext.slice(1),
+        files,
+        count: files.length,
+    }))
+        .filter(g => g.count > 0)
+        .sort((a, b) => b.count - a.count);
+}
 // ── Main entry point ────────────────────────────────────────────
 export async function deepScan(rootDir, options) {
     const maxFiles = options?.maxFiles ?? 500;
@@ -83,6 +143,7 @@ export async function deepScan(rootDir, options) {
             interfaces: [],
             functions: [],
             methodCalls: [],
+            unsupportedFiles: [],
             fileCount: total,
             symbolCount: 0,
             scanDurationMs: Date.now() - start,
@@ -147,12 +208,16 @@ export async function deepScan(rootDir, options) {
     const symbolCount = classes.reduce((n, c) => n + 1 + c.methods.length, 0)
         + interfaces.length
         + functions.length;
+    // Discover unsupported language files
+    const supportedExtensions = new Set(available.flatMap(e => e.extensions));
+    const unsupportedFiles = await discoverUnsupportedFiles(rootDir, supportedExtensions);
     return {
         deepScanAvailable: true,
         classes,
         interfaces,
         functions,
         methodCalls,
+        unsupportedFiles,
         fileCount: files.length,
         symbolCount,
         scanDurationMs: Date.now() - start,

package/dist/mcp/server.js

@@ -15,11 +15,12 @@ import { fromSchemaData, toMermaid, toDot } from '../lib/visualizer.js';
 import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { OTX_BOOTSTRAP_TURTLE } from '../templates/otx-ontology.js';
-import { generateContextSection, updateClaudeMd } from '../templates/claude-md-context.js';
+import { generateContextSection, updateClaudeMd, updateGlobalClaudeMd } from '../templates/claude-md-context.js';
 import { generateHookScript } from '../templates/session-start-hook.js';
 import { generatePreEditHookScript } from '../templates/pre-edit-hook.js';
 import { generateUserPromptHookScript } from '../templates/user-prompt-hook.js';
 import { generatePostErrorHookScript } from '../templates/post-error-hook.js';
+import { generateStopSessionHookScript } from '../templates/stop-session-hook.js';
 import { generateSlashCommands } from '../templates/slash-commands.js';
 import { runDoctor } from '../lib/doctor.js';
 import { syncContext } from '../lib/context-sync.js';
@@ -412,15 +413,74 @@ async function handleContextScan(args) {
             hints.push(`Symbol triples: ${pushStats.triplesInserted} in ${pushStats.batchCount} batches`);
         if (moduleStats)
             hints.push(`Module triples: ${moduleStats.modules} modules, ${moduleStats.edges} edges`);
-        return {
-            ...scanResult,
+        // Build compact summary — do NOT return full symbol arrays (#66)
+        const compact = {
+            deepScanAvailable: true,
+            counts: {
+                classes: scanResult.classes.length,
+                interfaces: scanResult.interfaces.length,
+                functions: scanResult.functions.length,
+                methodCalls: scanResult.methodCalls.length,
+                files: scanResult.fileCount,
+                symbols: scanResult.symbolCount,
+            },
+            scanDurationMs: scanResult.scanDurationMs,
+            capped: scanResult.capped,
+            warnings: scanResult.warnings,
             pushStats,
             moduleStats,
             _experimental: true,
             _hint: hints.length
-                ? `${hints.join('. ')}. Query examples:\n- Classes: SELECT ?c ?name WHERE { ?c a otx:Class ; otx:title ?name }\n- Dependents: SELECT ?dep WHERE { ?dep otx:dependsOn <urn:module:src/lib/store-adapter> }\n- Call graph: SELECT ?caller ?callee WHERE { ?s a otx:MethodCall ; otx:callerSymbol ?caller ; otx:calleeSymbol ?callee }`
+                ? `${hints.join('. ')}. All symbols auto-pushed to graph. Query examples:\n- Classes: SELECT ?c ?name WHERE { ?c a otx:Class ; otx:title ?name }\n- Dependents: SELECT ?dep WHERE { ?dep otx:dependsOn <urn:module:src/lib/store-adapter> }\n- Call graph: SELECT ?caller ?callee WHERE { ?s a otx:MethodCall ; otx:callerSymbol ?caller ; otx:calleeSymbol ?callee }`
                 : 'Deep scan completed but triple push failed. Use push manually with the generated triples.',
         };
+        // LLM fallback for unsupported languages (#65)
+        if (scanResult.unsupportedFiles.length > 0) {
+            const samples = [];
+            for (const group of scanResult.unsupportedFiles.slice(0, 5)) {
+                // Pick entry-point-like files first, then first files
+                const sorted = [...group.files].sort((a, b) => {
+                    const isEntry = (f) => /\/(main|index|app|mod|lib)\.[^/]+$/.test(f) ? 0 : 1;
+                    return isEntry(a) - isEntry(b);
+                });
+                for (const file of sorted.slice(0, 2)) {
+                    try {
+                        const fullPath = join(process.cwd(), file);
+                        const raw = readFileSync(fullPath, 'utf-8');
+                        const lines = raw.split('\n').slice(0, 30).join('\n');
+                        samples.push({ path: file, language: group.language, content: lines });
+                    }
+                    catch { /* skip unreadable */ }
+                }
+            }
+            compact.unsupportedFiles = scanResult.unsupportedFiles.map(g => ({
+                language: g.language,
+                extension: g.extension,
+                count: g.count,
+                files: g.files.slice(0, 5),
+            }));
+            if (samples.length > 0) {
+                compact.samples = samples;
+                compact.turtleTemplate = [
+                    '# Push symbol triples for unsupported language files.',
+                    '# Replace {filePath} and {Name} with actual values from the samples above.',
+                    '@prefix otx: <https://opentology.dev/vocab#> .',
+                    '',
+                    '# Class/Struct:',
+                    '# <urn:symbol:{filePath}/class/{Name}> a otx:Class ;',
+                    '#     otx:title "{Name}" ; otx:definedIn <urn:module:{filePath}> .',
+                    '',
+                    '# Function:',
+                    '# <urn:symbol:{filePath}/function/{name}> a otx:Function ;',
+                    '#     otx:title "{name}" ; otx:definedIn <urn:module:{filePath}> .',
+                    '',
+                    '# Interface/Trait/Protocol:',
+                    '# <urn:symbol:{filePath}/interface/{Name}> a otx:Interface ;',
+                    '#     otx:title "{Name}" ; otx:definedIn <urn:module:{filePath}> .',
+                ].join('\n');
+            }
+        }
+        return compact;
     }
     // Default: module-level scan — now auto-pushes module triples like context_init
     const maxBytes = args.maxSnapshotBytes ?? 15360;
@@ -491,7 +551,7 @@ async function handleContextInit(args) {
         if (!config.files[contextUri].includes(relPath)) {
             config.files[contextUri].push(relPath);
         }
-        actions.push('Bootstrapped otx ontology (6 classes, 12 properties)');
+        actions.push('Bootstrapped otx ontology (13 classes, 24 properties)');
     }
     // Generate hook script
     const hookDir = join(process.cwd(), '.opentology', 'hooks');
@@ -520,6 +580,12 @@ async function handleContextInit(args) {
         writeFileSync(postErrorHookPath, generatePostErrorHookScript(), 'utf-8');
         actions.push('Generated hook: .opentology/hooks/post-error.mjs');
     }
+    const stopSessionHookPath = join(hookDir, 'stop-session-reminder.mjs');
+    if (!existsSync(stopSessionHookPath) || force) {
+        mkdirSync(hookDir, { recursive: true });
+        writeFileSync(stopSessionHookPath, generateStopSessionHookScript(), 'utf-8');
+        actions.push('Generated hook: .opentology/hooks/stop-session-reminder.mjs');
+    }
     // Update CLAUDE.md
     const claudeMdPath = join(process.cwd(), 'CLAUDE.md');
     const section = generateContextSection(config.projectId, config.graphUri);
@@ -531,6 +597,16 @@ async function handleContextInit(args) {
         updateClaudeMd(claudeMdPath, section);
         actions.push('Updated CLAUDE.md context section');
     }
+    // Update global ~/.claude/CLAUDE.md
+    const homedir = (await import('node:os')).homedir();
+    const globalClaudeMdPath = join(homedir, '.claude', 'CLAUDE.md');
+    try {
+        updateGlobalClaudeMd(globalClaudeMdPath);
+        actions.push('Updated global ~/.claude/CLAUDE.md OpenTology section');
+    }
+    catch {
+        // Non-fatal: global CLAUDE.md update is best-effort
+    }
     // Generate slash commands
     const commandsDir = join(process.cwd(), '.claude', 'commands');
     const slashCommands = generateSlashCommands();
@@ -622,6 +698,22 @@ async function handleContextInit(args) {
         });
         hooksChanged = true;
     }
+    // Stop: session log + knowledge reminder
+    const stopSessionCmd = 'node .opentology/hooks/stop-session-reminder.mjs';
+    if (!hooks.Stop)
+        hooks.Stop = [];
+    const hasStopHook = hooks.Stop.some((h) => {
+        const entry = h;
+        const entryHooks = entry.hooks;
+        return entryHooks?.some((hook) => hook.command === stopSessionCmd);
+    });
+    if (!hasStopHook) {
+        hooks.Stop.push({
+            matcher: '',
+            hooks: [{ type: 'command', command: stopSessionCmd }],
+        });
+        hooksChanged = true;
+    }
     if (hooksChanged) {
         settings.hooks = hooks;
         writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');

package/dist/templates/claude-md-context.d.ts

@@ -1,2 +1,4 @@
 export declare function generateContextSection(projectId: string, graphUri: string): string;
+export declare function generateGlobalSection(): string;
+export declare function updateGlobalClaudeMd(filePath: string): void;
 export declare function updateClaudeMd(filePath: string, section: string): void;

package/dist/templates/claude-md-context.js

@@ -7,16 +7,17 @@ export function generateContextSection(projectId, graphUri) {
     return `${MARKER_BEGIN}
 ## Context Management — OpenTology
 
-This project uses OpenTology as its knowledge graph — treat it as the project's **long-term memory**.
-Before reading source files, grep-searching, or making assumptions, **query the graph first**.
-It holds architectural decisions, resolved issues, reusable patterns, module dependencies,
-symbol-level call graphs, and session history. Prefer graph knowledge over re-deriving facts from code.
+<principles>
+- **Graph first** — query the knowledge graph before reading source files or making assumptions.
+- **Always record** — push Session logs at session end; record Knowledge, Decisions, and Issues as they arise.
+- **Auto-ingest** — when the user shares a URL or external source, run the ingest protocol automatically.
+</principles>
 
 ### Graph Structure
 
 | Graph | URI | Purpose |
 |-------|-----|---------|
-| context | \`${contextUri}\` | Decisions, issues, knowledge |
+| context | \`${contextUri}\` | Decisions, issues, knowledge, modules, symbols |
 | sessions | \`${sessionsUri}\` | Session work logs |
 
 ### Ontology (\`otx:\` prefix)
@@ -29,27 +30,12 @@ symbol-level call graphs, and session history. Prefer graph knowledge over re-de
 | \`otx:Knowledge\` | Reusable knowledge |
 | \`otx:Session\` | Session logs |
 | \`otx:Pattern\` | Recurring patterns/conventions |
+| \`otx:Source\` | External knowledge source (article, paper, code, etc.) |
 | \`otx:Module\` | Source file module |
-| \`otx:Class\` | Class definition (symbol scan) |
-| \`otx:Interface\` | Interface definition (symbol scan) |
-| \`otx:Function\` | Function definition (symbol scan) |
-| \`otx:Method\` | Method definition (symbol scan) |
-| \`otx:MethodCall\` | Call relationship between symbols (symbol scan) |
-
-| Property | Range | Description |
-|----------|-------|-------------|
-| \`otx:title\` | string | Title |
-| \`otx:date\` | date | Date (YYYY-MM-DD) |
-| \`otx:body\` | string | Body content |
-| \`otx:status\` | string | Status (open/resolved/active) |
-| \`otx:reason\` | string | Decision rationale |
-| \`otx:nextTodo\` | string | Next action item |
-| \`otx:relatedTo\` | resource | Related entity |
-| \`otx:dependsOn\` | Module | Module import dependency |
-| \`otx:definedIn\` | Module | Which module a symbol belongs to |
-| \`otx:callerSymbol\` | string | Caller in a MethodCall |
-| \`otx:calleeSymbol\` | string | Callee in a MethodCall |
-| \`otx:calls\` | resource | Call relationship |
+| \`otx:Class\` / \`otx:Interface\` / \`otx:Function\` / \`otx:Method\` | Symbol-level entities (from deep scan) |
+| \`otx:MethodCall\` | Call relationship between symbols |
+
+Key properties: \`otx:title\`, \`otx:date\`, \`otx:body\`, \`otx:status\`, \`otx:reason\`, \`otx:nextTodo\`, \`otx:relatedTo\`, \`otx:dependsOn\`, \`otx:definedIn\`, \`otx:callerSymbol\`, \`otx:calleeSymbol\`, \`otx:sourceUrl\`, \`otx:sourceType\`. Full schema: use the \`schema\` tool.
 
 ### When to Record
 
@@ -58,127 +44,66 @@ symbol-level call graphs, and session history. Prefer graph knowledge over re-de
 | Architecture/tech decision | \`otx:Decision\` | context |
 | Bug/issue resolved | \`otx:Issue\` | context |
 | Reusable knowledge | \`otx:Knowledge\` | context |
+| Source ingested | \`otx:Source\` | context |
 | Session end | \`otx:Session\` | sessions |
 
-### Query Examples
-
-\`\`\`sparql
-# Recent sessions
-PREFIX otx: <https://opentology.dev/vocab#>
-SELECT ?title ?date ?nextTodo WHERE {
-  GRAPH <${sessionsUri}> {
-    ?s a otx:Session ; otx:title ?title ; otx:date ?date .
-    OPTIONAL { ?s otx:nextTodo ?nextTodo }
-  }
-} ORDER BY DESC(?date) LIMIT 5
-
-# Open issues
-PREFIX otx: <https://opentology.dev/vocab#>
-SELECT ?title ?date WHERE {
-  GRAPH <${contextUri}> {
-    ?s a otx:Issue ; otx:title ?title ; otx:date ?date ; otx:status "open" .
-  }
-} ORDER BY DESC(?date)
-\`\`\`
-
-### How to Use OpenTology Tools
+### Tools & Workflows
 
-OpenTology provides MCP tools to query and manage the project knowledge graph. Use them proactively.
+#### Before Working
 
-#### Pre-Analysis Context Check
-
-Before exploring code or analyzing architecture, query the knowledge graph for existing context:
-- **Decisions**: past architectural choices that may inform the current analysis
-- **Knowledge**: reusable patterns or lessons already recorded
-- **Issues**: known problems related to the area under investigation
-- **Sessions**: recent work in the same area
+1. **Query graph** — check for existing decisions, knowledge, issues, and sessions related to your task.
+2. **Check impact** — before editing a file, run \`context_impact\` to understand the blast radius (dependents, dependencies, related entities).
+3. **Search** — use \`query\` with SPARQL to find anything: \`?s a otx:Decision\`, \`?s a otx:Knowledge\`, \`?s a otx:Module\`, \`?s a otx:MethodCall\`, etc.
 
 \`\`\`sparql
+# Context search (replace "keyword" with your search term)
 PREFIX otx: <https://opentology.dev/vocab#>
 SELECT ?type ?title ?body WHERE {
   GRAPH <${contextUri}> {
     { ?s a otx:Decision ; otx:title ?title ; otx:body ?body . BIND("decision" AS ?type) }
-    UNION
-    { ?s a otx:Knowledge ; otx:title ?title ; otx:body ?body . BIND("knowledge" AS ?type) }
-    UNION
-    { ?s a otx:Issue ; otx:title ?title ; otx:body ?body . BIND("issue" AS ?type) }
+    UNION { ?s a otx:Knowledge ; otx:title ?title ; otx:body ?body . BIND("knowledge" AS ?type) }
+    UNION { ?s a otx:Issue ; otx:title ?title ; otx:body ?body . BIND("issue" AS ?type) }
   }
   FILTER(CONTAINS(LCASE(?title), "keyword") || CONTAINS(LCASE(?body), "keyword"))
 } LIMIT 10
 \`\`\`
 
-This prevents redundant analysis and ensures past decisions and knowledge inform current work.
-
-#### Pre-Edit Impact Check
-
-Before modifying a file, run \`context_impact\` with the target file path to understand the blast radius:
-- **dependents** — modules that import or depend on this file
-- **dependencies** — modules this file imports
-- **related** — decisions, issues, knowledge linked to this file
-- **impact level** — high / medium / low
-
-If impact is **high**, inform the user of affected modules and get confirmation before proceeding.
-
-#### Searching the Knowledge Graph
-
-Use \`query\` with SPARQL to find anything in the project graph. **Always query the graph before reading source files** when investigating code structure, dependencies, or call relationships:
+#### Ingesting External Sources
 
-- **Decisions**: \`?s a otx:Decision\` — why architectural choices were made
-- **Issues**: \`?s a otx:Issue ; otx:status "open"\` — known bugs and their status
-- **Knowledge**: \`?s a otx:Knowledge\` — reusable patterns and lessons learned
-- **Sessions**: query the sessions graph for past work logs and next TODOs
-- **Modules**: \`?s a otx:Module\` — all scanned source modules and their dependencies (\`otx:dependsOn\`)
-- **Symbols**: \`?s a otx:Class\`, \`otx:Interface\`, \`otx:Function\`, \`otx:Method\` — code-level entities (available after symbol-depth scan)
-- **Call graph**: \`?s a otx:MethodCall\` — who calls whom (available after symbol scan with \`includeMethodCalls=true\`)
-
-\`\`\`sparql
-# Functions in a specific module
-PREFIX otx: <https://opentology.dev/vocab#>
-SELECT ?name WHERE {
-  GRAPH <${contextUri}> {
-    ?f a otx:Function ; otx:title ?name ; otx:definedIn <urn:module:src/mcp/server> .
-  }
-}
+When the user shares a URL, file path, or external content, follow this protocol:
 
-# Who calls a specific function?
-PREFIX otx: <https://opentology.dev/vocab#>
-SELECT ?caller WHERE {
-  GRAPH <${contextUri}> {
-    ?s a otx:MethodCall ; otx:callerSymbol ?caller ; otx:calleeSymbol ?callee .
-    FILTER(CONTAINS(?callee, "persistGraph"))
-  }
-}
+1. **Duplicate check** — Query for existing sources with the same URL or title.
+2. **Register** — Push an \`otx:Source\` with status "pending" using the \`push\` tool.
+3. **Read** — Fetch URL content, read file, or use pasted text directly.
+4. **Extract** — Summarize key concepts. Create \`otx:Knowledge\` triples linked via \`otx:relatedTo\`.
+5. **Cross-reference** — Query existing graph for related decisions/issues/knowledge. Link via \`otx:relatedTo\`.
+6. **Contradictions** — If new knowledge contradicts existing entries, create \`otx:Issue\` with status "open".
+7. **Finalize** — Update source status from "pending" to "ingested". Run audit query.
 
-# Module dependency chain (what depends on a module?)
-PREFIX otx: <https://opentology.dev/vocab#>
-SELECT ?dependent WHERE {
-  GRAPH <${contextUri}> {
-    ?dependent otx:dependsOn+ <urn:module:src/lib/store-adapter> .
-  }
-}
-\`\`\`
+Duplicate check: \`SELECT ?s ?title WHERE { GRAPH <${contextUri}> { ?s a otx:Source ; otx:sourceUrl ?url . FILTER(?url = "URL") } }\`
+Audit: \`SELECT ?s ?title ?status (COUNT(?k) AS ?knowledgeCount) WHERE { GRAPH <${contextUri}> { ?s a otx:Source ; otx:title ?title ; otx:status ?status . OPTIONAL { ?k otx:relatedTo ?s } } } GROUP BY ?s ?title ?status\`
+Registration: \`<urn:source:{slug}> a otx:Source ; otx:title "..." ; otx:sourceUrl "..." ; otx:sourceType "article" ; otx:date "YYYY-MM-DD"^^xsd:date ; otx:status "pending" .\`
+Types: article | paper | code | transcript | documentation | video | podcast | book | other. Status: pending → ingested → stale. Recovery: \`rollback\`.
 
-#### Post-Edit Graph Update
+#### After Working
 
-After significant code changes (new files, renamed functions, changed dependencies), run \`context_scan\` to keep the knowledge graph in sync:
-- \`depth="module"\` — fast, updates file-level imports
-- \`depth="symbol"\` with \`includeMethodCalls=true\` — thorough, updates class/function/call graph
+- Run \`context_scan\` after significant code changes (\`depth="module"\` for fast, \`depth="symbol"\` for thorough).
 
-#### Other Useful Tools
+#### Tool Reference
 
 | Tool | When to Use |
 |------|-------------|
 | \`context_load\` | Session start — loads recent sessions, open issues, recent decisions |
-| \`context_scan\` | After significant code changes — rescans module/symbol dependencies |
+| \`context_scan\` | After code changes — rescans module/symbol dependencies |
 | \`context_impact\` | Before editing — checks blast radius of a file change |
-| \`schema\` | Explore ontology classes and properties, or inspect a specific class |
+| \`schema\` | Explore ontology classes and properties |
 | \`query\` | Run any SPARQL query against the project graph |
-| \`push\` | Record decisions, issues, knowledge, or session summaries |
+| \`push\` | Record decisions, issues, knowledge, sources, or session summaries |
 | \`doctor\` | Diagnose project health (config, store, hooks, CLAUDE.md) |
 
-### Session End Reminder
+### Session End
 
-At the end of each session, push a summary:
+Push a summary at the end of each meaningful session:
 
 \`\`\`turtle
 @prefix otx: <https://opentology.dev/vocab#> .
@@ -192,6 +117,62 @@ At the end of each session, push a summary:
 \`\`\`
 ${MARKER_END}`;
 }
+const GLOBAL_MARKER_BEGIN = '<!-- OPENTOLOGY:GLOBAL:BEGIN -->';
+const GLOBAL_MARKER_END = '<!-- OPENTOLOGY:GLOBAL:END -->';
+export function generateGlobalSection() {
+    return `${GLOBAL_MARKER_BEGIN}
+# OpenTology — RDF 기반 프로젝트 컨텍스트 관리
+
+Claude Code는 글로벌 MCP \`opentology\`를 통해 프로젝트 지식을 RDF 그래프로 관리한다.
+온톨로지, 도구 사용법, SPARQL 예시 등 상세 정보는 프로젝트별 CLAUDE.md에 자동 생성된다.
+여기서는 **모든 프로젝트에 공통 적용되는 행동 규칙만** 정의한다.
+
+## 핵심 원칙
+
+1. **그래프 먼저** — 코드를 읽거나 가정하기 전에 \`query\`로 그래프를 먼저 조회한다.
+2. **항상 기록** — 세션 종료 시 \`otx:Session\`, 의미 있는 작업은 \`Knowledge\`/\`Decision\`/\`Issue\`로 기록.
+3. **자동 수집** — 사용자가 URL이나 외부 소스를 공유하면 ingest 프로토콜을 자동 실행한다.
+4. **영향도 확인** — 파일 수정 전 \`context_impact\`로 blast radius를 확인한다.
+
+## URI 규칙
+
+| 대상 | 패턴 | 예시 |
+|------|------|------|
+| 프로젝트 | \`urn:project:{name}\` | \`urn:project:opentology\` |
+| 세션 | \`urn:session:{date}\` | \`urn:session:2026-04-05\` |
+| 의사결정 | \`urn:decision:{date}-{slug}\` | \`urn:decision:2026-04-05-ingest-feature\` |
+| 이슈 | \`urn:issue:{id}\` | \`urn:issue:1\` |
+| 지식 | \`urn:knowledge:{slug}\` | \`urn:knowledge:wasm-oxigraph\` |
+| 패턴 | \`urn:pattern:{slug}\` | \`urn:pattern:singleton-adapter\` |
+| 소스 | \`urn:source:{slug}\` | \`urn:source:karpathy-llm-wiki\` |
+
+## 기록 기준
+
+- **기록함**: 아키텍처 변경, 새 기능 구현, 버그 해결, 재사용 가능한 지식, 외부 소스 수집
+- **기록 안 함**: 오타 수정, 단순 질문 응답, 단순 설정 변경
+- 기록은 **간결하게**. 민감 정보(API 키 등)는 절대 기록하지 않는다.
+- \`opentology\` MCP가 연결되지 않은 프로젝트에서는 기록을 건너뛴다.
+${GLOBAL_MARKER_END}`;
+}
+export function updateGlobalClaudeMd(filePath) {
+    const section = generateGlobalSection();
+    if (!existsSync(filePath)) {
+        writeFileSync(filePath, section + '\n', 'utf-8');
+        return;
+    }
+    const content = readFileSync(filePath, 'utf-8');
+    const beginIdx = content.indexOf(GLOBAL_MARKER_BEGIN);
+    const endIdx = content.indexOf(GLOBAL_MARKER_END);
+    if (beginIdx === -1 || endIdx === -1) {
+        // No markers — prepend before existing content
+        writeFileSync(filePath, section + '\n\n' + content, 'utf-8');
+        return;
+    }
+    // Replace between markers
+    const before = content.substring(0, beginIdx);
+    const after = content.substring(endIdx + GLOBAL_MARKER_END.length);
+    writeFileSync(filePath, before + section + after, 'utf-8');
+}
 export function updateClaudeMd(filePath, section) {
     if (!existsSync(filePath)) {
         // Case 1: No file — create with just the section

package/dist/templates/otx-ontology.d.ts

@@ -1 +1 @@
-export declare const OTX_BOOTSTRAP_TURTLE = "@prefix otx: <https://opentology.dev/vocab#> .\n@prefix owl: <http://www.w3.org/2002/07/owl#> .\n@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .\n@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .\n\notx:Project a owl:Class .\notx:Decision a owl:Class .\notx:Issue a owl:Class .\notx:Knowledge a owl:Class .\notx:Session a owl:Class .\notx:Pattern a owl:Class .\notx:Module a owl:Class .\n\notx:title a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:date a owl:DatatypeProperty ; rdfs:range xsd:date .\notx:body a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:status a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:reason a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:cause a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:solution a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:nextTodo a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:relatedTo a owl:ObjectProperty .\notx:project a owl:ObjectProperty .\notx:dependsOn a owl:ObjectProperty ; rdfs:domain otx:Module ; rdfs:range otx:Module .\notx:stack a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:alternative a owl:DatatypeProperty ; rdfs:range xsd:string .\n\notx:Class a owl:Class .\notx:Interface a owl:Class .\notx:Function a owl:Class .\notx:Method a owl:Class .\notx:MethodCall a owl:Class .\n\notx:definedIn a owl:ObjectProperty ; rdfs:range otx:Module .\notx:extends a owl:ObjectProperty ; rdfs:domain otx:Class ; rdfs:range otx:Class .\notx:implements a owl:ObjectProperty ; rdfs:domain otx:Class ; rdfs:range otx:Interface .\notx:hasMethod a owl:ObjectProperty ; rdfs:domain otx:Class ; rdfs:range otx:Method .\notx:calls a owl:ObjectProperty .\notx:callerSymbol a owl:ObjectProperty ; rdfs:domain otx:MethodCall .\notx:calleeSymbol a owl:ObjectProperty ; rdfs:domain otx:MethodCall .\notx:returns a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:paramType a owl:DatatypeProperty ; rdfs:range xsd:string .\n";
+export declare const OTX_BOOTSTRAP_TURTLE = "@prefix otx: <https://opentology.dev/vocab#> .\n@prefix owl: <http://www.w3.org/2002/07/owl#> .\n@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .\n@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .\n\notx:Project a owl:Class .\notx:Decision a owl:Class .\notx:Issue a owl:Class .\notx:Knowledge a owl:Class .\notx:Session a owl:Class .\notx:Pattern a owl:Class .\notx:Module a owl:Class .\n\notx:title a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:date a owl:DatatypeProperty ; rdfs:range xsd:date .\notx:body a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:status a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:reason a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:cause a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:solution a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:nextTodo a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:relatedTo a owl:ObjectProperty .\notx:project a owl:ObjectProperty .\notx:dependsOn a owl:ObjectProperty ; rdfs:domain otx:Module ; rdfs:range otx:Module .\notx:stack a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:alternative a owl:DatatypeProperty ; rdfs:range xsd:string .\n\notx:Source a owl:Class .\n\notx:Class a owl:Class .\notx:Interface a owl:Class .\notx:Function a owl:Class .\notx:Method a owl:Class .\notx:MethodCall a owl:Class .\n\notx:definedIn a owl:ObjectProperty ; rdfs:range otx:Module .\notx:extends a owl:ObjectProperty ; rdfs:domain otx:Class ; rdfs:range otx:Class .\notx:implements a owl:ObjectProperty ; rdfs:domain otx:Class ; rdfs:range otx:Interface .\notx:hasMethod a owl:ObjectProperty ; rdfs:domain otx:Class ; rdfs:range otx:Method .\notx:calls a owl:ObjectProperty .\notx:callerSymbol a owl:ObjectProperty ; rdfs:domain otx:MethodCall .\notx:calleeSymbol a owl:ObjectProperty ; rdfs:domain otx:MethodCall .\notx:returns a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:paramType a owl:DatatypeProperty ; rdfs:range xsd:string .\n\notx:sourceUrl a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:sourceType a owl:DatatypeProperty ; rdfs:range xsd:string .\n";

package/dist/templates/otx-ontology.js

@@ -26,6 +26,8 @@ otx:dependsOn a owl:ObjectProperty ; rdfs:domain otx:Module ; rdfs:range otx:Mod
 otx:stack a owl:DatatypeProperty ; rdfs:range xsd:string .
 otx:alternative a owl:DatatypeProperty ; rdfs:range xsd:string .
 
+otx:Source a owl:Class .
+
 otx:Class a owl:Class .
 otx:Interface a owl:Class .
 otx:Function a owl:Class .
@@ -41,4 +43,7 @@ otx:callerSymbol a owl:ObjectProperty ; rdfs:domain otx:MethodCall .
 otx:calleeSymbol a owl:ObjectProperty ; rdfs:domain otx:MethodCall .
 otx:returns a owl:DatatypeProperty ; rdfs:range xsd:string .
 otx:paramType a owl:DatatypeProperty ; rdfs:range xsd:string .
+
+otx:sourceUrl a owl:DatatypeProperty ; rdfs:range xsd:string .
+otx:sourceType a owl:DatatypeProperty ; rdfs:range xsd:string .
 `;

package/dist/templates/stop-session-hook.d.ts

@@ -0,0 +1 @@
+export declare function generateStopSessionHookScript(): string;

package/dist/templates/stop-session-hook.js

@@ -0,0 +1,99 @@
+export function generateStopSessionHookScript() {
+    return `#!/usr/bin/env node
+// Generated by: opentology context init
+// Stop hook — reminds LLM to push session log and knowledge triples
+import { existsSync } from 'node:fs';
+import { execSync, execFileSync } from 'node:child_process';
+import { join, resolve, dirname } from 'node:path';
+
+const TIMEOUT = parseInt(process.env.OPENTOLOGY_HOOK_TIMEOUT || '5000', 10);
+
+function findProjectRoot(startDir) {
+  let dir = resolve(startDir);
+  while (dir !== dirname(dir)) {
+    if (existsSync(join(dir, '.opentology.json'))) return dir;
+    dir = dirname(dir);
+  }
+  return null;
+}
+
+function findBin(projectRoot) {
+  const local = join(projectRoot, 'node_modules', '.bin', 'opentology');
+  if (existsSync(local)) return { bin: local, args: [] };
+  return { bin: 'npx', args: ['opentology'] };
+}
+
+function run(projectRoot, cmdArgs) {
+  const { bin, args } = findBin(projectRoot);
+  return execFileSync(bin, [...args, ...cmdArgs], {
+    cwd: projectRoot,
+    timeout: TIMEOUT,
+    encoding: 'utf-8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+}
+
+try {
+  const projectRoot = findProjectRoot(process.cwd());
+  if (!projectRoot) process.exit(0);
+
+  // Check recent commits (last 2 hours)
+  let log = '';
+  try {
+    log = execSync('git log --since="2 hours ago" --oneline', {
+      cwd: projectRoot, encoding: 'utf-8', timeout: 3000,
+    }).trim();
+  } catch { process.exit(0); }
+
+  if (!log) process.exit(0);
+
+  const commitCount = log.split('\\n').length;
+  // Check if source code was changed (not just docs/config)
+  let srcChanged = false;
+  try {
+    const diff = execSync('git diff HEAD~' + Math.min(commitCount, 10) + ' --name-only 2>/dev/null', {
+      cwd: projectRoot, encoding: 'utf-8', timeout: 3000,
+    }).trim();
+    srcChanged = diff.split('\\n').some(f => f.startsWith('src/') || f.startsWith('lib/') || f.endsWith('.ts') || f.endsWith('.py') || f.endsWith('.go'));
+  } catch { srcChanged = commitCount >= 2; }
+
+  // Importance: high (3+ commits or src changes), medium (1-2 commits), low (0)
+  const importance = (commitCount >= 3 || srcChanged) ? 'high' : commitCount >= 1 ? 'medium' : 'low';
+  if (importance === 'low') process.exit(0);
+
+  // Check if session log already exists for today
+  const today = new Date().toISOString().slice(0, 10);
+  let sessionExists = false;
+  try {
+    const raw = run(projectRoot, [
+      'query', '--format', 'json',
+      'PREFIX otx: <https://opentology.dev/vocab#> ASK WHERE { ?s a otx:Session ; otx:date "' + today + '"^^<http://www.w3.org/2001/XMLSchema#date> }'
+    ]);
+    sessionExists = raw.includes('true');
+  } catch { /* query failed, assume not exists */ }
+
+  const reminders = [];
+
+  if (!sessionExists) {
+    reminders.push('Push an otx:Session summary to the sessions graph (title, date, body, nextTodo).');
+  }
+
+  // Always remind about Knowledge/Decision/Issue recording
+  reminders.push('Review if any of these should be recorded:');
+  reminders.push('- Architecture/tech decisions → otx:Decision');
+  reminders.push('- Reusable patterns or lessons → otx:Knowledge');
+  reminders.push('- Resolved bugs/issues → otx:Issue');
+  reminders.push('- External sources ingested → otx:Source');
+
+  if (reminders.length > 0) {
+    const header = sessionExists
+      ? 'Session log exists. Check if additional knowledge should be recorded:'
+      : 'Session log missing (' + today + ', ' + commitCount + ' commits, importance: ' + importance + '). Before ending:';
+    console.log(header);
+    for (const r of reminders) console.log('  ' + r);
+  }
+} catch {
+  process.exit(0);
+}
+`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opentology",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "description": "Ontology-powered project memory for AI coding assistants — your codebase as a knowledge graph",
   "type": "module",
   "bin": {