@getmikk/ai-context 1.3.2 → 1.5.1

package/package.json

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

package/src/claude-md-generator.ts

@@ -1,13 +1,21 @@
 import type { MikkContract, MikkLock, MikkLockFunction } from '@getmikk/core'
 
-/** Default token budget for claude.md — prevents bloating the context window */
-const DEFAULT_TOKEN_BUDGET = 6000
+/** Default token budget for claude.md — generous but still bounded */
+const DEFAULT_TOKEN_BUDGET = 12000
 
 /** Rough token estimation: ~4 chars per token */
 function estimateTokens(text: string): number {
     return Math.ceil(text.length / 4)
 }
 
+/** Metadata from package.json that enriches the AI context */
+export interface ProjectMeta {
+    description?: string
+    scripts?: Record<string, string>
+    dependencies?: Record<string, string>
+    devDependencies?: Record<string, string>
+}
+
 /**
  * ClaudeMdGenerator — generates an always-accurate `claude.md` and `AGENTS.md`
  * from the lock file and contract. Every function name, file path, and module
@@ -19,11 +27,16 @@ function estimateTokens(text: string): number {
  *  Tier 3: Recent changes (~50 tokens/change) — last section added
  */
 export class ClaudeMdGenerator {
+    private meta: ProjectMeta
+
     constructor(
         private contract: MikkContract,
         private lock: MikkLock,
-        private tokenBudget: number = DEFAULT_TOKEN_BUDGET
-    ) { }
+        private tokenBudget: number = DEFAULT_TOKEN_BUDGET,
+        meta?: ProjectMeta
+    ) {
+        this.meta = meta || {}
+    }
 
     /** Generate the full claude.md content */
     generate(): string {
@@ -35,8 +48,29 @@ export class ClaudeMdGenerator {
         sections.push(summary)
         usedTokens += estimateTokens(summary)
 
+        // ── Tech stack & conventions (always included if detectable) ──
+        const techSection = this.generateTechStackSection()
+        if (techSection) {
+            sections.push(techSection)
+            usedTokens += estimateTokens(techSection)
+        }
+
+        // ── Build / test / run commands ─────────────────────────────
+        const commandsSection = this.generateCommandsSection()
+        if (commandsSection) {
+            sections.push(commandsSection)
+            usedTokens += estimateTokens(commandsSection)
+        }
+
         // ── Tier 2: Module details (if budget allows) ──────────────
+        // Skip modules with zero functions — they waste AI tokens
         const modules = this.getModulesSortedByDependencyOrder()
+            .filter(m => {
+                const fnCount = Object.values(this.lock.functions)
+                    .filter(f => f.moduleId === m.id).length
+                return fnCount > 0
+            })
+
         for (const module of modules) {
             const moduleSection = this.generateModuleSection(module.id)
             const tokens = estimateTokens(moduleSection)
@@ -48,6 +82,36 @@ export class ClaudeMdGenerator {
             usedTokens += tokens
         }
 
+        // ── Context files: schemas, data models, config ─────────
+        const contextSection = this.generateContextFilesSection()
+        if (contextSection) {
+            const ctxTokens = estimateTokens(contextSection)
+            if (usedTokens + ctxTokens <= this.tokenBudget) {
+                sections.push(contextSection)
+                usedTokens += ctxTokens
+            }
+        }
+
+        // ── File import graph per module ────────────────────────────
+        const importSection = this.generateImportGraphSection()
+        if (importSection) {
+            const impTokens = estimateTokens(importSection)
+            if (usedTokens + impTokens <= this.tokenBudget) {
+                sections.push(importSection)
+                usedTokens += impTokens
+            }
+        }
+
+        // ── HTTP Routes (Express + Next.js) ─────────────────────────
+        const routesSection = this.generateRoutesSection()
+        if (routesSection) {
+            const routeTokens = estimateTokens(routesSection)
+            if (usedTokens + routeTokens <= this.tokenBudget) {
+                sections.push(routesSection)
+                usedTokens += routeTokens
+            }
+        }
+
         // ── Tier 3: Constraints & decisions ────────────────────────
         const constraintsSection = this.generateConstraintsSection()
         const constraintTokens = estimateTokens(constraintsSection)
@@ -77,24 +141,35 @@ export class ClaudeMdGenerator {
         lines.push(`# ${this.contract.project.name} — Architecture Overview`)
         lines.push('')
 
-        if (this.contract.project.description) {
+        // 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(this.contract.project.description)
+            lines.push(description)
             lines.push('')
         }
 
+        // Only list modules that have functions (skip empty ones)
+        const nonEmptyModules = this.contract.declared.modules.filter(m => {
+            const fnCount = Object.values(this.lock.functions)
+                .filter(f => f.moduleId === m.id).length
+            return fnCount > 0
+        })
+
         lines.push('## Modules')
-        for (const module of this.contract.declared.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 || ''
-            const descStr = desc ? ` — ${desc}` : ''
+            // 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, ${moduleCount} modules`)
+        lines.push(`- ${fileCount} files, ${functionCount} functions, ${nonEmptyModules.length} modules`)
         lines.push(`- Language: ${this.contract.project.language}`)
         lines.push('')
 
@@ -122,9 +197,10 @@ export class ClaudeMdGenerator {
 
         lines.push(`## ${module.name} module`)
 
-        // Location
+        // Location — collapse to common prefix when many paths share a root
         if (module.paths.length > 0) {
-            lines.push(`**Location:** ${module.paths.join(', ')}`)
+            const collapsed = this.collapsePaths(module.paths)
+            lines.push(`**Location:** ${collapsed}`)
         }
 
         // Intent
@@ -146,7 +222,7 @@ export class ClaudeMdGenerator {
             lines.push('**Entry points:**')
             for (const fn of entryPoints) {
                 const sig = this.formatSignature(fn)
-                const purpose = fn.purpose ? ` — ${fn.purpose}` : ''
+                const purpose = fn.purpose ? ` — ${this.oneLine(fn.purpose)}` : ''
                 lines.push(`  - \`${sig}\`${purpose}`)
             }
             lines.push('')
@@ -162,7 +238,7 @@ export class ClaudeMdGenerator {
             lines.push('**Key internal functions:**')
             for (const fn of keyFunctions) {
                 const callerCount = fn.calledBy.length
-                const purpose = fn.purpose ? ` — ${fn.purpose}` : ''
+                const purpose = fn.purpose ? ` — ${this.oneLine(fn.purpose)}` : ''
                 lines.push(`  - \`${fn.name}\` (called by ${callerCount})${purpose}`)
             }
             lines.push('')
@@ -228,11 +304,410 @@ export class ClaudeMdGenerator {
         return lines.join('\n')
     }
 
+    // ── Context Files Section ──────────────────────────────────────
+
+    /** Generate a section with discovered schema/config files inlined */
+    private generateContextFilesSection(): string | null {
+        const ctxFiles = this.lock.contextFiles
+        if (!ctxFiles || ctxFiles.length === 0) return null
+
+        const lines: string[] = []
+        lines.push('## Data Models & Schemas')
+        lines.push('')
+        lines.push('These files define the project\'s data structures, schemas, and configuration.')
+        lines.push('They are auto-discovered and included verbatim from the source.')
+        lines.push('')
+
+        for (const cf of ctxFiles) {
+            const ext = cf.path.split('.').pop() || 'txt'
+            const lang = this.extToLang(ext)
+            lines.push(`### \`${cf.path}\` (${cf.type})`)
+            lines.push('')
+            lines.push('```' + lang)
+            // Trim content to avoid blowing up the token budget
+            const maxChars = 8000 // ~2000 tokens per file
+            if (cf.content.length > maxChars) {
+                lines.push(cf.content.slice(0, maxChars))
+                lines.push(`// ... truncated (${cf.size} bytes total)`)
+            } else {
+                lines.push(cf.content.trimEnd())
+            }
+            lines.push('```')
+            lines.push('')
+        }
+
+        return lines.join('\n')
+    }
+
+    /** Map file extensions to Markdown code fence languages */
+    private extToLang(ext: string): string {
+        const map: Record<string, string> = {
+            ts: 'typescript', js: 'javascript', tsx: 'tsx', jsx: 'jsx',
+            mjs: 'javascript', cjs: 'javascript',
+            py: 'python', go: 'go', rs: 'rust', rb: 'ruby',
+            java: 'java', kt: 'kotlin', cs: 'csharp', swift: 'swift',
+            dart: 'dart', ex: 'elixir', exs: 'elixir', php: 'php',
+            prisma: 'prisma', graphql: 'graphql', gql: 'graphql',
+            sql: 'sql', proto: 'protobuf', yaml: 'yaml', yml: 'yaml',
+            json: 'json', toml: 'toml', xml: 'xml',
+            css: 'css', scss: 'scss', html: 'html',
+            svelte: 'svelte', vue: 'vue',
+            md: 'markdown', sh: 'bash', bash: 'bash', zsh: 'bash',
+            dockerfile: 'dockerfile', tf: 'hcl',
+            avsc: 'json', thrift: 'thrift',
+        }
+        return map[ext.toLowerCase()] || ext
+    }
+
+    // ── Routes Section ──────────────────────────────────────────
+
+    /** Generate a section with detected HTTP route registrations + Next.js filesystem routes */
+    private generateRoutesSection(): string | null {
+        const expressRoutes = this.lock.routes || []
+        const nextRoutes = this.detectNextJsRoutes()
+        if (expressRoutes.length === 0 && nextRoutes.length === 0) return null
+
+        const lines: string[] = []
+        lines.push('## HTTP Routes')
+        lines.push('')
+
+        // Next.js App Router routes (detected from file paths)
+        if (nextRoutes.length > 0) {
+            lines.push('### API Routes (Next.js App Router)')
+            for (const r of nextRoutes) {
+                const methods = r.methods.length > 0 ? r.methods.join(', ') : 'handler'
+                lines.push(`- **${methods}** \`${r.urlPath}\` *(${r.file})*`)
+            }
+            lines.push('')
+        }
+
+        // Express/Koa/Hono routes
+        if (expressRoutes.length > 0) {
+            if (nextRoutes.length > 0) lines.push('### Server Routes')
+            for (const r of expressRoutes) {
+                const mw = r.middlewares.length > 0 ? ` → [${r.middlewares.join(', ')}]` : ''
+                lines.push(`- **${r.method}** \`${r.path}\` → \`${r.handler}\`${mw} *(${r.file}:${r.line})*`)
+            }
+            lines.push('')
+        }
+
+        return lines.join('\n')
+    }
+
+    // ── Tech Stack Section ──────────────────────────────────────
+
+    /** Detect technology stack from dependencies and config */
+    private generateTechStackSection(): string | null {
+        const deps = { ...this.meta.dependencies, ...this.meta.devDependencies }
+        if (Object.keys(deps).length === 0) return null
+
+        const detected: string[] = []
+
+        // Language / Runtime
+        const lang = this.contract.project.language
+        if (lang && lang !== 'typescript' && lang !== 'javascript') {
+            detected.push(lang.charAt(0).toUpperCase() + lang.slice(1))
+        }
+
+        // Frameworks — JS/TS
+        if (deps['next']) detected.push(`Next.js ${deps['next'].replace(/^\^|~/, '')}`)
+        else if (deps['nuxt']) detected.push(`Nuxt ${deps['nuxt'].replace(/^\^|~/, '')}`)
+        else if (deps['@sveltejs/kit']) detected.push('SvelteKit')
+        else if (deps['@remix-run/react'] || deps['@remix-run/node']) detected.push('Remix')
+        else if (deps['astro']) detected.push('Astro')
+        else if (deps['gatsby']) detected.push('Gatsby')
+        else if (deps['express']) detected.push('Express')
+        else if (deps['fastify']) detected.push('Fastify')
+        else if (deps['hono']) detected.push('Hono')
+        else if (deps['koa']) detected.push('Koa')
+        else if (deps['nestjs'] || deps['@nestjs/core']) detected.push('NestJS')
+        if (deps['react']) detected.push('React')
+        if (deps['vue']) detected.push('Vue')
+        if (deps['svelte']) detected.push('Svelte')
+        if (deps['solid-js']) detected.push('SolidJS')
+        if (deps['angular'] || deps['@angular/core']) detected.push('Angular')
+
+        // Mobile / Desktop
+        if (deps['react-native']) detected.push('React Native')
+        if (deps['expo']) detected.push('Expo')
+        if (deps['@capacitor/core']) detected.push('Capacitor')
+        if (deps['electron']) detected.push('Electron')
+        if (deps['tauri'] || deps['@tauri-apps/api']) detected.push('Tauri')
+
+        // Database / ORM
+        if (deps['prisma'] || deps['@prisma/client']) detected.push('Prisma ORM')
+        else if (deps['drizzle-orm']) detected.push('Drizzle ORM')
+        else if (deps['typeorm']) detected.push('TypeORM')
+        else if (deps['mongoose']) detected.push('Mongoose')
+        else if (deps['sequelize']) detected.push('Sequelize')
+        else if (deps['knex']) detected.push('Knex')
+        else if (deps['pg'] || deps['mysql2'] || deps['better-sqlite3']) detected.push('SQL client')
+        if (deps['redis'] || deps['ioredis']) detected.push('Redis')
+
+        // Auth
+        if (deps['next-auth'] || deps['@auth/core']) detected.push('NextAuth')
+        else if (deps['passport']) detected.push('Passport.js')
+        else if (deps['clerk'] || deps['@clerk/nextjs']) detected.push('Clerk')
+        else if (deps['lucia'] || deps['lucia-auth']) detected.push('Lucia')
+
+        // Styling
+        if (deps['tailwindcss']) detected.push('Tailwind CSS')
+        if (deps['radix-ui'] || deps['@radix-ui/react-dialog'] || deps['@radix-ui/react-slot']) detected.push('Radix UI')
+        if (deps['shadcn'] || deps['shadcn-ui']) detected.push('shadcn/ui')
+        if (deps['styled-components']) detected.push('styled-components')
+        if (deps['@emotion/react']) detected.push('Emotion')
+
+        // State / Data
+        if (deps['@tanstack/react-query']) detected.push('TanStack Query')
+        if (deps['zustand']) detected.push('Zustand')
+        if (deps['jotai']) detected.push('Jotai')
+        if (deps['@reduxjs/toolkit'] || deps['redux']) detected.push('Redux')
+        if (deps['zod']) detected.push('Zod validation')
+        if (deps['@trpc/server'] || deps['@trpc/client']) detected.push('tRPC')
+        if (deps['graphql'] || deps['@apollo/client']) detected.push('GraphQL')
+
+        // Content / Docs
+        if (deps['fumadocs-core'] || deps['fumadocs-mdx']) detected.push('Fumadocs')
+        if (deps['next-mdx-remote'] || deps['@next/mdx']) detected.push('MDX')
+        if (deps['contentlayer'] || deps['contentlayer2']) detected.push('Contentlayer')
+
+        // Animation
+        if (deps['motion'] || deps['framer-motion']) detected.push('Motion')
+
+        // Analytics / Monitoring
+        if (deps['posthog-js'] || deps['@posthog/react']) detected.push('PostHog')
+        if (deps['@vercel/analytics']) detected.push('Vercel Analytics')
+        if (deps['@sentry/node'] || deps['@sentry/nextjs'] || deps['@sentry/browser']) detected.push('Sentry')
+
+        // URL state
+        if (deps['nuqs']) detected.push('nuqs')
+
+        // Messaging / Queue
+        if (deps['bullmq'] || deps['bull']) detected.push('BullMQ')
+        if (deps['amqplib']) detected.push('RabbitMQ')
+        if (deps['kafkajs']) detected.push('Kafka')
+
+        // Cloud / Infra
+        if (deps['aws-sdk'] || deps['@aws-sdk/client-s3']) detected.push('AWS SDK')
+        if (deps['@google-cloud/storage']) detected.push('Google Cloud')
+        if (deps['firebase'] || deps['firebase-admin']) detected.push('Firebase')
+        if (deps['@supabase/supabase-js']) detected.push('Supabase')
+        if (deps['convex']) detected.push('Convex')
+
+        // Testing
+        if (deps['jest']) detected.push('Jest')
+        else if (deps['vitest']) detected.push('Vitest')
+        if (deps['playwright'] || deps['@playwright/test']) detected.push('Playwright')
+        if (deps['cypress']) detected.push('Cypress')
+        if (deps['@testing-library/react']) detected.push('Testing Library')
+
+        // Build
+        if (deps['turbo'] || deps['turbo-json']) detected.push('Turborepo')
+        if (deps['nx']) detected.push('Nx')
+        if (deps['webpack']) detected.push('Webpack')
+        if (deps['vite']) detected.push('Vite')
+        if (deps['esbuild']) detected.push('esbuild')
+        if (deps['rollup']) detected.push('Rollup')
+
+        if (detected.length === 0) return null
+
+        const lines: string[] = []
+        lines.push('## Tech Stack')
+        lines.push(detected.join(' · '))
+        lines.push('')
+        return lines.join('\n')
+    }
+
+    // ── Commands Section ────────────────────────────────────────
+
+    /** Detect build/test/dev commands from package.json scripts */
+    private generateCommandsSection(): string | null {
+        const scripts = this.meta.scripts
+        if (!scripts || Object.keys(scripts).length === 0) return null
+
+        // Auto-detect package manager from lockfile hints in meta, or fall back to heuristic
+        let pm = 'npm run'
+        const deps = { ...this.meta.dependencies, ...this.meta.devDependencies }
+        // Heuristic: check for telltale signs in scripts values
+        const allScriptValues = Object.values(scripts).join(' ')
+        if (allScriptValues.includes('bun ') || deps['bun-types']) pm = 'bun run'
+        else if (allScriptValues.includes('pnpm ') || allScriptValues.includes('pnpm-')) pm = 'pnpm'
+        else if (allScriptValues.includes('yarn ')) pm = 'yarn'
+
+        const useful: [string, string][] = []
+        const interestingKeys = ['dev', 'build', 'start', 'test', 'lint', 'format', 'typecheck', 'check', 'e2e', 'storybook', 'db:push', 'db:migrate', 'db:seed', 'prisma:generate', 'generate']
+
+        for (const key of interestingKeys) {
+            if (scripts[key]) {
+                useful.push([key, scripts[key]])
+            }
+        }
+
+        if (useful.length === 0) return null
+
+        const lines: string[] = []
+        lines.push('## Commands')
+        for (const [key, cmd] of useful) {
+            lines.push(`- \`${pm} ${key}\` \u2014 \`${cmd}\``)
+        }
+
+        lines.push('')
+        return lines.join('\n')
+    }
+
+    // ── Next.js Route Detection ─────────────────────────────────
+
+    /** Detect Next.js App Router routes from file paths in the lock */
+    private detectNextJsRoutes(): { urlPath: string; methods: string[]; file: string }[] {
+        const routes: { urlPath: string; methods: string[]; file: string }[] = []
+        const allFiles = Object.keys(this.lock.files)
+
+        for (const filePath of allFiles) {
+            const normalised = filePath.replace(/\\/g, '/')
+
+            // App Router API routes: app/**/route.ts
+            const routeMatch = normalised.match(/^(?:src\/)?app\/(.+)\/route\.[jt]sx?$/)
+            if (routeMatch) {
+                const urlSegments = routeMatch[1]
+                    .replace(/\([\w-]+\)\/?/g, '')           // strip route groups (marketing)/
+                    .replace(/\[\.\.\.(\w+)\]/g, ':$1*')     // [...slug] → :slug*
+                    .replace(/\[(\w+)\]/g, ':$1')            // [id] → :id
+                const urlPath = `/${urlSegments}` || '/'
+
+                // Detect exported HTTP methods from functions AND generics
+                // (Next.js handlers can be `export async function GET` → fn: or `export const GET =` → const:)
+                const methods: string[] = []
+                const HTTP_VERBS = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS']
+                for (const [fnId, fn] of Object.entries(this.lock.functions)) {
+                    if (fn.file === filePath && fn.isExported && HTTP_VERBS.includes(fn.name)) {
+                        methods.push(fn.name)
+                    }
+                }
+                if (this.lock.generics) {
+                    for (const [gId, g] of Object.entries(this.lock.generics)) {
+                        // Direct match: this generic is in this file
+                        if (g.file === filePath && g.isExported && HTTP_VERBS.includes(g.name)) {
+                            if (!methods.includes(g.name)) methods.push(g.name)
+                        }
+                        // alsoIn match: deduped generics list the same verb in other files
+                        if (g.isExported && HTTP_VERBS.includes(g.name) && g.alsoIn?.includes(filePath)) {
+                            if (!methods.includes(g.name)) methods.push(g.name)
+                        }
+                    }
+                }
+
+                routes.push({ urlPath, methods, file: filePath })
+            }
+
+            // App Router pages: app/**/page.tsx (informational)
+            const pageMatch = normalised.match(/^(?:src\/)?app\/(.+)\/page\.[jt]sx?$/)
+            if (pageMatch) {
+                const urlSegments = pageMatch[1]
+                    .replace(/\([\w-]+\)\/?/g, '')           // strip route groups
+                    .replace(/\[\.\.\.(\w+)\]/g, ':$1*')
+                    .replace(/\[(\w+)\]/g, ':$1')
+                const urlPath = `/${urlSegments}` || '/'
+                routes.push({ urlPath, methods: ['PAGE'], file: filePath })
+            }
+        }
+
+        // Sort by URL path
+        return routes.sort((a, b) => a.urlPath.localeCompare(b.urlPath))
+    }
+
+    // ── Import Graph Section ──────────────────────────────────────
+
+    /** Generate a per-module file import map */
+    private generateImportGraphSection(): string | null {
+        const filesWithImports = Object.values(this.lock.files)
+            .filter(f => f.imports && f.imports.length > 0)
+        if (filesWithImports.length === 0) return null
+
+        const lines: string[] = []
+        lines.push('## File Import Graph')
+        lines.push('')
+        lines.push('Which files import which — useful for understanding data flow.')
+        lines.push('')
+
+        // Group by module
+        const byModule = new Map<string, typeof filesWithImports>()
+        for (const f of filesWithImports) {
+            const existing = byModule.get(f.moduleId) || []
+            existing.push(f)
+            byModule.set(f.moduleId, existing)
+        }
+
+        for (const [moduleId, files] of byModule) {
+            const mod = this.contract.declared.modules.find(m => m.id === moduleId)
+            const name = mod?.name || moduleId
+            lines.push(`### ${name}`)
+            for (const f of files) {
+                const imports = f.imports!.map(imp => `\`${imp}\``).join(', ')
+                lines.push(`- \`${f.path}\` → ${imports}`)
+            }
+            lines.push('')
+        }
+
+        return lines.join('\n')
+    }
+
     // ── Helpers ───────────────────────────────────────────────────
 
-    /** Format a function into a readable signature */
+    /** Collapse multi-line text to a single trimmed line */
+    private oneLine(text: string): string {
+        return text.replace(/\n/g, ' ').replace(/\s+/g, ' ').trim()
+    }
+
+    /** Format a function into a compact single-line signature */
     private formatSignature(fn: MikkLockFunction): string {
-        return `${fn.name}() [${fn.file}:${fn.startLine}]`
+        const asyncPrefix = fn.isAsync ? 'async ' : ''
+        const params = fn.params && fn.params.length > 0
+            ? fn.params.map(p => {
+                const opt = p.optional ? '?' : ''
+                // Use just name (skip destructured object types — they bloat multi-line)
+                const name = p.name.replace(/\n/g, ' ').replace(/\s+/g, ' ')
+                return `${name}${opt}`
+            }).join(', ')
+            : ''
+        return `${asyncPrefix}${fn.name}(${params}) [${fn.file}:${fn.startLine}]`
+    }
+
+    /**
+     * Collapse many paths into fewest glob patterns.
+     * e.g. ["src/features/portfolio/components/awards/**", "src/features/portfolio/components/bookmarks/**", ...]
+     * becomes "src/features/portfolio/**"
+     */
+    private collapsePaths(paths: string[]): string {
+        if (paths.length <= 2) return paths.join(', ')
+
+        // Split each path into segments (strip trailing **)
+        const stripped = paths.map(p => p.replace(/\/\*\*$/, ''))
+
+        // Try progressively shorter common prefixes
+        // Find the longest common directory prefix shared by majority of paths
+        const segments = stripped.map(p => p.split('/'))
+        let bestPrefix = ''
+        for (let depth = 1; depth <= (segments[0]?.length ?? 0); depth++) {
+            const prefix = segments[0].slice(0, depth).join('/')
+            const matching = stripped.filter(p => p === prefix || p.startsWith(prefix + '/'))
+            if (matching.length >= Math.ceil(paths.length * 0.6)) {
+                bestPrefix = prefix
+            }
+        }
+
+        if (bestPrefix) {
+            // Some paths outside the prefix
+            const outside = paths.filter(p => {
+                const s = p.replace(/\/\*\*$/, '')
+                return s !== bestPrefix && !s.startsWith(bestPrefix + '/')
+            })
+            if (outside.length === 0) {
+                return `${bestPrefix}/**`
+            }
+            return [`${bestPrefix}/**`, ...outside].join(', ')
+        }
+
+        return paths.join(', ')
     }
 
     /** Sort modules by inter-module dependency order (depended-on modules first) */

package/src/context-builder.ts

@@ -1,5 +1,7 @@
 import type { MikkContract, MikkLock, MikkLockFunction } from '@getmikk/core'
 import type { AIContext, ContextQuery, ContextModule, ContextFunction } from './types.js'
+import * as fs from 'node:fs'
+import * as path from 'node:path'
 
 // ---------------------------------------------------------------------------
 // Scoring weights — tune these to adjust what "relevant" means
@@ -301,6 +303,19 @@ export class ContextBuilder {
                 title: d.title,
                 reason: d.reason,
             })),
+            contextFiles: this.lock.contextFiles?.map(cf => ({
+                path: cf.path,
+                content: cf.content,
+                type: cf.type,
+            })),
+            routes: this.lock.routes?.map(r => ({
+                method: r.method,
+                path: r.path,
+                handler: r.handler,
+                middlewares: r.middlewares,
+                file: r.file,
+                line: r.line,
+            })),
             prompt: this.generatePrompt(query, contextModules),
             meta: {
                 seedCount: seeds.length,
@@ -315,17 +330,53 @@ export class ContextBuilder {
     // ── Private helpers ────────────────────────────────────────────────────
 
     private toContextFunction(fn: MikkLockFunction, query: ContextQuery): ContextFunction {
-        return {
+        const base: ContextFunction = {
             name: fn.name,
             file: fn.file,
             startLine: fn.startLine,
             endLine: fn.endLine,
             calls: query.includeCallGraph !== false ? fn.calls : [],
             calledBy: query.includeCallGraph !== false ? fn.calledBy : [],
+            params: fn.params,
+            returnType: fn.returnType,
+            isAsync: fn.isAsync,
+            isExported: fn.isExported,
             purpose: fn.purpose,
             errorHandling: fn.errorHandling?.map(e => `${e.type} @ line ${e.line}: ${e.detail}`),
             edgeCases: fn.edgeCasesHandled,
         }
+
+        // Attach body if requested and projectRoot is available
+        if (query.includeBodies !== false && query.projectRoot) {
+            base.body = this.readFunctionBody(fn, query.projectRoot)
+        }
+
+        return base
+    }
+
+    /**
+     * Read the actual source code of a function from disk.
+     * Uses startLine/endLine from the lock to extract the relevant lines.
+     * Large bodies are compressed to preserve logic while stripping noise.
+     */
+    private readFunctionBody(fn: MikkLockFunction, projectRoot: string): string | undefined {
+        try {
+            const filePath = path.resolve(projectRoot, fn.file)
+            if (!fs.existsSync(filePath)) return undefined
+
+            const content = fs.readFileSync(filePath, 'utf-8')
+            const lines = content.split('\n')
+            const start = Math.max(0, fn.startLine - 1)  // Convert to 0-based
+            const end = Math.min(lines.length, fn.endLine)
+            const body = lines.slice(start, end).join('\n')
+
+            // Skip if body is trivially small (single-line setters etc.)
+            if (body.length < 20) return undefined
+
+            return compressBody(body)
+        } catch {
+            return undefined
+        }
     }
 
     /**
@@ -333,11 +384,21 @@ export class ContextBuilder {
      * Mirrors what the providers will emit.
      */
     private buildFunctionSnippet(fn: MikkLockFunction, query: ContextQuery): string {
-        const parts = [`${fn.name}(${fn.file}:${fn.startLine}-${fn.endLine})`]
+        const asyncStr = fn.isAsync ? 'async ' : ''
+        const params = fn.params?.map(p => `${p.name}: ${p.type}`).join(', ') || ''
+        const retStr = fn.returnType ? `: ${fn.returnType}` : ''
+        const parts = [`${asyncStr}${fn.name}(${params})${retStr} ${fn.file}:${fn.startLine}-${fn.endLine}`]
         if (fn.purpose) parts.push(` — ${fn.purpose}`)
         if (query.includeCallGraph !== false && fn.calls.length > 0) {
             parts.push(` calls:[${fn.calls.join(',')}]`)
         }
+        // Estimate body contribution to tokens if bodies will be included
+        if (query.includeBodies !== false && query.projectRoot) {
+            const bodyLines = (fn.endLine - fn.startLine) + 1
+            // Compressed bodies are ~40-60% smaller; use reduced estimate
+            const charsPerLine = bodyLines > 15 ? 20 : 40
+            parts.push('X'.repeat(bodyLines * charsPerLine))
+        }
         return parts.join('')
     }
 
@@ -353,6 +414,35 @@ export class ContextBuilder {
         lines.push(`Task: ${query.task}`)
         lines.push('')
 
+        // Include routes (API endpoints) — critical for understanding how the app works
+        const routes = this.lock.routes
+        if (routes && routes.length > 0) {
+            lines.push('=== HTTP ROUTES ===')
+            for (const r of routes) {
+                const mw = r.middlewares.length > 0 ? ` [${r.middlewares.join(', ')}]` : ''
+                lines.push(`  ${r.method} ${r.path} → ${r.handler}${mw}  (${r.file}:${r.line})`)
+            }
+            lines.push('')
+        }
+
+        // Include context files (schemas, data models) first — they define the shape
+        const ctxFiles = this.lock.contextFiles
+        if (ctxFiles && ctxFiles.length > 0) {
+            lines.push('=== DATA MODELS & SCHEMAS ===')
+            for (const cf of ctxFiles) {
+                lines.push(`--- ${cf.path} (${cf.type}) ---`)
+                // Trim to ~2000 chars per file in prompt output
+                const maxChars = 2000
+                if (cf.content.length > maxChars) {
+                    lines.push(cf.content.slice(0, maxChars))
+                    lines.push(`... (truncated, ${cf.size} bytes total)`)
+                } else {
+                    lines.push(cf.content.trimEnd())
+                }
+                lines.push('')
+            }
+        }
+
         for (const mod of modules) {
             lines.push(`--- Module: ${mod.name} (${mod.id}) ---`)
             if (mod.description) lines.push(mod.description)
@@ -360,13 +450,22 @@ export class ContextBuilder {
             lines.push('')
 
             for (const fn of mod.functions) {
+                // Rich signature
+                const asyncStr = fn.isAsync ? 'async ' : ''
+                const params = fn.params && fn.params.length > 0
+                    ? fn.params.map(p => `${p.name}${p.optional ? '?' : ''}: ${p.type}`).join(', ')
+                    : ''
+                const retStr = fn.returnType ? `: ${fn.returnType}` : ''
+                const exported = fn.isExported ? 'export ' : ''
+                const sig = `${exported}${asyncStr}${fn.name}(${params})${retStr}`
+
                 const callStr = fn.calls.length > 0
                     ? ` → [${fn.calls.join(', ')}]`
                     : ''
                 const calledByStr = fn.calledBy.length > 0
                     ? ` ← called by [${fn.calledBy.join(', ')}]`
                     : ''
-                lines.push(`  ${fn.name}  ${fn.file}:${fn.startLine}-${fn.endLine}${callStr}${calledByStr}`)
+                lines.push(`  ${sig}  ${fn.file}:${fn.startLine}-${fn.endLine}${callStr}${calledByStr}`)
                 if (fn.purpose) lines.push(`    purpose: ${fn.purpose}`)
                 if (fn.edgeCases && fn.edgeCases.length > 0) {
                     lines.push(`    edge cases: ${fn.edgeCases.join('; ')}`)
@@ -374,6 +473,11 @@ export class ContextBuilder {
                 if (fn.errorHandling && fn.errorHandling.length > 0) {
                     lines.push(`    error handling: ${fn.errorHandling.join('; ')}`)
                 }
+                if (fn.body) {
+                    lines.push('    ```')
+                    lines.push(fn.body)
+                    lines.push('    ```')
+                }
             }
             lines.push('')
         }
@@ -396,4 +500,240 @@ export class ContextBuilder {
 
         return lines.join('\n')
     }
+}
+
+// ---------------------------------------------------------------------------
+// Body compressor — produces dense pseudo-code preserving all logic
+// ---------------------------------------------------------------------------
+
+/**
+ * Compress a function body for context output.
+ * Bodies ≤ 15 lines pass through unchanged.
+ * Larger bodies get noise stripped, templates collapsed, and blocks condensed.
+ */
+function compressBody(raw: string): string {
+    const lines = raw.split('\n')
+    if (lines.length <= 15) return raw
+
+    let result = stripNoise(lines)
+    result = removeEmptyBlocks(result)
+    result = collapseTemplates(result)
+    result = collapseChains(result)
+    result = collapseSimpleBlocks(result)
+    result = dedent(result)
+
+    return result.join('\n')
+}
+
+/** Strip blank lines, comment-only lines, and console.* statements */
+function stripNoise(lines: string[]): string[] {
+    const out: string[] = []
+    let inBlock = false
+
+    for (const line of lines) {
+        const t = line.trim()
+
+        // Track block comments
+        if (inBlock) {
+            if (t.includes('*/')) inBlock = false
+            continue
+        }
+        if (t.startsWith('/*')) {
+            if (!t.includes('*/')) inBlock = true
+            continue
+        }
+
+        // Skip blank lines
+        if (!t) continue
+
+        // Skip single-line comments (preserve TODO/FIXME/NOTE)
+        if (t.startsWith('//') && !/\b(TODO|FIXME|HACK|NOTE)\b/i.test(t)) continue
+
+        // Skip console.log/error/warn/info/debug statements
+        if (/^\s*console\.(log|error|warn|info|debug)\s*\(/.test(line)) continue
+
+        out.push(line)
+    }
+
+    return out
+}
+
+/** Remove empty blocks left after noise stripping (empty else {}, catch {}) */
+function removeEmptyBlocks(lines: string[]): string[] {
+    const out: string[] = []
+    let i = 0
+
+    while (i < lines.length) {
+        const t = lines[i].trim()
+        const next = i + 1 < lines.length ? lines[i + 1].trim() : ''
+
+        // "} else {" followed by "}" → just "}" (closing the if-block)
+        if (/^}\s*else\s*\{$/.test(t) && next === '}') {
+            const indent = lines[i].match(/^(\s*)/)?.[1] || ''
+            out.push(`${indent}}`)
+            i += 2
+            continue
+        }
+
+        // "} catch (...) {" followed by "}" → "} catch (...) {}" on one line
+        if (/^}\s*catch\s*(\(.*\))?\s*\{$/.test(t) && next === '}') {
+            const indent = lines[i].match(/^(\s*)/)?.[1] || ''
+            out.push(`${indent}${t} }`)
+            i += 2
+            continue
+        }
+
+        out.push(lines[i])
+        i++
+    }
+
+    return out
+}
+/** Collapse multi-line template literals (>5 lines) into short descriptors */
+function collapseTemplates(lines: string[]): string[] {
+    const out: string[] = []
+    let i = 0
+
+    while (i < lines.length) {
+        const line = lines[i]
+        const t = line.trim()
+
+        // Count unescaped backticks on this line
+        const bts = (t.replace(/\\`/g, '').match(/`/g) || []).length
+
+        if (bts % 2 === 1) {
+            // Odd count → opens a multi-line template literal
+            const start = i
+            const collected: string[] = [t]
+            i++
+
+            while (i < lines.length) {
+                const tl = lines[i].trim()
+                collected.push(tl)
+                const tlBts = (tl.replace(/\\`/g, '').match(/`/g) || []).length
+                if (tlBts % 2 === 1) { i++; break }
+                i++
+            }
+
+            // Only collapse if the template is large (>5 lines)
+            if (collected.length > 5) {
+                const content = collected.join('\n')
+                const desc = describeTemplate(content)
+                const indent = line.match(/^(\s*)/)?.[1] || ''
+                const btIdx = t.indexOf('`')
+                const prefix = btIdx >= 0 ? t.substring(0, btIdx) : ''
+                out.push(`${indent}${prefix}[template: ${desc}]`)
+            } else {
+                // Small template — keep original lines
+                for (let j = start; j < i; j++) out.push(lines[j])
+            }
+            continue
+        }
+
+        out.push(line)
+        i++
+    }
+
+    return out
+}
+
+/** Analyze template content and produce a short description */
+function describeTemplate(content: string): string {
+    const lower = content.toLowerCase()
+    const f: string[] = []
+
+    if (lower.includes('<!doctype') || lower.includes('<html')) f.push('HTML page')
+    else if (lower.includes('<div') || lower.includes('<span')) f.push('HTML fragment')
+    if (lower.includes('<style>') || lower.includes('font-family')) f.push('with CSS')
+    if (lower.includes('<script>')) f.push('with JS')
+    if (/\bselect\b|\binsert\b|\bupdate\b.*\bset\b/i.test(content)) f.push('SQL query')
+
+    const interps = (content.match(/\$\{/g) || []).length
+    if (interps > 0) f.push(`${interps} vars`)
+
+    return f.length > 0 ? f.join(', ') : `${content.split('\n').length}-line string`
+}
+
+/** Collapse 3+ consecutive .replace() lines into a summary */
+function collapseChains(lines: string[]): string[] {
+    const out: string[] = []
+    let i = 0
+
+    while (i < lines.length) {
+        if (lines[i].trim().includes('.replace(')) {
+            const start = i
+            let count = 0
+            while (i < lines.length && lines[i].trim().includes('.replace(')) {
+                count++
+                i++
+            }
+
+            if (count >= 3) {
+                const indent = lines[start].match(/^(\s*)/)?.[1] || ''
+                // If the previous line is the chain's assignment target (no semicolon), merge
+                if (out.length > 0) {
+                    const prev = out[out.length - 1].trimEnd()
+                    if (!prev.endsWith(';') && !prev.endsWith('{') && !prev.endsWith('}')) {
+                        out[out.length - 1] = `${prev} [${count}x .replace() chain]`
+                        continue
+                    }
+                }
+                out.push(`${indent}[${count}x .replace() chain]`)
+            } else {
+                for (let j = start; j < i; j++) out.push(lines[j])
+            }
+            continue
+        }
+
+        out.push(lines[i])
+        i++
+    }
+
+    return out
+}
+
+/** Collapse single-statement if/else blocks (3 lines → 1 line) */
+function collapseSimpleBlocks(lines: string[]): string[] {
+    const out: string[] = []
+    let i = 0
+
+    while (i < lines.length) {
+        const t = lines[i].trim()
+
+        // Match: if (...) {   or   else if (...) {   or   else {
+        if (/^(if\s*\(.*\)|else\s+if\s*\(.*\)|else)\s*\{\s*$/.test(t) && i + 2 < lines.length) {
+            const body = lines[i + 1].trim()
+            const close = lines[i + 2].trim()
+
+            // Only collapse if the next line is a single statement and line after is closing }
+            if (close === '}' && !body.startsWith('if') && !body.startsWith('for') &&
+                !body.startsWith('while') && !body.startsWith('switch')) {
+                const indent = lines[i].match(/^(\s*)/)?.[1] || ''
+                out.push(`${indent}${t} ${body} }`)
+                i += 3
+                continue
+            }
+        }
+
+        out.push(lines[i])
+        i++
+    }
+
+    return out
+}
+
+/** Remove common leading indentation */
+function dedent(lines: string[]): string[] {
+    let min = Infinity
+    for (const l of lines) {
+        const m = l.match(/^(\s+)\S/)
+        if (m && m[1].length < min) min = m[1].length
+    }
+    if (min === Infinity || min <= 0) return lines
+
+    return lines.map(l => {
+        if (!l.trim()) return l
+        const spaces = l.length - l.trimStart().length
+        return l.substring(Math.min(min, spaces))
+    })
 }

package/src/index.ts

@@ -1,4 +1,5 @@
 export { ContextBuilder } from './context-builder.js'
 export { ClaudeMdGenerator } from './claude-md-generator.js'
+export type { ProjectMeta } from './claude-md-generator.js'
 export { ClaudeProvider, GenericProvider, getProvider } from './providers.js'
 export type { AIContext, ContextModule, ContextFunction, ContextQuery, ContextProvider } from './types.js'

package/src/providers.ts

@@ -51,7 +51,14 @@ export class ClaudeProvider implements ContextProvider {
                     const calledBy = fn.calledBy.length > 0
                         ? ` calledBy="${esc(fn.calledBy.join(','))}"`
                         : ''
-                    lines.push(`    <fn name="${esc(fn.name)}" file="${esc(fn.file)}" lines="${fn.startLine}-${fn.endLine}"${calls}${calledBy}>`)
+                    // Rich signature attributes
+                    const asyncAttr = fn.isAsync ? ' async="true"' : ''
+                    const exportedAttr = fn.isExported ? ' exported="true"' : ''
+                    const retAttr = fn.returnType ? ` returns="${esc(fn.returnType)}"` : ''
+                    const paramStr = fn.params && fn.params.length > 0
+                        ? ` params="${esc(fn.params.map(p => `${p.name}${p.optional ? '?' : ''}: ${p.type}`).join(', '))}"`
+                        : ''
+                    lines.push(`    <fn name="${esc(fn.name)}" file="${esc(fn.file)}" lines="${fn.startLine}-${fn.endLine}"${asyncAttr}${exportedAttr}${paramStr}${retAttr}${calls}${calledBy}>`)
                     if (fn.purpose) lines.push(`      <purpose>${esc(fn.purpose)}</purpose>`)
                     if (fn.edgeCases && fn.edgeCases.length > 0) {
                         lines.push(`      <edge_cases>${esc(fn.edgeCases.join('; '))}</edge_cases>`)
@@ -59,6 +66,11 @@ export class ClaudeProvider implements ContextProvider {
                     if (fn.errorHandling && fn.errorHandling.length > 0) {
                         lines.push(`      <error_handling>${esc(fn.errorHandling.join('; '))}</error_handling>`)
                     }
+                    if (fn.body) {
+                        lines.push(`      <body>`)
+                        lines.push(esc(fn.body))
+                        lines.push(`      </body>`)
+                    }
                     lines.push('    </fn>')
                 }
                 lines.push('  </functions>')
@@ -67,6 +79,36 @@ export class ClaudeProvider implements ContextProvider {
             lines.push('')
         }
 
+        // ── Context files (schemas, data models, config) ───────────────────
+        if (context.contextFiles && context.contextFiles.length > 0) {
+            lines.push('<context_files>')
+            for (const cf of context.contextFiles) {
+                lines.push(`  <file path="${esc(cf.path)}" type="${esc(cf.type)}">`)
+                // Trim to ~2000 chars per file to stay within token budget
+                const maxChars = 2000
+                if (cf.content.length > maxChars) {
+                    lines.push(esc(cf.content.slice(0, maxChars)))
+                    lines.push(`... (truncated)`)
+                } else {
+                    lines.push(esc(cf.content.trimEnd()))
+                }
+                lines.push('  </file>')
+            }
+            lines.push('</context_files>')
+            lines.push('')
+        }
+
+        // ── Routes (HTTP endpoints) ────────────────────────────────────────
+        if (context.routes && context.routes.length > 0) {
+            lines.push('<routes>')
+            for (const r of context.routes) {
+                const mw = r.middlewares.length > 0 ? ` middlewares="${esc(r.middlewares.join(','))}"` : ''
+                lines.push(`  <route method="${esc(r.method)}" path="${esc(r.path)}" handler="${esc(r.handler)}" file="${esc(r.file)}" line="${r.line}"${mw}/>`)
+            }
+            lines.push('</routes>')
+            lines.push('')
+        }
+
         // ── Constraints ────────────────────────────────────────────────────
         if (context.constraints.length > 0) {
             lines.push('<constraints>')
@@ -121,8 +163,32 @@ export class CompactProvider implements ContextProvider {
         for (const mod of context.modules) {
             lines.push(`## ${mod.name}`)
             for (const fn of mod.functions) {
+                const asyncStr = fn.isAsync ? 'async ' : ''
+                const params = fn.params?.map(p => `${p.name}: ${p.type}`).join(', ') || ''
+                const retStr = fn.returnType ? `: ${fn.returnType}` : ''
                 const calls = fn.calls.length > 0 ? ` → ${fn.calls.join(',')}` : ''
-                lines.push(`  ${fn.name} [${fn.file}:${fn.startLine}]${calls}`)
+                lines.push(`  ${asyncStr}${fn.name}(${params})${retStr} [${fn.file}:${fn.startLine}]${calls}`)
+                if (fn.body) {
+                    lines.push('  ```')
+                    lines.push(fn.body)
+                    lines.push('  ```')
+                }
+            }
+            lines.push('')
+        }
+        if (context.contextFiles && context.contextFiles.length > 0) {
+            lines.push('## Schemas & Data Models')
+            for (const cf of context.contextFiles) {
+                lines.push(`### ${cf.path} (${cf.type})`)
+                lines.push(cf.content.length > 1500 ? cf.content.slice(0, 1500) + '\n...(truncated)' : cf.content.trimEnd())
+                lines.push('')
+            }
+        }
+        if (context.routes && context.routes.length > 0) {
+            lines.push('## Routes')
+            for (const r of context.routes) {
+                const mw = r.middlewares.length > 0 ? ` [${r.middlewares.join(', ')}]` : ''
+                lines.push(`  ${r.method} ${r.path} → ${r.handler}${mw} (${r.file}:${r.line})`)
             }
             lines.push('')
         }

package/src/types.ts

@@ -12,6 +12,10 @@ export interface AIContext {
     modules: ContextModule[]
     constraints: string[]
     decisions: { title: string; reason: string }[]
+    /** Discovered schema/config/model files included verbatim */
+    contextFiles?: { path: string; content: string; type: string }[]
+    /** Detected HTTP route registrations */
+    routes?: { method: string; path: string; handler: string; middlewares: string[]; file: string; line: number }[]
     prompt: string
     /** Diagnostic info — helpful for debugging context quality */
     meta: {
@@ -39,9 +43,15 @@ export interface ContextFunction {
     endLine: number
     calls: string[]
     calledBy: string[]
+    params?: { name: string; type: string; optional?: boolean }[]
+    returnType?: string
+    isAsync?: boolean
+    isExported?: boolean
     purpose?: string
     errorHandling?: string[]
     edgeCases?: string[]
+    /** The actual source code body (only included for top-scored functions) */
+    body?: string
 }
 
 /** Query options for context generation */
@@ -60,6 +70,10 @@ export interface ContextQuery {
     tokenBudget?: number
     /** Include call graph arrows (default true) */
     includeCallGraph?: boolean
+    /** Include function bodies for top-scored functions (default true) */
+    includeBodies?: boolean
+    /** Absolute filesystem path to the project root (needed for body reading) */
+    projectRoot?: string
 }
 
 /** Context provider interface for different AI platforms */