feat: v0.6.0 — inline context injection, 13→5 tools, MCP resources + prompts

Replace indirect 3-line CLAUDE.md pointer with rich inline context injection
(architecture, risk map, directives) between <!-- codecortex:start/end --> markers.
Reduces MCP tools from 13 to 5 proven, irreplaceable ones. Adds 3 MCP resources
and 2 MCP prompts. Includes coupling noise filter, static fallback paths, and
new `inject` CLI command.

Changes:
- NEW: src/core/context-injection.ts — generates ~60-80 line inline Markdown
- NEW: src/cli/commands/inject.ts — standalone CLI command
- NEW: src/mcp/resources.ts — 3 MCP resources (overview, hotspots, module/{name})
- NEW: src/mcp/prompts.ts — 2 MCP prompts (start_session, before_editing)
- NEW: generateHotspotsMarkdown() in temporal.ts — static hotspots.md generation
- NEW: coupling noise filter (go.mod↔go.sum, Cargo pairs, golden clusters)
- REMOVED: 8 MCP tools (5 read + 3 write) — agents use static files instead
- REMOVED: src/mcp/tools/write.ts (0 organic usage)
- 279 tests passing, tsc clean

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: rushikeshmore

CLAUDE.md

@@ -6,7 +6,7 @@ Persistent codebase knowledge layer for AI agents. Pre-builds architecture, depe
 - TypeScript, ESM (`"type": "module"`)
 - tree-sitter (native N-API) + 27 language grammar packages
 - @modelcontextprotocol/sdk - MCP server (stdio transport)
-- commander - CLI (init, serve, update, status, symbols, search, modules, hotspots, hook, upgrade)
+- commander - CLI (init, serve, update, inject, status, symbols, search, modules, hotspots, hook, upgrade)
 - simple-git - git integration + temporal analysis
 - zod - schema validation for LLM analysis results
 - yaml - cortex.yaml manifest
@@ -45,16 +45,25 @@ Hybrid extraction:
 - `codecortex symbols [query]` - browse and filter the symbol index
 - `codecortex search <query>` - search across all knowledge files
 - `codecortex modules [name]` - list modules or deep-dive into one
+- `codecortex inject` - regenerate inline context in CLAUDE.md and agent config files
 - `codecortex hotspots` - files ranked by risk (churn + coupling + bugs)
 - `codecortex hook install|uninstall|status` - manage git hooks for auto-update
 - `codecortex upgrade` - check for and install latest version
 
-## MCP Tools (13)
-Read (10): get_project_overview, get_module_context, get_session_briefing, search_knowledge, get_decision_history, get_dependency_graph, lookup_symbol, get_change_coupling, get_hotspots, get_edit_briefing
-Write (3): record_decision, update_patterns, record_observation
+## MCP Tools (5)
+get_project_overview, get_dependency_graph, lookup_symbol, get_change_coupling, get_edit_briefing
 
-All read tools include `_freshness` metadata (status, lastAnalyzed, filesChangedSince, changedFiles, message).
-All read tools return context-safe responses (<10K chars) via truncation utilities in `src/utils/truncate.ts`.
+## MCP Resources (3)
+- `codecortex://project/overview` — constitution (architecture, risk map)
+- `codecortex://project/hotspots` — risk-ranked files
+- `codecortex://module/{name}` — module documentation (template)
+
+## MCP Prompts (2)
+- `start_session` — constitution + latest session for context
+- `before_editing` — risk assessment for files you plan to edit
+
+All tools include `_freshness` metadata (status, lastAnalyzed, filesChangedSince, changedFiles, message).
+All tools return context-safe responses (<10K chars) via truncation utilities in `src/utils/truncate.ts`.
 
 ## Pre-Publish Checklist
 Run ALL of these before `npm publish`. Do not skip any step.
@@ -72,7 +81,7 @@ Run ALL of these before `npm publish`. Do not skip any step.
 - **Grammar smoke test** (`parser.test.ts`): Loads every language in `LANGUAGE_LOADERS` via `parseSource()`. Catches missing packages, broken native builds, wrong require paths. This is what would have caught the tree-sitter-liquid issue.
 - **Version-check tests**: Update notification, cache lifecycle, PM detection, upgrade commands.
 - **Hook tests**: Git hook install/uninstall/status integration tests.
-- **MCP tests**: All 13 tools (read + write), simulation tests.
+- **MCP tests**: All 5 tools, resources, prompts, simulation tests.
 
 ### Known limitations
 - tree-sitter native bindings don't compile on Node 24 yet (upstream issue)
@@ -91,7 +100,7 @@ Run ALL of these before `npm publish`. Do not skip any step.
 src/
   cli/           - commander CLI (init, serve, update, status)
   mcp/           - MCP server + tools
-  core/          - knowledge store (graph, modules, decisions, sessions, patterns, constitution, search, agent-instructions, freshness)
+  core/          - knowledge store (graph, modules, decisions, sessions, patterns, constitution, search, agent-instructions, context-injection, freshness)
   extraction/    - tree-sitter native N-API (parser, symbols, imports, calls)
   git/           - git diff, history, temporal analysis
   types/         - TypeScript types + Zod schemas

package.json

@@ -1,6 +1,6 @@
 {
   "name": "codecortex-ai",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Persistent codebase knowledge layer for AI agents — architecture, dependencies, coupling, and risk served via MCP",
   "type": "module",
   "bin": {

src/cli/commands/init.ts

@@ -14,6 +14,7 @@ import { writeFile, writeJsonStream, ensureDir, cortexPath } from '../../utils/f
 import { readFile } from 'node:fs/promises'
 import { generateStructuralModuleDocs } from '../../core/module-gen.js'
 import { generateAgentInstructions } from '../../core/agent-instructions.js'
+import { generateHotspotsMarkdown } from '../../git/temporal.js'
 import { createDecision, writeDecision, listDecisions } from '../../core/decisions.js'
 import type { SymbolRecord, ImportEdge, CallEdge, SymbolIndex, ProjectInfo } from '../../types/index.js'
 
@@ -40,6 +41,7 @@ export async function initCommand(opts: { root: string; days: string }): Promise
   const allImports: ImportEdge[] = []
   const allCalls: CallEdge[] = []
   let extractionErrors = 0
+  const langStats = new Map<string, { files: number; symbols: number }>()
 
   let parsed = 0
   const parseable = project.files.filter(f => languageFromPath(f.path)).length
@@ -49,6 +51,9 @@ export async function initCommand(opts: { root: string; days: string }): Promise
     const lang = languageFromPath(file.path)
     if (!lang) continue
 
+    const stats = langStats.get(lang) || { files: 0, symbols: 0 }
+    stats.files++
+
     try {
       const tree = await parseFile(file.absolutePath, lang)
       const source = await readFile(file.absolutePath, 'utf-8')
@@ -57,12 +62,14 @@ export async function initCommand(opts: { root: string; days: string }): Promise
       const imports = extractImports(tree, file.path, lang)
       const calls = extractCalls(tree, file.path, lang)
 
+      stats.symbols += symbols.length
       allSymbols.push(...symbols)
       allImports.push(...imports)
       allCalls.push(...calls)
     } catch {
       extractionErrors++
     }
+    langStats.set(lang, stats)
     parsed++
     if (showProgress && parsed % 5000 === 0) {
       process.stdout.write(`\r  Progress: ${parsed}/${parseable} files (${allSymbols.length} symbols)`)
@@ -74,6 +81,13 @@ export async function initCommand(opts: { root: string; days: string }): Promise
   if (extractionErrors > 0) {
     console.log(`  (${extractionErrors} files skipped due to parse errors)`)
   }
+
+  // Warn about languages with 0 symbols extracted
+  for (const [lang, stats] of langStats) {
+    if (stats.files > 0 && stats.symbols === 0) {
+      console.log(`  \u26a0 Warning: ${lang} \u2014 ${stats.files} files parsed, 0 symbols extracted. Grammar may not support this language.`)
+    }
+  }
   console.log('')
 
   // Step 3: Build dependency graph
@@ -140,9 +154,10 @@ export async function initCommand(opts: { root: string; days: string }): Promise
   // Write graph.json
   await writeGraph(root, graph)
 
-  // Write temporal.json
+  // Write temporal.json + hotspots.md
   if (temporalData) {
     await writeFile(cortexPath(root, 'temporal.json'), JSON.stringify(temporalData, null, 2))
+    await writeFile(cortexPath(root, 'hotspots.md'), generateHotspotsMarkdown(temporalData))
   }
 
   // Write overview.md — compact summary only (no raw file listing)
@@ -162,7 +177,7 @@ export async function initCommand(opts: { root: string; days: string }): Promise
   await writeManifest(root, manifest)
 
   // Write patterns.md (empty template)
-  await writeFile(cortexPath(root, 'patterns.md'), '# Coding Patterns\n\nNo patterns recorded yet. Use `update_patterns` to add patterns.\n')
+  await writeFile(cortexPath(root, 'patterns.md'), '# Coding Patterns\n\nNo patterns recorded yet. Edit this file directly to add patterns.\n')
 
   // Generate structural module docs
   const moduleDocsGenerated = await generateStructuralModuleDocs(root, {
@@ -185,8 +200,8 @@ export async function initCommand(opts: { root: string; days: string }): Promise
   console.log('  Written: constitution.md')
   console.log('')
 
-  // Step 7: Agent onboarding
-  console.log('Step 7/7: Generating agent instructions...')
+  // Step 7: Agent onboarding + inline context injection
+  console.log('Step 7/7: Generating inline context...')
   const updatedFiles = await generateAgentInstructions(root)
 
   // Seed a starter decision (skip if decisions already exist)

src/cli/commands/inject.ts

@@ -0,0 +1,27 @@
+import { resolve } from 'node:path'
+import { existsSync } from 'node:fs'
+import { cortexPath } from '../../utils/files.js'
+import { injectAllAgentFiles } from '../../core/context-injection.js'
+
+export async function injectCommand(opts: { root: string }): Promise<void> {
+  const root = resolve(opts.root)
+
+  if (!existsSync(cortexPath(root, 'cortex.yaml'))) {
+    console.error('Error: No CodeCortex knowledge found. Run `codecortex init` first.')
+    process.exitCode = 1
+    return
+  }
+
+  console.log('Regenerating inline context...')
+  const updated = await injectAllAgentFiles(root)
+
+  if (updated.length === 0) {
+    console.log('  All agent config files are already up to date.')
+  } else {
+    for (const file of updated) {
+      console.log(`  Updated: ${file}`)
+    }
+  }
+  console.log('')
+  console.log('Done. Agent config files now contain inline project knowledge.')
+}

src/cli/commands/update.ts

@@ -16,6 +16,8 @@ import { generateConstitution } from '../../core/constitution.js'
 import { createSession, writeSession, getLatestSession } from '../../core/sessions.js'
 import { readFile as fsRead } from 'node:fs/promises'
 import { generateStructuralModuleDocs } from '../../core/module-gen.js'
+import { generateHotspotsMarkdown } from '../../git/temporal.js'
+import { injectAllAgentFiles } from '../../core/context-injection.js'
 import type { SymbolRecord, ImportEdge, CallEdge, SymbolIndex } from '../../types/index.js'
 
 export async function updateCommand(opts: { root: string; days: string }): Promise<void> {
@@ -100,6 +102,7 @@ export async function updateCommand(opts: { root: string; days: string }): Promi
   await writeGraph(root, graph)
   if (temporalData) {
     await writeFile(cortexPath(root, 'temporal.json'), JSON.stringify(temporalData, null, 2))
+    await writeFile(cortexPath(root, 'hotspots.md'), generateHotspotsMarkdown(temporalData))
   }
 
   // Generate structural module docs (skip existing)
@@ -125,6 +128,9 @@ export async function updateCommand(opts: { root: string; days: string }): Promi
     temporal: temporalData,
   })
 
+  // Refresh inline context in agent config files
+  await injectAllAgentFiles(root)
+
   // Create session log
   const diff = await getUncommittedDiff(root).catch(() => ({ filesChanged: [], summary: 'no changes' }))
   const previousSession = await getLatestSession(root)

src/cli/grouped-help.ts

@@ -1,7 +1,7 @@
 import type { Command, Help } from 'commander'
 
 const COMMAND_GROUPS: Array<{ title: string; commands: string[] }> = [
-  { title: 'Core',    commands: ['init', 'serve', 'update', 'status'] },
+  { title: 'Core',    commands: ['init', 'serve', 'update', 'inject', 'status'] },
   { title: 'Query',   commands: ['symbols', 'search', 'modules', 'hotspots'] },
   { title: 'Utility', commands: ['hook', 'upgrade'] },
 ]

src/cli/index.ts

@@ -5,6 +5,7 @@ import { Command } from 'commander'
 import { initCommand } from './commands/init.js'
 import { serveCommand } from './commands/serve.js'
 import { updateCommand } from './commands/update.js'
+import { injectCommand } from './commands/inject.js'
 import { statusCommand } from './commands/status.js'
 import { symbolsCommand } from './commands/symbols.js'
 import { searchCommand } from './commands/search.js'
@@ -51,6 +52,12 @@ program
   .option('-d, --days <number>', 'Days of git history to re-analyze', '90')
   .action(updateCommand)
 
+program
+  .command('inject')
+  .description('Regenerate inline context in CLAUDE.md and agent config files')
+  .option('-r, --root <path>', 'Project root directory', process.cwd())
+  .action(injectCommand)
+
 program
   .command('status')
   .description('Show knowledge freshness and symbol counts')

src/core/agent-instructions.ts

@@ -1,9 +1,5 @@
-import { existsSync } from 'node:fs'
-import { join } from 'node:path'
-import { readFile, writeFile as writeFileFs } from 'node:fs/promises'
 import { writeFile, ensureDir, cortexPath } from '../utils/files.js'
-
-const CODECORTEX_SECTION_MARKER = '## CodeCortex'
+import { injectAllAgentFiles } from './context-injection.js'
 
 export const AGENT_INSTRUCTIONS = `# CodeCortex — Codebase Navigation & Risk Tools
 
@@ -13,95 +9,35 @@ This project uses CodeCortex. It gives you a pre-built map of the codebase — a
 
 ## Navigation (start here)
 - \`get_project_overview\` — architecture, modules, risk map. Call this first.
-- \`search_knowledge\` — find where a function/class/type is DEFINED by name. Ranked results: exported definitions first. NOT for content search — use grep for that.
 - \`lookup_symbol\` — precise symbol lookup with kind + file path filters. Use when you know exactly what you're looking for (e.g., "all interfaces in gateway/").
-- \`get_module_context\` — what files, symbols, and deps are in a specific module.
 - \`get_dependency_graph\` — import/export graph filtered by file or module.
-- \`get_session_briefing\` — what changed since the last session.
 
 ## When to use grep instead
 - "How does X work?" → grep (searches file contents)
 - "Find all usage of X" → grep (finds every occurrence)
-- "Where is X defined?" → \`search_knowledge\` or \`lookup_symbol\` (finds definitions, ranked)
+- "Where is X defined?" → \`lookup_symbol\` (finds definitions with filters)
 
 ## Before Editing (ALWAYS call these)
 - \`get_edit_briefing\` — co-change risks, hidden dependencies, bug history for files you plan to edit. Prevents bugs from files that secretly change together.
 - \`get_change_coupling\` — files that historically change together. Missing one causes bugs.
-- \`get_hotspots\` — files ranked by risk (churn + coupling + bugs).
+
+## Static Knowledge (read directly, no tool needed)
+- \`.codecortex/modules/*.md\` — module docs (purpose, deps, API)
+- \`.codecortex/hotspots.md\` — files ranked by risk (churn + coupling + bugs)
+- \`.codecortex/patterns.md\` — coding conventions
+- \`.codecortex/decisions/*.md\` — architectural decision records
 
 ## Response Detail Control
 Most tools accept \`detail: "brief"\` (default) or \`"full"\`. Use brief for exploration, full only when you need exhaustive data.
-
-## Building Knowledge (call as you work)
-- \`record_decision\` — when you make a non-obvious technical choice, record WHY.
-- \`update_patterns\` — when you discover a coding convention, document it.
-- \`record_observation\` — record anything you learned (gotchas, undocumented deps, env requirements).
-- \`get_decision_history\` — check what decisions were already made and why.
 `
 
-const CLAUDEMD_POINTER = `
-${CODECORTEX_SECTION_MARKER}
-This project uses CodeCortex for codebase knowledge. See \`.codecortex/AGENT.md\` for available MCP tools and when to use them.
-`
-
-// All known agent instruction files across AI coding tools
-const AGENT_CONFIG_FILES = [
-  'CLAUDE.md',           // Claude Code, Claude Desktop
-  '.cursorrules',        // Cursor
-  '.windsurfrules',      // Windsurf
-  'AGENTS.md',           // Generic / multi-agent convention
-  '.github/copilot-instructions.md', // GitHub Copilot
-]
-
 export async function generateAgentInstructions(projectRoot: string): Promise<string[]> {
-  // 1. Write .codecortex/AGENT.md (canonical source of truth)
+  // 1. Write .codecortex/AGENT.md (compact tool reference)
   await ensureDir(cortexPath(projectRoot))
   await writeFile(cortexPath(projectRoot, 'AGENT.md'), AGENT_INSTRUCTIONS)
 
-  // 2. Append pointer to every agent config file that exists
-  //    If NONE exist, create CLAUDE.md as default
-  const updated: string[] = ['AGENT.md']
-  let foundAny = false
-
-  for (const file of AGENT_CONFIG_FILES) {
-    const filePath = join(projectRoot, file)
-    if (existsSync(filePath)) {
-      foundAny = true
-      const wasUpdated = await appendPointerToFile(filePath)
-      if (wasUpdated) updated.push(file)
-    }
-  }
-
-  // If no agent config files exist at all, create CLAUDE.md as default
-  if (!foundAny) {
-    await appendPointerToFile(join(projectRoot, 'CLAUDE.md'))
-    updated.push('CLAUDE.md')
-  }
-
-  return updated
-}
-
-async function appendPointerToFile(filePath: string): Promise<boolean> {
-  // Ensure parent directory exists (for .github/copilot-instructions.md)
-  const dir = join(filePath, '..')
-  if (!existsSync(dir)) {
-    const { mkdir } = await import('node:fs/promises')
-    await mkdir(dir, { recursive: true })
-  }
-
-  if (existsSync(filePath)) {
-    const content = await readFileFs(filePath, 'utf-8')
-    // Don't duplicate — check if CodeCortex section already exists
-    if (content.includes(CODECORTEX_SECTION_MARKER)) return false
-    await writeFileFs(filePath, content + CLAUDEMD_POINTER, 'utf-8')
-    return true
-  } else {
-    // Create new file with just the pointer
-    await writeFileFs(filePath, CLAUDEMD_POINTER.trimStart(), 'utf-8')
-    return true
-  }
-}
+  // 2. Inject rich inline context into all agent config files
+  const injected = await injectAllAgentFiles(projectRoot)
 
-async function readFileFs(path: string, encoding: BufferEncoding): Promise<string> {
-  return readFile(path, encoding)
+  return ['AGENT.md', ...injected]
 }

src/core/constitution.ts

@@ -148,7 +148,7 @@ export async function generateConstitution(projectRoot: string, data?: Constitut
   }
   lines.push(
     ``,
-    `Use \`get_module_context\` to deep-dive into any module.`,
+    `Read \`.codecortex/modules/*.md\` directly for module deep-dives.`,
     `Use \`get_change_coupling\` before editing a file to check what else must change.`,
     `Use \`lookup_symbol\` to find any function, type, or class.`,
   )