fix: add CHECKPOINT before closeLbug to prevent WAL corruption on Windows

On Windows with LadybugDB 0.16.0, the non-blocking checkpoint thread can
outlive the close() call and leave WAL/sidecar pages pending on disk.
When a subsequent read-side open occurs (e.g. gitnexus query/cypher after
analyze --embeddings), it races with the WAL replay or trips the database-id
check on the sidecars, triggering the UNREACHABLE_CODE assertion.

Fix: issue CHECKPOINT before closing the connection in closeLbug() and in
doInitLbug() (when switching databases), matching the pattern already used
in closeBridgeDb() in bridge-db.ts. CHECKPOINT is a no-op when nothing is
pending, so it is safe on all platforms and LadybugDB versions.

Agent-Logs-Url: https://github.com/abhigyanpatwari/GitNexus/sessions/6d853496-e7b9-4e98-a906-475a756a05c5

Co-authored-by: magyargergo <11230420+magyargergo@users.noreply.github.com>

.claude/skills/gitnexus/gitnexus-cli/SKILL.md

@@ -17,12 +17,13 @@ npx gitnexus analyze
 
 Run from the project root. This parses all source files, builds the knowledge graph, writes it to `.gitnexus/`, and generates CLAUDE.md / AGENTS.md context files.
 
-| Flag           | Effect                                                           |
-| -------------- | ---------------------------------------------------------------- |
-| `--force`      | Force full re-index even if up to date                           |
-| `--embeddings` | Enable embedding generation for semantic search (off by default) |
+| Flag                | Effect                                                                                                  |
+| ------------------- | ------------------------------------------------------------------------------------------------------- |
+| `--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.    |
 
-**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 runs `analyze` automatically after `git commit` and `git merge`, preserving embeddings if previously generated.
+**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.
 
 ### status — Check index freshness
 

.dockerignore

@@ -14,6 +14,8 @@ coverage
 .env.local
 .env.*.local
 
+**/*.tsbuildinfo
+
 .gitnexus
 gitnexus-web/playwright-report
 gitnexus-web/test-results

.env.example

@@ -1,4 +1,8 @@
-# Images (signed Cosign keyless on every push from main / vX.Y.Z tags)
+# Images (signed Cosign keyless on every push from main / vX.Y.Z tags).
+# Available from both GHCR (default below) and Docker Hub — pick one:
+#   GHCR:       ghcr.io/abhigyanpatwari/gitnexus{,-web}:latest
+#   Docker Hub: akonlabs/gitnexus{,-web}:latest
+# Both registries receive the same digest from a single signed build.
 SERVER_IMAGE=ghcr.io/abhigyanpatwari/gitnexus:latest
 WEB_IMAGE=ghcr.io/abhigyanpatwari/gitnexus-web:latest
 

.github/actions/docker-build-push-retry/action.yml

@@ -0,0 +1,105 @@
+# Wraps docker/build-push-action with one automatic retry. Upstream explicitly
+# keeps retry out of the action (docker/build-push-action#1422); a local
+# composite keeps docker.yml readable and pins the same action SHA in one place.
+name: Docker build-push (with retry)
+description: >-
+  Runs docker/build-push-action twice on failure with a configurable backoff,
+  then exposes the digest from whichever attempt succeeded.
+
+inputs:
+  context:
+    description: Build context path
+    required: false
+    default: '.'
+  file:
+    description: Dockerfile path (relative to repo root)
+    required: true
+  platforms:
+    description: Comma-separated platforms list for buildx
+    required: true
+  push:
+    description: Whether to push (string 'true' or 'false')
+    required: true
+  tags:
+    description: Newline-separated image tags (from docker/metadata-action)
+    required: true
+  labels:
+    description: Labels string (from docker/metadata-action)
+    required: true
+  cache-from:
+    description: buildx cache-from value
+    required: true
+  cache-to:
+    description: buildx cache-to value (include ignore-error=true for GHA cache flakes)
+    required: true
+  retry-wait-seconds:
+    description: Seconds to sleep before the second attempt
+    required: false
+    default: '45'
+
+outputs:
+  digest:
+    description: Manifest digest from the successful build attempt
+    value: ${{ steps.resolve.outputs.digest }}
+
+runs:
+  using: composite
+  steps:
+    - name: Build and push (attempt 1)
+      id: try1
+      continue-on-error: true
+      uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+      with:
+        context: ${{ inputs.context }}
+        file: ${{ inputs.file }}
+        platforms: ${{ inputs.platforms }}
+        push: ${{ inputs.push == 'true' }}
+        tags: ${{ inputs.tags }}
+        labels: ${{ inputs.labels }}
+        cache-from: ${{ inputs.cache-from }}
+        cache-to: ${{ inputs.cache-to }}
+        provenance: mode=max
+        sbom: true
+
+    - name: Backoff before Docker build retry
+      if: steps.try1.outcome == 'failure'
+      shell: bash
+      env:
+        RETRY_WAIT_SECONDS: ${{ inputs.retry-wait-seconds }}
+      run: |
+        echo "::warning::Docker build-push attempt 1 failed; retrying in ${RETRY_WAIT_SECONDS}s…"
+        sleep "${RETRY_WAIT_SECONDS}"
+
+    - name: Build and push (attempt 2)
+      id: try2
+      if: steps.try1.outcome == 'failure'
+      uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+      with:
+        context: ${{ inputs.context }}
+        file: ${{ inputs.file }}
+        platforms: ${{ inputs.platforms }}
+        push: ${{ inputs.push == 'true' }}
+        tags: ${{ inputs.tags }}
+        labels: ${{ inputs.labels }}
+        cache-from: ${{ inputs.cache-from }}
+        cache-to: ${{ inputs.cache-to }}
+        provenance: mode=max
+        sbom: true
+
+    - name: Resolve image digest
+      id: resolve
+      if: always()
+      shell: bash
+      run: |
+        set -euo pipefail
+        if [ "${{ steps.try1.outcome }}" = "success" ]; then
+          echo "digest=${{ steps.try1.outputs.digest }}" >> "$GITHUB_OUTPUT"
+          exit 0
+        fi
+        if [ "${{ steps.try2.outcome }}" = "success" ]; then
+          echo "::notice::docker-build-push retry succeeded (attempt 2); investigate if this recurs across runs."
+          echo "digest=${{ steps.try2.outputs.digest }}" >> "$GITHUB_OUTPUT"
+          exit 0
+        fi
+        echo "::error::Docker build and push failed after two attempts (registry/cache flake or real build error)."
+        exit 1

.github/actions/setup-gitnexus-web/action.yml

@@ -1,12 +1,15 @@
 name: Setup GitNexus Web
-description: Setup Node.js 20, build gitnexus-shared, install web dependencies
+description: Setup Node.js 20.19+ (vite 7 floor), build gitnexus-shared, install web dependencies
 
 runs:
   using: composite
   steps:
     - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
       with:
-        node-version: 20
+        # Vite 7 requires Node ^20.19.0 || >=22.12.0 (require(esm) support).
+        # Pin explicitly so we don't depend on the floating "20" alias resolving
+        # to a high enough patch version on every runner image.
+        node-version: '20.19.0'
         cache: npm
         cache-dependency-path: gitnexus-web/package-lock.json
 

.github/scripts/check-tree-sitter-upgrade-readiness.py

@@ -36,7 +36,6 @@ import urllib.request
 
 REPO_ROOT = pathlib.Path(__file__).resolve().parents[2]
 GITNEXUS_DIR = REPO_ROOT / "gitnexus"
-VENDOR_PROTO_DIR = GITNEXUS_DIR / "vendor" / "tree-sitter-proto"
 
 # ── Upgrade target ──────────────────────────────────────────────────────
 # The runtime version we want to upgrade TO. Update this when the goal
@@ -73,18 +72,37 @@ GRAMMARS: dict[str, tuple[str, str, str]] = {
     "tree-sitter-rust":       ("tree-sitter/tree-sitter-rust",       "master", "src/parser.c"),
     "tree-sitter-swift":      ("alex-pinkus/tree-sitter-swift",      "main",   "src/parser.c"),
     "tree-sitter-typescript": ("tree-sitter/tree-sitter-typescript", "master",  "typescript/src/parser.c"),
+    # Vendored parsers — kept here so the upstream coords for drift
+    # detection are co-located with every other grammar's coords.
+    "tree-sitter-proto":      ("coder3101/tree-sitter-proto",        "main",   "src/parser.c"),
 }
 
-UPSTREAM_PROTO_OWNER = "coder3101"
-UPSTREAM_PROTO_REPO = "tree-sitter-proto"
-UPSTREAM_PROTO_BRANCH = "main"
+# Grammars deliberately held below npm latest. The readiness report surfaces
+# these so reviewers can tell intentional pins apart from drift, and so the
+# context for each pin (which issue motivated it) is visible at a glance.
+# Add an entry whenever you pin a grammar below npm latest.
+INTENTIONAL_PINS: dict[str, str] = {
+    "tree-sitter-c": (
+        "#1242 — last release built against the tree-sitter@0.21 ABI; "
+        "tree-sitter-c@0.23.x prebuilds segfault on Windows under tree-sitter@0.21.1"
+    ),
+    "tree-sitter-cpp": (
+        "#1242 — last 0.23.x release before tree-sitter-cpp added a runtime "
+        "dep on the broken-ABI tree-sitter-c@^0.23.1; pinning here removes "
+        "the need for a transitive override"
+    ),
+}
 
 
 # ── Helpers ─────────────────────────────────────────────────────────────
 
+def _load_package_json() -> dict:
+    return json.loads((GITNEXUS_DIR / "package.json").read_text())
+
+
 def read_current_runtime() -> str:
     """Return the tree-sitter runtime version pinned in package.json (e.g. '0.21')."""
-    pkg = json.loads((GITNEXUS_DIR / "package.json").read_text())
+    pkg = _load_package_json()
     raw = pkg["dependencies"]["tree-sitter"]
     match = re.search(r"(\d+)\.(\d+)", raw)
     if not match:
@@ -92,6 +110,22 @@ def read_current_runtime() -> str:
     return f"{match.group(1)}.{match.group(2)}"
 
 
+def read_pinned_grammar_versions() -> dict[str, str]:
+    """Return the grammar version range pinned in gitnexus/package.json.
+
+    Looks at both runtime and optional dependencies. Returns the raw range
+    string (e.g. '0.21.4', '^0.23.0', 'file:./vendor/...') so the report can
+    expose how flexible each pin is.
+    """
+    pkg = _load_package_json()
+    pinned: dict[str, str] = {}
+    for section in ("dependencies", "optionalDependencies"):
+        for name, spec in (pkg.get(section) or {}).items():
+            if name.startswith("tree-sitter-"):
+                pinned[name] = spec
+    return pinned
+
+
 def npm_view_json(pkg: str) -> dict | None:
     """Fetch package metadata from the npm registry via HTTPS.
 
@@ -185,8 +219,178 @@ def md_h(text: str, level: int = 2) -> str:
     return f"{'#' * level} {text}\n"
 
 
+def _first_sentence(text: str) -> str:
+    """Return the leading sentence of a free-form rationale string.
+
+    Vendor package.json `_vendoredBy` fields often look like
+    "<reason>. <install-script breadcrumb>. Do NOT <warning>." — the
+    first sentence is what reviewers actually want to read; the rest is
+    noise in this context. Match a sentence-ending '.' followed by
+    whitespace; fall back to the whole string if nothing matches.
+    """
+    text = text.strip()
+    match = re.search(r"\.\s+[A-Z]", text)
+    return text[: match.start() + 1] if match else text
+
+
+def range_includes(spec: str | None, version: str) -> bool:
+    """Return True if pinned-range `spec` accepts the concrete `version`.
+
+    Handles the spec shapes we actually use in package.json:
+      - exact pins  ('0.21.4')
+      - caret / tilde ranges ('^0.23.0', '~0.23.5')
+      - non-registry pins ('file:./vendor/...', 'git+...') — always False,
+        because there's no meaningful "behind npm latest" comparison.
+    """
+    if not spec or spec == "—":
+        return False
+    if spec.startswith(("file:", "git", "http")):
+        return False
+    if spec.startswith(("^", "~")):
+        return satisfies_target(spec, version)
+    return spec.strip() == version.strip()
+
+
+def is_vendored_pin(spec: str | None) -> bool:
+    return bool(spec) and spec.startswith(("file:", "git", "http"))
+
+
+def vendored_drift_summary(
+    name: str, upstream_repo: str, upstream_branch: str, parser_path: str
+) -> dict:
+    """Inspect a vendored grammar under gitnexus/vendor/<name>.
+
+    Returns the vendored package.json's ``version`` and ``_vendoredBy``
+    fields (which carry the human rationale for vendoring), the vendored
+    parser's ABI, and a comparison against upstream main. We deliberately
+    rely on ``_vendoredBy`` rather than a parallel registry in this
+    script: the rationale belongs next to the vendored sources, not in
+    a daily-running CI script.
+    """
+    vendor_dir = GITNEXUS_DIR / "vendor" / name
+    pkg: dict = {}
+    pkg_path = vendor_dir / "package.json"
+    if pkg_path.is_file():
+        try:
+            pkg = json.loads(pkg_path.read_text(encoding="utf-8", errors="ignore"))
+        except json.JSONDecodeError:
+            pass
+
+    vendored_parser = vendor_dir / parser_path
+    if not vendored_parser.is_file():
+        vendored_parser = vendor_dir / "src" / "parser.c"
+    vendored_abi = extract_language_version(vendored_parser)
+
+    upstream_url = (
+        f"https://raw.githubusercontent.com/{upstream_repo}/"
+        f"{upstream_branch}/{parser_path}"
+    )
+    upstream_text = fetch_text(upstream_url)
+    upstream_abi = extract_abi_from_text(upstream_text) if upstream_text else None
+
+    sha_text = fetch_text(
+        f"https://api.github.com/repos/{upstream_repo}/commits/{upstream_branch}"
+    )
+    upstream_sha = "?"
+    if sha_text:
+        try:
+            upstream_sha = json.loads(sha_text).get("sha", "?")[:12]
+        except json.JSONDecodeError:
+            pass
+
+    local_text = (
+        vendored_parser.read_text(encoding="utf-8", errors="ignore")
+        if vendored_parser.is_file()
+        else ""
+    )
+    in_sync = bool(
+        upstream_text
+        and local_text.replace("\r\n", "\n") == upstream_text.replace("\r\n", "\n")
+    )
+
+    return {
+        "name": name,
+        "vendored_version": pkg.get("version", "?"),
+        "vendored_by": pkg.get("_vendoredBy"),
+        "vendored_abi": vendored_abi,
+        "upstream_repo": upstream_repo,
+        "upstream_branch": upstream_branch,
+        "upstream_sha": upstream_sha,
+        "upstream_abi": upstream_abi,
+        "in_sync": in_sync,
+    }
+
+
 # ── Main ────────────────────────────────────────────────────────────────
 
+
+def _classify_grammar(
+    *,
+    name: str,
+    pinned_spec: str | None,
+    npm_version: str,
+    peer_range: str | None,
+    fetch_failed: bool,
+    target_compat: bool,
+    current_compat: bool,
+    upstream_progress: str | None,
+) -> dict:
+    """Decide a single primary disposition + a separate bump-now hint.
+
+    Buckets are mutually exclusive and ordered by what a reviewer should
+    look at first:
+      - fetch_failed   : npm registry fetch failed (treat as blocker, but
+                          surface separately so reviewers don't confuse it
+                          with an upstream block)
+      - intentional    : pinned in INTENTIONAL_PINS — explicit choice
+      - ready          : npm-latest peer dep already accepts the target
+                          runtime; nothing to do
+      - waiting        : main has a fix (ABI 15 or relaxed peer) but no
+                          published npm release yet
+      - blocked        : peer dep too tight on both npm and main
+
+    Independently of bucket, `bump_now` reports whether reviewers can
+    move the pin forward today without touching the runtime — we only
+    suggest it when npm-latest's peer dep also accepts our *current*
+    runtime, otherwise the bump would break `npm install`.
+    """
+    is_vendored = is_vendored_pin(pinned_spec)
+    behind_latest = (
+        not is_vendored
+        and npm_version != "?"
+        and not range_includes(pinned_spec, npm_version)
+    )
+    # Intentional pins must never appear as actionable bumps — by definition
+    # we're holding them back on purpose. The pin can only be lifted by
+    # editing INTENTIONAL_PINS and package.json together.
+    bump_now = behind_latest and current_compat and name not in INTENTIONAL_PINS
+
+    if fetch_failed:
+        bucket = "fetch_failed"
+    elif name in INTENTIONAL_PINS:
+        bucket = "intentional"
+    elif target_compat:
+        bucket = "ready"
+    elif upstream_progress:
+        bucket = "waiting"
+    else:
+        bucket = "blocked"
+
+    return {
+        "name": name,
+        "pinned_spec": pinned_spec or "—",
+        "npm_version": npm_version,
+        "peer_range": peer_range,
+        "target_compat": target_compat,
+        "current_compat": current_compat,
+        "upstream_progress": upstream_progress,
+        "behind_latest": behind_latest,
+        "bump_now": bump_now,
+        "bucket": bucket,
+        "is_vendored": is_vendored,
+    }
+
+
 def main() -> int:
     blockers: dict[str, str] = {}
     lines: list[str] = []
@@ -196,20 +400,68 @@ def main() -> int:
     current_runtime = read_current_runtime()
     current_abi_range = RUNTIME_ABI_RANGES.get(current_runtime, (0, 0))
     target_abi_range = RUNTIME_ABI_RANGES.get(TARGET_RUNTIME_MAJOR_MINOR, (0, 0))
+    pinned_versions = read_pinned_grammar_versions()
 
-    lines.append(f"- Current runtime: `tree-sitter@{current_runtime}.x` (ABI {current_abi_range[0]}..{current_abi_range[1]})")
-    lines.append(f"- Target runtime: `tree-sitter@{TARGET_RUNTIME}` (ABI {target_abi_range[0]}..{target_abi_range[1]})")
+    lines.append(
+        f"`tree-sitter@{current_runtime}.x` (ABI {current_abi_range[0]}–{current_abi_range[1]}) "
+        f"→ target `tree-sitter@{TARGET_RUNTIME}` "
+        f"(ABI {target_abi_range[0]}–{target_abi_range[1]})."
+    )
     lines.append("")
 
-    # ── Grammar peer-dep compatibility ───────────────────────────────
-    lines.append(md_h("Grammar compatibility", 2))
-    lines.append("| Grammar | npm latest | Peer dep | Satisfies 0.25? | ABI | Upstream ABI | Status |")
-    lines.append("|---|---|---|---|---|---|---|")
+    # First pass: gather raw data + classification per grammar. We render
+    # the human-friendly buckets first, then the raw matrix in a <details>
+    # block at the end. Status text in the matrix is preserved verbatim
+    # so the workflow's row-diff change-detection keeps working.
+    grammar_rows: list[dict] = []
+    raw_matrix: list[str] = [
+        "| Grammar | Pinned | npm latest | Peer dep | Satisfies 0.25? | ABI | Upstream ABI | Status |",
+        "|---|---|---|---|---|---|---|---|",
+    ]
 
-    ready_count = 0
-    total_count = len(GRAMMARS)
+    vendored_grammars: list[dict] = []
 
     for name, (upstream_repo, upstream_branch, parser_path) in sorted(GRAMMARS.items()):
+        pinned_spec = pinned_versions.get(name, "—")
+
+        # Vendored grammars don't have an "npm latest" we install from —
+        # we ship our own copy under gitnexus/vendor/<name>. Treat them
+        # as a separate kind of artefact: their readiness for the runtime
+        # upgrade depends on the vendored ABI being in the target range,
+        # not on a peer-dep negotiation.
+        if is_vendored_pin(pinned_spec):
+            v = vendored_drift_summary(name, upstream_repo, upstream_branch, parser_path)
+            v["pinned_spec"] = pinned_spec
+            # Three-state classification: in-range, out-of-range, or
+            # not-introspectable (e.g. tree-sitter-swift ships only
+            # prebuilt .node binaries, no parser.c — assume compatible).
+            if v["vendored_abi"] is None:
+                v["target_compat"] = True
+                v["abi_state"] = "prebuilt"
+                status = "Vendored (prebuilt — ABI not introspectable)"
+            elif target_abi_range[0] <= v["vendored_abi"] <= target_abi_range[1]:
+                v["target_compat"] = True
+                v["abi_state"] = "in_range"
+                status = "Vendored (ABI in target range)"
+            else:
+                v["target_compat"] = False
+                v["abi_state"] = "out_of_range"
+                status = "Vendored (ABI out of range)"
+                blockers[name] = (
+                    f"vendored `{name}`: ABI {v['vendored_abi']} outside target range "
+                    f"{target_abi_range[0]}..{target_abi_range[1]}"
+                )
+            # Keep vendored grammars in the raw matrix so the workflow's
+            # row-diff change-detection picks up status transitions on
+            # them too. npm-only columns get sentinels.
+            raw_matrix.append(
+                f"| `{name}` | {pinned_spec} | (vendored) | (vendored) | "
+                f"{'Yes' if v['target_compat'] else '**No**'} | "
+                f"{v['vendored_abi'] or '?'} | {v['upstream_abi'] or '?'} | {status} |"
+            )
+            vendored_grammars.append(v)
+            continue
+
         # Fetch latest npm metadata.
         info = npm_view_json(name)
         fetch_failed = info is None
@@ -226,12 +478,14 @@ def main() -> int:
 
         if fetch_failed:
             peer_display = "? (fetch failed)"
-            compatible = False
+            target_compat = False
+            current_compat = False
         else:
             peer_display = peer_range or "none"
             if peer_range and not peer_optional:
                 peer_display += " (required)"
-            compatible = satisfies_target(peer_range, TARGET_RUNTIME)
+            target_compat = satisfies_target(peer_range, TARGET_RUNTIME)
+            current_compat = satisfies_target(peer_range, f"{current_runtime}.0")
 
         # Check installed ABI using the same parser_path from GRAMMARS.
         installed_parser = GITNEXUS_DIR / "node_modules" / name / parser_path
@@ -250,22 +504,40 @@ def main() -> int:
         upstream_abi = extract_abi_from_text(upstream_text) if upstream_text else None
         upstream_abi_display = str(upstream_abi) if upstream_abi else "?"
 
-        # Determine status.
+        # Status text + upstream-progress detection. The Status column
+        # values are preserved as-is to keep the workflow's row-diff
+        # change-detection working on the raw matrix below.
+        upstream_progress: str | None = None
         if fetch_failed:
             status = "Unknown (fetch failed)"
             blockers[name] = f"`{name}`: npm registry fetch failed — could not verify peer dep"
-        elif compatible:
+        elif name in INTENTIONAL_PINS:
+            # An intentional pin is, by definition, a held-back grammar:
+            # whatever npm-latest's peer dep says, our shipped version is
+            # the one whose ABI/peer must accept the target runtime, and
+            # the pin entry exists precisely because it does not. Treat
+            # it as a blocker until the pin is lifted (entry removed from
+            # INTENTIONAL_PINS), at which point this grammar falls back
+            # to standard classification on the next run.
+            status = "Intentionally pinned"
+            blockers[name] = (
+                f"`{name}` intentionally pinned at `{pinned_spec}` "
+                f"({INTENTIONAL_PINS[name]}) — pin must be lifted "
+                f"before the {TARGET_RUNTIME} runtime upgrade"
+            )
+        elif target_compat:
             status = "Ready"
-            ready_count += 1
         elif upstream_abi and upstream_abi >= 15:
             status = "Unreleased (ABI 15 on main)"
+            upstream_progress = f"ABI 15 on `{upstream_repo}@{upstream_branch}` not yet published"
             blockers[name] = f"`{name}`: ABI 15 on `{upstream_repo}` main but not published to npm"
         else:
             status = "Blocking"
             blockers[name] = f"`{name}@{npm_version}`: peer `{peer_display}` incompatible with 0.25"
 
-        # Also check upstream package.json for relaxed peer dep.
-        if not compatible and not fetch_failed:
+        # Also check upstream package.json for relaxed peer dep — beats
+        # the ABI-15 hint when both are true.
+        if not target_compat and not fetch_failed:
             upstream_pkg_url = (
                 f"https://raw.githubusercontent.com/{upstream_repo}/"
                 f"{upstream_branch}/package.json"
@@ -277,82 +549,250 @@ def main() -> int:
                     upstream_peer = (upstream_pkg.get("peerDependencies") or {}).get("tree-sitter")
                     if upstream_peer and satisfies_target(upstream_peer, TARGET_RUNTIME):
                         status = "Unreleased (peer relaxed on main)"
+                        upstream_progress = (
+                            f"peer relaxed to `{upstream_peer}` on "
+                            f"`{upstream_repo}@{upstream_branch}` not yet published"
+                        )
                         blockers[name] = f"`{name}`: peer dep relaxed on `{upstream_repo}` main but not published to npm"
                 except json.JSONDecodeError:
                     pass
 
-        compat_icon = "Yes" if compatible else "**No**"
-        lines.append(
-            f"| `{name}` | {npm_version} | {peer_display} | {compat_icon} | {abi_display} | {upstream_abi_display} | {status} |"
+        pinned_spec = pinned_versions.get(name, "—")
+        compat_icon = "Yes" if target_compat else "**No**"
+        raw_matrix.append(
+            f"| `{name}` | {pinned_spec} | {npm_version} | {peer_display} | "
+            f"{compat_icon} | {abi_display} | {upstream_abi_display} | {status} |"
         )
 
-    lines.append("")
-    lines.append(f"**{ready_count}/{total_count}** grammars ready for `tree-sitter@{TARGET_RUNTIME}`.")
-    lines.append("")
+        grammar_rows.append(_classify_grammar(
+            name=name,
+            pinned_spec=pinned_spec,
+            npm_version=npm_version,
+            peer_range=peer_range,
+            fetch_failed=fetch_failed,
+            target_compat=target_compat,
+            current_compat=current_compat,
+            upstream_progress=upstream_progress,
+        ))
 
-    # ── Vendored proto drift ─────────────────────────────────────────
-    lines.append(md_h("Vendored tree-sitter-proto", 2))
-    vendored_abi = extract_language_version(VENDOR_PROTO_DIR / "src" / "parser.c")
+    # ── Bucketize ────────────────────────────────────────────────────
+    by_bucket: dict[str, list[dict]] = {
+        k: [] for k in ("ready", "intentional", "waiting", "blocked", "fetch_failed")
+    }
+    for row in grammar_rows:
+        by_bucket[row["bucket"]].append(row)
+    bump_now = [r for r in grammar_rows if r["bump_now"]]
+    ready_count = len(by_bucket["ready"])
 
-    upstream_proto_url = (
-        f"https://raw.githubusercontent.com/{UPSTREAM_PROTO_OWNER}/"
-        f"{UPSTREAM_PROTO_REPO}/{UPSTREAM_PROTO_BRANCH}/src/parser.c"
-    )
-    upstream_proto_text = fetch_text(upstream_proto_url)
-    upstream_proto_abi = extract_abi_from_text(upstream_proto_text) if upstream_proto_text else None
+    # ── TL;DR ────────────────────────────────────────────────────────
+    npm_count = len(grammar_rows)
+    vendored_count = len(vendored_grammars)
+    vendored_ready = sum(1 for v in vendored_grammars if v["target_compat"])
 
-    sha_url = (
-        f"https://api.github.com/repos/{UPSTREAM_PROTO_OWNER}/"
-        f"{UPSTREAM_PROTO_REPO}/commits/{UPSTREAM_PROTO_BRANCH}"
-    )
-    sha_text = fetch_text(sha_url)
-    upstream_sha = "?"
-    if sha_text:
-        try:
-            upstream_sha = json.loads(sha_text).get("sha", "?")[:12]
-        except json.JSONDecodeError:
-            pass
-
-    local_proto_path = VENDOR_PROTO_DIR / "src" / "parser.c"
-    local_proto_text = local_proto_path.read_text(encoding="utf-8", errors="ignore") if local_proto_path.is_file() else ""
-    in_sync = bool(
-        upstream_proto_text
-        and local_proto_text.replace("\r\n", "\n")
-        == upstream_proto_text.replace("\r\n", "\n")
-    )
-
-    lines.append(f"- Upstream: `{UPSTREAM_PROTO_OWNER}/{UPSTREAM_PROTO_REPO}@{UPSTREAM_PROTO_BRANCH}` (HEAD `{upstream_sha}`)")
-    lines.append(f"- Upstream ABI: **{upstream_proto_abi}**")
-    lines.append(f"- Vendored ABI: **{vendored_abi}**")
-    lines.append(f"- In sync: {'yes' if in_sync else 'no — upstream has diverged'}")
-
-    if upstream_proto_abi and vendored_abi and upstream_proto_abi > vendored_abi:
-        can_upgrade = upstream_proto_abi <= target_abi_range[1]
-        lines.append(f"- Upstream ABI {upstream_proto_abi} {'is' if can_upgrade else 'is NOT'} within target runtime range ({target_abi_range[0]}..{target_abi_range[1]})")
-        if can_upgrade:
-            lines.append(f"- **Action:** after upgrading to tree-sitter@{TARGET_RUNTIME}, regenerate vendored parser.c from upstream `{upstream_sha}`")
-        else:
-            lines.append(f"- **Action:** wait for runtime upgrade beyond {TARGET_RUNTIME} that supports ABI {upstream_proto_abi}")
-            blockers["vendored-proto-abi"] = f"vendored tree-sitter-proto: upstream ABI {upstream_proto_abi} outside target range"
-    elif not in_sync:
-        lines.append("- **Action:** review upstream changes; vendored copy may need updating")
-        blockers["vendored-proto-sync"] = "vendored tree-sitter-proto: out of sync with upstream"
-
-    # ── Summary ──────────────────────────────────────────────────────
-    lines.append("")
-    lines.append(md_h("Summary", 2))
-    if blockers:
-        lines.append(f"**{len(blockers)} blocker(s) remaining:**\n")
-        for b in blockers.values():
-            lines.append(f"- {b}")
-        lines.append("")
-        lines.append("Upgrade to `tree-sitter@0.25` is **blocked**.")
+    if not blockers:
+        verdict = "**Ready** — all grammars are 0.25-compatible. The runtime upgrade can proceed."
     else:
-        lines.append("All grammars are compatible. Upgrade to `tree-sitter@0.25` is **ready**.")
+        moved = "no" if not by_bucket["waiting"] else f"yes — {len(by_bucket['waiting'])} grammars have unreleased fixes on main"
+        verdict = (
+            f"**Blocked** — {len(blockers)} grammars are not yet 0.25-compatible. "
+            f"Upstream movement: {moved}."
+        )
+
+    lines.append(md_h("TL;DR", 2))
+    lines.append(verdict)
+    lines.append("")
+    lines.append(f"- {ready_count}/{npm_count} npm-installed grammars already accept tree-sitter@{TARGET_RUNTIME}")
+    if vendored_count:
+        lines.append(
+            f"- {vendored_ready}/{vendored_count} vendored grammars at an ABI within the target runtime range"
+        )
+    lines.append(f"- {len(by_bucket['intentional'])} intentionally pinned (see below)")
+    lines.append(f"- {len(by_bucket['waiting'])} waiting on an upstream npm release")
+    lines.append(f"- {len(by_bucket['blocked'])} blocked on upstream (no fix even on main)")
+    if by_bucket['fetch_failed']:
+        lines.append(f"- {len(by_bucket['fetch_failed'])} could not be checked (npm registry unreachable)")
+    if bump_now:
+        lines.append(
+            f"- **{len(bump_now)} bump candidate(s) you can take TODAY** (npm-latest "
+            f"is newer than the pin AND its peer dep accepts our current runtime)"
+        )
+    lines.append("")
+
+    # ── What you can do today ───────────────────────────────────────
+    if bump_now:
+        lines.append(md_h("What you can do today", 2))
+        lines.append(
+            "These pins lag npm latest and the latest version's peer dep already "
+            "accepts our current `tree-sitter@" + current_runtime + ".x` runtime. "
+            "Bumping is independent of the 0.25 upgrade and should be a quick PR."
+        )
+        lines.append("")
+        for r in sorted(bump_now, key=lambda r: r["name"]):
+            lines.append(
+                f"- `{r['name']}`: `{r['pinned_spec']}` → `{r['npm_version']}` "
+                f"(peer `{r['peer_range'] or 'none'}`)"
+            )
+        lines.append("")
+
+    # ── Per-disposition sections ────────────────────────────────────
+    def _emit_bucket(title: str, body_intro: str, rows: list[dict], render) -> None:
+        if not rows:
+            return
+        lines.append(md_h(f"{title} ({len(rows)})", 3))
+        lines.append(body_intro)
+        lines.append("")
+        for r in sorted(rows, key=lambda r: r["name"]):
+            lines.append(render(r))
+        lines.append("")
+
+    lines.append(md_h("Disposition", 2))
+
+    _emit_bucket(
+        "Ready for 0.25",
+        "These grammars' npm-latest peer dep already accepts the target runtime. No action needed for the upgrade.",
+        by_bucket["ready"],
+        lambda r: (
+            f"- `{r['name']}` — pinned `{r['pinned_spec']}`, npm latest `{r['npm_version']}`"
+            + ("  _(also a bump candidate — see above)_" if r["bump_now"] else "")
+        ),
+    )
+
+    if by_bucket["intentional"]:
+        lines.append(md_h(f"Intentionally pinned ({len(by_bucket['intentional'])})", 3))
+        lines.append(
+            "Deliberately held below npm latest. These are **not** drift — each entry "
+            "lists the issue motivating the pin and the condition for unpinning."
+        )
+        lines.append("")
+        for r in sorted(by_bucket["intentional"], key=lambda r: r["name"]):
+            reason = INTENTIONAL_PINS.get(r["name"], "(no rationale recorded)")
+            lines.append(
+                f"- `{r['name']}` pinned at `{r['pinned_spec']}` "
+                f"(npm latest `{r['npm_version']}`)\n  {reason}"
+            )
+        lines.append("")
+
+    _emit_bucket(
+        "Waiting on upstream npm release",
+        "Fixes are merged on the upstream main branch but not yet published to npm. "
+        "We can move forward as soon as upstream cuts a release.",
+        by_bucket["waiting"],
+        lambda r: (
+            f"- `{r['name']}@{r['npm_version']}` — peer `{r['peer_range'] or 'none'}`. "
+            f"_{r['upstream_progress']}_"
+        ),
+    )
+
+    _emit_bucket(
+        "Blocked on upstream",
+        "Peer dep is too tight on both the latest npm release and on upstream main. "
+        "These need an upstream issue/PR before we can proceed.",
+        by_bucket["blocked"],
+        lambda r: (
+            f"- `{r['name']}@{r['npm_version']}` — peer `{r['peer_range'] or 'none'}`"
+            + (" _(vendored)_" if r["is_vendored"] else "")
+        ),
+    )
+
+    _emit_bucket(
+        "Could not check",
+        "npm registry fetch failed for these grammars. Re-run the workflow to retry.",
+        by_bucket["fetch_failed"],
+        lambda r: f"- `{r['name']}` (pinned `{r['pinned_spec']}`)",
+    )
+
+    # ── Vendored parsers ────────────────────────────────────────────
+    if vendored_grammars:
+        lines.append(md_h(f"Vendored parsers ({len(vendored_grammars)})", 2))
+        lines.append(
+            "These grammars ship from `gitnexus/vendor/` rather than the npm "
+            "registry. Their compatibility is governed by the **vendored "
+            "ABI** (must lie in the target runtime's range), not by a peer-"
+            "dep negotiation. The rationale for each vendored copy lives in "
+            "its own `package.json` `_vendoredBy` field."
+        )
+        lines.append("")
+        for v in sorted(vendored_grammars, key=lambda v: v["name"]):
+            sync_label = (
+                "in sync with upstream" if v["in_sync"] else "diverged from upstream"
+            )
+            if v["abi_state"] == "in_range":
+                abi_label = f"ABI `{v['vendored_abi']}` (in target range)"
+            elif v["abi_state"] == "prebuilt":
+                abi_label = "ABI `prebuilt` (binary-only vendor, source not introspectable)"
+            else:
+                abi_label = (
+                    f"ABI `{v['vendored_abi']}` (**outside** target range "
+                    f"{target_abi_range[0]}..{target_abi_range[1]})"
+                )
+            upstream_abi_str = (
+                f"ABI `{v['upstream_abi']}`" if v["upstream_abi"] else "ABI `?`"
+            )
+            lines.append(
+                f"- **`{v['name']}`** `{v['vendored_version']}` — {abi_label}, "
+                f"upstream `{v['upstream_repo']}@{v['upstream_sha']}` "
+                f"{upstream_abi_str} · {sync_label}"
+            )
+            if v["vendored_by"]:
+                # Show the first sentence — vendor package.json fields tend
+                # to start with the rationale and tail off into install-
+                # script breadcrumbs that aren't useful in this report.
+                rationale = _first_sentence(v["vendored_by"])
+                lines.append(f"  - **Why vendored:** {rationale}")
+            # Action computation: needs regen iff upstream ABI exceeds
+            # vendored AND is still within target range. If upstream ABI
+            # exceeds the target, that's a runtime-side blocker. For
+            # prebuilt-only vendors we can't drive this from source ABI;
+            # the action is a manual upstream-binary refresh, surfaced
+            # via the in-sync flag instead.
+            if v["abi_state"] == "prebuilt":
+                if not v["in_sync"]:
+                    lines.append(
+                        "  - **Action:** check whether upstream has shipped a new "
+                        "prebuilt release; this vendor ships binary-only artefacts."
+                    )
+            elif v["upstream_abi"] and v["vendored_abi"] and v["upstream_abi"] > v["vendored_abi"]:
+                if v["upstream_abi"] <= target_abi_range[1]:
+                    lines.append(
+                        f"  - **Action:** after upgrading to tree-sitter@{TARGET_RUNTIME}, "
+                        f"regenerate `parser.c` from upstream `{v['upstream_sha']}`."
+                    )
+                else:
+                    lines.append(
+                        f"  - **Action:** wait for a runtime supporting ABI "
+                        f"{v['upstream_abi']}; current target ({TARGET_RUNTIME}) only "
+                        f"goes up to ABI {target_abi_range[1]}."
+                    )
+                    blockers[f"vendored-{v['name']}-abi"] = (
+                        f"vendored {v['name']}: upstream ABI {v['upstream_abi']} outside target range"
+                    )
+            elif not v["in_sync"]:
+                lines.append(
+                    "  - **Action:** review upstream changes; vendored copy may "
+                    "need a refresh (no ABI bump required)."
+                )
+        lines.append("")
+
+    # ── Raw matrix (for completeness + workflow row-diff) ────────────
+    lines.append(md_h("Full grammar matrix", 2))
+    lines.append(
+        "<details><summary>Click to expand the raw per-grammar table "
+        "(used by the workflow's change-detection bot).</summary>\n"
+    )
+    lines.extend(raw_matrix)
+    lines.append("\n</details>")
+    lines.append("")
 
     print("\n".join(lines))
     return 1 if blockers else 0
 
 
 if __name__ == "__main__":
+    # Force UTF-8 output: the report contains em-dashes and arrows that
+    # Windows' default cp1252 codepage can't encode, while Linux runners
+    # default to UTF-8 anyway.
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")  # type: ignore[attr-defined]
+    except Exception:
+        pass
     sys.exit(main())

.github/scripts/check-workflow-concurrency.py

@@ -11,10 +11,14 @@ Rules:
      `concurrency:` block.
   2. Reusable workflows (on: workflow_call ONLY) do NOT declare one.
   3. The `concurrency.group` expression MUST reference either
-     `${{ github.workflow }}` or a literal `CI-` prefix (the documented
-     ci.yml reusable-workflow-safe exception). This is checked by substring
-     containment rather than prefix match because ci.yml's group is a
-     conditional expression that resolves to a `CI-…` literal at runtime.
+     `${{ github.workflow }}` or one of the approved hardcoded literal prefixes
+     for workflows that are simultaneously entry-points AND reusable (on: push/
+     workflow_call). Two such exceptions are currently approved:
+       - `CI-` for ci.yml (the original canonical form)
+       - `docker-build-push-` for docker.yml
+     This is checked by substring containment rather than prefix match because
+     the group value is a conditional expression that resolves to a `CI-…` or
+     `docker-build-push-…` literal at runtime.
 
 We deliberately do not use a YAML library — keeps the script dependency-free
 on any vanilla runner. `on:` block parsing is line-based and handles both the
@@ -28,7 +32,7 @@ import re
 import sys
 
 
-REQUIRED_TOKENS = ("${{ github.workflow }}", "CI-")
+REQUIRED_TOKENS = ("${{ github.workflow }}", "CI-", "docker-build-push-")
 
 
 def is_reusable(lines: list[str]) -> bool:
@@ -150,8 +154,10 @@ def check(workflows_dir: pathlib.Path) -> int:
         if not any(token in group for token in REQUIRED_TOKENS):
             print(
                 f"::error file={path}::concurrency.group `{group}` must "
-                f"reference one of {REQUIRED_TOKENS}. See CONTRIBUTING.md -> "
-                "GitHub Actions — Concurrency Convention."
+                f"reference one of {REQUIRED_TOKENS} (use ${{{{ github.workflow }}}} "
+                "for normal entry-point workflows; use an approved literal prefix "
+                "only for workflows that are both entry-points AND reusable — "
+                "see CONTRIBUTING.md -> GitHub Actions — Concurrency Convention)."
             )
             fail = 1
 

.github/workflows/ci-e2e.yml

@@ -28,6 +28,9 @@ jobs:
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
+      - name: Configure e2e GitNexus home
+        run: echo "GITNEXUS_HOME=${RUNNER_TEMP}/gitnexus-home" >> "$GITHUB_ENV"
+
       - uses: ./.github/actions/setup-gitnexus-web
 
       - name: Install Playwright browsers
@@ -44,9 +47,14 @@ jobs:
 
       - name: Analyze repository (index for backend)
         run: |
-          node gitnexus/dist/cli/index.js analyze || true
-          if [ ! -d ".gitnexus" ]; then
-            echo "::error::No .gitnexus index created"
+          E2E_REPO="${RUNNER_TEMP}/gitnexus-e2e-repo"
+          rm -rf "${E2E_REPO}"
+          mkdir -p "${E2E_REPO}"
+          cp -R gitnexus/test/fixtures/mini-repo/src "${E2E_REPO}/src"
+          printf '%s\n' '{"name":"e2e-mini-repo","version":"0.0.0","private":true}' > "${E2E_REPO}/package.json"
+          node gitnexus/dist/cli/index.js analyze "${E2E_REPO}" --skip-git --skip-agents-md --name e2e-mini-repo
+          if [ ! -d "${E2E_REPO}/.gitnexus" ]; then
+            echo "::error::No fixture .gitnexus index created"
             exit 1
           fi
 

.github/workflows/ci-quality.yml

@@ -9,7 +9,7 @@ jobs:
     timeout-minutes: 5
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version: 20
           cache: npm
@@ -22,7 +22,7 @@ jobs:
     timeout-minutes: 10
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version: 20
           cache: npm

.github/workflows/ci-scope-parity.yml

@@ -0,0 +1,110 @@
+name: Scope Resolution Parity
+
+# Reusable workflow — called from ci.yml. Does NOT declare concurrency;
+# it inherits the caller's concurrency group per the convention documented
+# in CONTRIBUTING.md → "GitHub Actions — Concurrency Convention".
+#
+# ── Purpose (RFC #909 Ring 3, §6.4 "Observability gates") ──────────────
+# For every language in `MIGRATED_LANGUAGES` (exported from
+# `gitnexus/src/core/ingestion/registry-primary-flag.ts`), run the
+# resolver integration test at `test/integration/resolvers/<slug>.test.ts`
+# TWICE on every PR:
+#
+#   1. `REGISTRY_PRIMARY_<LANG>=0` — legacy DAG path (guarantees we haven't
+#      broken the old path while migrating). Known legacy gaps may be skipped
+#      through the resolver test helper's expected-failure list.
+#   2. `REGISTRY_PRIMARY_<LANG>=1` — registry-primary path (guarantees the
+#      new path carries the same behavior — the parity gate).
+#
+# BOTH must pass. The source of truth is the TypeScript constant — adding
+# a language to that `Set` is the ONLY contributor action; CI auto-
+# discovers it, runs parity, and the language's default production path
+# flips to registry-primary in the same change.
+#
+# When the set is empty (e.g. mid-Ring-3 for every language), the parity
+# matrix is skipped and the workflow reports success — no-op until a
+# language is explicitly claimed migrated.
+
+on:
+  workflow_call:
+
+jobs:
+  discover:
+    name: Discover migrated languages
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      languages: ${{ steps.read.outputs.languages }}
+      has-any: ${{ steps.read.outputs.has-any }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: ./.github/actions/setup-gitnexus
+
+      - name: Extract MIGRATED_LANGUAGES from registry-primary-flag.ts
+        id: read
+        shell: bash
+        working-directory: gitnexus
+        run: |
+          set -euo pipefail
+          # `tsx` evaluates the TS source directly (no build step), imports
+          # the exported `Set`, and emits a GH-Actions-friendly JSON matrix.
+          LANGS=$(npx tsx scripts/ci-list-migrated-languages.ts)
+          COUNT=$(printf '%s' "$LANGS" | jq 'length')
+          HAS_ANY="false"
+          if [[ "$COUNT" -gt 0 ]]; then HAS_ANY="true"; fi
+          echo "languages=$LANGS" >> "$GITHUB_OUTPUT"
+          echo "has-any=$HAS_ANY" >> "$GITHUB_OUTPUT"
+          echo "Discovered $COUNT migrated language(s): $LANGS"
+          echo "Parity matrix will run: $HAS_ANY"
+
+  parity:
+    name: ${{ matrix.lang.slug }} parity
+    needs: discover
+    if: needs.discover.outputs.has-any == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      # One language failing must not abort the others — we want the full
+      # parity matrix result on a single CI run so a reviewer sees every
+      # regression at once rather than one-at-a-time.
+      fail-fast: false
+      matrix:
+        lang: ${{ fromJSON(needs.discover.outputs.languages) }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: ./.github/actions/setup-gitnexus
+        with:
+          build: 'true'
+
+      - name: Verify resolver test file exists
+        shell: bash
+        working-directory: gitnexus
+        run: |
+          set -euo pipefail
+          TEST_FILE="test/integration/resolvers/${{ matrix.lang.slug }}.test.ts"
+          if [[ ! -f "$TEST_FILE" ]]; then
+            echo "::error title=Missing resolver test::\
+          Expected $TEST_FILE for '${{ matrix.lang.slug }}' (listed in \
+          MIGRATED_LANGUAGES). Either fix the slug or add the test file \
+          before listing this language as migrated."
+            exit 1
+          fi
+
+      - name: Resolver tests — legacy DAG (REGISTRY_PRIMARY_${{ matrix.lang.envvar }}=0)
+        shell: bash
+        working-directory: gitnexus
+        env:
+          FLAG_NAME: REGISTRY_PRIMARY_${{ matrix.lang.envvar }}
+        # Explicitly force the flag to `0` even though it also defaults to
+        # `MIGRATED_LANGUAGES.has(lang)` — once a language is in the set,
+        # the default flips to registry-primary, so an unset env var would
+        # silently re-run the same path as step #2. `env FOO=0 cmd` spawns
+        # `cmd` with the override scoped to just this invocation.
+        run: env "$FLAG_NAME=0" npx vitest run "test/integration/resolvers/${{ matrix.lang.slug }}.test.ts"
+
+      - name: Resolver tests — registry-primary (REGISTRY_PRIMARY_${{ matrix.lang.envvar }}=1)
+        shell: bash
+        working-directory: gitnexus
+        env:
+          FLAG_NAME: REGISTRY_PRIMARY_${{ matrix.lang.envvar }}
+        run: env "$FLAG_NAME=1" npx vitest run "test/integration/resolvers/${{ matrix.lang.slug }}.test.ts"

.github/workflows/ci.yml

@@ -1,9 +1,6 @@
 name: CI
 
 on:
-  push:
-    branches: [main]
-    paths-ignore: ['**.md', 'docs/**', 'LICENSE']
   pull_request:
     branches: [main]
     paths-ignore: ['**.md', 'docs/**', 'LICENSE']
@@ -15,13 +12,12 @@ on:
 # called-workflow context `github.workflow` evaluation is ambiguous across GitHub
 # Actions versions, and a prefix that could resolve to the caller's name would
 # share a concurrency group with the caller → deadlock. A literal prefix is
-# immune. Direct `push`/`pull_request` invocations use `CI-<ref>`; invocations
-# from a reusable-workflow caller fall into a per-run-unique group that never
-# serializes with the caller.
-# cancel-in-progress is event-aware: cancel superseded PR runs, queue every other
-# event (push to main, workflow_call from publish.yml, etc.).
+# immune. Direct `pull_request` invocations use `CI-<ref>`; invocations from a
+# reusable-workflow caller fall into a per-run-unique group that never serializes
+# with the caller. `push` to main is handled by release-candidate.yml, which
+# calls this workflow once before publishing.
 concurrency:
-  group: ${{ (github.event_name == 'pull_request' || github.event_name == 'push') && format('CI-{0}', github.ref) || format('CI-nested-{0}', github.run_id) }}
+  group: ${{ github.event_name == 'pull_request' && format('CI-{0}', github.ref) || format('CI-nested-{0}', github.run_id) }}
   cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
 # ── Reusable workflow orchestration ─────────────────────────────────
@@ -29,6 +25,8 @@ concurrency:
 #   ci-quality.yml       — typecheck (tsc --noEmit)
 #   ci-tests.yml         — unit + integration tests with coverage + cross-platform
 #   ci-e2e.yml           — E2E tests (only when gitnexus-web/ changes)
+#   ci-scope-parity.yml  — RFC #909 Ring 3 parity gate: legacy DAG + registry-primary
+#                          both pass, per migrated language in the JSON registry
 #
 # Shared setup is DRY via .github/actions/setup-gitnexus composite action.
 
@@ -48,6 +46,11 @@ jobs:
     permissions:
       contents: read
 
+  scope-parity:
+    uses: ./.github/workflows/ci-scope-parity.yml
+    permissions:
+      contents: read
+
   # ── Save PR metadata for the reporting workflow ─────────────────
   # The ci-report.yml workflow (triggered by workflow_run) needs the
   # PR number and job results to post a comment.  We save them as an
@@ -56,7 +59,7 @@ jobs:
   save-pr-meta:
     name: Save PR Metadata
     if: always() && github.event_name == 'pull_request'
-    needs: [quality, tests, e2e]
+    needs: [quality, tests, e2e, scope-parity]
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:
@@ -67,12 +70,14 @@ jobs:
           QUALITY: ${{ needs.quality.result }}
           TESTS: ${{ needs.tests.result }}
           E2E: ${{ needs.e2e.result }}
+          SCOPE_PARITY: ${{ needs.scope-parity.result }}
         run: |
           mkdir -p pr-meta
-          echo "$PR_NUMBER"  > pr-meta/pr_number
-          echo "$QUALITY"    > pr-meta/quality_result
-          echo "$TESTS"      > pr-meta/tests_result
-          echo "$E2E"        > pr-meta/e2e_result
+          echo "$PR_NUMBER"      > pr-meta/pr_number
+          echo "$QUALITY"        > pr-meta/quality_result
+          echo "$TESTS"          > pr-meta/tests_result
+          echo "$E2E"            > pr-meta/e2e_result
+          echo "$SCOPE_PARITY"   > pr-meta/scope_parity_result
           # TODO(post-merge): remove backward-compat copies once ci-report.yml
           # on main reads underscore names.
           # Backward-compat: ci-report.yml on main still reads hyphenated
@@ -95,7 +100,7 @@ jobs:
   # Single required check for branch protection.
   ci-status:
     name: CI Gate
-    needs: [quality, tests, e2e]
+    needs: [quality, tests, e2e, scope-parity]
     if: always()
     runs-on: ubuntu-latest
     timeout-minutes: 5
@@ -106,10 +111,12 @@ jobs:
           QUALITY: ${{ needs.quality.result }}
           TESTS: ${{ needs.tests.result }}
           E2E: ${{ needs.e2e.result }}
+          SCOPE_PARITY: ${{ needs.scope-parity.result }}
         run: |
           echo "Quality:        $QUALITY"
           echo "Tests:          $TESTS"
           echo "E2E:            $E2E"
+          echo "Scope parity:   $SCOPE_PARITY"
           if [[ "$QUALITY" != "success" ]] ||
              [[ "$TESTS" != "success" ]]; then
             echo "::error::Quality or test jobs failed"
@@ -119,3 +126,14 @@ jobs:
             echo "::error::E2E job failed"
             exit 1
           fi
+          # scope-parity is a reusable workflow. With an empty migrated-
+          # languages list, its parity matrix is skipped and the outer
+          # workflow still reports `success`. If any entry's legacy-DAG or
+          # registry-primary run fails, the workflow reports `failure`.
+          # Accept only `success`; `skipped` would mean the entire
+          # discover job was skipped too (upstream failure), which should
+          # still block.
+          if [[ "$SCOPE_PARITY" != "success" ]]; then
+            echo "::error::Scope-resolution parity gate failed (RFC #909 Ring 3)"
+            exit 1
+          fi

.github/workflows/claude-code-review.yml

@@ -1,96 +0,0 @@
-name: Claude Code Review
-
-# Uses pull_request_target so the workflow runs as defined on the default branch,
-# which allows access to secrets for posting review comments on fork PRs.
-# SECURITY: The checkout pins the fork's HEAD SHA (not the branch name) to
-# prevent TOCTOU races (force-push between trigger and checkout). The
-# claude-code-action sandboxes execution — it does NOT run arbitrary code
-# from the checked-out source.
-
-on:
-  # Trigger only when explicitly requested:
-  #   - Add the "claude-review" label to a PR, OR
-  #   - Comment "@claude" or "/review" on a PR
-  pull_request_target:
-    types: [labeled]
-  issue_comment:
-    types: [created]
-
-# Concurrency convention: see CONTRIBUTING.md → "GitHub Actions — Concurrency Convention".
-# Serialize per-PR to avoid racing review comments.
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event.issue.number || github.event.pull_request.number }}
-  cancel-in-progress: false
-
-jobs:
-  claude-review:
-    # Run only when:
-    #   1. The "claude-review" label is added to a non-draft PR by a trusted contributor, OR
-    #   2. A trusted contributor comments "@claude" or "/review" on a PR
-    if: |
-      (
-        github.event_name == 'pull_request_target' &&
-        github.event.label.name == 'claude-review' &&
-        github.event.pull_request.draft == false &&
-        (github.event.pull_request.author_association == 'OWNER' ||
-         github.event.pull_request.author_association == 'MEMBER' ||
-         github.event.pull_request.author_association == 'COLLABORATOR')
-      ) ||
-      (
-        github.event_name == 'issue_comment' &&
-        github.event.issue.pull_request &&
-        (contains(github.event.comment.body, '@claude') ||
-         contains(github.event.comment.body, '/review')) &&
-        (github.event.comment.author_association == 'OWNER' ||
-         github.event.comment.author_association == 'MEMBER' ||
-         github.event.comment.author_association == 'COLLABORATOR')
-      )
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
-    permissions:
-      contents: read
-      pull-requests: write
-      issues: read
-      id-token: write
-
-    steps:
-      # For issue_comment triggers, resolve the PR number, head SHA, and fork repo
-      - name: Resolve PR context
-        id: pr
-        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v7
-        with:
-          script: |
-            let pr;
-            if (context.eventName === 'issue_comment') {
-              const resp = await github.rest.pulls.get({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                pull_number: context.payload.issue.number,
-              });
-              pr = resp.data;
-            } else {
-              pr = context.payload.pull_request;
-            }
-            core.setOutput('number', pr.number);
-            core.setOutput('sha', pr.head.sha);
-            core.setOutput('repo', pr.head.repo.full_name);
-            core.setOutput('branch', pr.head.ref);
-
-      - name: Checkout PR head
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-        with:
-          repository: ${{ steps.pr.outputs.repo }}
-          ref: ${{ steps.pr.outputs.sha }}
-          fetch-depth: 1
-
-      - name: Run Claude Code Review
-        id: claude-review
-        uses: anthropics/claude-code-action@9469d113c6afd29550c402740f22d1a97dd1209b # v1
-        with:
-          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          allowed_non_write_users: '*'
-          show_full_output: true
-          plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
-          plugins: 'code-review@claude-code-plugins'
-          prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ steps.pr.outputs.number }}'

.github/workflows/claude.yml

@@ -1,8 +1,17 @@
 name: Claude Code
 
+# Label-triggered code-review requests use pull_request_target so the workflow
+# runs as defined on the default branch, which allows access to secrets for
+# posting review comments on fork PRs. SECURITY: PR checkouts pin the fork's
+# HEAD SHA (not the branch name) to prevent TOCTOU races.
+# The claude-code-action sandboxes execution; it does not run arbitrary code
+# from the checked-out source.
+
 on:
   issue_comment:
     types: [created]
+  pull_request_target:
+    types: [labeled]
   pull_request_review_comment:
     types: [created]
   issues:
@@ -21,7 +30,10 @@ jobs:
     if: |
       (
         github.event_name == 'issue_comment' &&
-        contains(github.event.comment.body, '@claude') &&
+        (
+          contains(github.event.comment.body, '@claude') ||
+          (github.event.issue.pull_request && contains(github.event.comment.body, '/review'))
+        ) &&
         (github.event.comment.author_association == 'OWNER' ||
          github.event.comment.author_association == 'MEMBER' ||
          github.event.comment.author_association == 'COLLABORATOR')
@@ -46,6 +58,14 @@ jobs:
         (github.event.issue.author_association == 'OWNER' ||
          github.event.issue.author_association == 'MEMBER' ||
          github.event.issue.author_association == 'COLLABORATOR')
+      ) ||
+      (
+        github.event_name == 'pull_request_target' &&
+        github.event.label.name == 'claude-review' &&
+        github.event.pull_request.draft == false &&
+        (github.event.pull_request.author_association == 'OWNER' ||
+         github.event.pull_request.author_association == 'MEMBER' ||
+         github.event.pull_request.author_association == 'COLLABORATOR')
       )
     runs-on: ubuntu-latest
     timeout-minutes: 30
@@ -63,33 +83,48 @@ jobs:
         with:
           script: |
             // Determine if this event is PR-related
-            let prNumber = null;
+            let pr = null;
             if (context.eventName === 'issue_comment' && context.payload.issue.pull_request) {
-              prNumber = context.payload.issue.number;
+              const resp = await github.rest.pulls.get({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                pull_number: context.payload.issue.number,
+              });
+              pr = resp.data;
             } else if (context.eventName === 'pull_request_review_comment') {
-              prNumber = context.payload.pull_request.number;
+              pr = context.payload.pull_request;
             } else if (context.eventName === 'pull_request_review') {
-              prNumber = context.payload.pull_request.number;
+              pr = context.payload.pull_request;
+            } else if (context.eventName === 'pull_request_target') {
+              pr = context.payload.pull_request;
             }
 
-            if (!prNumber) {
+            if (!pr) {
               core.setOutput('is_pr', 'false');
               return;
             }
 
-            const resp = await github.rest.pulls.get({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              pull_number: prNumber,
-            });
-            const pr = resp.data;
-
             core.setOutput('is_pr', 'true');
-            core.setOutput('number', String(prNumber));
+            core.setOutput('number', String(pr.number));
             core.setOutput('sha', pr.head.sha);
             core.setOutput('repo', pr.head.repo.full_name);
             core.setOutput('branch', pr.head.ref);
 
+      - name: Resolve Claude mode
+        id: mode
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v7
+        with:
+          script: |
+            const body = (context.payload.comment?.body ?? '').toLowerCase();
+            const isCodeReview =
+              (context.eventName === 'pull_request_target' &&
+                context.payload.label?.name === 'claude-review') ||
+              (context.eventName === 'issue_comment' &&
+                Boolean(context.payload.issue?.pull_request) &&
+                body.includes('/review'));
+
+            core.setOutput('code_review', isCodeReview ? 'true' : 'false');
+
       - name: Checkout repository
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
@@ -98,6 +133,7 @@ jobs:
           fetch-depth: 1
 
       - name: Run Claude Code
+        if: steps.mode.outputs.code_review != 'true'
         id: claude
         uses: anthropics/claude-code-action@9469d113c6afd29550c402740f22d1a97dd1209b # v1
         with:
@@ -109,3 +145,16 @@ jobs:
           # This is an optional setting that allows Claude to read CI results on PRs
           additional_permissions: |
             actions: read
+
+      - name: Run Claude Code Review
+        if: steps.mode.outputs.code_review == 'true'
+        id: claude-review
+        uses: anthropics/claude-code-action@9469d113c6afd29550c402740f22d1a97dd1209b # v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          allowed_non_write_users: '*'
+          show_full_output: true
+          plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
+          plugins: 'code-review@claude-code-plugins'
+          prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ steps.pr.outputs.number }}'

.github/workflows/codeql.yml

@@ -0,0 +1,71 @@
+name: CodeQL
+
+# Static analysis (SAST) for TypeScript/JavaScript and Python sources.
+# Findings upload to the GitHub Security tab as SARIF.
+#
+# Advisory only on first introduction — see docs/plans/2026-05-03-001-feat-automated-security-scans-plan.md.
+# Promote to a required check after baseline triage (operator decision).
+
+on:
+  pull_request:
+    branches: [main]
+    paths-ignore: ['**.md', 'docs/**', 'LICENSE']
+  push:
+    branches: [main]
+  schedule:
+    # Weekly Monday 06:00 UTC — catches advisories newly published against
+    # already-merged code without waiting for the next PR.
+    - cron: '0 6 * * 1'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    permissions:
+      actions: read
+      contents: read
+      # security-events:write is what enables SARIF upload to the Security tab.
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [javascript-typescript, python]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          # Don't leave GITHUB_TOKEN in .git/config for downstream steps to read.
+          persist-credentials: false
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@0daab03d71ff584ef619d027a3fd9146679c5d84 # v3.35.3
+        with:
+          languages: ${{ matrix.language }}
+          queries: security-and-quality
+          # Exclude generated/vendored code; tune after first-run signal.
+          # gitnexus/vendor/ holds tree-sitter-proto sources (regenerated, not authored).
+          # CodeQL path filters use .gitignore-style globs and do NOT support
+          # brace expansion — list each generated parser file separately.
+          config: |
+            paths-ignore:
+              - '**/dist/**'
+              - '**/node_modules/**'
+              - 'gitnexus/vendor/**'
+              - 'gitnexus/src/core/parsing/**/parser.c'
+              - 'gitnexus/src/core/parsing/**/parser.js'
+              # Test fixtures are intentionally synthetic inputs (broken/unused
+              # code, malformed samples) used to exercise the analyzer. CodeQL
+              # findings here are noise, not real bugs.
+              - '**/test/fixtures/**'
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@0daab03d71ff584ef619d027a3fd9146679c5d84 # v3.35.3
+        with:
+          category: '/language:${{ matrix.language }}'

.github/workflows/dependency-review.yml

@@ -0,0 +1,36 @@
+name: Dependency Review
+
+# Blocks PRs that introduce dependencies with high/critical known vulnerabilities.
+# Reads the dependency graph diff between PR head and base.
+#
+# This is a required-check candidate after one week of clean runs
+# (operator decision — see docs/plans/2026-05-03-001-feat-automated-security-scans-plan.md).
+
+on:
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      # pull-requests:write enables the inline summary comment on failure.
+      pull-requests: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Dependency Review
+        uses: actions/dependency-review-action@2031cfc080254a8a887f58cffee85186f0e49e48 # v4.9.0
+        with:
+          fail-on-severity: high
+          comment-summary-in-pr: on-failure

.github/workflows/docker.yml

@@ -4,15 +4,38 @@ on:
   push:
     tags:
       - 'v*'
-  # No workflow_dispatch: publishing is exclusively tag-driven so that every
-  # signed image corresponds 1:1 to a published `gitnexus@X.Y.Z` on npm. A
-  # manual run from a branch ref would fail the version check below anyway.
+  pull_request:
+  # workflow_dispatch is allowed for dry-run testing only. Publishing is still
+  # exclusively tag-driven so that every signed image corresponds 1:1 to a
+  # published `gitnexus@X.Y.Z` on npm. dry_run:true (the default) skips all
+  # push, sign, and attestation steps — the build runs but nothing is published.
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: 'Build only — skip push, signing, and attestations'
+        required: false
+        default: true
+        type: boolean
+  workflow_call:
+    inputs:
+      tag:
+        description: >-
+          The full v-prefixed tag to build (e.g. v1.2.3-rc.1).
+          The tag must already exist in the repo and its tree must contain
+          a gitnexus/package.json whose version matches the tag.
+        required: true
+        type: string
 
 # Concurrency convention: see CONTRIBUTING.md → "GitHub Actions — Concurrency Convention".
 # Tag refs are unique per release, so distinct tags run in parallel.
 # Re-pushes of the same tag serialize. cancel-in-progress: false — never cancel a publish mid-flight.
+# Hardcoded `docker-build-push-` prefix (not `${{ github.workflow }}`) when invoked as a reusable
+# workflow: in called-workflow context `github.workflow` is ambiguous and could resolve to the
+# caller's name, sharing a concurrency group with the caller → deadlock.
+# Direct tag-push invocations use `docker-build-push-<ref>`; workflow_call invocations get a
+# per-run-unique group (they are already serialized by the caller's own concurrency group).
 concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
+  group: ${{ (github.event_name == 'push') && format('docker-build-push-{0}', github.ref) || format('docker-build-push-nested-{0}', github.run_id) }}
   cancel-in-progress: false
 
 jobs:
@@ -46,7 +69,29 @@ jobs:
             slug: gitnexus
 
     steps:
+      # Only the workflow_call path requires a non-empty `inputs.tag` — callers
+      # (e.g. release-candidate.yml) must pass the RC tag explicitly. On direct
+      # tag pushes the tag comes from `github.ref`, so `inputs.tag` is always
+      # empty and validating it here would break every real release (#1064).
+      # The downstream "Verify tag matches gitnexus/package.json version" step
+      # handles both event types by falling back to GITHUB_REF.
+      - name: Validate tag input
+        if: github.event_name == 'workflow_call'
+        shell: bash
+        env:
+          TAG_INPUT: ${{ inputs.tag }}
+        run: |
+          if [ -z "${TAG_INPUT}" ]; then
+            echo "::error::No tag provided to docker.yml — refusing to build/push."
+            exit 1
+          fi
+
+      # When triggered by workflow_call the caller passes the RC tag as an input;
+      # we check out that tag so the Dockerfile and package.json match the built image.
+      # For tag-push events github.ref is already the tag ref — no override needed.
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          ref: ${{ inputs.tag || github.ref }}
 
       # ── Lock the docker image version to the npm package version ──────────
       # Mirrors the check in publish.yml: refuse to build unless the git tag
@@ -55,9 +100,18 @@ jobs:
       # `gitnexus@X.Y.Z` published to npm — no drift, no surprises.
       - name: Verify tag matches gitnexus/package.json version
         id: version
+        if: github.event_name != 'workflow_dispatch' && github.event_name != 'pull_request'
         shell: bash
+        env:
+          # For workflow_call the tag comes from the caller input; for push events
+          # it is derived from GITHUB_REF (set to empty so the else-branch fires).
+          INPUT_TAG: ${{ inputs.tag }}
         run: |
-          TAG_VERSION="${GITHUB_REF#refs/tags/v}"
+          if [ -n "$INPUT_TAG" ]; then
+            TAG_VERSION="${INPUT_TAG#v}"
+          else
+            TAG_VERSION="${GITHUB_REF#refs/tags/v}"
+          fi
           if ! [[ "$TAG_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$ ]]; then
             echo "::error::Tag does not follow semver: v$TAG_VERSION"
             exit 1
@@ -81,42 +135,78 @@ jobs:
         uses: sigstore/cosign-installer@cad07c2e89fa2edd6e2d7bab4c1aa38e53f76003 # v4.1.1
 
       - name: Log in to GitHub Container Registry
+        if: ${{ github.event_name != 'pull_request' && !inputs.dry_run }}
         uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
+      # Docker Hub is a mirror of GHCR: same tags, same digests, same Cosign
+      # signatures. GHCR remains authoritative (it is the registry the
+      # ClusterImagePolicy globs against by default), but Docker Hub is the
+      # registry most users reach for first, so we publish there too.
+      # Requires repo secrets DOCKERHUB_USERNAME and DOCKERHUB_TOKEN (a scoped
+      # access token, NOT the account password) with write access to the
+      # `akonlabs/gitnexus` and `akonlabs/gitnexus-web` repos.
+      - name: Log in to Docker Hub
+        if: ${{ github.event_name != 'pull_request' && !inputs.dry_run }}
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
       # Computes image tags and labels from the verified semver tag:
       #   v1.2.3        → :1.2.3, :1.2, :1, :latest (auto, only for non-prerelease)
       #   v1.2.3-rc.1   → :1.2.3-rc.1 only (prereleases never become :latest)
       # `:latest` is only emitted for tag pushes thanks to `flavor: latest=auto`,
       # ensuring it always points at a real npm-published version.
+      #
+      # For workflow_call invocations github.ref is the caller's branch ref, so
+      # the type=semver patterns would not match. In that case we add an explicit
+      # type=raw tag using the version already verified above, so the same
+      # image-naming rules apply regardless of how the workflow was triggered.
+      # NOTE: We check `inputs.tag` rather than `github.event_name` because in a
+      # reusable workflow the github context is inherited from the caller —
+      # `github.event_name` would still be "push", not "workflow_call".
       - name: Extract Docker metadata
         id: meta
         uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
         with:
-          images: ghcr.io/${{ github.repository_owner }}/${{ matrix.image.slug }}
+          # Dual-registry publish. metadata-action expands the same tag set
+          # against every image ref listed here, and build-push-action pushes
+          # one build to all of them, so the GHCR and Docker Hub images share
+          # a digest and are byte-identical. The Docker Hub namespace
+          # (`akonlabs`) is hardcoded because it differs from the GitHub org
+          # (`abhigyanpatwari`) — `github.repository_owner` would produce the
+          # wrong ref.
+          images: |
+            ghcr.io/${{ github.repository_owner }}/${{ matrix.image.slug }}
+            docker.io/akonlabs/${{ matrix.image.slug }}
           flavor: latest=auto
           tags: |
             type=semver,pattern={{version}}
             type=semver,pattern={{major}}.{{minor}}
             type=semver,pattern={{major}}
+            type=raw,value=${{ steps.version.outputs.version }},enable=${{ inputs.tag != '' }}
 
+      # Transient 502s from GHCR / Docker Hub / GHA cache during multi-platform
+      # exports are retried inside `.github/actions/docker-build-push-retry`
+      # (see docker/build-push-action#1422 — retry policy stays out of the
+      # upstream action). `ignore-error=true` on cache-to avoids cache export
+      # flakes failing an otherwise successful push.
       - name: Build and push
         id: build
-        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        uses: ./.github/actions/docker-build-push-retry
         with:
           context: .
           file: ${{ matrix.image.dockerfile }}
           platforms: linux/amd64,linux/arm64
-          push: true
+          push: ${{ github.event_name != 'pull_request' && !inputs.dry_run }}
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
           cache-from: type=gha,scope=${{ matrix.image.slug }}
-          cache-to: type=gha,mode=max,scope=${{ matrix.image.slug }}
-          provenance: mode=max
-          sbom: true
+          cache-to: type=gha,mode=max,scope=${{ matrix.image.slug }},ignore-error=true
 
       # Cosign keyless signing. Each pushed tag is signed by the workflow's
       # OIDC identity, so consumers can verify the image with the strict,
@@ -131,6 +221,7 @@ jobs:
       # Do NOT relax to `@.*` — that accepts signatures from any ref, including
       # unprotected branches and PRs, and defeats the supply-chain guarantee.
       - name: Sign image with Cosign (keyless)
+        if: ${{ github.event_name != 'pull_request' && !inputs.dry_run }}
         env:
           # Cosign v2 (installed by sigstore/cosign-installer above) makes
           # keyless the default. COSIGN_EXPERIMENTAL is a v1-only opt-in flag
@@ -146,10 +237,23 @@ jobs:
             [[ -n "$tag" ]] && cosign sign --yes "${tag}@${DIGEST}"
           done <<< "$TAGS"
 
-      # Attach the SBOM produced by buildx as a verifiable attestation on the digest.
-      - name: Generate build provenance attestation
+      # Attach the SBOM produced by buildx as a verifiable attestation on the
+      # digest. Attestations are pushed as OCI referrers to the registry named
+      # in `subject-name`, so we call the action once per registry. The digest
+      # is identical across registries (same build, same push), so consumers
+      # pulling from either GHCR or Docker Hub see the same provenance.
+      - name: Generate build provenance attestation (GHCR)
+        if: ${{ github.event_name != 'pull_request' && !inputs.dry_run }}
         uses: actions/attest-build-provenance@a2bbfa25375fe432b6a289bc6b6cd05ecd0c4c32 # v4.1.0
         with:
           subject-name: ghcr.io/${{ github.repository_owner }}/${{ matrix.image.slug }}
           subject-digest: ${{ steps.build.outputs.digest }}
           push-to-registry: true
+
+      - name: Generate build provenance attestation (Docker Hub)
+        if: ${{ github.event_name != 'pull_request' && !inputs.dry_run }}
+        uses: actions/attest-build-provenance@a2bbfa25375fe432b6a289bc6b6cd05ecd0c4c32 # v4.1.0
+        with:
+          subject-name: docker.io/akonlabs/${{ matrix.image.slug }}
+          subject-digest: ${{ steps.build.outputs.digest }}
+          push-to-registry: true

.github/workflows/gitleaks.yml

@@ -0,0 +1,45 @@
+name: Gitleaks
+
+# Deterministic in-CI secret scanning. Defense-in-depth on top of GitHub's
+# native secret-scanning push protection (which is a repo Settings toggle —
+# see SECURITY.md for the recommended admin action).
+#
+# PR runs scan the diff (fast); main pushes scan full history.
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  gitleaks:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      pull-requests: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          # Full history needed for the on-push full-history scan; on PRs the
+          # action diffs against the base ref so the cost is bounded by the PR.
+          fetch-depth: 0
+          # Don't bake the token into the cloned .git/config; downstream
+          # steps (and Gitleaks itself) don't need it for repo operations.
+          persist-credentials: false
+
+      # No GITLEAKS_LICENSE secret is required for OSS / public-repo usage.
+      # If this repo becomes private, the action will require a license key.
+      - name: Gitleaks
+        uses: gitleaks/gitleaks-action@ff98106e4c7b2bc287b24eaf42907196329070c7 # v2.3.9
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITLEAKS_ENABLE_UPLOAD_ARTIFACT: true
+          GITLEAKS_ENABLE_SUMMARY: true

.github/workflows/pr-labeler.yml

@@ -105,7 +105,7 @@ jobs:
       # Pinned to v7.2.0. Verify SHA via:
       #   gh api repos/release-drafter/release-drafter/git/refs/tags/v7.2.0
       # v7 removed `disable-releaser`; use `dry-run: true` to only autolabel.
-      - uses: release-drafter/release-drafter@5de93583980a40bd78603b6dfdcda5b4df377b32 # v7.2.0
+      - uses: release-drafter/release-drafter@563bf132657a13ded0b01fcb723c5a58cdd824e2 # v7.2.1
         with:
           config-name: release-drafter.yml
           dry-run: true

.github/workflows/publish.yml

@@ -33,12 +33,16 @@ jobs:
       id-token: write
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version: 20
           registry-url: https://registry.npmjs.org
-          cache: npm
-          cache-dependency-path: gitnexus/package-lock.json
+          # Hermetic install for the published artifact — no cache carry-over
+          # from non-tag contexts. setup-node v5+ caches by default when a
+          # packageManager field is present in package.json, so the explicit
+          # opt-out is required to clear the zizmor cache-poisoning audit.
+          # ~30s slower per release; runs rarely.
+          package-manager-cache: false
       - name: Build gitnexus-shared
         run: npm install && npm run build
         working-directory: gitnexus-shared

.github/workflows/release-candidate.yml

@@ -125,18 +125,23 @@ jobs:
     permissions:
       contents: write # push rc tag + marker
       id-token: write # npm provenance
+    outputs:
+      vtag: ${{ steps.reltag.outputs.vtag }}
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           fetch-depth: 0
           fetch-tags: true
 
-      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version: 20
           registry-url: https://registry.npmjs.org
-          cache: npm
-          cache-dependency-path: gitnexus/package-lock.json
+          # Hermetic install — release-candidate produces shipped artifacts.
+          # setup-node v5+ caches by default when a packageManager field is
+          # present in package.json; explicit opt-out is required to clear
+          # the zizmor cache-poisoning audit. See cache-poisoning audit.
+          package-manager-cache: false
 
       - name: Build gitnexus-shared
         run: npm install && npm run build
@@ -364,3 +369,27 @@ jobs:
 
             Release candidates are pre-stable builds intended for early testing.
             Stable releases remain on the `latest` dist-tag.
+
+  # ── Build & push RC Docker images ────────────────────────────────────
+  # Calls docker.yml as a reusable workflow so that the build, signing, and
+  # attestation logic stays in one place. The publish job exposes `vtag`
+  # (e.g. `v1.2.3-rc.1`) as an output so we can pass it as the tag input.
+  # RC images are signed with Cosign keyless signing; the OIDC identity
+  # will be `docker.yml@refs/heads/main` (the caller's ref) rather than a
+  # tag ref — see README.md § Docker for the correct verify command for RCs.
+  docker:
+    name: Build & Push RC Docker images
+    needs: [guard, publish]
+    if: needs.guard.outputs.should_run == 'true' && needs.publish.outputs.vtag != ''
+    uses: ./.github/workflows/docker.yml
+    # Reusable workflows do not receive caller secrets unless inherited; without
+    # this, DOCKERHUB_* / GITHUB_TOKEN are empty in docker.yml → "Username and
+    # password required" on Docker Hub login (see same pattern on `ci:` above).
+    secrets: inherit
+    permissions:
+      contents: read
+      packages: write
+      id-token: write
+      attestations: write
+    with:
+      tag: ${{ needs.publish.outputs.vtag }}

.github/workflows/scorecard.yml

@@ -0,0 +1,58 @@
+name: Scorecard
+
+# OpenSSF Scorecard supply-chain posture check. Runs weekly + on main push +
+# branch_protection_rule changes. SARIF uploads to the Security tab; the public
+# badge URL resolves once the first scheduled run lands (see README badge wiring).
+
+on:
+  branch_protection_rule:
+  schedule:
+    - cron: '0 7 * * 1'
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions: read-all
+
+jobs:
+  analysis:
+    name: Scorecard analysis
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      # Needed to upload SARIF results to the Security tab.
+      security-events: write
+      # Needed for the publish_results badge flow (OIDC).
+      id-token: write
+      contents: read
+      actions: read
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Run Scorecard
+        uses: ossf/scorecard-action@4eaacf0543bb3f2c246792bd56e8cdeffafb205a # v2.4.3
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          # publish_results enables the public Scorecard badge.
+          publish_results: true
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: SARIF file
+          path: results.sarif
+          retention-days: 5
+
+      - name: Upload to Security tab
+        uses: github/codeql-action/upload-sarif@0daab03d71ff584ef619d027a3fd9146679c5d84 # v3.35.3
+        with:
+          sarif_file: results.sarif

.github/workflows/trivy.yml

@@ -0,0 +1,73 @@
+name: Trivy Image Scan
+
+# Builds Dockerfile.cli and Dockerfile.web, then scans the resulting images
+# for OS-package and language-package CVEs at HIGH/CRITICAL severity.
+# Findings upload to the Security tab; record-only (does not block merges).
+#
+# NOT triggered on PRs — image builds are slow and base-image CVE churn
+# shouldn't gate feature delivery.
+
+on:
+  push:
+    branches: [main]
+  schedule:
+    - cron: '0 8 * * 1'
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  scan:
+    name: Trivy (${{ matrix.image.name }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        image:
+          - { dockerfile: Dockerfile.cli, name: gitnexus-cli }
+          - { dockerfile: Dockerfile.web, name: gitnexus-web }
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Setup Buildx
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
+
+      - name: Build image (load locally for scan)
+        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6.19.2
+        with:
+          context: .
+          file: ${{ matrix.image.dockerfile }}
+          load: true
+          push: false
+          tags: scan-target:${{ matrix.image.name }}
+
+      # aquasecurity/trivy-action versions < 0.35.0 are flagged by
+      # GHSA-69fq-xp46-6x23 (briefly compromised supply chain). Pinned to
+      # v0.36.0 (post-incident clean release) by commit SHA.
+      - name: Run Trivy
+        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
+        with:
+          image-ref: scan-target:${{ matrix.image.name }}
+          format: sarif
+          output: trivy-${{ matrix.image.name }}.sarif
+          severity: HIGH,CRITICAL
+          # Hides CVEs with no available fix in the base image.
+          ignore-unfixed: true
+          exit-code: '0'
+
+      - name: Upload to Security tab
+        uses: github/codeql-action/upload-sarif@0daab03d71ff584ef619d027a3fd9146679c5d84 # v3.35.3
+        with:
+          sarif_file: trivy-${{ matrix.image.name }}.sarif
+          category: trivy-${{ matrix.image.name }}

.github/workflows/workflow-lint.yml

@@ -0,0 +1,58 @@
+name: Workflow Lint (zizmor)
+
+# Lints .github/workflows/** for known GitHub Actions security misconfigurations:
+# unpinned Actions, dangerous ${{ ... }} interpolation in run: blocks,
+# missing per-job permissions:, etc.
+#
+# Scoped to PRs that touch .github/** only — keeps off the typical PR critical path.
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - '.github/**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  zizmor:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      security-events: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Setup Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: '3.12'
+
+      - name: Install zizmor
+        # Pinned — resolves to whatever's latest on PyPI otherwise.
+        # Bump via Dependabot pip ecosystem (see .github/dependabot.yml).
+        run: pipx install zizmor==1.24.1
+
+      # Initial threshold: medium. High+ findings fail the job; medium findings
+      # appear in the Security tab without blocking. Tune after first run.
+      # Per-rule exemptions for pre-existing intentional patterns live in
+      # .github/zizmor.yml (each carries a documented mitigation).
+      - name: Run zizmor
+        run: zizmor --config .github/zizmor.yml --format sarif --min-severity medium . > zizmor.sarif
+        continue-on-error: true
+
+      - name: Upload SARIF
+        uses: github/codeql-action/upload-sarif@0daab03d71ff584ef619d027a3fd9146679c5d84 # v3.35.3
+        with:
+          sarif_file: zizmor.sarif
+          category: zizmor
+
+      - name: Fail on high+ findings
+        run: zizmor --config .github/zizmor.yml --min-severity high .

.github/zizmor.yml

@@ -0,0 +1,34 @@
+# zizmor config — pre-existing intentional patterns flagged on initial introduction.
+# Each ignore below has a documented mitigation. Re-evaluate when the source workflow changes.
+#
+# To run zizmor locally with this config:
+#   zizmor --config .github/zizmor.yml .
+
+rules:
+  dangerous-triggers:
+    ignore:
+      # workflow_run is REQUIRED to post sticky comments on fork PRs — the
+      # default-branch privileged token isn't accessible from `pull_request`
+      # on a fork. Mitigated by: read-only `actions:read` + `contents:read`
+      # for artifact download; `pull-requests:write` is the only write scope;
+      # no checkout of fork code occurs. Header comment in the file documents.
+      - ci-report.yml
+
+      # pull_request_target needed by claude-code-action to access secrets
+      # and post review comments on fork PRs. Mitigated by: PR checkouts pin
+      # the fork's HEAD SHA (not the branch ref) to prevent TOCTOU races,
+      # and claude-code-action sandboxes execution. Header comment documents.
+      - claude.yml
+
+      # pull_request_target on the autolabel job needs `pull-requests:write`
+      # to apply labels. Mitigated by: release-drafter runs with `dry-run:
+      # true`, reads only `.github/release-drafter.yml` from the BASE ref,
+      # and the validate-title job (which runs untrusted `pull_request`
+      # context) holds no write permissions. Header comment documents.
+      - pr-labeler.yml
+
+  # Note: cache-poisoning is NOT exempted. The two prior findings in
+  # publish.yml and release-candidate.yml were fixed structurally by
+  # dropping `cache: npm` from those workflows (matches the pattern used
+  # by PyO3/maturin for the same audit). See the commit that added this
+  # file for the rationale.

.gitignore

@@ -103,3 +103,8 @@ gitnexus/vendor/**/node_modules/
 
 local_docs/
 
+# Local agent scratch / review prompts (never commit)
+.tmp/
+.agents/
+.context/
+gitnexus/web/

.prettierignore

@@ -2,6 +2,7 @@ dist/
 coverage/
 gitnexus/vendor/
 gitnexus/test/fixtures/
+gitnexus-web/test/fixtures/
 gitnexus-web/playwright-report/
 gitnexus-web/test-results/
 *.d.ts

AGENTS.md

@@ -1,7 +1,7 @@
-<!-- version: 1.4.0 -->
-<!-- Last updated: 2026-04-16 -->
+<!-- version: 1.7.0 -->
+<!-- Last updated: 2026-04-23 -->
 
-Last reviewed: 2026-04-16
+Last reviewed: 2026-04-23
 
 **Project:** GitNexus · **Environment:** dev · **Maintainer:** repository maintainers (see GitHub)
 
@@ -39,7 +39,8 @@ Commands and gotchas live under **Repo reference** below and in **[CONTRIBUTING.
 ## Reference docs
 
 - **[ARCHITECTURE.md](ARCHITECTURE.md)**, **[CONTRIBUTING.md](CONTRIBUTING.md)**, **[GUARDRAILS.md](GUARDRAILS.md)**
-- **Call-resolution DAG:** See ARCHITECTURE.md § Call-Resolution DAG. Typed 6-stage DAG inside the `parse` phase; language-specific behavior behind `inferImplicitReceiver` / `selectDispatch` hooks on `LanguageProvider`. Shared code in `gitnexus/src/core/ingestion/` must not name languages. Types: `gitnexus/src/core/ingestion/call-types.ts`.
+- **Call-resolution DAG (legacy path):** See ARCHITECTURE.md § Call-Resolution DAG. Typed 6-stage DAG inside the `parse` phase; language-specific behavior behind `inferImplicitReceiver` / `selectDispatch` hooks on `LanguageProvider`. Shared code in `gitnexus/src/core/ingestion/` must not name languages. Types: `gitnexus/src/core/ingestion/call-types.ts`.
+- **Scope-resolution pipeline (RFC #909 Ring 3):** See ARCHITECTURE.md § Scope-Resolution Pipeline. Replaces the legacy DAG for languages in `MIGRATED_LANGUAGES` (see `registry-primary-flag.ts`). A language plugs in by implementing `ScopeResolver` (`scope-resolution/contract/scope-resolver.ts`) and registering it in `SCOPE_RESOLVERS`. CI parity gate runs BOTH paths per migrated language on every PR.
 - **Cursor:** `.cursor/index.mdc` (always-on); `.cursor/rules/*.mdc` (glob-scoped). Legacy `.cursorrules` deprecated.
 - **GitNexus:** skills in `.claude/skills/gitnexus/`; MCP rules in `gitnexus:start` block below.
 
@@ -47,6 +48,9 @@ Commands and gotchas live under **Repo reference** below and in **[CONTRIBUTING.
 
 | Date | Version | Change |
 |------|---------|--------|
+| 2026-04-23 | 1.7.0 | TypeScript added to `MIGRATED_LANGUAGES` (registry-primary call resolution by default). |
+| 2026-04-20 | 1.6.0 | Added scope-resolution pipeline pointer (RFC #909 Ring 3); Python migrated to registry-primary. |
+| 2026-04-19 | 1.5.0 | Cross-repo impact (#794): `impact`/`query`/`context` accept `repo: "@<group>"` + `service`. Removed `group_query`/`group_contracts`/`group_status` MCP tools; added `gitnexus://group/{name}/contracts` and `gitnexus://group/{name}/status` resources. |
 | 2026-04-16 | 1.4.0 | Fixed: web UI description, pre-commit behavior, MCP tools (7->16), added gitnexus-shared, removed stale vite-plugin-wasm gotcha. |
 | 2026-04-13 | 1.3.0 | Updated GitNexus index stats after DAG refactor. |
 | 2026-03-24 | 1.2.0 | Fixed gitnexus:start block duplication. |
@@ -107,10 +111,14 @@ Indexed as **GitNexus** (4325 symbols, 10556 relationships, 300 execution flows)
 | `tool_map` | MCP/RPC tool definitions | `gitnexus_tool_map({})` |
 | `shape_check` | Response shape vs consumer access | `gitnexus_shape_check({route: "/api/users"})` |
 | `group_list` | List repo groups | `gitnexus_group_list({})` |
-| `group_query` | Cross-repo search in a group | `gitnexus_group_query({name: "myGroup", query: "auth"})` |
 | `group_sync` | Rebuild group Contract Registry | `gitnexus_group_sync({name: "myGroup"})` |
-| `group_contracts` | Inspect group contracts | `gitnexus_group_contracts({name: "myGroup"})` |
-| `group_status` | Group staleness report | `gitnexus_group_status({name: "myGroup"})` |
+| `query` (group mode) | Cross-repo search in a group (RRF-merged) | `gitnexus_query({repo: "@myGroup", query: "auth"})` |
+| `context` (group mode) | 360° view across all member repos | `gitnexus_context({repo: "@myGroup", name: "validateUser"})` |
+| `impact` (group mode) | Cross-repo blast radius via Contract Bridge | `gitnexus_impact({repo: "@myGroup", target: "X", direction: "upstream"})` |
+
+> Group mode: pass `repo: "@<groupName>"` to fan out across all member repos, or `repo: "@<groupName>/<memberPath>"` to target a single member (path keys from `group.yaml`). Optional `service: "<monorepo/path>"` filters by service root. Group-level state (contracts, staleness) lives in the resources table below — there are **no** `group_query` / `group_context` / `group_impact` / `group_contracts` / `group_status` MCP tools.
+>
+> For a full walkthrough of setting up a group across multiple repos that communicate over gRPC, see [docs/guides/microservices-grpc.md](docs/guides/microservices-grpc.md).
 
 ## Impact Risk Levels
 
@@ -128,6 +136,8 @@ Indexed as **GitNexus** (4325 symbols, 10556 relationships, 300 execution flows)
 | `gitnexus://repo/GitNexus/clusters` | All functional areas |
 | `gitnexus://repo/GitNexus/processes` | All execution flows |
 | `gitnexus://repo/GitNexus/process/{name}` | Step-by-step execution trace |
+| `gitnexus://group/{name}/contracts` | Group Contract Registry (provider/consumer rows + cross-links) |
+| `gitnexus://group/{name}/status` | Per-member index + Contract Registry staleness report |
 
 ## Self-Check Before Finishing
 
@@ -139,13 +149,14 @@ Indexed as **GitNexus** (4325 symbols, 10556 relationships, 300 execution flows)
 ## Keeping the Index Fresh
 
 ```bash
-npx gitnexus analyze              # basic refresh
-npx gitnexus analyze --embeddings # preserve embeddings
+npx gitnexus analyze                 # basic refresh; preserves any existing embeddings
+npx gitnexus analyze --embeddings    # also generate embeddings for new/changed nodes
+npx gitnexus analyze --drop-embeddings  # explicit opt-in to wipe existing embeddings
 ```
 
-Check `.gitnexus/meta.json` `stats.embeddings` (0 = none). Running without `--embeddings` deletes existing vectors.
+Check `.gitnexus/meta.json` `stats.embeddings` (0 = none). A plain `analyze` no longer drops existing vectors — pass `--drop-embeddings` to wipe.
 
-> Claude Code: PostToolUse hook handles this after `git commit` and `git merge`.
+> Claude Code: PostToolUse hook detects a stale index after `git commit` and `git merge` and prompts the agent to run `analyze`. The hook does not invoke `analyze` itself.
 
 ## CLI Skills
 

ARCHITECTURE.md

@@ -42,10 +42,14 @@ Monorepo: **CLI/MCP** (`gitnexus/`) + **browser UI** (`gitnexus-web/`).
 | `tool_map` | MCP/RPC tool definitions and handlers |
 | `shape_check` | Response shape vs consumer property access mismatches |
 | `group_list` | List repo groups or details for one group |
-| `group_query` | Cross-repo search in a group (reciprocal rank fusion) |
-| `group_sync` | Rebuild group Contract Registry (`contracts.json`) |
-| `group_contracts` | Inspect group contracts and cross-links |
-| `group_status` | Index and Contract Registry staleness per repo in a group |
+| `group_sync` | Rebuild group Contract Registry (`contracts.json`) and bridge graph |
+
+`query`, `context`, and `impact` are group-aware: pass `repo: "@<groupName>"` (or `"@<groupName>/<memberPath>"` to scope to one member) plus optional `service: "<monorepo/path>"`. Group-mode `query` merges per-repo results via Reciprocal Rank Fusion; group-mode `impact` runs the local walk in the chosen member and fans out across boundaries via the Contract Bridge (`gitnexus/src/core/group/cross-impact.ts`). The previously-planned `group_query`, `group_context`, `group_impact`, `group_contracts`, `group_status` MCP tools are intentionally not introduced — group-level state is exposed via resources instead:
+
+| Resource URI | Purpose |
+|--------------|---------|
+| `gitnexus://group/{name}/contracts` | Contract Registry (provider/consumer rows + cross-links) |
+| `gitnexus://group/{name}/status` | Per-member index + Contract Registry staleness |
 
 ## Where to change what
 
@@ -55,6 +59,7 @@ Monorepo: **CLI/MCP** (`gitnexus/`) + **browser UI** (`gitnexus-web/`).
 | Parsing/graph construction | `src/core/ingestion/pipeline-phases/` + `pipeline.ts` |
 | Graph schema/DB | `src/core/lbug/` (`schema.ts`, `lbug-adapter.ts`) |
 | MCP tools/resources | `src/mcp/server.ts`, `tools.ts`, `resources.ts` |
+| Cross-repo groups (sync, contracts, `@<group>` routing) | `src/core/group/` (`service.ts`, `cross-impact.ts`, `sync.ts`, `bridge-db.ts`) |
 | Search ranking | `src/core/search/` (BM25, hybrid fusion) |
 | Embeddings | `src/core/embeddings/` + `src/core/run-analyze.ts` |
 | Wiki generation | `src/core/wiki/` |
@@ -205,6 +210,138 @@ Both hooks are optional on `LanguageProvider`. Ruby is the only current implemen
 | `core/ingestion/languages/ruby.ts` | Both hooks + `mroStrategy: 'ruby-mixin'` |
 | `core/ingestion/utils/ruby-self-call.ts` | Bare-call rewrite for `inferImplicitReceiver` |
 
+### Coexistence with the scope-resolution pipeline
+
+The Call-Resolution DAG is the **legacy path**. RFC #909 Ring 3 introduces a parallel **scope-resolution pipeline** (next section) that replaces stages 1–6 with a scope-indexed registry lookup. Both paths ship side-by-side and are gated per-language via `MIGRATED_LANGUAGES` + the `REGISTRY_PRIMARY_<LANG>` env var.
+
+- **Unmigrated language** → Call-Resolution DAG runs; scope-resolution phase is a no-op.
+- **Migrated language** (currently: Python, C#) → scope-resolution owns CALLS/ACCESSES/USES emission; the legacy DAG gates off for that language via `isRegistryPrimary(lang)` checks in `call-processor.ts` and `import-processor.ts`.
+- `import-processor` still populates `importMap` for migrated languages — heritage's `ctx.resolve` reads it to disambiguate parent classes. Only edge emission is gated.
+- CI runs BOTH paths for every migrated language on every PR (`.github/workflows/ci-scope-parity.yml`); both must pass.
+
+#### Same-graph guarantee
+
+Edges emitted by the scope-resolution pipeline and edges emitted by the legacy DAG are indistinguishable to downstream consumers (MCP tools, HTTP API, embeddings, group bridge):
+
+- **Node identity** — both paths use `generateId(...)` from `lib/utils.ts`, the same qualified-name keyspace, and the same node labels (`File`, `Folder`, `Class`, `Method`, `Function`, …). Overload disambiguation suffixes `parameterTypes` into the id consistently — see `scope-resolution/graph-bridge/ids.ts` and the legacy emitter in `call-processor.ts`.
+- **Edge vocabulary** — both paths emit the same reasons: `'import-resolved' | 'global' | 'local-call' | 'same-file' | 'interface-dispatch' | 'read' | 'write'`. Migrating a language must not change which reasons consumers see for previously-resolved edges.
+- **Confidence tier** — both paths attach a numeric `confidence` to each edge using the same scale.
+
+The CI parity workflow (`.github/workflows/ci-scope-parity.yml`) runs both paths against every migrated language's fixture corpus and fails on any divergence.
+
+#### Semantic-model source of truth
+
+Two independent invariants.
+
+**ParsedFile = the AST-level truth.** `ParsedFile` (`gitnexus-shared/src/scope-resolution/parsed-file.ts`) is the single per-file artifact both resolution paths consume. Scope-resolution passes MUST NOT build a parallel parse representation. If a per-language hook needs AST-level facts that `ParsedFile` doesn't expose, it should reuse the orchestrator's `treeCache` (`RunScopeResolutionInput.treeCache`) rather than re-invoking `parser.parse(...)` on its own — the C# `populateNamespaceSiblings` hook is the reference implementation of this pattern.
+
+**SemanticModel = the symbol-level truth.** `SemanticModel` (`gitnexus/src/core/ingestion/model/semantic-model.ts`) is the authoritative store for every symbol-indexed lookup (by `nodeId`, `simpleName`, `qualifiedName`, or `filePath`). Both paths read from here:
+
+- Legacy Call-Resolution DAG → `call-processor` Tier 1/2/3 via `model.symbols.lookupExactAll`, `model.methods.lookupMethodByName`, `model.types.lookupClassByName`, `lookupMethodByOwnerWithMRO`.
+- Scope-resolution pipeline → `findOwnedMember`, `pickOverload`, `findExportedDefByName` all consult `model.methods` / `model.fields` / `model.symbols`.
+
+The scope-resolution pipeline additionally carries `WorkspaceResolutionIndex` for `Scope`-valued lookups (`classScopeByDefId`, `moduleScopeByFile`) that `SemanticModel` structurally cannot hold. No symbol-indexed duplicates exist outside `SemanticModel`.
+
+**Write / read phase contract.** The model is mutable during three ordered phases and read-only afterward:
+
+```
+ Phase 1: legacy parse     ──► symbolTable.add fans into types/methods/fields
+ Phase 2: scope-resolution ──► reconcileOwnership() registers corrected ownerIds
+ Phase 3: finalize         ──► model.attachScopeIndexes(bundle) — one-shot freeze
+ ─────────────────────────── phase boundary ───────────────────────────
+ Read phase: all resolution passes + MCP + HTTP + embeddings see
+             SemanticModel (read-only handle); writes are type-errors.
+```
+
+`runScopeResolution` narrows `MutableSemanticModel` → `SemanticModel` at the phase boundary so downstream passes physically cannot mutate the model even accidentally.
+
+**Transitional: reconciliation pass.** `reconcileOwnership` (`scope-resolution/pipeline/reconcile-ownership.ts`) is a shim for languages whose legacy extractor doesn't resolve `enclosingClassId` at parse time (Python class-body methods are the canonical case). It walks `parsed.localDefs[i].ownerId` after `populateOwners` and registers any missed methods/fields into the model. Idempotent — safe to re-run, safe alongside languages whose legacy extractor already carries `ownerId` (C#).
+
+The architectural end state is for every language's parse-time extractor to emit the correct `ownerId` directly, making reconciliation a no-op (tracked as a follow-up refactor). The dev-mode validator `validateOwnershipParity` surfaces any drift via `onWarn` under `NODE_ENV !== 'production' && VALIDATE_SEMANTIC_MODEL !== '0'`.
+
+References: `semantic-model.ts` file-head (full write/read contract); `contract/scope-resolver.ts` Contract Invariant I9 (scope-resolution-side rule).
+
+---
+
+## Scope-Resolution Pipeline (RFC #909 Ring 3)
+
+Language-agnostic registry-primary resolver. Replaces the Call-Resolution DAG for migrated languages. Adding a language is one interface implementation (`ScopeResolver`) plus two registrations — no changes to shared code, no new pipeline phase.
+
+### Pipeline stages
+
+```
+ ParsedFile[]  (extractParsedFile per file)
+    │  finalizeScopeModel (+ provider hooks)
+    ▼
+ ScopeResolutionIndexes
+    │  resolveReferenceSites  (via MethodRegistry.lookup)
+    ▼
+ ReferenceIndex
+    │  emitReceiverBoundCalls  ── FIRST
+    │  emitFreeCallFallback    ── THEN
+    │  emitReferencesViaLookup ── LAST (uses handledSites)
+    │  emitImportEdges
+    ▼
+ KnowledgeGraph  (IMPORTS / CALLS / ACCESSES / INHERITS / USES)
+```
+
+Orchestrator: `runScopeResolution(input, provider)` in `scope-resolution/pipeline/run.ts`.
+Pipeline phase: `scopeResolutionPhase` in `scope-resolution/pipeline/phase.ts` — iterates `SCOPE_RESOLVERS ∩ MIGRATED_LANGUAGES`, reads per-file Trees from the parse phase's `scopeTreeCache`, disposes the cache at the end.
+
+### `ScopeResolver` contract
+
+Single interface a language implements to plug into the pipeline. Contract fully documented in `scope-resolution/contract/scope-resolver.ts`.
+
+| Hook | Purpose |
+|------|---------|
+| `languageProvider` | Base `LanguageProvider` (tree-sitter query, `emitScopeCaptures`, import/binding interpreters, hooks) |
+| `populateOwners(parsed)` | Fill deferred `ownerId` fields on method defs (captures can't always know the owning class at parse time) |
+| `buildMro(graph, parsed, nodeLookup)` | Produce `mroByClassDefId: Map<DefId, DefId[]>` — C3, Ruby-mixin, or first-wins per language |
+| `resolveImportTarget(target, fromFile, allFiles)` | `(rawImportPath, sourceFile) → targetFilePath` (PEP-328 for Python, etc.) |
+| `mergeBindings(existing, incoming, scopeId)` | Shadowing / LEGB precedence |
+| `arityCompatibility` | Provider consumed by registry during `MethodRegistry.lookup` Step 2 |
+| `importEdgeReason` | Confidence-tier string for IMPORTS edge reason field |
+| `propagatesReturnTypesAcrossImports?` | Opt out of cross-file return-type propagation (default on) |
+| `fieldFallbackOnMethodLookup?` | Statically-typed languages turn this OFF — the heuristic over-connects (default on) |
+| `unwrapCollectionAccessor?` | Property-style collection views (`data.Values` on Dictionary-like receivers) — default off |
+| `collapseMemberCallsByCallerTarget?` | One CALLS edge per (caller, target) instead of per-site — default off |
+| `populateNamespaceSiblings?` | Cross-file implicit visibility (compiler-implicit namespace sharing) — default off; ctx carries `treeCache` |
+| `hoistTypeBindingsToModule?` | Walk up to Module scope when looking up a method's return-type typeBinding — default off; enable only when bindings are stored at module level |
+
+### Per-language registration
+
+1. Implement `ScopeResolver` in `languages/<lang>/scope-resolver.ts`.
+2. Add entry to `SCOPE_RESOLVERS` in `scope-resolution/pipeline/registry.ts`.
+3. Add the language to `MIGRATED_LANGUAGES` in `registry-primary-flag.ts` when the shadow-harness corpus parity ≥ 99% fixtures / ≥ 98% corpus.
+
+CI auto-discovers the set via `tsx`. No workflow edit required.
+
+### Code references
+
+| Module | Purpose |
+|--------|---------|
+| `scope-resolution/contract/scope-resolver.ts` | `ScopeResolver` interface + shared types |
+| `scope-resolution/pipeline/run.ts` | Generic orchestrator |
+| `scope-resolution/pipeline/phase.ts` | Pipeline-phase wrapper (deps: `parse`, `structure`) |
+| `scope-resolution/pipeline/registry.ts` | `SCOPE_RESOLVERS` map |
+| `scope-resolution/passes/*.ts` | Reference-resolution passes (receiver-bound, free-call fallback, compound-receiver, MRO, cross-file return-type propagation) |
+| `scope-resolution/graph-bridge/*.ts` | CLI-local translation from resolved references → `KnowledgeGraph` edges |
+| `scope-resolution/scope/*.ts` | Generic scope-chain walkers + namespace targets |
+| `scope-resolution/workspace-index.ts` | Build-once O(1) lookup index |
+| `registry-primary-flag.ts` | `MIGRATED_LANGUAGES` set + `isRegistryPrimary(lang)` |
+| `languages/python/index.ts` | Python `ScopeResolver` hooks + known-limitation docs |
+| `languages/python/captures.ts` | `emitPythonScopeCaptures` (honors cross-phase Tree cache) |
+| `languages/csharp/index.ts` | C# `ScopeResolver` hooks + known-limitation docs |
+| `languages/csharp/captures.ts` | `emitCsharpScopeCaptures` (honors cross-phase Tree cache) |
+| `languages/csharp/namespace-siblings.ts` | Cross-file implicit-namespace visibility hook (reads `treeCache`) |
+
+### Performance notes
+
+- **Cross-phase Tree cache**: parse phase writes Trees into `scopeTreeCache` (separate from the chunk-local `astCache`) ONLY for languages with `emitScopeCaptures`. Scope-resolution reads from it to skip the second parse. Cleared at end of the phase. Workers leave the cache empty — Trees can't cross MessageChannels; cache miss = fresh parse. `PROF_SCOPE_RESOLUTION=1` emits hit/miss counters and a worker-engaged warning.
+- **Typed relationship iteration**: heritage + MRO walk only the EXTENDS / IMPLEMENTS / HAS_METHOD edges via `iterRelationshipsByType`, not the full relationship map.
+- **Workspace-resolution-index**: O(1) `findOwnedMember` / `findExportedDef` / `classScopeByDefId` built once per run.
+- **SCC-ordered cross-file return-type propagation** (PR #1050): `propagateImportedReturnTypes` walks `indexes.sccs` in reverse-topological order (leaves first), so multi-hop alias chains like `models.User → service.user → app.user` collapse to the terminal class in a single linear pass. Within each importer, the source module's `typeBindings` is chain-followed BEFORE mirroring (so we mirror terminal types, not intermediate refs), and the importer's own `typeBindings` is chain-followed AFTER mirroring (so local `const x = importedFn()` resolves before downstream importers run). Cyclic SCCs reach a partial fixpoint within a single pass without iterating to convergence — see the `ts-circular` cross-file-binding fixture which only asserts pipeline-no-throw. PROF output (`PROF_SCOPE_RESOLUTION=1`) splits `finalize` from `propagate` so quadratic regressions in the chain-follow surface independently.
+
 ---
 
 ## Language-agnostic graph feeding

CONTRIBUTING.md

@@ -77,7 +77,7 @@ Every workflow under `.github/workflows/` MUST declare a top-level `concurrency:
   - Per-PR scope (for `issue_comment`, `pull_request_review*`, `pull_request` meta events): `${{ github.workflow }}-${{ github.event.pull_request.number || github.event.issue.number }}`
   - `workflow_run` scope (e.g. `ci-report.yml`): `${{ github.workflow }}-${{ github.event.workflow_run.pull_requests[0].number || format('{0}/{1}', github.event.workflow_run.head_repository.full_name, github.event.workflow_run.head_branch) }}` — the fork fallback must be stable across reruns (never `workflow_run.id`, which is per-run-unique and defeats serialization).
   - Global single-slot (manual dispatch utilities): `${{ github.workflow }}`
-  - **Reusable workflows invoked via `workflow_call`:** do NOT use `${{ github.workflow }}` in the group key — in called-workflow context its evaluation is ambiguous and can resolve to the caller's name, which would deadlock against the caller's own group. Use a hardcoded literal prefix and a `github.event_name`-aware expression that falls through to `github.run_id` for reusable invocations (see `ci.yml` for the canonical form).
+  - **Reusable workflows invoked via `workflow_call`:** do NOT use `${{ github.workflow }}` in the group key — in called-workflow context its evaluation is ambiguous and can resolve to the caller's name, which would deadlock against the caller's own group. Use a hardcoded literal prefix and a `github.event_name`-aware expression that falls through to `github.run_id` for reusable invocations (see `ci.yml` for the canonical form). Approved literal prefixes: `CI-` (`ci.yml`) and `docker-build-push-` (`docker.yml`). The `check-workflow-concurrency.py` validation script must be updated whenever a new approved literal prefix is added.
   - **Merge queue (`merge_group`)**: when this event is added, use `${{ github.workflow }}-${{ github.event.merge_group.head_ref }}` with `cancel-in-progress: false` (every queue entry is a distinct ref; never cancel).
 - **`cancel-in-progress` policy:**
 
@@ -127,6 +127,12 @@ Two publish workflows ship `gitnexus` to npm:
     the cycle from `latest`.
   - `N` is auto-incremented against existing `X.Y.Z-rc.*` entries on the
     registry. First rc for a given base is `rc.1`.
+  - After the npm publish succeeds, the workflow calls `docker.yml` as a
+    reusable workflow to build and push the corresponding RC Docker images
+    (e.g. `ghcr.io/abhigyanpatwari/gitnexus:1.7.0-rc.1`, mirrored to
+    `docker.io/akonlabs/gitnexus:1.7.0-rc.1`). The images are signed
+    with Cosign; the OIDC identity is `docker.yml@refs/heads/main` (the
+    caller's ref — see README.md § Docker for the verify command).
 
   Idempotency: the workflow pushes an `rc/<HEAD_SHA>` marker tag and a
   `v<RC>` release tag **atomically, before** calling `npm publish`. The guard
@@ -140,6 +146,27 @@ Two publish workflows ship `gitnexus` to npm:
   # then redispatch the workflow with force: true
   ```
 
+  **Docker-only partial failure:** if `publish` succeeds (npm tarball + tags
+  are live) but the `docker` job subsequently fails (e.g. GHCR flakiness),
+  the npm RC is already published and the `rc/<HEAD_SHA>` marker is in place.
+  Re-running `release-candidate.yml` with `force: true` will abort at the
+  "Version already exists on npm" guard. To recover without cutting a new RC:
+
+  ```bash
+  # 1. Manually trigger only the docker workflow, passing the existing RC tag:
+  gh workflow run docker.yml --ref main -f tag=v<RC_VERSION>
+  # (requires a workflow_dispatch trigger on docker.yml — see note below)
+  ```
+
+  Because `docker.yml` intentionally has no `workflow_dispatch` (images are
+  tag-driven by design), the practical recovery options are:
+  - Wait for the next commit on `main`, which will cut a new RC that includes
+    the Docker build.
+  - Manually run `docker build` + `docker push` locally and sign with Cosign
+    against the same digest.
+  - Delete `rc/<HEAD_SHA>` and `v<RC>` tags, then redispatch with `force:
+    true` to re-run the full RC pipeline (cuts a new RC number).
+
 The rc workflow never moves `latest`. To verify after a change, inspect dist-tags:
 
 ```bash

DoD.md

@@ -0,0 +1,209 @@
+# Definition of Done — GitNexus
+
+Last reviewed: 2026-04-23 · Version: 2.0.0
+
+This document defines the repo-wide completion bar for production-ready changes in GitNexus. It is the stable baseline. Implementation prompts, agent behavior, and review workflows may add task-specific checks, but they must never weaken this bar.
+
+Use it together with:
+
+- `AGENTS.md` — agent-facing rules of engagement
+- `GUARDRAILS.md` — hard safety constraints
+- `CONTRIBUTING.md` — contributor workflow
+- `TESTING.md` — test strategy and coverage expectations
+- `ARCHITECTURE.md` — pipeline boundaries, Call-Resolution DAG, LanguageProvider contract
+
+## 1. Scope and Intent
+
+A change is **Done** when it is correct, safely integrated, appropriately tested, operationally sound, and a net improvement to the codebase — not merely "the code compiles and a test passes."
+
+This DoD applies to:
+
+- CLI, MCP, and HTTP-bridge behavior in `gitnexus/`
+- Browser UI in `gitnexus-web/`
+- Shared contracts in `gitnexus-shared/`
+- CI workflows, release pipelines, and repo-level docs
+
+Out of scope: full agent personas, step-by-step implementation prompts, verbose review formatting rules, repo walkthroughs already covered elsewhere, temporary task-specific acceptance criteria. Those belong in prompts, PR templates, or other repo docs.
+
+## 2. Core Definition of Done
+
+Every change must satisfy **every relevant item** below. If an item does not apply, say so explicitly in the PR description.
+
+### 2.1 Correctness and Completeness
+
+- [ ] The requested behavior is implemented end-to-end in the **real runtime path** for the affected surface — no dead code, partial wiring, test-only shims, or "works in isolation but not in production" seams.
+- [ ] Edge cases relevant to the changed surface are handled or explicitly documented as out of scope.
+- [ ] Error handling is proportionate: inputs at system boundaries (user input, external APIs, filesystem, process spawn) are validated; internal, framework-guaranteed paths are trusted.
+- [ ] The change produces the same result on re-run (idempotent where expected) and does not rely on accidental ordering.
+
+### 2.2 Architecture and Placement
+
+- [ ] The change is placed in the correct package and layer:
+  - `gitnexus/` for CLI, MCP, HTTP bridge, ingestion, graph, and runtime logic
+  - `gitnexus-web/` for browser UI (thin client — no WASM workers, all queries via HTTP API)
+  - `gitnexus-shared/` for shared contracts, types, and constants
+- [ ] Pipeline and architecture boundaries remain explicit. Shared ingestion code in `gitnexus/src/core/ingestion/` must not name languages — use `LanguageProvider` hooks (see `AGENTS.md` and `ARCHITECTURE.md` § Call-Resolution DAG).
+- [ ] No hidden cross-phase coupling; no leaking of language-specific logic into shared infrastructure without a documented architectural reason.
+- [ ] Runtime and graph behavior are consistent — the real source of truth is fixed at the source, not symptom-patched in a downstream layer.
+- [ ] Direct imports from `gitnexus-shared` are used. No barrel re-exports introduced to paper over drift between packages.
+
+### 2.3 Design and Readability
+
+- [ ] The implementation is the **smallest correct solution** for the requirement. No speculative abstraction, unnecessary indirection, clever but hard-to-follow control flow, or unrelated cleanup.
+- [ ] Naming, control flow, ownership, and extension points are clear enough that the next contributor can extend the code without archaeology.
+- [ ] Comments are minimal and useful — they explain intent, invariants, contracts, or non-obvious constraints. No stale comments, placeholder comments, narrated code, commented-out code, or "what" comments where a good name would do.
+- [ ] No copy-paste duplication created for convenience; no premature deduplication of three similar lines.
+
+### 2.4 Contracts and Compatibility
+
+- [ ] Existing contracts (types in `gitnexus-shared/`, CLI flags, MCP tools/resources, HTTP routes, graph node/edge shapes, persisted IDs) are preserved unless the task explicitly requires a contract change.
+- [ ] Any contract change is intentional, explicit, and reflected in **every direct consumer** in the same change, with types aligned end-to-end.
+- [ ] Persisted data changes (graph schema, IDs, embeddings) are backward-compatible or accompanied by a documented migration / reindex path.
+- [ ] If user-visible behavior, public usage, CLI help, or README examples change, the relevant docs, examples, help text, or migration notes are updated in the same change.
+
+### 2.5 Security
+
+- [ ] No new injection surfaces (command, path, SQL/Cypher-style, prompt) introduced on paths that consume untrusted input.
+- [ ] No secrets, tokens, or credentials committed to the repo, to logs, or to error messages.
+- [ ] Filesystem access honors the repo-scope and indexed-repo boundaries documented in `AGENTS.md` and `GUARDRAILS.md`.
+- [ ] Third-party dependencies added or bumped are justified, from reputable sources, and do not regress the supply-chain posture.
+
+### 2.6 Performance and Resource Use
+
+- [ ] No repeated avoidable work, unnecessary scans, unnecessary round-trips, unbounded caches, or obvious hot-path regressions.
+- [ ] Tree-sitter buffer sizing follows the adaptive 512KB–32MB convention (`getTreeSitterBufferSize`) — do not hard-code new buffer sizes.
+- [ ] Memory and handle lifecycles are explicit: database handles (LadybugDB) close cleanly, no dangling process watchers, no leaked tree-sitter parsers.
+- [ ] Long-running or large-graph paths remain bounded or are measurably streamed; degradation on large real repos is considered, not assumed benign.
+
+### 2.7 Tests
+
+- [ ] Tests cover the **real changed path** — they would fail if behavior, wiring, or contracts were broken, not only if a mock were misconfigured.
+- [ ] Integration tests hit a real database where the production path does; do not introduce mocks that hide migration or schema drift.
+- [ ] Assertions are meaningful. Use `toBe` / `toEqual` for exact expectations; avoid `toBeGreaterThanOrEqual` and other bounds-only assertions that mask regressions.
+- [ ] Fixtures are realistic enough for the risk of the change — a one-file fixture is not sufficient for a pipeline-wide behavior change.
+- [ ] New tests are deterministic and do not depend on network, clock, or host-specific paths without explicit isolation.
+
+### 2.8 Observability and Operability
+
+- [ ] Errors surfaced to users or callers are actionable: they name what failed, what input was involved (without leaking secrets), and how to recover where possible.
+- [ ] Logging is proportionate — no noisy debug logs left in hot paths, no silent catches that swallow diagnostics.
+- [ ] CLI exit codes and MCP tool responses are correct for each outcome (success, user error, internal error).
+- [ ] Progress reporting (`PipelineProgress` and similar shared contracts) remains accurate after the change.
+
+### 2.9 Reversibility and Risk
+
+- [ ] The change has a clear rollback story: revert is safe, or migration is accompanied by a documented rollback / reindex procedure.
+- [ ] Residual risks, compatibility impacts, and operational concerns are either resolved or **clearly stated** in the PR description.
+- [ ] Destructive or hard-to-reverse operations (graph rebuild, schema change, `git` state manipulation) are opt-in or guarded.
+
+## 3. Agent-Assisted Workflow Guardrails
+
+When the change is produced with or reviewed by an AI agent, the following additional gates apply:
+
+- [ ] **Scope match.** The final diff matches the intended symbols, files, and processes — no speculative refactors, unrelated formatting churn, or collateral edits outside the task scope.
+- [ ] **Evidence-based edits.** Claims about repo state are verified against the current code, not trusted from memory or stale documentation.
+- [ ] **Impact analysis.** Where GitNexus graph tooling is available and relevant, impact of non-trivial symbol, contract, or runtime-path changes is checked **before** editing.
+- [ ] **Embeddings preserved.** If an indexed repo already has embeddings and re-analysis is required, embeddings are preserved — not accidentally dropped by a destructive reindex.
+- [ ] **No false-done.** "Done" is claimed only after the Validation Baseline below has been run or any gap is explicitly named. Green tests on an unrelated path do not constitute validation.
+- [ ] **Five-axis self-review** before handing off: correctness, readability, architecture, security, performance.
+
+## 4. Validation Baseline
+
+Run the commands relevant to the touched area. If something cannot be run in the current environment, state it explicitly in the handoff.
+
+### 4.1 Build ordering
+
+- [ ] `gitnexus-shared/` dist is built before consuming packages are typechecked or tested (CI uses the `setup-gitnexus` action for this — local runs must match).
+
+### 4.2 If `gitnexus/` changed
+
+- [ ] `cd gitnexus && npx tsc --noEmit`
+- [ ] `cd gitnexus && npm test`
+- [ ] `cd gitnexus && npx prettier --check .` for files in the diff (pre-commit runs the affected-tests subset; do not expand scope)
+
+### 4.3 If `gitnexus-web/` changed
+
+- [ ] `cd gitnexus-web && npx tsc -b --noEmit`
+- [ ] `cd gitnexus-web && npm test`
+- [ ] `cd gitnexus-web && npm run test:e2e` when browser flows or user-facing UI behavior changed
+
+### 4.4 If `gitnexus-shared/` changed
+
+- [ ] Shared package builds cleanly (`npm run build` in `gitnexus-shared/`)
+- [ ] Dependent packages still typecheck and test after the shared change — verify both CLI and web consumers together
+
+### 4.5 If CI workflows or release pipelines changed
+
+- [ ] The workflow passes a dry-run or triggered run before merge; concurrency (`cancel-in-progress`) and the `setup-gitnexus` action remain wired correctly.
+- [ ] `CHANGELOG.md` is **not** edited here — it is owned by the release process.
+
+## 5. Review Gates
+
+A reviewer (human or agent) should be able to answer **yes** to each of the following before approving:
+
+1. **Correctness** — Does the change do what it claims on the real runtime path?
+2. **Readability** — Will the next contributor understand this in six months without asking?
+3. **Architecture** — Is it in the right package, layer, and phase? Are boundaries respected?
+4. **Security** — No new injection, leak, or trust-boundary violation?
+5. **Performance** — No obvious regression on realistic inputs?
+6. **Tests** — Would a regression in the changed behavior fail loudly?
+7. **Scope** — Does the diff match the intended change, with no unrelated churn?
+
+## 6. "Not Done" Signals
+
+A change is **not** Done if any of the following is true, even if CI is green:
+
+- The runtime path is not actually exercised by the tests.
+- A contract drifted between `gitnexus/`, `gitnexus-web/`, and `gitnexus-shared/` and only one side was updated.
+- A language-specific concern leaked into shared ingestion code.
+- The diff contains unrelated reformatting, refactors, or cleanup beyond the stated task.
+- Logs, comments, or TODOs were added as placeholders for work not done.
+- The change depends on a manual step that is not documented.
+- `CHANGELOG.md` was edited during PR work.
+- Pre-commit, prettier, or typecheck was bypassed without explicit justification.
+
+## 7. Task-Specific DoD Template
+
+Use this in implementation and review prompts. Keep it short and tailor it to the actual change:
+
+```md
+# Definition of Done for this implementation
+
+- [ ] Runtime wiring is complete for the affected path.
+- [ ] Requested behavior is correct and relevant contracts are preserved or explicitly updated.
+- [ ] The design stays scoped, readable, and proportionate to the task.
+- [ ] Tests prove the changed behavior and catch broken wiring.
+- [ ] Required validation for touched packages has been run, or any gap is explicitly noted.
+- [ ] Repo boundaries, security, performance, and operational safety are respected.
+- [ ] The diff contains only the intended change — no unrelated churn.
+```
+
+## 8. How to Use This File in Claude Review
+
+Reference this file as the repo-wide completion bar. Add a task-specific review instruction such as:
+
+```md
+Review this change against `DoD.md` and the repo docs (`AGENTS.md`, `GUARDRAILS.md`,
+`CONTRIBUTING.md`, `TESTING.md`, `ARCHITECTURE.md`). Treat `DoD.md` as the minimum
+bar for production readiness. Flag anything that is partially wired, contract-unsafe,
+under-tested, architecturally misplaced, scope-creeping, or harder to maintain than
+necessary. Apply the five-axis review gate: correctness, readability, architecture,
+security, performance.
+```
+
+## 9. Evolution
+
+This DoD is living. Revisit it when:
+
+- A class of incident slips past it (add a gate).
+- A gate becomes consistently ceremonial without catching issues (remove or merge it).
+- The architecture evolves in a way that changes what "done" means (update placement, validation, or contracts sections).
+
+Track material updates in the changelog below. Keep the file tight — if it grows past a single read-in-one-sitting, something has drifted into the wrong place.
+
+## Changelog
+
+| Date       | Version | Change                                                                                                                                                        |
+| ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 2026-04-23 | 2.0.0   | Restructured into numbered sections; added Security, Observability, Reversibility, Agent-Assisted Guardrails, Review Gates, Not-Done Signals; expanded validation baseline (shared-first build, prettier, CI workflow checks). |
+| 2026-04-13 | 1.0.0   | Initial repo-wide Definition of Done.                                                                                                                         |

Dockerfile.cli

@@ -4,17 +4,18 @@ ARG TARGETPLATFORM
 # ── Builder ────────────────────────────────────────────────────────────
 # Native modules (tree-sitter-*, onnxruntime-node, node-gyp builds for
 # tree-sitter-proto / tree-sitter-swift) require python3 + a C/C++ toolchain.
-FROM node:22-alpine AS builder
+FROM node:22-trixie-slim AS builder
 
 WORKDIR /app
 
 # Toolchain for node-gyp / native builds.
-RUN apk add --no-cache python3 make g++ git
+RUN apt-get update && apt-get install -y --no-install-recommends python3 make g++ git && rm -rf /var/lib/apt/lists/*
 
 # Build gitnexus-shared first — gitnexus depends on it as a workspace.
 COPY gitnexus-shared/package.json gitnexus-shared/package-lock.json ./gitnexus-shared/
 RUN npm ci --prefix gitnexus-shared
 COPY gitnexus-shared ./gitnexus-shared
+RUN rm -f gitnexus-shared/tsconfig.tsbuildinfo
 RUN npm run build --prefix gitnexus-shared
 
 # Copy the full gitnexus package before installing — `npm ci` triggers
@@ -28,10 +29,10 @@ RUN npm ci --prefix gitnexus
 RUN npm prune --omit=dev --prefix gitnexus
 
 # ── Runtime ────────────────────────────────────────────────────────────
-FROM node:22-alpine AS runtime
+FROM node:22-trixie-slim AS runtime
 
 # curl for the healthcheck; git so `gitnexus` can clone repos at runtime.
-RUN apk add --no-cache curl git
+RUN apt-get update && apt-get install -y --no-install-recommends curl git && rm -rf /var/lib/apt/lists/*
 
 WORKDIR /app
 

Dockerfile.web

@@ -11,6 +11,8 @@ RUN npm ci --prefix gitnexus-shared
 COPY gitnexus-shared ./gitnexus-shared
 RUN npm run build --prefix gitnexus-shared
 
+COPY gitnexus/package.json ./gitnexus/
+
 COPY gitnexus-web/package.json gitnexus-web/package-lock.json ./gitnexus-web/
 RUN npm ci --prefix gitnexus-web
 

GUARDRAILS.md

@@ -19,7 +19,7 @@ Maintainer may widen scope per task.
 2. **Never rename with find-and-replace** in GitNexus-indexed projects — use `rename` MCP tool with `dry_run: true` first, review `graph` vs `text_search` edits. No separate `gitnexus rename` CLI exists.
 3. **Run impact analysis before editing shared symbols** — `impact` (upstream) for functions/classes/methods others call. Do not ignore HIGH/CRITICAL without maintainer sign-off.
 4. **Run `detect_changes` before commit** — confirm diffs map to expected symbols/processes when the graph is available.
-5. **Preserve embeddings** — if `.gitnexus/meta.json` shows embeddings, use `npx gitnexus analyze --embeddings`; plain `analyze` drops them.
+5. **Preserve embeddings** — plain `npx gitnexus analyze` now preserves any embeddings recorded in `.gitnexus/meta.json` (the previous behavior wiped them). Use `--embeddings` to also generate vectors for new/changed nodes; use `--drop-embeddings` only when an explicit wipe is intended (e.g., model swap).
 
 ---
 
@@ -36,8 +36,8 @@ Format: **Trigger → Instruction → Reason**. Append new Signs when the same m
 ### Embeddings vanished after analyze
 
 - **Trigger:** Semantic search quality drops; `stats.embeddings` in `meta.json` is 0 after refresh.
-- **Do:** `npx gitnexus analyze --embeddings`, confirm `meta.json` reflects stored embeddings.
-- **Why:** Embedding generation is opt-in; analyze without the flag does not preserve prior vectors.
+- **Do:** Re-run `npx gitnexus analyze --embeddings` to regenerate. Check the analyze log for a `Warning: could not load cached embeddings` line — if present, the cache restore failed (corrupt DB / schema mismatch) and the rebuild had nothing to preserve. If you intentionally passed `--drop-embeddings`, this is expected.
+- **Why:** Plain `analyze` preserves prior vectors by re-inserting them after the rebuild; the only ways to end up at zero are an explicit `--drop-embeddings`, a cache-load failure (now logged), or a model/dimension change that invalidates the cache.
 
 ### MCP lists no repos
 

README.md

@@ -1,5 +1,5 @@
 # GitNexus
-⚠️ Important Notice:** GitNexus has NO official cryptocurrency, token, or coin. Any token/coin using the GitNexus name on Pump.fun or any other platform is **not affiliated with, endorsed by, or created by** this project or its maintainers. Do not purchase any cryptocurrency claiming association with GitNexus.
+**⚠️ Important Notice:** GitNexus has NO official cryptocurrency, token, or coin. Any token/coin using the GitNexus name on Pump.fun or any other platform is **not affiliated with, endorsed by, or created by** this project or its maintainers. Do not purchase any cryptocurrency claiming association with GitNexus.
 
 <div align="center">
 
@@ -9,7 +9,7 @@
 
   <h2>Join the official Discord to discuss ideas, issues etc!</h2>
 
-  <a href="https://discord.gg/AAsRVT6fGb">
+  <a href="https://discord.gg/MgJrmsqr62">
     <img src="https://img.shields.io/discord/1477255801545429032?color=5865F2&logo=discord&logoColor=white" alt="Discord"/>
   </a>
   <a href="https://www.npmjs.com/package/gitnexus">
@@ -18,6 +18,9 @@
   <a href="https://polyformproject.org/licenses/noncommercial/1.0.0/">
     <img src="https://img.shields.io/badge/License-PolyForm%20Noncommercial-blue.svg" alt="License: PolyForm Noncommercial"/>
   </a>
+  <a href="https://securityscorecards.dev/viewer/?uri=github.com/abhigyanpatwari/GitNexus">
+    <img src="https://api.securityscorecards.dev/projects/github.com/abhigyanpatwari/GitNexus/badge" alt="OpenSSF Scorecard"/>
+  </a>
 
   <p><strong>Enterprise (SaaS & Self-hosted)</strong> - <a href="https://akonlabs.com">akonlabs.com</a></p>
 
@@ -36,7 +39,7 @@ https://github.com/user-attachments/assets/172685ba-8e54-4ea7-9ad1-e31a3398da72
 
 > *Like DeepWiki, but deeper.* DeepWiki helps you *understand* code. GitNexus lets you *analyze* it — because a knowledge graph tracks every relationship, not just descriptions.
 
-**TL;DR:** The **Web UI** is a quick way to chat with any repo. The **CLI + MCP** is how you make your AI agent actually reliable — it gives Cursor, Claude Code, Codex, and friends a deep architectural view of your codebase so they stop missing dependencies, breaking call chains, and shipping blind edits. Even smaller models get full architectural clarity, making it compete with goliath models.
+**TL;DR:** The **Web UI** is a quick way to chat with any repo. The **CLI + MCP** is how you make your AI agent actually reliable — it gives Cursor, Claude Code, Codex, and friends a deep architectural view of your codebase so they stop missing dependencies, breaking call chains, and shipping blind edits. Even smaller models get full architectural clarity, making it compete with Goliath models.
 
 ---
 
@@ -120,7 +123,7 @@ To configure MCP for your editor, run `npx gitnexus setup` once — or set it up
 | **Windsurf**    | Yes | —     | —                   | MCP            |
 | **OpenCode**    | Yes | Yes    | —                   | MCP + Skills   |
 
-> **Claude Code** gets the deepest integration: MCP tools + agent skills + PreToolUse hooks that enrich searches with graph context + PostToolUse hooks that auto-reindex after commits.
+> **Claude Code** gets the deepest integration: MCP tools + agent skills + PreToolUse hooks that enrich searches with graph context + PostToolUse hooks that detect a stale index after commits and prompt the agent to reindex.
 
 ## Community Integrations
 
@@ -194,8 +197,10 @@ gitnexus analyze --force         # Force full re-index
 gitnexus analyze --skills        # Generate repo-specific skill files from detected communities
 gitnexus analyze --skip-embeddings  # Skip embedding generation (faster)
 gitnexus analyze --skip-agents-md  # Preserve custom AGENTS.md/CLAUDE.md gitnexus section edits
+gitnexus analyze --skip-git        # Index folders that are not Git repositories
 gitnexus analyze --embeddings    # Enable embedding generation (slower, better search)
 gitnexus analyze --verbose       # Log skipped files when parsers are unavailable
+gitnexus analyze --worker-timeout 60  # Increase worker idle timeout for slow parses
 gitnexus mcp                     # Start MCP server (stdio) — serves all indexed repos
 gitnexus serve                   # Start local HTTP server (multi-repo) for web UI connection
 gitnexus list                    # List all indexed repositories
@@ -207,16 +212,18 @@ gitnexus wiki --model <model>    # Wiki with custom LLM model (default: gpt-4o-m
 gitnexus wiki --base-url <url>   # Wiki with custom LLM API base URL
 
 # Repository groups (multi-repo / monorepo service tracking)
-gitnexus group create <name>     # Create a repository group
-gitnexus group add <name> <repo> # Add a repo to a group
-gitnexus group remove <name> <repo> # Remove a repo from a group
-gitnexus group list [name]       # List groups, or show one group's config
-gitnexus group sync <name>       # Extract contracts and match across repos/services
+gitnexus group create <name>                                   # Create a repository group
+gitnexus group add <group> <groupPath> <registryName>          # Add a repo to a group. <groupPath> is a hierarchy path (e.g. hr/hiring/backend); <registryName> is the repo's name from the registry (see `gitnexus list`)
+gitnexus group remove <group> <groupPath>                      # Remove a repo from a group by its hierarchy path
+gitnexus group list [name]                                     # List groups, or show one group's config
+gitnexus group sync <name>                                     # Extract contracts and match across repos/services
 gitnexus group contracts <name>  # Inspect extracted contracts and cross-links
 gitnexus group query <name> <q>  # Search execution flows across all repos in a group
 gitnexus group status <name>     # Check staleness of repos in a group
 ```
 
+If `analyze` reports a worker parse timeout on a large or unusual repository, it keeps running and falls back safely. To give slow worker jobs more time, use `gitnexus analyze --worker-timeout 60` or set `GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=60000`. For very large files, `GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES` controls the worker job byte budget.
+
 ### What Your AI Agent Gets
 
 **16 tools** exposed via MCP (11 per-repo + 5 group):
@@ -320,29 +327,31 @@ flowchart TD
 
 ## Web UI (browser-based)
 
-A fully client-side graph explorer and AI chat. No server, no install — your code never leaves the browser.
+A client-side graph explorer and AI chat — your code never leaves your machine.
 
-**Try it now:** [gitnexus.vercel.app](https://gitnexus.vercel.app) — drag & drop a ZIP and start exploring.
+**Try it now:** [gitnexus.vercel.app](https://gitnexus.vercel.app) — run `npx gitnexus@latest serve` locally and the page auto-connects to your local backend.
 
 <img width="2550" height="1343" alt="gitnexus_img" src="https://github.com/user-attachments/assets/cc5d637d-e0e5-48e6-93ff-5bcfdb929285" />
 
-Or run locally:
+Or run the frontend locally:
 
 ```bash
 git clone https://github.com/abhigyanpatwari/gitnexus.git
 cd gitnexus/gitnexus-shared && npm install && npm run build
 cd ../gitnexus-web && npm install
 npm run dev
+# Then in another terminal, start the backend the frontend connects to:
+npx gitnexus@latest serve
 ```
 
 ## Docker
 
-The official Docker setup ships **two signed images** orchestrated by `docker-compose.yaml`:
+The official Docker setup ships **two signed images** orchestrated by `docker-compose.yaml`. Each image is published to both **GitHub Container Registry** (GHCR) and **Docker Hub** — same build, same digest, same Cosign signature — so pick whichever registry you prefer:
 
-| Image                                              | Purpose                                                                |
-| -------------------------------------------------- | ---------------------------------------------------------------------- |
-| `ghcr.io/abhigyanpatwari/gitnexus:latest`          | CLI / `gitnexus serve` backend (HTTP API on port `4747`, MCP, indexer) |
-| `ghcr.io/abhigyanpatwari/gitnexus-web:latest`      | Static web UI (port `4173`)                                            |
+| Purpose                                                                | GHCR (default in `docker-compose.yaml`)       | Docker Hub mirror                           |
+| ---------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------- |
+| CLI / `gitnexus serve` backend (HTTP API on port `4747`, MCP, indexer) | `ghcr.io/abhigyanpatwari/gitnexus:latest`     | `akonlabs/gitnexus:latest`                  |
+| Static web UI (port `4173`)                                            | `ghcr.io/abhigyanpatwari/gitnexus-web:latest` | `akonlabs/gitnexus-web:latest`              |
 
 > **Heads-up — image rename.** Earlier releases published the web UI under
 > `ghcr.io/abhigyanpatwari/gitnexus`. Starting with the introduction of the
@@ -400,11 +409,17 @@ docker compose --env-file .env up -d
 
 The Docker images are version-locked to the npm package:
 
-- Both images are **only published from `vX.Y.Z` git tags**, and the workflow
-  refuses to build unless the tag exactly matches `gitnexus/package.json`'s
-  version. So `ghcr.io/abhigyanpatwari/gitnexus:1.6.2` is byte-for-byte the
-  same release as `npm install gitnexus@1.6.2` — no drift, no floating
-  builds from `main`.
+- Stable images are **only published from `vX.Y.Z` git tags** (via `docker.yml`
+  triggered directly by the tag push), and the workflow refuses to build unless
+  the tag exactly matches `gitnexus/package.json`'s version. So
+  `ghcr.io/abhigyanpatwari/gitnexus:1.6.2` (and its Docker Hub mirror
+  `akonlabs/gitnexus:1.6.2`) is byte-for-byte the same release as
+  `npm install gitnexus@1.6.2` — no drift, no floating builds from `main`.
+  Both registries receive the same digest from a single build step, so you can
+  pull from either and the signature verifies identically.
+- Release-candidate images (e.g. `:1.7.0-rc.1`) are published alongside each
+  RC npm release. They are built by `release-candidate.yml` calling `docker.yml`
+  as a reusable workflow after the RC tag is created and pushed.
 - `:latest` is auto-promoted only from non-prerelease tags by the Docker
   metadata action, so it always points at a real, npm-published version.
 
@@ -416,15 +431,33 @@ typo-squatted registry), they cannot forge a Cosign signature tied to
 `abhigyanpatwari/GitNexus`'s `docker.yml`. Always verify before pulling into
 sensitive environments:
 
+**Stable releases** — signed from the `v*` tag ref:
+
 ```bash
 cosign verify ghcr.io/abhigyanpatwari/gitnexus:1.6.2 \
   --certificate-identity-regexp '^https://github\.com/abhigyanpatwari/GitNexus/\.github/workflows/docker\.yml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$' \
   --certificate-oidc-issuer https://token.actions.githubusercontent.com
+
+# Same signature verifies the Docker Hub mirror (identical digest):
+cosign verify docker.io/akonlabs/gitnexus:1.6.2 \
+  --certificate-identity-regexp '^https://github\.com/abhigyanpatwari/GitNexus/\.github/workflows/docker\.yml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$' \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com
 ```
 
 The regex pins the certificate identity to this repo's `docker.yml` workflow
 **run from a `v*` tag** — rejecting unsigned images, images signed by other
-workflows, and images signed from unprotected refs.
+workflows, and images signed from unprotected refs. It is identical for both
+registries because both sets of tags were signed at the same digest in one
+workflow run.
+
+**Release candidates** — signed from `refs/heads/main` (the caller's ref when
+`release-candidate.yml` invokes `docker.yml` as a reusable workflow):
+
+```bash
+cosign verify ghcr.io/abhigyanpatwari/gitnexus:1.7.0-rc.1 \
+  --certificate-identity 'https://github.com/abhigyanpatwari/GitNexus/.github/workflows/docker.yml@refs/heads/main' \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com
+```
 
 You can also inspect the build provenance and SBOM:
 

SECURITY.md

@@ -0,0 +1,67 @@
+# Security Policy
+
+## Supported Versions
+
+GitNexus is developed on `main`. Security fixes are applied to the latest released minor on npm (`gitnexus`) and to the published Docker images (`Dockerfile.cli`, `Dockerfile.web`). Older minors are not back-patched.
+
+## Reporting a Vulnerability
+
+**Please do not open a public GitHub issue for security reports.**
+
+Use **GitHub Private Vulnerability Reporting** for this repository:
+
+→ https://github.com/abhigyanpatwari/GitNexus/security/advisories/new
+
+Please include:
+
+- A description of the issue and its potential impact
+- Steps to reproduce (a minimal repro repo or commit hash if possible)
+- The affected version(s) — `npm view gitnexus version`, image digest, or commit SHA
+- Any suggested mitigation
+
+### What to expect
+
+- **Acknowledgement:** best-effort within 5 business days, subject to maintainer capacity.
+- **Triage:** we will confirm whether the report is in scope, request clarifications if needed, and propose a fix timeline.
+- **Disclosure:** coordinated. We will agree on a disclosure date with you before publishing an advisory.
+
+### Scope
+
+In scope:
+
+- The `gitnexus` CLI and MCP server (`gitnexus/`)
+- The `gitnexus-web` thin client (`gitnexus-web/`)
+- The `gitnexus-shared` types package (`gitnexus-shared/`)
+- The published Docker images (`Dockerfile.cli`, `Dockerfile.web`)
+- GitHub Actions workflows in `.github/workflows/`
+
+Out of scope:
+
+- Vulnerabilities in third-party dependencies that we have no influence over (please report upstream; if a viable mitigation exists at the GitNexus layer, that's in scope).
+- Issues requiring physical access to a developer machine or a compromised local environment.
+- Theoretical attacks without a practical exploit against a default GitNexus deployment.
+
+## Recommended Hardening for Forks and Self-Hosted Deployments
+
+If you fork GitNexus or self-host it, we recommend enabling the following in your repository's **Settings → Code security and analysis**:
+
+- **Private vulnerability reporting** — the channel described above.
+- **Dependabot alerts** — alerts on advisories affecting your dependencies.
+- **Dependabot security updates** — automated PRs for security patches (this repo's `.github/dependabot.yml` already covers version updates).
+- **Secret scanning** and **Push protection** — blocks pushes that introduce known secret patterns. Defense-in-depth on top of the in-CI Gitleaks scan documented below.
+- **Code scanning** — surfaces SARIF results from CodeQL, Trivy, Scorecard, and zizmor in one place.
+
+## Automated Scans Running in CI
+
+This repository runs the following scans automatically. Findings appear under the repository's **Security → Code scanning** tab.
+
+| Scan | Tool | Trigger | Action on finding |
+|------|------|---------|-------------------|
+| Static analysis (JS/TS, Python) | [CodeQL](https://github.com/github/codeql-action) | PR, `main` push, weekly | Advisory (Security tab) |
+| Dependency vulnerabilities (PR diff) | [`dependency-review-action`](https://github.com/actions/dependency-review-action) | PR | **Blocks PR** at `high+` severity |
+| Secret scanning | [Gitleaks](https://github.com/gitleaks/gitleaks-action) | PR, `main` push | **Blocks PR** on default rules |
+| Supply-chain posture | [OpenSSF Scorecard](https://github.com/ossf/scorecard-action) | Weekly, `main` push | Advisory (Security tab + public badge) |
+| Workflow lint | [zizmor](https://github.com/woodruffw/zizmor) | PR (touching `.github/**`) | **Blocks PR** at `high+` severity |
+| Container image scan | [Trivy](https://github.com/aquasecurity/trivy-action) | Weekly, `main` push | Advisory (Security tab) |
+
+Dependency version updates are managed separately by Dependabot — see `.github/dependabot.yml`.

deploy/kubernetes/cluster-image-policy.yaml

@@ -36,12 +36,24 @@ kind: ClusterImagePolicy
 metadata:
   name: gitnexus-signed-images
 spec:
-  # Apply to both published GitNexus images on GHCR. Image references always
-  # carry a tag or digest at admission time, so these two globs cover every
-  # `gitnexus:<tag>`, `gitnexus@sha256:...`, `gitnexus-web:<tag>`, and
-  # `gitnexus-web@sha256:...` reference.
+  # Apply to both published GitNexus images on both registries. Image
+  # references always carry a tag or digest at admission time, so these globs
+  # cover every `gitnexus:<tag>`, `gitnexus@sha256:...`, `gitnexus-web:<tag>`,
+  # and `gitnexus-web@sha256:...` reference on either GHCR or Docker Hub.
+  # The Docker Hub images are byte-for-byte mirrors of the GHCR images (same
+  # build, same digest, same Cosign signature), so the same keyless identity
+  # authority verifies both.
   images:
     - glob: 'ghcr.io/abhigyanpatwari/gitnexus*'
+    # Docker Hub references can appear in three forms at admission time
+    # (`docker.io/...`, `index.docker.io/...`, and bare `akonlabs/...` with
+    # the default registry implied). List all three so the policy cannot be
+    # sidestepped by the choice of registry prefix. The Docker Hub namespace
+    # is `akonlabs` rather than `abhigyanpatwari` because the Docker Hub org
+    # differs from the GitHub org.
+    - glob: 'docker.io/akonlabs/gitnexus*'
+    - glob: 'index.docker.io/akonlabs/gitnexus*'
+    - glob: 'akonlabs/gitnexus*'
   authorities:
     - name: gitnexus-cosign-keyless
       keyless:

docker-compose.yaml

@@ -19,7 +19,7 @@ services:
       - ${WORKSPACE_DIR:-./workspace}:/workspace:ro
     restart: unless-stopped
     healthcheck:
-      test: ['CMD', 'curl', '-fsS', 'http://localhost:4747/api/heartbeat']
+      test: ['CMD', 'curl', '-fsSI', 'http://localhost:4747/api/heartbeat']
       interval: 30s
       timeout: 5s
       retries: 3

docker-server.mjs

@@ -1,11 +1,11 @@
 import { createReadStream } from 'node:fs';
 import { stat } from 'node:fs/promises';
 import { createServer } from 'node:http';
-import { extname, join, normalize, sep } from 'node:path';
+import { extname, isAbsolute, normalize, relative, resolve } from 'node:path';
 
 const host = '0.0.0.0';
 const port = Number(process.env.PORT || '4173');
-const root = join(process.cwd(), 'dist');
+const root = resolve(process.cwd(), 'dist');
 
 const contentTypes = {
   '.css': 'text/css; charset=utf-8',
@@ -20,39 +20,78 @@ const contentTypes = {
   '.woff2': 'font/woff2',
 };
 
-function resolvePath(urlPath) {
+// Static asset server for the gitnexus-web Docker image.
+//
+// Path-injection containment: the request handler is intentionally a single
+// inline pipeline with no helper functions on the path-data flow. Each
+// filesystem sink (stat, createReadStream) is immediately preceded by the
+// canonical `path.relative` containment check that CodeQL's
+// `js/path-injection` query recognizes as a sanitizer barrier:
+//
+//     const rel = relative(root, candidate);
+//     if (rel.startsWith('..') || isAbsolute(rel)) reject;
+//     // candidate is now proven inside `root`
+//
+// Earlier iterations of this file used a helper (`resolveWithinRoot`) and a
+// `startsWith(root + sep)` check. Both were semantically correct but neither
+// was recognized by CodeQL: `startsWith(root + sep)` is not in the analyzer's
+// barrier-pattern set, and helper-based sanitization is not followed across
+// the request handler's reassignment paths in vanilla JS. The inline-at-sink
+// shape below is the documented analyzer-friendly idiom.
+const server = createServer(async (req, res) => {
+  const urlPath = req.url?.split('?')[0] || '/';
+
   let decoded;
   try {
     decoded = decodeURIComponent(urlPath);
   } catch {
-    return null;
+    res.writeHead(400);
+    res.end('Bad request');
+    return;
   }
-  if (decoded.includes('\0')) return null;
+  if (decoded.includes('\0')) {
+    res.writeHead(400);
+    res.end('Bad request');
+    return;
+  }
+
   const cleanPath = normalize(decoded.replace(/^\/+/, ''));
-  const candidate = join(root, cleanPath);
-  if (candidate !== root && !candidate.startsWith(root + sep)) return null;
-  return candidate;
-}
+  const initialPath = resolve(root, cleanPath);
 
-const server = createServer(async (req, res) => {
-  const requestPath = req.url?.split('?')[0] || '/';
-  let filePath = resolvePath(requestPath);
-
-  if (!filePath) {
+  // Sanitizer barrier #1 — guards the first stat() sink.
+  const initialRel = relative(root, initialPath);
+  if (initialRel.startsWith('..') || isAbsolute(initialRel)) {
     res.writeHead(400);
     res.end('Bad request');
     return;
   }
 
   try {
-    const fileStat = await stat(filePath).catch(() => null);
-    if (fileStat?.isDirectory()) {
-      filePath = join(filePath, 'index.html');
-    } else if (!fileStat?.isFile()) {
-      filePath = join(root, 'index.html');
+    const initialStat = await stat(initialPath).catch(() => null);
+
+    // Pick the path we actually serve. Note: any branch reassigns to a
+    // freshly-resolved path; the next sanitizer barrier re-validates.
+    let finalPath;
+    if (initialStat?.isDirectory()) {
+      finalPath = resolve(initialPath, 'index.html');
+    } else if (!initialStat?.isFile()) {
+      finalPath = resolve(root, 'index.html');
+    } else {
+      finalPath = initialPath;
     }
 
-    const finalStat = await stat(filePath).catch(() => null);
+    // Sanitizer barrier #2 — guards both the second stat() and the
+    // createReadStream() sinks. No reassignment of finalPath happens
+    // between this guard and either sink, so the analyzer can prove
+    // containment for both.
+    const finalRel = relative(root, finalPath);
+    if (finalRel.startsWith('..') || isAbsolute(finalRel)) {
+      res.writeHead(400);
+      res.end('Bad request');
+      return;
+    }
+
+    const finalStat = await stat(finalPath).catch(() => null);
     if (!finalStat?.isFile()) {
       res.writeHead(404);
       res.end('Not found');
@@ -60,14 +99,14 @@ const server = createServer(async (req, res) => {
     }
 
     res.writeHead(200, {
-      'Cache-Control': filePath.includes('/assets/')
+      'Cache-Control': finalPath.includes('/assets/')
         ? 'public, max-age=31536000, immutable'
         : 'no-cache',
-      'Content-Type': contentTypes[extname(filePath)] || 'application/octet-stream',
+      'Content-Type': contentTypes[extname(finalPath)] || 'application/octet-stream',
       'Cross-Origin-Opener-Policy': 'same-origin',
       'Cross-Origin-Embedder-Policy': 'require-corp',
     });
-    const stream = createReadStream(filePath);
+    const stream = createReadStream(finalPath);
     stream.on('error', () => res.destroy());
     stream.pipe(res);
   } catch (error) {

docker-server.test.mjs

@@ -100,6 +100,23 @@ it('rejects percent-encoded null bytes with 400', async () => {
   assert.equal(res.status, 400);
 });
 
+it('rejects percent-encoded path traversal with 400', async () => {
+  // %2e%2e%2f decodes to '../'. Without the path.relative inline barrier,
+  // a naive string check on the raw URL would let this through and only
+  // the lexical-decoded path.resolve would catch it. Confirm the barrier
+  // does its job after decodeURIComponent.
+  const res = await rawGet(serverPort, '/%2e%2e%2f%2e%2e%2fetc%2fpasswd');
+  assert.equal(res.status, 400);
+});
+
+it('rejects malformed percent-encoding with 400', async () => {
+  // %GG is not a valid percent-encoded sequence — decodeURIComponent throws.
+  // The handler's try/catch around decode must convert this to a 400 rather
+  // than an unhandled rejection.
+  const res = await rawGet(serverPort, '/foo%GGbar');
+  assert.equal(res.status, 400);
+});
+
 it('returns 404 when dist/index.html is missing', async () => {
   await unlink(join(tmpDir, 'dist', 'index.html'));
   const res = await rawGet(serverPort, '/nonexistent-page');

docs/guides/microservices-grpc.md

@@ -0,0 +1,300 @@
+# Using GitNexus across gRPC microservices
+
+## When to use this guide
+
+This guide is for teams whose product lives in **several separate Git repositories** — one per service — and whose services talk to each other over **gRPC** (possibly alongside HTTP and message topics). GitNexus indexes each repo independently, then a _group_ stitches the per-repo indexes into a single cross-repo view that the `impact`, `query`, and `context` tools can traverse. If your services live in one monorepo, much of this still applies — set each service as a member of a group and use the `service` prefix to scope queries — but the walkthrough assumes the harder multi-repo case.
+
+## Mental model
+
+- Each repository has its own `.gitnexus/` index (a LadybugDB graph of symbols, relationships, processes). `gitnexus analyze` in each repo produces that index completely independently.
+- A **group** is a higher-level construct stored at `~/.gitnexus/groups/<group>/` that references the per-repo indexes by their registry name.
+- Sync-time extractors walk each member repo and emit **contracts** — provider or consumer records keyed by a canonical `contractId` (`grpc::auth.AuthService/Login`, `http::GET::/orders`, etc.).
+- The sync step matches providers and consumers that share a `contractId` and writes **cross-links** to `<groupDir>/contracts.json`. Those cross-links are what lets `impact({repo: "@<group>", target: "X"})` hop from one repo into another.
+- Contracts come from three places: automatic contract extractors (`grpc-extractor`, `http-route-extractor`, `topic-extractor`), a manifest escape hatch (`config.links` in `group.yaml`), and — for same-name symbol matches where no contract is declared — the exact-match matching cascade in [`matching.ts`](../../gitnexus/src/core/group/matching.ts).
+- Each repo stays editable and re-indexable on its own. Re-run `gitnexus analyze` in a repo when it changes, then `gitnexus group sync <group>` to refresh `contracts.json`. `gitnexus group status` reports which members are stale.
+
+## Prerequisites
+
+- GitNexus installed and runnable as `gitnexus` or `npx gitnexus` (see the root [README.md](../../README.md)).
+- Each service repository checked out locally. No requirement that they share a parent directory — the group references them by registry name.
+- Write access to `~/.gitnexus/` (the default gitnexus home; see `getDefaultGitnexusDir` in [`storage.ts`](../../gitnexus/src/core/group/storage.ts)).
+
+## Step-by-step walkthrough
+
+The example uses three services — a TypeScript API gateway, a Go orders service, and a Python inventory service — with gRPC between them. The gateway is an `orders` consumer; the orders service is both an `orders` provider and an `inventory` consumer; the inventory service is an `inventory` provider.
+
+### 1. Index each repository
+
+Run `analyze` from inside each service repo (or pass the path). The CLI surface lives in [`gitnexus/src/cli/analyze.ts`](../../gitnexus/src/cli/analyze.ts) and is wired in [`gitnexus/src/cli/index.ts`](../../gitnexus/src/cli/index.ts).
+
+```bash
+cd ~/code/gateway && npx gitnexus analyze
+cd ~/code/orders  && npx gitnexus analyze
+cd ~/code/inventory && npx gitnexus analyze
+```
+
+Useful flags:
+
+- `--force` — reindex even if up to date.
+- `--embeddings` — generate embedding vectors (needed only if you want semantic search; the exact-match cross-repo cascade does **not** need them).
+- `--name <alias>` — register the repo under a specific alias when two repos share a basename (e.g. two `api/` folders).
+- `--skip-git` — index a checkout that isn't a git repo.
+
+Each run writes a `.gitnexus/` folder in the repo and registers the repo in `~/.gitnexus/registry.json`. Confirm with `npx gitnexus list`.
+
+### 2. Author `group.yaml`
+
+Create the group directory and edit the config. Either use the CLI scaffolder or write the file directly — both produce the same shape consumed by [`config-parser.ts`](../../gitnexus/src/core/group/config-parser.ts).
+
+```bash
+npx gitnexus group create payments-platform
+# or manually:
+mkdir -p ~/.gitnexus/groups/payments-platform
+$EDITOR   ~/.gitnexus/groups/payments-platform/group.yaml
+```
+
+Minimal working `group.yaml`:
+
+```yaml
+version: 1
+name: payments-platform
+description: Gateway + orders + inventory (gRPC)
+
+repos:
+  gateway: gateway
+  orders: orders
+  inventory: inventory
+
+# Only add explicit links when the automatic extractors miss something —
+# see "When automatic extraction isn't enough" below.
+links: []
+
+packages: {}
+
+detect:
+  http: true
+  grpc: true
+  topics: true
+  shared_libs: true
+  embedding_fallback: false
+
+matching:
+  bm25_threshold: 0.7
+  embedding_threshold: 0.65
+  max_candidates_per_step: 3
+  # Exclude noisy paths from cross-link matching (contracts are still extracted)
+  exclude_links_paths: [/ping, /health, /healthcheck]
+  exclude_links_param_only_paths: true
+```
+
+Field notes (schema in [`types.ts`](../../gitnexus/src/core/group/types.ts)):
+
+- `version` — must be `1`. The parser rejects anything else.
+- `name` — required; used for the group directory name and all CLI / MCP calls.
+- `repos` — a mapping from **group path** (a logical name you choose; can be a hierarchy like `backend/orders`) to **registry name** (the name shown by `npx gitnexus list`). Both sides appear throughout the tooling: contract rows use the group path; `@<group>/<groupPath>` routes tools to a single member.
+- `links` — optional manifest escape hatch, one entry per explicit cross-repo contract. Validated by the parser: `from` and `to` must be known repo paths, `type` must be one of `http | grpc | topic | lib | custom`, and `role` must be `provider | consumer`.
+- `detect` — toggles per extractor family. Defaults (set in `config-parser.ts`) turn `http`, `grpc`, `topics`, and `shared_libs` on; disable the ones you don't use to speed up sync.
+- `matching` — thresholds for the matching cascade. The exact match is always run; other strategies depend on indexer state. Two optional fields reduce false-positive cross-links in large groups:
+  - `exclude_links_paths` — list of HTTP paths to exclude from cross-link matching (default `[]`). Contracts at these paths are still extracted and visible in the registry, but they don't produce cross-repo links. Useful for health-check endpoints (`/ping`, `/health`) that every service exposes. Trailing slashes are normalized.
+  - `exclude_links_param_only_paths` — when `true`, exclude routes where every segment is `{param}` (e.g. `/{param}`, `/{param}/{param}`) from cross-link matching (default `false`). Mixed routes like `/users/{param}` are not affected.
+
+### 3. Sync the group
+
+```bash
+npx gitnexus group sync payments-platform --verbose
+```
+
+What this does (see [`sync.ts`](../../gitnexus/src/core/group/sync.ts)):
+
+1. Opens each member's per-repo LadybugDB.
+2. Runs the HTTP, gRPC, and topic extractors against the source files.
+3. Applies manifest `links` through [`manifest-extractor.ts`](../../gitnexus/src/core/group/extractors/manifest-extractor.ts).
+4. Runs the exact-match cascade, joining providers and consumers that share a normalized `contractId`.
+5. Writes `contracts.json` in the group directory.
+
+Flags:
+
+- `--exact-only` — stop after the exact cascade; skip BM25 and embedding fallback.
+- `--skip-embeddings` — run exact plus BM25 but not embedding-based matching.
+- `--allow-stale` — don't warn if a member's index is stale.
+- `--json` — machine-readable output.
+
+The same operation is available over MCP as `group_sync({ name: "payments-platform" })` — see [`tools.ts`](../../gitnexus/src/mcp/tools.ts).
+
+### 4. Inspect the registry
+
+Use `gitnexus group contracts` for the CLI view or read the `gitnexus://group/<name>/contracts` MCP resource for the same data.
+
+```bash
+npx gitnexus group contracts payments-platform --type grpc --json
+```
+
+A shortened response:
+
+```json
+{
+  "contracts": [
+    {
+      "contractId": "grpc::orders.OrderService/PlaceOrder",
+      "type": "grpc",
+      "role": "provider",
+      "repo": "orders",
+      "symbolRef": { "filePath": "internal/grpc/order_server.go", "name": "RegisterOrderServiceServer" },
+      "confidence": 0.8,
+      "meta": { "service": "OrderService", "method": "PlaceOrder", "source": "go_register" }
+    },
+    {
+      "contractId": "grpc::orders.OrderService/PlaceOrder",
+      "type": "grpc",
+      "role": "consumer",
+      "repo": "gateway",
+      "symbolRef": { "filePath": "src/clients/orders.ts", "name": "OrderServiceClient" },
+      "confidence": 0.75,
+      "meta": { "service": "OrderService", "source": "ts_generated_client" }
+    }
+  ],
+  "crossLinks": [
+    {
+      "from": { "repo": "gateway", "symbolUid": "…", "symbolRef": { "filePath": "src/clients/orders.ts", "name": "OrderServiceClient" } },
+      "to":   { "repo": "orders",  "symbolUid": "…", "symbolRef": { "filePath": "internal/grpc/order_server.go", "name": "RegisterOrderServiceServer" } },
+      "type": "grpc",
+      "contractId": "grpc::orders.OrderService/PlaceOrder",
+      "matchType": "exact",
+      "confidence": 1.0
+    }
+  ]
+}
+```
+
+Staleness of the underlying indexes shows up in `npx gitnexus group status payments-platform` or the `gitnexus://group/<name>/status` resource.
+
+### 5. Run cross-repo impact with `@<group>` routing
+
+From any shell (you do **not** have to `cd` into a member repo), the normal `impact` / `query` / `context` tools accept `repo: "@<group>"` to fan out across all members, or `repo: "@<group>/<memberPath>"` to target one member. Routing is implemented in [`resolve-at-member.ts`](../../gitnexus/src/core/group/resolve-at-member.ts) and described in [`tools.ts`](../../gitnexus/src/mcp/tools.ts).
+
+Example MCP calls:
+
+```json
+{"tool": "impact", "arguments": {
+  "repo": "@payments-platform/orders",
+  "target": "PlaceOrder",
+  "direction": "upstream",
+  "crossDepth": 2
+}}
+```
+
+```json
+{"tool": "query", "arguments": {
+  "repo": "@payments-platform",
+  "query": "retry logic around PlaceOrder"
+}}
+```
+
+The CLI equivalents still exist for scripting:
+
+```bash
+npx gitnexus group impact payments-platform \
+  --repo orders --target PlaceOrder --direction upstream --cross-depth 2
+```
+
+Phase 1 walks within the anchor member; Phase 2 hops across the Contract Bridge wherever a cross-link endpoint matches an impacted symbol. See [`cross-impact.ts`](../../gitnexus/src/core/group/cross-impact.ts) for the bridge query.
+
+## How gRPC extraction works
+
+`GrpcExtractor` ([`grpc-extractor.ts`](../../gitnexus/src/core/group/extractors/grpc-extractor.ts)) runs two passes per member repo:
+
+1. **Proto map.** Every `**/*.proto` file is parsed to enumerate `service Foo { rpc Bar(...) }` blocks and (transitively) resolve the package name. Each RPC method becomes a provider contract with `contractId = grpc::<package>.<Service>/<Method>` and `confidence = 0.85`. Parsing uses the vendored `tree-sitter-proto` grammar when available and falls back to a length-preserving manual parser (`extractServiceBlocks`) otherwise, so `.proto` extraction works on platforms where the grammar fails to build.
+2. **Source scan.** Every source file whose extension matches [`GRPC_SCAN_GLOB`](../../gitnexus/src/core/group/extractors/grpc-patterns/index.ts) is parsed by its language plugin:
+
+| Language | Provider signal | Consumer signal |
+|----------|-----------------|-----------------|
+| Go ([`go.ts`](../../gitnexus/src/core/group/extractors/grpc-patterns/go.ts)) | `pb.RegisterXxxServer(...)`, `pb.UnimplementedXxxServer` embedded in struct | `pb.NewXxxClient(conn)` |
+| Java ([`java.ts`](../../gitnexus/src/core/group/extractors/grpc-patterns/java.ts)) | `extends XxxServiceGrpc.XxxServiceImplBase` (with or without `@GrpcService`) | `XxxServiceGrpc.newBlockingStub(...)`, `newStub(...)` |
+| Python ([`python.ts`](../../gitnexus/src/core/group/extractors/grpc-patterns/python.ts)) | `add_XxxServicer_to_server(...)` (bare or `_pb2_grpc.` attribute form) | `XxxStub(channel)` (ignores `Mock`/`Test`/`Fake`/`Stub`) |
+| Node / TS ([`node.ts`](../../gitnexus/src/core/group/extractors/grpc-patterns/node.ts)) | NestJS `@GrpcMethod('Service','Method')` | `@GrpcClient` field typed `XxxServiceClient`, `client.getService<X>('Service')`, `new XxxServiceClient(...)`, `new foo.bar.XxxService(...)` in files that call `loadPackageDefinition` |
+
+For each source-scan detection the extractor looks up the short service name in the proto map and picks:
+
+- `grpc::<package>.<Service>/<Method>` when a method is named and the service resolves against the proto map,
+- `grpc::<package>.<Service>/*` (wildcard) when only the service is known, or
+- `grpc::<ServiceName>/*` when no `.proto` is available at all.
+
+Provider detections land at confidence 0.8 (with proto) or 0.65 (without); consumers at 0.75 or 0.55. NestJS `@GrpcMethod` is fixed at 0.8 because the decorator is self-describing.
+
+### Matching
+
+`matching.ts` lowercases the package/service segment before comparing contract ids, so bindings that capitalize names differently (`auth.AuthService` vs `auth.authservice`) still match. Method names are compared case-sensitively because gRPC's wire path is case-sensitive. Service-only wildcards (`grpc::pkg.Svc/*`) match any method on the same service during cross-linking.
+
+### Known limitations
+
+- **Ambiguous proto resolution.** If a short service name exists in more than one `.proto` file and the source-scan hit can't be narrowed down by shared directory segments (`resolveProtoConflict` refuses to guess), the extractor skips contract emission and logs a warning.
+- **Proto packages must be resolvable locally.** Transitive imports that point outside the repo produce an empty package segment, which means the contract id collapses to `grpc::<Service>/<Method>`. Cross-repo matches still work as long as both sides agree on the empty package.
+- **Rewrite rules are not implemented.** If the provider repo writes `grpc::orders.OrderService/PlaceOrder` and the consumer repo writes `grpc::orderspb.OrderService/PlaceOrder`, they won't cross-link automatically. Use `config.links` to declare the correspondence (see below).
+- **One sync = one snapshot.** Contracts are extracted against the indexed snapshot of each repo. Re-index first, then re-sync; the `status` command and resource surface staleness.
+
+## When automatic extraction isn't enough
+
+The escape hatch is the `links` list in `group.yaml`, handled by [`ManifestExtractor`](../../gitnexus/src/core/group/extractors/manifest-extractor.ts). Each entry is a **one-directional** provider/consumer declaration:
+
+```yaml
+version: 1
+name: payments-platform
+repos:
+  gateway: gateway
+  orders: orders
+  inventory: inventory
+
+links:
+  # Explicit gRPC method: use when naming mismatches stop the
+  # automatic matcher from cross-linking.
+  - from: gateway
+    to: orders
+    type: grpc
+    contract: OrderService/PlaceOrder
+    role: consumer
+
+  # Service-level link when you don't want to enumerate methods.
+  - from: orders
+    to: inventory
+    type: grpc
+    contract: InventoryService
+    role: consumer
+
+  # Works for HTTP too — use `METHOD::/path` form for the exact
+  # handler, or just `/path` for a method-agnostic wildcard.
+  - from: gateway
+    to: orders
+    type: http
+    contract: POST::/orders
+    role: consumer
+```
+
+What the manifest extractor does (see [`manifest-extractor.ts`](../../gitnexus/src/core/group/extractors/manifest-extractor.ts)):
+
+1. Builds a canonical `contractId` with `buildContractId` — the same canonicalization used by the automatic extractors, so manifest links cross-match automatic contracts on the other side.
+2. Tries to resolve each side to a real graph symbol (the `Route` node for HTTP, a `Function|Method` / `Class|Interface` for gRPC, a `Package|Module` for `lib`).
+3. If resolution fails, falls back to a deterministic synthetic uid (`manifest::<repo>::<contractId>`) so both sides still line up in cross-impact — name-only links still work when the symbol isn't in the graph.
+4. Emits both a provider and a consumer `StoredContract` (confidence `1.0`, `source: "manifest"`) and a `CrossLink` with `matchType: "manifest"`.
+
+Use `links` for exactly the cases the extractor can't infer: different package names across repos (see #701), hand-rolled transports, cases where the provider repo isn't checked out locally but you still want a record, or any contract whose provider and consumer simply don't share a surface the extractors know how to pattern-match.
+
+History: the manifest extractor used to be silently skipped by the sync pipeline; that was fixed in [#827](https://github.com/abhigyanpatwari/GitNexus/pull/827) (tracking issue #826). If you ever see `config.links` with zero cross-links in `contracts.json`, make sure you're on a build that includes that fix, then re-run `group sync`.
+
+## Troubleshooting
+
+1. **`contracts.json` is empty after a sync.** Either no member repo contained a recognizable gRPC pattern, or the extractors are disabled in `detect`. Confirm `detect.grpc: true` and re-run with `--verbose`.
+2. **A known provider/consumer pair doesn't cross-link.** Most common cause: the package segment differs. Check the raw contract ids with `gitnexus group contracts <name> --unmatched` — if you see two same-method contracts with different package prefixes, add a manifest `links:` entry to bridge them (no automatic rewrite rules yet).
+3. **`matchType: "manifest"` is missing entirely.** The extractor needs `config.links` to be non-empty and the sync pipeline to actually call it — verify you're on a post-#827 build. Empty contract rows for manifest links usually mean `resolveSymbol` couldn't find a graph match; the synthetic uid still lets cross-impact work, it just won't carry a file path.
+4. **Ambiguous proto warnings.** Look for `[grpc-extractor] Ambiguous proto resolution` in the sync logs; that means a service name exists in multiple `.proto` files under the same repo and the path-distance heuristic couldn't pick a winner. Resolve by renaming the service or declaring the intended pairing in `config.links`.
+5. **Cross-impact says "stale".** Both sides need a fresh per-repo index _and_ a fresh group sync. Order matters: `gitnexus analyze` in each changed repo, then `gitnexus group sync <name>`. Use `gitnexus group status <name>` to see which side is behind.
+
+## Related docs and references
+
+- [AGENTS.md](../../AGENTS.md) — authoritative list of MCP tools and resources, including group-mode routing and the `gitnexus://group/…` resources.
+- [ARCHITECTURE.md](../../ARCHITECTURE.md) — overall data flow and the call-resolution DAG that the per-repo indexer uses.
+- [`gitnexus/src/core/group/`](../../gitnexus/src/core/group/) — `service.ts`, `sync.ts`, `config-parser.ts`, `matching.ts`.
+- [`gitnexus/src/core/group/extractors/grpc-extractor.ts`](../../gitnexus/src/core/group/extractors/grpc-extractor.ts) and [`grpc-patterns/`](../../gitnexus/src/core/group/extractors/grpc-patterns/) — gRPC detection.
+- [`gitnexus/src/core/group/extractors/manifest-extractor.ts`](../../gitnexus/src/core/group/extractors/manifest-extractor.ts) — the `config.links` escape hatch.
+- [`gitnexus/src/mcp/tools.ts`](../../gitnexus/src/mcp/tools.ts) — MCP tool schemas (`group_list`, `group_sync`, plus `@<group>` routing on `impact` / `query` / `context`).
+- [`gitnexus/src/cli/group.ts`](../../gitnexus/src/cli/group.ts) — CLI command definitions and flags.
+- Upstream issues: [#701](https://github.com/abhigyanpatwari/GitNexus/issues/701), [#826](https://github.com/abhigyanpatwari/GitNexus/issues/826), [#906](https://github.com/abhigyanpatwari/GitNexus/issues/906).

eslint.config.mjs

@@ -14,6 +14,7 @@ export default [
       'gitnexus/vendor/**',
       'gitnexus-web/src/vendor/**',
       'gitnexus/test/fixtures/**',
+      'gitnexus-web/test/fixtures/**',
       'gitnexus-web/playwright-report/**',
       'gitnexus-web/test-results/**',
       '**/*.d.ts',

eval/bridge/mcp_bridge.py

@@ -53,13 +53,13 @@ class MCPBridge:
 
         try:
             # Find gitnexus binary
-            gitnexus_bin = self._find_gitnexus()
-            if not gitnexus_bin:
+            gitnexus_cmd = self._find_gitnexus_command()
+            if not gitnexus_cmd:
                 logger.error("GitNexus not found. Install with: npm install -g gitnexus")
                 return False
 
             self.process = subprocess.Popen(
-                [gitnexus_bin, "mcp"],
+                [*gitnexus_cmd, "mcp"],
                 stdin=subprocess.PIPE,
                 stdout=subprocess.PIPE,
                 stderr=subprocess.PIPE,
@@ -152,33 +152,34 @@ class MCPBridge:
                 return contents[0].get("text", "")
         return None
 
-    def _find_gitnexus(self) -> str | None:
-        """Find the gitnexus CLI binary."""
+    def _find_gitnexus_command(self) -> list[str] | None:
+        """Find the gitnexus CLI command prefix."""
         # Check if npx is available (preferred - uses local install)
-        for cmd in ["npx"]:
-            try:
-                result = subprocess.run(
-                    [cmd, "gitnexus", "--version"],
-                    capture_output=True,
-                    text=True,
-                    timeout=MCP_FIND_GITNEXUS_TIMEOUT_SECONDS,
-                    cwd=self.repo_path,
-                )
-                if result.returncode == 0:
-                    return cmd  # Will use "npx gitnexus mcp"
-            except Exception:
-                continue
+        try:
+            result = subprocess.run(
+                ["npx", "gitnexus", "--version"],
+                stdin=subprocess.DEVNULL,
+                capture_output=True,
+                text=True,
+                timeout=MCP_FIND_GITNEXUS_TIMEOUT_SECONDS,
+                cwd=self.repo_path,
+            )
+            if result.returncode == 0:
+                return ["npx", "gitnexus"]
+        except Exception:
+            pass
 
         # Check for global install
         try:
             result = subprocess.run(
                 ["gitnexus", "--version"],
+                stdin=subprocess.DEVNULL,
                 capture_output=True,
                 text=True,
                 timeout=MCP_FIND_GITNEXUS_FALLBACK_TIMEOUT_SECONDS,
             )
             if result.returncode == 0:
-                return "gitnexus"
+                return ["gitnexus"]
         except Exception:
             pass
 

eval/pyproject.toml

@@ -6,19 +6,19 @@ readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [
     "mini-swe-agent>=2.0.0",
-    "litellm>=1.50.0,!=1.82.7,!=1.82.8",
+    "litellm!=1.82.7,!=1.82.8,>=1.83.7",
     "datasets>=3.0.0",
     "typer>=0.12.0",
     "rich>=13.0.0",
     "pyyaml>=6.0",
     "pandas>=2.0.0",
     "tabulate>=0.9.0",
-    "python-dotenv>=1.0.0",
+    "python-dotenv>=1.2.2",
 ]
 
 [project.optional-dependencies]
 dev = [
-    "pytest>=8.0.0",
+    "pytest>=9.0.3",
     "ruff>=0.5.0",
     "hypothesis>=6.88.0",
     "coverage>=7.6.0",

eval/tests/test_mcp_bridge.py

@@ -0,0 +1,170 @@
+"""Tests for MCPBridge._find_gitnexus_command() and subprocess spawn."""
+import subprocess
+import unittest
+from unittest.mock import MagicMock, call, patch
+
+
+class TestFindGitnexusCommand(unittest.TestCase):
+    """Verify _find_gitnexus_command() returns the correct command prefix."""
+
+    def _make_bridge(self):
+        from bridge.mcp_bridge import MCPBridge
+        return MCPBridge(repo_path="/fake/repo")
+
+    def _success(self):
+        r = MagicMock()
+        r.returncode = 0
+        return r
+
+    def _failure(self):
+        r = MagicMock()
+        r.returncode = 1
+        return r
+
+    def test_npx_path_returns_npx_gitnexus(self):
+        """When npx probe succeeds, command prefix is ['npx', 'gitnexus']."""
+        with patch("subprocess.run", return_value=self._success()) as mock_run:
+            bridge = self._make_bridge()
+            result = bridge._find_gitnexus_command()
+
+        self.assertEqual(result, ["npx", "gitnexus"])
+        mock_run.assert_called_once()
+        args = mock_run.call_args[0][0]
+        self.assertEqual(args, ["npx", "gitnexus", "--version"])
+
+    def test_global_path_returns_gitnexus(self):
+        """When npx probe fails but global install exists, prefix is ['gitnexus']."""
+        with patch("subprocess.run", side_effect=[self._failure(), self._success()]) as mock_run:
+            bridge = self._make_bridge()
+            result = bridge._find_gitnexus_command()
+
+        self.assertEqual(result, ["gitnexus"])
+        self.assertEqual(mock_run.call_count, 2)
+
+    def test_both_fail_returns_none(self):
+        """When both probes fail, returns None."""
+        with patch("subprocess.run", return_value=self._failure()):
+            bridge = self._make_bridge()
+            result = bridge._find_gitnexus_command()
+
+        self.assertIsNone(result)
+
+    def test_npx_exception_falls_back_to_global(self):
+        """When npx raises (not installed), falls back to global probe."""
+        with patch("subprocess.run", side_effect=[FileNotFoundError, self._success()]):
+            bridge = self._make_bridge()
+            result = bridge._find_gitnexus_command()
+
+        self.assertEqual(result, ["gitnexus"])
+
+    def test_both_raise_returns_none(self):
+        """When both probes raise exceptions, returns None."""
+        with patch("subprocess.run", side_effect=FileNotFoundError):
+            bridge = self._make_bridge()
+            result = bridge._find_gitnexus_command()
+
+        self.assertIsNone(result)
+
+    def test_stdin_devnull_on_npx_probe(self):
+        """npx probe must pass stdin=DEVNULL to prevent interactive blocking."""
+        with patch("subprocess.run", return_value=self._success()) as mock_run:
+            bridge = self._make_bridge()
+            bridge._find_gitnexus_command()
+
+        kwargs = mock_run.call_args[1]
+        self.assertEqual(kwargs.get("stdin"), subprocess.DEVNULL)
+
+    def test_stdin_devnull_on_global_probe(self):
+        """global probe must pass stdin=DEVNULL to prevent interactive blocking."""
+        with patch("subprocess.run", side_effect=[self._failure(), self._success()]) as mock_run:
+            bridge = self._make_bridge()
+            bridge._find_gitnexus_command()
+
+        global_call_kwargs = mock_run.call_args_list[1][1]
+        self.assertEqual(global_call_kwargs.get("stdin"), subprocess.DEVNULL)
+
+
+class TestStartSpawnCommand(unittest.TestCase):
+    """Verify start() spawns Popen with the correct argv."""
+
+    def _make_bridge(self):
+        from bridge.mcp_bridge import MCPBridge
+        return MCPBridge(repo_path="/fake/repo")
+
+    def test_npx_path_spawns_npx_gitnexus_mcp(self):
+        """When npx path found, Popen must receive ['npx', 'gitnexus', 'mcp']."""
+        bridge = self._make_bridge()
+
+        with patch.object(bridge, "_find_gitnexus_command", return_value=["npx", "gitnexus"]), \
+             patch("subprocess.Popen") as mock_popen, \
+             patch.object(bridge, "_send_request", return_value={"protocolVersion": "2024-11-05"}), \
+             patch.object(bridge, "_send_notification"):
+
+            mock_proc = MagicMock()
+            mock_proc.stdin = MagicMock()
+            mock_proc.stdout = MagicMock()
+            mock_proc.stderr = MagicMock()
+            mock_popen.return_value = mock_proc
+
+            bridge.start()
+
+        mock_popen.assert_called_once()
+        argv = mock_popen.call_args[0][0]
+        self.assertEqual(argv, ["npx", "gitnexus", "mcp"])
+
+    def test_global_path_spawns_gitnexus_mcp(self):
+        """When global path found, Popen must receive ['gitnexus', 'mcp']."""
+        bridge = self._make_bridge()
+
+        with patch.object(bridge, "_find_gitnexus_command", return_value=["gitnexus"]), \
+             patch("subprocess.Popen") as mock_popen, \
+             patch.object(bridge, "_send_request", return_value={"protocolVersion": "2024-11-05"}), \
+             patch.object(bridge, "_send_notification"):
+
+            mock_proc = MagicMock()
+            mock_proc.stdin = MagicMock()
+            mock_proc.stdout = MagicMock()
+            mock_proc.stderr = MagicMock()
+            mock_popen.return_value = mock_proc
+
+            bridge.start()
+
+        mock_popen.assert_called_once()
+        argv = mock_popen.call_args[0][0]
+        self.assertEqual(argv, ["gitnexus", "mcp"])
+
+    def test_no_shell_true(self):
+        """Popen must never be called with shell=True."""
+        bridge = self._make_bridge()
+
+        with patch.object(bridge, "_find_gitnexus_command", return_value=["npx", "gitnexus"]), \
+             patch("subprocess.Popen") as mock_popen, \
+             patch.object(bridge, "_send_request", return_value={"protocolVersion": "2024-11-05"}), \
+             patch.object(bridge, "_send_notification"):
+
+            mock_proc = MagicMock()
+            mock_proc.stdin = MagicMock()
+            mock_proc.stdout = MagicMock()
+            mock_proc.stderr = MagicMock()
+            mock_popen.return_value = mock_proc
+
+            bridge.start()
+
+        kwargs = mock_popen.call_args[1]
+        self.assertNotEqual(kwargs.get("shell"), True)
+
+    def test_gitnexus_not_found_returns_false(self):
+        """start() returns False and does not call Popen when gitnexus not found."""
+        bridge = self._make_bridge()
+
+        with patch.object(bridge, "_find_gitnexus_command", return_value=None), \
+             patch("subprocess.Popen") as mock_popen:
+
+            result = bridge.start()
+
+        self.assertFalse(result)
+        mock_popen.assert_not_called()
+
+
+if __name__ == "__main__":
+    unittest.main()

eval/uv.lock

@@ -21,7 +21,7 @@ wheels = [
 
 [[package]]
 name = "aiohttp"
-version = "3.13.3"
+version = "3.13.4"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "aiohappyeyeballs" },
@@ -32,93 +32,93 @@ dependencies = [
     { name = "propcache" },
     { name = "yarl" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/50/42/32cf8e7704ceb4481406eb87161349abb46a57fee3f008ba9cb610968646/aiohttp-3.13.3.tar.gz", hash = "sha256:a949eee43d3782f2daae4f4a2819b2cb9b0c5d3b7f7a927067cc84dafdbb9f88", size = 7844556, upload-time = "2026-01-03T17:33:05.204Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/45/4a/064321452809dae953c1ed6e017504e72551a26b6f5708a5a80e4bf556ff/aiohttp-3.13.4.tar.gz", hash = "sha256:d97a6d09c66087890c2ab5d49069e1e570583f7ac0314ecf98294c1b6aaebd38", size = 7859748, upload-time = "2026-03-28T17:19:40.6Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/f1/4c/a164164834f03924d9a29dc3acd9e7ee58f95857e0b467f6d04298594ebb/aiohttp-3.13.3-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:5b6073099fb654e0a068ae678b10feff95c5cae95bbfcbfa7af669d361a8aa6b", size = 746051, upload-time = "2026-01-03T17:29:43.287Z" },
-    { url = "https://files.pythonhosted.org/packages/82/71/d5c31390d18d4f58115037c432b7e0348c60f6f53b727cad33172144a112/aiohttp-3.13.3-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:1cb93e166e6c28716c8c6aeb5f99dfb6d5ccf482d29fe9bf9a794110e6d0ab64", size = 499234, upload-time = "2026-01-03T17:29:44.822Z" },
-    { url = "https://files.pythonhosted.org/packages/0e/c9/741f8ac91e14b1d2e7100690425a5b2b919a87a5075406582991fb7de920/aiohttp-3.13.3-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:28e027cf2f6b641693a09f631759b4d9ce9165099d2b5d92af9bd4e197690eea", size = 494979, upload-time = "2026-01-03T17:29:46.405Z" },
-    { url = "https://files.pythonhosted.org/packages/75/b5/31d4d2e802dfd59f74ed47eba48869c1c21552c586d5e81a9d0d5c2ad640/aiohttp-3.13.3-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:3b61b7169ababd7802f9568ed96142616a9118dd2be0d1866e920e77ec8fa92a", size = 1748297, upload-time = "2026-01-03T17:29:48.083Z" },
-    { url = "https://files.pythonhosted.org/packages/1a/3e/eefad0ad42959f226bb79664826883f2687d602a9ae2941a18e0484a74d3/aiohttp-3.13.3-cp311-cp311-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:80dd4c21b0f6237676449c6baaa1039abae86b91636b6c91a7f8e61c87f89540", size = 1707172, upload-time = "2026-01-03T17:29:49.648Z" },
-    { url = "https://files.pythonhosted.org/packages/c5/3a/54a64299fac2891c346cdcf2aa6803f994a2e4beeaf2e5a09dcc54acc842/aiohttp-3.13.3-cp311-cp311-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:65d2ccb7eabee90ce0503c17716fc77226be026dcc3e65cce859a30db715025b", size = 1805405, upload-time = "2026-01-03T17:29:51.244Z" },
-    { url = "https://files.pythonhosted.org/packages/6c/70/ddc1b7169cf64075e864f64595a14b147a895a868394a48f6a8031979038/aiohttp-3.13.3-cp311-cp311-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:5b179331a481cb5529fca8b432d8d3c7001cb217513c94cd72d668d1248688a3", size = 1899449, upload-time = "2026-01-03T17:29:53.938Z" },
-    { url = "https://files.pythonhosted.org/packages/a1/7e/6815aab7d3a56610891c76ef79095677b8b5be6646aaf00f69b221765021/aiohttp-3.13.3-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:9d4c940f02f49483b18b079d1c27ab948721852b281f8b015c058100e9421dd1", size = 1748444, upload-time = "2026-01-03T17:29:55.484Z" },
-    { url = "https://files.pythonhosted.org/packages/6b/f2/073b145c4100da5511f457dc0f7558e99b2987cf72600d42b559db856fbc/aiohttp-3.13.3-cp311-cp311-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:f9444f105664c4ce47a2a7171a2418bce5b7bae45fb610f4e2c36045d85911d3", size = 1606038, upload-time = "2026-01-03T17:29:57.179Z" },
-    { url = "https://files.pythonhosted.org/packages/0a/c1/778d011920cae03ae01424ec202c513dc69243cf2db303965615b81deeea/aiohttp-3.13.3-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:694976222c711d1d00ba131904beb60534f93966562f64440d0c9d41b8cdb440", size = 1724156, upload-time = "2026-01-03T17:29:58.914Z" },
-    { url = "https://files.pythonhosted.org/packages/0e/cb/3419eabf4ec1e9ec6f242c32b689248365a1cf621891f6f0386632525494/aiohttp-3.13.3-cp311-cp311-musllinux_1_2_armv7l.whl", hash = "sha256:f33ed1a2bf1997a36661874b017f5c4b760f41266341af36febaf271d179f6d7", size = 1722340, upload-time = "2026-01-03T17:30:01.962Z" },
-    { url = "https://files.pythonhosted.org/packages/7a/e5/76cf77bdbc435bf233c1f114edad39ed4177ccbfab7c329482b179cff4f4/aiohttp-3.13.3-cp311-cp311-musllinux_1_2_ppc64le.whl", hash = "sha256:e636b3c5f61da31a92bf0d91da83e58fdfa96f178ba682f11d24f31944cdd28c", size = 1783041, upload-time = "2026-01-03T17:30:03.609Z" },
-    { url = "https://files.pythonhosted.org/packages/9d/d4/dd1ca234c794fd29c057ce8c0566b8ef7fd6a51069de5f06fa84b9a1971c/aiohttp-3.13.3-cp311-cp311-musllinux_1_2_riscv64.whl", hash = "sha256:5d2d94f1f5fcbe40838ac51a6ab5704a6f9ea42e72ceda48de5e6b898521da51", size = 1596024, upload-time = "2026-01-03T17:30:05.132Z" },
-    { url = "https://files.pythonhosted.org/packages/55/58/4345b5f26661a6180afa686c473620c30a66afdf120ed3dd545bbc809e85/aiohttp-3.13.3-cp311-cp311-musllinux_1_2_s390x.whl", hash = "sha256:2be0e9ccf23e8a94f6f0650ce06042cefc6ac703d0d7ab6c7a917289f2539ad4", size = 1804590, upload-time = "2026-01-03T17:30:07.135Z" },
-    { url = "https://files.pythonhosted.org/packages/7b/06/05950619af6c2df7e0a431d889ba2813c9f0129cec76f663e547a5ad56f2/aiohttp-3.13.3-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:9af5e68ee47d6534d36791bbe9b646d2a7c7deb6fc24d7943628edfbb3581f29", size = 1740355, upload-time = "2026-01-03T17:30:09.083Z" },
-    { url = "https://files.pythonhosted.org/packages/3e/80/958f16de79ba0422d7c1e284b2abd0c84bc03394fbe631d0a39ffa10e1eb/aiohttp-3.13.3-cp311-cp311-win32.whl", hash = "sha256:a2212ad43c0833a873d0fb3c63fa1bacedd4cf6af2fee62bf4b739ceec3ab239", size = 433701, upload-time = "2026-01-03T17:30:10.869Z" },
-    { url = "https://files.pythonhosted.org/packages/dc/f2/27cdf04c9851712d6c1b99df6821a6623c3c9e55956d4b1e318c337b5a48/aiohttp-3.13.3-cp311-cp311-win_amd64.whl", hash = "sha256:642f752c3eb117b105acbd87e2c143de710987e09860d674e068c4c2c441034f", size = 457678, upload-time = "2026-01-03T17:30:12.719Z" },
-    { url = "https://files.pythonhosted.org/packages/a0/be/4fc11f202955a69e0db803a12a062b8379c970c7c84f4882b6da17337cc1/aiohttp-3.13.3-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:b903a4dfee7d347e2d87697d0713be59e0b87925be030c9178c5faa58ea58d5c", size = 739732, upload-time = "2026-01-03T17:30:14.23Z" },
-    { url = "https://files.pythonhosted.org/packages/97/2c/621d5b851f94fa0bb7430d6089b3aa970a9d9b75196bc93bb624b0db237a/aiohttp-3.13.3-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:a45530014d7a1e09f4a55f4f43097ba0fd155089372e105e4bff4ca76cb1b168", size = 494293, upload-time = "2026-01-03T17:30:15.96Z" },
-    { url = "https://files.pythonhosted.org/packages/5d/43/4be01406b78e1be8320bb8316dc9c42dbab553d281c40364e0f862d5661c/aiohttp-3.13.3-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:27234ef6d85c914f9efeb77ff616dbf4ad2380be0cda40b4db086ffc7ddd1b7d", size = 493533, upload-time = "2026-01-03T17:30:17.431Z" },
-    { url = "https://files.pythonhosted.org/packages/8d/a8/5a35dc56a06a2c90d4742cbf35294396907027f80eea696637945a106f25/aiohttp-3.13.3-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:d32764c6c9aafb7fb55366a224756387cd50bfa720f32b88e0e6fa45b27dcf29", size = 1737839, upload-time = "2026-01-03T17:30:19.422Z" },
-    { url = "https://files.pythonhosted.org/packages/bf/62/4b9eeb331da56530bf2e198a297e5303e1c1ebdceeb00fe9b568a65c5a0c/aiohttp-3.13.3-cp312-cp312-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:b1a6102b4d3ebc07dad44fbf07b45bb600300f15b552ddf1851b5390202ea2e3", size = 1703932, upload-time = "2026-01-03T17:30:21.756Z" },
-    { url = "https://files.pythonhosted.org/packages/7c/f6/af16887b5d419e6a367095994c0b1332d154f647e7dc2bd50e61876e8e3d/aiohttp-3.13.3-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:c014c7ea7fb775dd015b2d3137378b7be0249a448a1612268b5a90c2d81de04d", size = 1771906, upload-time = "2026-01-03T17:30:23.932Z" },
-    { url = "https://files.pythonhosted.org/packages/ce/83/397c634b1bcc24292fa1e0c7822800f9f6569e32934bdeef09dae7992dfb/aiohttp-3.13.3-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:2b8d8ddba8f95ba17582226f80e2de99c7a7948e66490ef8d947e272a93e9463", size = 1871020, upload-time = "2026-01-03T17:30:26Z" },
-    { url = "https://files.pythonhosted.org/packages/86/f6/a62cbbf13f0ac80a70f71b1672feba90fdb21fd7abd8dbf25c0105fb6fa3/aiohttp-3.13.3-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:9ae8dd55c8e6c4257eae3a20fd2c8f41edaea5992ed67156642493b8daf3cecc", size = 1755181, upload-time = "2026-01-03T17:30:27.554Z" },
-    { url = "https://files.pythonhosted.org/packages/0a/87/20a35ad487efdd3fba93d5843efdfaa62d2f1479eaafa7453398a44faf13/aiohttp-3.13.3-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:01ad2529d4b5035578f5081606a465f3b814c542882804e2e8cda61adf5c71bf", size = 1561794, upload-time = "2026-01-03T17:30:29.254Z" },
-    { url = "https://files.pythonhosted.org/packages/de/95/8fd69a66682012f6716e1bc09ef8a1a2a91922c5725cb904689f112309c4/aiohttp-3.13.3-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:bb4f7475e359992b580559e008c598091c45b5088f28614e855e42d39c2f1033", size = 1697900, upload-time = "2026-01-03T17:30:31.033Z" },
-    { url = "https://files.pythonhosted.org/packages/e5/66/7b94b3b5ba70e955ff597672dad1691333080e37f50280178967aff68657/aiohttp-3.13.3-cp312-cp312-musllinux_1_2_armv7l.whl", hash = "sha256:c19b90316ad3b24c69cd78d5c9b4f3aa4497643685901185b65166293d36a00f", size = 1728239, upload-time = "2026-01-03T17:30:32.703Z" },
-    { url = "https://files.pythonhosted.org/packages/47/71/6f72f77f9f7d74719692ab65a2a0252584bf8d5f301e2ecb4c0da734530a/aiohttp-3.13.3-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:96d604498a7c782cb15a51c406acaea70d8c027ee6b90c569baa6e7b93073679", size = 1740527, upload-time = "2026-01-03T17:30:34.695Z" },
-    { url = "https://files.pythonhosted.org/packages/fa/b4/75ec16cbbd5c01bdaf4a05b19e103e78d7ce1ef7c80867eb0ace42ff4488/aiohttp-3.13.3-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:084911a532763e9d3dd95adf78a78f4096cd5f58cdc18e6fdbc1b58417a45423", size = 1554489, upload-time = "2026-01-03T17:30:36.864Z" },
-    { url = "https://files.pythonhosted.org/packages/52/8f/bc518c0eea29f8406dcf7ed1f96c9b48e3bc3995a96159b3fc11f9e08321/aiohttp-3.13.3-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:7a4a94eb787e606d0a09404b9c38c113d3b099d508021faa615d70a0131907ce", size = 1767852, upload-time = "2026-01-03T17:30:39.433Z" },
-    { url = "https://files.pythonhosted.org/packages/9d/f2/a07a75173124f31f11ea6f863dc44e6f09afe2bca45dd4e64979490deab1/aiohttp-3.13.3-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:87797e645d9d8e222e04160ee32aa06bc5c163e8499f24db719e7852ec23093a", size = 1722379, upload-time = "2026-01-03T17:30:41.081Z" },
-    { url = "https://files.pythonhosted.org/packages/3c/4a/1a3fee7c21350cac78e5c5cef711bac1b94feca07399f3d406972e2d8fcd/aiohttp-3.13.3-cp312-cp312-win32.whl", hash = "sha256:b04be762396457bef43f3597c991e192ee7da460a4953d7e647ee4b1c28e7046", size = 428253, upload-time = "2026-01-03T17:30:42.644Z" },
-    { url = "https://files.pythonhosted.org/packages/d9/b7/76175c7cb4eb73d91ad63c34e29fc4f77c9386bba4a65b53ba8e05ee3c39/aiohttp-3.13.3-cp312-cp312-win_amd64.whl", hash = "sha256:e3531d63d3bdfa7e3ac5e9b27b2dd7ec9df3206a98e0b3445fa906f233264c57", size = 455407, upload-time = "2026-01-03T17:30:44.195Z" },
-    { url = "https://files.pythonhosted.org/packages/97/8a/12ca489246ca1faaf5432844adbfce7ff2cc4997733e0af120869345643a/aiohttp-3.13.3-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:5dff64413671b0d3e7d5918ea490bdccb97a4ad29b3f311ed423200b2203e01c", size = 734190, upload-time = "2026-01-03T17:30:45.832Z" },
-    { url = "https://files.pythonhosted.org/packages/32/08/de43984c74ed1fca5c014808963cc83cb00d7bb06af228f132d33862ca76/aiohttp-3.13.3-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:87b9aab6d6ed88235aa2970294f496ff1a1f9adcd724d800e9b952395a80ffd9", size = 491783, upload-time = "2026-01-03T17:30:47.466Z" },
-    { url = "https://files.pythonhosted.org/packages/17/f8/8dd2cf6112a5a76f81f81a5130c57ca829d101ad583ce57f889179accdda/aiohttp-3.13.3-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:425c126c0dc43861e22cb1c14ba4c8e45d09516d0a3ae0a3f7494b79f5f233a3", size = 490704, upload-time = "2026-01-03T17:30:49.373Z" },
-    { url = "https://files.pythonhosted.org/packages/6d/40/a46b03ca03936f832bc7eaa47cfbb1ad012ba1be4790122ee4f4f8cba074/aiohttp-3.13.3-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:7f9120f7093c2a32d9647abcaf21e6ad275b4fbec5b55969f978b1a97c7c86bf", size = 1720652, upload-time = "2026-01-03T17:30:50.974Z" },
-    { url = "https://files.pythonhosted.org/packages/f7/7e/917fe18e3607af92657e4285498f500dca797ff8c918bd7d90b05abf6c2a/aiohttp-3.13.3-cp313-cp313-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:697753042d57f4bf7122cab985bf15d0cef23c770864580f5af4f52023a56bd6", size = 1692014, upload-time = "2026-01-03T17:30:52.729Z" },
-    { url = "https://files.pythonhosted.org/packages/71/b6/cefa4cbc00d315d68973b671cf105b21a609c12b82d52e5d0c9ae61d2a09/aiohttp-3.13.3-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:6de499a1a44e7de70735d0b39f67c8f25eb3d91eb3103be99ca0fa882cdd987d", size = 1759777, upload-time = "2026-01-03T17:30:54.537Z" },
-    { url = "https://files.pythonhosted.org/packages/fb/e3/e06ee07b45e59e6d81498b591fc589629be1553abb2a82ce33efe2a7b068/aiohttp-3.13.3-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:37239e9f9a7ea9ac5bf6b92b0260b01f8a22281996da609206a84df860bc1261", size = 1861276, upload-time = "2026-01-03T17:30:56.512Z" },
-    { url = "https://files.pythonhosted.org/packages/7c/24/75d274228acf35ceeb2850b8ce04de9dd7355ff7a0b49d607ee60c29c518/aiohttp-3.13.3-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:f76c1e3fe7d7c8afad7ed193f89a292e1999608170dcc9751a7462a87dfd5bc0", size = 1743131, upload-time = "2026-01-03T17:30:58.256Z" },
-    { url = "https://files.pythonhosted.org/packages/04/98/3d21dde21889b17ca2eea54fdcff21b27b93f45b7bb94ca029c31ab59dc3/aiohttp-3.13.3-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:fc290605db2a917f6e81b0e1e0796469871f5af381ce15c604a3c5c7e51cb730", size = 1556863, upload-time = "2026-01-03T17:31:00.445Z" },
-    { url = "https://files.pythonhosted.org/packages/9e/84/da0c3ab1192eaf64782b03971ab4055b475d0db07b17eff925e8c93b3aa5/aiohttp-3.13.3-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:4021b51936308aeea0367b8f006dc999ca02bc118a0cc78c303f50a2ff6afb91", size = 1682793, upload-time = "2026-01-03T17:31:03.024Z" },
-    { url = "https://files.pythonhosted.org/packages/ff/0f/5802ada182f575afa02cbd0ec5180d7e13a402afb7c2c03a9aa5e5d49060/aiohttp-3.13.3-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:49a03727c1bba9a97d3e93c9f93ca03a57300f484b6e935463099841261195d3", size = 1716676, upload-time = "2026-01-03T17:31:04.842Z" },
-    { url = "https://files.pythonhosted.org/packages/3f/8c/714d53bd8b5a4560667f7bbbb06b20c2382f9c7847d198370ec6526af39c/aiohttp-3.13.3-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:3d9908a48eb7416dc1f4524e69f1d32e5d90e3981e4e37eb0aa1cd18f9cfa2a4", size = 1733217, upload-time = "2026-01-03T17:31:06.868Z" },
-    { url = "https://files.pythonhosted.org/packages/7d/79/e2176f46d2e963facea939f5be2d26368ce543622be6f00a12844d3c991f/aiohttp-3.13.3-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:2712039939ec963c237286113c68dbad80a82a4281543f3abf766d9d73228998", size = 1552303, upload-time = "2026-01-03T17:31:08.958Z" },
-    { url = "https://files.pythonhosted.org/packages/ab/6a/28ed4dea1759916090587d1fe57087b03e6c784a642b85ef48217b0277ae/aiohttp-3.13.3-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:7bfdc049127717581866fa4708791220970ce291c23e28ccf3922c700740fdc0", size = 1763673, upload-time = "2026-01-03T17:31:10.676Z" },
-    { url = "https://files.pythonhosted.org/packages/e8/35/4a3daeb8b9fab49240d21c04d50732313295e4bd813a465d840236dd0ce1/aiohttp-3.13.3-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:8057c98e0c8472d8846b9c79f56766bcc57e3e8ac7bfd510482332366c56c591", size = 1721120, upload-time = "2026-01-03T17:31:12.575Z" },
-    { url = "https://files.pythonhosted.org/packages/bc/9f/d643bb3c5fb99547323e635e251c609fbbc660d983144cfebec529e09264/aiohttp-3.13.3-cp313-cp313-win32.whl", hash = "sha256:1449ceddcdbcf2e0446957863af03ebaaa03f94c090f945411b61269e2cb5daf", size = 427383, upload-time = "2026-01-03T17:31:14.382Z" },
-    { url = "https://files.pythonhosted.org/packages/4e/f1/ab0395f8a79933577cdd996dd2f9aa6014af9535f65dddcf88204682fe62/aiohttp-3.13.3-cp313-cp313-win_amd64.whl", hash = "sha256:693781c45a4033d31d4187d2436f5ac701e7bbfe5df40d917736108c1cc7436e", size = 453899, upload-time = "2026-01-03T17:31:15.958Z" },
-    { url = "https://files.pythonhosted.org/packages/99/36/5b6514a9f5d66f4e2597e40dea2e3db271e023eb7a5d22defe96ba560996/aiohttp-3.13.3-cp314-cp314-macosx_10_13_universal2.whl", hash = "sha256:ea37047c6b367fd4bd632bff8077449b8fa034b69e812a18e0132a00fae6e808", size = 737238, upload-time = "2026-01-03T17:31:17.909Z" },
-    { url = "https://files.pythonhosted.org/packages/f7/49/459327f0d5bcd8c6c9ca69e60fdeebc3622861e696490d8674a6d0cb90a6/aiohttp-3.13.3-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:6fc0e2337d1a4c3e6acafda6a78a39d4c14caea625124817420abceed36e2415", size = 492292, upload-time = "2026-01-03T17:31:19.919Z" },
-    { url = "https://files.pythonhosted.org/packages/e8/0b/b97660c5fd05d3495b4eb27f2d0ef18dc1dc4eff7511a9bf371397ff0264/aiohttp-3.13.3-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:c685f2d80bb67ca8c3837823ad76196b3694b0159d232206d1e461d3d434666f", size = 493021, upload-time = "2026-01-03T17:31:21.636Z" },
-    { url = "https://files.pythonhosted.org/packages/54/d4/438efabdf74e30aeceb890c3290bbaa449780583b1270b00661126b8aae4/aiohttp-3.13.3-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:48e377758516d262bde50c2584fc6c578af272559c409eecbdd2bae1601184d6", size = 1717263, upload-time = "2026-01-03T17:31:23.296Z" },
-    { url = "https://files.pythonhosted.org/packages/71/f2/7bddc7fd612367d1459c5bcf598a9e8f7092d6580d98de0e057eb42697ad/aiohttp-3.13.3-cp314-cp314-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:34749271508078b261c4abb1767d42b8d0c0cc9449c73a4df494777dc55f0687", size = 1669107, upload-time = "2026-01-03T17:31:25.334Z" },
-    { url = "https://files.pythonhosted.org/packages/00/5a/1aeaecca40e22560f97610a329e0e5efef5e0b5afdf9f857f0d93839ab2e/aiohttp-3.13.3-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:82611aeec80eb144416956ec85b6ca45a64d76429c1ed46ae1b5f86c6e0c9a26", size = 1760196, upload-time = "2026-01-03T17:31:27.394Z" },
-    { url = "https://files.pythonhosted.org/packages/f8/f8/0ff6992bea7bd560fc510ea1c815f87eedd745fe035589c71ce05612a19a/aiohttp-3.13.3-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:2fff83cfc93f18f215896e3a190e8e5cb413ce01553901aca925176e7568963a", size = 1843591, upload-time = "2026-01-03T17:31:29.238Z" },
-    { url = "https://files.pythonhosted.org/packages/e3/d1/e30e537a15f53485b61f5be525f2157da719819e8377298502aebac45536/aiohttp-3.13.3-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:bbe7d4cecacb439e2e2a8a1a7b935c25b812af7a5fd26503a66dadf428e79ec1", size = 1720277, upload-time = "2026-01-03T17:31:31.053Z" },
-    { url = "https://files.pythonhosted.org/packages/84/45/23f4c451d8192f553d38d838831ebbc156907ea6e05557f39563101b7717/aiohttp-3.13.3-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:b928f30fe49574253644b1ca44b1b8adbd903aa0da4b9054a6c20fc7f4092a25", size = 1548575, upload-time = "2026-01-03T17:31:32.87Z" },
-    { url = "https://files.pythonhosted.org/packages/6a/ed/0a42b127a43712eda7807e7892c083eadfaf8429ca8fb619662a530a3aab/aiohttp-3.13.3-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:7b5e8fe4de30df199155baaf64f2fcd604f4c678ed20910db8e2c66dc4b11603", size = 1679455, upload-time = "2026-01-03T17:31:34.76Z" },
-    { url = "https://files.pythonhosted.org/packages/2e/b5/c05f0c2b4b4fe2c9d55e73b6d3ed4fd6c9dc2684b1d81cbdf77e7fad9adb/aiohttp-3.13.3-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:8542f41a62bcc58fc7f11cf7c90e0ec324ce44950003feb70640fc2a9092c32a", size = 1687417, upload-time = "2026-01-03T17:31:36.699Z" },
-    { url = "https://files.pythonhosted.org/packages/c9/6b/915bc5dad66aef602b9e459b5a973529304d4e89ca86999d9d75d80cbd0b/aiohttp-3.13.3-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:5e1d8c8b8f1d91cd08d8f4a3c2b067bfca6ec043d3ff36de0f3a715feeedf926", size = 1729968, upload-time = "2026-01-03T17:31:38.622Z" },
-    { url = "https://files.pythonhosted.org/packages/11/3b/e84581290a9520024a08640b63d07673057aec5ca548177a82026187ba73/aiohttp-3.13.3-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:90455115e5da1c3c51ab619ac57f877da8fd6d73c05aacd125c5ae9819582aba", size = 1545690, upload-time = "2026-01-03T17:31:40.57Z" },
-    { url = "https://files.pythonhosted.org/packages/f5/04/0c3655a566c43fd647c81b895dfe361b9f9ad6d58c19309d45cff52d6c3b/aiohttp-3.13.3-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:042e9e0bcb5fba81886c8b4fbb9a09d6b8a00245fd8d88e4d989c1f96c74164c", size = 1746390, upload-time = "2026-01-03T17:31:42.857Z" },
-    { url = "https://files.pythonhosted.org/packages/1f/53/71165b26978f719c3419381514c9690bd5980e764a09440a10bb816ea4ab/aiohttp-3.13.3-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:2eb752b102b12a76ca02dff751a801f028b4ffbbc478840b473597fc91a9ed43", size = 1702188, upload-time = "2026-01-03T17:31:44.984Z" },
-    { url = "https://files.pythonhosted.org/packages/29/a7/cbe6c9e8e136314fa1980da388a59d2f35f35395948a08b6747baebb6aa6/aiohttp-3.13.3-cp314-cp314-win32.whl", hash = "sha256:b556c85915d8efaed322bf1bdae9486aa0f3f764195a0fb6ee962e5c71ef5ce1", size = 433126, upload-time = "2026-01-03T17:31:47.463Z" },
-    { url = "https://files.pythonhosted.org/packages/de/56/982704adea7d3b16614fc5936014e9af85c0e34b58f9046655817f04306e/aiohttp-3.13.3-cp314-cp314-win_amd64.whl", hash = "sha256:9bf9f7a65e7aa20dd764151fb3d616c81088f91f8df39c3893a536e279b4b984", size = 459128, upload-time = "2026-01-03T17:31:49.2Z" },
-    { url = "https://files.pythonhosted.org/packages/6c/2a/3c79b638a9c3d4658d345339d22070241ea341ed4e07b5ac60fb0f418003/aiohttp-3.13.3-cp314-cp314t-macosx_10_13_universal2.whl", hash = "sha256:05861afbbec40650d8a07ea324367cb93e9e8cc7762e04dd4405df99fa65159c", size = 769512, upload-time = "2026-01-03T17:31:51.134Z" },
-    { url = "https://files.pythonhosted.org/packages/29/b9/3e5014d46c0ab0db8707e0ac2711ed28c4da0218c358a4e7c17bae0d8722/aiohttp-3.13.3-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:2fc82186fadc4a8316768d61f3722c230e2c1dcab4200d52d2ebdf2482e47592", size = 506444, upload-time = "2026-01-03T17:31:52.85Z" },
-    { url = "https://files.pythonhosted.org/packages/90/03/c1d4ef9a054e151cd7839cdc497f2638f00b93cbe8043983986630d7a80c/aiohttp-3.13.3-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:0add0900ff220d1d5c5ebbf99ed88b0c1bbf87aa7e4262300ed1376a6b13414f", size = 510798, upload-time = "2026-01-03T17:31:54.91Z" },
-    { url = "https://files.pythonhosted.org/packages/ea/76/8c1e5abbfe8e127c893fe7ead569148a4d5a799f7cf958d8c09f3eedf097/aiohttp-3.13.3-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:568f416a4072fbfae453dcf9a99194bbb8bdeab718e08ee13dfa2ba0e4bebf29", size = 1868835, upload-time = "2026-01-03T17:31:56.733Z" },
-    { url = "https://files.pythonhosted.org/packages/8e/ac/984c5a6f74c363b01ff97adc96a3976d9c98940b8969a1881575b279ac5d/aiohttp-3.13.3-cp314-cp314t-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:add1da70de90a2569c5e15249ff76a631ccacfe198375eead4aadf3b8dc849dc", size = 1720486, upload-time = "2026-01-03T17:31:58.65Z" },
-    { url = "https://files.pythonhosted.org/packages/b2/9a/b7039c5f099c4eb632138728828b33428585031a1e658d693d41d07d89d1/aiohttp-3.13.3-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:10b47b7ba335d2e9b1239fa571131a87e2d8ec96b333e68b2a305e7a98b0bae2", size = 1847951, upload-time = "2026-01-03T17:32:00.989Z" },
-    { url = "https://files.pythonhosted.org/packages/3c/02/3bec2b9a1ba3c19ff89a43a19324202b8eb187ca1e928d8bdac9bbdddebd/aiohttp-3.13.3-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:3dd4dce1c718e38081c8f35f323209d4c1df7d4db4bab1b5c88a6b4d12b74587", size = 1941001, upload-time = "2026-01-03T17:32:03.122Z" },
-    { url = "https://files.pythonhosted.org/packages/37/df/d879401cedeef27ac4717f6426c8c36c3091c6e9f08a9178cc87549c537f/aiohttp-3.13.3-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:34bac00a67a812570d4a460447e1e9e06fae622946955f939051e7cc895cfab8", size = 1797246, upload-time = "2026-01-03T17:32:05.255Z" },
-    { url = "https://files.pythonhosted.org/packages/8d/15/be122de1f67e6953add23335c8ece6d314ab67c8bebb3f181063010795a7/aiohttp-3.13.3-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:a19884d2ee70b06d9204b2727a7b9f983d0c684c650254679e716b0b77920632", size = 1627131, upload-time = "2026-01-03T17:32:07.607Z" },
-    { url = "https://files.pythonhosted.org/packages/12/12/70eedcac9134cfa3219ab7af31ea56bc877395b1ac30d65b1bc4b27d0438/aiohttp-3.13.3-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:5f8ca7f2bb6ba8348a3614c7918cc4bb73268c5ac2a207576b7afea19d3d9f64", size = 1795196, upload-time = "2026-01-03T17:32:09.59Z" },
-    { url = "https://files.pythonhosted.org/packages/32/11/b30e1b1cd1f3054af86ebe60df96989c6a414dd87e27ad16950eee420bea/aiohttp-3.13.3-cp314-cp314t-musllinux_1_2_armv7l.whl", hash = "sha256:b0d95340658b9d2f11d9697f59b3814a9d3bb4b7a7c20b131df4bcef464037c0", size = 1782841, upload-time = "2026-01-03T17:32:11.445Z" },
-    { url = "https://files.pythonhosted.org/packages/88/0d/d98a9367b38912384a17e287850f5695c528cff0f14f791ce8ee2e4f7796/aiohttp-3.13.3-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:a1e53262fd202e4b40b70c3aff944a8155059beedc8a89bba9dc1f9ef06a1b56", size = 1795193, upload-time = "2026-01-03T17:32:13.705Z" },
-    { url = "https://files.pythonhosted.org/packages/43/a5/a2dfd1f5ff5581632c7f6a30e1744deda03808974f94f6534241ef60c751/aiohttp-3.13.3-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:d60ac9663f44168038586cab2157e122e46bdef09e9368b37f2d82d354c23f72", size = 1621979, upload-time = "2026-01-03T17:32:15.965Z" },
-    { url = "https://files.pythonhosted.org/packages/fa/f0/12973c382ae7c1cccbc4417e129c5bf54c374dfb85af70893646e1f0e749/aiohttp-3.13.3-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:90751b8eed69435bac9ff4e3d2f6b3af1f57e37ecb0fbeee59c0174c9e2d41df", size = 1822193, upload-time = "2026-01-03T17:32:18.219Z" },
-    { url = "https://files.pythonhosted.org/packages/3c/5f/24155e30ba7f8c96918af1350eb0663e2430aad9e001c0489d89cd708ab1/aiohttp-3.13.3-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:fc353029f176fd2b3ec6cfc71be166aba1936fe5d73dd1992ce289ca6647a9aa", size = 1769801, upload-time = "2026-01-03T17:32:20.25Z" },
-    { url = "https://files.pythonhosted.org/packages/eb/f8/7314031ff5c10e6ece114da79b338ec17eeff3a079e53151f7e9f43c4723/aiohttp-3.13.3-cp314-cp314t-win32.whl", hash = "sha256:2e41b18a58da1e474a057b3d35248d8320029f61d70a37629535b16a0c8f3767", size = 466523, upload-time = "2026-01-03T17:32:22.215Z" },
-    { url = "https://files.pythonhosted.org/packages/b4/63/278a98c715ae467624eafe375542d8ba9b4383a016df8fdefe0ae28382a7/aiohttp-3.13.3-cp314-cp314t-win_amd64.whl", hash = "sha256:44531a36aa2264a1860089ffd4dce7baf875ee5a6079d5fb42e261c704ef7344", size = 499694, upload-time = "2026-01-03T17:32:24.546Z" },
+    { url = "https://files.pythonhosted.org/packages/d4/7e/cb94129302d78c46662b47f9897d642fd0b33bdfef4b73b20c6ced35aa4c/aiohttp-3.13.4-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:8ea0c64d1bcbf201b285c2246c51a0c035ba3bbd306640007bc5844a3b4658c1", size = 760027, upload-time = "2026-03-28T17:15:33.022Z" },
+    { url = "https://files.pythonhosted.org/packages/5e/cd/2db3c9397c3bd24216b203dd739945b04f8b87bb036c640da7ddb63c75ef/aiohttp-3.13.4-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:6f742e1fa45c0ed522b00ede565e18f97e4cf8d1883a712ac42d0339dfb0cce7", size = 508325, upload-time = "2026-03-28T17:15:34.714Z" },
+    { url = "https://files.pythonhosted.org/packages/36/a3/d28b2722ec13107f2e37a86b8a169897308bab6a3b9e071ecead9d67bd9b/aiohttp-3.13.4-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:6dcfb50ee25b3b7a1222a9123be1f9f89e56e67636b561441f0b304e25aaef8f", size = 502402, upload-time = "2026-03-28T17:15:36.409Z" },
+    { url = "https://files.pythonhosted.org/packages/fa/d6/acd47b5f17c4430e555590990a4746efbcb2079909bb865516892bf85f37/aiohttp-3.13.4-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:3262386c4ff370849863ea93b9ea60fd59c6cf56bf8f93beac625cf4d677c04d", size = 1771224, upload-time = "2026-03-28T17:15:38.223Z" },
+    { url = "https://files.pythonhosted.org/packages/98/af/af6e20113ba6a48fd1cd9e5832c4851e7613ef50c7619acdaee6ec5f1aff/aiohttp-3.13.4-cp311-cp311-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:473bb5aa4218dd254e9ae4834f20e31f5a0083064ac0136a01a62ddbae2eaa42", size = 1731530, upload-time = "2026-03-28T17:15:39.988Z" },
+    { url = "https://files.pythonhosted.org/packages/81/16/78a2f5d9c124ad05d5ce59a9af94214b6466c3491a25fb70760e98e9f762/aiohttp-3.13.4-cp311-cp311-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:e56423766399b4c77b965f6aaab6c9546617b8994a956821cc507d00b91d978c", size = 1827925, upload-time = "2026-03-28T17:15:41.944Z" },
+    { url = "https://files.pythonhosted.org/packages/2a/1f/79acf0974ced805e0e70027389fccbb7d728e6f30fcac725fb1071e63075/aiohttp-3.13.4-cp311-cp311-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:8af249343fafd5ad90366a16d230fc265cf1149f26075dc9fe93cfd7c7173942", size = 1923579, upload-time = "2026-03-28T17:15:44.071Z" },
+    { url = "https://files.pythonhosted.org/packages/af/53/29f9e2054ea6900413f3b4c3eb9d8331f60678ec855f13ba8714c47fd48d/aiohttp-3.13.4-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:0bc0a5cf4f10ef5a2c94fdde488734b582a3a7a000b131263e27c9295bd682d9", size = 1767655, upload-time = "2026-03-28T17:15:45.911Z" },
+    { url = "https://files.pythonhosted.org/packages/f3/57/462fe1d3da08109ba4aa8590e7aed57c059af2a7e80ec21f4bac5cfe1094/aiohttp-3.13.4-cp311-cp311-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:5c7ff1028e3c9fc5123a865ce17df1cb6424d180c503b8517afbe89aa566e6be", size = 1630439, upload-time = "2026-03-28T17:15:48.11Z" },
+    { url = "https://files.pythonhosted.org/packages/d7/4b/4813344aacdb8127263e3eec343d24e973421143826364fa9fc847f6283f/aiohttp-3.13.4-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:ba5cf98b5dcb9bddd857da6713a503fa6d341043258ca823f0f5ab7ab4a94ee8", size = 1745557, upload-time = "2026-03-28T17:15:50.13Z" },
+    { url = "https://files.pythonhosted.org/packages/d4/01/1ef1adae1454341ec50a789f03cfafe4c4ac9c003f6a64515ecd32fe4210/aiohttp-3.13.4-cp311-cp311-musllinux_1_2_armv7l.whl", hash = "sha256:d85965d3ba21ee4999e83e992fecb86c4614d6920e40705501c0a1f80a583c12", size = 1741796, upload-time = "2026-03-28T17:15:52.351Z" },
+    { url = "https://files.pythonhosted.org/packages/22/04/8cdd99af988d2aa6922714d957d21383c559835cbd43fbf5a47ddf2e0f05/aiohttp-3.13.4-cp311-cp311-musllinux_1_2_ppc64le.whl", hash = "sha256:49f0b18a9b05d79f6f37ddd567695943fcefb834ef480f17a4211987302b2dc7", size = 1805312, upload-time = "2026-03-28T17:15:54.407Z" },
+    { url = "https://files.pythonhosted.org/packages/fb/7f/b48d5577338d4b25bbdbae35c75dbfd0493cb8886dc586fbfb2e90862239/aiohttp-3.13.4-cp311-cp311-musllinux_1_2_riscv64.whl", hash = "sha256:7f78cb080c86fbf765920e5f1ef35af3f24ec4314d6675d0a21eaf41f6f2679c", size = 1621751, upload-time = "2026-03-28T17:15:56.564Z" },
+    { url = "https://files.pythonhosted.org/packages/bc/89/4eecad8c1858e6d0893c05929e22343e0ebe3aec29a8a399c65c3cc38311/aiohttp-3.13.4-cp311-cp311-musllinux_1_2_s390x.whl", hash = "sha256:67a3ec705534a614b68bbf1c70efa777a21c3da3895d1c44510a41f5a7ae0453", size = 1826073, upload-time = "2026-03-28T17:15:58.489Z" },
+    { url = "https://files.pythonhosted.org/packages/f5/5c/9dc8293ed31b46c39c9c513ac7ca152b3c3d38e0ea111a530ad12001b827/aiohttp-3.13.4-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:d6630ec917e85c5356b2295744c8a97d40f007f96a1c76bf1928dc2e27465393", size = 1760083, upload-time = "2026-03-28T17:16:00.677Z" },
+    { url = "https://files.pythonhosted.org/packages/1e/19/8bbf6a4994205d96831f97b7d21a0feed120136e6267b5b22d229c6dc4dc/aiohttp-3.13.4-cp311-cp311-win32.whl", hash = "sha256:54049021bc626f53a5394c29e8c444f726ee5a14b6e89e0ad118315b1f90f5e3", size = 439690, upload-time = "2026-03-28T17:16:02.902Z" },
+    { url = "https://files.pythonhosted.org/packages/0c/f5/ac409ecd1007528d15c3e8c3a57d34f334c70d76cfb7128a28cffdebd4c1/aiohttp-3.13.4-cp311-cp311-win_amd64.whl", hash = "sha256:c033f2bc964156030772d31cbf7e5defea181238ce1f87b9455b786de7d30145", size = 463824, upload-time = "2026-03-28T17:16:05.058Z" },
+    { url = "https://files.pythonhosted.org/packages/1e/bd/ede278648914cabbabfdf95e436679b5d4156e417896a9b9f4587169e376/aiohttp-3.13.4-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:ee62d4471ce86b108b19c3364db4b91180d13fe3510144872d6bad5401957360", size = 752158, upload-time = "2026-03-28T17:16:06.901Z" },
+    { url = "https://files.pythonhosted.org/packages/90/de/581c053253c07b480b03785196ca5335e3c606a37dc73e95f6527f1591fe/aiohttp-3.13.4-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:c0fd8f41b54b58636402eb493afd512c23580456f022c1ba2db0f810c959ed0d", size = 501037, upload-time = "2026-03-28T17:16:08.82Z" },
+    { url = "https://files.pythonhosted.org/packages/fa/f9/a5ede193c08f13cc42c0a5b50d1e246ecee9115e4cf6e900d8dbd8fd6acb/aiohttp-3.13.4-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:4baa48ce49efd82d6b1a0be12d6a36b35e5594d1dd42f8bfba96ea9f8678b88c", size = 501556, upload-time = "2026-03-28T17:16:10.63Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/10/88ff67cd48a6ec36335b63a640abe86135791544863e0cfe1f065d6cef7a/aiohttp-3.13.4-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:d738ebab9f71ee652d9dbd0211057690022201b11197f9a7324fd4dba128aa97", size = 1757314, upload-time = "2026-03-28T17:16:12.498Z" },
+    { url = "https://files.pythonhosted.org/packages/8b/15/fdb90a5cf5a1f52845c276e76298c75fbbcc0ac2b4a86551906d54529965/aiohttp-3.13.4-cp312-cp312-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:0ce692c3468fa831af7dceed52edf51ac348cebfc8d3feb935927b63bd3e8576", size = 1731819, upload-time = "2026-03-28T17:16:14.558Z" },
+    { url = "https://files.pythonhosted.org/packages/ec/df/28146785a007f7820416be05d4f28cc207493efd1e8c6c1068e9bdc29198/aiohttp-3.13.4-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:8e08abcfe752a454d2cb89ff0c08f2d1ecd057ae3e8cc6d84638de853530ebab", size = 1793279, upload-time = "2026-03-28T17:16:16.594Z" },
+    { url = "https://files.pythonhosted.org/packages/10/47/689c743abf62ea7a77774d5722f220e2c912a77d65d368b884d9779ef41b/aiohttp-3.13.4-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:5977f701b3fff36367a11087f30ea73c212e686d41cd363c50c022d48b011d8d", size = 1891082, upload-time = "2026-03-28T17:16:18.71Z" },
+    { url = "https://files.pythonhosted.org/packages/b0/b6/f7f4f318c7e58c23b761c9b13b9a3c9b394e0f9d5d76fbc6622fa98509f6/aiohttp-3.13.4-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:54203e10405c06f8b6020bd1e076ae0fe6c194adcee12a5a78af3ffa3c57025e", size = 1773938, upload-time = "2026-03-28T17:16:21.125Z" },
+    { url = "https://files.pythonhosted.org/packages/aa/06/f207cb3121852c989586a6fc16ff854c4fcc8651b86c5d3bd1fc83057650/aiohttp-3.13.4-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:358a6af0145bc4dda037f13167bef3cce54b132087acc4c295c739d05d16b1c3", size = 1579548, upload-time = "2026-03-28T17:16:23.588Z" },
+    { url = "https://files.pythonhosted.org/packages/6c/58/e1289661a32161e24c1fe479711d783067210d266842523752869cc1d9c2/aiohttp-3.13.4-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:898ea1850656d7d61832ef06aa9846ab3ddb1621b74f46de78fbc5e1a586ba83", size = 1714669, upload-time = "2026-03-28T17:16:25.713Z" },
+    { url = "https://files.pythonhosted.org/packages/96/0a/3e86d039438a74a86e6a948a9119b22540bae037d6ba317a042ae3c22711/aiohttp-3.13.4-cp312-cp312-musllinux_1_2_armv7l.whl", hash = "sha256:7bc30cceb710cf6a44e9617e43eebb6e3e43ad855a34da7b4b6a73537d8a6763", size = 1754175, upload-time = "2026-03-28T17:16:28.18Z" },
+    { url = "https://files.pythonhosted.org/packages/f4/30/e717fc5df83133ba467a560b6d8ef20197037b4bb5d7075b90037de1018e/aiohttp-3.13.4-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:4a31c0c587a8a038f19a4c7e60654a6c899c9de9174593a13e7cc6e15ff271f9", size = 1762049, upload-time = "2026-03-28T17:16:30.941Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/28/8f7a2d4492e336e40005151bdd94baf344880a4707573378579f833a64c1/aiohttp-3.13.4-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:2062f675f3fe6e06d6113eb74a157fb9df58953ffed0cdb4182554b116545758", size = 1570861, upload-time = "2026-03-28T17:16:32.953Z" },
+    { url = "https://files.pythonhosted.org/packages/78/45/12e1a3d0645968b1c38de4b23fdf270b8637735ea057d4f84482ff918ad9/aiohttp-3.13.4-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:3d1ba8afb847ff80626d5e408c1fdc99f942acc877d0702fe137015903a220a9", size = 1790003, upload-time = "2026-03-28T17:16:35.468Z" },
+    { url = "https://files.pythonhosted.org/packages/eb/0f/60374e18d590de16dcb39d6ff62f39c096c1b958e6f37727b5870026ea30/aiohttp-3.13.4-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:b08149419994cdd4d5eecf7fd4bc5986b5a9380285bcd01ab4c0d6bfca47b79d", size = 1737289, upload-time = "2026-03-28T17:16:38.187Z" },
+    { url = "https://files.pythonhosted.org/packages/02/bf/535e58d886cfbc40a8b0013c974afad24ef7632d645bca0b678b70033a60/aiohttp-3.13.4-cp312-cp312-win32.whl", hash = "sha256:fc432f6a2c4f720180959bc19aa37259651c1a4ed8af8afc84dd41c60f15f791", size = 434185, upload-time = "2026-03-28T17:16:40.735Z" },
+    { url = "https://files.pythonhosted.org/packages/1e/1a/d92e3325134ebfff6f4069f270d3aac770d63320bd1fcd0eca023e74d9a8/aiohttp-3.13.4-cp312-cp312-win_amd64.whl", hash = "sha256:6148c9ae97a3e8bff9a1fc9c757fa164116f86c100468339730e717590a3fb77", size = 461285, upload-time = "2026-03-28T17:16:42.713Z" },
+    { url = "https://files.pythonhosted.org/packages/e3/ac/892f4162df9b115b4758d615f32ec63d00f3084c705ff5526630887b9b42/aiohttp-3.13.4-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:63dd5e5b1e43b8fb1e91b79b7ceba1feba588b317d1edff385084fcc7a0a4538", size = 745744, upload-time = "2026-03-28T17:16:44.67Z" },
+    { url = "https://files.pythonhosted.org/packages/97/a9/c5b87e4443a2f0ea88cb3000c93a8fdad1ee63bffc9ded8d8c8e0d66efc6/aiohttp-3.13.4-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:746ac3cc00b5baea424dacddea3ec2c2702f9590de27d837aa67004db1eebc6e", size = 498178, upload-time = "2026-03-28T17:16:46.766Z" },
+    { url = "https://files.pythonhosted.org/packages/94/42/07e1b543a61250783650df13da8ddcdc0d0a5538b2bd15cef6e042aefc61/aiohttp-3.13.4-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:bda8f16ea99d6a6705e5946732e48487a448be874e54a4f73d514660ff7c05d3", size = 498331, upload-time = "2026-03-28T17:16:48.9Z" },
+    { url = "https://files.pythonhosted.org/packages/20/d6/492f46bf0328534124772d0cf58570acae5b286ea25006900650f69dae0e/aiohttp-3.13.4-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:4b061e7b5f840391e3f64d0ddf672973e45c4cfff7a0feea425ea24e51530fc2", size = 1744414, upload-time = "2026-03-28T17:16:50.968Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/4d/e02627b2683f68051246215d2d62b2d2f249ff7a285e7a858dc47d6b6a14/aiohttp-3.13.4-cp313-cp313-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:b252e8d5cd66184b570d0d010de742736e8a4fab22c58299772b0c5a466d4b21", size = 1719226, upload-time = "2026-03-28T17:16:53.173Z" },
+    { url = "https://files.pythonhosted.org/packages/7b/6c/5d0a3394dd2b9f9aeba6e1b6065d0439e4b75d41f1fb09a3ec010b43552b/aiohttp-3.13.4-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:20af8aad61d1803ff11152a26146d8d81c266aa8c5aa9b4504432abb965c36a0", size = 1782110, upload-time = "2026-03-28T17:16:55.362Z" },
+    { url = "https://files.pythonhosted.org/packages/0d/2d/c20791e3437700a7441a7edfb59731150322424f5aadf635602d1d326101/aiohttp-3.13.4-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:13a5cc924b59859ad2adb1478e31f410a7ed46e92a2a619d6d1dd1a63c1a855e", size = 1884809, upload-time = "2026-03-28T17:16:57.734Z" },
+    { url = "https://files.pythonhosted.org/packages/c8/94/d99dbfbd1924a87ef643833932eb2a3d9e5eee87656efea7d78058539eff/aiohttp-3.13.4-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:534913dfb0a644d537aebb4123e7d466d94e3be5549205e6a31f72368980a81a", size = 1764938, upload-time = "2026-03-28T17:17:00.221Z" },
+    { url = "https://files.pythonhosted.org/packages/49/61/3ce326a1538781deb89f6cf5e094e2029cd308ed1e21b2ba2278b08426f6/aiohttp-3.13.4-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:320e40192a2dcc1cf4b5576936e9652981ab596bf81eb309535db7e2f5b5672f", size = 1570697, upload-time = "2026-03-28T17:17:02.985Z" },
+    { url = "https://files.pythonhosted.org/packages/b6/77/4ab5a546857bb3028fbaf34d6eea180267bdab022ee8b1168b1fcde4bfdd/aiohttp-3.13.4-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:9e587fcfce2bcf06526a43cb705bdee21ac089096f2e271d75de9c339db3100c", size = 1702258, upload-time = "2026-03-28T17:17:05.28Z" },
+    { url = "https://files.pythonhosted.org/packages/79/63/d8f29021e39bc5af8e5d5e9da1b07976fb9846487a784e11e4f4eeda4666/aiohttp-3.13.4-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:9eb9c2eea7278206b5c6c1441fdd9dc420c278ead3f3b2cc87f9b693698cc500", size = 1740287, upload-time = "2026-03-28T17:17:07.712Z" },
+    { url = "https://files.pythonhosted.org/packages/55/3a/cbc6b3b124859a11bc8055d3682c26999b393531ef926754a3445b99dfef/aiohttp-3.13.4-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:29be00c51972b04bf9d5c8f2d7f7314f48f96070ca40a873a53056e652e805f7", size = 1753011, upload-time = "2026-03-28T17:17:10.053Z" },
+    { url = "https://files.pythonhosted.org/packages/e0/30/836278675205d58c1368b21520eab9572457cf19afd23759216c04483048/aiohttp-3.13.4-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:90c06228a6c3a7c9f776fe4fc0b7ff647fffd3bed93779a6913c804ae00c1073", size = 1566359, upload-time = "2026-03-28T17:17:12.433Z" },
+    { url = "https://files.pythonhosted.org/packages/50/b4/8032cc9b82d17e4277704ba30509eaccb39329dc18d6a35f05e424439e32/aiohttp-3.13.4-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:a533ec132f05fd9a1d959e7f34184cd7d5e8511584848dab85faefbaac573069", size = 1785537, upload-time = "2026-03-28T17:17:14.721Z" },
+    { url = "https://files.pythonhosted.org/packages/17/7d/5873e98230bde59f493bf1f7c3e327486a4b5653fa401144704df5d00211/aiohttp-3.13.4-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:1c946f10f413836f82ea4cfb90200d2a59578c549f00857e03111cf45ad01ca5", size = 1740752, upload-time = "2026-03-28T17:17:17.387Z" },
+    { url = "https://files.pythonhosted.org/packages/7b/f2/13e46e0df051494d7d3c68b7f72d071f48c384c12716fc294f75d5b1a064/aiohttp-3.13.4-cp313-cp313-win32.whl", hash = "sha256:48708e2706106da6967eff5908c78ca3943f005ed6bcb75da2a7e4da94ef8c70", size = 433187, upload-time = "2026-03-28T17:17:19.523Z" },
+    { url = "https://files.pythonhosted.org/packages/ea/c0/649856ee655a843c8f8664592cfccb73ac80ede6a8c8db33a25d810c12db/aiohttp-3.13.4-cp313-cp313-win_amd64.whl", hash = "sha256:74a2eb058da44fa3a877a49e2095b591d4913308bb424c418b77beb160c55ce3", size = 459778, upload-time = "2026-03-28T17:17:21.964Z" },
+    { url = "https://files.pythonhosted.org/packages/6d/29/6657cc37ae04cacc2dbf53fb730a06b6091cc4cbe745028e047c53e6d840/aiohttp-3.13.4-cp314-cp314-macosx_10_13_universal2.whl", hash = "sha256:e0a2c961fc92abeff61d6444f2ce6ad35bb982db9fc8ff8a47455beacf454a57", size = 749363, upload-time = "2026-03-28T17:17:24.044Z" },
+    { url = "https://files.pythonhosted.org/packages/90/7f/30ccdf67ca3d24b610067dc63d64dcb91e5d88e27667811640644aa4a85d/aiohttp-3.13.4-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:153274535985a0ff2bff1fb6c104ed547cec898a09213d21b0f791a44b14d933", size = 499317, upload-time = "2026-03-28T17:17:26.199Z" },
+    { url = "https://files.pythonhosted.org/packages/93/13/e372dd4e68ad04ee25dafb050c7f98b0d91ea643f7352757e87231102555/aiohttp-3.13.4-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:351f3171e2458da3d731ce83f9e6b9619e325c45cbd534c7759750cabf453ad7", size = 500477, upload-time = "2026-03-28T17:17:28.279Z" },
+    { url = "https://files.pythonhosted.org/packages/e5/fe/ee6298e8e586096fb6f5eddd31393d8544f33ae0792c71ecbb4c2bef98ac/aiohttp-3.13.4-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f989ac8bc5595ff761a5ccd32bdb0768a117f36dd1504b1c2c074ed5d3f4df9c", size = 1737227, upload-time = "2026-03-28T17:17:30.587Z" },
+    { url = "https://files.pythonhosted.org/packages/b0/b9/a7a0463a09e1a3fe35100f74324f23644bfc3383ac5fd5effe0722a5f0b7/aiohttp-3.13.4-cp314-cp314-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:d36fc1709110ec1e87a229b201dd3ddc32aa01e98e7868083a794609b081c349", size = 1694036, upload-time = "2026-03-28T17:17:33.29Z" },
+    { url = "https://files.pythonhosted.org/packages/57/7c/8972ae3fb7be00a91aee6b644b2a6a909aedb2c425269a3bfd90115e6f8f/aiohttp-3.13.4-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:42adaeea83cbdf069ab94f5103ce0787c21fb1a0153270da76b59d5578302329", size = 1786814, upload-time = "2026-03-28T17:17:36.035Z" },
+    { url = "https://files.pythonhosted.org/packages/93/01/c81e97e85c774decbaf0d577de7d848934e8166a3a14ad9f8aa5be329d28/aiohttp-3.13.4-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:92deb95469928cc41fd4b42a95d8012fa6df93f6b1c0a83af0ffbc4a5e218cde", size = 1866676, upload-time = "2026-03-28T17:17:38.441Z" },
+    { url = "https://files.pythonhosted.org/packages/5a/5f/5b46fe8694a639ddea2cd035bf5729e4677ea882cb251396637e2ef1590d/aiohttp-3.13.4-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:0c0c7c07c4257ef3a1df355f840bc62d133bcdef5c1c5ba75add3c08553e2eed", size = 1740842, upload-time = "2026-03-28T17:17:40.783Z" },
+    { url = "https://files.pythonhosted.org/packages/20/a2/0d4b03d011cca6b6b0acba8433193c1e484efa8d705ea58295590fe24203/aiohttp-3.13.4-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:f062c45de8a1098cb137a1898819796a2491aec4e637a06b03f149315dff4d8f", size = 1566508, upload-time = "2026-03-28T17:17:43.235Z" },
+    { url = "https://files.pythonhosted.org/packages/98/17/e689fd500da52488ec5f889effd6404dece6a59de301e380f3c64f167beb/aiohttp-3.13.4-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:76093107c531517001114f0ebdb4f46858ce818590363e3e99a4a2280334454a", size = 1700569, upload-time = "2026-03-28T17:17:46.165Z" },
+    { url = "https://files.pythonhosted.org/packages/d8/0d/66402894dbcf470ef7db99449e436105ea862c24f7ea4c95c683e635af35/aiohttp-3.13.4-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:6f6ec32162d293b82f8b63a16edc80769662fbd5ae6fbd4936d3206a2c2cc63b", size = 1707407, upload-time = "2026-03-28T17:17:48.825Z" },
+    { url = "https://files.pythonhosted.org/packages/2f/eb/af0ab1a3650092cbd8e14ef29e4ab0209e1460e1c299996c3f8288b3f1ff/aiohttp-3.13.4-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:5903e2db3d202a00ad9f0ec35a122c005e85d90c9836ab4cda628f01edf425e2", size = 1752214, upload-time = "2026-03-28T17:17:51.206Z" },
+    { url = "https://files.pythonhosted.org/packages/5a/bf/72326f8a98e4c666f292f03c385545963cc65e358835d2a7375037a97b57/aiohttp-3.13.4-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:2d5bea57be7aca98dbbac8da046d99b5557c5cf4e28538c4c786313078aca09e", size = 1562162, upload-time = "2026-03-28T17:17:53.634Z" },
+    { url = "https://files.pythonhosted.org/packages/67/9f/13b72435f99151dd9a5469c96b3b5f86aa29b7e785ca7f35cf5e538f74c0/aiohttp-3.13.4-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:bcf0c9902085976edc0232b75006ef38f89686901249ce14226b6877f88464fb", size = 1768904, upload-time = "2026-03-28T17:17:55.991Z" },
+    { url = "https://files.pythonhosted.org/packages/18/bc/28d4970e7d5452ac7776cdb5431a1164a0d9cf8bd2fffd67b4fb463aa56d/aiohttp-3.13.4-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:c3295f98bfeed2e867cab588f2a146a9db37a85e3ae9062abf46ba062bd29165", size = 1723378, upload-time = "2026-03-28T17:17:58.348Z" },
+    { url = "https://files.pythonhosted.org/packages/53/74/b32458ca1a7f34d65bdee7aef2036adbe0438123d3d53e2b083c453c24dd/aiohttp-3.13.4-cp314-cp314-win32.whl", hash = "sha256:a598a5c5767e1369d8f5b08695cab1d8160040f796c4416af76fd773d229b3c9", size = 438711, upload-time = "2026-03-28T17:18:00.728Z" },
+    { url = "https://files.pythonhosted.org/packages/40/b2/54b487316c2df3e03a8f3435e9636f8a81a42a69d942164830d193beb56a/aiohttp-3.13.4-cp314-cp314-win_amd64.whl", hash = "sha256:c555db4bc7a264bead5a7d63d92d41a1122fcd39cc62a4db815f45ad46f9c2c8", size = 464977, upload-time = "2026-03-28T17:18:03.367Z" },
+    { url = "https://files.pythonhosted.org/packages/47/fb/e41b63c6ce71b07a59243bb8f3b457ee0c3402a619acb9d2c0d21ef0e647/aiohttp-3.13.4-cp314-cp314t-macosx_10_13_universal2.whl", hash = "sha256:45abbbf09a129825d13c18c7d3182fecd46d9da3cfc383756145394013604ac1", size = 781549, upload-time = "2026-03-28T17:18:05.779Z" },
+    { url = "https://files.pythonhosted.org/packages/97/53/532b8d28df1e17e44c4d9a9368b78dcb6bf0b51037522136eced13afa9e8/aiohttp-3.13.4-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:74c80b2bc2c2adb7b3d1941b2b60701ee2af8296fc8aad8b8bc48bc25767266c", size = 514383, upload-time = "2026-03-28T17:18:08.096Z" },
+    { url = "https://files.pythonhosted.org/packages/1b/1f/62e5d400603e8468cd635812d99cb81cfdc08127a3dc474c647615f31339/aiohttp-3.13.4-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:c97989ae40a9746650fa196894f317dafc12227c808c774929dda0ff873a5954", size = 518304, upload-time = "2026-03-28T17:18:10.642Z" },
+    { url = "https://files.pythonhosted.org/packages/90/57/2326b37b10896447e3c6e0cbef4fe2486d30913639a5cfd1332b5d870f82/aiohttp-3.13.4-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:dae86be9811493f9990ef44fff1685f5c1a3192e9061a71a109d527944eed551", size = 1893433, upload-time = "2026-03-28T17:18:13.121Z" },
+    { url = "https://files.pythonhosted.org/packages/d2/b4/a24d82112c304afdb650167ef2fe190957d81cbddac7460bedd245f765aa/aiohttp-3.13.4-cp314-cp314t-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:1db491abe852ca2fa6cc48a3341985b0174b3741838e1341b82ac82c8bd9e871", size = 1755901, upload-time = "2026-03-28T17:18:16.21Z" },
+    { url = "https://files.pythonhosted.org/packages/9e/2d/0883ef9d878d7846287f036c162a951968f22aabeef3ac97b0bea6f76d5d/aiohttp-3.13.4-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:0e5d701c0aad02a7dce72eef6b93226cf3734330f1a31d69ebbf69f33b86666e", size = 1876093, upload-time = "2026-03-28T17:18:18.703Z" },
+    { url = "https://files.pythonhosted.org/packages/ad/52/9204bb59c014869b71971addad6778f005daa72a96eed652c496789d7468/aiohttp-3.13.4-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:8ac32a189081ae0a10ba18993f10f338ec94341f0d5df8fff348043962f3c6f8", size = 1970815, upload-time = "2026-03-28T17:18:21.858Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/b5/e4eb20275a866dde0f570f411b36c6b48f7b53edfe4f4071aa1b0728098a/aiohttp-3.13.4-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:98e968cdaba43e45c73c3f306fca418c8009a957733bac85937c9f9cf3f4de27", size = 1816223, upload-time = "2026-03-28T17:18:24.729Z" },
+    { url = "https://files.pythonhosted.org/packages/d8/23/e98075c5bb146aa61a1239ee1ac7714c85e814838d6cebbe37d3fe19214a/aiohttp-3.13.4-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:ca114790c9144c335d538852612d3e43ea0f075288f4849cf4b05d6cd2238ce7", size = 1649145, upload-time = "2026-03-28T17:18:27.269Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/c1/7bad8be33bb06c2bb224b6468874346026092762cbec388c3bdb65a368ee/aiohttp-3.13.4-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:ea2e071661ba9cfe11eabbc81ac5376eaeb3061f6e72ec4cc86d7cdd1ffbdbbb", size = 1816562, upload-time = "2026-03-28T17:18:29.847Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/10/c00323348695e9a5e316825969c88463dcc24c7e9d443244b8a2c9cf2eae/aiohttp-3.13.4-cp314-cp314t-musllinux_1_2_armv7l.whl", hash = "sha256:34e89912b6c20e0fd80e07fa401fd218a410aa1ce9f1c2f1dad6db1bd0ce0927", size = 1800333, upload-time = "2026-03-28T17:18:32.269Z" },
+    { url = "https://files.pythonhosted.org/packages/84/43/9b2147a1df3559f49bd723e22905b46a46c068a53adb54abdca32c4de180/aiohttp-3.13.4-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:0e217cf9f6a42908c52b46e42c568bd57adc39c9286ced31aaace614b6087965", size = 1820617, upload-time = "2026-03-28T17:18:35.238Z" },
+    { url = "https://files.pythonhosted.org/packages/a9/7f/b3481a81e7a586d02e99387b18c6dafff41285f6efd3daa2124c01f87eae/aiohttp-3.13.4-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:0c296f1221e21ba979f5ac1964c3b78cfde15c5c5f855ffd2caab337e9cd9182", size = 1643417, upload-time = "2026-03-28T17:18:37.949Z" },
+    { url = "https://files.pythonhosted.org/packages/8f/72/07181226bc99ce1124e0f89280f5221a82d3ae6a6d9d1973ce429d48e52b/aiohttp-3.13.4-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:d99a9d168ebaffb74f36d011750e490085ac418f4db926cce3989c8fe6cb6b1b", size = 1849286, upload-time = "2026-03-28T17:18:40.534Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/e6/1b3566e103eca6da5be4ae6713e112a053725c584e96574caf117568ffef/aiohttp-3.13.4-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:cb19177205d93b881f3f89e6081593676043a6828f59c78c17a0fd6c1fbed2ba", size = 1782635, upload-time = "2026-03-28T17:18:43.073Z" },
+    { url = "https://files.pythonhosted.org/packages/37/58/1b11c71904b8d079eb0c39fe664180dd1e14bebe5608e235d8bfbadc8929/aiohttp-3.13.4-cp314-cp314t-win32.whl", hash = "sha256:c606aa5656dab6552e52ca368e43869c916338346bfaf6304e15c58fb113ea30", size = 472537, upload-time = "2026-03-28T17:18:46.286Z" },
+    { url = "https://files.pythonhosted.org/packages/bc/8f/87c56a1a1977d7dddea5b31e12189665a140fdb48a71e9038ff90bb564ec/aiohttp-3.13.4-cp314-cp314t-win_amd64.whl", hash = "sha256:014dcc10ec8ab8db681f0d68e939d1e9286a5aa2b993cbbdb0db130853e02144", size = 506381, upload-time = "2026-03-28T17:18:48.74Z" },
 ]
 
 [[package]]
@@ -274,14 +274,14 @@ wheels = [
 
 [[package]]
 name = "click"
-version = "8.3.1"
+version = "8.1.8"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "colorama", marker = "sys_platform == 'win32'" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/3d/fa/656b739db8587d7b5dfa22e22ed02566950fbfbcdc20311993483657a5c0/click-8.3.1.tar.gz", hash = "sha256:12ff4785d337a1bb490bb7e9c2b1ee5da3112e94a8622f26a6c77f5d2fc6842a", size = 295065, upload-time = "2025-11-15T20:45:42.706Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/b9/2e/0090cbf739cee7d23781ad4b89a9894a41538e4fcf4c31dcdd705b78eb8b/click-8.1.8.tar.gz", hash = "sha256:ed53c9d8990d83c2a27deae68e4ee337473f6330c040a31d4225c9574d16096a", size = 226593, upload-time = "2024-12-21T18:38:44.339Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/98/78/01c019cdb5d6498122777c1a43056ebb3ebfeef2076d9d026bfe15583b2b/click-8.3.1-py3-none-any.whl", hash = "sha256:981153a64e25f12d547d3426c367a4857371575ee7ad18df2a6183ab0545b2a6", size = 108274, upload-time = "2025-11-15T20:45:41.139Z" },
+    { url = "https://files.pythonhosted.org/packages/7e/d4/7ebdbd03970677812aac39c869717059dbb71a4cfc033ca6e5221787892c/click-8.1.8-py3-none-any.whl", hash = "sha256:63c132bbbed01578a06712a2d1f497bb62d9c1c0d329b7903a866228027263b2", size = 98188, upload-time = "2024-12-21T18:38:41.666Z" },
 ]
 
 [[package]]
@@ -644,11 +644,11 @@ requires-dist = [
     { name = "coverage", marker = "extra == 'dev'", specifier = ">=7.6.0" },
     { name = "datasets", specifier = ">=3.0.0" },
     { name = "hypothesis", marker = "extra == 'dev'", specifier = ">=6.88.0" },
-    { name = "litellm", specifier = ">=1.50.0" },
+    { name = "litellm", specifier = "!=1.82.7,!=1.82.8,>=1.83.7" },
     { name = "mini-swe-agent", specifier = ">=2.0.0" },
     { name = "pandas", specifier = ">=2.0.0" },
-    { name = "pytest", marker = "extra == 'dev'", specifier = ">=8.0.0" },
-    { name = "python-dotenv", specifier = ">=1.0.0" },
+    { name = "pytest", marker = "extra == 'dev'", specifier = ">=9.0.3" },
+    { name = "python-dotenv", specifier = ">=1.2.2" },
     { name = "pyyaml", specifier = ">=6.0" },
     { name = "rich", specifier = ">=13.0.0" },
     { name = "ruff", marker = "extra == 'dev'", specifier = ">=0.5.0" },
@@ -769,14 +769,14 @@ wheels = [
 
 [[package]]
 name = "importlib-metadata"
-version = "9.0.0"
+version = "8.5.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "zipp" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/a9/01/15bb152d77b21318514a96f43af312635eb2500c96b55398d020c93d86ea/importlib_metadata-9.0.0.tar.gz", hash = "sha256:a4f57ab599e6a2e3016d7595cfd72eb4661a5106e787a95bcc90c7105b831efc", size = 56405, upload-time = "2026-03-20T06:42:56.999Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/cd/12/33e59336dca5be0c398a7482335911a33aa0e20776128f038019f1a95f1b/importlib_metadata-8.5.0.tar.gz", hash = "sha256:71522656f0abace1d072b9e5481a48f07c138e00f079c38c8f883823f9c26bd7", size = 55304, upload-time = "2024-09-11T14:56:08.937Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/38/3d/2d244233ac4f76e38533cfcb2991c9eb4c7bf688ae0a036d30725b8faafe/importlib_metadata-9.0.0-py3-none-any.whl", hash = "sha256:2d21d1cc5a017bd0559e36150c21c830ab1dc304dedd1b7ea85d20f45ef3edd7", size = 27789, upload-time = "2026-03-20T06:42:55.665Z" },
+    { url = "https://files.pythonhosted.org/packages/a0/d9/a1e041c5e7caa9a05c925f4bdbdfb7f006d1f74996af53467bc394c97be7/importlib_metadata-8.5.0-py3-none-any.whl", hash = "sha256:45e54197d28b7a7f1559e60b95e7c567032b602131fbd588f1497f47880aa68b", size = 26514, upload-time = "2024-09-11T14:56:07.019Z" },
 ]
 
 [[package]]
@@ -887,7 +887,7 @@ wheels = [
 
 [[package]]
 name = "jsonschema"
-version = "4.26.0"
+version = "4.23.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "attrs" },
@@ -895,9 +895,9 @@ dependencies = [
     { name = "referencing" },
     { name = "rpds-py" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/b3/fc/e067678238fa451312d4c62bf6e6cf5ec56375422aee02f9cb5f909b3047/jsonschema-4.26.0.tar.gz", hash = "sha256:0c26707e2efad8aa1bfc5b7ce170f3fccc2e4918ff85989ba9ffa9facb2be326", size = 366583, upload-time = "2026-01-07T13:41:07.246Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/38/2e/03362ee4034a4c917f697890ccd4aec0800ccf9ded7f511971c75451deec/jsonschema-4.23.0.tar.gz", hash = "sha256:d71497fef26351a33265337fa77ffeb82423f3ea21283cd9467bb03999266bc4", size = 325778, upload-time = "2024-07-08T18:40:05.546Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/69/90/f63fb5873511e014207a475e2bb4e8b2e570d655b00ac19a9a0ca0a385ee/jsonschema-4.26.0-py3-none-any.whl", hash = "sha256:d489f15263b8d200f8387e64b4c3a75f06629559fb73deb8fdfb525f2dab50ce", size = 90630, upload-time = "2026-01-07T13:41:05.306Z" },
+    { url = "https://files.pythonhosted.org/packages/69/4a/4f9dbeb84e8850557c02365a0eee0649abe5eb1d84af92a25731c6c0f922/jsonschema-4.23.0-py3-none-any.whl", hash = "sha256:fbadb6f8b144a8f8cf9f0b89ba94501d143e50411a1278633f56a7acf7fd5566", size = 88462, upload-time = "2024-07-08T18:40:00.165Z" },
 ]
 
 [[package]]
@@ -926,7 +926,7 @@ wheels = [
 
 [[package]]
 name = "litellm"
-version = "1.82.6"
+version = "1.83.14"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "aiohttp" },
@@ -942,9 +942,9 @@ dependencies = [
     { name = "tiktoken" },
     { name = "tokenizers" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/29/75/1c537aa458426a9127a92bc2273787b2f987f4e5044e21f01f2eed5244fd/litellm-1.82.6.tar.gz", hash = "sha256:2aa1c2da21fe940c33613aa447119674a3ad4d2ad5eb064e4d5ce5ee42420136", size = 17414147, upload-time = "2026-03-22T06:36:00.452Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/8d/7c/c095649380adc96c8630273c1768c2ad1e74aa2ee1dd8dd05d218a60569f/litellm-1.83.14.tar.gz", hash = "sha256:24aef9b47cdc424c833e32f3727f411741c690832cd1fe4405e0077144fe09c9", size = 14836599, upload-time = "2026-04-26T03:16:10.176Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/02/6c/5327667e6dbe9e98cbfbd4261c8e91386a52e38f41419575854248bbab6a/litellm-1.82.6-py3-none-any.whl", hash = "sha256:164a3ef3e19f309e3cabc199bef3d2045212712fefdfa25fc7f75884a5b5b205", size = 15591595, upload-time = "2026-03-22T06:35:56.795Z" },
+    { url = "https://files.pythonhosted.org/packages/7f/5c/1b5691575420135e90578543b2bf219497caa33cfd0af64cb38f30288450/litellm-1.83.14-py3-none-any.whl", hash = "sha256:92b11ba2a32cf80707ddf388d18526696c7999a21b418c5e3b6eda1243d2cfdb", size = 16457054, upload-time = "2026-04-26T03:16:05.72Z" },
 ]
 
 [[package]]
@@ -1302,7 +1302,7 @@ wheels = [
 
 [[package]]
 name = "openai"
-version = "2.29.0"
+version = "2.24.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "anyio" },
@@ -1314,9 +1314,9 @@ dependencies = [
     { name = "tqdm" },
     { name = "typing-extensions" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/b4/15/203d537e58986b5673e7f232453a2a2f110f22757b15921cbdeea392e520/openai-2.29.0.tar.gz", hash = "sha256:32d09eb2f661b38d3edd7d7e1a2943d1633f572596febe64c0cd370c86d52bec", size = 671128, upload-time = "2026-03-17T17:53:49.599Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/55/13/17e87641b89b74552ed408a92b231283786523edddc95f3545809fab673c/openai-2.24.0.tar.gz", hash = "sha256:1e5769f540dbd01cb33bc4716a23e67b9d695161a734aff9c5f925e2bf99a673", size = 658717, upload-time = "2026-02-24T20:02:07.958Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/d0/b1/35b6f9c8cf9318e3dbb7146cc82dab4cf61182a8d5406fc9b50864362895/openai-2.29.0-py3-none-any.whl", hash = "sha256:b7c5de513c3286d17c5e29b92c4c98ceaf0d775244ac8159aeb1bddf840eb42a", size = 1141533, upload-time = "2026-03-17T17:53:47.348Z" },
+    { url = "https://files.pythonhosted.org/packages/c9/30/844dc675ee6902579b8eef01ed23917cc9319a1c9c0c14ec6e39340c96d0/openai-2.24.0-py3-none-any.whl", hash = "sha256:fed30480d7d6c884303287bde864980a4b137b60553ffbcf9ab4a233b7a73d94", size = 1120122, upload-time = "2026-02-24T20:02:05.669Z" },
 ]
 
 [[package]]
@@ -1690,7 +1690,7 @@ wheels = [
 
 [[package]]
 name = "pytest"
-version = "9.0.2"
+version = "9.0.3"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "colorama", marker = "sys_platform == 'win32'" },
@@ -1699,9 +1699,9 @@ dependencies = [
     { name = "pluggy" },
     { name = "pygments" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/d1/db/7ef3487e0fb0049ddb5ce41d3a49c235bf9ad299b6a25d5780a89f19230f/pytest-9.0.2.tar.gz", hash = "sha256:75186651a92bd89611d1d9fc20f0b4345fd827c41ccd5c299a868a05d70edf11", size = 1568901, upload-time = "2025-12-06T21:30:51.014Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/7d/0d/549bd94f1a0a402dc8cf64563a117c0f3765662e2e668477624baeec44d5/pytest-9.0.3.tar.gz", hash = "sha256:b86ada508af81d19edeb213c681b1d48246c1a91d304c6c81a427674c17eb91c", size = 1572165, upload-time = "2026-04-07T17:16:18.027Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/3b/ab/b3226f0bd7cdcf710fbede2b3548584366da3b19b5021e74f5bde2a8fa3f/pytest-9.0.2-py3-none-any.whl", hash = "sha256:711ffd45bf766d5264d487b917733b453d917afd2b0ad65223959f59089f875b", size = 374801, upload-time = "2025-12-06T21:30:49.154Z" },
+    { url = "https://files.pythonhosted.org/packages/d4/24/a372aaf5c9b7208e7112038812994107bc65a84cd00e0354a88c2c77a617/pytest-9.0.3-py3-none-any.whl", hash = "sha256:2c5efc453d45394fdd706ade797c0a81091eccd1d6e4bccfcd476e2b8e0ab5d9", size = 375249, upload-time = "2026-04-07T17:16:16.13Z" },
 ]
 
 [[package]]
@@ -1900,7 +1900,7 @@ wheels = [
 
 [[package]]
 name = "requests"
-version = "2.32.5"
+version = "2.33.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "certifi" },
@@ -1908,9 +1908,9 @@ dependencies = [
     { name = "idna" },
     { name = "urllib3" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/c9/74/b3ff8e6c8446842c3f5c837e9c3dfcfe2018ea6ecef224c710c85ef728f4/requests-2.32.5.tar.gz", hash = "sha256:dbba0bac56e100853db0ea71b82b4dfd5fe2bf6d3754a8893c3af500cec7d7cf", size = 134517, upload-time = "2025-08-18T20:46:02.573Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/34/64/8860370b167a9721e8956ae116825caff829224fbca0ca6e7bf8ddef8430/requests-2.33.0.tar.gz", hash = "sha256:c7ebc5e8b0f21837386ad0e1c8fe8b829fa5f544d8df3b2253bff14ef29d7652", size = 134232, upload-time = "2026-03-25T15:10:41.586Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/1e/db/4254e3eabe8020b458f1a747140d32277ec7a271daf1d235b70dc0b4e6e3/requests-2.32.5-py3-none-any.whl", hash = "sha256:2462f94637a34fd532264295e186976db0f5d453d1cdd31473c85a6a161affb6", size = 64738, upload-time = "2025-08-18T20:46:00.542Z" },
+    { url = "https://files.pythonhosted.org/packages/56/5d/c814546c2333ceea4ba42262d8c4d55763003e767fa169adc693bd524478/requests-2.33.0-py3-none-any.whl", hash = "sha256:3324635456fa185245e24865e810cecec7b4caf933d7eb133dcde67d48cee69b", size = 65017, upload-time = "2026-03-25T15:10:40.382Z" },
 ]
 
 [[package]]
@@ -2224,7 +2224,7 @@ wheels = [
 
 [[package]]
 name = "typer"
-version = "0.24.1"
+version = "0.23.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "annotated-doc" },
@@ -2232,9 +2232,9 @@ dependencies = [
     { name = "rich" },
     { name = "shellingham" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/f5/24/cb09efec5cc954f7f9b930bf8279447d24618bb6758d4f6adf2574c41780/typer-0.24.1.tar.gz", hash = "sha256:e39b4732d65fbdcde189ae76cf7cd48aeae72919dea1fdfc16593be016256b45", size = 118613, upload-time = "2026-02-21T16:54:40.609Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/fd/07/b822e1b307d40e263e8253d2384cf98c51aa2368cc7ba9a07e523a1d964b/typer-0.23.1.tar.gz", hash = "sha256:2070374e4d31c83e7b61362fd859aa683576432fd5b026b060ad6b4cd3b86134", size = 120047, upload-time = "2026-02-13T10:04:30.984Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/4a/91/48db081e7a63bb37284f9fbcefda7c44c277b18b0e13fbc36ea2335b71e6/typer-0.24.1-py3-none-any.whl", hash = "sha256:112c1f0ce578bfb4cab9ffdabc68f031416ebcc216536611ba21f04e9aa84c9e", size = 56085, upload-time = "2026-02-21T16:54:41.616Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/91/9b286ab899c008c2cb05e8be99814807e7fbbd33f0c0c960470826e5ac82/typer-0.23.1-py3-none-any.whl", hash = "sha256:3291ad0d3c701cbf522012faccfbb29352ff16ad262db2139e6b01f15781f14e", size = 56813, upload-time = "2026-02-13T10:04:32.008Z" },
 ]
 
 [[package]]

gitnexus-claude-plugin/hooks/gitnexus-hook.js

@@ -31,11 +31,25 @@ function readInput() {
  * Find the .gitnexus directory by walking up from startDir.
  * Returns the path to .gitnexus/ or null if not found.
  */
-function findGitNexusDir(startDir) {
-  let dir = startDir || process.cwd();
+function isGlobalRegistryDir(candidate) {
+  if (fs.existsSync(path.join(candidate, 'meta.json'))) return false;
+  return (
+    fs.existsSync(path.join(candidate, 'registry.json')) ||
+    fs.existsSync(path.join(candidate, 'repos'))
+  );
+}
+
+/**
+ * Walk up from `startDir` looking for a non-registry `.gitnexus/` folder.
+ * Returns the path to `.gitnexus/` or null if not found within 5 levels.
+ */
+function walkForGitNexusDir(startDir) {
+  let dir = startDir;
   for (let i = 0; i < 5; i++) {
     const candidate = path.join(dir, '.gitnexus');
-    if (fs.existsSync(candidate)) return candidate;
+    if (fs.existsSync(candidate)) {
+      if (!isGlobalRegistryDir(candidate)) return candidate;
+    }
     const parent = path.dirname(dir);
     if (parent === dir) break;
     dir = parent;
@@ -43,6 +57,51 @@ function findGitNexusDir(startDir) {
   return null;
 }
 
+/**
+ * Resolve the canonical (main) worktree root for `cwd`, when `cwd` is inside
+ * any git working tree — including a *linked* worktree created via
+ * `git worktree add`. Linked worktrees never contain `.gitnexus/`, so the
+ * upward walk from cwd alone misses the index. Returns null when `cwd` is
+ * not inside a git repo or `git` is not available.
+ *
+ * Implementation: `git rev-parse --git-common-dir` resolves to the canonical
+ * `.git/` directory (or `.git/worktrees/...` parent) that is shared across
+ * all linked worktrees. The canonical repo root is its parent directory.
+ */
+function findCanonicalRepoRoot(cwd) {
+  try {
+    const result = spawnSync('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], {
+      encoding: 'utf-8',
+      timeout: 2000,
+      cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    if (result.error || result.status !== 0) return null;
+    const commonDir = (result.stdout || '').trim();
+    if (!commonDir || !path.isAbsolute(commonDir)) return null;
+    return path.dirname(commonDir);
+  } catch {
+    return null;
+  }
+}
+
+function findGitNexusDir(startDir) {
+  const cwd = startDir || process.cwd();
+
+  // Fast path: the cwd is inside the canonical repo (most common case).
+  const fromCwd = walkForGitNexusDir(cwd);
+  if (fromCwd) return fromCwd;
+
+  // Fallback: cwd may be inside a linked git worktree whose `.gitnexus/`
+  // only lives in the canonical repo root. Resolve the shared git dir
+  // and retry from there.
+  const canonicalRoot = findCanonicalRepoRoot(cwd);
+  if (canonicalRoot && canonicalRoot !== cwd) {
+    return walkForGitNexusDir(canonicalRoot);
+  }
+  return null;
+}
+
 /**
  * Extract search pattern from tool input.
  */

gitnexus-claude-plugin/skills/gitnexus-cli/SKILL.md

@@ -21,6 +21,7 @@ Run from the project root. This parses all source files, builds the knowledge gr
 |------|--------|
 | `--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. |
 
 **When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale.
 

gitnexus-shared/package-lock.json

@@ -8,13 +8,13 @@
       "name": "gitnexus-shared",
       "version": "1.0.0",
       "devDependencies": {
-        "typescript": "^6.0.2"
+        "typescript": "^6.0.3"
       }
     },
     "node_modules/typescript": {
-      "version": "6.0.2",
-      "resolved": "https://registry.npmjs.org/typescript/-/typescript-6.0.2.tgz",
-      "integrity": "sha512-bGdAIrZ0wiGDo5l8c++HWtbaNCWTS4UTv7RaTH/ThVIgjkveJt83m74bBHMJkuCbslY8ixgLBVZJIOiQlQTjfQ==",
+      "version": "6.0.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-6.0.3.tgz",
+      "integrity": "sha512-y2TvuxSZPDyQakkFRPZHKFm+KKVqIisdg9/CZwm9ftvKXLP8NRWj38/ODjNbr43SsoXqNuAisEf1GdCxqWcdBw==",
       "dev": true,
       "license": "Apache-2.0",
       "bin": {

gitnexus-shared/package.json

@@ -20,6 +20,6 @@
     "src"
   ],
   "devDependencies": {
-    "typescript": "^6.0.2"
+    "typescript": "^6.0.3"
   }
 }

gitnexus-shared/src/index.ts

@@ -134,7 +134,11 @@ export type {
 // Scope tree spine + position lookup (RFC §2.2 + §3.1; Ring 2 SHARED #912)
 export { makeScopeId, clearScopeIdInternPool } from './scope-resolution/scope-id.js';
 export type { ScopeIdInput } from './scope-resolution/scope-id.js';
-export { buildScopeTree, ScopeTreeInvariantError } from './scope-resolution/scope-tree.js';
+export {
+  buildScopeTree,
+  canParentScope,
+  ScopeTreeInvariantError,
+} from './scope-resolution/scope-tree.js';
 export type { ScopeTree } from './scope-resolution/scope-tree.js';
 export { buildPositionIndex } from './scope-resolution/position-index.js';
 export type { PositionIndex } from './scope-resolution/position-index.js';

gitnexus-shared/src/scope-resolution/finalize-algorithm.ts

@@ -26,9 +26,9 @@
  * (`resolveImportTarget`, `expandsWildcardTo`, `mergeBindings`) that
  * match the LanguageProvider surface from #911.
  *
- * **Dynamic imports rule.** `kind === 'dynamic-unresolved'` passes through
- * as an `ImportEdge { kind: 'dynamic-unresolved', targetFile: null }`
- * with no `BindingRef`. They are parse-time signals, not linkable targets.
+ * **Non-binding imports rule.** `dynamic-unresolved` passes through with
+ * `targetFile: null`; `dynamic-resolved` and `side-effect` resolve to
+ * file-level `ImportEdge`s. None of these materialize `BindingRef`s.
  */
 
 import type { SymbolDefinition } from './symbol-definition.js';
@@ -45,20 +45,28 @@ export interface FinalizeFile {
   /**
    * Defs exported from this file — the "what other files can import by name"
    * surface. Typically those with `isExported: true` (the module's own
-   * declarations) plus, for multi-hop re-export chains, the re-exported
-   * names the parser chose to surface here.
+   * declarations); parsers MAY also surface re-exported names here as a
+   * shortcut, but it is no longer required for correctness.
    *
    * **Multi-hop re-export contract.** `finalize` resolves an edge
-   * `A → B (importedName: 'X')` by looking up `X` in `B.localDefs`. If B
-   * only has `export { X } from './C'` and the parser *does not* include
-   * `X` in `B.localDefs`, A's edge hits the fixpoint cap and is marked
-   * `linkStatus: 'unresolved'`. The fixpoint does NOT mutate `localDefs`
-   * across iterations — it is static input.
+   * `A → B (importedName: 'X')` by first looking up `X` in `B.localDefs`.
+   * If `B` only has `export { X } from './C'` and does NOT surface `X` in
+   * its own `localDefs`, `finalize` falls back to the precomputed
+   * per-file re-export closure (`buildReexportClosures`), which encodes
+   * every name reachable through `B`'s named and wildcard re-exports —
+   * including transitively through cyclic SCCs. The lookup is O(1) and
+   * inherits the upstream `targetDefId`, populating `transitiveVia` with
+   * the file paths traversed to reach the leaf def.
    *
-   * Parsers that want multi-hop re-export chains to settle end-to-end must
-   * include re-exported names in the intermediate file's `localDefs` (with
-   * the original `DefId` of the source symbol). This keeps the algorithm
-   * O(1) per lookup and avoids graph-crawl during finalize.
+   * Surfacing re-exported names in `localDefs` is still a valid (and
+   * slightly cheaper) optimization: the direct lookup short-circuits the
+   * closure consult. Parsers SHOULD prefer surfacing names they can resolve
+   * statically (e.g., `export { X } from './c'` when `c.ts` is parsed in
+   * the same workspace), and rely on the closure for the long tail of
+   * barrel patterns.
+   *
+   * The fixpoint does NOT mutate `localDefs` across iterations — it is
+   * static input.
    */
   readonly localDefs: readonly SymbolDefinition[];
 }
@@ -85,7 +93,7 @@ export interface FinalizeHooks {
     targetRaw: string,
     fromFile: string,
     workspaceIndex: WorkspaceIndex,
-  ): string | null;
+  ): string | readonly string[] | null;
 
   /**
    * For a wildcard `import * from M`, return the names visible in the
@@ -119,20 +127,22 @@ export interface FinalizedScc {
 /**
  * Counters reported by `finalize`.
  *
- * **Counting granularity** — all edge counters are **per-`ParsedImport`**,
- * not per-materialized-`ImportEdge`. A single `wildcard` ParsedImport that
- * expands to N exports counts as one linked edge in these stats; the
- * materialized output (`FinalizeOutput.imports`) will have N edges for
- * that input. `dynamic-unresolved` ParsedImports count as linked (they
- * pass through with no `linkStatus`), so `linkedEdges` ≠ "has a
+ * **Counting granularity** — `totalEdges` is **per-generated-`ImportEdgeDraft`**,
+ * which may exceed the number of `ParsedImport` records when
+ * `resolveImportTarget` returns a multi-file array (e.g. Go package-scoped
+ * imports fan out to every `.go` file in the target directory). A single
+ * `wildcard` ParsedImport that expands to N exports also counts as one
+ * linked edge here; the materialized output (`FinalizeOutput.imports`) will
+ * have N edges for that input. `dynamic-unresolved` ParsedImports count as
+ * linked (they pass through with no `linkStatus`), so `linkedEdges` ≠ "has a
  * BindingRef" — use the `bindings` map for that.
  *
- * In other words: `totalEdges === input.parsedImports.length` summed
+ * In other words: `totalEdges >= input.parsedImports.length` summed
  * across files, and `linkedEdges + unresolvedEdges === totalEdges`.
  */
 export interface FinalizeStats {
   readonly totalFiles: number;
-  /** Total `ParsedImport` records seen across all files. */
+  /** Total `ImportEdgeDraft` records generated (≥ ParsedImport count). */
   readonly totalEdges: number;
   /**
    * `ParsedImport`s whose finalized edge does NOT carry
@@ -171,9 +181,9 @@ export function finalize(input: FinalizeInput, hooks: FinalizeHooks): FinalizeOu
   for (const file of input.files) {
     const drafts: ImportEdgeDraft[] = [];
     for (const parsed of file.parsedImports) {
-      const draft = makeEdgeDraft(parsed, file, hooks, input.workspaceIndex);
-      drafts.push(draft);
-      totalEdges++;
+      const draftArray = makeEdgeDrafts(parsed, file, hooks, input.workspaceIndex);
+      drafts.push(...draftArray);
+      totalEdges += draftArray.length;
     }
     edgeIndex.set(file.filePath, drafts);
   }
@@ -186,7 +196,8 @@ export function finalize(input: FinalizeInput, hooks: FinalizeHooks): FinalizeOu
     graph.set(file.filePath, new Set());
   }
   for (const [fromFile, drafts] of edgeIndex) {
-    const edges = graph.get(fromFile)!;
+    const edges = graph.get(fromFile);
+    if (edges === undefined) continue;
     for (const d of drafts) {
       if (d.targetFile !== null && byFilePath.has(d.targetFile)) {
         edges.add(d.targetFile);
@@ -197,6 +208,12 @@ export function finalize(input: FinalizeInput, hooks: FinalizeHooks): FinalizeOu
   // ── Phase 2: Tarjan SCC → reverse-topological list of SCCs.
   const sccs = tarjanSccs(graph);
 
+  // ── Phase 2.5: precompute the per-file re-export closure (iterative,
+  // SCC-condensed). Eliminates the recursive crawl that the per-edge
+  // `tryFinalize` call site used to do; lookups are O(1) afterwards.
+  // See `buildReexportClosures` for the algorithm.
+  const reexportClosures = buildReexportClosures(input.files, byFilePath, edgeIndex);
+
   // ── Phase 3: process SCCs in reverse-topological order (leaves first).
   // Within each SCC, run a bounded fixpoint that resolves intra-SCC edges.
   // Edges leaving the SCC are already resolved (their target SCC is
@@ -217,10 +234,11 @@ export function finalize(input: FinalizeInput, hooks: FinalizeHooks): FinalizeOu
       progressed = false;
       iterations++;
       for (const filePath of scc.files) {
-        const drafts = edgeIndex.get(filePath)!;
+        const drafts = edgeIndex.get(filePath);
+        if (drafts === undefined) continue;
         for (const draft of drafts) {
           if (draft.finalized !== null) continue;
-          const finalized = tryFinalize(draft, byFilePath);
+          const finalized = tryFinalize(draft, byFilePath, reexportClosures);
           if (finalized !== null) {
             draft.finalized = finalized;
             progressed = true;
@@ -231,7 +249,8 @@ export function finalize(input: FinalizeInput, hooks: FinalizeHooks): FinalizeOu
 
     // Any drafts still not finalized within this SCC hit the cap → unresolved.
     for (const filePath of scc.files) {
-      const drafts = edgeIndex.get(filePath)!;
+      const drafts = edgeIndex.get(filePath);
+      if (drafts === undefined) continue;
       for (const draft of drafts) {
         if (draft.finalized !== null) continue;
         draft.finalized = {
@@ -245,10 +264,14 @@ export function finalize(input: FinalizeInput, hooks: FinalizeHooks): FinalizeOu
   // ── Phase 4: collect finalized `ImportEdge[]` per module scope, preserving
   // input order within each file, and wildcard-expand where applicable.
   for (const file of input.files) {
-    const drafts = edgeIndex.get(file.filePath)!;
+    const drafts = edgeIndex.get(file.filePath);
+    if (drafts === undefined) continue;
     const finalized: ImportEdge[] = [];
     for (const d of drafts) {
-      const edge = d.finalized!;
+      const edge = d.finalized;
+      if (edge === null) {
+        throw new Error(`Invariant violated: import edge was not finalized for ${file.filePath}`);
+      }
       if (d.source.kind === 'wildcard' && edge.linkStatus !== 'unresolved') {
         // Produce one `wildcard-expanded` ImportEdge per exported name.
         const expanded = expandWildcard(edge, byFilePath, hooks, input.workspaceIndex);
@@ -299,12 +322,12 @@ interface ImportEdgeDraft {
   finalized: ImportEdge | null;
 }
 
-function makeEdgeDraft(
+function makeEdgeDrafts(
   parsed: ParsedImport,
   file: FinalizeFile,
   hooks: FinalizeHooks,
   workspace: WorkspaceIndex,
-): ImportEdgeDraft {
+): ImportEdgeDraft[] {
   // Dynamic-unresolved passes through — no `BindingRef`, no target file.
   if (parsed.kind === 'dynamic-unresolved') {
     const base: ImportEdge = {
@@ -313,59 +336,80 @@ function makeEdgeDraft(
       targetExportedName: '',
       kind: 'dynamic-unresolved',
     };
-    return {
-      source: parsed,
-      fromFile: file.filePath,
-      fromScope: file.moduleScope,
-      targetFile: null,
-      base,
-      finalized: base, // already fully finalized
-    };
+    return [
+      {
+        source: parsed,
+        fromFile: file.filePath,
+        fromScope: file.moduleScope,
+        targetFile: null,
+        base,
+        finalized: base, // already fully finalized
+      },
+    ];
   }
 
   const targetFile = hooks.resolveImportTarget(parsed.targetRaw ?? '', file.filePath, workspace);
 
   // Edge is unresolvable at the file level — mark unresolved now.
   if (targetFile === null) {
-    const edgeKind = parsed.kind === 'wildcard' ? 'wildcard-expanded' : parsed.kind;
-    const localName = parsed.kind === 'wildcard' ? '' : parsed.localName;
-    const targetExportedName = extractExportedName(parsed);
     const base: ImportEdge = {
-      localName,
+      localName: extractLocalName(parsed),
       targetFile: null,
-      targetExportedName,
-      kind: edgeKind,
+      targetExportedName: extractExportedName(parsed),
+      kind: edgeKindFor(parsed),
       linkStatus: 'unresolved',
     };
+    return [
+      {
+        source: parsed,
+        fromFile: file.filePath,
+        fromScope: file.moduleScope,
+        targetFile: null,
+        base,
+        finalized: base,
+      },
+    ];
+  }
+
+  // Resolvable at the file level; intra-SCC fixpoint may still fail to fill
+  // in `targetDefId` (e.g., symbol not exported from target). Side-effect
+  // and resolved-dynamic imports are terminal at the file level — no
+  // `targetDefId` needed since they materialize no `BindingRef`. Pre-
+  // finalize them here so the fixpoint loop skips them entirely.
+  const targetFiles = Array.isArray(targetFile) ? targetFile : [targetFile];
+  const isFileLevelTerminal = parsed.kind === 'side-effect' || parsed.kind === 'dynamic-resolved';
+  return targetFiles.map((tf) => {
+    const base: ImportEdge = {
+      localName: extractLocalName(parsed),
+      targetFile: tf,
+      targetExportedName: extractExportedName(parsed),
+      kind: edgeKindFor(parsed),
+    };
     return {
       source: parsed,
       fromFile: file.filePath,
       fromScope: file.moduleScope,
-      targetFile: null,
+      targetFile: tf,
       base,
-      finalized: base,
+      finalized: isFileLevelTerminal ? base : null,
     };
-  }
+  });
+}
 
-  // Resolvable at the file level; intra-SCC fixpoint may still fail to fill
-  // in `targetDefId` (e.g., symbol not exported from target).
-  const edgeKind = parsed.kind === 'wildcard' ? 'wildcard-expanded' : parsed.kind;
-  const localName = parsed.kind === 'wildcard' ? '' : parsed.localName;
-  const targetExportedName = extractExportedName(parsed);
-  const base: ImportEdge = {
-    localName,
-    targetFile,
-    targetExportedName,
-    kind: edgeKind,
-  };
-  return {
-    source: parsed,
-    fromFile: file.filePath,
-    fromScope: file.moduleScope,
-    targetFile,
-    base,
-    finalized: null,
-  };
+function edgeKindFor(parsed: ParsedImport): ImportEdge['kind'] {
+  if (parsed.kind === 'wildcard') return 'wildcard-expanded';
+  return parsed.kind;
+}
+
+function extractLocalName(parsed: ParsedImport): string {
+  switch (parsed.kind) {
+    case 'wildcard':
+    case 'side-effect':
+    case 'dynamic-resolved':
+      return '';
+    default:
+      return parsed.localName;
+  }
 }
 
 function extractExportedName(parsed: ParsedImport): string {
@@ -377,6 +421,8 @@ function extractExportedName(parsed: ParsedImport): string {
       return parsed.importedName;
     case 'wildcard':
     case 'dynamic-unresolved':
+    case 'dynamic-resolved':
+    case 'side-effect':
       return '';
   }
 }
@@ -386,6 +432,7 @@ function extractExportedName(parsed: ParsedImport): string {
 function tryFinalize(
   draft: ImportEdgeDraft,
   byFilePath: Map<string, FinalizeFile>,
+  reexportClosures: ReadonlyMap<string, FileReexportClosure>,
 ): ImportEdge | null {
   const targetFile = draft.targetFile;
   if (targetFile === null) return draft.base; // already terminal
@@ -423,22 +470,265 @@ function tryFinalize(
   const importedName = extractExportedName(draft.source);
   const exported = findExportByName(targetModule.localDefs, importedName);
 
-  if (exported === undefined) {
+  if (exported !== undefined) {
+    const transitiveVia =
+      draft.source.kind === 'reexport' ? Object.freeze([targetFile]) : undefined;
+    return {
+      ...draft.base,
+      targetModuleScope: targetModule.moduleScope,
+      targetDefId: exported.nodeId,
+      ...(transitiveVia !== undefined ? { transitiveVia } : {}),
+    };
+  }
+
+  // Multi-hop re-export follow. Barrel modules like
+  //   // models.ts
+  //   export { User } from './base';
+  // emit no local def for `User`; the name surfaces only via their own
+  // `reexport` edge. The per-file re-export closure built in phase 2.5
+  // already encodes every name reachable through that file's named and
+  // wildcard re-exports — including transitively through cyclic SCCs —
+  // so the lookup is O(1) and never recurses.
+  const followed = lookupReexportedName(reexportClosures, targetFile, importedName);
+  if (followed === null) {
     // Target resolvable but the name isn't exported — keep trying in case a
     // re-export inside the target's SCC surfaces it in a later iteration.
     return null;
   }
 
-  const transitiveVia = draft.source.kind === 'reexport' ? Object.freeze([targetFile]) : undefined;
+  const viaFiles = [targetFile, ...followed.via];
+  const transitiveVia =
+    draft.source.kind === 'reexport' || viaFiles.length > 1 ? Object.freeze(viaFiles) : undefined;
 
   return {
     ...draft.base,
     targetModuleScope: targetModule.moduleScope,
-    targetDefId: exported.nodeId,
+    targetDefId: followed.def.nodeId,
     ...(transitiveVia !== undefined ? { transitiveVia } : {}),
   };
 }
 
+// ─── Internal: re-export closure (phase 2.5) ───────────────────────────────
+
+/**
+ * Per-file map of `name → terminal def + via path` — i.e. every name
+ * importable from this file via its named/wildcard re-export chain
+ * (excluding the file's own `localDefs`, which the caller checks first
+ * via `findExportByName`). `via` is the ordered list of intermediate
+ * files traversed to reach the def.
+ *
+ * Built once per finalize pass. Lookups are O(1).
+ */
+type ReexportClosureEntry = { readonly def: SymbolDefinition; readonly via: readonly string[] };
+type FileReexportClosure = ReadonlyMap<string, ReexportClosureEntry>;
+
+/**
+ * Build per-file re-export closures.
+ *
+ * **Algorithm.** Iterative SCC-condensed reverse-topological propagation,
+ * structurally identical to how `finalize` itself processes the file-
+ * level import graph. Replaces the legacy recursive
+ * `followReexportChain` crawl with a bounded, stack-safe pass:
+ *
+ *   1. **Sub-graph.** Build a directed graph whose edges are
+ *      `reexport` and `wildcard` drafts only (regular imports do not
+ *      contribute to the export surface, and `namespace`/
+ *      `reexport-namespace` are terminal — their target def lives in
+ *      `localDefs`).
+ *   2. **SCC condensation.** Run the same iterative `tarjanSccs` over
+ *      the sub-graph. Output is in reverse-topological order (leaves
+ *      first), so when we process an SCC every out-of-SCC neighbor
+ *      already has its closure populated.
+ *   3. **Per-SCC propagation.**
+ *        * Acyclic singleton: one pass — read neighbors' (already
+ *          fully populated) closures.
+ *        * Cyclic SCC (cycle ≥ 2 files, or self-loop): bounded
+ *          fixpoint inside the SCC, capped at `|SCC| + 1` iterations
+ *          (each iteration propagates names one hop further around
+ *          the cycle; first-wins precedence keeps the map monotone
+ *          so the fixpoint converges in at most |SCC| hops).
+ *
+ * **Precedence semantics — preserved from the recursive crawl.**
+ *   * Named re-exports take precedence over wildcards.
+ *   * Within each kind, declaration order wins (first match for a
+ *     given exported name is kept; later drafts skip).
+ *
+ * **Complexity.**
+ *   * Pre-pass: O(V + E_re) for SCC, plus O(|SCC| × Σ drafts) per cyclic
+ *     SCC. For tree-shaped barrel graphs (the common case) it
+ *     collapses to O(E_re) total.
+ *   * Per-edge lookup at finalize time: O(1).
+ *   * `transitiveVia` preserves the exact file path chain for diagnostics
+ *     and graph provenance. Building those arrays copies the inherited path,
+ *     which is O(depth²) in a pathological single-name barrel chain; practical
+ *     TypeScript barrel chains are shallow enough that we keep exact paths
+ *     instead of capping or summarizing them.
+ *   * Pathological deep chains that previously needed
+ *     `MAX_REEXPORT_DEPTH=100` to bound stack growth now resolve
+ *     in full and are bounded only by available memory — the
+ *     iterative formulation has no call-stack ceiling.
+ */
+function buildReexportClosures(
+  files: readonly FinalizeFile[],
+  byFilePath: ReadonlyMap<string, FinalizeFile>,
+  edgeIndex: ReadonlyMap<string, ImportEdgeDraft[]>,
+): ReadonlyMap<string, FileReexportClosure> {
+  const closures = new Map<string, Map<string, ReexportClosureEntry>>();
+  for (const file of files) closures.set(file.filePath, new Map());
+
+  // ── Step 1: build the re-export sub-graph (only resolvable
+  // reexport/wildcard targets contribute edges).
+  const subGraph = new Map<string, Set<string>>();
+  for (const file of files) {
+    const targets = new Set<string>();
+    const drafts = edgeIndex.get(file.filePath);
+    if (drafts !== undefined) {
+      for (const d of drafts) {
+        if (d.source.kind !== 'reexport' && d.source.kind !== 'wildcard') continue;
+        if (d.targetFile === null) continue;
+        if (!byFilePath.has(d.targetFile)) continue;
+        targets.add(d.targetFile);
+      }
+    }
+    subGraph.set(file.filePath, targets);
+  }
+
+  // ── Step 2: SCC over the sub-graph. Reuses the same iterative Tarjan
+  // implementation that drives the file-level finalize loop, so any
+  // call-stack-safety guarantees there transfer here unchanged.
+  const subSccs = tarjanSccs(subGraph);
+
+  // ── Step 3: process SCCs in reverse-topological order. Acyclic
+  // singletons settle in one pass; cyclic SCCs run a bounded fixpoint.
+  for (const scc of subSccs) {
+    if (!scc.isCycle) {
+      const filePath = scc.files[0];
+      if (filePath !== undefined) {
+        populateFileClosure(filePath, byFilePath, edgeIndex, closures);
+      }
+      continue;
+    }
+    // Cap = |SCC| + 1. With first-wins precedence each name needs at
+    // most |SCC| iterations to propagate fully around the cycle; the
+    // extra iteration confirms no progress and breaks the loop.
+    const cap = scc.files.length + 1;
+    let progressed = true;
+    let iter = 0;
+    while (progressed && iter < cap) {
+      progressed = false;
+      iter++;
+      for (const filePath of scc.files) {
+        if (populateFileClosure(filePath, byFilePath, edgeIndex, closures)) {
+          progressed = true;
+        }
+      }
+    }
+  }
+
+  return closures;
+}
+
+/**
+ * Populate one file's re-export closure for one pass. Returns `true`
+ * iff the closure grew (signalling fixpoint progress to the caller).
+ *
+ * Walks the file's drafts in declaration order, named re-exports first
+ * (precedence), then wildcards. For each draft, attempts:
+ *   1. **Direct hit** — name exists in the target file's `localDefs`.
+ *   2. **Inherited** — name exists in the target file's already-populated
+ *      closure (which encodes the target's own re-export chain).
+ *
+ * `closures.get(targetFile)` may itself still be empty for in-SCC
+ * targets on the first iteration; the outer fixpoint loop handles
+ * that by re-invoking this function.
+ */
+function populateFileClosure(
+  filePath: string,
+  byFilePath: ReadonlyMap<string, FinalizeFile>,
+  edgeIndex: ReadonlyMap<string, ImportEdgeDraft[]>,
+  closures: Map<string, Map<string, ReexportClosureEntry>>,
+): boolean {
+  const myClosure = closures.get(filePath);
+  if (myClosure === undefined) return false;
+  const before = myClosure.size;
+  const drafts = edgeIndex.get(filePath);
+  if (drafts === undefined) return false;
+
+  // Named re-exports — precedence over wildcards, declaration order
+  // first-wins for duplicates of the same exported name.
+  for (const draft of drafts) {
+    if (draft.source.kind !== 'reexport') continue;
+    const targetFile = draft.targetFile;
+    if (targetFile === null) continue;
+    const targetModule = byFilePath.get(targetFile);
+    if (targetModule === undefined) continue;
+
+    const localName = draft.source.localName;
+    if (myClosure.has(localName)) continue;
+
+    const importedName = draft.source.importedName;
+    const direct = findExportByName(targetModule.localDefs, importedName);
+    if (direct !== undefined) {
+      myClosure.set(localName, { def: direct, via: Object.freeze([targetFile]) });
+      continue;
+    }
+    const inherited = closures.get(targetFile)?.get(importedName);
+    if (inherited !== undefined) {
+      myClosure.set(localName, {
+        def: inherited.def,
+        via: Object.freeze([targetFile, ...inherited.via]),
+      });
+    }
+    // Else: target's closure is still empty (in-SCC, awaiting next
+    // iteration). Outer loop will revisit.
+  }
+
+  // Wildcard re-exports — fan out the target's own surface (localDefs
+  // + transitive closure). `myClosure.has(name)` checks below preserve
+  // the named-precedence and first-wins semantics from above.
+  for (const draft of drafts) {
+    if (draft.source.kind !== 'wildcard') continue;
+    const targetFile = draft.targetFile;
+    if (targetFile === null) continue;
+    const targetModule = byFilePath.get(targetFile);
+    if (targetModule === undefined) continue;
+
+    for (const def of targetModule.localDefs) {
+      const name = deriveSimpleName(def);
+      if (name === null || myClosure.has(name)) continue;
+      myClosure.set(name, { def, via: Object.freeze([targetFile]) });
+    }
+    const targetClosure = closures.get(targetFile);
+    if (targetClosure !== undefined) {
+      for (const [name, entry] of targetClosure) {
+        if (myClosure.has(name)) continue;
+        myClosure.set(name, {
+          def: entry.def,
+          via: Object.freeze([targetFile, ...entry.via]),
+        });
+      }
+    }
+  }
+
+  return myClosure.size > before;
+}
+
+/**
+ * O(1) lookup into a precomputed re-export closure. Replaces the legacy
+ * recursive `followReexportChain` traversal with a single map indexing.
+ */
+function lookupReexportedName(
+  closures: ReadonlyMap<string, FileReexportClosure>,
+  filePath: string,
+  name: string,
+): { def: SymbolDefinition; via: readonly string[] } | null {
+  const closure = closures.get(filePath);
+  if (closure === undefined) return null;
+  const entry = closure.get(name);
+  if (entry === undefined) return null;
+  return { def: entry.def, via: entry.via };
+}
+
 /**
  * The "simple" (unqualified) name of a def, for import-name matching.
  *
@@ -459,10 +749,58 @@ function findExportByName(
   defs: readonly SymbolDefinition[],
   name: string,
 ): SymbolDefinition | undefined {
+  // GENERIC RULE (applies to every language using this finalize
+  // algorithm): when MULTIPLE `SymbolDefinition`s share the same simple
+  // name in `localDefs`, prefer callable / type-like defs over plain
+  // value defs (`Variable`, `Property`, …). The CALLER side of an
+  // import almost always wants the callable, not a value shadow that
+  // happens to share the name — and without a deterministic
+  // preference, capture order silently decides which def the import
+  // binds to.
+  //
+  // The single-def case is unchanged: when only one def has the name,
+  // it's returned regardless of its type (the `fallback` path below).
+  //
+  // TypeScript is the first known language where this matters in
+  // practice: `const fn = () => {}` emits BOTH a `Function` def (from
+  // `@declaration.function` on the inner arrow) AND a `Variable` def
+  // (from the generic `@declaration.variable` pattern matching the
+  // wrapping `lexical_declaration`), and consumers of `import { fn }`
+  // need to bind to the callable. Other migrated languages don't
+  // currently produce dual emits of this shape, so the rule is a no-op
+  // for them today; future languages get the same correctness
+  // guarantee for free if they ever do.
+  //
+  // See `gitnexus/test/integration/resolvers/typescript-hof-callbacks.test.ts`
+  // for the cross-file regression this rule prevents.
+  let fallback: SymbolDefinition | undefined;
   for (const d of defs) {
-    if (deriveSimpleName(d) === name) return d;
+    if (deriveSimpleName(d) !== name) continue;
+    if (isCallableOrTypeLike(d.type)) return d;
+    if (fallback === undefined) fallback = d;
   }
-  return undefined;
+  return fallback;
+}
+
+const CALLABLE_OR_TYPE_LIKE: ReadonlySet<string> = new Set([
+  'Function',
+  'Method',
+  'Constructor',
+  'Class',
+  'Interface',
+  'Enum',
+  'Struct',
+  'Record',
+  'Trait',
+  'Namespace',
+  'Module',
+  'TypeAlias',
+  'Type',
+  'Typedef',
+]);
+
+function isCallableOrTypeLike(type: string): boolean {
+  return CALLABLE_OR_TYPE_LIKE.has(type);
 }
 
 function countEdgesWithin(edgeIndex: Map<string, ImportEdgeDraft[]>, files: Set<string>): number {
@@ -522,6 +860,17 @@ function materializeBindings(
 ): ReadonlyMap<ScopeId, ReadonlyMap<string, readonly BindingRef[]>> {
   const out = new Map<ScopeId, ReadonlyMap<string, readonly BindingRef[]>>();
 
+  // Build a `nodeId → SymbolDefinition` index once across all files
+  // (O(N_files × D_defs)) so the per-edge lookup below is O(1) instead
+  // of a full linear scan. At realistic TypeScript monorepo scale
+  // (~5k files × ~50 defs × ~100k linked import edges) this is the
+  // difference between ~25 s and a few ms inside finalize. The map
+  // is local to this pass — no cross-pass state leaks.
+  const defById = new Map<string, SymbolDefinition>();
+  for (const f of files) {
+    for (const d of f.localDefs) defById.set(d.nodeId, d);
+  }
+
   for (const file of files) {
     const scopeBindings = new Map<string, readonly BindingRef[]>();
 
@@ -538,10 +887,7 @@ function materializeBindings(
     const imports = linkedByScope.get(file.moduleScope) ?? [];
     for (const edge of imports) {
       if (edge.targetDefId === undefined || edge.linkStatus === 'unresolved') continue;
-      // Every def the importing file needs to reach is in some other file's
-      // `localDefs`; walk all files to find it. In practice we could index
-      // this, but at finalize-time N(files) is small per workspace pass.
-      const def = findDefById(files, edge.targetDefId);
+      const def = defById.get(edge.targetDefId);
       if (def === undefined) continue;
 
       const origin: BindingRef['origin'] =
@@ -571,15 +917,6 @@ function materializeBindings(
   return out;
 }
 
-function findDefById(files: readonly FinalizeFile[], defId: string): SymbolDefinition | undefined {
-  for (const f of files) {
-    for (const d of f.localDefs) {
-      if (d.nodeId === defId) return d;
-    }
-  }
-  return undefined;
-}
-
 // ─── Internal: Tarjan SCC ──────────────────────────────────────────────────
 
 /**
@@ -607,7 +944,8 @@ function tarjanSccs(graph: ReadonlyMap<string, ReadonlySet<string>>): FinalizedS
       entered: false,
     });
     while (iterStack.length > 0) {
-      const frame = iterStack[iterStack.length - 1]!;
+      const frame = iterStack[iterStack.length - 1];
+      if (frame === undefined) break;
 
       if (!frame.entered) {
         frame.entered = true;
@@ -625,7 +963,10 @@ function tarjanSccs(graph: ReadonlyMap<string, ReadonlySet<string>>): FinalizedS
           const scc: string[] = [];
           let selfInCycle = false;
           while (true) {
-            const w = stack.pop()!;
+            const w = stack.pop();
+            if (w === undefined) {
+              throw new Error(`Invariant violated: Tarjan stack exhausted at ${frame.node}`);
+            }
             onStack.delete(w);
             scc.push(w);
             // A single-file self-loop counts as a cycle.
@@ -640,8 +981,16 @@ function tarjanSccs(graph: ReadonlyMap<string, ReadonlySet<string>>): FinalizedS
         iterStack.pop();
         // Propagate lowlink to parent.
         if (iterStack.length > 0) {
-          const parent = iterStack[iterStack.length - 1]!;
-          lowlink.set(parent.node, Math.min(lowlink.get(parent.node)!, lowlink.get(frame.node)!));
+          const parent = iterStack[iterStack.length - 1];
+          if (parent !== undefined) {
+            lowlink.set(
+              parent.node,
+              Math.min(
+                requiredNumber(lowlink, parent.node, 'lowlink'),
+                requiredNumber(lowlink, frame.node, 'lowlink'),
+              ),
+            );
+          }
         }
         continue;
       }
@@ -654,10 +1003,24 @@ function tarjanSccs(graph: ReadonlyMap<string, ReadonlySet<string>>): FinalizedS
           entered: false,
         });
       } else if (onStack.has(child)) {
-        lowlink.set(frame.node, Math.min(lowlink.get(frame.node)!, index.get(child)!));
+        lowlink.set(
+          frame.node,
+          Math.min(
+            requiredNumber(lowlink, frame.node, 'lowlink'),
+            requiredNumber(index, child, 'index'),
+          ),
+        );
       }
     }
   }
 
   return sccs;
 }
+
+function requiredNumber(map: ReadonlyMap<string, number>, key: string, label: string): number {
+  const value = map.get(key);
+  if (value === undefined) {
+    throw new Error(`Invariant violated: missing Tarjan ${label} for ${key}`);
+  }
+  return value;
+}

gitnexus-shared/src/scope-resolution/parsed-file.ts

@@ -37,6 +37,18 @@
  * `localDefs`. A `ParsedFile` is trivially convertible to a `FinalizeFile`
  * by picking those four fields, so the finalize orchestrator threads
  * ParsedFile through to the shared algorithm without shape-shifting.
+ *
+ * ## Source-of-truth invariant
+ *
+ * `ParsedFile` is the single semantic model consumed by both the legacy
+ * DAG (`gitnexus/src/core/ingestion/` outside `scope-resolution/`) and
+ * the scope-resolution pipeline (`gitnexus/src/core/ingestion/scope-resolution/`).
+ * Downstream passes MUST NOT build a parallel parse representation; if
+ * a pass needs AST-level facts that `ParsedFile` doesn't expose, it
+ * should reuse the orchestrator's `treeCache` rather than re-invoke
+ * `parser.parse(...)` on its own. See the
+ * `ScopeResolver` contract (`gitnexus/src/core/ingestion/scope-resolution/contract/scope-resolver.ts`)
+ * for the full list of invariants downstream consumers rely on.
  */
 
 import type { Scope, ScopeId } from './types.js';

gitnexus-shared/src/scope-resolution/reference-site.ts

@@ -71,4 +71,12 @@ export interface ReferenceSite {
   readonly explicitReceiver?: { readonly name: string };
   /** Argument count at the call site; used by `provider.arityCompatibility`. */
   readonly arity?: number;
+  /**
+   * Inferred argument types at the call site, one per argument. An
+   * empty-string entry means "unknown" — consumers narrowing overload
+   * candidates treat unknown as any-match. Populated by languages
+   * that can derive types from literals / constructor expressions
+   * (C#: `42` → `'int'`, `"alice"` → `'string'`).
+   */
+  readonly argumentTypes?: readonly string[];
 }

gitnexus-shared/src/scope-resolution/scope-tree.ts

@@ -119,10 +119,10 @@ export function buildScopeTree(scopes: readonly Scope[]): ScopeTree {
         `Scope '${scope.id}' (${scope.filePath}) has parent '${parent.id}' in a different file (${parent.filePath}). Parent/child scopes must share filePath.`,
       );
     }
-    if (!rangeStrictlyContains(parent.range, scope.range)) {
+    if (!canParentScope(parent.range, scope.range, parent.kind, scope.kind)) {
       throw new ScopeTreeInvariantError(
         'parent-must-contain-child',
-        `Parent scope '${parent.id}' at ${formatRange(parent.range)} does not strictly contain child '${scope.id}' at ${formatRange(scope.range)}.`,
+        `Parent scope '${parent.id}' at ${formatRange(parent.range)} does not contain child '${scope.id}' at ${formatRange(scope.range)} (allowed: strict containment, or equal-range Module-as-parent).`,
       );
     }
 
@@ -230,6 +230,47 @@ function rangeStrictlyContains(outer: Range, inner: Range): boolean {
   return outerStartsAtOrBefore && outerEndsAtOrAfter;
 }
 
+function rangesEqual(a: Range, b: Range): boolean {
+  return (
+    a.startLine === b.startLine &&
+    a.startCol === b.startCol &&
+    a.endLine === b.endLine &&
+    a.endCol === b.endCol
+  );
+}
+
+/**
+ * Whether `outer` (kind `outerKind`) is a valid parent for `inner` (kind
+ * `innerKind`).
+ *
+ * Strict containment is the general rule. The single carve-out is the
+ * `Module`/non-`Module` pair whose ranges are exactly equal — this happens
+ * naturally when tree-sitter reports identical byte spans for the
+ * `compilation_unit` (or equivalent file-root construct) and the file's
+ * single top-level scope. Common shape: a C# file consisting of nothing
+ * but `namespace X { ... }` with no leading or trailing trivia outside the
+ * namespace's `{}` body — `compilation_unit` and `namespace_declaration`
+ * both span exactly the same byte range. The `Module` is the universal
+ * outer of any file-level scope by language semantics, so coincident
+ * ranges should not break the parent chain.
+ *
+ * The carve-out is direction-asymmetric: only `Module`-as-outer parents a
+ * same-range non-`Module`, never the reverse. This preserves the
+ * acyclicity buildScopeTree relies on, and matches the corresponding
+ * helper in `scope-extractor.ts` so `pass1BuildScopes` and the validator
+ * agree on what a well-formed parent edge looks like.
+ */
+export function canParentScope(
+  outer: Range,
+  inner: Range,
+  outerKind: Scope['kind'],
+  innerKind: Scope['kind'],
+): boolean {
+  if (rangeStrictlyContains(outer, inner)) return true;
+  if (outerKind === 'Module' && innerKind !== 'Module' && rangesEqual(outer, inner)) return true;
+  return false;
+}
+
 /**
  * Two ranges overlap when neither finishes before the other begins. Ranges
  * that merely touch at a single boundary point (`a.end === b.start`) do

gitnexus-shared/src/scope-resolution/types.ts

@@ -10,8 +10,16 @@
  * Lifecycle contract (RFC §2.8): scopes are **constructed during extraction,
  * linked during finalize, immutable after finalize**. All fields are
  * `readonly` at the type level; `Object.freeze` is applied at runtime in dev
- * builds. `ReferenceIndex` is the sole structure populated after freeze — by
- * resolution, before emission.
+ * builds.
+ *
+ * Two structures are populated after freeze:
+ *   1. `ReferenceIndex` — by resolution, before emission.
+ *   2. `ScopeResolutionIndexes.bindingAugmentations` — the dedicated
+ *      append-only post-finalize binding channel (e.g. C# same-namespace
+ *      cross-file fanout). The companion `indexes.bindings` is the
+ *      finalize-output channel and is deep-frozen by `materializeBindings`;
+ *      walkers consult both via `lookupBindingsAt`. See `ScopeResolver`
+ *      Invariant I8 for the full lifecycle contract.
  */
 
 import type { NodeLabel } from '../graph/types.js';
@@ -182,6 +190,42 @@ export type ParsedImport =
       readonly localName: string;
       /** Source text of the unresolved expression when available; `null` otherwise. */
       readonly targetRaw: string | null;
+    }
+  /**
+   * Lazy / dynamic import whose target IS a static string literal at parse
+   * time, so it can be linked to a concrete `targetFile`. No local name
+   * binding is materialized — `import('./m')` returns `Promise<Module>` and
+   * any consumer-visible names appear via subsequent `.then(({ X }) => …)`
+   * destructuring, which is outside the static-import surface. The edge
+   * exists for module-reachability and impact analysis (so editing `./m`
+   * still flags the dynamic importer as affected).
+   *
+   * Providers MUST only emit this kind when `targetRaw` is a literal
+   * string they can hand to `resolveImportTarget`; expression arguments
+   * stay `dynamic-unresolved`.
+   *
+   * Examples:
+   *   - JS `import('./feature')`                  → `{ kind: 'dynamic-resolved', targetRaw: './feature' }`
+   *   - JS `await import('@scope/pkg/sub')`       → `{ kind: 'dynamic-resolved', targetRaw: '@scope/pkg/sub' }`
+   */
+  | {
+      readonly kind: 'dynamic-resolved';
+      readonly targetRaw: string;
+    }
+  /**
+   * Bare-source / side-effect import that introduces no local name binding
+   * but still establishes a file-level dependency. Resolves to a concrete
+   * `targetFile` via `resolveImportTarget` and produces a file→file
+   * `ImportEdge` for module-reachability and impact analysis, with no
+   * `BindingRef` materialized.
+   *
+   * Examples:
+   *   - JS / TS `import './polyfill'`        → `{ kind: 'side-effect', targetRaw: './polyfill' }`
+   *   - Rust    `use foo::bar as _`          → side-effect (binding hidden under `_`)
+   */
+  | {
+      readonly kind: 'side-effect';
+      readonly targetRaw: string;
     };
 
 /**
@@ -253,7 +297,9 @@ export interface ImportEdge {
     | 'namespace'
     | 'wildcard-expanded'
     | 'reexport'
-    | 'dynamic-unresolved';
+    | 'dynamic-unresolved'
+    | 'dynamic-resolved'
+    | 'side-effect';
   /** Re-export chain, for provenance (e.g., `['./y']` when re-exported via `./y`). */
   readonly transitiveVia?: readonly string[];
   /** Set to `'unresolved'` when the SCC fixpoint could not link this edge. */

gitnexus-web/package.json

@@ -3,7 +3,7 @@
   "private": true,
   "version": "0.0.0",
   "engines": {
-    "node": ">=20.0.0"
+    "node": "^20.19.0 || >=22.12.0"
   },
   "type": "module",
   "scripts": {
@@ -19,59 +19,59 @@
   },
   "dependencies": {
     "gitnexus-shared": "file:../gitnexus-shared",
-    "@langchain/anthropic": "^1.3.10",
-    "@langchain/core": "^1.1.15",
-    "@langchain/google-genai": "^2.1.10",
-    "@langchain/langgraph": "^1.1.0",
-    "@langchain/ollama": "^1.2.0",
-    "@langchain/openai": "^1.2.2",
+    "@langchain/anthropic": "^1.3.27",
+    "@langchain/core": "^1.1.41",
+    "@langchain/google-genai": "^2.1.28",
+    "@langchain/langgraph": "^1.2.9",
+    "@langchain/ollama": "^1.2.6",
+    "@langchain/openai": "^1.4.5",
     "@sigma/edge-curve": "^3.1.0",
-    "@tailwindcss/vite": "^4.1.18",
+    "@tailwindcss/vite": "^4.2.4",
     "axios": "^1.13.2",
     "d3": "^7.9.0",
-    "dompurify": "^3.3.3",
+    "dompurify": "^3.4.2",
     "graphology": "^0.26.0",
     "graphology-indices": "^0.17.0",
     "graphology-layout-force": "^0.2.4",
     "graphology-layout-forceatlas2": "^0.10.1",
     "graphology-layout-noverlap": "^0.4.2",
     "graphology-utils": "^2.3.0",
-    "langchain": "^1.2.10",
+    "langchain": "^1.3.4",
     "lru-cache": "^11.2.4",
-    "lucide-react": "^0.562.0",
+    "lucide-react": "^1.11.0",
     "mermaid": "^11.14.0",
     "mnemonist": "^0.39.0",
     "pandemonium": "^2.4.0",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
     "react-markdown": "^10.1.0",
     "react-syntax-highlighter": "^16.1.0",
-    "react-zoom-pan-pinch": "^3.7.0",
+    "react-zoom-pan-pinch": "^4.0.3",
     "remark-gfm": "^4.0.1",
     "sigma": "^3.0.2",
-    "tailwindcss": "^4.2.2",
-    "uuid": "^13.0.0",
+    "tailwindcss": "^4.2.4",
+    "uuid": "^14.0.0",
     "zod": "^3.25.76"
   },
   "devDependencies": {
-    "@babel/types": "^7.28.5",
+    "@babel/types": "^7.29.0",
     "@playwright/test": "^1.58.2",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
     "@testing-library/user-event": "^14.6.1",
     "@types/dompurify": "^3.0.5",
-    "@types/node": "^24.10.1",
-    "@types/react": "^18.3.5",
-    "@types/react-dom": "^18.3.0",
+    "@types/node": "^25.6.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
     "@types/react-syntax-highlighter": "^15.5.13",
     "@vercel/node": "^5.5.16",
-    "@vitejs/plugin-react": "^5.1.0",
-    "@vitest/coverage-v8": "^3.2.4",
+    "@vitejs/plugin-react": "^5.1.4",
+    "@vitest/coverage-v8": "^4.1.5",
     "jsdom": "^29.0.2",
     "tree-sitter-wasms": "^0.1.13",
     "typescript": "^5.4.5",
-    "vite": "^5.2.0",
-    "vitest": "^3.2.4",
+    "vite": "^8.0.10",
+    "vitest": "^4.1.5",
     "wait-on": "^9.0.5"
   }
 }

gitnexus-web/src/hooks/useAutoScroll.ts

@@ -4,8 +4,8 @@ const DEFAULT_BOTTOM_THRESHOLD = 100;
 const USER_SCROLL_EPSILON = 5;
 
 export interface UseAutoScrollResult {
-  scrollContainerRef: React.RefObject<HTMLDivElement>;
-  messagesContainerRef: React.RefObject<HTMLDivElement>;
+  scrollContainerRef: React.RefObject<HTMLDivElement | null>;
+  messagesContainerRef: React.RefObject<HTMLDivElement | null>;
   isAtBottom: boolean;
   scrollToBottom: (behavior?: ScrollBehavior) => void;
 }

gitnexus-web/src/hooks/useSigma.ts

@@ -65,7 +65,7 @@ interface UseSigmaOptions {
 }
 
 interface UseSigmaReturn {
-  containerRef: React.RefObject<HTMLDivElement>;
+  containerRef: React.RefObject<HTMLDivElement | null>;
   sigmaRef: React.RefObject<Sigma | null>;
   setGraph: (graph: Graph<SigmaNodeAttributes, SigmaEdgeAttributes>) => void;
   zoomIn: () => void;

gitnexus-web/src/lib/lucide-icons.tsx

@@ -5,7 +5,42 @@
  * than directly from lucide-react. This provides a single place to manage
  * which icons are used and allows future optimization (e.g., tree-shaking
  * configuration, icon subset bundling) without touching every component.
+ *
+ * --- Why a local `Github` icon? ---
+ *
+ * Lucide removed all brand icons in v1
+ * (https://lucide.dev/guide/react/migration,
+ *  https://github.com/lucide-icons/lucide/blob/main/BRAND_LOGOS_STATEMENT.md),
+ * so `import { Github } from 'lucide-react'` no longer compiles.
+ *
+ * We replace it with the official mark from Primer Octicons — the icon set
+ * GitHub itself uses on github.com — copied verbatim. This was preferred over
+ * the alternatives because it:
+ *
+ *   1. Is the canonical GitHub-maintained source for the mark, kept in sync
+ *      with what users see on github.com.
+ *   2. Is MIT-licensed (Copyright (c) GitHub Inc.,
+ *      https://github.com/primer/octicons/blob/main/LICENSE), so embedding the
+ *      path data is permitted.
+ *   3. Adds zero new npm dependencies (vs. `@primer/octicons-react`,
+ *      `react-icons`, or `simple-icons`), keeping the web bundle lean.
+ *   4. Ships per-size hand-tuned glyphs (16 + 24) — the same approach Primer
+ *      uses — so the mark stays crisp at the small `h-4 w-4` sites in the
+ *      header and onboarding screens as well as at full size.
+ *
+ * Trademark note: the GitHub mark is a registered trademark of GitHub, Inc.
+ * (https://brand.github.com/foundations/logo). The MIT license covers our
+ * right to copy the SVG; trademark rules still govern *use*. We use the mark
+ * here only to link to GitHub and to indicate GitHub source-repo integration,
+ * which are explicitly permitted by GitHub's brand toolkit.
+ *
+ * SVG sources (copied verbatim, MIT, Copyright (c) GitHub Inc.):
+ *   - https://github.com/primer/octicons/blob/main/icons/mark-github-16.svg
+ *   - https://github.com/primer/octicons/blob/main/icons/mark-github-24.svg
  */
+import { forwardRef } from 'react';
+import type { LucideProps } from 'lucide-react';
+
 export {
   AlertCircle,
   AlertTriangle,
@@ -31,7 +66,6 @@ export {
   Folder,
   FolderOpen,
   GitBranch,
-  Github,
   Globe,
   Hash,
   Heart,
@@ -75,3 +109,63 @@ export {
   ZoomIn,
   ZoomOut,
 } from 'lucide-react';
+
+/**
+ * GitHub mark — local copy of Primer Octicons `mark-github-{16,24}`.
+ *
+ * Why this exists, why Primer Octicons, and the trademark caveat are documented
+ * at the top of this file. Please read that header before changing the SVG
+ * paths or swapping the source.
+ *
+ * API-compatible with `lucide-react` icons (`LucideProps`). The Octicons mark
+ * is a *filled* glyph, so the lucide-only stroke props (`strokeWidth`,
+ * `absoluteStrokeWidth`) are accepted for type parity but ignored. Color
+ * defaults to `currentColor`, so Tailwind `text-*` utilities work the same as
+ * with any other icon in this module.
+ */
+export const Github = forwardRef<SVGSVGElement, LucideProps>(function Github(
+  {
+    size = 24,
+    color = 'currentColor',
+    className,
+    strokeWidth: _strokeWidth,
+    absoluteStrokeWidth: _absoluteStrokeWidth,
+    ...rest
+  },
+  ref,
+) {
+  const numericSize = typeof size === 'string' ? Number.parseFloat(size) : size;
+  const useSmallVariant = Number.isFinite(numericSize) && (numericSize as number) <= 16;
+
+  if (useSmallVariant) {
+    return (
+      <svg
+        ref={ref}
+        xmlns="http://www.w3.org/2000/svg"
+        width={size}
+        height={size}
+        viewBox="0 0 16 16"
+        fill={color}
+        className={className}
+        {...rest}
+      >
+        <path d="M6.766 11.328c-2.063-.25-3.516-1.734-3.516-3.656 0-.781.281-1.625.75-2.188-.203-.515-.172-1.609.063-2.062.625-.078 1.468.25 1.968.703.594-.187 1.219-.281 1.985-.281.765 0 1.39.094 1.953.265.484-.437 1.344-.765 1.969-.687.218.422.25 1.515.046 2.047.5.593.766 1.39.766 2.203 0 1.922-1.453 3.375-3.547 3.64.531.344.89 1.094.89 1.954v1.625c0 .468.391.734.86.547C13.781 14.359 16 11.53 16 8.03 16 3.61 12.406 0 7.984 0 3.563 0 0 3.61 0 8.031a7.88 7.88 0 0 0 5.172 7.422c.422.156.828-.125.828-.547v-1.25c-.219.094-.5.156-.75.156-1.031 0-1.64-.562-2.078-1.609-.172-.422-.36-.672-.719-.719-.187-.015-.25-.093-.25-.187 0-.188.313-.328.625-.328.453 0 .844.281 1.25.86.313.452.64.655 1.031.655s.641-.14 1-.5c.266-.265.47-.5.657-.656" />
+      </svg>
+    );
+  }
+
+  return (
+    <svg
+      ref={ref}
+      xmlns="http://www.w3.org/2000/svg"
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill={color}
+      className={className}
+      {...rest}
+    >
+      <path d="M10.226 17.284c-2.965-.36-5.054-2.493-5.054-5.256 0-1.123.404-2.336 1.078-3.144-.292-.741-.247-2.314.09-2.965.898-.112 2.111.36 2.83 1.01.853-.269 1.752-.404 2.853-.404 1.1 0 1.999.135 2.807.382.696-.629 1.932-1.1 2.83-.988.315.606.36 2.179.067 2.942.72.854 1.101 2 1.101 3.167 0 2.763-2.089 4.852-5.098 5.234.763.494 1.28 1.572 1.28 2.807v2.336c0 .674.561 1.056 1.235.786 4.066-1.55 7.255-5.615 7.255-10.646C23.5 6.188 18.334 1 11.978 1 5.62 1 .5 6.188.5 12.545c0 4.986 3.167 9.12 7.435 10.669.606.225 1.19-.18 1.19-.786V20.63a2.9 2.9 0 0 1-1.078.224c-1.483 0-2.359-.808-2.987-2.313-.247-.607-.517-.966-1.034-1.033-.27-.023-.359-.135-.359-.27 0-.27.45-.471.898-.471.652 0 1.213.404 1.797 1.235.45.651.921.943 1.483.943.561 0 .92-.202 1.437-.719.382-.381.674-.718.944-.943" />
+    </svg>
+  );
+});

gitnexus-web/src/services/backend-client.ts

@@ -72,7 +72,19 @@ export class BackendError extends Error {
   constructor(
     message: string,
     public readonly status: number,
-    public readonly code: 'network' | 'server' | 'client' | 'not_found' | 'timeout',
+    public readonly code:
+      | 'network'
+      | 'server'
+      | 'client'
+      | 'not_found'
+      | 'timeout'
+      | 'rate_limited',
+    /**
+     * Milliseconds until the caller should retry. Populated for rate-limited
+     * responses (HTTP 429) from the server's `Retry-After` header. `undefined`
+     * for every other code, including `client` errors that aren't 429.
+     */
+    public readonly retryAfterMs?: number,
   ) {
     super(message);
     this.name = 'BackendError';
@@ -279,10 +291,32 @@ const assertOk = async (response: Response): Promise<void> => {
   const code =
     response.status === 404
       ? 'not_found'
-      : response.status >= 400 && response.status < 500
-        ? 'client'
-        : 'server';
-  throw new BackendError(message, response.status, code);
+      : response.status === 429
+        ? 'rate_limited'
+        : response.status >= 400 && response.status < 500
+          ? 'client'
+          : 'server';
+
+  // Retry-After is the standard HTTP signal for when the client may try again.
+  // express-rate-limit emits it on 429 with seconds (integer) or HTTP-date.
+  // We accept both shapes; an unparseable header yields undefined retryAfterMs.
+  let retryAfterMs: number | undefined;
+  if (response.status === 429) {
+    const header = response.headers.get('retry-after');
+    if (header) {
+      const seconds = Number(header);
+      if (Number.isFinite(seconds) && seconds >= 0) {
+        retryAfterMs = seconds * 1000;
+      } else {
+        const dateMs = Date.parse(header);
+        if (Number.isFinite(dateMs)) {
+          retryAfterMs = Math.max(0, dateMs - Date.now());
+        }
+      }
+    }
+  }
+
+  throw new BackendError(message, response.status, code, retryAfterMs);
 };
 
 const repoParam = (repo?: string): string => (repo ? `repo=${encodeURIComponent(repo)}` : '');

gitnexus-web/test/unit/heartbeat.test.ts

@@ -16,9 +16,12 @@ let lastEventSource: MockEventSource | null = null;
 
 beforeEach(() => {
   lastEventSource = null;
+  // vitest 4 enforces that mock implementations used with `new` must have a
+  // [[Construct]] slot. Arrow functions don't, so we use a regular function
+  // declaration here. The production code calls `new EventSource(...)`.
   vi.stubGlobal(
     'EventSource',
-    vi.fn().mockImplementation(() => {
+    vi.fn().mockImplementation(function () {
       lastEventSource = new MockEventSource();
       return lastEventSource;
     }),

gitnexus-web/vitest.config.ts

@@ -38,11 +38,15 @@ export default defineConfig({
         'src/main.tsx', // Entry point
         'src/vite-env.d.ts', // Type declarations
       ],
+      // Thresholds set to the post-vitest-4 baseline (AST-aware remapping
+      // measures coverage more accurately than the old istanbul-style mapping,
+      // so the same 220 tests now report slightly lower percentages). These
+      // are soft floors for regression detection, not coverage targets.
       thresholds: {
-        statements: 10,
-        branches: 10,
-        functions: 10,
-        lines: 10,
+        statements: 9,
+        branches: 4,
+        functions: 7,
+        lines: 9,
       },
     },
   },

gitnexus/CHANGELOG.md

@@ -2,6 +2,76 @@
 
 All notable changes to GitNexus will be documented in this file.
 
+## [Unreleased]
+
+## [1.6.3] - 2026-04-24
+
+### Added
+
+- **Cross-repo impact analysis** — `@repo` MCP routing plus group resources let impact queries span multiple indexed repositories in a group (#794, #984)
+- **Python scope-based call resolution** — registry-primary flip, performance, and generalization work from RFC #909 Ring 3 (#980)
+- **C# scope-resolution migration** — C# now runs on the registry-primary path alongside Python (#934, #1019)
+- **RFC #909 Ring 1 & Ring 2 scope-resolution infrastructure** — the shared foundation for language-agnostic scope resolution:
+  - Scope-resolution types and constants, `LanguageProvider` hook extension (#910, #911, #949, #950)
+  - `ScopeTree` + `PositionIndex` + `makeScopeId` (#912, #961)
+  - `DefIndex` / `ModuleScopeIndex` / `QualifiedNameIndex` (#913, #958)
+  - `MethodDispatchIndex` materialized view over `HeritageMap` (#914, #960)
+  - `resolveTypeRef` strict single-return type resolver (#916, #959)
+  - SCC-aware finalize with bounded fixpoint (#915, #962)
+  - `ClassRegistry` / `MethodRegistry` / `FieldRegistry` + 7-step lookup (#917, #963)
+  - Shadow-mode diff + aggregate, parity harness + static dashboard (#918, #923, #951, #972)
+  - `ScopeExtractor` driver with 5-pass CaptureMatch → ParsedFile (#919, #965)
+  - `ScopeExtractor` wired into parse-worker + processor (#920, #969)
+  - `finalize-orchestrator` materializes `ScopeResolutionIndexes` (#921, #970)
+  - Per-language `resolveImportTarget` adapter (#922, #971)
+  - `REGISTRY_PRIMARY_<LANG>` per-language flag reader (#924, #968)
+  - `emit-references` drains `ReferenceIndex` to graph edges (#925, #973)
+- **`gitnexus analyze --name <alias>`** with duplicate-name guard in the repo registry (#955)
+- **`gitnexus remove <target>`** unindexes a registered repo by name or path (#664, #1003)
+- **Auto-infer registry name** from `git remote.origin.url` when `--name` is omitted (#981)
+- **Sibling-clone drift detection** — indexed repos are fingerprinted by remote URL so duplicate registrations are caught before graph divergence (#982)
+- **Configurable large-file skip threshold** — the walker's 512 KB default is now overridable via `GITNEXUS_MAX_FILE_SIZE` (KB) or `gitnexus analyze --max-file-size <kb>`. Values are clamped to the 32 MB tree-sitter ceiling, invalid inputs fall back to the default with a one-time warning, and the CLI banner reports the effective post-clamp threshold when an override is active (#991, #1044, #1045)
+- **`GITNEXUS_INDEX_TEST_DIRS` opt-in** for `__tests__` / `__mocks__` traversal (#771, #1046)
+- **`analyze` embedding preservation** — existing embeddings are preserved by default, `--force` regenerates them, `--drop-embeddings` opts out entirely (CLI + HTTP API) (#1055)
+- **Structural embedding chunking** with data-driven `CHUNKING_RULES` dispatch, replacing the flat line-based split (#987)
+- **PHP HTTP consumer detection** for the extractor catalogue (#993)
+- **Per-phase search timing** instrumentation across the query pipeline (#953)
+- **MCP disambiguation ranking** — `context` / `impact` candidates are ranked and expose `kind` / `file_path` hints (#888)
+- **Docker images for UI + CLI/server** shipped via `docker-compose` with cosign signing (#967), RC image builds (#978), and GHCR → Docker Hub mirroring (#1029)
+
+### Fixed
+
+- **Go CALLS edges for receiver methods** — worker source IDs now align with the main pipeline, restoring receiver-method call edges (#1043)
+- **Node 22 DEP0151 warning** from `tree-sitter-c-sharp` import silenced (#1013, #1049)
+- **FTS index bootstrap** tries a local `LOAD` before `INSTALL` so offline/air-gapped runs no longer fail on network errors (#726)
+- **FTS ensure failures** are no longer cached and are invalidated on pool teardown (#1006)
+- **`groupImpact` local-impact errors** now bubble to the caller instead of being swallowed (#1004, #1007)
+- **Friendly error** when a group name is not found, with regression test for #903 (#989)
+- **`bm25` results** return FTS-matched symbols instead of an arbitrary `LIMIT 3` slice (#806)
+- **Embedding AST traversal** switched from recursion to iterative DFS, fixing stack overflow on deeply nested files (#990)
+- **React component path detection** runs before lowercasing, so mixed-case `.jsx`/`.tsx` files are recognised (#260)
+- **`detect-changes` ENOBUFS** by setting `maxBuffer` on `git` / `rg` `execFileSync` invocations (#957)
+- **`detect-changes` in direct CLI** — command was wired to MCP only; now exposed on the CLI as well (#892)
+- **CLI gitnexus markers** — `<!-- gitnexus:* -->` is only matched at section position, no longer inside code/prose (#1041, #1042)
+- **`opencode.json` setup** preserves existing comments and config during install (#998)
+- **Sequential parser logging** — skipped languages are now logged instead of silently dropped (#1021)
+- **`cli-e2e` fixture isolation** from the shared mini-repo, plus stabilised `rel-csv-split` stream teardown on Windows via `expect.poll` (#954, #1052)
+- **Docker** — RC build guarded against empty `vtag`, `inputs.tag` used to detect `workflow_call` context, web builder stage now copies `gitnexus/package.json`, base image switched from alpine to debian (#983, #996, #997, #1014)
+- **CI** — reusable `docker.yml` now inherits secrets from `release-candidate.yml` (#1054)
+
+### Changed
+
+- **`setup` config I/O unified** on `mergeJsoncFile` across all writers (#1031)
+- **Docker CI** gains a retry wrapper for `build-push` with visibility and hardened shell
+
+### Chore / Dependencies
+
+- Dependency bumps: `graphology` 0.25.4 → 0.26.0 (#1001), `uuid` 13 → 14 (#1000), `@huggingface/transformers` (#1035), `@types/node` (#1002), `@types/uuid` (#1016), `vitest` 4.1.4 → 4.1.5 (#1017), `@vitest/coverage-v8` (#1018)
+- gitnexus-web dependency bumps: `vite` 5.4.21 → 6.4.2 → 7.3.2 → 8.0.10 + `vitest` 4 (#1061, #1062, #1063), `lucide-react` 0.562.0 → 1.11.0 with local GitHub SVG fallback (#1038), `@langchain/anthropic` 1.3.10 → 1.3.27 (#1039), `@babel/types` (#1037)
+- gitnexus-shared dependency bumps: `typescript` (#1034)
+- GitHub Actions bumps: `actions/setup-node` 6.3.0 → 6.4.0 (#1033)
+- Documentation: repo-wide `DoD.md` Definition of Done (#1032), gRPC microservices group guide (#906, #994), `group add` / `group remove` README fixes (#1020), CLI docs include `--skip-git` (#750), README Discord link updated
+
 ## [1.6.2] - 2026-04-18
 
 ### Added

gitnexus/Dockerfile.test

@@ -3,7 +3,8 @@ WORKDIR /app
 RUN apt-get -o Acquire::Check-Valid-Until=false -o Acquire::Check-Date=false update && apt-get install -y python3 make g++ && rm -rf /var/lib/apt/lists/*
 COPY . .
 RUN npm ci --ignore-scripts \
-    && node scripts/patch-tree-sitter-swift.cjs \
+    && npm rebuild tree-sitter-swift 2>&1 \
+    && node -e "require('tree-sitter-swift')" \
     && (npm rebuild 2>&1 || true) \
     && cd node_modules/tree-sitter-kotlin && npx --yes node-gyp rebuild 2>&1
 CMD ["npx", "vitest", "run", "test/integration", "--reporter=verbose"]

gitnexus/README.md

@@ -155,6 +155,8 @@ gitnexus analyze --force         # Force full re-index
 gitnexus analyze --embeddings    # Enable embedding generation (slower, better search)
 gitnexus analyze --skip-agents-md  # Preserve custom AGENTS.md/CLAUDE.md gitnexus section edits
 gitnexus analyze --verbose       # Log skipped files when parsers are unavailable
+gitnexus analyze --max-file-size 1024  # Skip files larger than N KB (default: 512, cap: 32768)
+gitnexus analyze --worker-timeout 60  # Increase worker idle timeout for slow parses
 gitnexus mcp                     # Start MCP server (stdio) — serves all indexed repos
 gitnexus serve                   # Start local HTTP server (multi-repo) for web UI
 gitnexus index                   # Register an existing .gitnexus/ folder into the global registry
@@ -166,11 +168,11 @@ gitnexus wiki [path]             # Generate LLM-powered docs from knowledge grap
 gitnexus wiki --model <model>    # Wiki with custom LLM model (default: gpt-4o-mini)
 
 # Repository groups (multi-repo / monorepo service tracking)
-gitnexus group create <name>     # Create a repository group
-gitnexus group add <name> <repo> # Add a repo to a group
-gitnexus group remove <name> <repo> # Remove a repo from a group
-gitnexus group list [name]       # List groups, or show one group's config
-gitnexus group sync <name>       # Extract contracts and match across repos/services
+gitnexus group create <name>                                   # Create a repository group
+gitnexus group add <group> <groupPath> <registryName>          # Add a repo to a group. <groupPath> is a hierarchy path (e.g. hr/hiring/backend); <registryName> is the repo's name from the registry (see `gitnexus list`)
+gitnexus group remove <group> <groupPath>                      # Remove a repo from a group by its hierarchy path
+gitnexus group list [name]                                     # List groups, or show one group's config
+gitnexus group sync <name>                                     # Extract contracts and match across repos/services
 gitnexus group contracts <name>  # Inspect extracted contracts and cross-links
 gitnexus group query <name> <q>  # Search execution flows across all repos in a group
 gitnexus group status <name>     # Check staleness of repos in a group
@@ -294,6 +296,25 @@ If `npm install -g gitnexus` fails on native modules:
 npm install -g gitnexus
 ```
 
+### 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.
+
+Configure the behavior with two 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. |
+
+```bash
+# Offline/airgapped: never reach the network for extensions
+GITNEXUS_LBUG_EXTENSION_INSTALL=load-only npx gitnexus analyze
+
+# Slow network: give extension downloads more time
+GITNEXUS_LBUG_EXTENSION_INSTALL_TIMEOUT_MS=30000 npx gitnexus analyze
+```
+
 ### Analysis runs out of memory
 
 For very large repositories:
@@ -307,6 +328,36 @@ echo "vendor/" >> .gitnexusignore
 echo "dist/" >> .gitnexusignore
 ```
 
+### Large files are being skipped
+
+By default the walker skips files larger than **512 KB** (see log line `Skipped N large files (>512KB)`). Raise the threshold via either the CLI flag or the environment variable — both accept a value in **KB**:
+
+```bash
+# CLI flag (takes precedence over the env var)
+npx gitnexus analyze --max-file-size 2048     # skip only files > 2 MB
+
+# Environment variable (persists across commands)
+export GITNEXUS_MAX_FILE_SIZE=2048
+npx gitnexus analyze
+```
+
+Values above **32768 KB (32 MB)** are clamped to the tree-sitter parser ceiling; invalid values fall back to the 512 KB default with a one-time warning. When an override is active, `analyze` prints the effective threshold in its startup banner (e.g. `GITNEXUS_MAX_FILE_SIZE: effective threshold 2048KB (default 512KB)`).
+
+### Analyze reports a worker timeout
+
+Worker parse timeouts are recoverable. GitNexus retries stalled worker jobs with backoff, splits large jobs to isolate slow files, and falls back to the sequential parser when needed. If a large repository needs more time per worker job, use either:
+
+```bash
+# CLI flag, in seconds
+npx gitnexus analyze --worker-timeout 60
+
+# Environment variable, in milliseconds
+export GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=60000
+npx gitnexus analyze
+```
+
+For repositories with very large source files, `GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES` controls the worker job byte budget. The default is **8388608 bytes (8 MB)**.
+
 ## Privacy
 
 - All processing happens locally on your machine

gitnexus/hooks/claude/gitnexus-hook.cjs

@@ -31,11 +31,25 @@ function readInput() {
  * Find the .gitnexus directory by walking up from startDir.
  * Returns the path to .gitnexus/ or null if not found.
  */
-function findGitNexusDir(startDir) {
-  let dir = startDir || process.cwd();
+function isGlobalRegistryDir(candidate) {
+  if (fs.existsSync(path.join(candidate, 'meta.json'))) return false;
+  return (
+    fs.existsSync(path.join(candidate, 'registry.json')) ||
+    fs.existsSync(path.join(candidate, 'repos'))
+  );
+}
+
+/**
+ * Walk up from `startDir` looking for a non-registry `.gitnexus/` folder.
+ * Returns the path to `.gitnexus/` or null if not found within 5 levels.
+ */
+function walkForGitNexusDir(startDir) {
+  let dir = startDir;
   for (let i = 0; i < 5; i++) {
     const candidate = path.join(dir, '.gitnexus');
-    if (fs.existsSync(candidate)) return candidate;
+    if (fs.existsSync(candidate)) {
+      if (!isGlobalRegistryDir(candidate)) return candidate;
+    }
     const parent = path.dirname(dir);
     if (parent === dir) break;
     dir = parent;
@@ -43,6 +57,51 @@ function findGitNexusDir(startDir) {
   return null;
 }
 
+/**
+ * Resolve the canonical (main) worktree root for `cwd`, when `cwd` is inside
+ * any git working tree — including a *linked* worktree created via
+ * `git worktree add`. Linked worktrees never contain `.gitnexus/`, so the
+ * upward walk from cwd alone misses the index. Returns null when `cwd` is
+ * not inside a git repo or `git` is not available.
+ *
+ * Implementation: `git rev-parse --git-common-dir` resolves to the canonical
+ * `.git/` directory (or `.git/worktrees/...` parent) that is shared across
+ * all linked worktrees. The canonical repo root is its parent directory.
+ */
+function findCanonicalRepoRoot(cwd) {
+  try {
+    const result = spawnSync('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], {
+      encoding: 'utf-8',
+      timeout: 2000,
+      cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    if (result.error || result.status !== 0) return null;
+    const commonDir = (result.stdout || '').trim();
+    if (!commonDir || !path.isAbsolute(commonDir)) return null;
+    return path.dirname(commonDir);
+  } catch {
+    return null;
+  }
+}
+
+function findGitNexusDir(startDir) {
+  const cwd = startDir || process.cwd();
+
+  // Fast path: the cwd is inside the canonical repo (most common case).
+  const fromCwd = walkForGitNexusDir(cwd);
+  if (fromCwd) return fromCwd;
+
+  // Fallback: cwd may be inside a linked git worktree whose `.gitnexus/`
+  // only lives in the canonical repo root. Resolve the shared git dir
+  // and retry from there.
+  const canonicalRoot = findCanonicalRepoRoot(cwd);
+  if (canonicalRoot && canonicalRoot !== cwd) {
+    return walkForGitNexusDir(canonicalRoot);
+  }
+  return null;
+}
+
 /**
  * Extract search pattern from tool input.
  */

gitnexus/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.2",
+  "version": "1.6.3",
   "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",
@@ -35,7 +35,8 @@
     "hooks",
     "scripts",
     "skills",
-    "vendor"
+    "vendor",
+    "web"
   ],
   "scripts": {
     "build": "node scripts/build.js",
@@ -46,33 +47,35 @@
     "test:integration": "vitest run test/integration",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "postinstall": "node scripts/patch-tree-sitter-swift.cjs && node scripts/build-tree-sitter-proto.cjs",
+    "postinstall": "node scripts/build-tree-sitter-dart.cjs && node scripts/build-tree-sitter-proto.cjs",
     "prepare": "node scripts/build.js",
     "prepack": "node scripts/build.js"
   },
   "dependencies": {
     "@huggingface/transformers": "^4.1.0",
-    "@ladybugdb/core": "^0.15.2",
+    "@ladybugdb/core": "^0.16.1",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@scarf/scarf": "^1.4.0",
     "cli-progress": "^3.12.0",
     "commander": "^14.0.3",
     "cors": "^2.8.5",
     "express": "^4.19.2",
+    "express-rate-limit": "^8.4.1",
     "glob": "^13.0.6",
-    "graphology": "^0.25.4",
+    "graphology": "^0.26.0",
     "graphology-indices": "^0.17.0",
     "graphology-utils": "^2.3.0",
     "ignore": "^7.0.5",
     "js-yaml": "^4.1.1",
+    "jsonc-parser": "^3.3.1",
     "lru-cache": "^11.0.0",
     "mnemonist": "^0.40.3",
     "onnxruntime-node": "^1.24.0",
     "pandemonium": "^2.4.0",
     "tree-sitter": "^0.21.1",
-    "tree-sitter-c": "0.23.2",
+    "tree-sitter-c": "0.21.4",
     "tree-sitter-c-sharp": "0.23.1",
-    "tree-sitter-cpp": "^0.23.4",
+    "tree-sitter-cpp": "0.23.2",
     "tree-sitter-go": "^0.23.0",
     "tree-sitter-java": "^0.23.5",
     "tree-sitter-javascript": "^0.23.0",
@@ -81,25 +84,25 @@
     "tree-sitter-ruby": "^0.23.1",
     "tree-sitter-rust": "0.23.1",
     "tree-sitter-typescript": "^0.23.2",
-    "uuid": "^13.0.0"
+    "uuid": "^14.0.0"
   },
   "optionalDependencies": {
     "node-addon-api": "^8.0.0",
     "node-gyp-build": "^4.8.0",
-    "tree-sitter-dart": "git+https://github.com/UserNobody14/tree-sitter-dart.git#80e23c07b64494f7e21090bb3450223ef0b192f4",
+    "tree-sitter-dart": "file:./vendor/tree-sitter-dart",
     "tree-sitter-kotlin": "^0.3.8",
     "tree-sitter-proto": "file:./vendor/tree-sitter-proto",
-    "tree-sitter-swift": "^0.6.0"
+    "tree-sitter-swift": "file:./vendor/tree-sitter-swift"
   },
   "devDependencies": {
-    "gitnexus-shared": "file:../gitnexus-shared",
     "@types/cli-progress": "^3.11.6",
     "@types/cors": "^2.8.17",
     "@types/express": "^4.17.21",
     "@types/js-yaml": "^4.0.9",
-    "@types/node": "^20.0.0",
-    "@types/uuid": "^10.0.0",
+    "@types/node": "^25.6.0",
+    "@types/uuid": "^11.0.0",
     "@vitest/coverage-v8": "^4.0.18",
+    "gitnexus-shared": "file:../gitnexus-shared",
     "tsx": "^4.0.0",
     "typescript": "^5.4.5",
     "vitest": "^4.0.18"
@@ -107,8 +110,7 @@
   "overrides": {
     "@huggingface/transformers": {
       "onnxruntime-node": "$onnxruntime-node"
-    },
-    "tree-sitter-c": "0.23.2"
+    }
   },
   "engines": {
     "node": ">=20.0.0"

gitnexus/scripts/bench-scope-resolution.ts

@@ -0,0 +1,134 @@
+/**
+ * Synthetic benchmark for scope-resolution. Builds a large in-memory
+ * Python workspace and times runScopeResolution against it directly,
+ * isolating the resolution cost from parse / heritage / pipeline
+ * overhead.
+ *
+ * Usage: REGISTRY_PRIMARY_PYTHON=1 npx tsx scripts/bench-scope-resolution.ts
+ */
+process.env.REGISTRY_PRIMARY_PYTHON = '1';
+
+import { generateId } from '../src/lib/utils.js';
+import { createKnowledgeGraph } from '../src/core/graph/graph.js';
+import { runScopeResolution } from '../src/core/ingestion/scope-resolution/index.js';
+import { pythonScopeResolver } from '../src/core/ingestion/languages/python/scope-resolver.js';
+
+const N_CLASSES = Number(process.env.BENCH_CLASSES ?? '60');
+const N_USERS = Number(process.env.BENCH_USERS ?? '40');
+const ITERS = Number(process.env.BENCH_ITERS ?? '5');
+
+function buildWorkspace(): { path: string; content: string }[] {
+  const files: { path: string; content: string }[] = [];
+
+  // Build N_CLASSES "model" files, each defining a class with a few methods.
+  for (let i = 0; i < N_CLASSES; i++) {
+    const lines: string[] = [];
+    for (let j = 0; j < 5; j++) {
+      lines.push(`class Model${i}_${j}:`);
+      lines.push(`    name: str`);
+      lines.push(`    def save(self) -> bool:`);
+      lines.push(`        return True`);
+      lines.push(`    def update(self, name: str) -> "Model${i}_${j}":`);
+      lines.push(`        self.name = name`);
+      lines.push(`        return self`);
+      lines.push(`    def get_other(self) -> "Model${i}_${(j + 1) % 5}":`);
+      lines.push(`        return Model${i}_${(j + 1) % 5}()`);
+      lines.push('');
+    }
+    files.push({ path: `models/m${i}.py`, content: lines.join('\n') });
+  }
+
+  // Build N_USERS "user" files that import from a few model files
+  // and exercise the receiver-bound dispatcher heavily.
+  for (let u = 0; u < N_USERS; u++) {
+    const targets = [u % N_CLASSES, (u + 1) % N_CLASSES, (u + 2) % N_CLASSES];
+    const imports = targets
+      .map((t) => `from models.m${t} import Model${t}_0, Model${t}_1, Model${t}_2`)
+      .join('\n');
+    const calls: string[] = [];
+    for (let k = 0; k < 30; k++) {
+      const t = targets[k % 3]!;
+      const j = k % 3;
+      calls.push(`    m${k} = Model${t}_${j}()`);
+      calls.push(`    m${k}.save()`);
+      calls.push(`    m${k}.update("x").save()`);
+      calls.push(`    m${k}.get_other().save()`);
+    }
+    const content = `${imports}\n\ndef use_${u}() -> None:\n${calls.join('\n')}\n`;
+    files.push({ path: `app/u${u}.py`, content });
+  }
+
+  return files;
+}
+
+function buildGraph(files: { path: string; content: string }[]) {
+  const graph = createKnowledgeGraph();
+  // Pre-populate File / Class / Function nodes the resolver expects.
+  for (const f of files) {
+    const fileId = generateId('File', f.path);
+    graph.addNode({
+      id: fileId,
+      label: 'File',
+      properties: { name: f.path, filePath: f.path },
+    });
+
+    // Lightweight regex-extract class & def names so the lookup index
+    // has something to find. Real pipeline builds these via parse phase;
+    // for the bench this stand-in is enough to exercise the resolver.
+    const classRe = /^class (\w+)/gm;
+    const defRe = /^\s*def (\w+)/gm;
+    let m: RegExpExecArray | null;
+    while ((m = classRe.exec(f.content)) !== null) {
+      const name = m[1]!;
+      const id = generateId('Class', `${f.path}:${name}`);
+      graph.addNode({
+        id,
+        label: 'Class',
+        properties: { name, filePath: f.path, qualifiedName: name },
+      });
+    }
+    while ((m = defRe.exec(f.content)) !== null) {
+      const name = m[1]!;
+      const id = generateId('Function', `${f.path}:${name}`);
+      graph.addNode({
+        id,
+        label: 'Function',
+        properties: { name, filePath: f.path, qualifiedName: name },
+      });
+    }
+  }
+  return graph;
+}
+
+async function main() {
+  const files = buildWorkspace();
+  console.log(`bench: ${files.length} files (${N_CLASSES} models × 5 classes + ${N_USERS} users)`);
+  console.log(`       × ${ITERS} iterations\n`);
+
+  // Warmup
+  for (let i = 0; i < 2; i++) {
+    const graph = buildGraph(files);
+    runScopeResolution({ graph, files, onWarn: () => {} }, pythonScopeResolver);
+  }
+
+  const samples: number[] = [];
+  for (let i = 0; i < ITERS; i++) {
+    const graph = buildGraph(files);
+    const start = process.hrtime.bigint();
+    runScopeResolution({ graph, files, onWarn: () => {} }, pythonScopeResolver);
+    const end = process.hrtime.bigint();
+    const ms = Number(end - start) / 1_000_000;
+    samples.push(ms);
+    console.log(`  iter ${i + 1}: ${ms.toFixed(0)} ms`);
+  }
+
+  samples.sort((a, b) => a - b);
+  const median = samples[Math.floor(samples.length / 2)]!;
+  const min = samples[0]!;
+  console.log(`\nmin: ${min.toFixed(0)} ms · median: ${median.toFixed(0)} ms`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

gitnexus/scripts/build-tree-sitter-dart.cjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const dartDir = path.join(__dirname, '..', 'node_modules', 'tree-sitter-dart');
+const bindingGyp = path.join(dartDir, 'binding.gyp');
+const bindingNode = path.join(dartDir, 'build', 'Release', 'tree_sitter_dart_binding.node');
+
+try {
+  if (!fs.existsSync(bindingGyp) || fs.existsSync(bindingNode)) {
+    process.exit(0);
+  }
+
+  try {
+    require.resolve('node-addon-api');
+    require.resolve('node-gyp-build');
+  } catch (resolveErr) {
+    console.warn(
+      '[tree-sitter-dart] Skipping build: hoisted build deps not resolvable (%s).',
+      resolveErr.message,
+    );
+    console.warn(
+      '[tree-sitter-dart] Dart parsing will be unavailable. Install without --no-optional and with scripts enabled to build.',
+    );
+    process.exit(0);
+  }
+
+  console.log('[tree-sitter-dart] Building native binding...');
+  execSync('npx node-gyp rebuild', {
+    cwd: dartDir,
+    stdio: 'pipe',
+    timeout: 180000,
+  });
+  console.log('[tree-sitter-dart] Native binding built successfully');
+} catch (err) {
+  console.warn('[tree-sitter-dart] Could not build native binding:', err.message);
+  console.warn(
+    '[tree-sitter-dart] Dart parsing will be unavailable. Non-Dart functionality is unaffected.',
+  );
+  process.exit(0);
+}

gitnexus/scripts/build-tree-sitter-proto.cjs

@@ -26,7 +26,7 @@
  *   `node_modules/tree-sitter-proto/build/Release/tree_sitter_proto_binding.node`
  *   — under npm-managed territory, safe on upgrade.
  *
- *   Mirrors scripts/patch-tree-sitter-swift.cjs. Best-effort: if any
+ *   Mirrors the tree-sitter-dart build helper. Best-effort: if any
  *   precondition fails (optional dep absent, no toolchain, --ignore-scripts),
  *   warn and exit 0 so gitnexus install still succeeds.
  */

gitnexus/scripts/build.js

@@ -21,11 +21,11 @@ const SHARED_DEST = path.join(DIST, '_shared');
 
 // ── 1. Build gitnexus-shared ───────────────────────────────────────
 console.log('[build] compiling gitnexus-shared…');
-execSync('npx tsc', { cwd: SHARED_ROOT, stdio: 'inherit' });
+execSync('npx tsc', { cwd: SHARED_ROOT, stdio: 'inherit', timeout: 120_000 });
 
 // ── 2. Build gitnexus ──────────────────────────────────────────────
 console.log('[build] compiling gitnexus…');
-execSync('npx tsc', { cwd: ROOT, stdio: 'inherit' });
+execSync('npx tsc', { cwd: ROOT, stdio: 'inherit', timeout: 120_000 });
 
 // ── 3. Copy shared dist ────────────────────────────────────────────
 console.log('[build] copying shared module into dist/_shared…');
@@ -70,4 +70,24 @@ walk(DIST, ['.js', '.d.ts'], rewriteFile);
 const cliEntry = path.join(DIST, 'cli', 'index.js');
 if (fs.existsSync(cliEntry)) fs.chmodSync(cliEntry, 0o755);
 
+// ── 6. Build & copy web UI ──────────────────────────────────────────
+const WEB_ROOT = path.resolve(ROOT, '..', 'gitnexus-web');
+const WEB_DEST = path.join(DIST, '..', 'web');
+
+if (fs.existsSync(path.join(WEB_ROOT, 'package.json'))) {
+  console.log('[build] building gitnexus-web…');
+  if (!fs.existsSync(path.join(WEB_ROOT, 'node_modules'))) {
+    console.log('[build] installing gitnexus-web dependencies…');
+    execSync('npm ci', { cwd: WEB_ROOT, stdio: 'inherit', timeout: 120_000 });
+  }
+  execSync('npm run build', { cwd: WEB_ROOT, stdio: 'inherit', timeout: 120_000 });
+
+  // Copy dist → gitnexus/web/ (shipped in the npm package)
+  fs.rmSync(WEB_DEST, { recursive: true, force: true });
+  fs.cpSync(path.join(WEB_ROOT, 'dist'), WEB_DEST, { recursive: true });
+  console.log('[build] copied web UI → gitnexus/web/');
+} else {
+  console.log('[build] skipping web UI (gitnexus-web not found)');
+}
+
 console.log(`[build] done — rewrote ${rewritten} files.`);

gitnexus/scripts/ci-list-migrated-languages.ts

@@ -0,0 +1,24 @@
+/**
+ * CI helper — emits the `MIGRATED_LANGUAGES` set as a JSON matrix array for
+ * GitHub Actions (`.github/workflows/ci-scope-parity.yml`).
+ *
+ * Consumed by the `discover` job in that workflow. Each entry has:
+ *   - `slug`: lowercase language id, matching `test/integration/resolvers/<slug>.test.ts`.
+ *   - `envvar`: uppercase suffix used to build the `REGISTRY_PRIMARY_<envvar>` toggle.
+ *
+ * Run with `npx tsx scripts/ci-list-migrated-languages.ts`. The script
+ * writes a single JSON array to stdout (no wrapper object) so the
+ * workflow can pipe it straight into `$GITHUB_OUTPUT`.
+ */
+
+import { MIGRATED_LANGUAGES } from '../src/core/ingestion/registry-primary-flag.js';
+
+const entries = [...MIGRATED_LANGUAGES].map((slug) => {
+  const s = String(slug);
+  return {
+    slug: s,
+    envvar: s.toUpperCase().replace(/-/g, '_'),
+  };
+});
+
+process.stdout.write(JSON.stringify(entries));

gitnexus/scripts/install-duckdb-extension.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+const EXTENSION_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_]*$/;
+
+function parseLbugMaxDbSize(raw) {
+  const parsed = raw ? Number(raw) : NaN;
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error(`Invalid LadybugDB max DB size for extension installer: ${raw ?? '<missing>'}`);
+  }
+  return Math.floor(parsed);
+}
+
+async function installDuckDbExtension(extensionName) {
+  if (!extensionName || !EXTENSION_NAME_PATTERN.test(extensionName)) {
+    throw new Error(`Invalid DuckDB extension name: ${extensionName ?? '<missing>'}`);
+  }
+
+  const require = createRequire(import.meta.url);
+  const lbugModule = require('@ladybugdb/core');
+  const lbug = lbugModule.default ?? lbugModule;
+  const lbugMaxDbSize = parseLbugMaxDbSize(
+    process.argv[3] ?? process.env.GITNEXUS_LBUG_MAX_DB_SIZE,
+  );
+
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'gitnexus-ext-install-'));
+  const dbPath = path.join(tmpDir, 'install.lbug');
+  let db;
+  let conn;
+
+  try {
+    db = new lbug.Database(dbPath, 0, false, false, lbugMaxDbSize);
+    conn = new lbug.Connection(db);
+    await conn.query(`INSTALL ${extensionName}`);
+  } finally {
+    if (conn) await conn.close().catch(() => {});
+    if (db) await db.close().catch(() => {});
+    await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+installDuckDbExtension(process.argv[2] ?? process.env.GITNEXUS_LBUG_EXTENSION_NAME).catch((err) => {
+  console.error(err instanceof Error ? (err.stack ?? err.message) : String(err));
+  process.exitCode = 1;
+});

gitnexus/scripts/patch-tree-sitter-swift.cjs

@@ -1,78 +0,0 @@
-#!/usr/bin/env node
-/**
- * WORKAROUND: tree-sitter-swift@0.6.0 binding.gyp build failure
- *
- * Background:
- *   tree-sitter-swift@0.6.0's binding.gyp contains an "actions" array that
- *   invokes `tree-sitter generate` to regenerate parser.c from grammar.js.
- *   This is intended for grammar developers, but the published npm package
- *   already ships pre-generated parser files (parser.c, scanner.c), so the
- *   actions are unnecessary for consumers. Since consumers don't have
- *   tree-sitter-cli installed, the actions always fail during `npm install`.
- *
- * Why we can't just upgrade:
- *   tree-sitter-swift@0.7.1 fixes this (removes postinstall, ships prebuilds),
- *   but it requires tree-sitter@^0.22.1. The upstream project pins tree-sitter
- *   to ^0.21.0 and all other grammar packages depend on that version.
- *   Upgrading tree-sitter would be a separate breaking change.
- *
- * How this workaround works:
- *   1. tree-sitter-swift's own postinstall fails (npm warns but continues)
- *   2. This script runs as gitnexus's postinstall
- *   3. It removes the "actions" array from binding.gyp
- *   4. It rebuilds the native binding with the cleaned binding.gyp
- *
- * TODO: Remove this script when tree-sitter is upgraded to ^0.22.x,
- *       which allows using tree-sitter-swift@0.7.1+ directly.
- */
-const fs = require('fs');
-const path = require('path');
-const { execSync } = require('child_process');
-
-const swiftDir = path.join(__dirname, '..', 'node_modules', 'tree-sitter-swift');
-const bindingPath = path.join(swiftDir, 'binding.gyp');
-
-try {
-  if (!fs.existsSync(bindingPath)) {
-    process.exit(0);
-  }
-
-  const content = fs.readFileSync(bindingPath, 'utf8');
-  let needsRebuild = false;
-
-  if (content.includes('"actions"')) {
-    // Strip Python-style comments (#) and trailing commas before JSON parsing
-    const cleaned = content
-      .replace(/#[^\n]*/g, '') // Remove # comments
-      .replace(/,(\s*[\]}])/g, '$1'); // Remove trailing commas before ] or }
-    const gyp = JSON.parse(cleaned);
-
-    if (gyp.targets && gyp.targets[0] && gyp.targets[0].actions) {
-      delete gyp.targets[0].actions;
-      fs.writeFileSync(bindingPath, JSON.stringify(gyp, null, 2) + '\n');
-      console.log('[tree-sitter-swift] Patched binding.gyp (removed actions array)');
-      needsRebuild = true;
-    }
-  }
-
-  // Check if native binding exists
-  const bindingNode = path.join(swiftDir, 'build', 'Release', 'tree_sitter_swift_binding.node');
-  if (!fs.existsSync(bindingNode)) {
-    needsRebuild = true;
-  }
-
-  if (needsRebuild) {
-    console.log('[tree-sitter-swift] Rebuilding native binding...');
-    execSync('npx node-gyp rebuild', {
-      cwd: swiftDir,
-      stdio: 'pipe',
-      timeout: 120000,
-    });
-    console.log('[tree-sitter-swift] Native binding built successfully');
-  }
-} catch (err) {
-  console.warn('[tree-sitter-swift] Could not build native binding:', err.message);
-  console.warn(
-    '[tree-sitter-swift] You may need to manually run: cd node_modules/tree-sitter-swift && npx node-gyp rebuild',
-  );
-}

gitnexus/skills/gitnexus-cli.md

@@ -21,8 +21,9 @@ Run from the project root. This parses all source files, builds the knowledge gr
 | -------------- | ---------------------------------------------------------------- |
 | `--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. |
 
-**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 runs `analyze` automatically after `git commit` and `git merge`, preserving embeddings if previously generated.
+**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.
 
 ### status — Check index freshness
 

gitnexus/src/cli/ai-context.ts

@@ -32,6 +32,33 @@ export interface AIContextOptions {
 const GITNEXUS_START_MARKER = '<!-- gitnexus:start -->';
 const GITNEXUS_END_MARKER = '<!-- gitnexus:end -->';
 
+/**
+ * Find the index of a section marker that occupies its own line.
+ * Unlike `indexOf`, this rejects inline prose references like
+ * `` See the `<!-- gitnexus:start -->` block `` that appear
+ * mid-sentence (#1041). A marker counts as section-position only when:
+ *   - preceded by newline or start-of-file, AND
+ *   - followed by newline, `\r` (CRLF files), or end-of-file.
+ * The generator always emits each marker alone on its line, so this
+ * matches every legitimate section and none of the inline mentions.
+ *
+ * `startFrom` lets the end-marker lookup start after the already-found
+ * start marker, avoiding a scan from 0 and guaranteeing we never pick
+ * up an end marker that appears earlier in the file than the start.
+ */
+function findSectionMarkerIndex(content: string, marker: string, startFrom = 0): number {
+  let idx = content.indexOf(marker, startFrom);
+  while (idx !== -1) {
+    const atLineStart = idx === 0 || content[idx - 1] === '\n';
+    const endPos = idx + marker.length;
+    const atLineEnd =
+      endPos === content.length || content[endPos] === '\n' || content[endPos] === '\r';
+    if (atLineStart && atLineEnd) return idx;
+    idx = content.indexOf(marker, idx + 1);
+  }
+  return -1;
+}
+
 /**
  * Generate the full GitNexus context content.
  *
@@ -121,7 +148,7 @@ ${
   groupNames && groupNames.length > 0
     ? `## Cross-Repo Groups
 
-This repository is listed under GitNexus **group(s): ${groupNames.join(', ')}** (see \`~/.gitnexus/groups/\`). For blast radius across repository boundaries, use MCP tools \`group_impact\`, \`group_sync\`, \`group_query\`, \`group_contracts\`, \`group_status\`, and \`group_list\`. From the terminal: \`npx gitnexus group list\`, \`npx gitnexus group sync <name>\`, \`npx gitnexus group impact <name> --target <symbol> --repo <group-path>\`.
+This repository is listed under GitNexus **group(s): ${groupNames.join(', ')}** (see \`~/.gitnexus/groups/\`). For cross-repo analysis, use MCP tools \`impact\`, \`query\`, and \`context\` with \`repo\` set to \`@<groupName>\` or \`@<groupName>/<memberPath>\` (paths match keys in that group’s \`group.yaml\`). Use \`group_list\` / \`group_sync\` for membership and sync. From the terminal: \`npx gitnexus group list\`, \`npx gitnexus group sync <name>\`, \`npx gitnexus group impact <name> --target <symbol> --repo <group-path>\`.
 
 `
     : ''
@@ -163,9 +190,18 @@ async function upsertGitNexusSection(
 
   const existingContent = await fs.readFile(filePath, 'utf-8');
 
-  // Check if GitNexus section already exists
-  const startIdx = existingContent.indexOf(GITNEXUS_START_MARKER);
-  const endIdx = existingContent.indexOf(GITNEXUS_END_MARKER);
+  // Check if GitNexus section already exists. Matching is restricted
+  // to markers that occupy their own line so that inline prose
+  // references (e.g. `` See the `<!-- gitnexus:start -->` block `` in
+  // the shipped CLAUDE.md) are NOT treated as section delimiters
+  // (#1041). The end-marker scan starts after the start-marker so it
+  // can never pick up an earlier end in the file.
+  const startIdx = findSectionMarkerIndex(existingContent, GITNEXUS_START_MARKER);
+  const endIdx = findSectionMarkerIndex(
+    existingContent,
+    GITNEXUS_END_MARKER,
+    startIdx === -1 ? 0 : startIdx,
+  );
 
   if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
     // Replace existing section

gitnexus/src/cli/analyze.ts

@@ -17,11 +17,52 @@ import {
   getStoragePaths,
   getGlobalRegistryPath,
   RegistryNameCollisionError,
+  AnalysisNotFinalizedError,
+  assertAnalysisFinalized,
 } from '../storage/repo-manager.js';
 import { getGitRoot, hasGitDir } from '../storage/git.js';
 import { runFullAnalysis } from '../core/run-analyze.js';
+import { getMaxFileSizeBannerMessage } from '../core/ingestion/utils/max-file-size.js';
 import fs from 'fs/promises';
 
+// Capture stderr.write at module load BEFORE anything (LadybugDB native
+// init, progress bar, console redirection) can monkey-patch it. The
+// fatal handlers below MUST reach the user even when the analyze path
+// has redirected console.* through the progress bar's bar.log() — the
+// previous behaviour silently swallowed stack traces and made #1169
+// indistinguishable from a no-op success on Windows.
+const realStderrWrite = process.stderr.write.bind(process.stderr);
+
+const writeFatalToStderr = (label: string, err: unknown): void => {
+  const isErr = err instanceof Error;
+  const message = isErr ? err.message : String(err);
+  realStderrWrite(`\n  ${label}: ${message}\n`);
+  if (isErr && err.stack) realStderrWrite(`${err.stack}\n`);
+};
+
+let fatalHandlersInstalled = false;
+
+/**
+ * Install one-shot `unhandledRejection` / `uncaughtException` handlers
+ * that surface the failure to the real stderr (bypassing any console
+ * redirection installed by the progress bar) and force a non-zero exit
+ * code. Without these, an async error escaping {@link analyzeCommand}'s
+ * try/catch was reported as exit 0 with no diagnostic — the silent
+ * failure mode tracked in #1169.
+ */
+const installFatalHandlers = (): void => {
+  if (fatalHandlersInstalled) return;
+  fatalHandlersInstalled = true;
+  process.on('unhandledRejection', (err) => {
+    writeFatalToStderr('Analysis failed (unhandled rejection)', err);
+    process.exit(1);
+  });
+  process.on('uncaughtException', (err) => {
+    writeFatalToStderr('Analysis failed (uncaught exception)', err);
+    process.exit(1);
+  });
+};
+
 const HEAP_MB = 8192;
 const HEAP_FLAG = `--max-old-space-size=${HEAP_MB}`;
 /** Increase default stack size (KB) to prevent stack overflow on deep class hierarchies. */
@@ -55,6 +96,12 @@ function ensureHeap(): boolean {
 export interface AnalyzeOptions {
   force?: boolean;
   embeddings?: boolean;
+  /**
+   * Explicitly drop existing embeddings on rebuild instead of preserving
+   * them. Without this flag, a routine `analyze` keeps any embeddings
+   * already present in the index even when `--embeddings` is omitted.
+   */
+  dropEmbeddings?: boolean;
   skills?: boolean;
   verbose?: boolean;
   /** Skip AGENTS.md and CLAUDE.md gitnexus block updates. */
@@ -78,35 +125,112 @@ export interface AnalyzeOptions {
    * `allowDuplicateName` option end-to-end.
    */
   allowDuplicateName?: boolean;
+  /**
+   * Override the walker's large-file skip threshold (#991). Value in KB;
+   * clamped downstream to the tree-sitter 32 MB ceiling. Sets
+   * `GITNEXUS_MAX_FILE_SIZE` for the rest of the pipeline.
+   */
+  maxFileSize?: string;
+  /** Override worker sub-batch idle timeout in seconds. */
+  workerTimeout?: string;
+  embeddingThreads?: string;
+  embeddingBatchSize?: string;
+  embeddingSubBatchSize?: string;
+  embeddingDevice?: string;
 }
 
 export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOptions) => {
   if (ensureHeap()) return;
 
+  // Install fatal handlers immediately after re-exec resolution so any
+  // async error that escapes the try/catch below (#1169) surfaces with
+  // a stack trace and a non-zero exit code instead of a silent exit 0.
+  installFatalHandlers();
+
   if (options?.verbose) {
     process.env.GITNEXUS_VERBOSE = '1';
   }
 
+  if (options?.maxFileSize) {
+    process.env.GITNEXUS_MAX_FILE_SIZE = options.maxFileSize;
+  }
+
+  if (options?.workerTimeout) {
+    const workerTimeoutSeconds = Number(options.workerTimeout);
+    if (!Number.isFinite(workerTimeoutSeconds) || workerTimeoutSeconds < 1) {
+      console.error('  --worker-timeout must be at least 1 second.\n');
+      process.exitCode = 1;
+      return;
+    }
+    process.env.GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS = String(
+      Math.round(workerTimeoutSeconds * 1000),
+    );
+  }
+
+  const setPositiveEnv = (
+    optionName: string,
+    envName: string,
+    value: string | undefined,
+  ): boolean => {
+    if (value === undefined) return true;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+      console.error(`  ${optionName} must be a positive integer.\n`);
+      process.exitCode = 1;
+      return false;
+    }
+    process.env[envName] = String(parsed);
+    return true;
+  };
+
+  if (
+    !setPositiveEnv(
+      '--embedding-threads',
+      'GITNEXUS_EMBEDDING_THREADS',
+      options?.embeddingThreads,
+    ) ||
+    !setPositiveEnv(
+      '--embedding-batch-size',
+      'GITNEXUS_EMBEDDING_BATCH_SIZE',
+      options?.embeddingBatchSize,
+    ) ||
+    !setPositiveEnv(
+      '--embedding-sub-batch-size',
+      'GITNEXUS_EMBEDDING_SUB_BATCH_SIZE',
+      options?.embeddingSubBatchSize,
+    )
+  ) {
+    return;
+  }
+
+  if (options?.embeddingDevice) {
+    const allowed = new Set(['auto', 'cpu', 'dml', 'cuda', 'wasm']);
+    if (!allowed.has(options.embeddingDevice)) {
+      console.error('  --embedding-device must be one of: auto, cpu, dml, cuda, wasm.\n');
+      process.exitCode = 1;
+      return;
+    }
+    process.env.GITNEXUS_EMBEDDING_DEVICE = options.embeddingDevice;
+  }
+
   console.log('\n  GitNexus Analyzer\n');
 
   let repoPath: string;
   if (inputPath) {
     repoPath = path.resolve(inputPath);
+  } else if (options?.skipGit) {
+    // --skip-git: treat cwd as the index root, do not walk up to a parent git repo.
+    repoPath = path.resolve(process.cwd());
   } else {
     const gitRoot = getGitRoot(process.cwd());
     if (!gitRoot) {
-      if (!options?.skipGit) {
-        console.log(
-          '  Not inside a git repository.\n  Tip: pass --skip-git to index any folder without a .git directory.\n',
-        );
-        process.exitCode = 1;
-        return;
-      }
-      // --skip-git: fall back to cwd as the root
-      repoPath = path.resolve(process.cwd());
-    } else {
-      repoPath = gitRoot;
+      console.log(
+        '  Not inside a git repository.\n  Tip: pass --skip-git to index any folder without a .git directory.\n',
+      );
+      process.exitCode = 1;
+      return;
     }
+    repoPath = gitRoot;
   }
 
   const repoHasGit = hasGitDir(repoPath);
@@ -132,6 +256,11 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
     );
   }
 
+  const maxFileSizeBanner = getMaxFileSizeBannerMessage();
+  if (maxFileSizeBanner) {
+    console.log(`${maxFileSizeBanner}\n`);
+  }
+
   // ── CLI progress bar setup ─────────────────────────────────────────
   const bar = new cliProgress.SingleBar(
     {
@@ -210,6 +339,7 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
         // collision guard (see allowDuplicateName below).
         force: options?.force || options?.skills,
         embeddings: options?.embeddings,
+        dropEmbeddings: options?.dropEmbeddings,
         skipGit: options?.skipGit,
         skipAgentsMd: options?.skipAgentsMd,
         noStats: options?.noStats,
@@ -229,6 +359,11 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
     );
 
     if (result.alreadyUpToDate) {
+      // Even the fast path must prove the repo is discoverable. A prior
+      // run can write meta.json and then fail before registerRepo(); in
+      // that half-finalized state, runFullAnalysis returns alreadyUpToDate
+      // on the next invocation unless we check the registry here too.
+      await assertAnalysisFinalized(repoPath);
       clearInterval(elapsedTimer);
       process.removeListener('SIGINT', sigintHandler);
       console.log = origLog;
@@ -241,6 +376,15 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
       return;
     }
 
+    // Post-finalize invariant (#1169): runFullAnalysis nominally writes
+    // meta.json and registers the repo, but on Windows it has been
+    // observed to return successfully with neither artifact present
+    // (banner-only output, exit 0). Verify both before declaring
+    // success so the silent-finalize state surfaces with a non-zero
+    // exit code and an actionable error instead of being mistaken for
+    // a healthy index.
+    await assertAnalysisFinalized(repoPath);
+
     // Skill generation (CLI-only, uses pipeline result from analysis)
     if (options?.skills && result.pipelineResult) {
       updateBar(99, 'Generating skill files...');
@@ -342,7 +486,29 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
       return;
     }
 
-    console.error(`\n  Analysis failed: ${msg}\n`);
+    // Finalize invariant failure (#1169) — keep the rich actionable
+    // message intact and write through realStderrWrite so it can't be
+    // erased by a leftover bar refresh on slow terminals.
+    if (err instanceof AnalysisNotFinalizedError) {
+      writeFatalToStderr('Analysis did not finalize', err);
+      realStderrWrite(
+        `\n  Diagnostic checklist:\n` +
+          `    1. Re-run "gitnexus analyze" - transient native errors often clear on retry.\n` +
+          `    2. Inspect ${err.storagePath} - a leftover lbug.wal indicates an aborted write.\n` +
+          `    3. If the failure persists, run with NODE_OPTIONS="--max-old-space-size=8192 --trace-exit"\n` +
+          `       and attach the trace to the GitNexus issue tracker.\n\n`,
+      );
+      process.exitCode = 1;
+      return;
+    }
+
+    // Bypass the redirected console.error and write the full stack to
+    // the real stderr captured at module load. The redirected
+    // console.error wraps every line with `\\x1b[2K\\r` (ANSI clear-line)
+    // and forces a bar.update() afterwards, which on some Windows
+    // terminals visually erases the failure message — the canonical
+    // shape of the silent-exit symptom in #1169.
+    writeFatalToStderr('Analysis failed', err);
 
     // Provide helpful guidance for known failure modes
     if (

gitnexus/src/cli/clean.ts

@@ -6,7 +6,13 @@
  */
 
 import fs from 'fs/promises';
-import { findRepo, unregisterRepo, listRegisteredRepos } from '../storage/repo-manager.js';
+import {
+  findRepo,
+  unregisterRepo,
+  listRegisteredRepos,
+  assertSafeStoragePath,
+  UnsafeStoragePathError,
+} from '../storage/repo-manager.js';
 
 export const cleanCommand = async (options?: { force?: boolean; all?: boolean }) => {
   // --all flag: clean all indexed repos
@@ -27,6 +33,24 @@ export const cleanCommand = async (options?: { force?: boolean; all?: boolean })
 
     const entries = await listRegisteredRepos();
     for (const entry of entries) {
+      // Safety guard (#1003 review — @magyargergo): same rationale as
+      // remove.ts. `~/.gitnexus/registry.json` is user-writable, so a
+      // corrupted or hand-edited entry could point storagePath at the
+      // repo root, an empty string, or anywhere else — and
+      // fs.rm(recursive: true) on any of those would be catastrophic.
+      // Skip poisoned entries without touching disk, but keep going
+      // through the rest of the registry (preserves the existing
+      // per-repo error-tolerance semantics of `clean --all`).
+      try {
+        assertSafeStoragePath(entry);
+      } catch (err) {
+        if (err instanceof UnsafeStoragePathError) {
+          console.error(`Refusing to clean ${entry.name}: ${err.message}`);
+          continue;
+        }
+        throw err;
+      }
+
       try {
         await fs.rm(entry.storagePath, { recursive: true, force: true });
         await unregisterRepo(entry.path);

gitnexus/src/cli/doctor.ts

@@ -0,0 +1,32 @@
+import { getRuntimeCapabilities, getRuntimeFingerprint } from '../core/platform/capabilities.js';
+import { resolveEmbeddingConfig } from '../core/embeddings/config.js';
+import { isHttpMode } from '../core/embeddings/http-client.js';
+
+export const doctorCommand = async () => {
+  const fingerprint = getRuntimeFingerprint();
+  const capabilities = getRuntimeCapabilities();
+  const embeddingConfig = resolveEmbeddingConfig();
+
+  console.log('GitNexus Doctor\n');
+  console.log('Runtime');
+  console.log(`  OS:        ${fingerprint.platform}/${fingerprint.arch}`);
+  console.log(`  Node:      ${fingerprint.node}`);
+  console.log(`  GitNexus:  ${fingerprint.gitnexus}`);
+  console.log(`  LadybugDB: ${fingerprint.ladybugdb ?? 'unknown'}`);
+  console.log(`  ONNX:      ${fingerprint.onnxruntime ?? 'unknown'}`);
+  console.log('');
+  console.log('Capabilities');
+  console.log(`  Graph store:     ${capabilities.graph}`);
+  console.log(`  Full-text search:${capabilities.fts.padStart(10)}`);
+  console.log(`  VECTOR index:    ${capabilities.vector}`);
+  console.log(`  Semantic mode:   ${capabilities.semanticMode}`);
+  console.log(`  Exact scan limit:${String(capabilities.exactScanLimit).padStart(9)} chunks`);
+  if (capabilities.reason) console.log(`  Note:            ${capabilities.reason}`);
+  console.log('');
+  console.log('Embeddings');
+  console.log(`  Backend:   ${isHttpMode() ? 'http' : 'local'}`);
+  console.log(`  Device:    ${embeddingConfig.device}`);
+  console.log(`  Threads:   ${embeddingConfig.threads}`);
+  console.log(`  Batch:     ${embeddingConfig.batchSize} nodes`);
+  console.log(`  Sub-batch: ${embeddingConfig.subBatchSize} chunks`);
+};

gitnexus/src/cli/group.ts

@@ -184,6 +184,83 @@ export function registerGroupCommands(program: Command): void {
       }
     });
 
+  group
+    .command('impact <name>')
+    .description('Cross-repo impact for a symbol in one member repo of a group')
+    .requiredOption('--target <symbol>', 'Symbol or file name to analyze')
+    .requiredOption(
+      '--repo <groupPath>',
+      'Member path from group.yaml (e.g. app/backend), not the indexed repo name',
+    )
+    .option('--direction <dir>', 'upstream or downstream', 'upstream')
+    .option('--service <path>', 'Optional monorepo service directory prefix (path filter)')
+    .option(
+      '--subgroup <path>',
+      'Optional prefix limiting which group repos participate in cross fan-out',
+    )
+    .option('--max-depth <n>', 'Max graph traversal depth')
+    .option('--cross-depth <n>', 'Cross-repository hop depth')
+    .option('--min-confidence <n>', 'Minimum relation confidence (0–1)')
+    .option('--include-tests', 'Include test files in traversal', false)
+    .option('--timeout-ms <n>', 'Phase-1 local impact wall time in milliseconds')
+    .option('--json', 'JSON output')
+    .action(async (name: string, opts: Record<string, string | boolean | undefined>) => {
+      const { LocalBackend } = await import('../mcp/local/local-backend.js');
+
+      const backend = new LocalBackend();
+      try {
+        await backend.init();
+
+        const payload: Record<string, unknown> = {
+          name,
+          repo: opts.repo,
+          target: opts.target,
+          direction: (opts.direction as string) || 'upstream',
+        };
+        if (opts.service) payload.service = opts.service;
+        if (opts.subgroup) payload.subgroup = opts.subgroup;
+        if (opts.maxDepth !== undefined && opts.maxDepth !== '') {
+          const n = parseInt(String(opts.maxDepth), 10);
+          if (!Number.isNaN(n)) payload.maxDepth = n;
+        }
+        if (opts.crossDepth !== undefined && opts.crossDepth !== '') {
+          const n = parseInt(String(opts.crossDepth), 10);
+          if (!Number.isNaN(n)) payload.crossDepth = n;
+        }
+        if (opts.minConfidence !== undefined && opts.minConfidence !== '') {
+          const n = parseFloat(String(opts.minConfidence));
+          if (!Number.isNaN(n)) payload.minConfidence = n;
+        }
+        if (opts.timeoutMs !== undefined && opts.timeoutMs !== '') {
+          const n = parseInt(String(opts.timeoutMs), 10);
+          if (!Number.isNaN(n)) payload.timeoutMs = n;
+        }
+        if (opts.includeTests) payload.includeTests = true;
+
+        const raw = await backend.getGroupService().groupImpact(payload);
+        if (raw && typeof raw === 'object' && 'error' in raw) {
+          console.error(String((raw as { error: string }).error));
+          process.exitCode = 1;
+          return;
+        }
+
+        if (opts.json) {
+          console.log(JSON.stringify(raw, null, 2));
+        } else {
+          const summary = (raw as { summary?: Record<string, number> })?.summary;
+          const risk = (raw as { risk?: string })?.risk;
+          console.log(`Group impact for "${name}" (${String(opts.repo)}): risk=${risk ?? '?'}`);
+          if (summary) {
+            console.log(
+              `  direct=${summary.direct ?? 0} processes=${summary.processes_affected ?? 0} cross=${summary.cross_repo_hits ?? 0}`,
+            );
+          }
+        }
+      } finally {
+        await backend.dispose().catch(() => {});
+      }
+    });
+
   group
     .command('query <name> <query>')
     .description('Search execution flows across all repos in a group')

gitnexus/src/cli/index-repo.ts

@@ -14,10 +14,10 @@ import fs from 'fs/promises';
 import {
   getStoragePaths,
   loadMeta,
-  addToGitignore,
+  ensureGitNexusIgnored,
   registerRepo,
 } from '../storage/repo-manager.js';
-import { getGitRoot, isGitRepo } from '../storage/git.js';
+import { getGitRoot, getRemoteUrl, isGitRepo } from '../storage/git.js';
 
 export interface IndexOptions {
   force?: boolean;
@@ -107,8 +107,15 @@ export const indexCommand = async (inputPathParts?: string[], options?: IndexOpt
   }
 
   // ── Register in global registry ───────────────────────────────────
+  // Refresh the on-disk meta with a freshly captured `remoteUrl` if
+  // it's missing, so an `index` of an older `.gitnexus/` still gets
+  // sibling-clone fingerprinting on subsequent use without forcing a
+  // full re-analyze.
+  if (!meta.remoteUrl && isGitRepo(repoPath)) {
+    meta.remoteUrl = getRemoteUrl(repoPath);
+  }
   await registerRepo(repoPath, meta);
-  await addToGitignore(repoPath);
+  await ensureGitNexusIgnored(repoPath);
 
   const projectName = path.basename(repoPath);
   const { stats } = meta;

gitnexus/src/cli/index.ts

@@ -24,10 +24,18 @@ program
   .description('Index a repository (full analysis)')
   .option('-f, --force', 'Force full re-index even if up to date')
   .option('--embeddings', 'Enable embedding generation for semantic search (off by default)')
+  .option(
+    '--drop-embeddings',
+    'Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` ' +
+      'preserves any embeddings already present in the index.',
+  )
   .option('--skills', 'Generate repo-specific skill files from detected communities')
   .option('--skip-agents-md', 'Skip updating the gitnexus section in AGENTS.md and CLAUDE.md')
   .option('--no-stats', 'Omit volatile file/symbol counts from AGENTS.md and CLAUDE.md')
-  .option('--skip-git', 'Index a folder without requiring a .git directory')
+  .option(
+    '--skip-git',
+    'Treat the provided path/cwd as the index root and skip parent git-root discovery',
+  )
   .option(
     '--name <alias>',
     'Register this repo under a custom name in ~/.gitnexus/registry.json ' +
@@ -39,9 +47,29 @@ program
       'Leaves `-r <name>` ambiguous for the two paths; use -r <path> to disambiguate.',
   )
   .option('-v, --verbose', 'Enable verbose ingestion warnings (default: false)')
+  .option(
+    '--max-file-size <kb>',
+    'Skip files larger than this (KB). Default: 512. Hard cap: 32768 (tree-sitter limit).',
+  )
+  .option(
+    '--worker-timeout <seconds>',
+    'Worker sub-batch idle timeout before retry/fallback. Default: 30.',
+  )
+  .option('--embedding-threads <n>', 'Limit local ONNX embedding CPU threads')
+  .option('--embedding-batch-size <n>', 'Number of nodes per embedding batch')
+  .option('--embedding-sub-batch-size <n>', 'Number of chunks per embedding model call')
+  .option('--embedding-device <device>', 'Embedding device: auto, cpu, dml, cuda, or wasm')
   .addHelpText(
     'after',
-    '\nEnvironment variables:\n  GITNEXUS_NO_GITIGNORE=1  Skip .gitignore parsing (still reads .gitnexusignore)',
+    '\nEnvironment variables:\n' +
+      '  GITNEXUS_NO_GITIGNORE=1   Skip .gitignore parsing (still reads .gitnexusignore)\n' +
+      '  GITNEXUS_MAX_FILE_SIZE=N  Override large-file skip threshold (KB). Default 512, max 32768.\n' +
+      '  GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=N  Worker idle timeout in milliseconds. Default 30000.\n' +
+      '  GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES=N  Worker job byte budget. Default 8388608.\n' +
+      '  GITNEXUS_EMBEDDING_THREADS=N  Limit local ONNX CPU threads for --embeddings.\n' +
+      '  GITNEXUS_SEMANTIC_EXACT_SCAN_LIMIT=N  Max embedding chunks for exact-scan fallback. Default 10000.\n' +
+      '\nTip: `.gitnexusignore` supports `.gitignore`-style negation. Add e.g.\n' +
+      '     `!__tests__/` to index a directory that is auto-filtered by default (#771).',
   )
   .action(createLazyAction(() => import('./analyze.js'), 'analyzeCommand'));
 
@@ -76,6 +104,11 @@ program
   .description('Show index status for current repo')
   .action(createLazyAction(() => import('./status.js'), 'statusCommand'));
 
+program
+  .command('doctor')
+  .description('Show runtime platform capabilities and embedding configuration')
+  .action(createLazyAction(() => import('./doctor.js'), 'doctorCommand'));
+
 program
   .command('clean')
   .description('Delete GitNexus index for current repo')
@@ -83,6 +116,15 @@ program
   .option('--all', 'Clean all indexed repos')
   .action(createLazyAction(() => import('./clean.js'), 'cleanCommand'));
 
+program
+  .command('remove <target>')
+  .description(
+    'Delete the GitNexus index for a registered repo (by alias, name, or absolute path). ' +
+      'Unlike `clean`, does not require being inside the repo. Idempotent on unknown targets.',
+  )
+  .option('-f, --force', 'Skip confirmation prompt')
+  .action(createLazyAction(() => import('./remove.js'), 'removeCommand'));
+
 program
   .command('wiki [path]')
   .description('Generate repository wiki from knowledge graph')
@@ -151,6 +193,15 @@ program
   .option('-r, --repo <name>', 'Target repository')
   .action(createLazyAction(() => import('./tool.js'), 'cypherCommand'));
 
+program
+  .command('detect-changes')
+  .alias('detect_changes')
+  .description('Map git diff hunks to indexed symbols and affected execution flows')
+  .option('-s, --scope <scope>', 'What to analyze: unstaged, staged, all, or compare', 'unstaged')
+  .option('-b, --base-ref <ref>', 'Branch/commit for compare scope (e.g. main)')
+  .option('-r, --repo <name>', 'Target repository')
+  .action(createLazyAction(() => import('./tool.js'), 'detectChangesCommand'));
+
 // ─── Eval Server (persistent daemon for SWE-bench) ─────────────────
 
 program

gitnexus/src/cli/remove.ts

@@ -0,0 +1,110 @@
+/**
+ * Remove Command (#664)
+ *
+ * Delete the `.gitnexus/` index for a registered repo and unregister it
+ * from the global registry (~/.gitnexus/registry.json). The target is
+ * identified by alias / basename-derived name / remote-inferred name /
+ * absolute path — no `--repo` flag, just a positional argument so the
+ * destructive-command ergonomics match `clean` (which is also
+ * destructive but scoped to `process.cwd()`).
+ *
+ * Compared to `clean`:
+ *   - `clean`  acts on the repo discovered by walking up from cwd.
+ *   - `remove` acts on any registered repo identified by name or path.
+ *
+ * Behaviour notes:
+ *   - Idempotent on unknown targets: exits 0 with a warning so that
+ *     `remove X && analyze Y` keeps working in scripts. Per #664:
+ *     "behave atomically and idempotently so retries are safe".
+ *   - Atomic order mirrors `clean`: fs.rm FIRST, then unregister. A
+ *     partial failure leaves the registry pointing at a missing dir
+ *     (recoverable by `listRegisteredRepos({ validate: true })` on
+ *     next read) rather than the opposite, which would orphan
+ *     .gitnexus/ directories on disk.
+ *   - `-f` / `--force` matches the confirmation-skip semantics of
+ *     `clean -f`. (Distinct from `analyze --force`, which re-indexes;
+ *     here there is no pipeline, so no conflation.)
+ */
+
+import fs from 'fs/promises';
+import {
+  readRegistry,
+  resolveRegistryEntry,
+  assertSafeStoragePath,
+  unregisterRepo,
+  RegistryNotFoundError,
+  RegistryAmbiguousTargetError,
+  UnsafeStoragePathError,
+} from '../storage/repo-manager.js';
+
+export const removeCommand = async (target: string, options?: { force?: boolean }) => {
+  // Read the registry snapshot once and pass it to the resolver — this
+  // lets us render the "before" state in the dry-run path without a
+  // second disk read.
+  const entries = await readRegistry();
+
+  let entry;
+  try {
+    entry = resolveRegistryEntry(entries, target);
+  } catch (err) {
+    if (err instanceof RegistryNotFoundError) {
+      // Idempotent: missing target is a no-op warning, not an error.
+      // The `availableNames` hint comes from the error itself so users
+      // can see what they might have meant.
+      console.warn(`Nothing to remove: ${err.message}`);
+      return;
+    }
+    if (err instanceof RegistryAmbiguousTargetError) {
+      // Duplicate aliases are allowed via --allow-duplicate-name (#829);
+      // refuse to guess which one the user meant — surface the full list
+      // and exit non-zero so scripts don't silently pick the wrong repo.
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+    throw err;
+  }
+
+  // Confirmation gate — same shape as `clean`. Default is a dry-run
+  // that describes what would be deleted; `--force` actually deletes.
+  if (!options?.force) {
+    console.log(`This will delete the GitNexus index for: ${entry.name}`);
+    console.log(`   Path:    ${entry.path}`);
+    console.log(`   Storage: ${entry.storagePath}`);
+    console.log('\nRun with --force to confirm deletion.');
+    return;
+  }
+
+  // Safety guard (#1003 review — @magyargergo): refuse to proceed if
+  // the registry entry's `storagePath` isn't the canonical
+  // `<entry.path>/.gitnexus` subfolder. `~/.gitnexus/registry.json` is
+  // user-writable, so a corrupted or hand-edited entry could point
+  // storagePath at the repo root, an empty string (→ cwd), a parent
+  // dir, or anywhere else; `fs.rm(recursive: true, force: true)` on
+  // any of those would be a runtime disaster. Bail before touching
+  // disk, with an actionable hint for recovering a broken registry.
+  try {
+    assertSafeStoragePath(entry);
+  } catch (err) {
+    if (err instanceof UnsafeStoragePathError) {
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+    throw err;
+  }
+
+  // Deletion order: fs.rm first, then unregister. If fs.rm fails mid-way,
+  // the registry entry stays so the user can retry. If fs.rm succeeds but
+  // unregister throws (e.g. ENOSPC on registry write), the entry becomes
+  // orphaned — `listRegisteredRepos({ validate: true })` prunes those on
+  // next read, so the failure is self-healing.
+  try {
+    await fs.rm(entry.storagePath, { recursive: true, force: true });
+    await unregisterRepo(entry.path);
+    console.log(`Removed: ${entry.name}`);
+    console.log(`   Path:    ${entry.path}`);
+    console.log(`   Storage: ${entry.storagePath}`);
+  } catch (err) {
+    console.error(`Failed to remove ${entry.name}:`, err);
+    process.exit(1);
+  }
+};

gitnexus/src/cli/setup.ts

@@ -13,6 +13,7 @@ import { execFile, execFileSync } from 'child_process';
 import { promisify } from 'util';
 import { fileURLToPath } from 'url';
 import { glob } from 'glob';
+import { parseTree, modify, applyEdits, ParseError, parse as parseJsonc } from 'jsonc-parser';
 import { getGlobalDir } from '../storage/repo-manager.js';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -31,15 +32,27 @@ interface SetupResult {
  */
 function resolveGitnexusBin(): string | null {
   try {
-    const cmd = process.platform === 'win32' ? 'where' : 'which';
-    const resolved = execFileSync(cmd, ['gitnexus'], {
+    const isWin = process.platform === 'win32';
+    const cmd = isWin ? 'where' : 'which';
+    const output = execFileSync(cmd, ['gitnexus'], {
       encoding: 'utf-8',
       timeout: 5000,
       stdio: ['ignore', 'pipe', 'ignore'],
-    })
-      .split('\n')[0]
-      .trim();
-    return resolved || null;
+    });
+    const lines = output
+      .split('\n')
+      .map((l) => l.trim())
+      .filter(Boolean);
+
+    if (isWin) {
+      // On Windows, `where` returns multiple entries (e.g. the POSIX shell
+      // script AND the .cmd/.bat wrapper). Prefer the wrapper because
+      // child_process.spawn() cannot execute a shell script directly.
+      const cmdLine = lines.find((l) => /\.(cmd|bat)$/i.test(l));
+      return cmdLine || lines[0] || null;
+    }
+
+    return lines[0] || null;
   } catch {
     return null;
   }
@@ -76,38 +89,70 @@ function getMcpEntry() {
 }
 
 /**
- * Merge gitnexus entry into an existing MCP config JSON object.
- * Returns the updated config.
+ * OpenCode uses a different MCP format: { type: "local", command: [...] }
+ * where command is a flat array (command + args combined).
  */
-function mergeMcpConfig(existing: any): any {
-  if (!existing || typeof existing !== 'object') {
-    existing = {};
+function getOpenCodeMcpEntry() {
+  const bin = resolveGitnexusBin();
+
+  if (bin) {
+    return { type: 'local', command: [bin, 'mcp'] };
   }
-  if (!existing.mcpServers || typeof existing.mcpServers !== 'object') {
-    existing.mcpServers = {};
+
+  if (process.platform === 'win32') {
+    return { type: 'local', command: ['cmd', '/c', 'npx', '-y', 'gitnexus@latest', 'mcp'] };
   }
-  existing.mcpServers.gitnexus = getMcpEntry();
-  return existing;
+  return { type: 'local', command: ['npx', '-y', 'gitnexus@latest', 'mcp'] };
 }
 
 /**
- * Try to read a JSON file, returning null if it doesn't exist or is invalid.
+ * Detect indentation style from file content.
+ * Returns formatting options matching the file's existing style.
  */
-async function readJsonFile(filePath: string): Promise<any | null> {
+function detectIndentation(raw: string): { tabSize: number; insertSpaces: boolean } {
+  const firstIndented = raw.match(/^( +|\t)/m);
+  if (!firstIndented) return { tabSize: 2, insertSpaces: true };
+  if (firstIndented[1] === '\t') return { tabSize: 1, insertSpaces: false };
+  return { tabSize: firstIndented[1].length, insertSpaces: true };
+}
+
+/**
+ * Merge a key/value pair into a JSONC config file, preserving comments and formatting.
+ * If the file is genuinely corrupt (not valid JSONC), leaves it untouched.
+ */
+async function mergeJsoncFile(
+  filePath: string,
+  keyPath: string[],
+  value: unknown,
+): Promise<boolean> {
+  let raw: string;
   try {
-    const raw = await fs.readFile(filePath, 'utf-8');
-    return JSON.parse(raw);
+    raw = await fs.readFile(filePath, 'utf-8');
   } catch {
-    return null;
+    raw = '';
   }
-}
 
-/**
- * Write JSON to a file, creating parent directories if needed.
- */
-async function writeJsonFile(filePath: string, data: any): Promise<void> {
-  await fs.mkdir(path.dirname(filePath), { recursive: true });
-  await fs.writeFile(filePath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+  if (raw.trim().length === 0) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    const formattingOptions = { tabSize: 2, insertSpaces: true };
+    const edits = modify('{}', keyPath, value, { formattingOptions });
+    const result = applyEdits('{}', edits);
+    await fs.writeFile(filePath, result, 'utf-8');
+    return true;
+  }
+
+  const parseErrors: ParseError[] = [];
+  const tree = parseTree(raw, parseErrors);
+
+  if (tree && tree.type === 'object' && parseErrors.length === 0) {
+    const formattingOptions = detectIndentation(raw);
+    const edits = modify(raw, keyPath, value, { formattingOptions });
+    const result = applyEdits(raw, edits);
+    await fs.writeFile(filePath, result, 'utf-8');
+    return true;
+  }
+
+  return false;
 }
 
 /**
@@ -133,10 +178,12 @@ async function setupCursor(result: SetupResult): Promise<void> {
 
   const mcpPath = path.join(cursorDir, 'mcp.json');
   try {
-    const existing = await readJsonFile(mcpPath);
-    const updated = mergeMcpConfig(existing);
-    await writeJsonFile(mcpPath, updated);
-    result.configured.push('Cursor');
+    const ok = await mergeJsoncFile(mcpPath, ['mcpServers', 'gitnexus'], getMcpEntry());
+    if (ok) {
+      result.configured.push('Cursor');
+    } else {
+      result.errors.push('Cursor: mcp.json is corrupt — skipping to preserve existing content');
+    }
   } catch (err: any) {
     result.errors.push(`Cursor: ${err.message}`);
   }
@@ -152,10 +199,14 @@ async function setupClaudeCode(result: SetupResult): Promise<void> {
   // Claude Code stores MCP config in ~/.claude.json
   const mcpPath = path.join(os.homedir(), '.claude.json');
   try {
-    const existing = await readJsonFile(mcpPath);
-    const updated = mergeMcpConfig(existing);
-    await writeJsonFile(mcpPath, updated);
-    result.configured.push('Claude Code');
+    const ok = await mergeJsoncFile(mcpPath, ['mcpServers', 'gitnexus'], getMcpEntry());
+    if (ok) {
+      result.configured.push('Claude Code');
+    } else {
+      result.errors.push(
+        'Claude Code: .claude.json is corrupt — skipping to preserve existing content',
+      );
+    }
   } catch (err: any) {
     result.errors.push(`Claude Code: ${err.message}`);
   }
@@ -179,9 +230,90 @@ async function installClaudeCodeSkills(result: SetupResult): Promise<void> {
   }
 }
 
+/**
+ * Check whether an event array already contains a gitnexus-hook entry.
+ */
+function hasGitnexusHook(hooksObj: any, eventName: string): boolean {
+  const entries = hooksObj?.[eventName];
+  if (!Array.isArray(entries)) return false;
+  return entries.some(
+    (h: any) =>
+      Array.isArray(h.hooks) &&
+      h.hooks.some(
+        (hh: any) => typeof hh.command === 'string' && hh.command.includes('gitnexus-hook'),
+      ),
+  );
+}
+
+/**
+ * Merge hook entries into a JSONC settings file, preserving comments and formatting.
+ * Uses chained modify()+applyEdits() calls to append to arrays without a full
+ * JSON.stringify roundtrip that would strip comments.
+ */
+async function mergeHooksJsonc(
+  filePath: string,
+  entries: Array<{ eventName: string; value: unknown }>,
+): Promise<boolean> {
+  let raw: string;
+  try {
+    raw = await fs.readFile(filePath, 'utf-8');
+  } catch {
+    raw = '';
+  }
+
+  if (raw.trim().length === 0) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    const hooks: any = {};
+    for (const { eventName, value } of entries) {
+      hooks[eventName] = [value];
+    }
+    const formattingOptions = { tabSize: 2, insertSpaces: true };
+    const edits = modify('{}', ['hooks'], hooks, { formattingOptions });
+    await fs.writeFile(filePath, applyEdits('{}', edits), 'utf-8');
+    return true;
+  }
+
+  const parseErrors: ParseError[] = [];
+  const tree = parseTree(raw, parseErrors);
+
+  if (!tree || tree.type !== 'object' || parseErrors.length > 0) {
+    return false;
+  }
+
+  const formattingOptions = detectIndentation(raw);
+  let current = raw;
+
+  for (const { eventName, value } of entries) {
+    // Re-parse after each edit to get a fresh insertion index.
+    const currentTree = parseTree(current, []);
+    const hooksNode = currentTree?.children?.find(
+      (c) => c.type === 'property' && c.children?.[0]?.value === 'hooks',
+    );
+    const eventNode = hooksNode?.children?.[1]?.children?.find(
+      (c: any) => c.type === 'property' && c.children?.[0]?.value === eventName,
+    );
+
+    let insertIndex: number;
+    if (eventNode?.children?.[1] && Array.isArray(eventNode.children[1].children)) {
+      insertIndex = eventNode.children[1].children.length;
+    } else {
+      insertIndex = 0;
+    }
+
+    const edits = modify(current, ['hooks', eventName, insertIndex], value, {
+      formattingOptions,
+    });
+    current = applyEdits(current, edits);
+  }
+
+  await fs.writeFile(filePath, current, 'utf-8');
+  return true;
+}
+
 /**
  * Install GitNexus hooks to ~/.claude/settings.json for Claude Code.
- * Merges hook config without overwriting existing hooks.
+ * Merges hook config without overwriting existing hooks, preserving
+ * comments and formatting in the JSONC file.
  */
 async function installClaudeCodeHooks(result: SetupResult): Promise<void> {
   const claudeDir = path.join(os.homedir(), '.claude');
@@ -202,8 +334,6 @@ async function installClaudeCodeHooks(result: SetupResult): Promise<void> {
     const dest = path.join(destHooksDir, 'gitnexus-hook.cjs');
     try {
       let content = await fs.readFile(src, 'utf-8');
-      // Inject resolved CLI path so the copied hook can find the CLI
-      // even when it's no longer inside the npm package tree
       const resolvedCli = path.join(__dirname, '..', 'cli', 'index.js');
       const normalizedCli = path.resolve(resolvedCli).replace(/\\/g, '/');
       const jsonCli = JSON.stringify(normalizedCli);
@@ -219,40 +349,67 @@ async function installClaudeCodeHooks(result: SetupResult): Promise<void> {
     const hookPath = path.join(destHooksDir, 'gitnexus-hook.cjs').replace(/\\/g, '/');
     const hookCmd = `node "${hookPath.replace(/"/g, '\\"')}"`;
 
-    // Merge hook config into ~/.claude/settings.json
-    const existing = (await readJsonFile(settingsPath)) || {};
-    if (!existing.hooks) existing.hooks = {};
+    // Check which hook events need entries (idempotent: skip if already registered)
+    const parsed = await (async () => {
+      try {
+        const r = await fs.readFile(settingsPath, 'utf-8');
+        return parseJsonc(r);
+      } catch {
+        return null;
+      }
+    })();
+
+    const hookEntries: Array<{ eventName: string; value: unknown }> = [];
 
     // NOTE: SessionStart hooks are broken on Windows (Claude Code bug #23576).
     // Session context is delivered via CLAUDE.md / skills instead.
 
-    // Helper: add a hook entry if one with 'gitnexus-hook' isn't already registered
-    interface HookEntry {
-      hooks?: Array<{ command?: string }>;
+    if (!hasGitnexusHook(parsed?.hooks, 'PreToolUse')) {
+      hookEntries.push({
+        eventName: 'PreToolUse',
+        value: {
+          matcher: 'Grep|Glob|Bash',
+          hooks: [
+            {
+              type: 'command',
+              command: hookCmd,
+              timeout: 10,
+              statusMessage: 'Enriching with GitNexus graph context...',
+            },
+          ],
+        },
+      });
     }
-    function ensureHookEntry(
-      eventName: string,
-      matcher: string,
-      timeout: number,
-      statusMessage: string,
-    ) {
-      if (!existing.hooks[eventName]) existing.hooks[eventName] = [];
-      const hasHook = existing.hooks[eventName].some((h: HookEntry) =>
-        h.hooks?.some((hh) => hh.command?.includes('gitnexus-hook')),
+    if (!hasGitnexusHook(parsed?.hooks, 'PostToolUse')) {
+      hookEntries.push({
+        eventName: 'PostToolUse',
+        value: {
+          matcher: 'Bash',
+          hooks: [
+            {
+              type: 'command',
+              command: hookCmd,
+              timeout: 10,
+              statusMessage: 'Checking GitNexus index freshness...',
+            },
+          ],
+        },
+      });
+    }
+
+    if (hookEntries.length === 0) {
+      result.configured.push('Claude Code hooks (already configured)');
+      return;
+    }
+
+    const ok = await mergeHooksJsonc(settingsPath, hookEntries);
+    if (ok) {
+      result.configured.push('Claude Code hooks (PreToolUse, PostToolUse)');
+    } else {
+      result.errors.push(
+        'Claude Code hooks: settings.json is corrupt — skipping to preserve existing content',
       );
-      if (!hasHook) {
-        existing.hooks[eventName].push({
-          matcher,
-          hooks: [{ type: 'command', command: hookCmd, timeout, statusMessage }],
-        });
-      }
     }
-
-    ensureHookEntry('PreToolUse', 'Grep|Glob|Bash', 10, 'Enriching with GitNexus graph context...');
-    ensureHookEntry('PostToolUse', 'Bash', 10, 'Checking GitNexus index freshness...');
-
-    await writeJsonFile(settingsPath, existing);
-    result.configured.push('Claude Code hooks (PreToolUse, PostToolUse)');
   } catch (err: any) {
     result.errors.push(`Claude Code hooks: ${err.message}`);
   }
@@ -267,12 +424,14 @@ async function setupOpenCode(result: SetupResult): Promise<void> {
 
   const configPath = path.join(opencodeDir, 'opencode.json');
   try {
-    const existing = await readJsonFile(configPath);
-    const config = existing || {};
-    if (!config.mcp) config.mcp = {};
-    config.mcp.gitnexus = getMcpEntry();
-    await writeJsonFile(configPath, config);
-    result.configured.push('OpenCode');
+    const ok = await mergeJsoncFile(configPath, ['mcp', 'gitnexus'], getOpenCodeMcpEntry());
+    if (ok) {
+      result.configured.push('OpenCode');
+    } else {
+      result.errors.push(
+        'OpenCode: opencode.json is corrupt — skipping to preserve existing content',
+      );
+    }
   } catch (err: any) {
     result.errors.push(`OpenCode: ${err.message}`);
   }
@@ -434,13 +593,13 @@ async function installCursorSkills(result: SetupResult): Promise<void> {
 }
 
 /**
- * Install global OpenCode skills to ~/.config/opencode/skill/gitnexus/
+ * Install global OpenCode skills to ~/.config/opencode/skills/gitnexus/
  */
 async function installOpenCodeSkills(result: SetupResult): Promise<void> {
   const opencodeDir = path.join(os.homedir(), '.config', 'opencode');
   if (!(await dirExists(opencodeDir))) return;
 
-  const skillsDir = path.join(opencodeDir, 'skill');
+  const skillsDir = path.join(opencodeDir, 'skills');
   try {
     const installed = await installSkillsTo(skillsDir);
     if (installed.length > 0) {

gitnexus/src/cli/tool.ts

@@ -164,3 +164,55 @@ export async function cypherCommand(
   });
   output(result);
 }
+
+function formatDetectChangesResult(result: any): string {
+  if (result?.error) return `Error: ${result.error}`;
+
+  const summary = result?.summary || {};
+  if ((summary.changed_count || 0) === 0) {
+    return 'No changes detected.';
+  }
+
+  const lines: string[] = [];
+  lines.push(`Changes: ${summary.changed_files || 0} files, ${summary.changed_count || 0} symbols`);
+  lines.push(`Affected processes: ${summary.affected_count || 0}`);
+  lines.push(`Risk level: ${summary.risk_level || 'unknown'}`);
+  lines.push('');
+
+  const changed = result?.changed_symbols || [];
+  if (changed.length > 0) {
+    lines.push('Changed symbols:');
+    for (const symbol of changed.slice(0, 15)) {
+      lines.push(`  ${symbol.type} ${symbol.name} → ${symbol.filePath}`);
+    }
+    if (changed.length > 15) {
+      lines.push(`  ... and ${changed.length - 15} more`);
+    }
+    lines.push('');
+  }
+
+  const affected = result?.affected_processes || [];
+  if (affected.length > 0) {
+    lines.push('Affected execution flows:');
+    for (const processInfo of affected.slice(0, 10)) {
+      const steps = (processInfo.changed_steps || []).map((s: any) => s.symbol).join(', ');
+      lines.push(`  • ${processInfo.name} (${processInfo.step_count} steps) — changed: ${steps}`);
+    }
+  }
+
+  return lines.join('\n').trim();
+}
+
+export async function detectChangesCommand(options?: {
+  scope?: string;
+  baseRef?: string;
+  repo?: string;
+}): Promise<void> {
+  const backend = await getBackend();
+  const result = await backend.callTool('detect_changes', {
+    scope: options?.scope || 'unstaged',
+    base_ref: options?.baseRef,
+    repo: options?.repo,
+  });
+  output(formatDetectChangesResult(result));
+}

gitnexus/src/config/ignore-service.ts

@@ -270,17 +270,21 @@ const IGNORED_FILES = new Set([
   '.env.example',
 ]);
 
-// NOTE: Negation patterns in .gitnexusignore (e.g. `!vendor/`) cannot override
-// entries in DEFAULT_IGNORE_LIST — this is intentional. The hardcoded list protects
-// against indexing directories that are almost never source code (node_modules, .git, etc.).
-// Users who need to include such directories should remove them from the hardcoded list.
+// The hardcoded DEFAULT_IGNORE_LIST is the "safety net" default: directories
+// that are almost never source code (node_modules, .git, dist, __tests__,
+// etc.). Users who legitimately need to index one of these can negate the
+// hardcoded rule via a `!pattern` line in `.gitnexusignore` (#771) — same
+// semantics as `.gitignore` negation. That override is applied in
+// `createIgnoreFilter` below; `shouldIgnorePath` itself stays a pure
+// hardcoded-list check so its callers (wiki generator, tests) get
+// deterministic results independent of per-repo config.
 export const shouldIgnorePath = (filePath: string): boolean => {
   const normalizedPath = filePath.replace(/\\/g, '/');
   const parts = normalizedPath.split('/');
   const fileName = parts[parts.length - 1];
   const fileNameLower = fileName.toLowerCase();
 
-  // Check if any path segment is in ignore list
+  // Check if any path segment is in the hardcoded ignore list.
   for (const part of parts) {
     if (DEFAULT_IGNORE_LIST.has(part)) {
       return true;
@@ -369,6 +373,42 @@ export const loadIgnoreRules = async (
   return hasRules ? ig : null;
 };
 
+/**
+ * Walk ancestor segments of `rel` and check whether `.gitnexusignore`
+ * (or `.gitignore`) contains an explicit `!pattern` negation that
+ * applies. Returns true as soon as any segment — or the path itself —
+ * is matched by a negation rule.
+ *
+ * Why this exists (#771): the hardcoded DEFAULT_IGNORE_LIST would
+ * otherwise block indexing of directories like `__tests__/` even when
+ * the user has an explicit `!__tests__/` line in `.gitnexusignore`.
+ * Mirroring `.gitignore` negation semantics: a user's explicit
+ * unignore of a parent directory implicitly unignores everything
+ * underneath, so we walk the ancestor chain rather than only testing
+ * the leaf.
+ *
+ * The `ignore` package's `test(path)` returns `{ignored, unignored}`;
+ * `unignored: true` is the "a negation rule matched this path"
+ * signal. Children of a negated directory return
+ * `{ignored: false, unignored: false}` on a direct test, which is why
+ * we also walk the ancestors here.
+ */
+const hasExplicitUnignore = (ig: Ignore, rel: string): boolean => {
+  // Direct match on the path (as a file).
+  if (ig.test(rel).unignored) return true;
+  // Direct match on the path treated as a directory — `!dir/` matches
+  // here when rel is the directory itself.
+  if (ig.test(rel + '/').unignored) return true;
+  // Walk ancestor segments. `!parent/` should propagate to every
+  // descendant the same way `.gitignore` negation propagates.
+  const parts = rel.split('/');
+  for (let i = parts.length - 1; i > 0; i--) {
+    const ancestor = parts.slice(0, i).join('/') + '/';
+    if (ig.test(ancestor).unignored) return true;
+  }
+  return false;
+};
+
 /**
  * Create a glob-compatible ignore filter combining:
  * - .gitignore / .gitnexusignore patterns (via `ignore` package)
@@ -376,6 +416,15 @@ export const loadIgnoreRules = async (
  *
  * Returns an IgnoreLike object for glob's `ignore` option,
  * enabling directory-level pruning during traversal.
+ *
+ * Precedence (#771): user's `.gitnexusignore` negation patterns take
+ * priority over the hardcoded list, matching `.gitignore` semantics.
+ * An explicit `!pattern` rule unignores descendants even when they
+ * would otherwise be blocked by DEFAULT_IGNORE_LIST — UNLESS a more
+ * specific rule in the same file re-ignores a subset (e.g.
+ * `!__tests__/` paired with `__tests__/generated/` blocks the child
+ * while leaving the parent negated). Last-match-wins is enforced by
+ * consulting `ig.ignores(rel)` after `hasExplicitUnignore`.
  */
 export const createIgnoreFilter = async (repoPath: string, options?: IgnoreOptions) => {
   const ig = await loadIgnoreRules(repoPath, options);
@@ -386,16 +435,33 @@ export const createIgnoreFilter = async (repoPath: string, options?: IgnoreOptio
       // which is what the `ignore` package expects. No explicit normalization needed.
       const rel = p.relative();
       if (!rel) return false;
+      // User's .gitnexusignore negation takes precedence over hardcoded
+      // rules (#771). If any ancestor or the path itself was explicitly
+      // unignored AND no more-specific rule re-ignores this exact path,
+      // allow it through. The `!ig.ignores(rel)` guard matches
+      // .gitignore's last-match-wins semantics: `!__tests__/` followed
+      // by `__tests__/generated/` negates the parent but still blocks
+      // the re-ignored child.
+      if (ig && hasExplicitUnignore(ig, rel) && !ig.ignores(rel)) return false;
       // Check .gitignore / .gitnexusignore patterns
       if (ig && ig.ignores(rel)) return true;
       // Fall back to hardcoded rules
       return shouldIgnorePath(rel);
     },
     childrenIgnored(p: Path): boolean {
-      // Fast path: check directory name against hardcoded list.
       // Note: dot-directories (.git, .vscode, etc.) are primarily excluded by
-      // glob's `dot: false` option in filesystem-walker.ts. This check is
-      // defense-in-depth — do not remove `dot: false` assuming this covers it.
+      // glob's `dot: false` option in filesystem-walker.ts. The hardcoded
+      // list check below is defense-in-depth — do not remove `dot: false`
+      // assuming this covers it.
+      const rel = p.relative();
+      // User's .gitnexusignore negation takes precedence (#771) — if the
+      // user explicitly unignored this directory or any ancestor via a
+      // !pattern rule, allow descent even if the directory name is in
+      // DEFAULT_IGNORE_LIST. The `!ig.ignores(rel + '/')` guard keeps
+      // last-match-wins: `!__tests__/` + `__tests__/generated/` still
+      // blocks descent into `__tests__/generated/`.
+      if (ig && rel && hasExplicitUnignore(ig, rel) && !ig.ignores(rel + '/')) return false;
+      // Hardcoded list: block descent into well-known noise directories.
       if (DEFAULT_IGNORE_LIST.has(p.name)) return true;
       // Check against .gitignore / .gitnexusignore patterns.
       // Since childrenIgnored is only called for directories, always test with
@@ -405,10 +471,7 @@ export const createIgnoreFilter = async (repoPath: string, options?: IgnoreOptio
       // Bare-name patterns (e.g. `local`) still match `local/` per gitignore spec:
       // the `ignore` package normalizes `dir` and `dir/` to match directories.
       // See: https://github.com/kaelzhang/node-ignore#2-filenames-and-dirnames
-      if (ig) {
-        const rel = p.relative();
-        if (rel && ig.ignores(rel + '/')) return true;
-      }
+      if (ig && rel && ig.ignores(rel + '/')) return true;
       return false;
     },
   };

gitnexus/src/core/embedding-mode.ts

@@ -0,0 +1,54 @@
+/**
+ * Pure derivation of the embedding-mode flags for `runFullAnalysis`.
+ *
+ * Lives in its own module (no native imports) so the branching contract can
+ * be unit-tested without spinning up LadybugDB, tree-sitter, or any of the
+ * other side-effecting dependencies pulled in by `run-analyze.ts`.
+ *
+ * Semantics:
+ *   --drop-embeddings         -> wipe (skip cache load entirely)
+ *   --embeddings              -> load cache, restore, then generate
+ *   --force + existing>0      -> load cache, restore, then generate (regenerate top-up)
+ *   (default) + existing>0    -> preserve only (load + restore, no generation)
+ *   any path with existing=0  -> no cache work, no preservation
+ */
+
+export interface EmbeddingModeInput {
+  force?: boolean;
+  embeddings?: boolean;
+  dropEmbeddings?: boolean;
+}
+
+export interface EmbeddingMode {
+  /** True when phase 4 should run the embedding generation pipeline. */
+  shouldGenerateEmbeddings: boolean;
+  /** True when we should load the cache to re-insert vectors after rebuild without generating new ones. */
+  preserveExistingEmbeddings: boolean;
+  /** True when `--force` upgraded a default analyze into a regeneration because the repo was already embedded. */
+  forceRegenerateEmbeddings: boolean;
+  /** True when we need to load cached embeddings from the existing DB before the rebuild. */
+  shouldLoadCache: boolean;
+}
+
+export function deriveEmbeddingMode(
+  options: EmbeddingModeInput,
+  existingEmbeddingCount: number,
+): EmbeddingMode {
+  const hasExisting = existingEmbeddingCount > 0;
+  const drop = !!options.dropEmbeddings;
+  const explicit = !!options.embeddings;
+  const force = !!options.force;
+
+  const forceRegenerateEmbeddings = force && !explicit && !drop && hasExisting;
+  const preserveExistingEmbeddings =
+    !explicit && !drop && !forceRegenerateEmbeddings && hasExisting;
+  const shouldGenerateEmbeddings = explicit || forceRegenerateEmbeddings;
+  const shouldLoadCache = !drop && (shouldGenerateEmbeddings || preserveExistingEmbeddings);
+
+  return {
+    shouldGenerateEmbeddings,
+    preserveExistingEmbeddings,
+    forceRegenerateEmbeddings,
+    shouldLoadCache,
+  };
+}

gitnexus/src/core/embeddings/ast-utils.ts

@@ -64,16 +64,16 @@ const FUNCTION_LIKE_TYPES = new Set([
  * numbers don't apply.
  */
 export const findFunctionNode = (root: any): any | null => {
-  if (FUNCTION_LIKE_TYPES.has(root.type)) return root;
-
-  for (let i = 0; i < root.namedChildCount; i++) {
-    const child = root.namedChild(i);
-    if (!child) continue;
-    if (FUNCTION_LIKE_TYPES.has(child.type)) return child;
-    const found = findFunctionNode(child);
-    if (found) return found;
+  // Iterative DFS — avoids stack overflow on deeply nested ASTs.
+  const stack = [root];
+  while (stack.length > 0) {
+    const node = stack.pop()!;
+    if (FUNCTION_LIKE_TYPES.has(node.type)) return node;
+    for (let i = node.namedChildCount - 1; i >= 0; i--) {
+      const child = node.namedChild(i);
+      if (child) stack.push(child);
+    }
   }
-
   return null;
 };
 
@@ -98,15 +98,15 @@ export const findDeclarationNode = (root: any): any | null => {
     'impl_item', // Rust: impl
   ]);
 
-  if (CLASS_LIKE_TYPES.has(root.type)) return root;
-
-  for (let i = 0; i < root.namedChildCount; i++) {
-    const child = root.namedChild(i);
-    if (!child) continue;
-    if (CLASS_LIKE_TYPES.has(child.type)) return child;
-    const found = findDeclarationNode(child);
-    if (found) return found;
+  // Iterative DFS — avoids stack overflow on deeply nested ASTs.
+  const stack = [root];
+  while (stack.length > 0) {
+    const node = stack.pop()!;
+    if (CLASS_LIKE_TYPES.has(node.type)) return node;
+    for (let i = node.namedChildCount - 1; i >= 0; i--) {
+      const child = node.namedChild(i);
+      if (child) stack.push(child);
+    }
   }
-
   return null;
 };

gitnexus/src/core/embeddings/chunker.ts

@@ -13,6 +13,12 @@ import { characterChunk } from './character-chunk.js';
 import type { Chunk } from './character-chunk.js';
 import { ensureAndParse, findDeclarationNode, findFunctionNode } from './ast-utils.js';
 import { buildLineIndex, resolveChunkLines } from './line-index.js';
+import {
+  CHUNKING_RULES,
+  CHUNK_MODE_AST_DECLARATION,
+  CHUNK_MODE_AST_FUNCTION,
+  type ChunkingRule,
+} from './types.js';
 
 /**
  * Main chunkNode function: dispatches by label
@@ -40,31 +46,39 @@ export const chunkNode = async (
     ];
   }
 
-  // Only function-like labels get AST chunking
-  if (label === 'Function' || label === 'Method' || label === 'Constructor') {
-    try {
-      const astChunks = await astChunk(content, filePath, startLine, endLine, chunkSize, overlap);
-      if (astChunks.length > 0) return astChunks;
-    } catch {
-      // AST parsing failed — fall through to character fallback
-    }
+  const rule = CHUNKING_RULES[label];
+  if (!rule) {
+    return characterChunk(content, startLine, endLine, chunkSize, overlap);
   }
 
-  if (label === 'Class' || label === 'Interface') {
-    try {
-      const declarationChunks = await declarationChunk(
-        label,
+  try {
+    if (rule.mode === CHUNK_MODE_AST_FUNCTION) {
+      const astChunks = await astChunk(
         content,
         filePath,
         startLine,
         endLine,
         chunkSize,
         overlap,
+        rule,
+      );
+      if (astChunks.length > 0) return astChunks;
+    }
+
+    if (rule.mode === CHUNK_MODE_AST_DECLARATION) {
+      const declarationChunks = await declarationChunk(
+        content,
+        filePath,
+        startLine,
+        endLine,
+        chunkSize,
+        overlap,
+        rule,
       );
       if (declarationChunks.length > 0) return declarationChunks;
-    } catch {
-      // AST parsing failed — fall through to character fallback
     }
+  } catch {
+    // AST parsing failed — fall through to character fallback
   }
 
   // Character-based fallback for everything else
@@ -83,6 +97,7 @@ const astChunk = async (
   endLine: number,
   chunkSize: number,
   overlap: number,
+  rule: ChunkingRule,
 ): Promise<Chunk[]> => {
   const tree = await ensureAndParse(content, filePath);
   if (!tree) return [];
@@ -121,8 +136,8 @@ const astChunk = async (
     statements,
     targetNode.startIndex,
     targetNode.endIndex,
-    true,
-    true,
+    rule.includePrefix,
+    rule.includeSuffix,
   );
 };
 
@@ -145,13 +160,13 @@ const FIELD_LIKE_MEMBER_TYPES = new Set([
 ]);
 
 const declarationChunk = async (
-  label: 'Class' | 'Interface',
   content: string,
   filePath: string,
   startLine: number,
   endLine: number,
   chunkSize: number,
   overlap: number,
+  rule: ChunkingRule,
 ): Promise<Chunk[]> => {
   const tree = await ensureAndParse(content, filePath);
   if (!tree) return [];
@@ -162,7 +177,7 @@ const declarationChunk = async (
   const bodyNode = getDeclarationBodyNode(targetNode);
   if (!bodyNode) return [];
 
-  const members = collectDeclarationUnits(bodyNode, label);
+  const members = collectDeclarationUnits(bodyNode, rule.groupFields);
   if (members.length === 0) return [];
 
   return chunkByUnits(
@@ -174,8 +189,8 @@ const declarationChunk = async (
     members,
     targetNode.startIndex,
     targetNode.endIndex,
-    false,
-    false,
+    rule.includePrefix,
+    rule.includeSuffix,
   );
 };
 
@@ -237,14 +252,22 @@ const chunkByUnits = (
 
     if (candidateEndOffset - chunkStartOffset > chunkSize) {
       const oversizedUnit = units[chunkStartUnitIdx];
+      const oversizedStartOffset =
+        chunkStartUnitIdx === 0 && includeContainerPrefixOnFirstChunk
+          ? containerStartOffset
+          : oversizedUnit.startIndex;
+      const oversizedEndOffset =
+        chunkStartUnitIdx === units.length - 1 && includeContainerSuffixOnLastChunk
+          ? containerEndOffset
+          : oversizedUnit.endIndex;
       const oversizedLineRange = resolveChunkLines(
         lineOffsets,
-        oversizedUnit.startIndex,
-        oversizedUnit.endIndex,
+        oversizedStartOffset,
+        oversizedEndOffset,
         baseStartLine,
       );
       const oversizedChunks = characterChunk(
-        content.slice(oversizedUnit.startIndex, oversizedUnit.endIndex),
+        content.slice(oversizedStartOffset, oversizedEndOffset),
         oversizedLineRange.startLine,
         oversizedLineRange.endLine,
         chunkSize,
@@ -252,8 +275,8 @@ const chunkByUnits = (
       ).map((chunk, offsetIdx) => ({
         ...chunk,
         chunkIndex: chunks.length + offsetIdx,
-        startOffset: chunk.startOffset + oversizedUnit.startIndex,
-        endOffset: chunk.endOffset + oversizedUnit.startIndex,
+        startOffset: chunk.startOffset + oversizedStartOffset,
+        endOffset: chunk.endOffset + oversizedStartOffset,
       }));
       chunks.push(...oversizedChunks);
       chunkStartUnitIdx += 1;
@@ -325,7 +348,7 @@ const getDeclarationBodyNode = (node: any): any | null => {
 
 const collectDeclarationUnits = (
   bodyNode: any,
-  label: 'Class' | 'Interface',
+  groupFields: boolean,
 ): Array<{ startIndex: number; endIndex: number }> => {
   const members: Array<{ startIndex: number; endIndex: number; groupable: boolean }> = [];
 
@@ -335,7 +358,7 @@ const collectDeclarationUnits = (
     members.push({
       startIndex: child.startIndex,
       endIndex: child.endIndex,
-      groupable: label === 'Class' && FIELD_LIKE_MEMBER_TYPES.has(child.type),
+      groupable: groupFields && FIELD_LIKE_MEMBER_TYPES.has(child.type),
     });
   }
 

gitnexus/src/core/embeddings/config.ts

@@ -0,0 +1,54 @@
+import { defaultEmbeddingThreads } from '../platform/capabilities.js';
+import { DEFAULT_EMBEDDING_CONFIG, type EmbeddingConfig } from './types.js';
+
+const parsePositiveInt = (name: string, value: string | undefined, fallback: number): number => {
+  if (value === undefined) return fallback;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`${name} must be a positive integer, got "${value}"`);
+  }
+  return parsed;
+};
+
+const parseDevice = (value: string | undefined): EmbeddingConfig['device'] | undefined => {
+  if (value === undefined) return undefined;
+  if (
+    value === 'auto' ||
+    value === 'dml' ||
+    value === 'cuda' ||
+    value === 'cpu' ||
+    value === 'wasm'
+  ) {
+    return value;
+  }
+  throw new Error(`embedding device must be one of auto, dml, cuda, cpu, wasm; got "${value}"`);
+};
+
+export const resolveEmbeddingConfig = (
+  overrides: Partial<EmbeddingConfig> = {},
+): EmbeddingConfig => {
+  const env = process.env;
+  return {
+    ...DEFAULT_EMBEDDING_CONFIG,
+    ...overrides,
+    batchSize: parsePositiveInt(
+      'GITNEXUS_EMBEDDING_BATCH_SIZE',
+      env.GITNEXUS_EMBEDDING_BATCH_SIZE,
+      overrides.batchSize ?? DEFAULT_EMBEDDING_CONFIG.batchSize,
+    ),
+    subBatchSize: parsePositiveInt(
+      'GITNEXUS_EMBEDDING_SUB_BATCH_SIZE',
+      env.GITNEXUS_EMBEDDING_SUB_BATCH_SIZE,
+      overrides.subBatchSize ?? DEFAULT_EMBEDDING_CONFIG.subBatchSize,
+    ),
+    threads: parsePositiveInt(
+      'GITNEXUS_EMBEDDING_THREADS',
+      env.GITNEXUS_EMBEDDING_THREADS,
+      overrides.threads ?? defaultEmbeddingThreads(),
+    ),
+    device:
+      parseDevice(env.GITNEXUS_EMBEDDING_DEVICE) ??
+      overrides.device ??
+      DEFAULT_EMBEDDING_CONFIG.device,
+  };
+};

gitnexus/src/core/embeddings/embedder.ts

@@ -21,6 +21,8 @@ import { join, dirname } from 'path';
 import { createRequire } from 'module';
 import { DEFAULT_EMBEDDING_CONFIG, type EmbeddingConfig, type ModelProgress } from './types.js';
 import { isHttpMode, getHttpDimensions, httpEmbed } from './http-client.js';
+import { resolveEmbeddingConfig } from './config.js';
+import { applyHfEnvOverrides } from './hf-env.js';
 
 /**
  * Check whether the onnxruntime-node package that @huggingface/transformers
@@ -143,13 +145,12 @@ export const initEmbedder = async (
 
   isInitializing = true;
 
-  const finalConfig = { ...DEFAULT_EMBEDDING_CONFIG, ...config };
-  // On Windows, use DirectML for GPU acceleration (via DirectX12)
-  // CUDA is only available on Linux x64 with onnxruntime-node
+  const finalConfig = resolveEmbeddingConfig(config);
+  // CUDA is probe-gated because ONNX Runtime can crash in native code when
+  // provider libraries are missing. DirectML stays opt-in for the same reason.
   // Probe for CUDA first — ONNX Runtime crashes (uncatchable native error)
   // if we attempt CUDA without the required shared libraries
-  const isWindows = process.platform === 'win32';
-  const gpuDevice = isWindows ? 'dml' : isCudaAvailable() ? 'cuda' : 'cpu';
+  const gpuDevice = isCudaAvailable() ? 'cuda' : 'cpu';
   const requestedDevice =
     forceDevice || (finalConfig.device === 'auto' ? gpuDevice : finalConfig.device);
 
@@ -157,11 +158,11 @@ export const initEmbedder = async (
     try {
       // Configure transformers.js environment
       env.allowLocalModels = false;
-      // Default cache to user-writable location. transformers.js defaults to
-      // ./node_modules/.cache inside its own install dir, which is unwritable
-      // when gitnexus is installed globally (e.g. /usr/lib/node_modules/).
-      // Respect HF_HOME if set, otherwise fall back to ~/.cache/huggingface.
-      env.cacheDir = process.env.HF_HOME ?? `${process.env.HOME}/.cache/huggingface`;
+      // Bridge user-controlled env vars to transformers.js: HF_HOME →
+      // env.cacheDir, HF_ENDPOINT → env.remoteHost (#1205). Centralised in
+      // applyHfEnvOverrides so the MCP embedder entry point behaves
+      // identically.
+      applyHfEnvOverrides(env);
 
       const isDev = process.env.NODE_ENV === 'development';
       if (isDev) {
@@ -204,7 +205,12 @@ export const initEmbedder = async (
             device: device,
             dtype: 'fp32',
             progress_callback: progressCallback,
-            session_options: { logSeverityLevel: 3 },
+            session_options: {
+              logSeverityLevel: 3,
+              intraOpNumThreads: finalConfig.threads,
+              interOpNumThreads: 1,
+              executionMode: 'sequential',
+            },
           });
           currentDevice = device;
 

gitnexus/src/core/embeddings/embedding-pipeline.ts

@@ -27,13 +27,15 @@ import {
   type SemanticSearchResult,
   type ModelProgress,
   type EmbeddingContext,
-  DEFAULT_EMBEDDING_CONFIG,
   EMBEDDABLE_LABELS,
   isShortLabel,
+  LABEL_METHOD,
   LABELS_WITH_EXPORTED,
   STRUCTURAL_LABELS,
   collectBestChunks,
 } from './types.js';
+import { resolveEmbeddingConfig } from './config.js';
+import { rankExactEmbeddingRows, type ExactEmbeddingRow } from './exact-search.js';
 import {
   EMBEDDING_TABLE_NAME,
   EMBEDDING_INDEX_NAME,
@@ -41,9 +43,27 @@ import {
   STALE_HASH_SENTINEL,
 } from '../lbug/schema.js';
 import { loadVectorExtension } from '../lbug/lbug-adapter.js';
+import { getExactScanLimit } from '../platform/capabilities.js';
 
 const isDev = process.env.NODE_ENV === 'development';
 
+const vectorUnavailableMessage =
+  'VECTOR extension is unavailable for this LadybugDB runtime; semantic search will use exact scan when embeddings exist.';
+
+const ensureVectorExtensionAvailable = async (): Promise<boolean> => {
+  const vectorReady = await loadVectorExtension();
+  if (!vectorReady) {
+    return false;
+  }
+  return true;
+};
+/**
+ * Bump this when the embedding text template changes in a way that should
+ * invalidate existing vectors, such as metadata/header shape changes,
+ * structural container context changes, or preceding-context formatting rules.
+ */
+export const EMBEDDING_TEXT_VERSION = 'v2';
+
 /**
  * Compute a stable content fingerprint for an embeddable node.
  * Used to detect when the underlying text has changed so stale vectors
@@ -57,12 +77,13 @@ export const contentHashForNode = (
   // Hash must be deterministic across runs, so exclude methodNames/fieldNames
   // which are populated during the batch loop via AST extraction.
   // Using only node.content ensures the hash stays stable.
+  // NOTE: A change to extractStructuralNames behavior requires bumping EMBEDDING_TEXT_VERSION.
   const text = generateEmbeddingText(
     { ...node, methodNames: undefined, fieldNames: undefined },
     node.content,
     config,
   );
-  return createHash('sha1').update(text).digest('hex');
+  return createHash('sha1').update(EMBEDDING_TEXT_VERSION).update('\n').update(text).digest('hex');
 };
 
 /**
@@ -83,7 +104,7 @@ const queryEmbeddableNodes = async (
     try {
       let query: string;
 
-      if (label === 'Method') {
+      if (label === LABEL_METHOD) {
         // Method has parameterCount and returnType
         query = `
           MATCH (n:Method)
@@ -115,7 +136,7 @@ const queryEmbeddableNodes = async (
 
       const rows = await executeQuery(query);
       for (const row of rows) {
-        const hasExportedColumn = label === 'Method' || LABELS_WITH_EXPORTED.has(label);
+        const hasExportedColumn = label === LABEL_METHOD || LABELS_WITH_EXPORTED.has(label);
         allNodes.push({
           id: row.id ?? row[0],
           name: row.name ?? row[1],
@@ -126,7 +147,7 @@ const queryEmbeddableNodes = async (
           endLine: row.endLine ?? row[6],
           isExported: hasExportedColumn ? (row.isExported ?? row[7]) : undefined,
           description: row.description ?? (hasExportedColumn ? row[8] : row[7]),
-          ...(label === 'Method'
+          ...(label === LABEL_METHOD
             ? {
                 parameterCount: row.parameterCount ?? row[9],
                 returnType: row.returnType ?? row[10],
@@ -184,19 +205,26 @@ export const batchInsertEmbeddings = async (
  */
 const createVectorIndex = async (
   executeQuery: (cypher: string) => Promise<any[]>,
-): Promise<void> => {
-  // Delegate to the adapter which tracks loaded state and handles DB reconnect resets
-  await loadVectorExtension();
-
+): Promise<boolean> => {
+  if (!(await ensureVectorExtensionAvailable())) return false;
   try {
     await executeQuery(CREATE_VECTOR_INDEX_QUERY);
+    return true;
   } catch (error) {
     if (isDev) {
       console.warn('Vector index creation warning:', error);
     }
+    return false;
   }
 };
 
+export interface EmbeddingPipelineResult {
+  nodesProcessed: number;
+  chunksProcessed: number;
+  vectorIndexReady: boolean;
+  semanticMode: 'vector-index' | 'exact-scan';
+}
+
 /**
  * Run the embedding pipeline
  *
@@ -222,10 +250,14 @@ export const runEmbeddingPipeline = async (
   skipNodeIds?: Set<string>,
   context?: EmbeddingContext,
   existingEmbeddings?: Map<string, string>,
-): Promise<void> => {
-  const finalConfig = { ...DEFAULT_EMBEDDING_CONFIG, ...config };
+): Promise<EmbeddingPipelineResult> => {
+  const finalConfig = resolveEmbeddingConfig(config);
+  let totalChunks = 0;
 
   try {
+    const vectorAvailable = await ensureVectorExtensionAvailable();
+    if (!vectorAvailable && isDev) console.warn(vectorUnavailableMessage);
+
     // Phase 1: Load embedding model
     onProgress({
       phase: 'loading-model',
@@ -330,7 +362,7 @@ export const runEmbeddingPipeline = async (
       // Ensure the vector index exists even when no new nodes need embedding.
       // A prior crash or first-time incremental run may have left CodeEmbedding
       // rows without ever reaching index creation.
-      await createVectorIndex(executeQuery);
+      const vectorIndexReady = await createVectorIndex(executeQuery);
 
       onProgress({
         phase: 'ready',
@@ -338,7 +370,12 @@ export const runEmbeddingPipeline = async (
         nodesProcessed: 0,
         totalNodes: 0,
       });
-      return;
+      return {
+        nodesProcessed: 0,
+        chunksProcessed: 0,
+        vectorIndexReady,
+        semanticMode: vectorIndexReady ? 'vector-index' : 'exact-scan',
+      };
     }
 
     // Phase 3: Chunk + embed nodes
@@ -346,7 +383,6 @@ export const runEmbeddingPipeline = async (
     const chunkSize = finalConfig.chunkSize;
     const overlap = finalConfig.overlap;
     let processedNodes = 0;
-    let totalChunks = 0;
 
     onProgress({
       phase: 'embedding',
@@ -415,8 +451,15 @@ export const runEmbeddingPipeline = async (
           }
         }
 
+        let prevTail = '';
         for (const chunk of chunks) {
-          const text = generateEmbeddingText(node, chunk.text, finalConfig);
+          const text = generateEmbeddingText(
+            node,
+            chunk.text,
+            finalConfig,
+            chunk.chunkIndex,
+            prevTail,
+          );
           allTexts.push(text);
           allUpdates.push({
             nodeId: node.id,
@@ -425,11 +468,12 @@ export const runEmbeddingPipeline = async (
             endLine: chunk.endLine,
             contentHash: hash,
           });
+          prevTail = overlap > 0 ? chunk.text.slice(-overlap) : '';
         }
       }
 
       // Embed chunk texts in sub-batches to control memory
-      const EMBED_SUB_BATCH = 8;
+      const EMBED_SUB_BATCH = finalConfig.subBatchSize;
       for (let si = 0; si < allTexts.length; si += EMBED_SUB_BATCH) {
         const subTexts = allTexts.slice(si, si + EMBED_SUB_BATCH);
         const subUpdates = allUpdates.slice(si, si + EMBED_SUB_BATCH);
@@ -479,7 +523,7 @@ export const runEmbeddingPipeline = async (
       console.log('📇 Creating vector index...');
     }
 
-    await createVectorIndex(executeQuery);
+    const vectorIndexReady = await createVectorIndex(executeQuery);
 
     onProgress({
       phase: 'ready',
@@ -493,6 +537,12 @@ export const runEmbeddingPipeline = async (
         `✅ Embedding pipeline complete! (${totalChunks} chunks from ${totalNodes} nodes)`,
       );
     }
+    return {
+      nodesProcessed: totalNodes,
+      chunksProcessed: totalChunks,
+      vectorIndexReady,
+      semanticMode: vectorIndexReady ? 'vector-index' : 'exact-scan',
+    };
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : 'Unknown error';
 
@@ -527,27 +577,71 @@ export const semanticSearch = async (
   const queryVec = embeddingToArray(queryEmbedding);
   const queryVecStr = `[${queryVec.join(',')}]`;
 
-  const bestChunks = await collectBestChunks(k, async (fetchLimit) => {
-    const vectorQuery = `
-      CALL QUERY_VECTOR_INDEX('${EMBEDDING_TABLE_NAME}', '${EMBEDDING_INDEX_NAME}',
-        CAST(${queryVecStr} AS FLOAT[${queryVec.length}]), ${fetchLimit})
-      YIELD node AS emb, distance
-      WITH emb, distance
-      WHERE distance < ${maxDistance}
-      RETURN emb.nodeId AS nodeId, emb.chunkIndex AS chunkIndex,
-             emb.startLine AS startLine, emb.endLine AS endLine, distance
-      ORDER BY distance
-    `;
+  let bestChunks = new Map<
+    string,
+    { distance: number; chunkIndex: number; startLine: number; endLine: number }
+  >();
+  if (await loadVectorExtension()) {
+    try {
+      bestChunks = await collectBestChunks(k, async (fetchLimit) => {
+        const vectorQuery = `
+          CALL QUERY_VECTOR_INDEX('${EMBEDDING_TABLE_NAME}', '${EMBEDDING_INDEX_NAME}',
+            CAST(${queryVecStr} AS FLOAT[${queryVec.length}]), ${fetchLimit})
+          YIELD node AS emb, distance
+          WITH emb, distance
+          WHERE distance < ${maxDistance}
+          RETURN emb.nodeId AS nodeId, emb.chunkIndex AS chunkIndex,
+                 emb.startLine AS startLine, emb.endLine AS endLine, distance
+          ORDER BY distance
+        `;
 
-    const embResults = await executeQuery(vectorQuery);
-    return embResults.map((row) => ({
-      nodeId: row.nodeId ?? row[0],
-      chunkIndex: row.chunkIndex ?? row[1] ?? 0,
-      startLine: row.startLine ?? row[2] ?? 0,
-      endLine: row.endLine ?? row[3] ?? 0,
-      distance: row.distance ?? row[4],
-    }));
-  });
+        const embResults = await executeQuery(vectorQuery);
+        return embResults.map((row) => ({
+          nodeId: row.nodeId ?? row[0],
+          chunkIndex: row.chunkIndex ?? row[1] ?? 0,
+          startLine: row.startLine ?? row[2] ?? 0,
+          endLine: row.endLine ?? row[3] ?? 0,
+          distance: row.distance ?? row[4],
+        }));
+      });
+    } catch {
+      bestChunks = new Map();
+    }
+  }
+
+  if (bestChunks.size === 0) {
+    const countRows = await executeQuery(
+      `MATCH (e:${EMBEDDING_TABLE_NAME}) RETURN count(e) AS cnt`,
+    );
+    const countRow = countRows[0];
+    const embeddingCount = Number(countRow?.cnt ?? countRow?.[0] ?? 0);
+    const exactLimit = getExactScanLimit();
+    if (embeddingCount > 0 && embeddingCount <= exactLimit) {
+      const rows = await executeQuery(`
+        MATCH (e:${EMBEDDING_TABLE_NAME})
+        RETURN e.nodeId AS nodeId, e.chunkIndex AS chunkIndex,
+               e.startLine AS startLine, e.endLine AS endLine, e.embedding AS embedding
+      `);
+      const exactRows: ExactEmbeddingRow[] = rows.map((row) => ({
+        nodeId: row.nodeId ?? row[0],
+        chunkIndex: row.chunkIndex ?? row[1] ?? 0,
+        startLine: row.startLine ?? row[2] ?? 0,
+        endLine: row.endLine ?? row[3] ?? 0,
+        embedding: row.embedding ?? row[4] ?? [],
+      }));
+      bestChunks = new Map(
+        rankExactEmbeddingRows(exactRows, queryVec, k, maxDistance).map((row) => [
+          row.nodeId,
+          {
+            distance: row.distance,
+            chunkIndex: row.chunkIndex,
+            startLine: row.startLine,
+            endLine: row.endLine,
+          },
+        ]),
+      );
+    }
+  }
 
   if (bestChunks.size === 0) {
     return [];

gitnexus/src/core/embeddings/exact-search.ts

@@ -0,0 +1,49 @@
+export interface ExactEmbeddingRow {
+  nodeId: string;
+  chunkIndex: number;
+  startLine: number;
+  endLine: number;
+  embedding: readonly number[];
+}
+
+export interface ExactSearchChunk {
+  nodeId: string;
+  chunkIndex: number;
+  startLine: number;
+  endLine: number;
+  distance: number;
+}
+
+const cosineDistance = (a: readonly number[], b: readonly number[]): number => {
+  let dot = 0;
+  let aNorm = 0;
+  let bNorm = 0;
+  const len = Math.min(a.length, b.length);
+  for (let i = 0; i < len; i++) {
+    const av = a[i] ?? 0;
+    const bv = b[i] ?? 0;
+    dot += av * bv;
+    aNorm += av * av;
+    bNorm += bv * bv;
+  }
+  if (aNorm === 0 || bNorm === 0) return 1;
+  return 1 - dot / (Math.sqrt(aNorm) * Math.sqrt(bNorm));
+};
+
+export const rankExactEmbeddingRows = (
+  rows: readonly ExactEmbeddingRow[],
+  queryEmbedding: readonly number[],
+  limit: number,
+  maxDistance: number,
+): ExactSearchChunk[] =>
+  rows
+    .map((row) => ({
+      nodeId: row.nodeId,
+      chunkIndex: row.chunkIndex,
+      startLine: row.startLine,
+      endLine: row.endLine,
+      distance: cosineDistance(row.embedding, queryEmbedding),
+    }))
+    .filter((row) => row.distance < maxDistance)
+    .sort((a, b) => a.distance - b.distance)
+    .slice(0, limit);

gitnexus/src/core/embeddings/hf-env.ts

@@ -0,0 +1,62 @@
+import os from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * @internal Exported only for unit tests and the two embedder entry points
+ * (`core/embeddings/embedder.ts` + `mcp/core/embedder.ts`). Not part of the
+ * public package API.
+ *
+ * Minimal subset of `@huggingface/transformers`' `env` object that gitnexus
+ * mutates. Defining a local structural type keeps this helper free of a
+ * transitive dependency on transformers' generated `.d.ts` while still
+ * giving full type-checking on the two fields we actually touch.
+ */
+export interface HfEnvSubset {
+  cacheDir: string;
+  remoteHost: string;
+}
+
+/**
+ * @internal Exported only for unit tests and the two embedder entry points
+ * (`core/embeddings/embedder.ts` + `mcp/core/embedder.ts`). Not part of the
+ * public package API.
+ *
+ * Apply user-controlled HuggingFace environment overrides to the
+ * `@huggingface/transformers` `env` object. Centralises the two env-var
+ * bridges so every gitnexus embedder entry point (the analyze pipeline
+ * and the MCP server) behaves identically.
+ *
+ * - **`HF_HOME`** → `env.cacheDir` (default: `~/.cache/huggingface`).
+ *   transformers.js otherwise defaults to `./node_modules/.cache` inside
+ *   its own install dir, which is unwritable when gitnexus is installed
+ *   globally (e.g. `/usr/lib/node_modules/`).
+ *
+ * - **`HF_ENDPOINT`** → `env.remoteHost` (#1205). transformers.js does
+ *   not read `HF_ENDPOINT` on its own — it reads `env.remoteHost` —
+ *   even though `HF_ENDPOINT` is the standard env var the upstream
+ *   `huggingface_hub` Python client and the official HF mirror docs
+ *   tell users to set. Bridging the two unblocks `--embeddings` for
+ *   users behind networks where `huggingface.co` is unreachable
+ *   (corporate proxies, the GFW, air-gapped mirrors). The trailing
+ *   slash is normalised because transformers.js builds URLs by string
+ *   concatenation and a missing slash silently falls through to its
+ *   default `huggingface.co/...` host.
+ *
+ * Mutation rather than return-and-apply because callers already hold a
+ * reference to the live `env` object imported from
+ * `@huggingface/transformers` — passing the same reference in keeps the
+ * call site a single line at each entry point.
+ */
+export function applyHfEnvOverrides(env: HfEnvSubset): void {
+  env.cacheDir = process.env.HF_HOME ?? join(os.homedir(), '.cache', 'huggingface');
+  // `.trim()` guards against the common copy-paste failure mode of
+  // `HF_ENDPOINT="  https://hf-mirror.com  "` (leading/trailing whitespace
+  // from shell scripts or docs) — without it, a whitespace-only value
+  // would be truthy and produce an invalid `env.remoteHost = '   /'` that
+  // silently misroutes downloads. Empty string remains falsy in JS so the
+  // truthy guard already handles the unset/empty cases.
+  const endpoint = process.env.HF_ENDPOINT?.trim();
+  if (endpoint) {
+    env.remoteHost = endpoint.endsWith('/') ? endpoint : endpoint + '/';
+  }
+}

gitnexus/src/core/embeddings/text-generator.ts

@@ -10,7 +10,12 @@
  */
 
 import type { EmbeddableNode, EmbeddingConfig } from './types.js';
-import { DEFAULT_EMBEDDING_CONFIG, isShortLabel } from './types.js';
+import {
+  CHUNKING_RULES,
+  DEFAULT_EMBEDDING_CONFIG,
+  STRUCTURAL_TEXT_MODE_DECLARATION,
+  isShortLabel,
+} from './types.js';
 
 /**
  * Truncate description to max length at sentence/word boundary
@@ -95,47 +100,62 @@ const generateCodeBodyText = (
   node: EmbeddableNode,
   codeBody: string,
   config: Partial<EmbeddingConfig>,
+  prevTail?: string,
 ): string => {
   const header = buildMetadataHeader(node, config);
-  const cleaned = cleanContent(codeBody);
-  return `${header}\n\n${cleaned}`;
+  const parts = [header];
+  if (prevTail) {
+    parts.push(`[preceding context]: ...${cleanContent(prevTail)}`);
+  }
+  parts.push('', cleanContent(codeBody));
+  return parts.join('\n');
 };
 
-/**
- * Generate embedding text for Class nodes
- * Signature + properties + method name list only (no method bodies)
- * Method/field names come from AST extractors via node.methodNames/node.fieldNames.
- */
-const generateClassText = (
-  node: EmbeddableNode,
-  codeBody: string,
-  config: Partial<EmbeddingConfig>,
-): string => {
-  return generateStructuralTypeText(node, codeBody, config);
+const getCompactContainerContext = (
+  cleanedContent: string,
+  declarationOnly: string,
+): string | undefined => {
+  const source = declarationOnly || cleanedContent;
+  const nlIdx = source.indexOf('\n');
+  const firstLine = (nlIdx === -1 ? source : source.substring(0, nlIdx)).trim();
+  return firstLine ? `Container: ${firstLine}` : undefined;
 };
 
 const generateStructuralTypeText = (
   node: EmbeddableNode,
   codeBody: string,
   config: Partial<EmbeddingConfig>,
+  chunkIndex?: number,
+  prevTail?: string,
 ): string => {
   const header = buildMetadataHeader(node, config);
   const parts: string[] = [header];
+  const isFirstChunk = chunkIndex === undefined || chunkIndex === 0;
+  const cleanedContent = cleanContent(node.content);
+  const declarationOnly = extractDeclarationOnly(cleanedContent);
+  const compactContainerContext = getCompactContainerContext(cleanedContent, declarationOnly);
 
-  if (node.methodNames?.length) {
+  if (compactContainerContext) {
+    parts.push(compactContainerContext);
+  }
+
+  if (prevTail) {
+    parts.push(`[preceding context]: ...${cleanContent(prevTail)}`);
+  }
+
+  if (isFirstChunk && node.methodNames?.length) {
     parts.push(`Methods: ${node.methodNames.join(', ')}`);
   }
-  if (node.fieldNames?.length) {
+  if (isFirstChunk && node.fieldNames?.length) {
     parts.push(`Properties: ${node.fieldNames.join(', ')}`);
   }
 
-  const declarationOnly = extractDeclarationOnly(cleanContent(node.content));
-  if (declarationOnly) {
+  if (isFirstChunk && declarationOnly) {
     parts.push('', declarationOnly);
   }
 
   const cleanedChunk = cleanContent(codeBody);
-  if (cleanedChunk && cleanedChunk !== cleanContent(node.content)) {
+  if (cleanedChunk && cleanedChunk !== cleanedContent) {
     parts.push('', cleanedChunk);
   }
 
@@ -229,6 +249,8 @@ export const generateEmbeddingText = (
   node: EmbeddableNode,
   codeBody: string,
   config: Partial<EmbeddingConfig> = {},
+  chunkIndex?: number,
+  prevTail?: string,
 ): string => {
   if (isShortLabel(node.label)) {
     const header = buildMetadataHeader(node, config);
@@ -236,15 +258,12 @@ export const generateEmbeddingText = (
     return `${header}\n\n${cleaned}`;
   }
 
-  if (node.label === 'Class') {
-    return generateClassText(node, codeBody, config);
+  const chunkingRule = CHUNKING_RULES[node.label];
+  if (chunkingRule?.structuralTextMode === STRUCTURAL_TEXT_MODE_DECLARATION) {
+    return generateStructuralTypeText(node, codeBody, config, chunkIndex, prevTail);
   }
 
-  if (node.label === 'Interface') {
-    return generateStructuralTypeText(node, codeBody, config);
-  }
-
-  return generateCodeBodyText(node, codeBody, config);
+  return generateCodeBodyText(node, codeBody, config, prevTail);
 };
 
 /**

gitnexus/src/core/embeddings/types.ts

@@ -4,35 +4,76 @@
  * Type definitions for the embedding generation and semantic search system.
  */
 
+export const LABEL_FUNCTION = 'Function' as const;
+export const LABEL_METHOD = 'Method' as const;
+export const LABEL_CONSTRUCTOR = 'Constructor' as const;
+export const LABEL_CLASS = 'Class' as const;
+export const LABEL_INTERFACE = 'Interface' as const;
+export const LABEL_STRUCT = 'Struct' as const;
+export const LABEL_ENUM = 'Enum' as const;
+export const LABEL_TRAIT = 'Trait' as const;
+export const LABEL_IMPL = 'Impl' as const;
+export const LABEL_MACRO = 'Macro' as const;
+export const LABEL_NAMESPACE = 'Namespace' as const;
+export const LABEL_TYPE_ALIAS = 'TypeAlias' as const;
+export const LABEL_TYPEDEF = 'Typedef' as const;
+export const LABEL_CONST = 'Const' as const;
+export const LABEL_PROPERTY = 'Property' as const;
+export const LABEL_RECORD = 'Record' as const;
+export const LABEL_UNION = 'Union' as const;
+export const LABEL_STATIC = 'Static' as const;
+export const LABEL_VARIABLE = 'Variable' as const;
+export const LABEL_CODE_ELEMENT = 'CodeElement' as const;
+
+export const CHUNK_MODE_AST_FUNCTION = 'ast-function' as const;
+export const CHUNK_MODE_AST_DECLARATION = 'ast-declaration' as const;
+// CHUNK_MODE_CHARACTER exists for type completeness but is a no-op in CHUNKING_RULES —
+// omit the entry entirely to get character fallback via chunker.ts dispatch.
+export const CHUNK_MODE_CHARACTER = 'character' as const;
+
+export const STRUCTURAL_TEXT_MODE_NONE = 'none' as const;
+export const STRUCTURAL_TEXT_MODE_DECLARATION = 'declaration' as const;
+
+export interface ChunkingRule {
+  mode:
+    | typeof CHUNK_MODE_AST_FUNCTION
+    | typeof CHUNK_MODE_AST_DECLARATION
+    | typeof CHUNK_MODE_CHARACTER;
+  includePrefix: boolean;
+  includeSuffix: boolean;
+  groupFields: boolean;
+  structuralTextMode: typeof STRUCTURAL_TEXT_MODE_NONE | typeof STRUCTURAL_TEXT_MODE_DECLARATION;
+}
+
 /**
  * Node labels that need chunking (have code body, potentially long)
  */
 export const CHUNKABLE_LABELS = [
-  'Function',
-  'Method',
-  'Constructor',
-  'Class',
-  'Interface',
-  'Struct',
-  'Enum',
-  'Trait',
-  'Impl',
-  'Macro',
-  'Namespace',
+  LABEL_FUNCTION,
+  LABEL_METHOD,
+  LABEL_CONSTRUCTOR,
+  LABEL_CLASS,
+  LABEL_INTERFACE,
+  LABEL_STRUCT,
+  LABEL_ENUM,
+  LABEL_TRAIT,
+  LABEL_IMPL,
+  LABEL_MACRO,
+  LABEL_NAMESPACE,
 ] as const;
 
 /**
  * Node labels that are short (no chunking needed, embed directly)
  */
 export const SHORT_LABELS = [
-  'TypeAlias',
-  'Typedef',
-  'Const',
-  'Property',
-  'Record',
-  'Union',
-  'Static',
-  'Variable',
+  LABEL_TYPE_ALIAS,
+  LABEL_TYPEDEF,
+  LABEL_CONST,
+  LABEL_PROPERTY,
+  LABEL_RECORD,
+  LABEL_UNION,
+  LABEL_STATIC,
+  LABEL_VARIABLE,
 ] as const;
 
 /**
@@ -61,26 +102,78 @@ export const isShortLabel = (label: string): boolean =>
   (SHORT_LABELS as readonly string[]).includes(label);
 
 /**
- * Node labels that have structural names (methods/fields) extractable via AST
+ * Node labels that have structural names (methods/fields) extractable via AST.
+ * Only labels that consume methodNames/fieldNames in their embedding text should
+ * be listed here — extra entries trigger wasted AST parses with no effect on output.
  */
 export const STRUCTURAL_LABELS: ReadonlySet<string> = new Set([
-  'Class',
-  'Struct',
-  'Interface',
-  'Enum',
+  LABEL_CLASS,
+  LABEL_STRUCT,
+  LABEL_INTERFACE,
 ]);
 
 /**
  * Node labels that have isExported column in their schema
  */
 export const LABELS_WITH_EXPORTED = new Set([
-  'Function',
-  'Class',
-  'Interface',
-  'Method',
-  'CodeElement',
+  LABEL_FUNCTION,
+  LABEL_CLASS,
+  LABEL_INTERFACE,
+  LABEL_METHOD,
+  LABEL_CODE_ELEMENT,
 ]) as ReadonlySet<string>;
 
+/**
+ * Labels that need special chunking and/or structural text semantics.
+ * Any chunkable label omitted here intentionally falls back to characterChunk
+ * plus generateCodeBodyText (for example Enum/Trait/Impl/Macro/Namespace).
+ */
+type ChunkableLabel = (typeof CHUNKABLE_LABELS)[number];
+export const CHUNKING_RULES: Readonly<Partial<Record<ChunkableLabel, ChunkingRule>>> = {
+  [LABEL_FUNCTION]: {
+    mode: CHUNK_MODE_AST_FUNCTION,
+    includePrefix: true,
+    includeSuffix: true,
+    groupFields: false,
+    structuralTextMode: STRUCTURAL_TEXT_MODE_NONE,
+  },
+  [LABEL_METHOD]: {
+    mode: CHUNK_MODE_AST_FUNCTION,
+    includePrefix: true,
+    includeSuffix: true,
+    groupFields: false,
+    structuralTextMode: STRUCTURAL_TEXT_MODE_NONE,
+  },
+  [LABEL_CONSTRUCTOR]: {
+    mode: CHUNK_MODE_AST_FUNCTION,
+    includePrefix: true,
+    includeSuffix: true,
+    groupFields: false,
+    structuralTextMode: STRUCTURAL_TEXT_MODE_NONE,
+  },
+  [LABEL_CLASS]: {
+    mode: CHUNK_MODE_AST_DECLARATION,
+    includePrefix: true,
+    includeSuffix: false,
+    groupFields: true,
+    structuralTextMode: STRUCTURAL_TEXT_MODE_DECLARATION,
+  },
+  [LABEL_INTERFACE]: {
+    mode: CHUNK_MODE_AST_DECLARATION,
+    includePrefix: true,
+    includeSuffix: false,
+    groupFields: false,
+    structuralTextMode: STRUCTURAL_TEXT_MODE_DECLARATION,
+  },
+  [LABEL_STRUCT]: {
+    mode: CHUNK_MODE_AST_DECLARATION,
+    includePrefix: true,
+    includeSuffix: false,
+    groupFields: true,
+    structuralTextMode: STRUCTURAL_TEXT_MODE_DECLARATION,
+  },
+};
+
 /**
  * Embedding pipeline phases
  */
@@ -114,6 +207,10 @@ export interface EmbeddingConfig {
   modelId: string;
   /** Number of nodes to embed in each batch */
   batchSize: number;
+  /** Number of chunks passed to one local/HTTP embedding call */
+  subBatchSize: number;
+  /** Maximum ONNX Runtime CPU threads for local inference */
+  threads: number;
   /** Embedding vector dimensions */
   dimensions: number;
   /** Device to use for inference: 'auto' tries GPU first (DirectML on Windows, CUDA on Linux), falls back to CPU */
@@ -136,6 +233,8 @@ export interface EmbeddingConfig {
 export const DEFAULT_EMBEDDING_CONFIG: EmbeddingConfig = {
   modelId: 'Snowflake/snowflake-arctic-embed-xs',
   batchSize: 16,
+  subBatchSize: 8,
+  threads: 2,
   dimensions: 384,
   device: 'auto',
   maxSnippetLength: 500,

gitnexus/src/core/git-staleness.ts

@@ -4,6 +4,9 @@
  */
 
 import { execFileSync } from 'node:child_process';
+import path from 'path';
+import { readRegistry, type RegistryEntry, type CwdMatch } from '../storage/repo-manager.js';
+import { findGitRootByDotGit, getCurrentCommit, getRemoteUrl } from '../storage/git.js';
 
 export interface StalenessInfo {
   isStale: boolean;
@@ -37,3 +40,112 @@ export function checkStaleness(repoPath: string, lastCommit: string): StalenessI
     return { isStale: false, commitsBehind: 0 };
   }
 }
+
+/**
+ * Compare a sibling-clone HEAD against an indexed `lastCommit`. Returns
+ * `undefined` when the indexed commit is not reachable from the sibling
+ * (e.g. divergent branches, shallow clone, missing ref). The caller
+ * should treat `undefined` as "drift unknown" rather than "no drift".
+ */
+function commitsAheadOfIndexed(siblingPath: string, indexedCommit: string): number | undefined {
+  if (!indexedCommit) return undefined;
+  try {
+    const result = execFileSync('git', ['rev-list', '--count', `${indexedCommit}..HEAD`], {
+      cwd: siblingPath,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    return parseInt(result, 10) || 0;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Resolve a working directory against the global registry. Returns:
+ *   - `match: 'path'`              when `cwd` is inside a registered entry's path
+ *   - `match: 'sibling-by-remote'` when `cwd` lives in a different on-disk clone
+ *                                   of the same repo (same `remoteUrl`)
+ *   - `match: 'none'`              when neither match applies
+ *
+ * For sibling-by-remote matches, the caller's HEAD and the drift vs the
+ * indexed `lastCommit` are also returned so the MCP layer can warn
+ * before serving silently-stale answers (issue: silent graph drift
+ * across sibling clones).
+ *
+ * `path` matches deliberately use the longest-prefix rule so a cwd
+ * inside a sub-path of a registered repo still matches that repo, not
+ * a coincidentally-aliased shorter entry.
+ */
+export async function checkCwdMatch(cwd: string): Promise<CwdMatch> {
+  const entries = await readRegistry();
+  if (entries.length === 0) return { match: 'none' };
+
+  const isWin = process.platform === 'win32';
+  const norm = (p: string) => (isWin ? path.resolve(p).toLowerCase() : path.resolve(p));
+  const sep = path.sep;
+  const cwdResolved = path.resolve(cwd);
+  const cwdNorm = norm(cwdResolved);
+
+  // 1) Path-based match (longest prefix wins, boundary-safe).
+  let bestPath: RegistryEntry | undefined;
+  let bestLen = -1;
+  for (const e of entries) {
+    const p = norm(e.path);
+    if (cwdNorm === p || cwdNorm.startsWith(p + sep)) {
+      if (p.length > bestLen) {
+        bestPath = e;
+        bestLen = p.length;
+      }
+    }
+  }
+  if (bestPath) return { match: 'path', entry: bestPath };
+
+  // 2) Sibling-by-remote: locate the cwd's git root using only ancestor
+  //    `.git` checks before shelling out. This keeps MCP startup from
+  //    running git in an unrelated launch cwd such as $HOME (#1138).
+  const cwdGitRoot = findGitRootByDotGit(cwdResolved);
+  if (!cwdGitRoot) return { match: 'none' };
+
+  const cwdRemote = getRemoteUrl(cwdGitRoot);
+  if (!cwdRemote) return { match: 'none' };
+
+  const sibling = entries.find(
+    (e) => e.remoteUrl === cwdRemote && norm(e.path) !== norm(cwdGitRoot),
+  );
+  if (!sibling) return { match: 'none' };
+
+  const cwdHead = getCurrentCommit(cwdGitRoot) || undefined;
+  const drift = commitsAheadOfIndexed(cwdGitRoot, sibling.lastCommit);
+
+  // Same commit on both clones → still report match=sibling-by-remote
+  // (the relationship is real and useful to callers like list_repos /
+  // future tooling) but leave `hint` unset: there's nothing to warn
+  // about, and `maybeWarnSiblingDrift` already short-circuits this
+  // case independently. Surfacing a no-op hint would force callers
+  // to second-guess whether they need to display it.
+  let hint: string | undefined;
+  if (cwdHead && cwdHead === sibling.lastCommit) {
+    hint = undefined;
+  } else if (drift && drift > 0) {
+    hint =
+      `⚠️ Index for "${sibling.name}" was built at ${sibling.path}; ` +
+      `your cwd (${cwdGitRoot}) is a sibling clone that is ${drift} commit${drift > 1 ? 's' : ''} ` +
+      `ahead of the indexed commit. Results may be stale or incorrect — re-run \`gitnexus analyze\` ` +
+      `to refresh the index.`;
+  } else {
+    hint =
+      `⚠️ Index for "${sibling.name}" was built at ${sibling.path}; ` +
+      `your cwd (${cwdGitRoot}) is a sibling clone whose HEAD differs from the indexed commit. ` +
+      `Results may be stale or incorrect — re-run \`gitnexus analyze\` to refresh the index.`;
+  }
+
+  return {
+    match: 'sibling-by-remote',
+    entry: sibling,
+    cwdGitRoot,
+    cwdHead,
+    drift,
+    hint,
+  };
+}

gitnexus/src/core/graph/graph.ts

@@ -1,35 +1,117 @@
-import type { GraphNode, GraphRelationship } from 'gitnexus-shared';
+import type { GraphNode, GraphRelationship, RelationshipType } from 'gitnexus-shared';
 import { KnowledgeGraph } from './types.js';
 
+/** Fresh empty iterator per call — `[].values()` returns a new
+ *  exhausted iterator each invocation, so empty-type lookups don't
+ *  share a single already-exhausted iterator across callers. */
+function emptyRelIter(): IterableIterator<GraphRelationship> {
+  return ([] as GraphRelationship[]).values();
+}
+
 export const createKnowledgeGraph = (): KnowledgeGraph => {
   const nodeMap = new Map<string, GraphNode>();
   const relationshipMap = new Map<string, GraphRelationship>();
+  // Per-type index maintained alongside `relationshipMap`. Bucket
+  // values are `Map<id, Relationship>` so per-type iteration is cheap
+  // and per-edge removal is O(1). See plan
+  // docs/plans/2026-04-20-002-perf-parse-heritage-mro-plan.md (Unit 1).
+  const relationshipsByType = new Map<RelationshipType, Map<string, GraphRelationship>>();
+  // Reverse-adjacency index: nodeId → Set<relId> of every edge where
+  // this node appears as source OR target. Maintained on writeRel /
+  // deleteRel so `removeNode` can delete a node's edges in
+  // O(edges-touching-node) instead of O(total-edges).
+  const edgeIdsByNode = new Map<string, Set<string>>();
+  // File index: filePath → Set<nodeId>. Maintained on addNode /
+  // removeNode so `removeNodesByFile` reaches its file's nodes
+  // directly instead of scanning the whole node map.
+  const nodeIdsByFile = new Map<string, Set<string>>();
+
+  // Private helpers that encode the dual-index invariants in one
+  // place. All mutation paths go through these — adding a new
+  // mutation method only needs to call the helper, not remember to
+  // touch every index.
+  const addToBucket = <K, V>(map: Map<K, Set<V>>, key: K, value: V): void => {
+    let bucket = map.get(key);
+    if (bucket === undefined) {
+      bucket = new Set();
+      map.set(key, bucket);
+    }
+    bucket.add(value);
+  };
+  const removeFromBucket = <K, V>(map: Map<K, Set<V>>, key: K, value: V): void => {
+    const bucket = map.get(key);
+    if (bucket === undefined) return;
+    bucket.delete(value);
+    if (bucket.size === 0) map.delete(key);
+  };
+
+  const writeRel = (rel: GraphRelationship): void => {
+    relationshipMap.set(rel.id, rel);
+    let typeBucket = relationshipsByType.get(rel.type);
+    if (typeBucket === undefined) {
+      typeBucket = new Map();
+      relationshipsByType.set(rel.type, typeBucket);
+    }
+    typeBucket.set(rel.id, rel);
+    addToBucket(edgeIdsByNode, rel.sourceId, rel.id);
+    // Guard against a self-edge writing the same rel.id into the
+    // same Set twice — Set dedup handles it, but we skip explicitly
+    // for clarity.
+    if (rel.targetId !== rel.sourceId) {
+      addToBucket(edgeIdsByNode, rel.targetId, rel.id);
+    }
+  };
+  const deleteRel = (rel: GraphRelationship): void => {
+    relationshipMap.delete(rel.id);
+    const typeBucket = relationshipsByType.get(rel.type);
+    if (typeBucket !== undefined) {
+      typeBucket.delete(rel.id);
+      if (typeBucket.size === 0) relationshipsByType.delete(rel.type);
+    }
+    removeFromBucket(edgeIdsByNode, rel.sourceId, rel.id);
+    if (rel.targetId !== rel.sourceId) {
+      removeFromBucket(edgeIdsByNode, rel.targetId, rel.id);
+    }
+  };
 
   const addNode = (node: GraphNode) => {
-    if (!nodeMap.has(node.id)) {
-      nodeMap.set(node.id, node);
+    if (nodeMap.has(node.id)) return;
+    nodeMap.set(node.id, node);
+    const filePath = node.properties?.filePath;
+    if (typeof filePath === 'string' && filePath.length > 0) {
+      addToBucket(nodeIdsByFile, filePath, node.id);
     }
   };
 
   const addRelationship = (relationship: GraphRelationship) => {
-    if (!relationshipMap.has(relationship.id)) {
-      relationshipMap.set(relationship.id, relationship);
-    }
+    if (relationshipMap.has(relationship.id)) return;
+    writeRel(relationship);
   };
 
   /**
-   * Remove a single node and all relationships involving it
+   * Remove a single node and all relationships involving it.
+   * O(edges-touching-node) via the reverse-adjacency index — no full
+   * relationshipMap scan.
    */
   const removeNode = (nodeId: string): boolean => {
-    if (!nodeMap.has(nodeId)) return false;
+    const node = nodeMap.get(nodeId);
+    if (node === undefined) return false;
 
     nodeMap.delete(nodeId);
+    const filePath = node.properties?.filePath;
+    if (typeof filePath === 'string' && filePath.length > 0) {
+      removeFromBucket(nodeIdsByFile, filePath, nodeId);
+    }
 
-    // Remove all relationships involving this node
-    for (const [relId, rel] of relationshipMap) {
-      if (rel.sourceId === nodeId || rel.targetId === nodeId) {
-        relationshipMap.delete(relId);
+    const touchingEdgeIds = edgeIdsByNode.get(nodeId);
+    if (touchingEdgeIds !== undefined) {
+      // Snapshot the ids before iterating — deleteRel mutates the same
+      // Set via removeFromBucket, which would break mid-loop iteration.
+      for (const relId of [...touchingEdgeIds]) {
+        const rel = relationshipMap.get(relId);
+        if (rel !== undefined) deleteRel(rel);
       }
+      edgeIdsByNode.delete(nodeId);
     }
     return true;
   };
@@ -39,21 +121,24 @@ export const createKnowledgeGraph = (): KnowledgeGraph => {
    * Returns true if the relationship existed and was removed, false otherwise.
    */
   const removeRelationship = (relationshipId: string): boolean => {
-    return relationshipMap.delete(relationshipId);
+    const rel = relationshipMap.get(relationshipId);
+    if (rel === undefined) return false;
+    deleteRel(rel);
+    return true;
   };
 
   /**
    * Remove all nodes (and their relationships) belonging to a file.
+   * O(file-nodes × avg-edges-per-node) via the file index — no full
+   * node-map scan.
    */
   const removeNodesByFile = (filePath: string): number => {
-    let removed = 0;
-    for (const [nodeId, node] of nodeMap) {
-      if (node.properties?.filePath === filePath) {
-        removeNode(nodeId);
-        removed++;
-      }
-    }
-    return removed;
+    const nodeIds = nodeIdsByFile.get(filePath);
+    if (nodeIds === undefined) return 0;
+    // Snapshot before iterating — removeNode mutates nodeIdsByFile.
+    const snapshot = [...nodeIds];
+    for (const nodeId of snapshot) removeNode(nodeId);
+    return snapshot.length;
   };
 
   return {
@@ -67,6 +152,10 @@ export const createKnowledgeGraph = (): KnowledgeGraph => {
 
     iterNodes: () => nodeMap.values(),
     iterRelationships: () => relationshipMap.values(),
+    iterRelationshipsByType: (type: RelationshipType) => {
+      const bucket = relationshipsByType.get(type);
+      return bucket === undefined ? emptyRelIter() : bucket.values();
+    },
     forEachNode(fn: (node: GraphNode) => void) {
       nodeMap.forEach(fn);
     },