@codragraph/cli 2.1.0 → 2.1.4

package/dist/core/ingestion/model/semantic-model.js

@@ -9,7 +9,7 @@
  *
  * ## Dependency direction
  *
- *     codragraph-shared (NodeLabel)             — leaf
+ *     @codragraph/shared (NodeLabel)            — leaf
  *          ↑
  *     symbol-table.ts                         — pure file/callable index
  *          ↑

package/dist/core/ingestion/model/symbol-table.d.ts

@@ -17,7 +17,7 @@
  *
  * Dependency direction (strictly enforced):
  *
- *     codragraph-shared (NodeLabel)       — leaf type
+ *     @codragraph/shared (NodeLabel)      — leaf type
  *          ↑
  *     symbol-table.ts                   — THIS FILE (pure storage)
  *          ↑

package/dist/core/ingestion/model/symbol-table.js

@@ -17,7 +17,7 @@
  *
  * Dependency direction (strictly enforced):
  *
- *     codragraph-shared (NodeLabel)       — leaf type
+ *     @codragraph/shared (NodeLabel)      — leaf type
  *          ↑
  *     symbol-table.ts                   — THIS FILE (pure storage)
  *          ↑

package/dist/core/ingestion/pipeline-phases/feature-clusters.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Phase: featureClusters
+ *
+ * Creates human-facing FeatureCluster nodes above algorithmic Community nodes.
+ * This is the layer agents query for product/domain areas such as Settings,
+ * AI, Auth, MCP, or Ingestion before drilling into exact symbols.
+ *
+ * @deps    processes, structure
+ * @reads   graph (all nodes and relationships)
+ * @writes  graph (FeatureCluster nodes, FEATURE_MEMBER_OF, FEATURE_DEPENDS_ON)
+ */
+import type { PipelinePhase } from './types.js';
+import { type FeatureClusterDetectionResult } from '../feature-cluster-processor.js';
+export interface FeatureClustersOutput {
+    featureClusterResult: FeatureClusterDetectionResult;
+}
+export declare const featureClustersPhase: PipelinePhase<FeatureClustersOutput>;

package/dist/core/ingestion/pipeline-phases/feature-clusters.js

@@ -0,0 +1,88 @@
+/**
+ * Phase: featureClusters
+ *
+ * Creates human-facing FeatureCluster nodes above algorithmic Community nodes.
+ * This is the layer agents query for product/domain areas such as Settings,
+ * AI, Auth, MCP, or Ingestion before drilling into exact symbols.
+ *
+ * @deps    processes, structure
+ * @reads   graph (all nodes and relationships)
+ * @writes  graph (FeatureCluster nodes, FEATURE_MEMBER_OF, FEATURE_DEPENDS_ON)
+ */
+import { getPhaseOutput } from './types.js';
+import { processFeatureClusters, } from '../feature-cluster-processor.js';
+import { generateId } from '../../../lib/utils.js';
+import { isDev } from '../utils/env.js';
+export const featureClustersPhase = {
+    name: 'featureClusters',
+    deps: ['processes', 'structure'],
+    async execute(ctx, deps) {
+        const { totalFiles } = getPhaseOutput(deps, 'structure');
+        ctx.onProgress({
+            phase: 'feature_clusters',
+            percent: 99,
+            message: 'Building feature clusters...',
+            stats: { filesProcessed: totalFiles, totalFiles, nodesCreated: ctx.graph.nodeCount },
+        });
+        const featureClusterResult = await processFeatureClusters(ctx.graph, (message, progress) => {
+            ctx.onProgress({
+                phase: 'feature_clusters',
+                percent: Math.round(99 + progress * 0.009),
+                message,
+                stats: { filesProcessed: totalFiles, totalFiles, nodesCreated: ctx.graph.nodeCount },
+            });
+        }, {
+            repo: ctx.options?.featureClusterRepo,
+            lastIndexedCommit: ctx.options?.lastIndexedCommit,
+        });
+        if (isDev) {
+            console.log(`Feature clustering: ${featureClusterResult.stats.totalClusters} clusters, ${featureClusterResult.stats.totalMemberships} memberships`);
+        }
+        featureClusterResult.clusters.forEach((cluster) => {
+            ctx.graph.addNode({
+                id: cluster.id,
+                label: 'FeatureCluster',
+                properties: {
+                    name: cluster.name,
+                    filePath: '',
+                    slug: cluster.slug,
+                    featureKind: cluster.featureKind,
+                    summary: cluster.summary,
+                    description: cluster.description,
+                    repo: cluster.repo,
+                    service: cluster.service,
+                    signals: cluster.signals,
+                    memberCount: cluster.memberCount,
+                    entryPointIds: cluster.entryPointIds,
+                    routes: cluster.routes,
+                    tools: cluster.tools,
+                    testCoverageHints: cluster.testCoverageHints,
+                    lastIndexedCommit: cluster.lastIndexedCommit,
+                    confidence: cluster.confidence,
+                    source: 'heuristic',
+                },
+            });
+        });
+        featureClusterResult.memberships.forEach((membership) => {
+            ctx.graph.addRelationship({
+                id: generateId('FEATURE_MEMBER_OF', `${membership.nodeId}->${membership.clusterId}`),
+                sourceId: membership.nodeId,
+                targetId: membership.clusterId,
+                type: 'FEATURE_MEMBER_OF',
+                confidence: membership.confidence,
+                reason: membership.signals.join('|'),
+            });
+        });
+        featureClusterResult.dependencies.forEach((dependency) => {
+            ctx.graph.addRelationship({
+                id: generateId('FEATURE_DEPENDS_ON', `${dependency.sourceClusterId}->${dependency.targetClusterId}`),
+                sourceId: dependency.sourceClusterId,
+                targetId: dependency.targetClusterId,
+                type: 'FEATURE_DEPENDS_ON',
+                confidence: dependency.confidence,
+                reason: `member-dependency|edges:${dependency.edgeCount}|types:${dependency.relationshipTypes.join(',')}`,
+            });
+        });
+        return { featureClusterResult };
+    },
+};

package/dist/core/ingestion/pipeline-phases/index.d.ts

@@ -17,6 +17,7 @@ export { scopeResolutionPhase, type ScopeResolutionOutput, } from '../scope-reso
 export { mroPhase, type MROOutput } from './mro.js';
 export { communitiesPhase, type CommunitiesOutput } from './communities.js';
 export { processesPhase, type ProcessesOutput } from './processes.js';
+export { featureClustersPhase, type FeatureClustersOutput } from './feature-clusters.js';
 export { runPipeline } from './runner.js';
 export type { PipelinePhase, PipelineContext, PhaseResult } from './types.js';
 export { getPhaseOutput } from './types.js';

package/dist/core/ingestion/pipeline-phases/index.js

@@ -18,6 +18,7 @@ export { scopeResolutionPhase, } from '../scope-resolution/pipeline/phase.js';
 export { mroPhase } from './mro.js';
 export { communitiesPhase } from './communities.js';
 export { processesPhase } from './processes.js';
+export { featureClustersPhase } from './feature-clusters.js';
 // ── Infrastructure ─────────────────────────────────────────────────────────
 export { runPipeline } from './runner.js';
 export { getPhaseOutput } from './types.js';

package/dist/core/ingestion/pipeline.d.ts

@@ -21,6 +21,10 @@ export interface PipelineOptions {
     skipGraphPhases?: boolean;
     /** Force sequential parsing (no worker pool). Useful for testing the sequential path. */
     skipWorkers?: boolean;
+    /** Repo label written onto FeatureCluster metadata. */
+    featureClusterRepo?: string;
+    /** Indexed source commit written onto FeatureCluster metadata. */
+    lastIndexedCommit?: string;
     /**
      * @internal Test-only override for worker-pool gating thresholds.
      * When unset, production defaults apply (15 files OR 512 KB total bytes).

package/dist/core/ingestion/pipeline.js

@@ -15,15 +15,16 @@
  * See ARCHITECTURE.md for the full phase dependency diagram.
  */
 import { createKnowledgeGraph } from '../graph/graph.js';
-import { runPipeline, getPhaseOutput, scanPhase, structurePhase, markdownPhase, cobolPhase, parsePhase, routesPhase, toolsPhase, ormPhase, crossFilePhase, scopeResolutionPhase, mroPhase, communitiesPhase, processesPhase, } from './pipeline-phases/index.js';
+import { runPipeline, getPhaseOutput, scanPhase, structurePhase, markdownPhase, cobolPhase, parsePhase, routesPhase, toolsPhase, ormPhase, crossFilePhase, scopeResolutionPhase, mroPhase, communitiesPhase, processesPhase, featureClustersPhase, } from './pipeline-phases/index.js';
 // ── Phase registry ─────────────────────────────────────────────────────────
 /**
  * All pipeline phases with their dependency relationships.
  *
  * Phase dependency graph:
  *
- *   scan → structure → [markdown, cobol] → parse → [routes, tools, orm]
- *     → crossFile → mro → communities → processes
+ *   scan -> structure -> [markdown, cobol] -> parse -> [routes, tools, orm]
+ *     -> crossFile -> scopeResolution -> mro -> communities -> processes
+ *     -> featureClusters
  *
  * To add a new phase: create a file in pipeline-phases/, export the phase
  * object, and add it to the appropriate position in this array.
@@ -42,7 +43,7 @@ function buildPhaseList(options) {
         scopeResolutionPhase,
     ];
     if (!options?.skipGraphPhases) {
-        phases.push(mroPhase, communitiesPhase, processesPhase);
+        phases.push(mroPhase, communitiesPhase, processesPhase, featureClustersPhase);
     }
     return phases;
 }
@@ -62,15 +63,17 @@ export const runPipelineFromRepo = async (repoPath, onProgress, options) => {
     const { totalFiles, usedWorkerPool } = getPhaseOutput(results, 'parse');
     let communityResult;
     let processResult;
+    let featureClusterResult;
     if (!options?.skipGraphPhases) {
         communityResult = getPhaseOutput(results, 'communities').communityResult;
         processResult = getPhaseOutput(results, 'processes').processResult;
+        featureClusterResult = getPhaseOutput(results, 'featureClusters').featureClusterResult;
     }
     onProgress({
         phase: 'complete',
         percent: 100,
         message: communityResult && processResult
-            ? `Graph complete! ${communityResult.stats.totalCommunities} communities, ${processResult.stats.totalProcesses} processes detected.`
+            ? `Graph complete! ${communityResult.stats.totalCommunities} communities, ${processResult.stats.totalProcesses} processes, ${featureClusterResult?.stats.totalClusters ?? 0} feature clusters detected.`
             : 'Graph complete! (graph phases skipped)',
         stats: {
             filesProcessed: totalFiles,
@@ -84,6 +87,7 @@ export const runPipelineFromRepo = async (repoPath, onProgress, options) => {
         totalFileCount: totalFiles,
         communityResult,
         processResult,
+        featureClusterResult,
         usedWorkerPool,
     };
 };

package/dist/core/run-analyze.d.ts

@@ -8,6 +8,7 @@
  * IMPORTANT: This module must NEVER call process.exit(). The caller (CLI
  * wrapper or server worker) is responsible for process lifecycle.
  */
+import { type RepoMeta } from '../storage/repo-manager.js';
 import type { ContentEncoding } from '@codragraph/graphstore';
 export interface AnalyzeCallbacks {
     onProgress: (phase: string, percent: number, message: string) => void;
@@ -63,14 +64,34 @@ export interface AnalyzeResult {
         nodes?: number;
         edges?: number;
         communities?: number;
+        featureClusters?: number;
         processes?: number;
         embeddings?: number;
     };
     alreadyUpToDate?: boolean;
+    /** User-facing explanation for a reused index fast path. */
+    reuseReason?: string;
+    /** True when the git commit advanced but indexed inputs did not. */
+    reusedExistingIndex?: boolean;
     /** The raw pipeline result — only populated when needed by callers (e.g. skill generation). */
     pipelineResult?: any;
 }
+export interface AnalyzeChangedPath {
+    /** Git name-status token, e.g. M, A, D, R100. */
+    status: string;
+    /** Current path for additions/modifications, or deleted path for deletions. */
+    path: string;
+    /** Previous path for renames/copies. */
+    previousPath?: string;
+}
 export declare const PHASE_LABELS: Record<string, string>;
+export declare const parseGitNameStatus: (raw: string) => AnalyzeChangedPath[];
+export declare const listChangedPathsBetweenCommits: (repoPath: string, fromRef: string, toRef: string) => AnalyzeChangedPath[] | null;
+export declare const isGeneratedAgentContextPath: (filePath: string) => boolean;
+export declare const isGraphContentPath: (filePath: string) => boolean;
+export declare const changedPathAffectsGraph: (change: AnalyzeChangedPath) => boolean;
+export declare const getGraphRelevantChangedPaths: (changes: readonly AnalyzeChangedPath[]) => AnalyzeChangedPath[];
+export declare const getAnalyzeConfigRebuildReason: (existingMeta: Pick<RepoMeta, "compress" | "stats">, options: Pick<AnalyzeOptions, "compress" | "embeddings">) => string | null;
 /**
  * Run the full CodraGraph analysis pipeline.
  *

package/dist/core/run-analyze.js

@@ -10,18 +10,52 @@
  */
 import path from 'path';
 import fs from 'fs/promises';
+import { execFileSync } from 'node:child_process';
 import * as fsSync from 'node:fs';
 import * as v8 from 'node:v8';
+import { getLanguageFromFilename } from '../_shared/index.js';
 import { runPipelineFromRepo } from './ingestion/pipeline.js';
 import { initCgdb, loadGraphToCgdb, getCgdbStats, executeQuery, executeWithReusedStatement, closeCgdb, loadCachedEmbeddings, } from './cgdb/cgdb-adapter.js';
 import { getStoragePaths, saveMeta, loadMeta, addToGitignore, registerRepo, cleanupOldKuzuFiles, INDEX_SCHEMA_VERSION, } from '../storage/repo-manager.js';
 import { getCurrentCommit, getRemoteUrl, hasGitDir, getInferredRepoName } from '../storage/git.js';
+import { shouldIgnorePath } from '../config/ignore-service.js';
 import { recordAnalysisSnapshot } from './graphstore/index.js';
 import { generateAIContextFiles } from '../cli/ai-context.js';
 import { EMBEDDING_TABLE_NAME } from './cgdb/schema.js';
 import { STALE_HASH_SENTINEL } from './cgdb/schema.js';
 /** Threshold: auto-skip embeddings for repos with more nodes than this */
 const EMBEDDING_NODE_LIMIT = 50_000;
+const GENERATED_AGENT_CONTEXT_PATHS = new Set(['agents.md', 'claude.md']);
+const GENERATED_AGENT_CONTEXT_PREFIXES = [
+    '.claude/skills/generated/',
+    '.cursor/rules/codragraph-generated/',
+];
+const IGNORE_CONTROL_FILES = new Set(['.gitignore', '.codragraphignore']);
+const GRAPH_CONFIG_BASENAMES = new Set([
+    'package.json',
+    'tsconfig.json',
+    'jsconfig.json',
+    'go.mod',
+    'cargo.toml',
+    'pyproject.toml',
+    'requirements.txt',
+    'composer.json',
+    'gemfile',
+    'pom.xml',
+    'build.gradle',
+    'build.gradle.kts',
+    'settings.gradle',
+    'settings.gradle.kts',
+    'pubspec.yaml',
+    'pubspec.yml',
+    'mix.exs',
+    'rebar.config',
+    'cmakelists.txt',
+    'makefile',
+    'dockerfile',
+]);
+const GRAPH_CONFIG_PATTERNS = [/^tsconfig\..+\.json$/i, /^jsconfig\..+\.json$/i];
+const MARKDOWN_EXTENSIONS = new Set(['.md', '.mdx']);
 export const PHASE_LABELS = {
     extracting: 'Scanning files',
     structure: 'Building structure',
@@ -31,12 +65,126 @@ export const PHASE_LABELS = {
     heritage: 'Extracting inheritance',
     communities: 'Detecting communities',
     processes: 'Detecting processes',
+    feature_clusters: 'Building feature clusters',
     complete: 'Pipeline complete',
     cgdb: 'Loading into LadybugDB',
     fts: 'Creating search indexes',
     embeddings: 'Generating embeddings',
     done: 'Done',
 };
+const normalizeGitPath = (filePath) => filePath.replace(/\\/g, '/');
+export const parseGitNameStatus = (raw) => {
+    const tokens = raw.split('\0').filter(Boolean);
+    const changes = [];
+    for (let i = 0; i < tokens.length;) {
+        const status = tokens[i++] ?? '';
+        const code = status[0]?.toUpperCase();
+        if (code === 'R' || code === 'C') {
+            const previousPath = tokens[i++];
+            const nextPath = tokens[i++];
+            if (previousPath && nextPath) {
+                changes.push({
+                    status,
+                    path: normalizeGitPath(nextPath),
+                    previousPath: normalizeGitPath(previousPath),
+                });
+            }
+            continue;
+        }
+        const changedPath = tokens[i++];
+        if (status && changedPath) {
+            changes.push({ status, path: normalizeGitPath(changedPath) });
+        }
+    }
+    return changes;
+};
+export const listChangedPathsBetweenCommits = (repoPath, fromRef, toRef) => {
+    if (!fromRef || !toRef || fromRef === toRef)
+        return [];
+    try {
+        const stdout = execFileSync('git', ['diff', '--name-status', '-z', `${fromRef}..${toRef}`], {
+            cwd: repoPath,
+            encoding: 'utf8',
+            maxBuffer: 20 * 1024 * 1024,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        return parseGitNameStatus(stdout);
+    }
+    catch {
+        return null;
+    }
+};
+export const isGeneratedAgentContextPath = (filePath) => {
+    const normalized = normalizeGitPath(filePath).toLowerCase();
+    const basename = path.posix.basename(normalized);
+    return (GENERATED_AGENT_CONTEXT_PATHS.has(basename) ||
+        GENERATED_AGENT_CONTEXT_PREFIXES.some((prefix) => normalized.startsWith(prefix)));
+};
+export const isGraphContentPath = (filePath) => {
+    const normalized = normalizeGitPath(filePath);
+    const basename = path.posix.basename(normalized);
+    const lowerBasename = basename.toLowerCase();
+    if (isGeneratedAgentContextPath(normalized))
+        return false;
+    if (IGNORE_CONTROL_FILES.has(lowerBasename))
+        return true;
+    if (shouldIgnorePath(normalized))
+        return false;
+    if (getLanguageFromFilename(normalized) !== null)
+        return true;
+    const ext = path.posix.extname(lowerBasename);
+    if (MARKDOWN_EXTENSIONS.has(ext))
+        return true;
+    if (GRAPH_CONFIG_BASENAMES.has(lowerBasename))
+        return true;
+    return GRAPH_CONFIG_PATTERNS.some((pattern) => pattern.test(basename));
+};
+export const changedPathAffectsGraph = (change) => {
+    const statusCode = change.status[0]?.toUpperCase();
+    const paths = [change.path, change.previousPath].filter((p) => Boolean(p));
+    if (paths.some(isGraphContentPath))
+        return true;
+    // Add/delete/rename/copy can change File/Folder structure even when content
+    // is not parsed. Ignored or generated-agent paths are outside the index.
+    if (statusCode === 'A' || statusCode === 'D' || statusCode === 'R' || statusCode === 'C') {
+        return paths.some((p) => !isGeneratedAgentContextPath(p) && !shouldIgnorePath(p));
+    }
+    // Modified non-code/non-doc files keep the same path and are not read by the
+    // graph pipeline, so the existing graph can be reused.
+    if (statusCode === 'M' || statusCode === 'T')
+        return false;
+    // Unknown git status: rebuild rather than risk stale graph state.
+    return true;
+};
+export const getGraphRelevantChangedPaths = (changes) => changes.filter(changedPathAffectsGraph);
+export const getAnalyzeConfigRebuildReason = (existingMeta, options) => {
+    const existingCompress = existingMeta.compress ?? 'none';
+    if (options.compress && options.compress !== existingCompress) {
+        return `requested compression changed from ${existingCompress} to ${options.compress}`;
+    }
+    if (options.embeddings && (existingMeta.stats?.embeddings ?? 0) === 0) {
+        return 'embeddings were requested but the existing index has no vectors';
+    }
+    return null;
+};
+const formatChangeForLog = (change) => change.previousPath ? `${change.previousPath} -> ${change.path}` : change.path;
+const buildReusedMeta = (existingMeta, repoPath, currentCommit) => ({
+    ...existingMeta,
+    repoPath,
+    lastCommit: currentCommit,
+    indexedAt: new Date().toISOString(),
+    schemaVersion: INDEX_SCHEMA_VERSION,
+    remoteUrl: hasGitDir(repoPath) ? getRemoteUrl(repoPath) : existingMeta.remoteUrl,
+});
+const pathExists = async (targetPath) => {
+    try {
+        await fs.stat(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
 // ---------------------------------------------------------------------------
 // Main orchestrator
 // ---------------------------------------------------------------------------
@@ -129,14 +277,23 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
     // ── Early-return: already up to date ──────────────────────────────
     // Schema-version mismatch forces a full re-analyze regardless of commit
     // equality: existing 1.7.x indexes have no `schemaVersion` field at all,
-    // and 1.8+ readers expect every node table to carry a `contentEncoding`
-    // column (RFC 0001 Phase 2). LadybugDB ALTER on existing tables is not
-    // validated end-to-end yet, so the supported migration path is
-    // re-analyze → fresh CREATE NODE TABLE.
+    // and current readers expect contentEncoding plus rich FeatureCluster
+    // context-pack columns. LadybugDB ALTER on existing tables is not validated
+    // end-to-end yet, so the supported migration path is re-analyze via a fresh
+    // CREATE NODE TABLE.
     const schemaUpToDate = !!existingMeta && (existingMeta.schemaVersion ?? 0) >= INDEX_SCHEMA_VERSION;
+    const existingCgdbPresent = existingMeta ? await pathExists(cgdbPath) : false;
+    const storageRebuildReason = existingMeta && schemaUpToDate && !existingCgdbPresent
+        ? 'graph database files are missing'
+        : null;
+    const configRebuildReason = storageRebuildReason ??
+        (existingMeta && schemaUpToDate && !options.force
+            ? getAnalyzeConfigRebuildReason(existingMeta, options)
+            : null);
     if (existingMeta &&
         schemaUpToDate &&
         !options.force &&
+        !configRebuildReason &&
         existingMeta.lastCommit === currentCommit) {
         // Non-git folders have currentCommit = '' — always rebuild since we can't detect changes
         if (currentCommit !== '') {
@@ -148,9 +305,54 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             };
         }
     }
+    if (existingMeta && schemaUpToDate && !options.force && configRebuildReason) {
+        log(`Re-analyzing: ${configRebuildReason}.`);
+    }
+    if (existingMeta &&
+        schemaUpToDate &&
+        !options.force &&
+        !configRebuildReason &&
+        currentCommit !== '' &&
+        existingMeta.lastCommit !== currentCommit) {
+        const changedPaths = listChangedPathsBetweenCommits(repoPath, existingMeta.lastCommit, currentCommit);
+        if (changedPaths) {
+            const graphRelevantChanges = getGraphRelevantChangedPaths(changedPaths);
+            if (graphRelevantChanges.length === 0) {
+                const reusedMeta = buildReusedMeta(existingMeta, repoPath, currentCommit);
+                await saveMeta(storagePath, reusedMeta);
+                const projectName = await registerRepo(repoPath, reusedMeta, {
+                    name: options.registryName,
+                    allowDuplicateName: options.allowDuplicateName,
+                });
+                if (hasGitDir(repoPath)) {
+                    await addToGitignore(repoPath);
+                }
+                const reuseReason = `Smart analyze reused the existing graph; ${changedPaths.length} changed ` +
+                    `file(s) did not affect indexed code, docs, config, or file structure.`;
+                log(reuseReason);
+                progress('done', 100, 'Existing graph reused');
+                return {
+                    repoName: projectName,
+                    repoPath,
+                    stats: reusedMeta.stats ?? {},
+                    alreadyUpToDate: true,
+                    reusedExistingIndex: true,
+                    reuseReason,
+                };
+            }
+            const preview = graphRelevantChanges.slice(0, 5).map(formatChangeForLog).join(', ');
+            const suffix = graphRelevantChanges.length > 5 ? ', ...' : '';
+            log(`Smart analyze: ${graphRelevantChanges.length} indexed change(s) require rebuild` +
+                (preview ? ` (${preview}${suffix})` : '') +
+                '.');
+        }
+        else {
+            log('Smart analyze: could not inspect git diff; rebuilding.');
+        }
+    }
     if (existingMeta && !schemaUpToDate) {
         log(`Index schema version ${existingMeta.schemaVersion ?? '<missing>'} is older than ` +
-            `${INDEX_SCHEMA_VERSION} (RFC 0001 Phase 2 — adds contentEncoding column). ` +
+            `${INDEX_SCHEMA_VERSION} (FeatureCluster context-pack schema). ` +
             `Re-analyzing.`);
     }
     // ── Cache embeddings from existing index before rebuild ────────────
@@ -175,10 +377,14 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
         }
     }
     // ── Phase 1: Full Pipeline (0–60%) ────────────────────────────────
+    const repoNameForFeatureClusters = options.registryName ?? getInferredRepoName(repoPath) ?? path.basename(repoPath);
     const pipelineResult = await runPipelineFromRepo(repoPath, (p) => {
         const phaseLabel = PHASE_LABELS[p.phase] || p.phase;
         const scaled = Math.round(p.percent * 0.6);
         progress(p.phase, scaled, phaseLabel);
+    }, {
+        featureClusterRepo: repoNameForFeatureClusters,
+        lastIndexedCommit: currentCommit || undefined,
     });
     // ── Phase 2: LadybugDB (60–85%) ──────────────────────────────────
     progress('cgdb', 60, 'Loading into LadybugDB...');
@@ -334,6 +540,7 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
                 nodes: stats.nodes,
                 edges: stats.edges,
                 communities: pipelineResult.communityResult?.stats.totalCommunities,
+                featureClusters: pipelineResult.featureClusterResult?.stats.totalClusters,
                 processes: pipelineResult.processResult?.stats.totalProcesses,
                 embeddings: embeddingCount,
             },
@@ -372,7 +579,7 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
                 nodes: stats.nodes,
                 edges: stats.edges,
                 communities: pipelineResult.communityResult?.stats.totalCommunities,
-                clusters: aggregatedClusterCount,
+                clusters: pipelineResult.featureClusterResult?.stats.totalClusters ?? aggregatedClusterCount,
                 processes: pipelineResult.processResult?.stats.totalProcesses,
             }, undefined, { skipAgentsMd: options.skipAgentsMd, noStats: options.noStats });
         }

package/dist/core/search/hybrid-search.js

@@ -111,8 +111,16 @@ export const formatHybridResults = (results) => {
  * The semanticSearch function is injected to keep this module environment-agnostic.
  */
 export const hybridSearch = async (query, limit, executeQuery, semanticSearch) => {
-    // Use LadybugDB FTS for always-fresh BM25 results
-    const bm25Results = await searchFTSFromCgdb(query, limit);
-    const semanticResults = await semanticSearch(executeQuery, query, limit);
+    const bm25Promise = searchFTSFromCgdb(query, limit);
+    // Start semantic work immediately, but gate its DB calls behind BM25.
+    // semanticSearch performs embedding before it calls executeQuery, so this
+    // overlaps CPU/model work with BM25 while avoiding concurrent queries on the
+    // singleton LadybugDB connection used by CLI/HTTP paths.
+    const executeAfterBm25 = async (cypher) => {
+        await bm25Promise;
+        return executeQuery(cypher);
+    };
+    const semanticPromise = semanticSearch(executeAfterBm25, query, limit);
+    const [bm25Results, semanticResults] = await Promise.all([bm25Promise, semanticPromise]);
     return mergeWithRRF(bm25Results, semanticResults, limit);
 };

package/dist/mcp/core/embedder.js

@@ -6,6 +6,8 @@
  */
 import { pipeline, env } from '@huggingface/transformers';
 import { isHttpMode, getHttpDimensions, httpEmbedQuery, } from '../../core/embeddings/http-client.js';
+import { homedir } from 'os';
+import { join } from 'path';
 import { silenceStdout, restoreStdout, realStderrWrite } from '../../core/cgdb/pool-adapter.js';
 // Model config
 const MODEL_ID = 'Snowflake/snowflake-arctic-embed-xs';
@@ -33,8 +35,9 @@ export const initEmbedder = async () => {
             // Default cache to user-writable location. transformers.js defaults to
             // ./node_modules/.cache inside its own install dir, which is unwritable
             // when codragraph is installed globally (e.g. /usr/lib/node_modules/).
-            // Respect HF_HOME if set, otherwise fall back to ~/.cache/huggingface.
-            env.cacheDir = process.env.HF_HOME ?? `${process.env.HOME}/.cache/huggingface`;
+            // Respect HF_HOME if set, otherwise fall back to a user-writable cache
+            // path using Node's OS-aware home directory resolution.
+            env.cacheDir = process.env.HF_HOME ?? join(homedir(), '.cache', 'huggingface');
             console.error('CodraGraph: Loading embedding model (first search may take a moment)...');
             // Try GPU first (DirectML on Windows, CUDA on Linux), fall back to CPU
             const isWindows = process.platform === 'win32';

package/dist/mcp/local/local-backend.d.ts

@@ -323,6 +323,18 @@ export declare class LocalBackend {
      * Query clusters (communities) directly from graph.
      * Used by getClustersResource — avoids legacy overview() dispatch.
      */
+    /**
+     * Query feature clusters directly from graph.
+     * FeatureCluster is the human-facing project area layer above Communities.
+     */
+    queryFeatureClusters(repoName?: string, limit?: number, query?: string): Promise<{
+        clusters: any[];
+    }>;
+    /**
+     * Query one feature cluster with members, dependencies, and process links.
+     */
+    queryFeatureContext(name: string, repoName?: string, limit?: number): Promise<any>;
+    queryFeatureImpact(name: string, repoName?: string, direction?: 'upstream' | 'downstream' | 'both', limit?: number): Promise<any>;
     queryClusters(repoName?: string, limit?: number): Promise<{
         clusters: any[];
     }>;