gitnexus 1.6.9 → 1.6.10-rc.10

package/README.md

@@ -2,7 +2,7 @@
 
 **Graph-powered code intelligence for AI agents.** Index any codebase into a knowledge graph, then query it via MCP or CLI.
 
-Works with **Cursor**, **Claude Code**, **Antigravity** (Google), **Codex**, **Windsurf**, **Cline**, **OpenCode**, and any MCP-compatible tool.
+Works with **Cursor**, **Claude Code**, **Antigravity** (Google), **Codex**, **Windsurf**, **Cline**, **OpenCode**, **CodeBuddy** (Tencent), **Qoder** (Alibaba), and any MCP-compatible tool.
 
 [![npm version](https://img.shields.io/npm/v/gitnexus.svg)](https://www.npmjs.com/package/gitnexus)
 [![License: PolyForm Noncommercial](https://img.shields.io/badge/License-PolyForm%20Noncommercial-blue.svg)](https://polyformproject.org/licenses/noncommercial/1.0.0/)
@@ -43,11 +43,13 @@ To configure MCP for your editor, run `npx gitnexus setup` once — or set it up
 | **Claude Code**          | Yes | Yes    | Yes (PreToolUse + PostToolUse)                                                             | **Full**     |
 | **Cursor**               | Yes | Yes    | Yes (postToolUse, [manual install](../gitnexus-cursor-integration/README.md#hook-install)) | **Full**     |
 | **Antigravity** (Google) | Yes | Yes    | Yes (AfterTool, [Gemini CLI hooks schema](https://geminicli.com/docs/hooks/reference/))    | **Full**     |
-| **Codex**                | Yes | Yes    | —                                                                                          | MCP + Skills |
+| **Codex**                | Yes | Yes    | Yes (PreToolUse + PostToolUse, [Codex hooks](https://developers.openai.com/codex/hooks))   | **Full**     |
 | **OpenCode**             | Yes | Yes    | —                                                                                          | MCP + Skills |
+| **CodeBuddy** (Tencent)  | Yes | Yes    | —                                                                                          | MCP + Skills |
+| **Qoder** (Alibaba)      | Yes | Yes    | —                                                                                          | MCP + Skills |
 | **Windsurf**             | Yes | —      | —                                                                                          | MCP          |
 
-> **Claude Code** gets the deepest integration: MCP tools + agent skills + PreToolUse hooks that automatically enrich grep/glob/bash calls with knowledge graph context + PostToolUse hooks that detect a stale index after commits and prompt the agent to reindex.
+> **Claude Code** and **Codex** get the deepest integration: MCP tools + agent skills + PreToolUse hooks that automatically enrich grep/glob/bash calls with knowledge graph context + PostToolUse hooks that detect a stale index after commits and prompt the agent to reindex.
 
 ### Community Integrations
 
@@ -69,12 +71,23 @@ claude mcp add gitnexus -- npx -y gitnexus@latest mcp
 claude mcp add gitnexus -- cmd /c npx -y gitnexus@latest mcp
 ```
 
-### Codex (full support — MCP + skills)
+### Codex (full support — MCP + skills + hooks)
 
 ```bash
 codex mcp add gitnexus -- npx -y gitnexus@latest mcp
 ```
 
+Codex hooks (PreToolUse graph enrichment + PostToolUse stale-index detection in `~/.codex/hooks.json`, [same schema as Claude Code](https://developers.openai.com/codex/hooks)) need the bundled adapter script, so they are installed by `gitnexus setup -c codex` rather than manually.
+
+Alternatively, install everything as a [Codex plugin](https://developers.openai.com/codex/plugins/build) (MCP + skills + hooks in one step):
+
+```bash
+codex plugin marketplace add abhigyanpatwari/GitNexus
+# then inside Codex: /plugins → install "GitNexus"
+```
+
+> **Codex notes:** SessionStart is intentionally not registered — Codex reads [AGENTS.md natively](https://developers.openai.com/codex/guides/agents-md), which already carries the GitNexus context block. Newly installed hooks need a one-time approval in Codex via `/hooks` before they run. Pick **one** install route (`gitnexus setup -c codex` **or** the plugin): plugin hooks load alongside `~/.codex/hooks.json`, so installing both can fire duplicate hooks per tool call.
+
 ### Cursor / Windsurf
 
 Add to `~/.cursor/mcp.json` (global — works for all projects):
@@ -105,6 +118,36 @@ Add to `~/.config/opencode/config.json`:
 }
 ```
 
+### CodeBuddy
+
+CodeBuddy reads only the **first existing file** in its config priority chain: `~/.codebuddy/.mcp.json` (recommended) → `~/.codebuddy/mcp.json` (deprecated) → `~/.codebuddy.json` (legacy). Edit the first non-empty file that exists — creating a higher-priority file would hide the servers in the ones below it. If none exist, create `~/.codebuddy/.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "gitnexus": {
+      "command": "npx",
+      "args": ["-y", "gitnexus@latest", "mcp"]
+    }
+  }
+}
+```
+
+### Qoder
+
+Add to `~/.qoder.json`:
+
+```json
+{
+  "mcpServers": {
+    "gitnexus": {
+      "command": "npx",
+      "args": ["-y", "gitnexus@latest", "mcp"]
+    }
+  }
+}
+```
+
 ## How It Works
 
 GitNexus builds a complete knowledge graph of your codebase through a multi-phase indexing pipeline:
@@ -120,29 +163,39 @@ GitNexus builds a complete knowledge graph of your codebase through a multi-phas
 
 The result is a **LadybugDB graph database** stored locally in `.gitnexus/` with full-text search and semantic embeddings.
 
+### Experimental community detection engine
+
+Community detection uses the bundled Graphology Leiden implementation by default. To test the #2337 Icebug migration path without changing default analyze behavior, set:
+
+```bash
+GITNEXUS_COMMUNITY_ENGINE=icebug npx gitnexus analyze
+```
+
+Supported values are `graphology`, `icebug`, and `auto`. The Icebug path is an experimental probe: GitNexus does not bundle an Icebug native package yet, and if a separately resolvable module is unavailable or its API does not match the expected `Graph.fromCSR` / `ParallelLeidenView` shape, analyze falls back to Graphology and reports the fallback in progress output. Today `auto` is behaviorally identical to `icebug`: both try Icebug and fall back to Graphology, while `graphology` skips the Icebug probe entirely.
+
 ## MCP Tools
 
 Your AI agent gets **17 tools** (15 per-repo + 2 group) automatically:
 
 | Tool             | What It Does                                                           |
-| ---------------- | ----------------------------------------------------------------------- |
-| `list_repos`     | Discover all indexed repositories (paginated — `limit`/`offset`)        |
-| `query`          | Process-grouped hybrid search (BM25 + semantic + RRF)                   |
-| `context`        | 360-degree symbol view — categorized refs, process participation        |
-| `impact`         | Blast radius analysis with depth grouping and confidence                |
-| `trace`          | Shortest directed path between two symbols (call + class-member edges)  |
-| `detect_changes` | Git-diff impact — maps changed lines to affected processes              |
-| `check`          | Read-only structural checks against the indexed graph                   |
-| `rename`         | Multi-file coordinated rename with graph + text search                  |
-| `cypher`         | Raw Cypher graph queries                                                |
-| `route_map`      | API route map — which components fetch which endpoints, and handlers    |
-| `tool_map`       | MCP/RPC tool definitions — where they're defined and handled            |
-| `shape_check`    | Validate API response shapes against consumers' property accesses       |
-| `api_impact`     | Pre-change impact report for an API route handler                       |
-| `explain`        | Explain persisted taint findings (source→sink flows, `--pdg` indexes)   |
-| `pdg_query`      | Query control/data dependence at statement level (`--pdg` indexes)      |
-| `group_list`     | List configured repository groups                                       |
-| `group_sync`     | Rebuild a group's Contract Registry and cross-repo links                |
+| ---------------- | ---------------------------------------------------------------------- |
+| `list_repos`     | Discover all indexed repositories (paginated — `limit`/`offset`)       |
+| `query`          | Process-grouped hybrid search (BM25 + semantic + RRF)                  |
+| `context`        | 360-degree symbol view — categorized refs, process participation       |
+| `impact`         | Blast radius analysis with depth grouping and confidence               |
+| `trace`          | Shortest directed path between two symbols (call + class-member edges) |
+| `detect_changes` | Git-diff impact — maps changed lines to affected processes             |
+| `check`          | Read-only structural checks against the indexed graph                  |
+| `rename`         | Multi-file coordinated rename with graph + text search                 |
+| `cypher`         | Raw Cypher graph queries                                               |
+| `route_map`      | API route map — which components fetch which endpoints, and handlers   |
+| `tool_map`       | MCP/RPC tool definitions — where they're defined and handled           |
+| `shape_check`    | Validate API response shapes against consumers' property accesses      |
+| `api_impact`     | Pre-change impact report for an API route handler                      |
+| `explain`        | Explain persisted taint findings (source→sink flows, `--pdg` indexes)  |
+| `pdg_query`      | Query control/data dependence at statement level (`--pdg` indexes)     |
+| `group_list`     | List configured repository groups                                      |
+| `group_sync`     | Rebuild a group's Contract Registry and cross-repo links               |
 
 > With one indexed repo, the `repo` param is optional. With multiple, specify which: `query({search_query: "auth", repo: "my-app"})`. Per-repo tools also take an optional `branch` for indexes pinned with `gitnexus analyze --branch`; omitting it queries the workspace index, which follows your checked-out working tree. `explain` and `pdg_query` need an index built with `gitnexus analyze --pdg`.
 
@@ -177,6 +230,7 @@ gitnexus analyze [path]          # Index a repository (or update stale index)
 gitnexus analyze --repair-fts    # Fast path: rebuild/verify only FTS indexes on existing index data
 gitnexus analyze --force         # Full rebuild: re-parse + graph rebuild + FTS rebuild
 gitnexus analyze --embeddings    # Enable embedding generation (slower, better search)
+gitnexus embeddings install      # Fetch the optional local embedding stack on demand (--cuda, --force)
 gitnexus analyze --skills        # Generate repo-specific skill files from detected communities
 gitnexus analyze --skip-agents-md  # Preserve custom AGENTS.md/CLAUDE.md gitnexus section edits
 gitnexus analyze --skip-skills   # Skip installing .claude/skills/gitnexus/ skill files
@@ -377,19 +431,41 @@ If `npm install -g gitnexus` fails on native modules:
 npm install -g gitnexus
 ```
 
+### Installation fails behind an HTTP proxy (`onnxruntime-node` postinstall)
+
+`onnxruntime-node`'s postinstall downloads optional CUDA GPU binaries from `api.nuget.org` — outside the npm registry, so registry mirrors don't cover it, and its proxy layer (`global-agent`) ignores the standard `HTTP_PROXY`/`HTTPS_PROXY` variables and rejects 302 redirects ([#2370](https://github.com/abhigyanpatwari/GitNexus/issues/2370)).
+
+Since the packages are optional dependencies, a failed download no longer breaks `npm install -g gitnexus` — npm skips the embedding stack and everything else works. The stack then **self-heals on demand**: the first `gitnexus analyze --embeddings` (or an explicit `gitnexus embeddings install`) fetches it through your configured npm registry — mirrors and proxies apply, no NuGet download involved — into `~/.gitnexus/embedding-runtime`.
+
+```bash
+# heal a proxy-degraded install manually (CPU embeddings; registry-only)
+gitnexus embeddings install
+
+# reinstall into the prefix even when the stack already resolves
+gitnexus embeddings install --force
+
+# CUDA GPU hosts: also fetch GPU binaries (NuGet; set the proxy global-agent reads)
+GLOBAL_AGENT_HTTPS_PROXY=<proxy-url> gitnexus embeddings install --cuda
+```
+
+The prefix defaults to `~/.gitnexus/embedding-runtime`; set `GITNEXUS_EMBEDDING_RUNTIME_DIR` to install it elsewhere (e.g. a writable path in a container).
+
+> **Node requirement for the on-demand prefix:** the self-heal loads the prefixed packages via `module.registerHooks`, available on Node **≥ 22.15** (on the 22.x line) or **≥ 23.5** (on the 23.x line). On an older Node the packages install but can't be loaded from the prefix — reinstall them into the install itself instead (works on every supported Node): `ONNXRUNTIME_NODE_INSTALL=skip npm install -g gitnexus` (Windows: `set ONNXRUNTIME_NODE_INSTALL=skip && npm install -g gitnexus`). Skipping only the CUDA download keeps full CPU embeddings (CPU embeddings don't need it). Check the result any time with `gitnexus doctor` (Embeddings → Support line).
+
 ### Analyze warns about unavailable FTS or VECTOR extensions
 
-GitNexus uses optional DuckDB extensions for BM25 and vector search. The `gitnexus serve` and MCP read paths only ever try to `LOAD` the extensions — they never block on a network install. The `analyze` command, by default, attempts one bounded out-of-process `INSTALL` if `LOAD` fails and proceeds even when that install times out, so the index is always written to disk; BM25/vector search degrade gracefully until the extensions become available.
+GitNexus uses optional DuckDB extensions for BM25 and vector search. The `gitnexus serve` and MCP read paths only ever try to `LOAD` the extensions — they never block on a network install. The `analyze` command, by default, attempts one bounded out-of-process install if `LOAD` fails (a plain `INSTALL` to download a missing extension, escalating to `FORCE INSTALL` only when the `LOAD` error shows the existing file is broken or truncated, so a permanent non-file failure does not re-download on every run) and proceeds even when that install times out, so the index is always written to disk; BM25/vector search degrade gracefully until the extensions become available.
 
 Configure the behavior with these environment variables:
 
-| Variable                                     | Values                       | Default             | Effect                                                                                                                                                                                                                                                                                   |
-| -------------------------------------------- | ---------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `GITNEXUS_LBUG_EXTENSION_INSTALL`            | `auto`, `load-only`, `never` | `auto`              | `auto` runs one bounded INSTALL if LOAD fails. `load-only` only uses already-installed extensions (recommended for offline / firewalled environments). `never` skips optional extensions entirely.                                                                                       |
-| `GITNEXUS_LBUG_EXTENSION_INSTALL_TIMEOUT_MS` | positive integer             | `15000`             | Wall-clock budget for the out-of-process `INSTALL` child before it is killed.                                                                                                                                                                                                            |
-| `GITNEXUS_FTS_STEMMER`                       | supported LadybugDB stemmer  | `porter`            | Stemmer used when rebuilding BM25/FTS indexes. Use `none` for CJK-heavy repositories, or a language stemmer such as `german`, `french`, or `spanish` when that better matches repository comments and identifiers. Re-run `gitnexus analyze --repair-fts` after changing it.              |
+| Variable                                     | Values                       | Default             | Effect                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| -------------------------------------------- | ---------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GITNEXUS_LBUG_EXTENSION_INSTALL`            | `auto`, `load-only`, `never` | `auto`              | `auto` runs one bounded install if LOAD fails — a plain `INSTALL`, escalating to `FORCE INSTALL` only when the LOAD error shows the present extension file is broken. `load-only` only uses already-installed extensions (recommended for offline / firewalled environments). `never` skips optional extensions entirely.                                                                                                                                                                                                                                                                                                                                                                               |
+| `GITNEXUS_LBUG_EXTENSION_INSTALL_TIMEOUT_MS` | positive integer             | `15000`             | Wall-clock budget for the out-of-process extension-install child before it is killed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `GITNEXUS_FTS_STEMMER`                       | supported LadybugDB stemmer  | `porter`            | Stemmer used when rebuilding BM25/FTS indexes. Use `none` for CJK-heavy repositories, or a language stemmer such as `german`, `french`, or `spanish` when that better matches repository comments and identifiers. Re-run `gitnexus analyze --repair-fts` after changing it.                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `GITNEXUS_FTS_CJK_SEGMENTATION`              | `none`, `bigram`             | `none`              | `bigram` inserts overlapping character-bigram boundaries into Chinese/Japanese Han-ideograph spans in `content`/`description` before FTS indexing, so LadybugDB's space-only tokenizer can see sub-phrase word boundaries. Scoped to CJK Unified Ideographs only — Japanese Hiragana/Katakana and Korean Hangul are not currently segmented. Unlike `GITNEXUS_FTS_STEMMER`, this rewrites stored text — enabling it on an already-indexed repo requires a full `gitnexus analyze --force`; neither `--repair-fts` nor a plain incremental `analyze` applies it to previously-indexed files. Set the same value wherever `analyze` and search-serving processes (CLI query, MCP server, web server) run. |
-| `GITNEXUS_WAL_CHECKPOINT_THRESHOLD`          | integer `>= -1`              | `67108864` (64 MiB) | LadybugDB WAL auto-checkpoint threshold during analyze (bytes). Auto-checkpoint remains enabled; `-1` keeps Ladybug's stock ~16 MiB. Larger thresholds reduce checkpoint frequency but increase the WAL size at rotation time — choose a smaller value on disk-constrained environments. |
+| `GITNEXUS_COMMUNITY_ENGINE`                  | `graphology`, `icebug`, `auto` | `graphology`        | Community-detection engine used during analyze. `graphology` uses the bundled default path. `icebug` and `auto` currently behave identically: both try the experimental Icebug CSR path and fall back to Graphology if the optional native module is unavailable or incompatible.                                                                                                                                                                                                                                                                                                                                                         |
+| `GITNEXUS_WAL_CHECKPOINT_THRESHOLD`          | integer `>= -1`              | `67108864` (64 MiB) | LadybugDB WAL auto-checkpoint threshold during analyze (bytes). Auto-checkpoint remains enabled; `-1` keeps Ladybug's stock ~16 MiB. Larger thresholds reduce checkpoint frequency but increase the WAL size at rotation time — choose a smaller value on disk-constrained environments.                                                                                                                                                                                                                                                                                                                                                                                                                |
 
 ```bash
 # Offline/airgapped: never reach the network for extensions
@@ -464,23 +540,32 @@ Three env vars expose the pool's resilience layers (respawn budget, cumulative-t
 
 After scope resolution, analyze prunes inert block-local value symbols (a function-local `const`/`let`/`var` that ends up with only its structural `File→DEFINES` edge) to keep the graph focused on cross-symbol relationships. Module/file-scope symbols, class members, and any local with a real edge are always kept.
 
-| Variable                             | Default | Effect                                                                                                  |
-| ------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------- |
-| `GITNEXUS_KEEP_LOCAL_VALUE_SYMBOLS`  | unset   | Set to `1`/`true` to keep inert block-local value symbols instead of pruning them.                      |
+| Variable                            | Default | Effect                                                                             |
+| ----------------------------------- | ------- | ---------------------------------------------------------------------------------- |
+| `GITNEXUS_KEEP_LOCAL_VALUE_SYMBOLS` | unset   | Set to `1`/`true` to keep inert block-local value symbols instead of pruning them. |
 
 Programmatic callers can pass `keepLocalValueSymbols: true` in `PipelineOptions` instead of setting the env var.
 
-### Hook augmentation/notifications are silently skipped
+### Hook augmentation and skip diagnostics
 
-The Claude Code / Antigravity hooks intentionally stay **silent** on normal skip
+The Claude Code / Antigravity hooks keep their **stderr** silent on normal skip
 paths so strict hook runners (e.g. Codex `PreToolUse`) never see unexpected
-output. A search may not be augmented — or a stale-index reminder may not appear
-on stderr — when the GitNexus MCP server owns the repo DB, when the DB-lock probe
-times out and fails closed, or when the index is already current.
-
-To see why a hook skipped, set `GITNEXUS_DEBUG=1` and re-run the action — the hook
-writes the reason (e.g. `[GitNexus] augment skipped: MCP server owns DB`) and the
-stale-index hint to its stderr:
+diagnostic output.
+
+When a GitNexus process holds the repo DB write lock (the common case — the MCP
+server is running, or the DB-lock probe timed out and failed closed), the local
+CLI `augment` can't run (LadybugDB is single-writer). Rather than drop the
+augmentation, the hook hands the agent a short, conditional MCP-query hint on
+stdout (the sanctioned `additionalContext` channel) — _"if the GitNexus MCP tools
+are live in this session, call `query` …"_ — so an agent that has the tools can
+still fetch graph-ranked context. The hint is throttled to at most once per repo
+per window (`GITNEXUS_MCP_HINT_THROTTLE_MS`, default 10 min; `0` disables), so an
+owner-locked session isn't nudged on every search. A stale-index reminder, or an
+already-current index, stays silent.
+
+To see why a hook skipped the CLI augment, set `GITNEXUS_DEBUG=1` and re-run the
+action — the hook writes the reason (e.g. `[GitNexus] augment skipped: MCP server
+owns DB`) and the stale-index hint to its stderr:
 
 ```bash
 GITNEXUS_DEBUG=1 <your command>   # surfaces hook skip/diagnostic reasons on stderr

package/dist/cli/ai-context.d.ts

@@ -2,7 +2,7 @@
  * AI Context Generator
  *
  * Creates AGENTS.md and CLAUDE.md with full inline GitNexus context.
- * AGENTS.md is the standard read by Cursor, Windsurf, OpenCode, Codex, Cline, etc.
+ * AGENTS.md is the standard read by Cursor, Windsurf, OpenCode, Codex, Cline, CodeBuddy, Qoder, etc.
  * CLAUDE.md is for Claude Code which only reads that file.
  */
 import { type GeneratedSkillInfo } from './skill-gen.js';

package/dist/cli/ai-context.js

@@ -2,7 +2,7 @@
  * AI Context Generator
  *
  * Creates AGENTS.md and CLAUDE.md with full inline GitNexus context.
- * AGENTS.md is the standard read by Cursor, Windsurf, OpenCode, Codex, Cline, etc.
+ * AGENTS.md is the standard read by Cursor, Windsurf, OpenCode, Codex, Cline, CodeBuddy, Qoder, etc.
  * CLAUDE.md is for Claude Code which only reads that file.
  */
 import fs from 'fs/promises';

package/dist/cli/analyze.js

@@ -27,8 +27,9 @@ import { cliError } from './cli-message.js';
 import { EMBEDDING_DIMS_ERROR, normalizeEmbeddingDims } from './embedding-dims.js';
 import { formatElapsed } from './format-elapsed.js';
 import { isHfDownloadFailure } from '../core/embeddings/hf-env.js';
-import { safeUrl } from '../core/embeddings/http-client.js';
-import { isLocalEmbeddingRuntimeBlockerMessage } from '../core/embeddings/runtime-support.js';
+import { isHttpEmbeddingDimsError, isHttpEmbeddingError, isHttpMode, safeUrl, } from '../core/embeddings/http-client.js';
+import { isLocalEmbeddingRuntimeBlockerMessage, isMissingLocalEmbeddingStackMessage, localEmbeddingPrefixUnloadableMessage, localEmbeddingStackMissingMessage, } from '../core/embeddings/runtime-support.js';
+import { ANALYZE_EMBEDDING_INSTALL_TIMEOUT_MS, getEmbeddingInstallTimeoutMs, getEmbeddingRuntimeDir, installEmbeddingRuntime, isPrefixRuntimeLoadable, resolveEmbeddingRuntime, } from '../core/embeddings/runtime-install.js';
 import { warnIfNpm11NpxRisk } from './resolve-invocation.js';
 // Capture stderr.write at module load BEFORE anything (LadybugDB native
 // init, progress bar, console redirection) can monkey-patch it. The
@@ -797,6 +798,52 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
         console.log('  Note: custom HTTP embeddings require BOTH --embedding-base-url and --embedding-model ' +
             '(or the matching env vars). Falling back to local ONNX embeddings.\n');
     }
+    // On-demand embedding runtime (#2370): when the optional stack was pruned at
+    // install time (proxy-blocked NuGet download in onnxruntime-node's
+    // postinstall), heal it here instead of failing later in the pipeline. The
+    // install goes through the user's npm registry config (mirrors/proxies
+    // apply) with --ignore-scripts, so no NuGet download is attempted. Runs
+    // before bar.start() like the sibling validations above.
+    if (embeddingsEnabled && !isHttpMode()) {
+        const resolved = resolveEmbeddingRuntime();
+        // Resolved-but-unloadable (a populated prefix on a Node with no
+        // module.registerHooks), or nothing installed on such a Node: fail fast with
+        // capability guidance instead of dying mid-pipeline over an unusable prefix
+        // or downloading a runtime the loader can't reach. A package-sourced stack
+        // never needs the hook, so it is excluded. --embeddings was explicitly
+        // requested and this failure is deterministic, so fail fast rather than
+        // silently degrading to BM25 (distinct from a transient install timeout).
+        if (!isPrefixRuntimeLoadable() && (resolved === null || resolved.source === 'runtime-prefix')) {
+            cliError(`  ${localEmbeddingPrefixUnloadableMessage().replace(/\n/g, '\n  ')}\n`, {
+                recoveryHint: 'local-embedding-stack-missing',
+            });
+            process.exitCode = 1;
+            return;
+        }
+        // On-demand embedding runtime (#2370): when the optional stack was pruned at
+        // install time (proxy-blocked NuGet download in onnxruntime-node's
+        // postinstall), heal it here instead of failing later in the pipeline. The
+        // install goes through the user's npm registry config (mirrors/proxies
+        // apply) with --ignore-scripts, so no NuGet download is attempted.
+        if (resolved === null) {
+            console.log(`  Local embedding runtime is not installed (optional packages were skipped at install time).\n` +
+                `  Downloading it now from your npm registry into ${getEmbeddingRuntimeDir()} …\n` +
+                `  (one-time; rerun manually anytime with \`gitnexus embeddings install\`)\n`);
+            try {
+                // Short deadline (env override still wins): analyze is interactive, so a
+                // blackholed proxy must not stall the whole index run for the 10-minute
+                // default — fail over to the guidance below instead.
+                await installEmbeddingRuntime({}, getEmbeddingInstallTimeoutMs(ANALYZE_EMBEDDING_INSTALL_TIMEOUT_MS));
+                console.log('  Embedding runtime installed.\n');
+            }
+            catch (err) {
+                cliError(`  Could not install the embedding runtime: ${err instanceof Error ? err.message : String(err)}\n\n` +
+                    `  ${localEmbeddingStackMissingMessage().replace(/\n/g, '\n  ')}\n`, { recoveryHint: 'local-embedding-stack-missing' });
+                process.exitCode = 1;
+                return;
+            }
+        }
+    }
     if (options.repairFts && options.force) {
         cliError('  Cannot combine `--repair-fts` with `--force`. ' +
             'Use `--repair-fts` for fast FTS-only repair, or `--force` for a full rebuild.\n');
@@ -1203,10 +1250,66 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
             process.exitCode = 1;
             return;
         }
+        // The optional embedding stack (@huggingface/transformers → onnxruntime-node)
+        // was pruned at install time — usually a proxy-blocked NuGet download during
+        // onnxruntime-node's postinstall (#2370). Checked before the generic
+        // module-not-found "installation may be corrupt" hint below, which would
+        // otherwise misdiagnose a deliberate optional-dependency skip.
+        if (isMissingLocalEmbeddingStackMessage(msg)) {
+            cliError(`  ${msg.replace(/\n/g, '\n  ')}\n`, {
+                recoveryHint: 'local-embedding-stack-missing',
+            });
+            process.exitCode = 1;
+            return;
+        }
+        // Malformed GITNEXUS_EMBEDDING_DIMS env var (#2385). readConfig() throws a
+        // plain Error (a config mistake, not an endpoint failure), surfacing here from
+        // httpEmbed()->readConfig() inside the analysis run. Show a clean config
+        // message rather than a raw stack dump. The --embedding-dims CLI flag is
+        // validated up front (EMBEDDING_DIMS_ERROR); this covers the env-var path.
+        // Checked before the endpoint/HF branches: it is a plain Error, so
+        // isHttpEmbeddingError() is false and the HF network heuristic must not claim it.
+        if (isHttpEmbeddingDimsError(msg)) {
+            cliError(`  ${msg.replace(/\n/g, '\n  ')}\n`, {
+                recoveryHint: 'embedding-dims-invalid',
+            });
+            process.exitCode = 1;
+            return;
+        }
+        // Custom HTTP embedding endpoint failure (#2385). When a `--embedding-base-url`
+        // is configured, HTTP mode never downloads a model — so a failure talking to
+        // that endpoint must NOT show the huggingface-download guidance. Keyed on the
+        // error *type* (HttpEmbeddingError), not its message text, so it stays correct
+        // regardless of locale or wording. Checked before the HF branch, whose network
+        // heuristic (`fetch failed` / `ECONNREFUSED`) would otherwise also match a
+        // wrapped endpoint-connection error. The header is deliberately neutral: this
+        // type covers both never-reached failures (connection/timeout/DNS) and
+        // reached-but-failed ones (4xx/5xx, dimension/shape mismatch), so it must not
+        // assert "unreachable". The thrown `msg` carries the specific reason (and the
+        // masked URL where one applies), so it is surfaced verbatim.
+        if (isHttpEmbeddingError(err)) {
+            cliError(`  The custom embedding endpoint request failed.\n` +
+                `  ${msg.replace(/\n/g, '\n  ')}\n` +
+                `  Suggestions:\n` +
+                `    1. Verify the endpoint URL is reachable and running ` +
+                `(--embedding-base-url / GITNEXUS_EMBEDDING_URL: host, port, /v1 path).\n` +
+                `    2. Confirm the model name and embedding dimensions match what the endpoint serves.\n` +
+                `    3. Re-run without --embeddings to index without vectors.\n`, { recoveryHint: 'http-embedding-endpoint-error' });
+            process.exitCode = 1;
+            return;
+        }
+        // isHttpMode() is a pure presence probe (URL+MODEL) that never throws — a
+        // malformed GITNEXUS_EMBEDDING_DIMS is handled by the dims branch above — so
+        // no defensive try/catch is needed here (#2385).
+        const inHttpMode = isHttpMode();
         // HF download failure — show clean guidance without the raw stack trace.
         // Checked before writeFatalToStderr so the user sees one focused message
         // rather than a stack-trace dump followed by a second remediation block.
-        if (isHfDownloadFailure(msg) || msg.includes('Failed to download embedding model')) {
+        // Gated on !inHttpMode: with a custom endpoint configured no model download
+        // is ever attempted, so a network error there is the endpoint's, handled by
+        // the HttpEmbeddingError branch above — never HF's (#2385).
+        if ((isHfDownloadFailure(msg) || msg.includes('Failed to download embedding model')) &&
+            !inHttpMode) {
             cliError(`  The embedding model could not be downloaded.\n` +
                 `  huggingface.co may be unreachable from your network\n` +
                 `  (e.g. behind a corporate proxy or a regional firewall).\n` +

package/dist/cli/cli-message.d.ts

@@ -12,7 +12,7 @@ import { type CliMessageKey, type CliMessageVars } from './i18n/index.js';
  * Consumers can import this type to narrow log-record `recoveryHint`
  * fields without restating the literal list.
  */
-export type RecoveryHint = 'wal-corruption' | 'wal-checkpoint-threshold' | 'heap-oom-respawn' | 'native-worker-abort' | 'hf-endpoint-unreachable' | 'local-embedding-unsupported' | 'large-repo' | 'npm-resolution' | 'module-not-found' | 'gitnexusrc-invalid' | 'default-branch-invalid';
+export type RecoveryHint = 'wal-corruption' | 'wal-checkpoint-threshold' | 'heap-oom-respawn' | 'native-worker-abort' | 'hf-endpoint-unreachable' | 'http-embedding-endpoint-error' | 'embedding-dims-invalid' | 'local-embedding-unsupported' | 'local-embedding-stack-missing' | 'large-repo' | 'npm-resolution' | 'module-not-found' | 'gitnexusrc-invalid' | 'default-branch-invalid';
 /**
  * Common shape for the optional structured-field bag passed to
  * `cliError`/`cliWarn`/`cliInfo`. Typed so the `recoveryHint` slot is

package/dist/cli/doctor.d.ts

@@ -1,3 +1,4 @@
+import { type EmbeddingRuntimeResolution } from '../core/embeddings/runtime-install.js';
 export declare function displayWidth(value: string): number;
 export declare function padDisplayEnd(value: string, columns: number): string;
 /**
@@ -14,6 +15,10 @@ export declare function localEmbeddingDoctorStatus(opts: {
     httpMode: boolean;
     platform?: NodeJS.Platform;
     arch?: NodeJS.Architecture;
+    /** Injectable for tests; defaults to probing the real install. */
+    resolution?: EmbeddingRuntimeResolution | null;
+    /** Injectable for tests; defaults to this Node's registerHooks capability. */
+    prefixLoadable?: boolean;
 }): {
     status: string;
     detail: string | null;

package/dist/cli/doctor.js

@@ -1,9 +1,11 @@
 import { getRuntimeCapabilities, getRuntimeFingerprint } from '../core/platform/capabilities.js';
 import { resolveEmbeddingConfig } from '../core/embeddings/config.js';
 import { isHttpMode } from '../core/embeddings/http-client.js';
-import { getLocalEmbeddingRuntimeBlocker } from '../core/embeddings/runtime-support.js';
+import { getLocalEmbeddingRuntimeBlocker, localEmbeddingPrefixUnloadableMessage, localEmbeddingStackMissingMessage, } from '../core/embeddings/runtime-support.js';
+import { isPrefixRuntimeLoadable, resolveEmbeddingRuntime, } from '../core/embeddings/runtime-install.js';
 import { cudaRedirectDoctorStatus } from '../core/embeddings/onnxruntime-node-resolver.js';
-import { checkLbugNative } from '../core/lbug/native-check.js';
+import { checkLbugNative, probeFtsExtensionLoad } from '../core/lbug/native-check.js';
+import { diagnoseExtensionLoad } from '../core/lbug/extension-load-error.js';
 import { getExtensionInstallPolicy } from '../core/lbug/extension-loader.js';
 import { t } from './i18n/index.js';
 function isCombiningMark(codePoint) {
@@ -64,6 +66,25 @@ export function localEmbeddingDoctorStatus(opts) {
     if (blocker) {
         return { status: `✗ local embeddings unavailable on ${platform}/${arch}`, detail: blocker };
     }
+    // The stack is an optionalDependency — npm prunes it when onnxruntime-node's
+    // postinstall can't download its CUDA binaries (proxy/firewall, #2370).
+    const resolution = opts.resolution !== undefined ? opts.resolution : resolveEmbeddingRuntime();
+    if (resolution === null) {
+        return {
+            status: '✗ optional embedding stack not installed',
+            detail: localEmbeddingStackMissingMessage(),
+        };
+    }
+    // A prefix-sourced stack needs module.registerHooks to load; on Node < 22.15 /
+    // < 23.5 it is present but unreachable (#2372). Report loadability, not bare
+    // presence, so the diagnostic stops claiming a ✓ the loader can't honour.
+    const prefixLoadable = opts.prefixLoadable ?? isPrefixRuntimeLoadable();
+    if (resolution.source === 'runtime-prefix' && !prefixLoadable) {
+        return {
+            status: '✗ embedding stack installed in the prefix but not loadable on this Node',
+            detail: localEmbeddingPrefixUnloadableMessage(),
+        };
+    }
     return { status: '✓ local embeddings supported', detail: null };
 }
 export const doctorCommand = async () => {
@@ -88,7 +109,24 @@ export const doctorCommand = async () => {
     console.log('');
     console.log(t('doctor.capabilities'));
     console.log(`  ${label('doctor.labels.graphStore', 18)}${capabilities.graph}`);
-    console.log(`  ${label('doctor.labels.fullTextSearch', 18)}${capabilities.fts}`);
+    // Live LOAD probe, not the static platform capability — the static value
+    // said "available" while analyze failed to load the extension (#2374).
+    const ftsProbe = nativeCheck.ok
+        ? await probeFtsExtensionLoad()
+        : { loaded: false, reason: 'LadybugDB native module (lbugjs.node) failed to load' };
+    console.log(`  ${label('doctor.labels.fullTextSearch', 18)}${ftsProbe.loaded ? 'available' : 'unavailable'}`);
+    if (!ftsProbe.loaded && ftsProbe.reason) {
+        console.log(`  ${padDisplayEnd('', 18)}${ftsProbe.reason}`);
+        // Add an actionable remedy for recognized failure classes (#2374). The
+        // Windows missing-dependency case is the point of this: the raw error 126
+        // ("specified module could not be found") is opaque, so name the fix (VC++
+        // redist, then OpenSSL) instead of leaving the user to reinstall in vain.
+        // `unknown`'s remedy is "run doctor", which would be circular here.
+        const { kind, remedy } = diagnoseExtensionLoad(ftsProbe.reason);
+        if (kind !== 'unknown') {
+            console.log(`  ${padDisplayEnd('', 18)}${remedy}`);
+        }
+    }
     console.log(`  ${label('doctor.labels.vectorIndex', 18)}${capabilities.vector}`);
     console.log(`  ${label('doctor.labels.semanticMode', 18)}${capabilities.semanticMode}`);
     // Surface the optional-extension install policy so offline users can see

package/dist/cli/editor-targets.d.ts

@@ -15,7 +15,7 @@
  * implementations remain behaviourally symmetrical on top of this shared
  * structure.
  */
-export type EditorId = 'cursor' | 'claude' | 'antigravity' | 'opencode' | 'codex';
+export type EditorId = 'cursor' | 'claude' | 'antigravity' | 'opencode' | 'codebuddy' | 'qoder' | 'codex';
 /** An editor whose MCP config is a JSONC document (server keyed by name). */
 export interface McpJsoncTarget {
     id: EditorId;
@@ -29,6 +29,14 @@ export interface McpJsoncTarget {
      * without either side needing a cast.
      */
     keyPath: string[];
+    /**
+     * Older config locations the editor still reads when `file` is absent
+     * (CodeBuddy reads only the FIRST existing file in its priority chain).
+     * Setup writes into the first existing candidate of [file, ...legacyFiles]
+     * so it never shadows a user's servers living in a deprecated file;
+     * uninstall sweeps all of them.
+     */
+    legacyFiles?: string[];
 }
 /** Codex stores MCP config as a TOML table, not JSONC. */
 export interface CodexMcpTarget {
@@ -58,7 +66,7 @@ export interface HookTarget {
     scriptDir: string;
 }
 export interface EditorTargets {
-    /** JSONC-format MCP entries: Cursor, Claude Code, Antigravity, OpenCode. */
+    /** JSONC-format MCP entries: Cursor, Claude Code, Antigravity, OpenCode, CodeBuddy, Qoder. */
     mcpJsonc: McpJsoncTarget[];
     /** Codex MCP (TOML). */
     codex: CodexMcpTarget;
@@ -80,6 +88,13 @@ export declare function mcpTarget(id: EditorId, home?: string): McpJsoncTarget;
 export declare function skillTarget(id: EditorId, home?: string): SkillTarget;
 /** Look up a single hook target by editor id (throws if unknown). */
 export declare function hookTarget(id: EditorId, home?: string): HookTarget;
+/**
+ * True when err is a Node fs error with code ENOENT (file/dir absent).
+ * Shared by setup and uninstall: both must swallow ONLY absence when reading
+ * editor configs — any other read/stat failure (EACCES, EIO) is surfaced so an
+ * unreadable config is never treated as empty and rewritten gitnexus-only.
+ */
+export declare function isEnoent(err: unknown): boolean;
 /**
  * Detect indentation style from file content so JSONC edits preserve the file's
  * existing formatting. Shared by setup (writes) and uninstall (removes).

package/dist/cli/editor-targets.js

@@ -50,6 +50,26 @@ export function getEditorTargets(home = os.homedir()) {
             // OpenCode nests servers under `mcp`, not `mcpServers`.
             keyPath: ['mcp', 'gitnexus'],
         },
+        {
+            id: 'codebuddy',
+            label: 'CodeBuddy',
+            // Recommended user-scope path per https://www.codebuddy.ai/docs/cli/mcp;
+            // CodeBuddy reads only the first existing file in this priority chain.
+            file: path.join(home, '.codebuddy', '.mcp.json'),
+            legacyFiles: [
+                path.join(home, '.codebuddy', 'mcp.json'), // deprecated
+                path.join(home, '.codebuddy.json'), // legacy
+            ],
+            keyPath: ['mcpServers', 'gitnexus'],
+        },
+        {
+            id: 'qoder',
+            label: 'Qoder',
+            // Qoder's documented user-scope MCP config (https://docs.qoder.com/cli/using-cli);
+            // the IDE manages MCP via its Settings UI with no documented file path.
+            file: path.join(home, '.qoder.json'),
+            keyPath: ['mcpServers', 'gitnexus'],
+        },
     ];
     const codex = {
         id: 'codex',
@@ -66,6 +86,10 @@ export function getEditorTargets(home = os.homedir()) {
         },
         { id: 'cursor', label: 'Cursor', dir: path.join(home, '.cursor', 'skills') },
         { id: 'opencode', label: 'OpenCode', dir: path.join(home, '.config', 'opencode', 'skills') },
+        { id: 'codebuddy', label: 'CodeBuddy', dir: path.join(home, '.codebuddy', 'skills') },
+        // Qoder skills live at ~/.qoder/skills/{name}/SKILL.md
+        // (https://docs.qoder.com/extensions/skills).
+        { id: 'qoder', label: 'Qoder', dir: path.join(home, '.qoder', 'skills') },
         // Codex reads skills from ~/.agents/skills (not ~/.codex).
         { id: 'codex', label: 'Codex', dir: path.join(home, '.agents', 'skills') },
     ];
@@ -78,6 +102,17 @@ export function getEditorTargets(home = os.homedir()) {
             needle: 'gitnexus-hook',
             scriptDir: path.join(home, '.claude', 'hooks', 'gitnexus'),
         },
+        {
+            id: 'codex',
+            label: 'Codex',
+            // Codex hooks use Claude Code's exact {hooks: {Event: [...]}} JSON shape
+            // and hookSpecificOutput response contract, in a dedicated hooks.json
+            // (https://developers.openai.com/codex/hooks).
+            settingsFile: path.join(home, '.codex', 'hooks.json'),
+            events: ['PreToolUse', 'PostToolUse'],
+            needle: 'gitnexus-hook',
+            scriptDir: path.join(home, '.codex', 'hooks', 'gitnexus'),
+        },
         {
             id: 'antigravity',
             label: 'Antigravity',
@@ -110,6 +145,15 @@ export function hookTarget(id, home) {
         throw new Error(`No hook target for editor "${id}"`);
     return t;
 }
+/**
+ * True when err is a Node fs error with code ENOENT (file/dir absent).
+ * Shared by setup and uninstall: both must swallow ONLY absence when reading
+ * editor configs — any other read/stat failure (EACCES, EIO) is surfaced so an
+ * unreadable config is never treated as empty and rewritten gitnexus-only.
+ */
+export function isEnoent(err) {
+    return err?.code === 'ENOENT';
+}
 /**
  * Detect indentation style from file content so JSONC edits preserve the file's
  * existing formatting. Shared by setup (writes) and uninstall (removes).