gitnexus 1.6.11-rc.21 → 1.6.11-rc.23

package/dist/mcp/local/local-backend.js

@@ -694,6 +694,18 @@ export function buildDetectChangesDiffArgs(scope, baseRef) {
  * (#2054).
  */
 export const REPO_ID_HASH_LENGTH = 6;
+const routeRuntimeEvidence = (route) => ({
+    confirmed: route.runtimeConfirmed,
+    ...(route.runtimeSource === null ? {} : { source: route.runtimeSource }),
+    ...(route.runtimeStatus === null ? {} : { status: route.runtimeStatus }),
+});
+const isMissingRouteRuntimePropertyError = (error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    return (['runtimeConfirmed', 'runtimeSource', 'runtimeStatus'].some((property) => message.includes(property)) &&
+        (/cannot find property/i.test(message) ||
+            /property .* does not exist/i.test(message) ||
+            /property .* not found/i.test(message)));
+};
 /**
  * Validate and normalise `list_repos` pagination arguments.
  *
@@ -6783,6 +6795,17 @@ export class LocalBackend {
                 target: params.target,
                 direction: params.direction,
             };
+            // Forward the target-selector params like the trace branch above.
+            // @group impact used to drop target_uid/file_path/kind here, so a name
+            // shared by same-named Api/Impl/Controller layers resolved ambiguously
+            // in the member repo and the documented "re-call with target_uid"
+            // disambiguation loop (impact tool schema) never worked in group mode.
+            if (typeof params.target_uid === 'string')
+                impactArgs.target_uid = params.target_uid;
+            if (typeof params.file_path === 'string')
+                impactArgs.file_path = params.file_path;
+            if (typeof params.kind === 'string')
+                impactArgs.kind = params.kind;
             if (params.maxDepth !== undefined)
                 impactArgs.maxDepth = params.maxDepth;
             if (params.crossDepth !== undefined)
@@ -6909,7 +6932,7 @@ export class LocalBackend {
      * Shared by routeMap and shapeCheck to avoid N+1 query patterns.
      */
     async fetchRoutesWithConsumers(repoId, routeFilter, params) {
-        const rows = await executeParameterized(repoId, `
+        const routeQuery = (includeRuntimeEvidence) => `
       MATCH (n:Route)
       WHERE n.id STARTS WITH 'Route:' ${routeFilter}
       OPTIONAL MATCH (consumer)-[r:CodeRelation]->(n)
@@ -6917,8 +6940,19 @@ export class LocalBackend {
       RETURN n.id AS routeId, n.name AS routeName, n.filePath AS handlerFile,
              n.responseKeys AS responseKeys, n.errorKeys AS errorKeys, n.middleware AS middleware,
              consumer.name AS consumerName, consumer.filePath AS consumerFile,
-             r.reason AS fetchReason, n.method AS method
-    `, params);
+             r.reason AS fetchReason, n.method AS method${includeRuntimeEvidence
+            ? ', n.runtimeConfirmed AS runtimeConfirmed, n.runtimeSource AS runtimeSource, n.runtimeStatus AS runtimeStatus'
+            : ''}
+    `;
+        let rows;
+        try {
+            rows = await executeParameterized(repoId, routeQuery(true), params);
+        }
+        catch (error) {
+            if (!isMissingRouteRuntimePropertyError(error))
+                throw error;
+            rows = await executeParameterized(repoId, routeQuery(false), params);
+        }
         // Strip wrapping quotes from DB array elements — CSV COPY stores ['key'] which
         // LadybugDB may return as "'key'" rather than "key"
         const stripQuotes = (keys) => keys ? keys.map((k) => k.replace(/^['"]|['"]$/g, '')) : null;
@@ -6938,6 +6972,9 @@ export class LocalBackend {
             // resource). Appended last in RETURN so positional fallbacks for the
             // consumer/reason columns above stay stable.
             const method = row.method ?? row[9] ?? null;
+            const runtimeConfirmed = (row.runtimeConfirmed ?? row[10]) === true;
+            const runtimeSource = row.runtimeSource ?? row[11] ?? null;
+            const runtimeStatus = row.runtimeStatus ?? row[12] ?? null;
             if (!routeMap.has(id)) {
                 routeMap.set(id, {
                     id,
@@ -6947,6 +6984,9 @@ export class LocalBackend {
                     responseKeys,
                     errorKeys,
                     middleware,
+                    runtimeConfirmed,
+                    runtimeSource,
+                    runtimeStatus,
                     consumers: [],
                 });
             }
@@ -7028,6 +7068,7 @@ export class LocalBackend {
                 route: r.name,
                 method: r.method,
                 handler: r.filePath,
+                runtimeEvidence: routeRuntimeEvidence(r),
                 middleware: r.middleware || [],
                 consumers: r.consumers,
                 flows: flowMap.get(r.id) || [],
@@ -7083,6 +7124,7 @@ export class LocalBackend {
                 route: r.name,
                 method: r.method,
                 handler: r.filePath,
+                runtimeEvidence: routeRuntimeEvidence(r),
                 ...(responseKeys.length > 0 ? { responseKeys } : {}),
                 ...(errorKeys.length > 0 ? { errorKeys } : {}),
                 consumers,
@@ -7246,6 +7288,7 @@ export class LocalBackend {
                 route: r.name,
                 method: r.method,
                 handler: r.filePath,
+                runtimeEvidence: routeRuntimeEvidence(r),
                 responseShape: {
                     success: responseKeys,
                     error: errorKeys,

package/dist/mcp/resources.js

@@ -298,6 +298,7 @@ async function getContextResource(backend, repoName) {
     lines.push(`  indexed_at: ${JSON.stringify(freshMeta?.indexedAt ?? null)}`);
     lines.push(`  runner_identity: ${JSON.stringify(freshMeta?.runnerIdentity ?? null)}`);
     lines.push(`  incomplete_reasons: ${JSON.stringify(incompleteReasons)}`);
+    lines.push(`  spring_actuator: ${JSON.stringify(freshMeta?.springActuator ?? null)}`);
     const indexedRunnerSchema = freshMeta?.runnerIdentity
         ?.schemaVersion;
     lines.push(`  runner_identity_schema_status: ${JSON.stringify(indexedRunnerSchema === ANALYZER_RUNNER_IDENTITY_SCHEMA_VERSION

package/dist/mcp/tools.js

@@ -696,7 +696,7 @@ CONTRACT CAVEATS:
 WHEN TO USE: Understanding API consumption patterns, finding orphaned routes. For pre-change analysis, prefer \`api_impact\` which combines this data with mismatch detection and risk assessment.
 AFTER THIS: Use impact() on specific route handlers to see full blast radius.
 
-Returns: route nodes with their handlers, middleware wrapper chains (e.g., withAuth, withRateLimit), and consumers. Each route object includes its "method" (the HTTP verb, "*" for method-agnostic routes, or null for method-less routes).`,
+Returns: route nodes with their handlers, middleware wrapper chains (e.g., withAuth, withRateLimit), and consumers. Each route object includes its "method" (the HTTP verb, "*" for method-agnostic routes, or null for method-less routes) and "runtimeEvidence". Runtime evidence is authoritative only when runtimeEvidence.confirmed is true; source records provenance, including conflicts.`,
         annotations: READ_ONLY_TOOL_ANNOTATIONS,
         inputSchema: {
             type: 'object',
@@ -740,7 +740,7 @@ Returns: tool nodes with their handler files and descriptions.`,
 WHEN TO USE: Detecting mismatches between what an API route returns and what consumers expect. Finding shape drift. For pre-change analysis, prefer \`api_impact\` which combines this data with mismatch detection and risk assessment.
 REQUIRES: Route nodes with responseKeys (extracted from .json({...}) calls during indexing).
 
-Returns routes that have both detected response keys AND consumers. Shows top-level keys each endpoint returns (e.g., data, pagination, error) and what keys each consumer accesses. Reports MISMATCH status when a consumer accesses keys not present in the route's response shape. Each route object includes its "method" (the HTTP verb, "*" for method-agnostic routes, or null for method-less routes).`,
+Returns routes that have both detected response keys AND consumers. Shows top-level keys each endpoint returns (e.g., data, pagination, error) and what keys each consumer accesses. Reports MISMATCH status when a consumer accesses keys not present in the route's response shape. Each route object includes its "method" (the HTTP verb, "*" for method-agnostic routes, or null for method-less routes) and "runtimeEvidence". Runtime evidence is authoritative only when runtimeEvidence.confirmed is true.`,
         annotations: READ_ONLY_TOOL_ANNOTATIONS,
         inputSchema: {
             type: 'object',
@@ -765,7 +765,7 @@ WHEN TO USE: BEFORE modifying any API route handler. Shows what consumers depend
 
 Risk levels: LOW (0-3 consumers), MEDIUM (4-9 or any mismatches), HIGH (10+ consumers or mismatches with 4+ consumers). Mismatches with confidence "low" indicate the consumer file fetches multiple routes — property attribution is approximate.
 
-Response shape is keyed on how many routes match, not on the data: exactly one match returns a single route object; two or more return { routes: [...], total: N }. The same URL can expose multiple HTTP verbs (e.g. GET and POST /api/orders are distinct routes that share the URL), so a bare-URL lookup may return the wrapped form — every route object carries its own "method" so verbs are distinguishable. Pass "method" to narrow to one verb; the single-object shape is returned only when exactly one route remains after filtering — a substring route/file match spanning several URLs can still return the wrapped form. A URL/file that exists but has no route for the given verb returns an error. Each route's "method" is the literal "*" for method-agnostic routes (e.g. Django function views), which match any "method" selector, or null for method-less routes (filesystem, Laravel resource), which never match a selector. Combines route_map, shape_check, and impact data.`,
+Response shape is keyed on how many routes match, not on the data: exactly one match returns a single route object; two or more return { routes: [...], total: N }. The same URL can expose multiple HTTP verbs (e.g. GET and POST /api/orders are distinct routes that share the URL), so a bare-URL lookup may return the wrapped form — every route object carries its own "method" so verbs are distinguishable. Pass "method" to narrow to one verb; the single-object shape is returned only when exactly one route remains after filtering — a substring route/file match spanning several URLs can still return the wrapped form. A URL/file that exists but has no route for the given verb returns an error. Each route's "method" is the literal "*" for method-agnostic routes (e.g. Django function views), which match any "method" selector, or null for method-less routes (filesystem, Laravel resource), which never match a selector. Every route also carries "runtimeEvidence"; treat it as authoritative only when runtimeEvidence.confirmed is true. Combines route_map, shape_check, and impact data.`,
         annotations: READ_ONLY_TOOL_ANNOTATIONS,
         inputSchema: {
             type: 'object',
@@ -804,7 +804,7 @@ WHEN TO USE: Discover groups before group_sync. Optional "name" returns a single
 
 WHEN TO USE: After changing group.yaml or re-indexing member repos.
 
-READ THE RESULT: \`missingRepos\` are configured repos with no entry in the registry (index them, or drop them from group.yaml); \`unreadableRepos\` ARE registered but this sync could not extract from them — the index would not open (version skew, lock, corruption), or an extractor failed partway — so NONE of their contracts are in this sync and a following group_impact / group_contracts is a lower bound, not a verdict. \`registryOutcome\` says what happened to the file, and the three values a call here can return each need a different response: 'written' — this run's contracts replaced contracts.json; 'preserved' — nothing could be read, so contracts.json was rewritten keeping the previous sync's contracts and cross-links verbatim and refreshing only \`missingRepos\`/\`unreadableRepos\` to describe THIS run (the file changed, the contracts in it did not, and they are as old as the last sync that succeeded); 'superseded' — nothing could be read, and another sync replaced contracts.json while this one waited for the group lock; that file was left untouched and this run's lists were NOT recorded, because they describe an older group state than what is on disk (so the registry is fresher than this response's diagnostics, not staler); 'no-prior-registry' — nothing could be read AND there was no previous contracts.json to carry forward, so none was written and this group has no contract registry on disk. Only 'no-prior-registry' means there is nothing to read: after it, group_contracts / group_impact have no registry at all rather than a stale one, so fix the repos above and re-run before trusting either. \`suppressedMatchStages\` names matching stages this sync was ASKED to skip, with the same three states as the repo lists: ABSENT means a registry written before the field existed, \`[]\` means this sync suppressed nothing, and a populated list means the cross-link set is a lower bound BY REQUEST — a later group_impact / group_contracts on it reports truncationReason 'suppressed-stage'.\n\nPARAMETERS ARE VALIDATED: \`exactOnly\` must be a real boolean — the string "false" is rejected, not coerced to true. The retired \`skipEmbeddings\` and \`allowStale\` parameters are refused by name; drop them from the call.`,
+READ THE RESULT: \`missingRepos\` are configured repos with no entry in the registry (index them, or drop them from group.yaml); \`unreadableRepos\` ARE registered but this sync could not extract from them — the index would not open (version skew, lock, corruption), or an extractor failed partway — so NONE of their contracts are in this sync and a following group_impact / group_contracts is a lower bound, not a verdict. \`degradedLinks\` is the count of persisted cross-links whose provider endpoint has no resolved graph symbol (\`degraded: true\`); re-analyze the provider so handlers resolve. \`failedRepos\` is \`{ repo, reason }[]\` for per-repo extraction throws — each also appears in \`unreadableRepos\`; \`repo\` is that group path (e.g. app/backend), not the registry display name. \`warnings\` are operator-facing run notes (e.g. bridge.lbug write failed after contracts.json was written); \`[]\` means none this run. \`registryOutcome\` says what happened to the file, and the three values a call here can return each need a different response: 'written' — this run's contracts replaced contracts.json; 'preserved' — nothing could be read, so contracts.json was rewritten keeping the previous sync's contracts and cross-links verbatim and refreshing only \`missingRepos\`/\`unreadableRepos\` to describe THIS run (the file changed, the contracts in it did not, and they are as old as the last sync that succeeded); 'superseded' — nothing could be read, and another sync replaced contracts.json while this one waited for the group lock; that file was left untouched and this run's lists were NOT recorded, because they describe an older group state than what is on disk (so the registry is fresher than this response's diagnostics, not staler); 'no-prior-registry' — nothing could be read AND there was no previous contracts.json to carry forward, so none was written and this group has no contract registry on disk. Only 'no-prior-registry' means there is nothing to read: after it, group_contracts / group_impact have no registry at all rather than a stale one, so fix the repos above and re-run before trusting either. \`suppressedMatchStages\` names matching stages this sync was ASKED to skip, with the same three states as the repo lists: ABSENT means a registry written before the field existed, \`[]\` means this sync suppressed nothing, and a populated list means the cross-link set is a lower bound BY REQUEST — a later group_impact / group_contracts on it reports truncationReason 'suppressed-stage'.\n\nPARAMETERS ARE VALIDATED: \`exactOnly\` must be a real boolean — the string "false" is rejected, not coerced to true. The retired \`skipEmbeddings\` and \`allowStale\` parameters are refused by name; drop them from the call.`,
         // Usually writes contracts.json, so conservatively non-idempotent even
         // though output is deterministic for identical input. When no configured
         // repo could be read it still rewrites the file, keeping the previous

package/dist/server/analyze-launch.d.ts

@@ -28,6 +28,7 @@ export interface LaunchOptions {
     force?: boolean;
     embeddings?: boolean;
     dropEmbeddings?: boolean;
+    springActuatorPath?: string;
     registryName?: string;
 }
 export declare function createLaunchAnalysisWorker(deps: LaunchDeps): (job: {

package/dist/server/analyze-launch.js

@@ -280,6 +280,7 @@ export function createLaunchAnalysisWorker(deps) {
                     force: !!opts.force,
                     embeddings: !!opts.embeddings,
                     dropEmbeddings: !!opts.dropEmbeddings,
+                    ...(opts.springActuatorPath ? { springActuatorPath: opts.springActuatorPath } : {}),
                     ...(opts.registryName ? { registryName: opts.registryName } : {}),
                 },
             });

package/dist/server/api.d.ts

@@ -50,6 +50,10 @@ export declare const landingPageHtml: () => string;
 export declare const staticCacheControlSetHeaders: (res: express.Response, filePath: string) => void;
 export declare const registerWebUI: (app: express.Express, staticDir: string | null) => void;
 export declare const writeNdjsonRecord: (res: express.Response, record: GraphStreamRecord, signal?: AbortSignal) => Promise<void>;
+export declare const buildGraph: (includeContent?: boolean) => Promise<{
+    nodes: GraphNode[];
+    relationships: GraphRelationship[];
+}>;
 export declare const getNodeQuery: (table: string, includeContent: boolean) => string;
 export declare const streamGraphNdjson: (res: express.Response, includeContent?: boolean, signal?: AbortSignal) => Promise<void>;
 /**

package/dist/server/api.js

@@ -266,7 +266,18 @@ export const writeNdjsonRecord = async (res, record, signal) => {
         throw err;
     }
 };
-const buildGraph = async (includeContent = false) => {
+const ROUTE_NODE_CORE_PROJECTION = 'n.id AS id, n.name AS name, n.filePath AS filePath, ' +
+    'n.responseKeys AS responseKeys, n.errorKeys AS errorKeys, n.middleware AS middleware';
+const LEGACY_ROUTE_NODE_QUERY = `MATCH (n:\`Route\`) RETURN ${ROUTE_NODE_CORE_PROJECTION}`;
+const isMissingRouteRuntimePropertyError = (err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    const mentionsRuntimeProperty = ['runtimeConfirmed', 'runtimeSource', 'runtimeStatus'].some((property) => message.includes(property));
+    return (mentionsRuntimeProperty &&
+        (/cannot find property/i.test(message) ||
+            /property .* does not exist/i.test(message) ||
+            /property .* not found/i.test(message)));
+};
+export const buildGraph = async (includeContent = false) => {
     const nodes = [];
     for (const table of NODE_TABLES) {
         try {
@@ -276,6 +287,13 @@ const buildGraph = async (includeContent = false) => {
             }
         }
         catch (err) {
+            if (table === 'Route' && isMissingRouteRuntimePropertyError(err)) {
+                const rows = await executeQuery(LEGACY_ROUTE_NODE_QUERY);
+                for (const row of rows) {
+                    nodes.push(mapGraphNodeRow(table, row, includeContent));
+                }
+                continue;
+            }
             if (!isIgnorableGraphQueryError(err)) {
                 throw err;
             }
@@ -316,7 +334,7 @@ export const getNodeQuery = (table, includeContent) => {
         return `MATCH (n:${tableLabel}) RETURN n.id AS id, n.label AS label, n.heuristicLabel AS heuristicLabel, n.processType AS processType, n.stepCount AS stepCount, n.communities AS communities, n.entryPointId AS entryPointId, n.terminalId AS terminalId`;
     }
     if (table === 'Route') {
-        return `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.responseKeys AS responseKeys, n.errorKeys AS errorKeys, n.middleware AS middleware`;
+        return `MATCH (n:${tableLabel}) RETURN ${ROUTE_NODE_CORE_PROJECTION}, n.runtimeConfirmed AS runtimeConfirmed, n.runtimeSource AS runtimeSource, n.runtimeStatus AS runtimeStatus`;
     }
     if (table === 'Tool') {
         return `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.description AS description`;
@@ -344,6 +362,11 @@ const mapGraphNodeRow = (table, row, includeContent) => ({
         responseKeys: row.responseKeys,
         errorKeys: row.errorKeys,
         middleware: row.middleware,
+        // Normalize legacy Route projections to the modern contract. Source is
+        // provenance; only runtimeConfirmed === true is authoritative.
+        runtimeConfirmed: table === 'Route' ? (row.runtimeConfirmed ?? false) : undefined,
+        runtimeSource: table === 'Route' ? row.runtimeSource : undefined,
+        runtimeStatus: table === 'Route' ? row.runtimeStatus : undefined,
         heuristicLabel: row.heuristicLabel,
         cohesion: row.cohesion,
         symbolCount: row.symbolCount,
@@ -375,6 +398,15 @@ export const streamGraphNdjson = async (res, includeContent = false, signal) =>
             });
         }
         catch (err) {
+            if (table === 'Route' && isMissingRouteRuntimePropertyError(err)) {
+                await streamQuery(LEGACY_ROUTE_NODE_QUERY, async (row) => {
+                    await writeNdjsonRecord(res, {
+                        type: 'node',
+                        data: mapGraphNodeRow(table, row, includeContent),
+                    }, signal);
+                });
+                continue;
+            }
             if (!isIgnorableGraphQueryError(err)) {
                 throw err;
             }
@@ -1225,7 +1257,7 @@ export const createServer = async (port, host = '127.0.0.1') => {
     // POST /api/analyze — start a new analysis job
     app.post('/api/analyze', createRouteLimiter({ limit: 10 }), requireTrustedOrigin, async (req, res) => {
         try {
-            const { url: repoUrl, path: repoLocalPath, force, embeddings, dropEmbeddings, token: repoToken, } = req.body;
+            const { url: repoUrl, path: repoLocalPath, force, embeddings, dropEmbeddings, springActuatorPath, token: repoToken, } = req.body;
             // Input type validation
             if (repoUrl !== undefined && typeof repoUrl !== 'string') {
                 res.status(400).json({ error: '"url" must be a string' });
@@ -1235,6 +1267,11 @@ export const createServer = async (port, host = '127.0.0.1') => {
                 res.status(400).json({ error: '"path" must be a string' });
                 return;
             }
+            if (springActuatorPath !== undefined &&
+                (typeof springActuatorPath !== 'string' || springActuatorPath.trim().length === 0)) {
+                res.status(400).json({ error: '"springActuatorPath" must be a non-empty string' });
+                return;
+            }
             if (!repoUrl && !repoLocalPath) {
                 res.status(400).json({ error: 'Provide "url" (git URL) or "path" (local path)' });
                 return;
@@ -1303,7 +1340,12 @@ export const createServer = async (port, host = '127.0.0.1') => {
                     if (!targetPath) {
                         throw new Error('No target path resolved');
                     }
-                    launchAnalysisWorker(job, targetPath, { force, embeddings, dropEmbeddings });
+                    launchAnalysisWorker(job, targetPath, {
+                        force,
+                        embeddings,
+                        dropEmbeddings,
+                        springActuatorPath,
+                    });
                 }
                 catch (err) {
                     if (targetPath)

package/dist/storage/parse-cache.js

@@ -680,7 +680,14 @@ import { copyV8CacheIfPresent, tryLoadV8Cache, writeV8CacheFile } from './v8-sid
 // cache can replay stale names and declaration metadata.
 // 85 -> 86: Kotlin interface property accessors now record isAbstract on the
 // synthetic Method. A warm v85 cache replays them as concrete.
-const SCHEMA_BUMP = 86;
+// 86 -> 87: ModuleConstants gained wildcardImports (static-import-asterisk
+// materialization) — a warm v86 cache has no wildcard bindings, so folding
+// would skip them and drop wildcard-imported route constants. origin/main at
+// allocation is 86 (#2885).
+// 87 -> 88: Java ModuleConstants now preserves unfoldable declaration names
+// across worker/cache replay so wildcard expansion cannot resurrect an imported
+// member hidden by a local field. A warm v87 cache lacks that shadow metadata.
+const SCHEMA_BUMP = 88;
 const GITNEXUS_PKG_VERSION = (() => {
     try {
         // package.json sits at gitnexus/package.json — two levels up from

package/dist/storage/repo-meta.d.ts

@@ -78,6 +78,18 @@ export interface RepoMeta {
     repoPath: string;
     lastCommit: string;
     indexedAt: string;
+    /**
+     * Runtime enrichment mode plus redacted scan exclusions. Payload data and
+     * absolute/external paths are deliberately excluded from metadata.
+     */
+    springActuator?: {
+        enabled: boolean;
+        /**
+         * Normalized repo-relative inputs that must remain excluded from all future
+         * source scans. The list is empty when every configured input was external.
+         */
+        repoRelativeInputs: string[];
+    };
     /**
      * Analyzer/runtime receipt for the successful run represented by this
      * metadata. Optional so indexes written by older GitNexus releases remain

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.11-rc.21",
+  "version": "1.6.11-rc.23",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",

package/skills/gitnexus-cli.md

@@ -27,9 +27,12 @@ Run from the project root. This parses all source files, builds the knowledge gr
 | `--embeddings` | Enable embedding generation for semantic search (off by default) |
 | `--drop-embeddings` | Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` preserves them. |
 | `--pdg` | Build the program-dependence layers used by `explain` and `pdg_query` (taint, CDG, and REACHING_DEF). |
+| `--spring-actuator <path>` | Import opt-in Spring Boot Actuator mappings, beans, conditions, configprops, and env snapshots. Forces a full rebuild; unsupported with `--watch`. |
 
 **When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale. In Claude Code, a PostToolUse hook detects staleness after `git commit` and `git merge` and notifies the agent to run `analyze` — the hook does not run analyze itself, to avoid blocking the agent for up to 120s and risking KuzuDB corruption on timeout.
 
+For Spring runtime enrichment, pass a JSON bundle, one endpoint JSON file, or a directory containing endpoint files. Route evidence is authoritative only when `runtimeConfirmed === true`; `runtimeSource` records provenance and may also accompany `handler-conflict`. Env/configprops values are never persisted.
+
 Use `node .gitnexus/run.cjs analyze --watch` for a long-lived local Git repository. It performs an initial analysis, queues scanner-admitted file changes, and retries intact failed batches with bounded backoff. Watch refreshes update only the graph: they skip AGENTS.md / CLAUDE.md injection and standard skill installation, so run a one-shot `analyze` when those generated files need updating. Watch rejects one-shot or context-output flags including `--force`, embedding flags, `--skills`, `--default-branch`, `--skip-agents-md`, `--skip-skills`, `--no-stats`, `--self-commit`, `--index-only`, and `--skip-git`. It never pulls remotes. Running MCP and `serve` processes periodically check for a published replacement and reopen it without a restart. MCP checks are throttled to once every five seconds, so a tool call before the next check can briefly use the previous index.
 
 ### status — Check index freshness