gitnexus 1.6.11-rc.2 → 1.6.11-rc.21

package/dist/storage/v8-sidecar.js

@@ -0,0 +1,347 @@
+/**
+ * One-file V8 cache envelope for parse-cache and ParsedFile shards.
+ *
+ * Each object-graph shard is a single immutable `.v8` file published by
+ * tmp+rename. JSON is not a fallback: a missing, corrupt, runtime-incompatible,
+ * or deserialize-failed envelope is a cache miss (re-extract / re-dispatch).
+ * Tiny JSON manifests (`index.json`) stay outside this module.
+ *
+ * Envelope: magic, format, Node major, V8 version, optional path listing,
+ * `v8.serialize` of the live graph, then SHA-256 of listing||payload. Path
+ * bytes live before the payload so a ParsedFile loader can skip a shard whose
+ * authenticated listing misses `wantPaths` without deserializing. An
+ * unreadable/invalid listing is fail-closed: deserialize, never skip.
+ */
+import { promises as fs } from 'node:fs';
+import { createHash } from 'node:crypto';
+import v8 from 'node:v8';
+import { logger } from '../core/logger.js';
+import { linkOrCopyFile, writeFileAtomicBytes, writeFileAtomicBytesSync } from './fs-atomic.js';
+const MAGIC = Buffer.from('GNXV8CF1', 'ascii');
+/** Envelope version — independent of PARSE_CACHE_VERSION / SCHEMA_BUMP. */
+export const V8_CACHE_FORMAT = 5;
+const U32 = 4;
+const U16 = 2;
+const PAYLOAD_HASH_LEN = 32;
+const MAGIC_LEN = 8;
+const FIXED_PREFIX = MAGIC_LEN + U32 + U16 + U16; // magic + format + nodeMajor + v8len
+const internString = (value, pool) => {
+    const hit = pool.get(value);
+    if (hit !== undefined)
+        return hit;
+    pool.set(value, value);
+    return value;
+};
+/**
+ * Collapse duplicate strings in a live deserialized graph into `pool`, mutating
+ * in place so object identity (shared `SymbolDefinition`s, Maps) is preserved.
+ * Required after `v8.deserialize` of ParsedFile shards: V8 does not recreate
+ * the JSON reviver's cross-shard string intern, and skipping it regresses
+ * retained heap (~+59% measured vs interned JSON).
+ */
+export const internGraphStrings = (root, pool) => {
+    const seen = new WeakSet();
+    const walk = (value) => {
+        if (typeof value === 'string')
+            return internString(value, pool);
+        if (value === null || typeof value !== 'object')
+            return value;
+        if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer)
+            return value;
+        if (seen.has(value))
+            return value;
+        seen.add(value);
+        if (value instanceof Map) {
+            const entries = [...value];
+            value.clear();
+            for (const [k, v] of entries)
+                value.set(walk(k), walk(v));
+            return value;
+        }
+        if (value instanceof Set) {
+            const entries = [...value];
+            value.clear();
+            for (const v of entries)
+                value.add(walk(v));
+            return value;
+        }
+        if (Array.isArray(value)) {
+            for (let i = 0; i < value.length; i++)
+                value[i] = walk(value[i]);
+            return value;
+        }
+        const rec = value;
+        for (const key of Object.keys(rec)) {
+            rec[key] = walk(rec[key]);
+        }
+        return value;
+    };
+    return walk(root);
+};
+const nodeMajor = () => Number.parseInt(process.versions.node.split('.')[0] ?? '0', 10);
+const isEnoent = (err) => err.code === 'ENOENT';
+const warnCache = (err, filePath, msg) => {
+    logger.warn({ err, filePath }, msg);
+};
+/** NDJSON listing cannot encode paths that themselves contain CR/LF/NUL. */
+export const encodeCachePathListing = (paths) => {
+    if (paths.length === 0)
+        return Buffer.alloc(0);
+    if (paths.some((p) => /[\r\n\0]/.test(p)))
+        return Buffer.alloc(0);
+    return Buffer.from(`${paths.length}\n${paths.join('\n')}\n`, 'utf8');
+};
+/**
+ * Parse a counted NDJSON path listing. Returns `null` when it must not be
+ * trusted to skip the payload: missing trailing newline, CR/NUL, or a count
+ * that does not match the remaining lines.
+ */
+export const parseCachePathListing = (raw) => {
+    if (raw.byteLength === 0)
+        return [];
+    let sidecarRaw;
+    try {
+        sidecarRaw = new TextDecoder('utf-8', { fatal: true }).decode(raw);
+    }
+    catch {
+        return null;
+    }
+    if (sidecarRaw.includes('\0') || sidecarRaw.includes('\r') || !sidecarRaw.endsWith('\n')) {
+        return null;
+    }
+    const nl = sidecarRaw.indexOf('\n');
+    if (nl < 0)
+        return null;
+    const countToken = sidecarRaw.slice(0, nl);
+    if (!/^[0-9]+$/.test(countToken))
+        return null;
+    const count = Number(countToken);
+    const body = sidecarRaw.slice(nl + 1);
+    const listed = body === '' ? [] : body.slice(0, -1).split('\n');
+    if (listed.length !== count)
+        return null;
+    return listed;
+};
+const encodeEnvelope = (graph, paths) => {
+    let payload;
+    try {
+        payload = v8.serialize(graph);
+    }
+    catch (err) {
+        warnCache(err, '', 'v8 cache: serialize failed; treating as miss on next load');
+        return undefined;
+    }
+    const pathListing = encodeCachePathListing(paths);
+    const listed = parseCachePathListing(pathListing);
+    const pathCount = listed === null ? 0 : listed.length;
+    if (payload.byteLength > 0xffff_ffff || pathListing.byteLength > 0xffff_ffff)
+        return undefined;
+    const v8ver = Buffer.from(process.versions.v8, 'utf8');
+    if (v8ver.byteLength > 0xffff)
+        return undefined;
+    const header = Buffer.allocUnsafe(FIXED_PREFIX + v8ver.length + U32 * 3);
+    MAGIC.copy(header, 0);
+    header.writeUInt32LE(V8_CACHE_FORMAT, MAGIC_LEN);
+    header.writeUInt16LE(nodeMajor(), MAGIC_LEN + U32);
+    header.writeUInt16LE(v8ver.length, MAGIC_LEN + U32 + U16);
+    v8ver.copy(header, FIXED_PREFIX);
+    let off = FIXED_PREFIX + v8ver.length;
+    header.writeUInt32LE(pathCount, off);
+    off += U32;
+    header.writeUInt32LE(pathListing.byteLength, off);
+    off += U32;
+    header.writeUInt32LE(payload.byteLength, off);
+    const payloadHash = createHash('sha256').update(pathListing).update(payload).digest();
+    return Buffer.concat([header, pathListing, payload, payloadHash]);
+};
+const decodePrefix = (buf) => {
+    if (buf.byteLength < FIXED_PREFIX)
+        return undefined;
+    if (!buf.subarray(0, MAGIC_LEN).equals(MAGIC))
+        return undefined;
+    if (buf.readUInt32LE(MAGIC_LEN) !== V8_CACHE_FORMAT)
+        return undefined;
+    const recordedNodeMajor = buf.readUInt16LE(MAGIC_LEN + U32);
+    const v8len = buf.readUInt16LE(MAGIC_LEN + U32 + U16);
+    const v8off = FIXED_PREFIX;
+    const countsOff = v8off + v8len;
+    if (buf.byteLength < countsOff + U32 * 3)
+        return undefined;
+    const recordedV8 = buf.subarray(v8off, v8off + v8len).toString('utf8');
+    const pathCount = buf.readUInt32LE(countsOff);
+    const pathBytes = buf.readUInt32LE(countsOff + U32);
+    const payloadLen = buf.readUInt32LE(countsOff + U32 * 2);
+    const pathsOff = countsOff + U32 * 3;
+    const payloadOff = pathsOff + pathBytes;
+    return {
+        recordedNodeMajor,
+        recordedV8,
+        pathCount,
+        pathBytes,
+        payloadLen,
+        pathsOff,
+        payloadOff,
+    };
+};
+const runtimeCompatible = (meta) => meta.recordedNodeMajor === nodeMajor() && meta.recordedV8 === process.versions.v8;
+const readExact = async (fh, offset, length) => {
+    const buf = Buffer.allocUnsafe(length);
+    let got = 0;
+    while (got < length) {
+        const { bytesRead } = await fh.read(buf, got, length - got, offset + got);
+        if (bytesRead === 0)
+            return undefined;
+        got += bytesRead;
+    }
+    return buf;
+};
+const readVerifiedPayload = async (fh, meta, pathRaw) => {
+    const payloadAndHash = await readExact(fh, meta.payloadOff, meta.payloadLen + PAYLOAD_HASH_LEN);
+    if (!payloadAndHash)
+        return undefined;
+    const payload = payloadAndHash.subarray(0, meta.payloadLen);
+    const expected = payloadAndHash.subarray(meta.payloadLen);
+    const digest = createHash('sha256').update(pathRaw).update(payload).digest();
+    return digest.equals(expected) ? payload : undefined;
+};
+/**
+ * Validate the immutable envelope metadata needed by the durable ParsedFile
+ * warm-hit gate without deserializing its payload. Atomic publication means a
+ * runtime-compatible envelope whose exact file length and counted path listing
+ * validate is a stable snapshot candidate; malformed/truncated envelopes miss.
+ */
+export const inspectV8Cache = async (filePath) => {
+    let fh;
+    try {
+        fh = await fs.open(filePath, 'r');
+        const st = await fh.stat();
+        const prefix = await readExact(fh, 0, Math.min(st.size, FIXED_PREFIX + 256 + U32 * 3));
+        if (!prefix)
+            return undefined;
+        const meta = decodePrefix(prefix);
+        if (!meta || !runtimeCompatible(meta))
+            return undefined;
+        if (meta.payloadOff + meta.payloadLen + PAYLOAD_HASH_LEN !== st.size || meta.pathBytes === 0) {
+            return undefined;
+        }
+        const pathRaw = prefix.byteLength >= meta.payloadOff
+            ? Buffer.from(prefix.subarray(meta.pathsOff, meta.payloadOff))
+            : await readExact(fh, meta.pathsOff, meta.pathBytes);
+        if (!pathRaw)
+            return undefined;
+        const listed = parseCachePathListing(pathRaw);
+        if (listed === null || listed.length !== meta.pathCount || listed.length === 0) {
+            return undefined;
+        }
+        if (!(await readVerifiedPayload(fh, meta, pathRaw)))
+            return undefined;
+        return { paths: listed };
+    }
+    catch (err) {
+        if (!isEnoent(err)) {
+            logger.debug({ err, filePath }, 'v8 cache: inspection failed; treating as miss');
+        }
+        return undefined;
+    }
+    finally {
+        await fh?.close().catch(() => { });
+    }
+};
+/**
+ * Load a cache file. When `wantPaths` is set and a digest-verified non-empty
+ * path listing has no intersection, returns `{ kind: 'skip' }` without
+ * deserializing. An authentic listing that does not parse deserializes (fail
+ * closed). Envelope/runtime/digest failure returns undefined (miss).
+ */
+export const tryLoadV8Cache = async (filePath, internPool, wantPaths) => {
+    let fh;
+    try {
+        fh = await fs.open(filePath, 'r');
+        const st = await fh.stat();
+        const prefix = await readExact(fh, 0, Math.min(st.size, FIXED_PREFIX + 256 + U32 * 3));
+        if (!prefix)
+            return undefined;
+        const meta = decodePrefix(prefix);
+        if (!meta)
+            return undefined;
+        if (!runtimeCompatible(meta))
+            return undefined;
+        if (meta.payloadOff + meta.payloadLen + PAYLOAD_HASH_LEN !== st.size)
+            return undefined;
+        let pathRaw = Buffer.alloc(0);
+        if (meta.pathBytes > 0) {
+            if (prefix.byteLength >= meta.payloadOff) {
+                pathRaw = Buffer.from(prefix.subarray(meta.pathsOff, meta.payloadOff));
+            }
+            else {
+                const raw = await readExact(fh, meta.pathsOff, meta.pathBytes);
+                if (!raw)
+                    return undefined;
+                pathRaw = Buffer.from(raw);
+            }
+        }
+        const payload = await readVerifiedPayload(fh, meta, pathRaw);
+        if (!payload)
+            return undefined;
+        if (wantPaths && wantPaths.size > 0 && meta.pathBytes > 0) {
+            const listed = parseCachePathListing(pathRaw);
+            if (listed !== null &&
+                listed.length === meta.pathCount &&
+                listed.length > 0 &&
+                !listed.some((p) => wantPaths.has(p))) {
+                return { kind: 'skip', bytes: st.size };
+            }
+        }
+        const value = v8.deserialize(payload);
+        if (internPool)
+            internGraphStrings(value, internPool);
+        return { kind: 'hit', value, bytes: st.size };
+    }
+    catch (err) {
+        if (!isEnoent(err)) {
+            logger.debug({ err, filePath }, 'v8 cache: load failed; treating as miss');
+        }
+        return undefined;
+    }
+    finally {
+        await fh?.close().catch(() => { });
+    }
+};
+export const writeV8CacheFile = async (filePath, graph, paths) => {
+    const blob = encodeEnvelope(graph, paths ?? []);
+    if (!blob)
+        return false;
+    try {
+        await writeFileAtomicBytes(filePath, blob, 1);
+        return true;
+    }
+    catch (err) {
+        warnCache(err, filePath, 'v8 cache: write failed; treating as miss');
+        return false;
+    }
+};
+export const writeV8CacheFileSync = (filePath, graph, paths) => {
+    const blob = encodeEnvelope(graph, paths ?? []);
+    if (!blob)
+        return false;
+    try {
+        writeFileAtomicBytesSync(filePath, blob);
+        return true;
+    }
+    catch (err) {
+        warnCache(err, filePath, 'v8 cache: write failed; treating as miss');
+        return false;
+    }
+};
+export const copyV8CacheIfPresent = async (srcPath, dstPath) => {
+    try {
+        await linkOrCopyFile(srcPath, dstPath);
+        return true;
+    }
+    catch (copyErr) {
+        if (!isEnoent(copyErr)) {
+            warnCache(copyErr, srcPath, 'v8 cache: copy failed; treating as miss');
+        }
+        return false;
+    }
+};

package/dist/types/pipeline.d.ts

@@ -13,6 +13,18 @@ export interface PipelineResult {
     totalFileCount: number;
     communityResult?: CommunityDetectionResult;
     processResult?: ProcessDetectionResult;
+    /**
+     * Runs the community/process phases that `skipDerivedGraphPhases` held back
+     * (#3016), against the same graph and phase outputs the pipeline already
+     * produced, and populates `communityResult`/`processResult` on this object.
+     *
+     * Present ONLY when those phases were skipped for that reason, so a caller
+     * that optimistically skipped them can still get a byte-identical derived
+     * layer on the paths that turn out to need one (full rebuild, escalated
+     * write, or an incremental run with deleted files). Absent means the phases
+     * either already ran or were disabled for an unrelated reason.
+     */
+    runDeferredDerivedPhases?: () => Promise<void>;
     /**
      * Additive diagnostics for registry-primary resolution decisions that
      * deliberately suppress edge emission. Empty means no diagnostic was
@@ -38,6 +50,8 @@ export interface PipelineResult {
      * affordance so regression suites can prove the pool engaged.
      */
     usedWorkerPool: boolean;
+    /** Files actually dispatched to parser workers after parse-cache lookup. */
+    reparsedFileCount: number;
     /** Files omitted from scope-resolution while the rest of analysis continued. */
     scopeExtractionFailures: readonly string[];
     /** Files scope resolution could not inspect because their parser was unavailable. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.11-rc.2",
+  "version": "1.6.11-rc.21",
   "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",
@@ -60,15 +60,18 @@
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@scarf/scarf": "^1.4.0",
     "busboy": "^1.6.0",
+    "chokidar": "^4.0.3",
     "cli-progress": "^3.12.0",
     "commander": "^15.0.0",
     "cors": "^2.8.5",
     "express": "^5.2.1",
     "express-rate-limit": "^8.4.1",
+    "fast-xml-parser": "^5.11.1",
     "glob": "^13.0.6",
     "graphology": "^0.26.0",
     "graphology-indices": "^0.17.0",
     "graphology-utils": "^2.3.0",
+    "graphql": "^16.14.2",
     "ignore": "^7.0.5",
     "js-yaml": "^5.0.0",
     "jsonc-parser": "^3.3.1",

package/scripts/cross-platform-shard.ts

@@ -3,7 +3,7 @@
  *
  * WHY THIS EXISTS. `run-cross-platform.ts` used to hand vitest the whole file
  * list plus `--shard=i/n`, and vitest partitions by file COUNT. Runtime on this
- * suite is wildly uneven — measured on the Windows runner, `cli-e2e` is 361 s
+ * suite is wildly uneven — measured on the Windows runner, `cli-e2e` is 621 s
  * and `worker-pool` 221 s, while most files are under a second — so a
  * count-split routinely put several of the heaviest suites on one shard. That
  * is #2449, and this file's sibling header has documented the symptom ("the
@@ -44,7 +44,9 @@
  * partition depend on the very machine load it is trying to protect against.
  */
 export const WINDOWS_WEIGHTS_SEC: Readonly<Record<string, number>> = {
-  'test/integration/cli-e2e.test.ts': 361,
+  // Re-measured after the analyze --watch e2e landed in #3072. The previous
+  // 361 s entry undercharged this suite and left shard 1 close to the watchdog.
+  'test/integration/cli-e2e.test.ts': 621,
   'test/integration/worker-pool.test.ts': 222,
   'test/unit/incremental-vector-extension-ordering.test.ts': 87,
   // ESTIMATE, not a measurement (#2841): this suite drives more full

package/scripts/cross-platform-tests.ts

@@ -90,6 +90,7 @@ const PLATFORM_LOGIC = [
   'test/unit/ignore-service.test.ts',
   'test/unit/group/bridge-db.test.ts',
   'test/unit/group/bridge-db-edge.test.ts',
+  'test/unit/group/fs-utils.test.ts',
   'test/unit/onnxruntime-node-resolver.test.ts',
   // Windows cmd.exe arg-quoting + compose-and-spawn for the npm install (#2372):
   // the quoting rules and win32 single-string spawn shape are OS-sensitive, so
@@ -113,6 +114,9 @@ const PLATFORM_LOGIC = [
   // POSIX and Windows — the fail-closed path-claim semantics must hold on the
   // real windows-latest path implementation (#2419/#2420).
   'test/unit/server-api-repo-resolution.test.ts',
+  // #3073: cwd-based repository selection canonicalizes real paths, compares
+  // platform separators/case, and rejects nested Git-boundary fallthrough.
+  'test/unit/calltool-dispatch.test.ts',
   // The index write-lock (#2658) selects its backend by process.platform — the
   // OS socket lock (Windows named pipe / Linux abstract socket) vs the file
   // fallback — and its socket-backend describe block is gated to linux/win32.
@@ -140,6 +144,7 @@ const LBUG_NATIVE = [
   // opens them through the pool adapter (native addon + bridge file locking).
   // Windows is skipped in-file (describeReopen) due to the bridge reopen lock.
   'test/integration/group/cross-trace-e2e.test.ts',
+  'test/integration/group/graphql-resolve-symbol.test.ts',
   'test/integration/local-backend.test.ts',
   'test/integration/local-backend-calltool.test.ts',
   'test/integration/search-core.test.ts',
@@ -232,7 +237,7 @@ const SPAWN_CLI = [
   // Cheap: measured on the Windows runner at 448 ms, 53 ms and sub-second. An
   // earlier attempt to register them still turned the matrix red — not from
   // their own cost, but because vitest sharded by file COUNT, so inserting any
-  // file re-partitioned the list and happened to cluster `cli-e2e` (361 s) with
+  // file re-partitioned the list and happened to cluster `cli-e2e` (621 s) with
   // `cli-limit-e2e` (75 s) on one shard. The split is weight-aware now
   // (`scripts/cross-platform-shard.ts`), so a cheap file can no longer move a
   // heavy one.
@@ -271,6 +276,7 @@ const NATIVE_ADDON_SMOKE = [
 // platforms (CRLF, symlinks, permissions, temp dirs)
 const FILESYSTEM = [
   'test/integration/filesystem-walker.test.ts',
+  'test/integration/watch-filesystem.test.ts',
   'test/integration/markdown-processor-crlf.test.ts',
   'test/integration/ignore-and-skip-e2e.test.ts',
   // Pins that the bridge pairing verdict is measured before the database is

package/skills/gitnexus-cli.md

@@ -21,6 +21,8 @@ Run from the project root. This parses all source files, builds the knowledge gr
 
 | Flag           | Effect                                                           |
 | -------------- | ---------------------------------------------------------------- |
+| `--watch`      | Keep a Git repository index current with serialized refreshes    |
+| `--debounce <ms>` | Watch quiet period before refresh (default: 300 ms)            |
 | `--force`      | Force full re-index even if up to date                           |
 | `--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. |
@@ -28,6 +30,8 @@ Run from the project root. This parses all source files, builds the knowledge gr
 
 **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.
 
+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
 
 ```bash
@@ -55,15 +59,19 @@ Deletes the `.gitnexus/` directory and unregisters the repo from the global regi
 node .gitnexus/run.cjs wiki
 ```
 
-Generates repository documentation from the knowledge graph using an LLM. Requires an API key (saved to `~/.gitnexus/config.json` on first use).
+Generates repository documentation from the knowledge graph using an LLM. HTTP providers require an API key (saved to `~/.gitnexus/config.json` on first use). Local CLI providers (`--provider cursor|claude|codex|opencode|grok`) use your existing CLI login.
 
 | Flag                | Effect                                    |
 | ------------------- | ----------------------------------------- |
-| `--force`           | Force full regeneration                   |
+| `--force`           | Force full regeneration, also required to re-generate an existing wiki in a different language |
+| `--provider <name>` | LLM provider: minimax, openai, openrouter, azure, custom, cursor, claude, codex, opencode, or grok (default: minimax). Local CLIs (`cursor`, `claude`, `codex`, `opencode`, `grok`) use your existing CLI login and skip `--api-key`. |
 | `--model <model>`   | LLM model (default: MiniMax-M3)           |
 | `--base-url <url>`  | LLM API base URL                          |
 | `--api-key <key>`   | LLM API key                               |
 | `--concurrency <n>` | Parallel LLM calls (default: 3)           |
+| `--timeout <seconds>` | LLM request timeout in seconds (default: disabled) |
+| `--retries <n>`     | Max LLM retry attempts per request (default: 3) |
+| `--lang <lang>`     | Output language for generated documentation (e.g. english, chinese, spanish, japanese) |
 | `--gist`            | Publish wiki as a public GitHub Gist      |
 
 ### list — Show all indexed repos
@@ -82,5 +90,5 @@ Lists all repositories registered in `~/.gitnexus/registry.json`. The MCP `list_
 ## Troubleshooting
 
 - **"Not inside a git repository"**: Run from a directory inside a git repo
-- **Index is stale after re-analyzing**: Restart Claude Code to reload the MCP server
+- **Index is stale after re-analyzing**: Wait for the next MCP tool call to reopen the published index; this normally takes no more than five seconds
 - **Embeddings slow**: Omit `--embeddings` (it's off by default) or set `OPENAI_API_KEY` for faster API-based embedding

package/skills/gitnexus-impact-analysis.md

@@ -93,6 +93,15 @@ dispatch, cross-language calls), so few-callers ⇒ LOW does **not** apply. The
 result carries a `riskNote` saying so. Confirm with a text search before
 treating the symbol as safe to change or delete.
 
+`risk` is the edit gate: warn on HIGH/CRITICAL and stop on UNKNOWN until the
+uncertainty is resolved. Within single-repo mode, compare File and symbol
+targets with local `riskSharedAxes` (direct/total only). Within group mode,
+compare only group results: their `riskSharedAxes` overlays resolved
+cross-repo crossings on that local value. Never use either field to waive the
+edit gate. Check `riskScale.unusedAxes` before comparing kinds: MCP File walks
+omit process/module axes, while web Graph-RAG expands File targets to in-file
+symbols before enrichment.
+
 ## Tools
 
 **impact** — the primary tool for symbol blast radius. If MCP is unavailable, use `node .gitnexus/run.cjs impact <symbol> --direction upstream --repo .` instead: