@phuetz/code-buddy 0.3.0 → 1.0.0-rc.8

package/dist/utils/init-project.js

@@ -1,10 +1,512 @@
 import fs from 'fs';
 import path from 'path';
+// ============================================================================
+// CONTEXT.md generator (rich, profile-aware)
+// ============================================================================
 /**
- * Initialize .codebuddy directory with templates and configurations
- * Similar to Claude Code's project initialization
+ * Generate rich CONTEXT.md content from a RepoProfile.
+ * Exported for unit testing.
  */
-export function initCodeBuddyProject(workingDirectory = process.cwd(), options = {}) {
+export function generateContextMdContent(profile, cwd) {
+    if (!profile) {
+        return `# Project Context
+
+This file is automatically loaded by Code Buddy to provide project context.
+
+## Getting Started
+
+This project appears to be empty. Use the \`/starter\` command to browse
+available framework starter packs (React, Django, Rust, Go, etc.).
+
+## Project Overview
+
+<!-- Describe your project here -->
+
+## Architecture
+
+<!-- Key architectural decisions -->
+
+## Conventions
+
+<!-- Coding conventions and patterns -->
+
+## Important Files
+
+<!-- Key files and their purposes -->
+
+## Common Tasks
+
+<!-- How to build, test, deploy -->
+`;
+    }
+    const pm = profile.packageManager ?? 'npm';
+    const run = pm === 'npm' ? 'npm run' : pm;
+    const sections = [];
+    // Header
+    const projectName = profile.name ?? path.basename(cwd || process.cwd());
+    sections.push(`# ${projectName} — Project Context
+
+This file is automatically loaded by Code Buddy to provide project context.`);
+    // Project Overview
+    const overviewLines = [];
+    if (profile.description) {
+        overviewLines.push(profile.description);
+    }
+    overviewLines.push('');
+    if (profile.languages?.length)
+        overviewLines.push(`- **Languages:** ${profile.languages.join(', ')}`);
+    if (profile.framework)
+        overviewLines.push(`- **Framework:** ${profile.framework}`);
+    if (profile.moduleType)
+        overviewLines.push(`- **Module system:** ${profile.moduleType.toUpperCase()}`);
+    if (pm)
+        overviewLines.push(`- **Package manager:** ${pm}`);
+    if (profile.testFramework)
+        overviewLines.push(`- **Test framework:** ${profile.testFramework}`);
+    if (profile.nodeVersion)
+        overviewLines.push(`- **Node.js:** ${profile.nodeVersion}`);
+    if (profile.license)
+        overviewLines.push(`- **License:** ${profile.license}`);
+    if (profile.hasCi)
+        overviewLines.push(`- **CI:** GitHub Actions`);
+    if (profile.hasDocker)
+        overviewLines.push(`- **Containerized:** Docker`);
+    if (profile.databases?.length)
+        overviewLines.push(`- **Databases:** ${profile.databases.join(', ')}`);
+    sections.push(`## Project Overview\n\n${overviewLines.join('\n')}`);
+    // Key Dependencies
+    if (profile.topDependencies?.length) {
+        const depList = profile.topDependencies.map((d) => `- \`${d}\``).join('\n');
+        sections.push(`## Key Dependencies\n\n${depList}`);
+    }
+    // Architecture
+    const archLines = [];
+    archLines.push('| Directory | Role |');
+    archLines.push('|-----------|------|');
+    if (profile.directories?.src)
+        archLines.push(`| \`${profile.directories.src}/\` | Source code |`);
+    if (profile.directories?.tests)
+        archLines.push(`| \`${profile.directories.tests}/\` | Tests |`);
+    if (profile.directories?.docs)
+        archLines.push(`| \`${profile.directories.docs}/\` | Documentation |`);
+    if (archLines.length > 2) {
+        const entryLine = profile.entryPoints?.length
+            ? `\n\n**Entry points:** ${profile.entryPoints.map((e) => `\`${e}\``).join(', ')}`
+            : '';
+        sections.push(`## Architecture\n\n${archLines.join('\n')}${entryLine}`);
+    }
+    // Build & Development
+    const cmdLines = [];
+    cmdLines.push('```bash');
+    if (profile.commands?.build)
+        cmdLines.push(`${profile.commands.build}    # Build`);
+    if (profile.commands?.test)
+        cmdLines.push(`${profile.commands.test}     # Test`);
+    if (profile.commands?.lint)
+        cmdLines.push(`${profile.commands.lint}     # Lint`);
+    if (profile.commands?.format)
+        cmdLines.push(`${profile.commands.format}   # Format`);
+    cmdLines.push('```');
+    const extraScripts = [];
+    if (profile.commands?.typecheck)
+        extraScripts.push(`\`${profile.commands.typecheck}\``);
+    if (profile.commands?.validate)
+        extraScripts.push(`\`${profile.commands.validate}\``);
+    const extraLine = extraScripts.length > 0
+        ? `\n\n**Other scripts:** ${extraScripts.join(', ')}`
+        : '';
+    const validateNote = profile.commands?.validate
+        ? `\n\n> **Pre-commit check:** Run \`${profile.commands.validate}\` before committing to catch lint/type/test errors early.`
+        : '';
+    sections.push(`## Build & Development\n\n${cmdLines.join('\n')}${extraLine}${validateNote}`);
+    // Testing
+    const testLines = [];
+    if (profile.testFramework)
+        testLines.push(`- **Framework:** ${profile.testFramework}`);
+    if (profile.commands?.test)
+        testLines.push(`- **Run:** \`${profile.commands.test}\``);
+    if (profile.directories?.tests)
+        testLines.push(`- **Location:** \`${profile.directories.tests}/\``);
+    if (testLines.length > 0) {
+        sections.push(`## Testing\n\n${testLines.join('\n')}`);
+    }
+    // Conventions
+    const convLines = [];
+    if (profile.conventions?.lintRules?.length) {
+        convLines.push(`- **Linter:** ${profile.conventions.lintRules.join(', ')}`);
+    }
+    if (profile.conventions?.naming)
+        convLines.push(`- **Naming:** ${profile.conventions.naming}`);
+    if (profile.moduleType === 'esm')
+        convLines.push(`- **Imports:** ESM (\`import\`/\`export\`), \`.js\` extensions required`);
+    if (convLines.length > 0) {
+        sections.push(`## Conventions\n\n${convLines.join('\n')}`);
+    }
+    // Cartography (deep scan results)
+    if (profile.cartography) {
+        const carto = profile.cartography;
+        const cartoLines = [];
+        // Scale
+        const totalFiles = carto.fileStats.totalSourceFiles + carto.fileStats.totalTestFiles;
+        const locEntries = Object.entries(carto.fileStats.locEstimate).sort((a, b) => b[1] - a[1]);
+        const locSummary = locEntries.map(([lang, loc]) => `${lang} ~${formatNumber(loc)}`).join(', ');
+        cartoLines.push(`**Scale:** ${formatNumber(carto.fileStats.totalSourceFiles)} source files, ${formatNumber(carto.fileStats.totalTestFiles)} test files (${formatNumber(totalFiles)} total)`);
+        if (locSummary)
+            cartoLines.push(`**Lines of code (est.):** ${locSummary}`);
+        // Architecture
+        if (carto.architecture.layers.length > 0) {
+            cartoLines.push(`\n**Architecture style:** ${carto.architecture.style} (${carto.architecture.layers.length} modules, max depth ${carto.architecture.maxDepth})`);
+            cartoLines.push('');
+            cartoLines.push('| Module | Directory | Files |');
+            cartoLines.push('|--------|-----------|-------|');
+            for (const layer of carto.architecture.layers.slice(0, 20)) {
+                cartoLines.push(`| ${layer.name} | \`${layer.directory}/\` | ${layer.fileCount} |`);
+            }
+        }
+        // Hot modules
+        if (carto.importGraph.hotModules.length > 0) {
+            cartoLines.push('');
+            cartoLines.push('**Most imported modules:**');
+            for (const m of carto.importGraph.hotModules.slice(0, 10)) {
+                cartoLines.push(`- \`${m.module}\` (imported by ${m.importedBy} files)`);
+            }
+        }
+        // Design patterns
+        const patternCounts = [];
+        if (carto.patterns.singletons.length)
+            patternCounts.push(`${carto.patterns.singletons.length} singletons`);
+        if (carto.patterns.registries.length)
+            patternCounts.push(`${carto.patterns.registries.length} registries`);
+        if (carto.patterns.factories.length)
+            patternCounts.push(`${carto.patterns.factories.length} factories`);
+        if (carto.patterns.facades.length)
+            patternCounts.push(`${carto.patterns.facades.length} facades`);
+        if (carto.patterns.middlewares.length)
+            patternCounts.push(`${carto.patterns.middlewares.length} middlewares`);
+        if (carto.patterns.observers.length)
+            patternCounts.push(`${carto.patterns.observers.length} event emitters`);
+        if (patternCounts.length > 0) {
+            cartoLines.push(`\n**Design patterns:** ${patternCounts.join(', ')}`);
+        }
+        // API surface
+        if (carto.apiSurface.endpointCount > 0) {
+            cartoLines.push(`\n**API surface:** ${carto.apiSurface.restRoutes.length} REST routes, ${carto.apiSurface.wsEvents.length} WebSocket events`);
+        }
+        // Circular risks
+        if (carto.importGraph.circularRisks.length > 0) {
+            cartoLines.push(`\n**Circular dependency risks (${carto.importGraph.circularRisks.length}):**`);
+            for (const c of carto.importGraph.circularRisks.slice(0, 5)) {
+                cartoLines.push(`- \`${c.a}\` <-> \`${c.b}\``);
+            }
+        }
+        sections.push(`## Project Cartography\n\n${cartoLines.join('\n')}`);
+        // V2: Component inventory (detailed architecture map)
+        if (carto.components) {
+            const compSections = renderComponentInventory(carto.components);
+            if (compSections) {
+                sections.push(compSections);
+            }
+        }
+        // V2: Data flow section (how components connect)
+        const dataFlow = renderDataFlow(carto, profile);
+        if (dataFlow) {
+            sections.push(dataFlow);
+        }
+    }
+    // CLAUDE.md reference
+    if (profile.hasClaudeMd) {
+        sections.push(`## Existing Documentation\n\n- \`CLAUDE.md\` exists with detailed project instructions (loaded separately by the runtime)`);
+    }
+    // Editable section
+    sections.push(`## Important Notes\n\n<!-- Add project-specific notes, gotchas, and patterns here -->`);
+    return sections.join('\n\n') + '\n';
+}
+// ============================================================================
+// CODEBUDDY.md generator (project-aware custom instructions)
+// ============================================================================
+/**
+ * Generate CODEBUDDY.md content tailored to the detected language/framework.
+ * Uses RepoProfile data to fill in real project details instead of placeholders.
+ * Exported for unit testing.
+ */
+export function generateCODEBUDDYMdContent(profile) {
+    const lang = profile?.languages?.[0]?.toLowerCase() ?? '';
+    const framework = profile?.framework ?? '';
+    const cmds = profile?.commands ?? {};
+    const dirs = profile?.directories ?? {};
+    const testCmd = cmds.test ?? 'npm test';
+    const lintCmd = cmds.lint ?? 'npm run lint';
+    const buildCmd = cmds.build ?? 'npm run build';
+    const srcDir = dirs.src ?? 'src';
+    const testsDir = dirs.tests ?? 'tests';
+    // ── About section ──────────────────────────────────────
+    const aboutLines = [];
+    if (profile?.description) {
+        aboutLines.push(profile.description);
+    }
+    else if (profile?.name) {
+        aboutLines.push(`<!-- Describe ${profile.name} here -->`);
+    }
+    else {
+        aboutLines.push('<!-- Describe your project here -->');
+    }
+    aboutLines.push('');
+    if (profile?.languages?.length)
+        aboutLines.push(`- **Languages:** ${profile.languages.join(', ')}`);
+    if (framework)
+        aboutLines.push(`- **Framework:** ${framework}`);
+    if (profile?.moduleType)
+        aboutLines.push(`- **Module system:** ${profile.moduleType.toUpperCase()}`);
+    if (profile?.packageManager)
+        aboutLines.push(`- **Package manager:** ${profile.packageManager}`);
+    if (profile?.testFramework)
+        aboutLines.push(`- **Test framework:** ${profile.testFramework}`);
+    // ── Style section (language-specific) ──────────────────
+    let styleSection;
+    if (lang === 'python') {
+        styleSection = `## Code Style Guidelines
+- Follow PEP 8 conventions
+- Use type annotations for all function signatures
+- Format with black or ruff
+- Add docstrings to public functions and classes`;
+    }
+    else if (lang === 'go') {
+        styleSection = `## Code Style Guidelines
+- Follow effective Go conventions
+- Run \`gofmt\` / \`goimports\` before committing
+- Prefer explicit error handling over panics
+- Add godoc comments to exported identifiers`;
+    }
+    else if (lang === 'rust') {
+        styleSection = `## Code Style Guidelines
+- Run \`cargo fmt\` before committing
+- Resolve all \`cargo clippy\` warnings
+- Prefer \`Result\`/\`Option\` over panics in library code`;
+    }
+    else {
+        const tsNote = lang === 'typescript' || lang === 'javascript'
+            ? '- Use TypeScript for all new files\n- Avoid `any`; use proper types'
+            : '- Follow the existing code style';
+        const esmNote = profile?.moduleType === 'esm'
+            ? '\n- ESM imports require `.js` extension even for `.ts` files'
+            : '';
+        styleSection = `## Code Style Guidelines
+${tsNote}
+- Follow the existing code style${esmNote}`;
+    }
+    // ── Architecture section ───────────────────────────────
+    let archSection;
+    if (lang === 'python') {
+        archSection = `## Architecture
+- \`${srcDir}/\` — Source code
+- \`${testsDir}/\` — Test files (pytest)`;
+    }
+    else if (lang === 'go') {
+        archSection = `## Architecture
+- \`${srcDir}/\` — Source packages
+- \`${testsDir}/\` — Test files (*_test.go)`;
+    }
+    else if (lang === 'rust') {
+        archSection = `## Architecture
+- \`src/\` — Source crates
+- \`tests/\` — Integration tests`;
+    }
+    else {
+        archSection = `## Architecture
+- \`${srcDir}/\` — Source code
+- \`${testsDir}/\` — Test files`;
+    }
+    if (dirs.docs) {
+        archSection += `\n- \`${dirs.docs}/\` — Documentation`;
+    }
+    if (profile?.entryPoints?.length) {
+        archSection += `\n\n**Entry point:** \`${profile.entryPoints[0]}\``;
+    }
+    // ── Test section ───────────────────────────────────────
+    let testSection;
+    if (lang === 'python') {
+        testSection = `## Testing
+- Write tests with pytest
+- Run: \`${testCmd}\``;
+    }
+    else if (lang === 'go') {
+        testSection = `## Testing
+- Use \`go test ./...\`
+- Run: \`${testCmd}\`
+- Table-driven tests are preferred`;
+    }
+    else if (lang === 'rust') {
+        testSection = `## Testing
+- Unit tests in \`#[cfg(test)]\` modules
+- Run: \`${testCmd}\`
+- Integration tests in tests/`;
+    }
+    else {
+        const fwNote = profile?.testFramework ? ` (${profile.testFramework})` : '';
+        testSection = `## Testing
+- Write tests for new features${fwNote}
+- Run: \`${testCmd}\``;
+    }
+    // ── Commands section ───────────────────────────────────
+    const cmdLines = [];
+    cmdLines.push(`- Build: \`${buildCmd}\``);
+    cmdLines.push(`- Lint: \`${lintCmd}\``);
+    if (cmds.typecheck)
+        cmdLines.push(`- Typecheck: \`${cmds.typecheck}\``);
+    if (cmds.validate)
+        cmdLines.push(`- Validate: \`${cmds.validate}\``);
+    if (cmds.format)
+        cmdLines.push(`- Format: \`${cmds.format}\``);
+    // ── CLAUDE.md note ─────────────────────────────────────
+    const claudeNote = profile?.hasClaudeMd
+        ? `\n## Reference\n\n> This project has a \`CLAUDE.md\` with detailed instructions. Refer to it for architecture details, testing gotchas, and subsystem reference.\n`
+        : '';
+    return `# Custom Instructions for Code Buddy
+
+## About This Project
+${aboutLines.join('\n')}
+
+${styleSection}
+
+${archSection}
+
+${testSection}
+
+## Commands
+${cmdLines.join('\n')}
+
+## Git Conventions
+- Use conventional commits (feat:, fix:, docs:, etc.)
+- Keep commits small and focused
+- Write descriptive commit messages
+${claudeNote}
+## Forbidden Actions
+- Never commit .env files
+- Never expose API keys
+- Never delete production data
+`;
+}
+// ============================================================================
+// AGENTS.md generator (cross-CLI convention, lives at project root)
+// ============================================================================
+/**
+ * Generate AGENTS.md content — the cross-CLI convention file read by
+ * Claude Code, Gemini CLI 0.20+, Cursor, Codex, and Code Buddy itself
+ * (see `src/context/jit-context.ts` and `bootstrap-loader.ts`).
+ *
+ * Intentionally minimal — this is the "first-glance" guide that any agent
+ * should be able to consume in under 30 seconds. Detailed instructions
+ * live in `.codebuddy/CODEBUDDY.md` and `.codebuddy/CONTEXT.md`, which
+ * AGENTS.md points to for deeper reading.
+ *
+ * Exported for unit testing.
+ */
+export function generateAgentsMdContent(profile) {
+    const cmds = profile?.commands ?? {};
+    const dirs = profile?.directories ?? {};
+    const buildCmd = cmds.build ?? 'npm run build';
+    const testCmd = cmds.test ?? 'npm test';
+    const lintCmd = cmds.lint ?? 'npm run lint';
+    const typecheckCmd = cmds.typecheck;
+    const formatCmd = cmds.format;
+    const projectName = profile?.name ?? 'this project';
+    const oneLiner = profile?.description
+        ?? (profile?.framework && profile?.languages?.[0]
+            ? `A ${profile.languages[0]} / ${profile.framework} project.`
+            : '<!-- one-line project description -->');
+    // Conventions block
+    const conventionLines = [];
+    if (profile?.languages?.length) {
+        conventionLines.push(`- **Language(s):** ${profile.languages.join(', ')}`);
+    }
+    if (profile?.framework) {
+        conventionLines.push(`- **Framework:** ${profile.framework}`);
+    }
+    if (profile?.moduleType) {
+        conventionLines.push(`- **Module system:** ${profile.moduleType.toUpperCase()}${profile.moduleType === 'esm' ? ' (imports require `.js` extension even from `.ts` sources)' : ''}`);
+    }
+    if (profile?.testFramework) {
+        conventionLines.push(`- **Test framework:** ${profile.testFramework}`);
+    }
+    if (profile?.packageManager) {
+        conventionLines.push(`- **Package manager:** ${profile.packageManager}`);
+    }
+    if (profile?.conventions?.naming) {
+        conventionLines.push(`- **Naming:** ${profile.conventions.naming}`);
+    }
+    if (conventionLines.length === 0) {
+        conventionLines.push('<!-- Add language, framework, module system here -->');
+    }
+    // Build & Test block
+    const buildLines = [
+        `- **Build:** \`${buildCmd}\``,
+        `- **Test:** \`${testCmd}\``,
+        `- **Lint:** \`${lintCmd}\``,
+    ];
+    if (typecheckCmd)
+        buildLines.push(`- **Typecheck:** \`${typecheckCmd}\``);
+    if (formatCmd)
+        buildLines.push(`- **Format:** \`${formatCmd}\``);
+    // Architecture block — top-level dirs only
+    const archLines = [];
+    if (dirs.src)
+        archLines.push(`- \`${dirs.src}/\` — source code`);
+    if (dirs.tests)
+        archLines.push(`- \`${dirs.tests}/\` — tests`);
+    if (dirs.docs)
+        archLines.push(`- \`${dirs.docs}/\` — documentation`);
+    if (archLines.length === 0) {
+        archLines.push('- `src/` — source code');
+        archLines.push('- `tests/` — tests');
+    }
+    if (profile?.entryPoints?.length) {
+        archLines.push('');
+        archLines.push(`**Entry point:** \`${profile.entryPoints[0]}\``);
+    }
+    // More-context pointers — list deeper docs only if they're likely to exist
+    const moreLines = [
+        '- `.codebuddy/CONTEXT.md` — full project cartography (auto-generated)',
+        '- `.codebuddy/CODEBUDDY.md` — Code Buddy custom instructions, style guide',
+    ];
+    if (profile?.hasClaudeMd) {
+        moreLines.push('- `CLAUDE.md` — Claude Code-specific deep-dive (manually maintained)');
+    }
+    return `# ${projectName} — Agent Guide
+
+${oneLiner}
+
+> Cross-CLI convention file. Read by Claude Code, Gemini CLI, Cursor, Codex, and Code Buddy.
+> Detailed instructions live in \`.codebuddy/\`; this file is the 30-second first-glance.
+
+## Build & Test
+${buildLines.join('\n')}
+
+## Conventions
+${conventionLines.join('\n')}
+
+## Architecture
+${archLines.join('\n')}
+
+## Forbidden
+- Never commit \`.env\` files or files containing secrets
+- Never expose API keys in code, comments, or commit messages
+- Never delete production data without explicit user confirmation
+
+## More Context
+${moreLines.join('\n')}
+
+---
+*Auto-generated by \`buddy init\`. Re-run with \`--force\` to refresh, or edit by hand — \`buddy init\` won't overwrite without explicit force.*
+`;
+}
+// ============================================================================
+// Project initialization
+// ============================================================================
+/**
+ * Initialize .codebuddy directory with templates and configurations.
+ * Similar to Native Engine's project initialization.
+ */
+export async function initCodeBuddyProject(workingDirectory = process.cwd(), options = {}) {
     const result = {
         success: true,
         created: [],
@@ -17,63 +519,96 @@ export function initCodeBuddyProject(workingDirectory = process.cwd(), options =
         fs.mkdirSync(codebuddyDir, { recursive: true });
         result.created.push('.codebuddy/');
     }
-    // Create CODEBUDDY.md (custom instructions)
-    const codebuddyMdPath = path.join(codebuddyDir, 'CODEBUDDY.md');
-    if (!fs.existsSync(codebuddyMdPath) || options.force) {
-        const codebuddyMdContent = `# Custom Instructions for Code Buddy
-
-## About This Project
-<!-- Describe your project here -->
-This project is...
-
-## Code Style Guidelines
-- Use TypeScript for all new files
-- Follow the existing code style
-- Add comments for complex logic
-- Use meaningful variable names
-
-## Architecture
-<!-- Describe your project architecture -->
-- src/ - Source code
-- tests/ - Test files
+    // Create runtime directories expected by the runtime
+    const runtimeDirs = ['sessions', 'runs', 'tool-results', 'knowledge'];
+    for (const dir of runtimeDirs) {
+        const dirPath = path.join(codebuddyDir, dir);
+        if (!fs.existsSync(dirPath)) {
+            fs.mkdirSync(dirPath, { recursive: true });
+            result.created.push(`.codebuddy/${dir}/`);
+        }
+    }
+    // Create .codebuddy/knowledge/README.md (explains frontmatter format)
+    const knowledgeReadmePath = path.join(codebuddyDir, 'knowledge', 'README.md');
+    if (!fs.existsSync(knowledgeReadmePath) || options.force) {
+        const knowledgeReadmeContent = `# Knowledge Directory
 
-## Testing
-- Write tests for new features
-- Maintain test coverage above 80%
-- Use Jest/Vitest for testing
+Place \`.md\` files here to inject domain-specific knowledge into Code Buddy's context.
 
-## Git Conventions
-- Use conventional commits (feat:, fix:, docs:, etc.)
-- Keep commits small and focused
-- Write descriptive commit messages
+## Frontmatter fields
 
-## Important Notes
-<!-- Add any project-specific notes here -->
-- ...
+\`\`\`yaml
+---
+title: "Short descriptive title"
+tags: ["tag1", "tag2"]
+scope: "project"       # project | global
+priority: 1            # lower = higher priority
+---
+\`\`\`
 
-## Forbidden Actions
-<!-- List things Code Buddy should never do -->
-- Never commit .env files
-- Never expose API keys
-- Never delete production data
+Files with lower \`priority\` values are injected first (higher precedence).
 `;
-        fs.writeFileSync(codebuddyMdPath, codebuddyMdContent);
+        fs.writeFileSync(knowledgeReadmePath, knowledgeReadmeContent);
+        result.created.push('.codebuddy/knowledge/README.md');
+    }
+    // Detect project profile for smart template generation
+    let profile = null;
+    try {
+        const { RepoProfiler } = await import('../agent/repo-profiler.js');
+        profile = await new RepoProfiler(workingDirectory).refresh();
+    }
+    catch {
+        // RepoProfiler unavailable — use generic template
+    }
+    // Create CONTEXT.md — priority 1 (highest priority context source)
+    // Generated directly from profile for rich, project-aware content
+    const contextMdPath = path.join(codebuddyDir, 'CONTEXT.md');
+    if (!fs.existsSync(contextMdPath) || options.force) {
+        const contextContent = generateContextMdContent(profile, workingDirectory);
+        fs.writeFileSync(contextMdPath, contextContent);
+        result.created.push('.codebuddy/CONTEXT.md');
+    }
+    else {
+        result.skipped.push('.codebuddy/CONTEXT.md (already exists)');
+    }
+    // Create CODEBUDDY.md — priority 2 (project-aware custom instructions)
+    const codebuddyMdPath = path.join(codebuddyDir, 'CODEBUDDY.md');
+    if (!fs.existsSync(codebuddyMdPath) || options.force) {
+        fs.writeFileSync(codebuddyMdPath, generateCODEBUDDYMdContent(profile));
         result.created.push('.codebuddy/CODEBUDDY.md');
     }
     else {
         result.skipped.push('.codebuddy/CODEBUDDY.md (already exists)');
     }
-    // Create hooks.json
+    // Create AGENTS.md at PROJECT ROOT — cross-CLI convention.
+    // Read by Claude Code, Gemini CLI 0.20+, Cursor, Codex, and Code Buddy
+    // itself (see jit-context.ts and bootstrap-loader.ts). Lives at the
+    // root, NOT in `.codebuddy/`, because the convention dictates root.
+    // This file is meant to be committed (the .gitignore generated below
+    // only ignores `.codebuddy/`, not AGENTS.md).
+    const agentsMdPath = path.join(workingDirectory, 'AGENTS.md');
+    if (!fs.existsSync(agentsMdPath) || options.force) {
+        fs.writeFileSync(agentsMdPath, generateAgentsMdContent(profile));
+        result.created.push('AGENTS.md');
+    }
+    else {
+        result.skipped.push('AGENTS.md (already exists)');
+    }
+    // Create hooks.json (uses profile commands when available)
     if (options.includeHooks !== false) {
         const hooksPath = path.join(codebuddyDir, 'hooks.json');
         if (!fs.existsSync(hooksPath) || options.force) {
+            const lintCmd = profile?.commands?.lint ?? 'npm run lint';
+            const testCmd = profile?.commands?.test ?? 'npm test';
+            const typecheckCmd = profile?.commands?.typecheck ?? profile?.commands?.validate ?? 'npm run typecheck';
+            const formatCmd = profile?.commands?.format ?? 'prettier --write {file}';
             const hooksContent = {
                 enabled: true,
                 globalTimeout: 30000,
                 hooks: [
                     {
                         type: 'pre-commit',
-                        command: 'npm run lint && npm test',
+                        command: `${lintCmd} && ${testCmd}`,
                         enabled: false,
                         timeout: 60000,
                         continueOnError: false,
@@ -81,7 +616,7 @@ This project is...
                     },
                     {
                         type: 'post-edit',
-                        command: 'npm run typecheck',
+                        command: typecheckCmd,
                         enabled: false,
                         timeout: 30000,
                         continueOnError: true,
@@ -89,11 +624,11 @@ This project is...
                     },
                     {
                         type: 'on-file-change',
-                        command: 'prettier --write {file}',
+                        command: formatCmd.includes('{file}') ? formatCmd : `${formatCmd} {file}`,
                         enabled: false,
                         timeout: 10000,
                         continueOnError: true,
-                        description: 'Format file with Prettier on change'
+                        description: 'Format file on change'
                     }
                 ]
             };
@@ -112,7 +647,6 @@ This project is...
                 $schema: 'https://json-schema.org/draft/2020-12/schema',
                 description: 'MCP server configuration. This file can be committed to share MCP servers with your team.',
                 mcpServers: {
-                    // Example configurations (disabled by default)
                     'filesystem': {
                         name: 'filesystem',
                         type: 'stdio',
@@ -158,14 +692,13 @@ This project is...
             result.skipped.push('.codebuddy/security.json (already exists)');
         }
     }
-    // Create commands directory with example
+    // Create commands directory with examples
     if (options.includeCommands !== false) {
         const commandsDir = path.join(codebuddyDir, 'commands');
         if (!fs.existsSync(commandsDir)) {
             fs.mkdirSync(commandsDir, { recursive: true });
             result.created.push('.codebuddy/commands/');
         }
-        // Create example command
         const exampleCommandPath = path.join(commandsDir, 'example.md');
         if (!fs.existsSync(exampleCommandPath) || options.force) {
             const exampleCommandContent = `---
@@ -187,7 +720,6 @@ Example: Analyze the file $1 and suggest improvements.
             fs.writeFileSync(exampleCommandPath, exampleCommandContent);
             result.created.push('.codebuddy/commands/example.md');
         }
-        // Create deploy command template
         const deployCommandPath = path.join(commandsDir, 'deploy.md');
         if (!fs.existsSync(deployCommandPath) || options.force) {
             const deployCommandContent = `---
@@ -215,11 +747,11 @@ Safety checks:
             result.created.push('.codebuddy/commands/deploy.md');
         }
     }
-    // Create settings.json
+    // Create settings.json (model aligned with SettingsManager default)
     const settingsPath = path.join(codebuddyDir, 'settings.json');
     if (!fs.existsSync(settingsPath) || options.force) {
         const settingsContent = {
-            model: 'grok-3-fast',
+            model: 'grok-code-fast-1',
             maxToolRounds: 400,
             theme: 'default'
         };
@@ -229,13 +761,16 @@ Safety checks:
     else {
         result.skipped.push('.codebuddy/settings.json (already exists)');
     }
-    // Update .gitignore if it exists
+    // Update .gitignore
     if (options.includeGitignore !== false) {
         const gitignorePath = path.join(workingDirectory, '.gitignore');
         const codebuddyIgnoreEntries = `
 # Code Buddy
 .codebuddy/sessions/
 .codebuddy/history/
+.codebuddy/runs/
+.codebuddy/tool-results/
+.codebuddy/cache/
 .codebuddy/user-settings.json
 `;
         if (fs.existsSync(gitignorePath)) {
@@ -262,12 +797,25 @@ This directory contains configuration and customization files for [Code Buddy](h
 
 ## Files
 
+- **CONTEXT.md** - Primary context file (highest priority, loaded first by the runtime)
 - **CODEBUDDY.md** - Custom instructions that Code Buddy follows when working in this project
 - **settings.json** - Project-specific settings
 - **hooks.json** - Automated hooks (pre-commit, post-edit, etc.)
 - **mcp.json** - MCP server configurations (committable, shared with team)
 - **security.json** - Security mode configuration
 - **commands/** - Custom slash commands
+- **knowledge/** - Domain knowledge files (frontmatter: title, tags, scope, priority)
+- **sessions/** - Saved sessions (gitignored)
+- **runs/** - Run observability logs (gitignored)
+- **tool-results/** - Cached tool outputs (gitignored)
+
+## Context Priority
+
+The runtime loads context in this order (lower number = higher priority):
+1. \`.codebuddy/CONTEXT.md\` — edit this first
+2. \`CODEBUDDY.md\` (project root)
+3. \`.codebuddy/context.md\`
+4. \`CLAUDE.md\`
 
 ## Custom Commands
 
@@ -315,34 +863,188 @@ See the [Code Buddy documentation](https://github.com/phuetz/code-buddy) for mor
     return result;
 }
 /**
- * Format init result for display
+ * Format init result for display (ASCII markers, no emojis)
  */
 export function formatInitResult(result) {
-    let output = '🚀 Code Buddy Project Initialization\n' + '═'.repeat(50) + '\n\n';
+    let output = 'Code Buddy Project Initialization\n' + '='.repeat(50) + '\n\n';
     if (result.created.length > 0) {
-        output += '✅ Created:\n';
+        output += '[+] Created:\n';
         for (const item of result.created) {
-            output += `   • ${item}\n`;
+            output += `    ${item}\n`;
         }
         output += '\n';
     }
     if (result.skipped.length > 0) {
-        output += '⏭️  Skipped:\n';
+        output += '[=] Skipped (already exists):\n';
         for (const item of result.skipped) {
-            output += `   • ${item}\n`;
+            output += `    ${item}\n`;
         }
         output += '\n';
     }
     if (result.errors.length > 0) {
-        output += '❌ Errors:\n';
+        output += '[!] Errors:\n';
         for (const item of result.errors) {
-            output += `   • ${item}\n`;
+            output += `    ${item}\n`;
         }
         output += '\n';
     }
-    output += '─'.repeat(50) + '\n';
-    output += '💡 Edit .codebuddy/CODEBUDDY.md to customize Code Buddy for this project\n';
-    output += '📚 See .codebuddy/README.md for documentation';
+    output += '-'.repeat(50) + '\n';
+    output += 'Next steps:\n';
+    output += '  1. Edit .codebuddy/CONTEXT.md  -- primary context (loaded first by the runtime)\n';
+    output += '  2. Edit .codebuddy/CODEBUDDY.md -- additional custom instructions\n';
+    output += '  3. Run \'buddy doctor\' to verify your environment\n';
+    output += '  4. Add files to .codebuddy/knowledge/ for domain-specific context\n';
+    output += '  5. Use /starter to browse framework starter packs for new projects\n';
     return output;
 }
+// ============================================================================
+// Data flow renderer — shows how key components connect
+// ============================================================================
+function renderDataFlow(carto, profile) {
+    if (!profile)
+        return null;
+    const hasUI = carto.importGraph.hotModules.some(m => /\b(ui|components|views|pages|app)\b/i.test(m.module));
+    const hasAgent = carto.components?.agents?.length || carto.importGraph.hotModules.some(m => /\bagent\b/i.test(m.module));
+    const hasTools = (carto.components?.tools?.length ?? 0) > 0;
+    const hasMiddleware = (carto.components?.middlewares?.length ?? 0) > 0;
+    const hasChannels = (carto.components?.channels?.length ?? 0) > 0;
+    const hasAPI = carto.apiSurface.endpointCount > 0;
+    // Only render if there's enough structure to show a meaningful flow
+    if (!hasAgent && !hasAPI && !hasMiddleware)
+        return null;
+    const lines = ['## Data Flow'];
+    // Build ASCII flow diagram based on detected components
+    if (hasUI || hasChannels || hasAPI) {
+        const flowParts = [];
+        // Entry points
+        if (hasUI)
+            flowParts.push('User Input');
+        if (hasChannels)
+            flowParts.push('Channel Message');
+        if (hasAPI)
+            flowParts.push('HTTP/WS Request');
+        const entry = flowParts.length > 1
+            ? `{ ${flowParts.join(' | ')} }`
+            : flowParts[0] ?? 'Input';
+        // Core processing
+        const coreParts = [];
+        if (hasMiddleware)
+            coreParts.push('Middleware Pipeline');
+        if (hasAgent)
+            coreParts.push('Agent Loop');
+        if (hasTools)
+            coreParts.push('Tool Execution');
+        const core = coreParts.join(' → ');
+        lines.push('');
+        lines.push('```');
+        lines.push(`${entry} → ${core} → Response`);
+        lines.push('```');
+    }
+    // Describe entry points with their files
+    const entryFiles = [];
+    const hotModules = carto.importGraph.hotModules;
+    // Find CLI/entry point
+    if (profile.entryPoints?.length) {
+        for (const ep of profile.entryPoints) {
+            entryFiles.push(`- **Entry:** \`${ep}\``);
+        }
+    }
+    // Find agent core (most-imported agent module)
+    const agentMod = hotModules.find(m => /\bagent\b/i.test(m.module));
+    if (agentMod) {
+        entryFiles.push(`- **Agent core:** \`${agentMod.module}\` (hub for ${agentMod.importedBy} modules)`);
+    }
+    // Find UI layer
+    const uiMod = hotModules.find(m => /\b(ui|components|app)\b/i.test(m.module));
+    if (uiMod) {
+        entryFiles.push(`- **UI layer:** \`${uiMod.module}\` (used by ${uiMod.importedBy} modules)`);
+    }
+    // Find type system
+    const typesMod = hotModules.find(m => /\btypes?\b/i.test(m.module) && !m.module.includes('registry'));
+    if (typesMod) {
+        entryFiles.push(`- **Type system:** \`${typesMod.module}\` (shared by ${typesMod.importedBy} modules)`);
+    }
+    if (entryFiles.length > 0) {
+        lines.push('');
+        lines.push('**Key connection points:**');
+        lines.push(...entryFiles);
+    }
+    return lines.length > 1 ? lines.join('\n') : null;
+}
+// ============================================================================
+// Component inventory renderer (V2 cartography)
+// ============================================================================
+function renderComponentInventory(comp) {
+    const sections = [];
+    // Facades (architecture backbone)
+    if (comp.facades.length > 0) {
+        const lines = ['**Facade architecture:**'];
+        for (const f of comp.facades) {
+            lines.push(`- \`${f.name}\` — \`${f.file}\``);
+        }
+        sections.push(lines.join('\n'));
+    }
+    // Middleware pipeline (with priorities)
+    if (comp.middlewares.length > 0) {
+        const lines = ['**Middleware pipeline:**', '', '| Priority | Middleware | File |', '|----------|-----------|------|'];
+        for (const m of comp.middlewares) {
+            const prio = m.priority != null ? String(m.priority) : '—';
+            lines.push(`| ${prio} | ${m.name} | \`${m.file}\` |`);
+        }
+        sections.push(lines.join('\n'));
+    }
+    // Specialized agents
+    if (comp.agents.length > 0) {
+        const lines = [`**Specialized agents (${comp.agents.length}):**`];
+        for (const a of comp.agents) {
+            lines.push(`- \`${a.name}\` — \`${a.file}\``);
+        }
+        sections.push(lines.join('\n'));
+    }
+    // Tool classes — with file paths for navigation
+    if (comp.tools.length > 0) {
+        if (comp.tools.length <= 25) {
+            const lines = [`**Tool classes (${comp.tools.length}):**`];
+            for (const t of comp.tools) {
+                lines.push(`- \`${t.name}\` — \`${t.file}\``);
+            }
+            sections.push(lines.join('\n'));
+        }
+        else {
+            // Too many — show first 20 with files, rest as names only
+            const lines = [`**Tool classes (${comp.tools.length}):**`];
+            for (const t of comp.tools.slice(0, 20)) {
+                lines.push(`- \`${t.name}\` — \`${t.file}\``);
+            }
+            lines.push(`- + ${comp.tools.length - 20} more in \`src/tools/\``);
+            sections.push(lines.join('\n'));
+        }
+    }
+    // Channels — with file paths for navigation
+    if (comp.channels.length > 0) {
+        const lines = [`**Channel adapters (${comp.channels.length}):**`];
+        for (const ch of comp.channels) {
+            lines.push(`- \`${ch.name}\` — \`${ch.file}\``);
+        }
+        sections.push(lines.join('\n'));
+    }
+    // Key exports per module (compact, top 12)
+    if (comp.keyExports.length > 0) {
+        const lines = ['**Key exports per module:**'];
+        for (const mod of comp.keyExports.slice(0, 12)) {
+            lines.push(`- **${mod.module}**: ${mod.exports.map((e) => `\`${e}\``).join(', ')}`);
+        }
+        sections.push(lines.join('\n'));
+    }
+    if (sections.length === 0)
+        return null;
+    return `## Component Map\n\n${sections.join('\n\n')}`;
+}
+/** Format a number with locale grouping (e.g., 1257 → "1,257") */
+function formatNumber(n) {
+    if (n >= 1000) {
+        return `${Math.round(n / 1000 * 10) / 10}K`.replace('.0K', 'K');
+    }
+    return String(n);
+}
 //# sourceMappingURL=init-project.js.map