@getmikk/ai-context 1.7.1 → 1.8.0

package/README.md

@@ -1,329 +1,100 @@
-# @getmikk/ai-context
+# @getmikk/ai-context
 
-> Token-budgeted, graph-traced AI context — the difference between an LLM that guesses your architecture and one that actually knows it.
+> Token-budgeted AI context builder and claude.md / AGENTS.md generator.
 
 [![npm](https://img.shields.io/npm/v/@getmikk/ai-context)](https://www.npmjs.com/package/@getmikk/ai-context)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](../../LICENSE)
 
-`@getmikk/ai-context` solves the AI context window problem at the architectural level. Instead of dumping your entire codebase into a prompt and hoping the LLM figures it out, it walks the dependency graph from task-relevant seed functions, scores every reachable function by relevance, and packs the highest-signal functions into a token budget — giving your AI exactly what it needs and nothing it doesn't.
+Two things: a graph-traced context builder that packs the most relevant functions into a token budget for any given task, and a documentation generator that produces always-accurate `claude.md` and `AGENTS.md` files from the lock file.
 
-It also generates `claude.md` and `AGENTS.md` — tiered architecture summaries that let AI agents understand your entire project structure from a single file.
-
-> Part of [Mikk](../../README.md) — the codebase nervous system for AI-assisted development.
+> Part of [Mikk](../../README.md) — live architectural context for your AI agent.
 
 ---
 
-## Installation
-
-```bash
-npm install @getmikk/ai-context
-# or
-bun add @getmikk/ai-context
-```
+## Context Builder
 
-**Peer dependencies:** `@getmikk/core`, `@getmikk/intent-engine`
+Given a task description, BFS-traces the dependency graph from matched seed functions and returns the most relevant context within a configurable token budget.
 
----
-
-## Quick Start
-
-### Context Queries
+### Usage
 
 ```typescript
 import { ContextBuilder, getProvider } from '@getmikk/ai-context'
-import { ContractReader, LockReader } from '@getmikk/core'
-
-const contract = await new ContractReader().read('./mikk.json')
-const lock = await new LockReader().read('./mikk.lock.json')
 
 const builder = new ContextBuilder(contract, lock)
-const context = builder.build({
-  task: 'Add rate limiting to the authentication endpoints',
-  tokenBudget: 8000,
-  maxHops: 3,
+
+const ctx = builder.build({
+  task: 'Add rate limiting to all API routes',
+  maxHops: 4,
+  tokenBudget: 6000,
+  focusModules: ['api-gateway'],
   includeCallGraph: true,
+  includeBodies: true,
+  projectRoot: '/path/to/project',
 })
 
-// Format for a specific AI provider
-const provider = getProvider('claude')
-const formatted = provider.formatContext(context)
-// Send `formatted` as part of your AI prompt
-```
-
-### Claude.md / AGENTS.md Generation
-
-```typescript
-import { ClaudeMdGenerator } from '@getmikk/ai-context'
-
-const generator = new ClaudeMdGenerator(contract, lock, /* tokenBudget */ 4000)
-const markdown = generator.generate()
+// Format for your AI client
+const formatter = getProvider('claude')   // XML tags
+// const formatter = getProvider('generic')  // plain text
+// const formatter = getProvider('compact')  // minimal tokens
 
-// Write to project root
-await writeFile('./claude.md', markdown)
-await writeFile('./AGENTS.md', markdown)
+const output = formatter.formatContext(ctx)
 ```
 
----
-
-## How Context Building Works
-
-The `ContextBuilder` uses a 6-step algorithm:
-
-```
-1. Resolve Seeds
-   └─ Parse task → extract keywords → match against lock file functions/modules
+### How context is built
 
-2. BFS Proximity Walk
-   └─ Walk the call graph outward from seed functions (up to maxHops)
+1. **Seed** — match task keywords against function names, module descriptions, and file paths
+2. **Walk** — BFS from seed nodes, following call graph edges outward up to `maxHops` depth
+3. **Score** — each function scored by: proximity to seed (depth penalty), keyword match bonus, entry-point bonus
+4. **Budget** — greedy knapsack: highest-scoring functions added until token budget is consumed
+5. **Format** — serialized with function bodies, params, return types, call graph, and file locations
 
-3. Score Functions
-   └─ Each function gets a relevance score:
-      • Proximity score (closer to seed = higher)
-      • Keyword match score (task keywords in function name)
-      • Entry-point bonus (exported functions score higher)
-
-4. Sort by Score
-   └─ Descending relevance
-
-5. Fill Token Budget
-   └─ Greedily add functions until budget is exhausted
-      (each function's token cost ≈ line count × 4)
-
-6. Group by Module
-   └─ Organize selected functions into module-level context
-```
+The result is surgical — agents get exactly the functions relevant to their task, not the entire codebase.
 
 ---
 
-## API Reference
+## claude.md / AGENTS.md Generator
 
-### ContextBuilder
+Generates `claude.md` and `AGENTS.md` automatically during `mikk init` and `mikk analyze`. Every piece of content is derived from the AST-parsed lock file — never hand-authored, never stale.
 
-The main entry point for building task-specific context.
-
-```typescript
-import { ContextBuilder } from '@getmikk/ai-context'
-
-const builder = new ContextBuilder(contract, lock)
-const context = builder.build(query)
-```
-
-**`ContextQuery`:**
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `task` | `string` | — | Natural-language description of the task |
-| `focusFiles` | `string[]` | `[]` | Specific files to prioritize |
-| `focusModules` | `string[]` | `[]` | Specific modules to prioritize |
-| `maxFunctions` | `number` | `50` | Maximum functions to include |
-| `maxHops` | `number` | `3` | BFS depth limit from seed functions |
-| `tokenBudget` | `number` | `8000` | Maximum estimated tokens |
-| `includeCallGraph` | `boolean` | `true` | Include `calls[]` and `calledBy[]` per function |
-
-**`AIContext` (returned):**
-
-```typescript
-type AIContext = {
-  project: string              // Project name from contract
-  modules: ContextModule[]     // Relevant modules with their functions
-  constraints: string[]        // Active architectural constraints
-  decisions: string[]          // Relevant ADRs
-  prompt: string               // Original task
-  meta: {
-    seedCount: number          // How many seed functions were found
-    totalFunctionsConsidered: number
-    selectedFunctions: number  // Functions that fit in the budget
-    estimatedTokens: number    // Approximate token count
-    keywords: string[]         // Extracted keywords from the task
-  }
-}
-```
-
-**`ContextModule`:**
-
-```typescript
-type ContextModule = {
-  id: string
-  name: string
-  description?: string
-  intent?: string              // Module's purpose from mikk.json
-  functions: ContextFunction[]
-  files: string[]
-}
-```
-
-**`ContextFunction`:**
-
-```typescript
-type ContextFunction = {
-  name: string
-  file: string
-  startLine: number
-  endLine: number
-  calls: string[]              // Functions this one calls
-  calledBy: string[]           // Functions that call this one
-  purpose?: string             // Inferred purpose
-  errorHandling?: string       // Error patterns detected
-  edgeCases?: string           // Edge cases noted
-}
-```
-
----
-
-### ClaudeMdGenerator
-
-Generates tiered markdown documentation files for AI agents.
+### Usage
 
 ```typescript
 import { ClaudeMdGenerator } from '@getmikk/ai-context'
 
-const generator = new ClaudeMdGenerator(contract, lock, tokenBudget)
-const markdown = generator.generate()
-```
-
-**Tiered output structure:**
-
-| Tier | Content | Budget |
-|------|---------|--------|
-| **Tier 1** | Project summary — name, module count, total functions, architecture overview | ~500 tokens |
-| **Tier 2** | Module details — each module's intent, public API, file list, key functions | ~300 tokens/module |
-| **Tier 3** | Constraints & decisions — all architectural rules and ADRs | Remaining budget |
-
-**All data is sourced from the AST-derived lock file** — no hallucinated descriptions. Module intents come from `mikk.json`, function lists and call graphs come from `mikk.lock.json`.
+const generator = new ClaudeMdGenerator(
+  contract,
+  lock,
+  12000,   // token budget
+  {        // from package.json
+    description: 'Multi-channel AI gateway',
+    scripts: { build: 'bun run build', test: 'vitest' },
+    dependencies: { ... },
+  },
+  projectRoot
+)
 
-**Example output:**
-
-```markdown
-# Project: my-app
-
-## Architecture Overview
-- **Modules:** 5
-- **Total Functions:** 87
-- **Total Files:** 23
-
-## Modules
-
-### auth
-**Intent:** Handle user authentication and session management
-**Public API:** `login`, `logout`, `validateToken`, `refreshSession`
-**Files:** auth/login.ts, auth/session.ts, auth/middleware.ts
-**Key Functions:**
-- `validateToken` (auth/middleware.ts:15-42) → calls: `decodeJWT`, `checkExpiry`
-- `login` (auth/login.ts:8-35) → calls: `validateCredentials`, `createSession`
-
-### payments
-...
-
-## Constraints
-- auth: no-import from payments
-- payments: must-use stripe-sdk
-
-## Decisions
-- ADR-001: Use JWT for stateless auth (2024-01-15)
-```
-
----
-
-### Providers
-
-Providers format the `AIContext` object into a string optimized for a specific AI model.
-
-```typescript
-import { getProvider, ClaudeProvider, GenericProvider } from '@getmikk/ai-context'
-
-// Factory
-const provider = getProvider('claude')   // or 'generic'
-
-// Format context for the provider
-const formatted = provider.formatContext(context)
-```
-
-#### ClaudeProvider
-
-Formats with structured XML tags optimized for Anthropic Claude:
-
-```xml
-<architecture>
-  <module name="auth" intent="Handle authentication">
-    <function name="validateToken" file="auth/middleware.ts" lines="15-42">
-      <calls>decodeJWT, checkExpiry</calls>
-      <calledBy>authMiddleware</calledBy>
-    </function>
-  </module>
-</architecture>
-<constraints>
-  auth: no-import from payments
-</constraints>
-```
-
-#### GenericProvider
-
-Clean plain-text format for any AI model:
-
-```
-## Module: auth
-Intent: Handle authentication
-
-### validateToken (auth/middleware.ts:15-42)
-Calls: decodeJWT, checkExpiry
-Called by: authMiddleware
+const content = generator.generate()
+// Write to claude.md and AGENTS.md
 ```
 
----
-
-## Usage Examples
-
-### "What breaks if I change this file?"
+### Tiered output
 
-```typescript
-const context = builder.build({
-  task: `Impact analysis for changes to src/auth/login.ts`,
-  focusFiles: ['src/auth/login.ts'],
-  maxHops: 5,
-  tokenBudget: 4000,
-})
-// Returns all functions transitively affected by login.ts
-```
-
-### "Get context for adding a feature"
-
-```typescript
-const context = builder.build({
-  task: 'Add two-factor authentication to the login flow',
-  focusModules: ['auth'],
-  tokenBudget: 12000,
-  includeCallGraph: true,
-})
-// Returns auth module functions + related cross-module calls
-```
+Content is generated in priority order until the token budget (default 12,000) is consumed:
 
-### "Focused context for a specific module"
+| Tier | Content | Always included? |
+|------|---------|-----------------|
+| 1 | Project summary — name, description, module list with function counts, stats, critical constraints | Yes |
+| — | Tech stack — detected frameworks, runtime, build tool | If detectable |
+| — | Build/test/run commands — from package.json scripts | If present |
+| 2 | Per-module detail — exported API, key functions, internal call summary (~300 tokens/module) | Until budget |
+| — | Context files — discovered schemas, configs, data models | If budget allows |
+| — | Import graph — cross-file import relationships per module | If budget allows |
+| — | HTTP routes — detected routes with method, path, handler | If budget allows |
+| 3 | Constraints — all declared constraint rules | If budget allows |
+| — | ADR decisions — architectural decisions with reasons | If budget allows |
 
-```typescript
-const context = builder.build({
-  task: 'Refactor the payment processing pipeline',
-  focusModules: ['payments'],
-  maxFunctions: 30,
-  tokenBudget: 6000,
-})
-```
-
----
-
-## Types
-
-```typescript
-import type {
-  AIContext,
-  ContextModule,
-  ContextFunction,
-  ContextQuery,
-  ContextProvider,
-} from '@getmikk/ai-context'
-```
-
----
+Modules with zero functions are skipped entirely.
 
-## License
+### Token estimation
 
-[Apache-2.0](../../LICENSE)
+Uses a ~4 chars/token approximation. The generator stops adding sections the moment adding the next section would exceed the budget, so the output always fits within the specified window.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@getmikk/ai-context",
-    "version": "1.7.1",
+    "version": "1.8.0",
     "license": "Apache-2.0",
     "repository": {
         "type": "git",
@@ -21,8 +21,8 @@
         "dev": "tsc --watch"
     },
     "dependencies": {
-        "@getmikk/core": "^1.7.1",
-        "@getmikk/intent-engine": "^1.7.1"
+        "@getmikk/core": "^1.8.0",
+        "@getmikk/intent-engine": "^1.8.0"
     },
     "devDependencies": {
         "typescript": "^5.7.0",

package/src/claude-md-generator.ts

@@ -46,26 +46,26 @@ export class ClaudeMdGenerator {
         const sections: string[] = []
         let usedTokens = 0
 
-        // ── Tier 1: Summary (always included) ──────────────────────
+        // --- Tier 1: Summary (always included) ----------------------
         const summary = this.generateSummary()
         sections.push(summary)
         usedTokens += estimateTokens(summary)
 
-        // ── Tech stack & conventions (always included if detectable) ──
+        // --- Tech stack & conventions (always included if detectable) ---
         const techSection = this.generateTechStackSection()
         if (techSection) {
             sections.push(techSection)
             usedTokens += estimateTokens(techSection)
         }
 
-        // ── Build / test / run commands ─────────────────────────────
+        // --- Build / test / run commands -----------------------------
         const commandsSection = this.generateCommandsSection()
         if (commandsSection) {
             sections.push(commandsSection)
             usedTokens += estimateTokens(commandsSection)
         }
 
-        // ── Tier 2: Module details (if budget allows) ──────────────
+        // --- Tier 2: Module details (if budget allows) --------------
         // Skip modules with zero functions — they waste AI tokens
         const modules = this.getModulesSortedByDependencyOrder()
             .filter(m => {
@@ -78,14 +78,16 @@ export class ClaudeMdGenerator {
             const moduleSection = this.generateModuleSection(module.id)
             const tokens = estimateTokens(moduleSection)
             if (usedTokens + tokens > this.tokenBudget) {
-                sections.push('\n> Full details available in `mikk.lock.json`\n')
+                sections.push('\n  <!-- Full details truncated due to context budget -->\n')
                 break
             }
             sections.push(moduleSection)
             usedTokens += tokens
         }
 
-        // ── Context files: schemas, data models, config ─────────
+        sections.push('</modules>\n')
+
+        // --- Context files: schemas, data models, config ---------
         const contextSection = this.generateContextFilesSection()
         if (contextSection) {
             const ctxTokens = estimateTokens(contextSection)
@@ -95,7 +97,7 @@ export class ClaudeMdGenerator {
             }
         }
 
-        // ── File import graph per module ────────────────────────────
+        // --- File import graph per module ----------------------------
         const importSection = this.generateImportGraphSection()
         if (importSection) {
             const impTokens = estimateTokens(importSection)
@@ -105,7 +107,7 @@ export class ClaudeMdGenerator {
             }
         }
 
-        // ── HTTP Routes (Express + Next.js) ─────────────────────────
+        // --- HTTP Routes (Express + Next.js) -------------------------
         const routesSection = this.generateRoutesSection()
         if (routesSection) {
             const routeTokens = estimateTokens(routesSection)
@@ -115,7 +117,7 @@ export class ClaudeMdGenerator {
             }
         }
 
-        // ── Tier 3: Constraints & decisions ────────────────────────
+        // --- Tier 3: Constraints & decisions ------------------------
         const constraintsSection = this.generateConstraintsSection()
         const constraintTokens = estimateTokens(constraintsSection)
         if (usedTokens + constraintTokens <= this.tokenBudget) {
@@ -141,15 +143,13 @@ export class ClaudeMdGenerator {
         const functionCount = Object.keys(this.lock.functions).length
         const fileCount = Object.keys(this.lock.files).length
 
-        lines.push(`# ${this.contract.project.name} — Architecture Overview`)
-        lines.push('')
+        lines.push('<repository_context>')
+        lines.push(`  <name>${this.contract.project.name}</name>`)
 
         // Project description: prefer contract, fall back to package.json
         const description = this.contract.project.description || this.meta.description
         if (description) {
-            lines.push('## What this project does')
-            lines.push(description)
-            lines.push('')
+            lines.push(`  <description>${description}</description>`)
         }
 
         // Only list modules that have functions (skip empty ones)
@@ -159,32 +159,26 @@ export class ClaudeMdGenerator {
             return fnCount > 0
         })
 
-        lines.push('## Modules')
-        for (const module of nonEmptyModules) {
-            const fnCount = Object.values(this.lock.functions)
-                .filter(f => f.moduleId === module.id).length
-            const desc = module.intent || module.description || ''
-            // Strip leading "N functions — " from auto-generated descriptions to avoid double-counting
-            const cleanDesc = desc.replace(/^\d+ functions\s*—\s*/, '')
-            const descStr = cleanDesc ? ` — ${cleanDesc}` : ''
-            lines.push(`- **${module.name}** (\`${module.id}\`): ${fnCount} functions${descStr}`)
-        }
-        lines.push('')
-
-        lines.push(`## Stats`)
-        lines.push(`- ${fileCount} files, ${functionCount} functions, ${nonEmptyModules.length} modules`)
-        lines.push(`- Language: ${this.contract.project.language}`)
-        lines.push('')
+        lines.push(`  <stats>`)
+        lines.push(`    <files>${fileCount}</files>`)
+        lines.push(`    <functions>${functionCount}</functions>`)
+        lines.push(`    <modules>${nonEmptyModules.length}</modules>`)
+        lines.push(`    <language>${this.contract.project.language}</language>`)
+        lines.push(`  </stats>`)
 
         // Critical constraints summary
         if (this.contract.declared.constraints.length > 0) {
-            lines.push('## Critical Constraints')
+            lines.push('  <critical_constraints>')
             for (const c of this.contract.declared.constraints) {
-                lines.push(`- ${c}`)
+                lines.push(`    <constraint>${c}</constraint>`)
             }
-            lines.push('')
+            lines.push('  </critical_constraints>')
         }
 
+        lines.push('</repository_context>')
+        lines.push('')
+        lines.push('<modules>')
+
         return lines.join('\n')
     }
 
@@ -198,23 +192,22 @@ export class ClaudeMdGenerator {
         const moduleFunctions = Object.values(this.lock.functions)
             .filter(f => f.moduleId === moduleId)
 
-        lines.push(`## ${module.name} module`)
+        lines.push(`  <module id="${moduleId}">`)
+        lines.push(`    <name>${module.name}</name>`)
 
         // Location — collapse to common prefix when many paths share a root
         if (module.paths.length > 0) {
             const collapsed = this.collapsePaths(module.paths)
-            lines.push(`**Location:** ${collapsed}`)
+            lines.push(`    <location>${collapsed}</location>`)
         }
 
         // Intent
         if (module.intent) {
-            lines.push(`**Purpose:** ${module.intent}`)
+            lines.push(`    <purpose>${module.intent}</purpose>`)
         } else if (module.description) {
-            lines.push(`**Purpose:** ${module.description}`)
+            lines.push(`    <purpose>${module.description}</purpose>`)
         }
 
-        lines.push('')
-
         // Entry points: functions with no calledBy (likely public API surface)
         const entryPoints = moduleFunctions
             .filter(fn => fn.calledBy.length === 0)
@@ -222,13 +215,13 @@ export class ClaudeMdGenerator {
             .slice(0, 5)
 
         if (entryPoints.length > 0) {
-            lines.push('**Entry points:**')
+            lines.push('    <entry_points>')
             for (const fn of entryPoints) {
                 const sig = this.formatSignature(fn)
-                const purpose = fn.purpose ? ` — ${this.oneLine(fn.purpose)}` : ''
-                lines.push(`  - \`${sig}\`${purpose}`)
+                const purpose = fn.purpose ? `${this.oneLine(fn.purpose)}` : ''
+                lines.push(`      <function signature="${sig.replace(/"/g, '&quot;')}" purpose="${purpose.replace(/"/g, '&quot;')}" />`)
             }
-            lines.push('')
+            lines.push('    </entry_points>')
         }
 
         // Key functions: top 5 by calledBy count (most depended upon)
@@ -238,13 +231,13 @@ export class ClaudeMdGenerator {
             .slice(0, 5)
 
         if (keyFunctions.length > 0) {
-            lines.push('**Key internal functions:**')
+            lines.push('    <key_internal_functions>')
             for (const fn of keyFunctions) {
                 const callerCount = fn.calledBy.length
-                const purpose = fn.purpose ? ` — ${this.oneLine(fn.purpose)}` : ''
-                lines.push(`  - \`${fn.name}\` (called by ${callerCount})${purpose}`)
+                const purpose = fn.purpose ? `${this.oneLine(fn.purpose)}` : ''
+                lines.push(`      <function name="${fn.name.replace(/"/g, '&quot;')}" callers="${callerCount}" purpose="${purpose.replace(/"/g, '&quot;')}" />`)
             }
-            lines.push('')
+            lines.push('    </key_internal_functions>')
         }
 
         // Dependencies: other modules this module imports from
@@ -263,8 +256,7 @@ export class ClaudeMdGenerator {
                 const mod = this.contract.declared.modules.find(m => m.id === id)
                 return mod?.name || id
             })
-            lines.push(`**Depends on:** ${depNames.join(', ')}`)
-            lines.push('')
+            lines.push(`    <depends_on>${depNames.join(', ')}</depends_on>`)
         }
 
         // Module-specific constraints
@@ -273,13 +265,14 @@ export class ClaudeMdGenerator {
             c.toLowerCase().includes(module.name.toLowerCase())
         )
         if (moduleConstraints.length > 0) {
-            lines.push('**Constraints:**')
+            lines.push('    <module_constraints>')
             for (const c of moduleConstraints) {
-                lines.push(`  - ${c}`)
+                lines.push(`      <constraint>${c}</constraint>`)
             }
-            lines.push('')
+            lines.push('    </module_constraints>')
         }
 
+        lines.push(`  </module>`)
         return lines.join('\n')
     }
 
@@ -520,9 +513,11 @@ export class ClaudeMdGenerator {
         if (detected.length === 0) return null
 
         const lines: string[] = []
-        lines.push('## Tech Stack')
-        lines.push(detected.join(' · '))
-        lines.push('')
+        lines.push('<tech_stack>')
+        for (const d of detected) {
+            lines.push(`  <technology>${d}</technology>`)
+        }
+        lines.push('</tech_stack>')
         return lines.join('\n')
     }
 
@@ -554,12 +549,14 @@ export class ClaudeMdGenerator {
         if (useful.length === 0) return null
 
         const lines: string[] = []
-        lines.push('## Commands')
+        lines.push('<commands>')
         for (const [key, cmd] of useful) {
-            lines.push(`- \`${pm} ${key}\` \u2014 \`${cmd}\``)
+            lines.push(`  <command>`)
+            lines.push(`    <run>${pm} ${key}</run>`)
+            lines.push(`    <executes>${cmd.replace(/"/g, '&quot;')}</executes>`)
+            lines.push(`  </command>`)
         }
-
-        lines.push('')
+        lines.push('</commands>')
         return lines.join('\n')
     }
 

package/tests/claude-md.test.ts

@@ -64,8 +64,8 @@ describe('ClaudeMdGenerator', () => {
     test('generates valid markdown', () => {
         const gen = new ClaudeMdGenerator(mockContract, mockLock)
         const md = gen.generate()
-        expect(md).toContain('# TestProject')
-        expect(md).toContain('Architecture Overview')
+        expect(md).toContain('<name>TestProject</name>')
+        expect(md).toContain('<repository_context>')
     })
 
     test('includes project description', () => {
@@ -77,8 +77,8 @@ describe('ClaudeMdGenerator', () => {
     test('includes module sections', () => {
         const gen = new ClaudeMdGenerator(mockContract, mockLock)
         const md = gen.generate()
-        expect(md).toContain('Authentication module')
-        expect(md).toContain('API module')
+        expect(md).toContain('<module id="auth">')
+        expect(md).toContain('<module id="api">')
     })
 
     test('includes function names', () => {
@@ -105,7 +105,7 @@ describe('ClaudeMdGenerator', () => {
         const gen = new ClaudeMdGenerator(mockContract, mockLock)
         const md = gen.generate()
         // API depends on Auth (handleLogin calls verifyToken)
-        expect(md).toContain('Depends on')
+        expect(md).toContain('<depends_on>Authentication</depends_on>')
     })
 
     test('respects token budget', () => {
@@ -119,8 +119,8 @@ describe('ClaudeMdGenerator', () => {
     test('includes stats', () => {
         const gen = new ClaudeMdGenerator(mockContract, mockLock)
         const md = gen.generate()
-        expect(md).toContain('3 functions')
-        expect(md).toContain('2 modules')
+        expect(md).toContain('<functions>3</functions>')
+        expect(md).toContain('<modules>2</modules>')
     })
 
     test('shows purpose when available', () => {
@@ -132,6 +132,86 @@ describe('ClaudeMdGenerator', () => {
     test('shows calledBy count for key functions', () => {
         const gen = new ClaudeMdGenerator(mockContract, mockLock)
         const md = gen.generate()
-        expect(md).toContain('called by 1')
+        expect(md).toContain('callers="1"')
+    })
+
+    describe('Edge Cases and Fault Tolerance', () => {
+        test('handles completely empty lock and contract without throwing', () => {
+            const emptyContract: MikkContract = {
+                version: '1',
+                project: { name: 'Empty', language: 'TS', description: '', entryPoints: [] },
+                declared: { modules: [], constraints: [], decisions: [] },
+                overwrite: { mode: 'never', requireConfirmation: false }
+            }
+            const emptyLock: MikkLock = {
+                version: '1', generatedAt: new Date().toISOString(), generatorVersion: '1', projectRoot: '', syncState: { status: 'clean', lastSyncAt: '', lockHash: '', contractHash: '' },
+                files: {}, functions: {}, classes: {}, modules: {}, graph: { nodes: 0, edges: 0, rootHash: '' }
+            }
+            const gen = new ClaudeMdGenerator(emptyContract, emptyLock)
+            const md = gen.generate()
+            expect(md).toContain('<name>Empty</name>')
+            expect(md).toContain('<modules>0</modules>')
+            expect(md).toContain('<functions>0</functions>')
+        })
+
+        test('handles missing optional fields gracefully', () => {
+            const partialContract: MikkContract = {
+                version: '1',
+                project: { name: 'Partial', language: 'TS', description: '', entryPoints: [] },
+                declared: { modules: [{ id: 'core', name: 'Core', description: '', paths: [] }], constraints: [], decisions: [] },
+                overwrite: { mode: 'never', requireConfirmation: false }
+            }
+            const partialLock: MikkLock = {
+                version: '1', generatedAt: new Date().toISOString(), generatorVersion: '1', projectRoot: '', syncState: { status: 'clean', lastSyncAt: '', lockHash: '', contractHash: '' },
+                files: {},
+                functions: {
+                    'f1': { id: 'f1', name: 'func', file: 'a.ts', startLine: 1, endLine: 2, hash: 'h', calls: [], calledBy: [], moduleId: 'core' } 
+                },
+                classes: {},
+                modules: {
+                    'core': { id: 'core', files: [], hash: 'h', fragmentPath: 'p' }
+                },
+                graph: { nodes: 0, edges: 0, rootHash: '' }
+            }
+            const gen = new ClaudeMdGenerator(partialContract, partialLock)
+            const md = gen.generate()
+            expect(md).toContain('<name>Core</name>')
+            expect(md).toContain('func')
+        })
+
+        test('handles circular dependencies between functions gracefully', () => {
+            const circLock: MikkLock = {
+                ...mockLock,
+                functions: {
+                    'fn:a': { id: 'fn:a', name: 'A', file: 'a.ts', startLine: 1, endLine: 2, hash: 'h', calls: ['fn:b'], calledBy: ['fn:b'], moduleId: 'auth' },
+                    'fn:b': { id: 'fn:b', name: 'B', file: 'b.ts', startLine: 1, endLine: 2, hash: 'h', calls: ['fn:a'], calledBy: ['fn:a'], moduleId: 'auth' },
+                }
+            }
+            const gen = new ClaudeMdGenerator(mockContract, circLock)
+            const md = gen.generate()
+            expect(md).toContain('A')
+            expect(md).toContain('B')
+            expect(md.length).toBeLessThan(10000)
+        })
+
+        test('truncates extremely strict token budgets without losing core layout', () => {
+            const gen = new ClaudeMdGenerator(mockContract, mockLock, 50) 
+            const md = gen.generate()
+            expect(md).toContain('<repository_context>')
+            expect(md).not.toContain('Use JWT') 
+        })
+        
+        test('handles foreign or orphaned modules robustly', () => {
+            const orphanedLock: MikkLock = {
+                ...mockLock,
+                functions: {
+                    'fn:orphan': { id: 'fn:orphan', name: 'OrphanFn', file: 'o.ts', startLine: 1, endLine: 2, hash: 'h', calls: [], calledBy: [], moduleId: 'unknown-module' }
+                }
+            }
+            const gen = new ClaudeMdGenerator(mockContract, orphanedLock)
+            const md = gen.generate()
+            // Unknown module functions are typically skipped entirely. The generator should not crash.
+            expect(md).not.toContain('OrphanFn')
+        })
     })
 })