@ekkos/cli 1.4.1 → 1.5.0

package/dist/index.js

@@ -67,6 +67,7 @@ commander_1.program
     `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos codex')}                        ${chalk_1.default.gray('Start Codex (OpenAI) mode')}`,
     `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos daemon start')}                 ${chalk_1.default.gray('Start the background mobile sync service')}`,
     `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos docs watch')}                   ${chalk_1.default.gray('Keep local ekkOS_CONTEXT.md files updated on disk')}`,
+    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos cortex workspaces')}             ${chalk_1.default.gray('Manage projects watched by the background guardian')}`,
     `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos connect gemini')}               ${chalk_1.default.gray('Securely store your Gemini API key in the cloud')}`,
     `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos agent create --path ./repo')}   ${chalk_1.default.gray('Spawn a headless remote agent in a directory')}`,
     `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos run --dashboard')}              ${chalk_1.default.gray('Launch Claude with live usage dashboard')}`,
@@ -169,7 +170,6 @@ commander_1.program
                 icon: '▸',
                 commands: [
                     { name: 'agent', desc: 'Manage remote headless agents (create, list, stop)' },
-                    { name: 'swarm', desc: 'Parallel workers, Q-learning routing, and swarm dashboard' },
                 ],
             },
             {
@@ -264,6 +264,8 @@ docsCmd
     .option('--poll-interval-ms <ms>', 'Polling interval fallback in milliseconds', (value) => parseInt(value, 10))
     .option('--debounce-ms <ms>', 'Debounce window before recompiling in milliseconds', (value) => parseInt(value, 10))
     .option('--no-seed', 'Do not seed the platform registry while watching')
+    .option('--rich', 'Perform server-side semantic analysis for rich insights (Directive Audit, Cascade Analysis, Entity Extraction)', true)
+    .option('--no-rich', 'Disable server-side semantic analysis')
     .action(async (options) => {
     const { watchLivingDocs } = await Promise.resolve().then(() => __importStar(require('./commands/living-docs')));
     watchLivingDocs({
@@ -272,8 +274,30 @@ docsCmd
         pollIntervalMs: options.pollIntervalMs,
         debounceMs: options.debounceMs,
         noSeed: options.seed === false,
+        rich: options.rich !== false,
     });
 });
+docsCmd
+    .command('workspaces')
+    .description('Manage projects watched by the Cortex background guardian')
+    .option('-l, --list', 'List all currently watched workspaces')
+    .option('-a, --add <path>', 'Add a new workspace to watch')
+    .option('-r, --remove <path>', 'Stop watching a workspace')
+    .action(async (options) => {
+    const { listWorkspaces, addWorkspace, removeWorkspace, manageWorkspaces } = await Promise.resolve().then(() => __importStar(require('./commands/workspaces')));
+    if (options.list) {
+        await listWorkspaces();
+    }
+    else if (options.add) {
+        await addWorkspace(path.resolve(options.add));
+    }
+    else if (options.remove) {
+        await removeWorkspace(path.resolve(options.remove));
+    }
+    else {
+        await manageWorkspaces();
+    }
+});
 docsCmd
     .command('setup-ci')
     .description('Generate a GitHub Actions workflow to automatically validate Cortex docs on PRs')
@@ -535,88 +559,14 @@ commander_1.program
         }
     }
 });
-// Deprecated setup command (redirects to init) — hidden from root help by custom formatHelp
+// Logout command
 commander_1.program
-    .command('setup')
-    .description('[DEPRECATED] Use "ekkos init" instead')
-    .option('-i, --ide <ide>', 'IDE to setup')
-    .option('-k, --key <key>', 'ekkOS API key')
+    .command('logout')
+    .description('Log out of ekkOS (clear API credentials)')
+    .option('-a, --all', 'Also clear Synk mobile sync credentials')
     .action(async (options) => {
-    console.log('');
-    console.log(chalk_1.default.yellow('⚠️  The "setup" command is deprecated.'));
-    console.log(chalk_1.default.yellow('   Please use "ekkos init" instead.'));
-    console.log('');
-    console.log(chalk_1.default.gray('Running init with your options...'));
-    console.log('');
-    // Forward to init
-    const { init } = await Promise.resolve().then(() => __importStar(require('./commands/init')));
-    await init({
-        ide: options.ide,
-        key: options.key
-    });
-});
-// Swarm command - manage Q-learning routing
-const swarmCmd = commander_1.program
-    .command('swarm')
-    .description('Manage Swarm Q-learning model routing');
-swarmCmd
-    .command('status')
-    .description('Show Q-table stats (states, visits, epsilon, top actions)')
-    .action(async () => { const { swarmStatus } = await Promise.resolve().then(() => __importStar(require('./commands/swarm'))); swarmStatus(); });
-swarmCmd
-    .command('reset')
-    .description('Clear Q-table from Redis (routing reverts to static rules)')
-    .action(async () => { const { swarmReset } = await Promise.resolve().then(() => __importStar(require('./commands/swarm'))); swarmReset(); });
-swarmCmd
-    .command('export')
-    .description('Export Q-table to .swarm/q-learning-model.json')
-    .action(async () => { const { swarmExport } = await Promise.resolve().then(() => __importStar(require('./commands/swarm'))); swarmExport(); });
-swarmCmd
-    .command('import')
-    .description('Import Q-table from .swarm/q-learning-model.json into Redis')
-    .action(async () => { const { swarmImport } = await Promise.resolve().then(() => __importStar(require('./commands/swarm'))); swarmImport(); });
-swarmCmd
-    .command('launch')
-    .description('Launch parallel workers on a decomposed task (opens wizard if --task is omitted)')
-    .option('-w, --workers <count>', 'Number of parallel workers (2-8)', parseInt)
-    .option('-t, --task <task>', 'Task description to decompose and execute')
-    .option('--no-bypass', 'Disable bypass permissions mode')
-    .option('--no-decompose', 'Skip AI decomposition (send same task to all workers)')
-    .option('--no-queen', 'Skip launching the Python Queen coordinator')
-    .option('--queen-strategy <strategy>', 'Queen strategy (adaptive-default, hierarchical-cascade, mesh-consensus)')
-    .option('-v, --verbose', 'Show debug output')
-    .action(async (options) => {
-    // Auto-open wizard when --task is missing
-    if (!options.task) {
-        const { swarmSetup } = await Promise.resolve().then(() => __importStar(require('./commands/swarm-setup')));
-        swarmSetup();
-        return;
-    }
-    const { swarmLaunch } = await Promise.resolve().then(() => __importStar(require('./commands/swarm')));
-    swarmLaunch({
-        workers: options.workers || 4,
-        task: options.task,
-        bypass: options.bypass !== false,
-        noDecompose: options.decompose === false,
-        noQueen: options.queen === false,
-        queenStrategy: options.queenStrategy,
-        verbose: options.verbose,
-    });
-});
-swarmCmd
-    .command('setup')
-    .description('Interactive TUI wizard for configuring and launching a swarm')
-    .action(async () => {
-    const { swarmSetup } = await Promise.resolve().then(() => __importStar(require('./commands/swarm-setup')));
-    swarmSetup();
-});
-swarmCmd
-    .command('swarm-dashboard')
-    .description('Live swarm dashboard')
-    .allowUnknownOption()
-    .action(async () => {
-    const { swarmDashboardCommand } = await Promise.resolve().then(() => __importStar(require('./commands/swarm-dashboard')));
-    swarmDashboardCommand.parse(process.argv.slice(3));
+    const { logout } = await Promise.resolve().then(() => __importStar(require('./commands/logout')));
+    await logout({ all: options.all });
 });
 // --- Remote & Agent Wrapper Helpers ---
 function runRemoteCommand(command, ...args) {
@@ -654,7 +604,20 @@ commander_1.program
     .command('codex')
     .description('Launch Codex (OpenAI) with mobile control')
     .allowUnknownOption()
-    .action(() => runRemoteCommand('synk', 'codex', ...process.argv.slice(3)));
+    .action(async () => {
+    const crypto = await Promise.resolve().then(() => __importStar(require('crypto')));
+    const { getConfig, uuidToWords } = await Promise.resolve().then(() => __importStar(require('./utils/state')));
+    const { buildProxyUrl } = await Promise.resolve().then(() => __importStar(require('./utils/proxy-url')));
+    const sessionId = process.env.CLAUDE_SESSION_ID || crypto.randomBytes(8).toString('hex');
+    const sessionName = process.env.CLAUDE_SESSION_NAME || uuidToWords(sessionId);
+    const config = await getConfig();
+    if (config?.userId) {
+        process.env.OPENAI_BASE_URL = buildProxyUrl(config.userId, sessionName, process.cwd(), sessionId);
+        process.env.CLAUDE_SESSION_ID = sessionId;
+        process.env.CLAUDE_SESSION_NAME = sessionName;
+    }
+    return runRemoteCommand('synk', 'codex', ...process.argv.slice(3));
+});
 commander_1.program
     .command('acp')
     .description('Launch a generic ACP-compatible agent')
@@ -692,10 +655,46 @@ if (helpIdx !== -1) {
     process.argv[helpIdx] = '--help';
 }
 // Default to `run` if no command specified (e.g. `ekkos`, `ekkos -b --dashboard`)
-const knownCommands = commander_1.program.commands.map(c => c.name());
+const knownCommands = commander_1.program.commands.flatMap(c => [c.name(), ...c.aliases()]);
 const userArgs = process.argv.slice(2);
 const hasCommand = userArgs.some(a => knownCommands.includes(a) || a === 'help' || a === '--help' || a === '-h' || a === '--version' || a === '-V');
 if (!hasCommand) {
     process.argv.splice(2, 0, 'run');
 }
 commander_1.program.parse();
+// ── Auto-register workspace with local daemon ──────────────────────────────
+// This ensures that simply running `ekkos` once in a directory is enough to
+// activate the universal background watcher for that project.
+void (async () => {
+    try {
+        const { getDaemonPortPath } = await Promise.resolve().then(() => __importStar(require('./utils/paths')));
+        const portPath = getDaemonPortPath();
+        if (!fs.existsSync(portPath))
+            return;
+        const port = fs.readFileSync(portPath, 'utf-8').trim();
+        if (!port || isNaN(Number(port)))
+            return;
+        // Resolve the workspace path - prefer git root, fallback to cwd
+        let workspacePath = process.cwd();
+        try {
+            const { getRepoRoot } = await Promise.resolve().then(() => __importStar(require('./local/git-utils')));
+            const gitRoot = getRepoRoot(workspacePath);
+            if (gitRoot)
+                workspacePath = gitRoot;
+        }
+        catch {
+            // ignore git errors
+        }
+        // Fire-and-forget signal to local daemon
+        void fetch(`http://127.0.0.1:${port}/register-workspace`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ path: workspacePath }),
+        }).catch(() => {
+            // Daemon might be starting up or port is stale - ignore
+        });
+    }
+    catch {
+        // Non-fatal
+    }
+})();

package/dist/local/diff-engine.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Cortex Diff Engine
+ * Responsible for extracting and compressing code changes for semantic analysis.
+ */
+export interface SemanticDiffOptions {
+    repoRoot: string;
+    directoryPath: string;
+    maxTokens?: number;
+}
+export interface SemanticDiffResult {
+    rawDiff: string;
+    isCompressed: boolean;
+    summary?: string;
+}
+/**
+ * Extracts a diff that is safe for LLM consumption.
+ * Respects .ekkosignore and performs compression if needed.
+ */
+export declare function getSemanticDiff(options: SemanticDiffOptions): Promise<SemanticDiffResult>;

package/dist/local/diff-engine.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSemanticDiff = getSemanticDiff;
+const git_utils_js_1 = require("./git-utils.js");
+/**
+ * Extracts a diff that is safe for LLM consumption.
+ * Respects .ekkosignore and performs compression if needed.
+ */
+async function getSemanticDiff(options) {
+    const { repoRoot, directoryPath } = options;
+    // 1. Get the uncommitted diff first
+    let rawDiff = (0, git_utils_js_1.getUncommittedDiff)(repoRoot, directoryPath);
+    // 2. If no uncommitted changes, check the most recent commit
+    if (!rawDiff) {
+        // This is useful if the user just committed but hasn't pushed yet
+        rawDiff = (0, git_utils_js_1.getRecentCommitDiff)(repoRoot, directoryPath);
+    }
+    if (!rawDiff) {
+        console.log(`[DiffEngine] No changes found in ${directoryPath} (checked uncommitted and last commit)`);
+        return { rawDiff: '', isCompressed: false };
+    }
+    // 3. Check if we need to compress (simple heuristic: > 20,000 chars)
+    if (rawDiff.length > 20000) {
+        return {
+            rawDiff: compressDiff(rawDiff),
+            isCompressed: true,
+            summary: generateDiffSummary(rawDiff)
+        };
+    }
+    return { rawDiff, isCompressed: false };
+}
+/**
+ * Compresses a large diff by extracting only the changed lines and minimal context.
+ * This saves tokens while preserving semantic intent.
+ */
+function compressDiff(diff) {
+    const lines = diff.split('\n');
+    const compressed = [];
+    let currentFile = '';
+    let inHunk = false;
+    for (const line of lines) {
+        if (line.startsWith('diff --git')) {
+            currentFile = line.split(' ').pop() || '';
+            compressed.push(line);
+            inHunk = false;
+        }
+        else if (line.startsWith('@@')) {
+            compressed.push(line);
+            inHunk = true;
+        }
+        else if (line.startsWith('+') || line.startsWith('-')) {
+            compressed.push(line);
+        }
+        else if (inHunk && compressed.length < 1000) {
+            // Include limited context lines if we have space
+            // For now, let's keep it very aggressive and skip context
+        }
+    }
+    return compressed.join('\n');
+}
+/**
+ * Generates a high-level summary of a massive diff (Phase 1: Basic AST-ish summary).
+ */
+function generateDiffSummary(diff) {
+    const lines = diff.split('\n');
+    const filesChanged = new Set();
+    let additions = 0;
+    let deletions = 0;
+    for (const line of lines) {
+        if (line.startsWith('+++ b/')) {
+            filesChanged.add(line.replace('+++ b/', ''));
+        }
+        else if (line.startsWith('+') && !line.startsWith('+++')) {
+            additions++;
+        }
+        else if (line.startsWith('-') && !line.startsWith('---')) {
+            deletions++;
+        }
+    }
+    return `Massive change: ${filesChanged.size} files, +${additions} / -${deletions} lines. Diff was compressed for analysis.`;
+}

package/dist/local/entity-extractor.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Cortex Entity Extractor
+ * Scans code changes for key Technologies, Concepts, and Architectural Patterns.
+ * Seeds the ekkOS Knowledge Graph with high-fidelity local data.
+ */
+export interface ExtractedEntities {
+    technologies: string[];
+    concepts: string[];
+    patterns: string[];
+}
+/**
+ * Extracts entities from a code diff.
+ */
+export declare function extractEntitiesFromDiff(diff: string): ExtractedEntities;
+/**
+ * Higher-fidelity extraction: Scan specific file extensions for stack-specific entities.
+ */
+export declare function extractStackEntities(files: string[]): string[];

package/dist/local/entity-extractor.js

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * Cortex Entity Extractor
+ * Scans code changes for key Technologies, Concepts, and Architectural Patterns.
+ * Seeds the ekkOS Knowledge Graph with high-fidelity local data.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractEntitiesFromDiff = extractEntitiesFromDiff;
+exports.extractStackEntities = extractStackEntities;
+const TECH_KEYWORDS = [
+    'Zustand', 'React', 'Redis', 'Supabase', 'Postgres', 'Next.js', 'Vercel',
+    'Tailwind', 'Zod', 'Prisma', 'BullMQ', 'QStash', 'Upstash', 'OpenAI', 'Gemini',
+    'Claude', 'Neo4j', 'Fastify', 'Express', 'Tauri', 'Electron', 'SQLite',
+    'TypeScript', 'Rust', 'Python', 'Go', 'Docker', 'Kubernetes', 'AWS', 'GCP',
+    'Azure', 'GitHub Actions', 'Prometheus', 'Grafana', 'Sentry', 'LogSnag'
+];
+const CONCEPT_KEYWORDS = [
+    'Reactivity', 'State Management', 'Polling', 'Caching', 'Authentication',
+    'Authorization', 'Rate Limiting', 'Streaming', 'Batching', 'Concurrency',
+    'Event Driven', 'Serverless', 'Edge Computing', 'Memory Layer', 'Context Injection',
+    'Semantic Search', 'Vector Embedding', 'LLM Inference', 'Agent Orchestration'
+];
+const PATTERN_KEYWORDS = [
+    'Golden Loop', 'Directive Pre-Flight', 'Cascade Analysis', 'Cortex Watch',
+    'Living Docs', 'Auto-Forge', 'Knowledge Graph', 'GraphRAG', 'Agentic Workflow',
+    'Model Context Protocol', 'MCP', 'Tool Execution', 'System Instruction'
+];
+/**
+ * Extracts entities from a code diff.
+ */
+function extractEntitiesFromDiff(diff) {
+    const result = {
+        technologies: [],
+        concepts: [],
+        patterns: []
+    };
+    // Case-insensitive regex scan
+    const scan = (keywords, target) => {
+        for (const keyword of keywords) {
+            const regex = new RegExp(`\\b${keyword}\\b`, 'gi');
+            if (regex.test(diff)) {
+                target.push(keyword);
+            }
+        }
+    };
+    scan(TECH_KEYWORDS, result.technologies);
+    scan(CONCEPT_KEYWORDS, result.concepts);
+    scan(PATTERN_KEYWORDS, result.patterns);
+    return result;
+}
+/**
+ * Higher-fidelity extraction: Scan specific file extensions for stack-specific entities.
+ */
+function extractStackEntities(files) {
+    const stacks = [];
+    if (files.some(f => f.endsWith('.ts') || f.endsWith('.tsx')))
+        stacks.push('TypeScript');
+    if (files.some(f => f.endsWith('.py')))
+        stacks.push('Python');
+    if (files.some(f => f.endsWith('.rs')))
+        stacks.push('Rust');
+    if (files.some(f => f.endsWith('.go')))
+        stacks.push('Go');
+    if (files.some(f => f.endsWith('.sql')))
+        stacks.push('SQL');
+    return stacks;
+}

package/dist/local/git-utils.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Common Git Utilities for ekkOS Cortex
+ */
+/**
+ * Formats a timestamp into a specific timezone string.
+ * Lifted from LivingDocsManager for central usage.
+ */
+export declare function formatZonedTimestamp(value: Date | string | number, timeZone: string): string;
+/**
+ * Reads recent git changes for a specific directory.
+ */
+export declare function readRecentGitChanges(repoRoot: string, directoryPath: string, timeZone: string, maxDays?: number): Array<{
+    date: string;
+    message: string;
+    timestamp: string;
+}>;
+/**
+ * Gets the raw diff for uncommitted changes in a specific directory.
+ * Filters out ekkOS context files and non-code files (if possible via git).
+ */
+export declare function getUncommittedDiff(repoRoot: string, directoryPath: string): string;
+/**
+ * Gets the diff for the most recent commit.
+ */
+export declare function getRecentCommitDiff(repoRoot: string, directoryPath: string): string;
+/**
+ * Checks if the current directory is a git repository.
+ */
+export declare function isGitRepo(dir: string): boolean;
+/**
+ * Gets the timestamp of the last commit for a specific directory.
+ */
+export declare function getLastCommitTimestamp(repoRoot: string, directoryPath: string): number | null;
+/**
+ * Gets the absolute path to the git repository root.
+ */
+export declare function getRepoRoot(dir: string): string | null;

package/dist/local/git-utils.js

@@ -0,0 +1,169 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatZonedTimestamp = formatZonedTimestamp;
+exports.readRecentGitChanges = readRecentGitChanges;
+exports.getUncommittedDiff = getUncommittedDiff;
+exports.getRecentCommitDiff = getRecentCommitDiff;
+exports.isGitRepo = isGitRepo;
+exports.getLastCommitTimestamp = getLastCommitTimestamp;
+exports.getRepoRoot = getRepoRoot;
+const child_process_1 = require("child_process");
+/**
+ * Common Git Utilities for ekkOS Cortex
+ */
+/**
+ * Formats a timestamp into a specific timezone string.
+ * Lifted from LivingDocsManager for central usage.
+ */
+function formatZonedTimestamp(value, timeZone) {
+    const date = value instanceof Date ? value : new Date(value);
+    if (Number.isNaN(date.getTime()))
+        return new Date().toISOString();
+    const parts = new Intl.DateTimeFormat('en-US', {
+        timeZone,
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+        hourCycle: 'h23',
+    }).formatToParts(date);
+    const map = Object.fromEntries(parts
+        .filter(part => part.type !== 'literal')
+        .map(part => [part.type, part.value]));
+    const asUtc = Date.UTC(Number(map.year), Number(map.month) - 1, Number(map.day), Number(map.hour), Number(map.minute), Number(map.second), date.getUTCMilliseconds());
+    const offsetMinutes = Math.round((asUtc - date.getTime()) / 60000);
+    const zoned = new Date(date.getTime() + offsetMinutes * 60000);
+    const sign = offsetMinutes >= 0 ? '+' : '-';
+    const absOffset = Math.abs(offsetMinutes);
+    const pad = (num, width = 2) => num.toString().padStart(width, '0');
+    return [
+        `${pad(zoned.getUTCFullYear(), 4)}-${pad(zoned.getUTCMonth() + 1)}-${pad(zoned.getUTCDate())}`,
+        `T${pad(zoned.getUTCHours())}:${pad(zoned.getUTCMinutes())}:${pad(zoned.getUTCSeconds())}.${pad(zoned.getUTCMilliseconds(), 3)}`,
+        `${sign}${pad(Math.floor(absOffset / 60))}:${pad(absOffset % 60)}`,
+    ].join('');
+}
+/**
+ * Reads recent git changes for a specific directory.
+ */
+function readRecentGitChanges(repoRoot, directoryPath, timeZone, maxDays = 7) {
+    try {
+        const scope = directoryPath === '.' ? '.' : directoryPath;
+        const output = (0, child_process_1.execSync)(`git -C ${JSON.stringify(repoRoot)} log --max-count=15 --since="${maxDays} days ago" --pretty=format:"%ct%x09%s%x09%b" --stat -- ${JSON.stringify(scope)} ':!**/ekkOS_CONTEXT.md'`, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 1024 * 64 }).trim();
+        if (!output)
+            return [];
+        const entries = [];
+        const blocks = output.split(/\n(?="\d+\t)/);
+        for (const block of blocks) {
+            const lines = block.split('\n');
+            const header = (lines[0] || '').replace(/^"|"$/g, '');
+            const parts = header.split('\t');
+            const epochSeconds = parts[0];
+            const subject = parts[1] || '';
+            const body = (parts[2] || '').trim();
+            const epochMs = Number(epochSeconds || '0') * 1000;
+            if (!epochMs)
+                continue;
+            const changedFiles = [];
+            for (let i = 1; i < lines.length; i++) {
+                const statMatch = lines[i].match(/^\s*(.+?)\s*\|\s*\d+/);
+                if (statMatch) {
+                    const filePath = statMatch[1].trim();
+                    if (scope === '.' || filePath.startsWith(scope + '/') || filePath.startsWith(scope.replace(/^\.\//, '') + '/')) {
+                        const shortName = filePath.split('/').pop() || filePath;
+                        changedFiles.push(shortName);
+                    }
+                }
+            }
+            const timestamp = formatZonedTimestamp(new Date(epochMs), timeZone);
+            let message = subject || 'Updated local code';
+            if (changedFiles.length > 0) {
+                message += ` — files: ${changedFiles.slice(0, 5).join(', ')}${changedFiles.length > 5 ? ` +${changedFiles.length - 5} more` : ''}`;
+            }
+            if (body && !body.toLowerCase().startsWith(subject.toLowerCase().slice(0, 20))) {
+                const bodyFirstLine = body.split('\n')[0].slice(0, 120);
+                if (bodyFirstLine.length > 10) {
+                    message += ` | ${bodyFirstLine}`;
+                }
+            }
+            entries.push({
+                date: timestamp,
+                timestamp,
+                message,
+            });
+        }
+        return entries;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Gets the raw diff for uncommitted changes in a specific directory.
+ * Filters out ekkOS context files and non-code files (if possible via git).
+ */
+function getUncommittedDiff(repoRoot, directoryPath) {
+    try {
+        const scope = directoryPath === '.' ? '.' : directoryPath;
+        // We filter out ekkOS_CONTEXT.md and lockfiles locally to save tokens
+        const command = `git -C ${JSON.stringify(repoRoot)} diff HEAD -- ${JSON.stringify(scope)} ':!**/ekkOS_CONTEXT.md' ':!**/package-lock.json' ':!**/pnpm-lock.yaml' ':!**/yarn.lock'`;
+        const diff = (0, child_process_1.execSync)(command, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 1024 * 1024 * 2 }).trim();
+        return diff;
+    }
+    catch (err) {
+        console.error(`[GitUtils] Failed to get uncommitted diff in ${directoryPath}:`, err.message);
+        return '';
+    }
+}
+/**
+ * Gets the diff for the most recent commit.
+ */
+function getRecentCommitDiff(repoRoot, directoryPath) {
+    try {
+        const scope = directoryPath === '.' ? '.' : directoryPath;
+        const command = `git -C ${JSON.stringify(repoRoot)} diff @~1..@ -- ${JSON.stringify(scope)} ':!**/ekkOS_CONTEXT.md' ':!**/package-lock.json' ':!**/pnpm-lock.yaml' ':!**/yarn.lock'`;
+        const diff = (0, child_process_1.execSync)(command, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 1024 * 1024 * 2 }).trim();
+        return diff;
+    }
+    catch (err) {
+        console.error(`[GitUtils] Failed to get recent commit diff in ${directoryPath}:`, err.message);
+        return '';
+    }
+}
+/**
+ * Checks if the current directory is a git repository.
+ */
+function isGitRepo(dir) {
+    try {
+        (0, child_process_1.execSync)(`git -C ${JSON.stringify(dir)} rev-parse --is-inside-work-tree`, { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Gets the timestamp of the last commit for a specific directory.
+ */
+function getLastCommitTimestamp(repoRoot, directoryPath) {
+    try {
+        const scope = directoryPath === '.' ? '.' : directoryPath;
+        const raw = (0, child_process_1.execSync)(`git -C ${JSON.stringify(repoRoot)} log --max-count=1 --pretty=format:%ct -- ${JSON.stringify(scope)} ':!**/ekkOS_CONTEXT.md'`, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+        return raw ? Number(raw) * 1000 : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Gets the absolute path to the git repository root.
+ */
+function getRepoRoot(dir) {
+    try {
+        return (0, child_process_1.execSync)(`git -C ${JSON.stringify(dir)} rev-parse --show-toplevel`, { encoding: 'utf-8' }).trim();
+    }
+    catch {
+        return null;
+    }
+}

package/dist/local/living-docs-manager.d.ts

@@ -5,6 +5,7 @@ export interface LocalLivingDocsManagerOptions {
     timeZone?: string;
     pollIntervalMs?: number;
     flushDebounceMs?: number;
+    richAnalysis?: boolean;
     onLog?: (message: string) => void;
 }
 export declare class LocalLivingDocsManager {
@@ -14,6 +15,7 @@ export declare class LocalLivingDocsManager {
     private readonly timeZone;
     private readonly pollIntervalMs;
     private readonly flushDebounceMs;
+    private readonly richAnalysis;
     private readonly onLog?;
     private repoRoot;
     private watchRoot;
@@ -50,6 +52,10 @@ export declare class LocalLivingDocsManager {
     private compileStaleSystems;
     private collectSystemFiles;
     private compileSystem;
+    /**
+     * Calls the server-side semantic analyzer and injects rich insights into the context file.
+     */
+    private injectSemanticAnalysis;
     /**
      * Metadata-only patch for server-compiled docs.
      * Updates ONLY the approved local-mutable frontmatter fields without touching the body.