chore(release): v1.6.2 (#952)

Bumps gitnexus to v1.6.2 and adds the matching CHANGELOG entry.

Highlights since v1.6.1 (61 commits):
  - Docker support (#848)
  - Language-agnostic heritage / call / variable extractors
    (config+factory pattern, #877 #878 #890)
  - AST-aware embedding chunking (#889)
  - jQuery / axios HTTP consumer detection (#887)
  - SemanticModel wired as first-class resolution input, SM-20 (#885)
  - ImportSemantics split into per-strategy hooks (#886)
  - Python dotted-import fix (#899); worker warnings non-terminal
    (#900 / #261); global-install ENOTEMPTY fixes (#843 #846);
    embeddings staleness fix (#831)

See gitnexus/CHANGELOG.md for the full list.

After merge, tag `v1.6.2` triggers publish.yml which runs CI,
verifies tag↔package.json match, publishes to npm with provenance,
and creates the GitHub Release using the extracted CHANGELOG body.

.cursor/.gitignore

@@ -0,0 +1 @@
+plans/

.dockerignore

@@ -0,0 +1,19 @@
+.git
+.gitignore
+.DS_Store
+
+node_modules
+**/node_modules
+
+dist
+**/dist
+coverage
+**/coverage
+
+.env
+.env.local
+.env.*.local
+
+.gitnexus
+gitnexus-web/playwright-report
+gitnexus-web/test-results

.env.example

@@ -0,0 +1,3 @@
+IMAGE_NAME=ghcr.io/abhigyanpatwari/gitnexus:latest
+CONTAINER_NAME=gitnexus
+HOST_PORT=4173

.git-blame-ignore-revs

@@ -0,0 +1,5 @@
+# Prettier initial formatting (2026-03-28)
+afcc3d1523f99c77ff67c4fd1af12334660113f6
+
+# ESLint unused import removal (2026-03-28)
+1491826bc8da5436d3b1eb092d9274f2c9f028a7

.gitattributes

@@ -0,0 +1,2 @@
+* text=auto eol=lf
+.husky/* text eol=lf

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

@@ -0,0 +1,21 @@
+name: Setup GitNexus Web
+description: Setup Node.js 20, build gitnexus-shared, install web dependencies
+
+runs:
+  using: composite
+  steps:
+    - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+      with:
+        node-version: 20
+        cache: npm
+        cache-dependency-path: gitnexus-web/package-lock.json
+
+    - name: Build gitnexus-shared
+      run: npm install && npm run build
+      shell: bash
+      working-directory: gitnexus-shared
+
+    - name: Install web dependencies
+      run: npm ci
+      shell: bash
+      working-directory: gitnexus-web

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

@@ -16,6 +16,11 @@ runs:
         cache: npm
         cache-dependency-path: gitnexus/package-lock.json
 
+    - name: Build gitnexus-shared
+      run: npm install && npm run build
+      shell: bash
+      working-directory: gitnexus-shared
+
     - name: Install dependencies
       run: npm ci
       shell: bash

.github/dependabot.yml

@@ -0,0 +1,75 @@
+version: 2
+updates:
+  # Keep third-party Actions SHA pins current. See CONTRIBUTING.md — when
+  # reviewing these bumps, verify the SHA corresponds to the claimed tag by
+  # running `gh api repos/<owner>/<action>/git/refs/tags/<tag>` before merge.
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: chore
+      include: scope
+    labels:
+      - dependencies
+      - ci
+
+  # Gitnexus npm deps — tree-sitter grammars checked daily so we catch
+  # new releases that unblock the tree-sitter 0.25 upgrade ASAP. Grammars
+  # are grouped so lockstep bumps produce a single PR. The tree-sitter
+  # RUNTIME is pinned — upgrade deliberately via the drift check workflow.
+  # See .github/scripts/check-tree-sitter-upgrade-readiness.py for
+  # the upgrade readiness tracker.
+  - package-ecosystem: npm
+    directory: /gitnexus
+    schedule:
+      interval: daily
+    open-pull-requests-limit: 10
+    commit-message:
+      prefix: chore(deps)
+      include: scope
+    labels:
+      - dependencies
+    groups:
+      tree-sitter-grammars:
+        patterns:
+          - tree-sitter-*
+        exclude-patterns:
+          - tree-sitter
+          - tree-sitter-cli
+    ignore:
+      # Pin the tree-sitter runtime at 0.21.x until the drift check
+      # reports all grammars are peer-dep compatible with 0.25.
+      - dependency-name: tree-sitter
+        update-types:
+          - version-update:semver-major
+          - version-update:semver-minor
+      # tree-sitter-cli follows the runtime's version cadence. Bump when
+      # regenerating vendor/tree-sitter-proto/src/parser.c, not on a schedule.
+      - dependency-name: tree-sitter-cli
+
+  # gitnexus-web (thin frontend client).
+  - package-ecosystem: npm
+    directory: /gitnexus-web
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: chore(deps)
+      include: scope
+    labels:
+      - dependencies
+      - frontend
+
+  # Shared types package.
+  - package-ecosystem: npm
+    directory: /gitnexus-shared
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: chore(deps)
+      include: scope
+    labels:
+      - dependencies

.github/release-drafter.yml

@@ -0,0 +1,53 @@
+# release-drafter config — used only for PR autolabeling by
+# `.github/workflows/pr-labeler.yml` (the workflow passes `disable-releaser: true`,
+# so the draft-release side of release-drafter never runs).
+#
+# The labels applied here are the same ones `.github/release.yml` maps to
+# categorized release-notes sections.
+#
+# `sync-labels: true` removes managed autolabels that no longer match the PR —
+# critical for the breaking-change case: if a PR title drops the `!` or the body
+# drops `BREAKING CHANGE:`, the `breaking` label is pulled off automatically.
+
+# Required by release-drafter; not used because releaser is disabled.
+name-template: 'unused'
+tag-template: 'unused'
+template: |
+  $CHANGES
+
+sync-labels: true
+
+autolabeler:
+  - label: enhancement
+    title:
+      - '/^feat(\([^)]+\))?!?:/i'
+  - label: bug
+    title:
+      - '/^fix(\([^)]+\))?!?:/i'
+  - label: performance
+    title:
+      - '/^perf(\([^)]+\))?!?:/i'
+  - label: refactor
+    title:
+      - '/^refactor(\([^)]+\))?!?:/i'
+  - label: documentation
+    title:
+      - '/^docs(\([^)]+\))?!?:/i'
+  - label: test
+    title:
+      - '/^test(\([^)]+\))?!?:/i'
+  - label: ci
+    title:
+      - '/^ci(\([^)]+\))?!?:/i'
+  - label: dependencies
+    title:
+      - '/^(build|deps)(\([^)]+\))?!?:/i'
+  - label: chore
+    title:
+      - '/^(chore|revert)(\([^)]+\))?!?:/i'
+  # Breaking-change marker: either `!` in the type prefix or `BREAKING CHANGE:` in body.
+  - label: breaking
+    title:
+      - '/^[a-z]+(\([^)]+\))?!:/i'
+    body:
+      - '/BREAKING[ -]CHANGE:/i'

.github/release.yml

@@ -35,7 +35,7 @@ changelog:
         - dependencies
     - title: "\U0001F4DD Other Changes"
       labels:
-        - "*"
+        - '*'
       exclude:
         labels:
           - dependencies

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

@@ -0,0 +1,358 @@
+#!/usr/bin/env python3
+"""Monitor tree-sitter 0.25 upgrade readiness.
+
+Tracks two things Dependabot cannot see:
+
+  1. Peer-dep compatibility. Each tree-sitter-* grammar declares a peer
+     dependency on the tree-sitter runtime. We want to know when every
+     grammar's *latest npm release* satisfies tree-sitter@0.25.0 so we
+     can upgrade without --legacy-peer-deps.
+
+  2. Vendored upstream drift. vendor/tree-sitter-proto/ is a snapshot of
+     coder3101/tree-sitter-proto's parser.c. When upstream moves, we want
+     to know whether we can pick it up.
+
+Invoked from .github/workflows/tree-sitter-upgrade-readiness.yml daily.
+Runs locally too:
+
+    python3 .github/scripts/check-tree-sitter-upgrade-readiness.py
+
+Outputs Markdown to stdout. Exit 0 when every grammar is upgrade-ready
+and the vendored proto is in sync. Exit 1 when blockers remain (the
+workflow uses this to open or update a tracking issue).
+
+No external deps -- stdlib only, so it runs on any vanilla runner.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import pathlib
+import re
+import sys
+import urllib.error
+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
+# changes (e.g. once 0.25 lands and we target 0.26).
+TARGET_RUNTIME = "0.25.0"
+TARGET_RUNTIME_MAJOR_MINOR = ".".join(TARGET_RUNTIME.split(".")[:2])
+
+# Tree-sitter runtime -> (min_abi, max_abi) it can load. Only the current
+# and target entries matter; extend when changing TARGET_RUNTIME.
+RUNTIME_ABI_RANGES: dict[str, tuple[int, int]] = {
+    "0.21": (13, 14),
+    "0.25": (13, 15),
+}
+
+assert TARGET_RUNTIME_MAJOR_MINOR in RUNTIME_ABI_RANGES, (
+    f"RUNTIME_ABI_RANGES has no entry for {TARGET_RUNTIME_MAJOR_MINOR!r}. "
+    f"Add the ABI range after auditing the upstream release notes."
+)
+
+# Grammars we use. Values are the upstream GitHub repos to check for
+# unreleased ABI bumps (owner/repo, branch, parser.c path).
+GRAMMARS: dict[str, tuple[str, str, str]] = {
+    "tree-sitter-c":          ("tree-sitter/tree-sitter-c",          "master", "src/parser.c"),
+    "tree-sitter-c-sharp":    ("tree-sitter/tree-sitter-c-sharp",    "master", "src/parser.c"),
+    "tree-sitter-cpp":        ("tree-sitter/tree-sitter-cpp",        "master", "src/parser.c"),
+    "tree-sitter-dart":       ("UserNobody14/tree-sitter-dart",      "master", "src/parser.c"),
+    "tree-sitter-go":         ("tree-sitter/tree-sitter-go",         "master", "src/parser.c"),
+    "tree-sitter-java":       ("tree-sitter/tree-sitter-java",       "master", "src/parser.c"),
+    "tree-sitter-javascript": ("tree-sitter/tree-sitter-javascript", "master", "src/parser.c"),
+    "tree-sitter-kotlin":     ("fwcd/tree-sitter-kotlin",            "main",   "src/parser.c"),
+    "tree-sitter-php":        ("tree-sitter/tree-sitter-php",        "master", "php/src/parser.c"),
+    "tree-sitter-python":     ("tree-sitter/tree-sitter-python",     "master", "src/parser.c"),
+    "tree-sitter-ruby":       ("tree-sitter/tree-sitter-ruby",       "master", "src/parser.c"),
+    "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"),
+}
+
+UPSTREAM_PROTO_OWNER = "coder3101"
+UPSTREAM_PROTO_REPO = "tree-sitter-proto"
+UPSTREAM_PROTO_BRANCH = "main"
+
+
+# ── Helpers ─────────────────────────────────────────────────────────────
+
+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())
+    raw = pkg["dependencies"]["tree-sitter"]
+    match = re.search(r"(\d+)\.(\d+)", raw)
+    if not match:
+        raise SystemExit(f"could not parse tree-sitter version: {raw!r}")
+    return f"{match.group(1)}.{match.group(2)}"
+
+
+def npm_view_json(pkg: str) -> dict | None:
+    """Fetch package metadata from the npm registry via HTTPS.
+
+    Uses the registry API directly so we don't depend on the npm CLI
+    being available (it's a batch file on Windows which complicates
+    subprocess calls).
+    """
+    url = f"https://registry.npmjs.org/{pkg}/latest"
+    try:
+        req = urllib.request.Request(url, headers={"Accept": "application/json"})
+        with urllib.request.urlopen(req, timeout=8) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except (urllib.error.URLError, urllib.error.HTTPError, json.JSONDecodeError):
+        return None
+
+
+def satisfies_target(peer_range: str | None, target: str) -> bool:
+    """Check if a semver range like '^0.22.4' or '^0.25.0' satisfies the target.
+
+    Simple heuristic: extract the minimum version from the range and check
+    if target >= min. For caret ranges (^X.Y.Z), the upper bound is the
+    next major (for X>0) or next minor (for X==0). We check both bounds.
+    """
+    if peer_range is None:
+        # No peer dep declared = no constraint = compatible.
+        return True
+    match = re.search(r"(\d+)\.(\d+)\.(\d+)", peer_range)
+    if not match:
+        return False
+    min_major, min_minor, min_patch = int(match.group(1)), int(match.group(2)), int(match.group(3))
+
+    t_match = re.search(r"(\d+)\.(\d+)\.(\d+)", target)
+    if not t_match:
+        return False
+    t_major, t_minor, t_patch = int(t_match.group(1)), int(t_match.group(2)), int(t_match.group(3))
+
+    # Target must be >= minimum.
+    target_tuple = (t_major, t_minor, t_patch)
+    min_tuple = (min_major, min_minor, min_patch)
+    if target_tuple < min_tuple:
+        return False
+
+    # For caret ranges with major 0: ^0.X.Y allows [0.X.Y, 0.(X+1).0).
+    if peer_range.startswith("^") and min_major == 0:
+        if t_major != 0 or t_minor >= min_minor + 1:
+            return False
+    # For caret ranges with major >0: ^X.Y.Z allows [X.Y.Z, (X+1).0.0).
+    elif peer_range.startswith("^") and min_major > 0:
+        if t_major >= min_major + 1:
+            return False
+
+    return True
+
+
+_GITHUB_TOKEN = os.environ.get("GITHUB_TOKEN")
+
+
+def fetch_text(url: str, timeout: int = 8) -> str | None:
+    """Fetch a URL and return its text, or None on failure.
+
+    Adds an Authorization header for github.com URLs when GITHUB_TOKEN is
+    set (raises the rate limit from 60 to 5 000 requests/hour).
+    """
+    headers: dict[str, str] = {}
+    if _GITHUB_TOKEN and ("github.com" in url or "githubusercontent.com" in url):
+        headers["Authorization"] = f"Bearer {_GITHUB_TOKEN}"
+    try:
+        req = urllib.request.Request(url, headers=headers)
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return resp.read().decode("utf-8", errors="ignore")
+    except (urllib.error.URLError, urllib.error.HTTPError):
+        return None
+
+
+def extract_abi_from_text(text: str) -> int | None:
+    """Extract LANGUAGE_VERSION from parser.c text."""
+    match = re.search(r"#define\s+LANGUAGE_VERSION\s+(\d+)", text[:4096])
+    return int(match.group(1)) if match else None
+
+
+def extract_language_version(parser_c: pathlib.Path) -> int | None:
+    """Return the LANGUAGE_VERSION defined in a parser.c, or None if absent."""
+    if not parser_c.is_file():
+        return None
+    with parser_c.open("r", encoding="utf-8", errors="ignore") as fh:
+        head = fh.read(4096)
+    return extract_abi_from_text(head)
+
+
+def md_h(text: str, level: int = 2) -> str:
+    return f"{'#' * level} {text}\n"
+
+
+# ── Main ────────────────────────────────────────────────────────────────
+
+def main() -> int:
+    blockers: dict[str, str] = {}
+    lines: list[str] = []
+    lines.append(md_h("Tree-sitter 0.25 upgrade readiness", 1))
+    lines.append("")
+
+    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))
+
+    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("")
+
+    # ── 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("|---|---|---|---|---|---|---|")
+
+    ready_count = 0
+    total_count = len(GRAMMARS)
+
+    for name, (upstream_repo, upstream_branch, parser_path) in sorted(GRAMMARS.items()):
+        # Fetch latest npm metadata.
+        info = npm_view_json(name)
+        fetch_failed = info is None
+        npm_version = "?"
+        peer_range = None
+        peer_optional = True
+        if info:
+            npm_version = info.get("version", "?")
+            peers = info.get("peerDependencies") or {}
+            peer_range = peers.get("tree-sitter")
+            meta = info.get("peerDependenciesMeta") or {}
+            ts_meta = meta.get("tree-sitter") or {}
+            peer_optional = ts_meta.get("optional", False) if peer_range else True
+
+        if fetch_failed:
+            peer_display = "? (fetch failed)"
+            compatible = 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)
+
+        # Check installed ABI using the same parser_path from GRAMMARS.
+        installed_parser = GITNEXUS_DIR / "node_modules" / name / parser_path
+        if not installed_parser.is_file():
+            # Fallback to default location.
+            installed_parser = GITNEXUS_DIR / "node_modules" / name / "src" / "parser.c"
+        installed_abi = extract_language_version(installed_parser)
+        abi_display = str(installed_abi) if installed_abi else "?"
+
+        # Check upstream (main/master branch) ABI for unreleased work.
+        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
+        upstream_abi_display = str(upstream_abi) if upstream_abi else "?"
+
+        # Determine status.
+        if fetch_failed:
+            status = "Unknown (fetch failed)"
+            blockers[name] = f"`{name}`: npm registry fetch failed — could not verify peer dep"
+        elif compatible:
+            status = "Ready"
+            ready_count += 1
+        elif upstream_abi and upstream_abi >= 15:
+            status = "Unreleased (ABI 15 on main)"
+            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:
+            upstream_pkg_url = (
+                f"https://raw.githubusercontent.com/{upstream_repo}/"
+                f"{upstream_branch}/package.json"
+            )
+            upstream_pkg_text = fetch_text(upstream_pkg_url)
+            if upstream_pkg_text:
+                try:
+                    upstream_pkg = json.loads(upstream_pkg_text)
+                    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)"
+                        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} |"
+        )
+
+    lines.append("")
+    lines.append(f"**{ready_count}/{total_count}** grammars ready for `tree-sitter@{TARGET_RUNTIME}`.")
+    lines.append("")
+
+    # ── Vendored proto drift ─────────────────────────────────────────
+    lines.append(md_h("Vendored tree-sitter-proto", 2))
+    vendored_abi = extract_language_version(VENDOR_PROTO_DIR / "src" / "parser.c")
+
+    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
+
+    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**.")
+    else:
+        lines.append("All grammars are compatible. Upgrade to `tree-sitter@0.25` is **ready**.")
+
+    print("\n".join(lines))
+    return 1 if blockers else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,173 @@
+#!/usr/bin/env python3
+"""Enforce the GitHub Actions concurrency convention.
+
+See CONTRIBUTING.md -> "GitHub Actions — Concurrency Convention" for the rules.
+
+Invoked from .github/workflows/ci-quality.yml. Runs locally too:
+    python3 .github/scripts/check-workflow-concurrency.py .github/workflows
+
+Rules:
+  1. Every entry-point (non-reusable) workflow declares a top-level
+     `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.
+
+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
+flat (`on: workflow_call`) and mapping (`on:\n  workflow_call:`) forms.
+"""
+
+from __future__ import annotations
+
+import pathlib
+import re
+import sys
+
+
+REQUIRED_TOKENS = ("${{ github.workflow }}", "CI-")
+
+
+def is_reusable(lines: list[str]) -> bool:
+    """Return True iff the workflow's `on:` block names only `workflow_call`."""
+    in_on = False
+    on_indent: int | None = None
+    keys: list[str] = []
+
+    for raw in lines:
+        # Skip blank lines and comments
+        stripped = raw.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+
+        indent = len(raw) - len(raw.lstrip(" "))
+
+        if not in_on:
+            if raw.startswith("on:"):
+                remainder = raw[len("on:"):].strip()
+                if not remainder:
+                    # `on:` followed by indented mapping on next lines
+                    in_on = True
+                    on_indent = indent
+                    continue
+                if remainder.startswith("[") and remainder.endswith("]"):
+                    # Flow-style list: on: [workflow_call]
+                    items = [
+                        item.strip() for item in remainder.strip("[]").split(",")
+                    ]
+                    return items == ["workflow_call"]
+                # Scalar form: on: workflow_call  (or a single other event)
+                return remainder == "workflow_call"
+            continue
+
+        # Inside the `on:` block; stop when indentation returns to <= on_indent
+        if on_indent is not None and indent <= on_indent:
+            break
+
+        # Only consider keys at on_indent + indentation step (anything deeper
+        # is nested config like `types:`)
+        if ":" not in stripped:
+            continue
+        # Heuristic: first-level event keys are those with indent == on_indent + 2
+        # (the canonical step for a 2-space YAML doc). We collect all first-level
+        # keys by tracking the smallest indent seen inside the block.
+        keys.append((indent, stripped.split(":", 1)[0].strip()))
+
+    if not keys:
+        return False
+
+    # Take only the outermost-indented keys as the event list
+    min_indent = min(i for i, _ in keys)
+    events = [name for i, name in keys if i == min_indent]
+    return events == ["workflow_call"]
+
+
+CONCURRENCY_RE = re.compile(r"^concurrency:\s*$")
+GROUP_RE = re.compile(r"^\s+group:\s*(.+?)\s*$")
+
+
+def extract_group_key(lines: list[str]) -> str | None:
+    """Return the `group:` value of the top-level `concurrency:` block, or None."""
+    for idx, raw in enumerate(lines):
+        if CONCURRENCY_RE.match(raw):
+            # Scan forward until we leave the concurrency block (next top-level key
+            # is at column 0 and ends with `:`).
+            for follow in lines[idx + 1:]:
+                if follow and not follow.startswith(" ") and follow.rstrip().endswith(":"):
+                    break
+                m = GROUP_RE.match(follow)
+                if m:
+                    return m.group(1).strip().strip("'").strip('"')
+            break
+    return None
+
+
+def has_top_level_concurrency(lines: list[str]) -> bool:
+    return any(CONCURRENCY_RE.match(raw) for raw in lines)
+
+
+def check(workflows_dir: pathlib.Path) -> int:
+    fail = 0
+    files = sorted(
+        list(workflows_dir.glob("*.yml")) + list(workflows_dir.glob("*.yaml"))
+    )
+    for path in files:
+        lines = path.read_text(encoding="utf-8").splitlines()
+        reusable = is_reusable(lines)
+        has_conc = has_top_level_concurrency(lines)
+
+        if reusable:
+            if has_conc:
+                print(
+                    f"::error file={path}::Reusable workflow (on: workflow_call) "
+                    "must NOT declare its own concurrency block — it inherits "
+                    "from the caller. See CONTRIBUTING.md -> GitHub Actions — "
+                    "Concurrency Convention."
+                )
+                fail = 1
+            continue
+
+        if not has_conc:
+            print(
+                f"::error file={path}::Missing top-level concurrency block. "
+                "See CONTRIBUTING.md -> GitHub Actions — Concurrency Convention."
+            )
+            fail = 1
+            continue
+
+        group = extract_group_key(lines)
+        if group is None:
+            print(
+                f"::error file={path}::concurrency block is missing a "
+                "`group:` key."
+            )
+            fail = 1
+            continue
+
+        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."
+            )
+            fail = 1
+
+    return fail
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) != 2:
+        print(f"usage: {argv[0]} <workflows-dir>", file=sys.stderr)
+        return 2
+    workflows_dir = pathlib.Path(argv[1])
+    if not workflows_dir.is_dir():
+        print(f"not a directory: {workflows_dir}", file=sys.stderr)
+        return 2
+    return check(workflows_dir)
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

.github/workflows/ci-e2e.yml

@@ -11,8 +11,8 @@ jobs:
     outputs:
       web_changed: ${{ steps.filter.outputs.web }}
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
-      - uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v3
         id: filter
         with:
           filters: |
@@ -26,17 +26,9 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 20
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
-      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
-        with:
-          node-version: 20
-          cache: npm
-          cache-dependency-path: gitnexus-web/package-lock.json
-
-      - name: Install frontend dependencies
-        run: npm ci
-        working-directory: gitnexus-web
+      - uses: ./.github/actions/setup-gitnexus-web
 
       - name: Install Playwright browsers
         run: npx playwright install --with-deps chromium
@@ -82,7 +74,7 @@ jobs:
 
       - name: Upload test results
         if: always()
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: e2e-results
           path: |

.github/workflows/ci-quality.yml

@@ -4,11 +4,37 @@ on:
   workflow_call:
 
 jobs:
+  format:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: package-lock.json
+      - run: npm ci
+      - run: npx prettier --check .
+
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: package-lock.json
+      - run: npm ci
+      - run: npx eslint .
+
   typecheck:
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - uses: ./.github/actions/setup-gitnexus
       - run: npx tsc --noEmit
         working-directory: gitnexus
@@ -17,13 +43,30 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
-      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
-        with:
-          node-version: 20
-          cache: npm
-          cache-dependency-path: gitnexus-web/package-lock.json
-      - run: npm ci
-        working-directory: gitnexus-web
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: ./.github/actions/setup-gitnexus-web
       - run: npx tsc -b --noEmit
         working-directory: gitnexus-web
+
+  # Enforces the convention documented in CONTRIBUTING.md → "GitHub Actions —
+  # Concurrency Convention":
+  #   1. Every entry-point (non-reusable) workflow declares a top-level
+  #      `concurrency:` block.
+  #   2. Reusable workflows (`on: workflow_call` only) do NOT declare one —
+  #      they inherit concurrency from the caller.
+  #   3. The concurrency group key starts with `${{ github.workflow }}` or
+  #      the literal `CI-` prefix (the documented ci.yml exception for
+  #      reusable-workflow-safe grouping).
+  # Reusability is detected by parsing each workflow's `on:` block, not an
+  # allowlist, so new reusable workflows never produce false positives.
+  workflow-convention:
+    name: Workflow concurrency convention
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Validate workflow concurrency convention
+        shell: bash
+        run: |
+          set -euo pipefail
+          python3 .github/scripts/check-workflow-concurrency.py .github/workflows

.github/workflows/ci-report.yml

@@ -6,14 +6,24 @@ name: CI Report
 
 on:
   workflow_run:
-    workflows: ["CI"]
+    workflows: ['CI']
     types: [completed]
 
 permissions:
-  actions: read        # needed to list/download workflow run artifacts
-  contents: read       # needed for sparse checkout of vitest.config.ts
+  actions: read # needed to list/download workflow run artifacts
+  contents: read # needed for sparse checkout of vitest.config.ts
   pull-requests: write # needed to post sticky PR comment
 
+# Concurrency convention: see CONTRIBUTING.md → "GitHub Actions — Concurrency Convention".
+# Serialize sticky-comment writes per PR so two rapid CI completions don't race.
+# Internal PRs surface in `pull_requests[0].number`. Fork PRs leave that array empty,
+# so we fall back to `<head-repo-full-name>/<head-branch>`, which is stable across
+# reruns and subsequent pushes for the same fork PR (unlike `workflow_run.id` which
+# is unique per run and therefore does not serialize anything).
+concurrency:
+  group: ${{ 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) }}
+  cancel-in-progress: false
+
 jobs:
   pr-report:
     name: PR Report
@@ -26,7 +36,7 @@ jobs:
     steps:
       # ── Download artifacts from the CI run ────────────────────────
       - name: Download artifacts
-        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v7
         with:
           script: |
             const fs = require('fs');
@@ -113,7 +123,7 @@ jobs:
 
       - name: Checkout (for vitest config)
         if: steps.meta.outputs.skip != 'true'
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           sparse-checkout: gitnexus/vitest.config.ts
           sparse-checkout-cone-mode: false
@@ -122,7 +132,7 @@ jobs:
       - name: Fetch base branch coverage
         if: steps.meta.outputs.skip != 'true'
         id: base-coverage
-        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v7
         with:
           script: |
             const fs = require('fs');
@@ -406,7 +416,7 @@ jobs:
 
       - name: Comment on PR
         if: steps.meta.outputs.skip != 'true'
-        uses: marocchino/sticky-pull-request-comment@773744901bac0e8cbb5a0dc842800d45e9b2b405 # v2
+        uses: marocchino/sticky-pull-request-comment@0ea0beb66eb9baf113663a64ec522f60e49231c0 # v2
         with:
           header: ci-report
           number: ${{ steps.meta.outputs.pr_number }}

.github/workflows/ci-tests.yml

@@ -9,7 +9,7 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 25
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - uses: ./.github/actions/setup-gitnexus
         with:
           build: 'true'
@@ -28,6 +28,7 @@ jobs:
           --coverage.reportOnFailure=true
         working-directory: gitnexus
 
+      # gitnexus-shared already built by setup-gitnexus action above
       - name: Install gitnexus-web dependencies
         run: npm ci
         working-directory: gitnexus-web
@@ -40,9 +41,12 @@ jobs:
           --outputFile=web-test-results.json
         working-directory: gitnexus-web
 
+      - name: Run docker-server integration tests
+        run: node --test docker-server.test.mjs
+
       - name: Upload test reports
         if: always()
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: test-reports
           path: |
@@ -62,7 +66,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     timeout-minutes: 25
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - uses: ./.github/actions/setup-gitnexus
         with:
           build: 'true'

.github/workflows/ci.yml

@@ -9,9 +9,20 @@ on:
     paths-ignore: ['**.md', 'docs/**', 'LICENSE']
   workflow_call:
 
+# Concurrency convention: see CONTRIBUTING.md → "GitHub Actions — Concurrency Convention".
+# Hardcoded `CI-` prefix (not `${{ github.workflow }}`) because this workflow is
+# invoked as a reusable workflow from publish.yml and release-candidate.yml. In
+# 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.).
 concurrency:
-  group: ci-${{ github.ref }}
-  cancel-in-progress: true
+  group: ${{ (github.event_name == 'pull_request' || github.event_name == 'push') && format('CI-{0}', github.ref) || format('CI-nested-{0}', github.run_id) }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
 # ── Reusable workflow orchestration ─────────────────────────────────
 # Each concern lives in its own workflow file for maintainability:
@@ -74,7 +85,7 @@ jobs:
           cp pr-meta/e2e_result      pr-meta/e2e-result
 
       - name: Upload PR metadata
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: pr-meta
           path: pr-meta/
@@ -96,9 +107,9 @@ jobs:
           TESTS: ${{ needs.tests.result }}
           E2E: ${{ needs.e2e.result }}
         run: |
-          echo "Quality:     $QUALITY"
-          echo "Tests:       $TESTS"
-          echo "E2E:         $E2E"
+          echo "Quality:        $QUALITY"
+          echo "Tests:          $TESTS"
+          echo "E2E:            $E2E"
           if [[ "$QUALITY" != "success" ]] ||
              [[ "$TESTS" != "success" ]]; then
             echo "::error::Quality or test jobs failed"

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

@@ -16,9 +16,10 @@ on:
   issue_comment:
     types: [created]
 
+# Concurrency convention: see CONTRIBUTING.md → "GitHub Actions — Concurrency Convention".
 # Serialize per-PR to avoid racing review comments.
 concurrency:
-  group: claude-review-${{ github.event.issue.number || github.event.pull_request.number }}
+  group: ${{ github.workflow }}-${{ github.event.issue.number || github.event.pull_request.number }}
   cancel-in-progress: false
 
 jobs:
@@ -56,7 +57,7 @@ jobs:
       # For issue_comment triggers, resolve the PR number, head SHA, and fork repo
       - name: Resolve PR context
         id: pr
-        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v7
         with:
           script: |
             let pr;
@@ -76,7 +77,7 @@ jobs:
             core.setOutput('branch', pr.head.ref);
 
       - name: Checkout PR head
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           repository: ${{ steps.pr.outputs.repo }}
           ref: ${{ steps.pr.outputs.sha }}

.github/workflows/claude.yml

@@ -10,9 +10,10 @@ on:
   pull_request_review:
     types: [submitted]
 
+# Concurrency convention: see CONTRIBUTING.md → "GitHub Actions — Concurrency Convention".
 # Serialize per-PR/issue to avoid racing comments.
 concurrency:
-  group: claude-code-${{ github.event.issue.number || github.event.pull_request.number || github.event.issue.id }}
+  group: ${{ github.workflow }}-${{ github.event.issue.number || github.event.pull_request.number || github.event.issue.id }}
   cancel-in-progress: false
 
 jobs:
@@ -53,12 +54,12 @@ jobs:
       pull-requests: write
       issues: write
       id-token: write
-      actions: read         # required for Claude to read CI results on PRs
+      actions: read # required for Claude to read CI results on PRs
     steps:
       # For PR-related triggers, resolve the fork repo so we can checkout correctly.
       - name: Resolve PR context
         id: pr
-        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v7
         with:
           script: |
             // Determine if this event is PR-related
@@ -90,7 +91,7 @@ jobs:
             core.setOutput('branch', pr.head.ref);
 
       - name: Checkout repository
-        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           repository: ${{ steps.pr.outputs.is_pr == 'true' && steps.pr.outputs.repo || github.repository }}
           ref: ${{ steps.pr.outputs.is_pr == 'true' && steps.pr.outputs.sha || '' }}

.github/workflows/docker.yml

@@ -0,0 +1,71 @@
+name: Docker Build & Push
+
+on:
+  push:
+    tags:
+      - 'v*'
+    branches:
+      - main
+    paths-ignore: ['**.md', 'docs/**', 'LICENSE']
+  workflow_dispatch:
+
+# Concurrency convention: see CONTRIBUTING.md → "GitHub Actions — Concurrency Convention".
+# Tag refs are unique per release — distinct tags run in parallel.
+# Pushes to main serialize; cancel superseded runs.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref == 'refs/heads/main' }}
+
+jobs:
+  build-push:
+    name: Build & Push image
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      # Required for multi-platform (linux/arm64) emulation.
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@ce360397dd3f832beb865e1373c09c0e9f86d70a # v4.0.0
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      # Computes image tags and labels from Git metadata:
+      #   v*  tag  → ghcr.io/<owner>/<repo>:<semver>  (e.g. 1.2.3, 1.2, 1)
+      #   main push → ghcr.io/<owner>/<repo>:latest
+      - name: Extract Docker metadata
+        id: meta
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+            type=raw,value=latest,enable={{is_default_branch}}
+            type=sha,prefix=sha-,format=short
+
+      - name: Build and push
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          build-args: |
+            BUILDPLATFORM=${{ runner.os == 'Linux' && 'linux/amd64' || 'linux/amd64' }}

.github/workflows/pr-description-check.yml

@@ -8,8 +8,9 @@ on:
 permissions:
   pull-requests: write
 
+# Concurrency convention: see CONTRIBUTING.md → "GitHub Actions — Concurrency Convention".
 concurrency:
-  group: pr-desc-${{ github.event.pull_request.number }}
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
   cancel-in-progress: true
 
 jobs:
@@ -18,7 +19,7 @@ jobs:
     timeout-minutes: 5
     steps:
       - name: Check PR description quality
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           script: |
             const MIN_BODY_LENGTH = 50;

.github/workflows/pr-labeler.yml

@@ -0,0 +1,113 @@
+name: PR Conventional Labeler
+
+# Two workflows in one file with different triggers, matched to the minimum
+# privilege each needs:
+#
+#   validate-title (on: pull_request)
+#     Fork-safe. Runs with the PR-head's read-only GITHUB_TOKEN. Uses
+#     `amannn/action-semantic-pull-request` to fail the check when the PR
+#     title doesn't follow the conventional-commit format. Because the
+#     action only reads the event payload, no fork-controlled code runs.
+#
+#   autolabel (on: pull_request_target)
+#     Needs `pull-requests: write` to apply labels, so must be
+#     pull_request_target. Uses `release-drafter/release-drafter` with
+#     `dry-run: true` to only run the autolabeler against the
+#     `.github/release-drafter.yml` config from the BASE ref (release-
+#     drafter reads the config from the repository's default branch, NOT
+#     the PR head — verify with `gh api repos/release-drafter/release-drafter/contents/...`
+#     or a fork-test PR before merging if the repo is high-value).
+#     `sync-labels: true` in the config removes managed autolabels that no
+#     longer match (e.g. when `!` or `BREAKING CHANGE:` is dropped).
+#
+# Title format: <type>[(scope)][!]: <subject>
+#   Allowed types: feat, fix, perf, refactor, docs, test, ci, build, chore, revert, deps
+#   Trailing `!` on the type marks a breaking change.
+# See CONTRIBUTING.md → "Pull request titles".
+
+on:
+  pull_request:
+    # Title-only changes fire `edited`. `opened` and `reopened` cover creation.
+    # `synchronize` (push to the PR branch) is intentionally excluded — titles
+    # don't change on push, so it only wastes CI minutes and broadens the
+    # privileged-token exposure window on the autolabel job.
+    types: [opened, edited, reopened]
+  pull_request_target:
+    types: [opened, edited, reopened]
+
+# Concurrency convention: see CONTRIBUTING.md → "GitHub Actions — Concurrency Convention".
+# Include `github.event_name` so `pull_request` (validate-title) and
+# `pull_request_target` (autolabel) runs for the same PR do NOT share a slot
+# and therefore cannot cancel each other — a cancelled required-check would
+# permanently block merge until the next title edit.
+# Within each trigger the latest title edit still supersedes the prior run.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  validate-title:
+    # Fork-safe job — only runs on `pull_request` (not `pull_request_target`).
+    # Token is read-only; writes a commit status that branch protection can
+    # require before merge.
+    name: Validate PR title
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      pull-requests: read
+    steps:
+      # Pinned to v6.1.1. Verify SHA via:
+      #   gh api repos/amannn/action-semantic-pull-request/git/refs/tags/v6.1.1
+      - uses: amannn/action-semantic-pull-request@48f256284bd46cdaab1048c3721360e808335d50 # v6.1.1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          types: |
+            feat
+            fix
+            perf
+            refactor
+            docs
+            test
+            ci
+            build
+            chore
+            revert
+            deps
+          requireScope: false
+          # Subject must be non-empty. We DO allow capitalized proper nouns
+          # (MCP, GitHub, API, etc.) — the old `^(?![A-Z]).+$` pattern
+          # rejected legitimate titles like `fix: MCP tool schema`.
+          subjectPattern: ^\S.{2,}$
+          subjectPatternError: |
+            The subject "{subject}" in PR title "{title}" is invalid.
+            Subjects must be at least 3 characters and must not start with whitespace.
+          wip: false
+
+  autolabel:
+    # Privileged job — runs only on `pull_request_target` so it can write labels.
+    # Never checks out fork code, never executes fork-controlled input; only
+    # reads the PR metadata (title, body, labels) and calls the GitHub API.
+    name: Apply conventional label
+    if: github.event_name == 'pull_request_target'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      # `contents: read` is required — release-drafter's context.config() reads
+      # `.github/release-drafter.yml` from the repo's default branch via the
+      # repo-contents API. Without it the job silently 403s and no labels are
+      # applied. Job-level permissions nullify all unlisted scopes, so an
+      # explicit grant is necessary here.
+      contents: read
+      pull-requests: write
+    steps:
+      # 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
+        with:
+          config-name: release-drafter.yml
+          dry-run: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/publish.yml

@@ -7,13 +7,22 @@ on:
 
 # No workflow-level permissions — scoped per job below.
 
+# 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.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
 jobs:
   ci:
     uses: ./.github/workflows/ci.yml
     permissions:
       contents: read
       actions: read
-      pull-requests: write
+      # No pull-requests:write — `ci.yml`'s save-pr-meta job is gated on
+      # `github.event_name == 'pull_request'`, so it never runs during a
+      # tag-triggered publish. Least-privilege for release-critical paths.
 
   publish:
     needs: ci
@@ -23,13 +32,17 @@ jobs:
       contents: write
       id-token: write
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
-      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
         with:
           node-version: 20
           registry-url: https://registry.npmjs.org
           cache: npm
           cache-dependency-path: gitnexus/package-lock.json
+      - name: Build gitnexus-shared
+        run: npm install && npm run build
+        working-directory: gitnexus-shared
+
       - run: npm ci
         working-directory: gitnexus
 
@@ -63,7 +76,22 @@ jobs:
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
+      - name: Extract release notes from CHANGELOG
+        id: changelog
+        shell: bash
+        run: |
+          VERSION="${GITHUB_REF#refs/tags/v}"
+          NOTES=$(awk "/^## \\[$VERSION\\]/{found=1; next} /^## \\[/{if(found) exit} found" gitnexus/CHANGELOG.md)
+          if [ -z "$NOTES" ]; then
+            echo "::warning::No CHANGELOG entry found for v$VERSION, falling back to auto-generated notes"
+            echo "fallback=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "$NOTES" > /tmp/release-notes.md
+            echo "fallback=false" >> "$GITHUB_OUTPUT"
+          fi
+
       - name: Create GitHub Release
-        uses: softprops/action-gh-release@a06a81a03ee405af7f2048a818ed3f03bbf83c7b # v2
+        uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda # v2
         with:
-          generate_release_notes: true
+          body_path: ${{ steps.changelog.outputs.fallback == 'false' && '/tmp/release-notes.md' || '' }}
+          generate_release_notes: ${{ steps.changelog.outputs.fallback == 'true' }}

.github/workflows/release-candidate.yml

@@ -0,0 +1,366 @@
+name: Release Candidate
+
+on:
+  # Publish a release-candidate build whenever a merge/commit lands on main.
+  # Docs/README-only changes are filtered out so prose updates don't
+  # cut a release.
+  push:
+    branches: [main]
+    paths-ignore:
+      - '**.md'
+      - 'docs/**'
+      - 'LICENSE'
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: >-
+          Cycle policy. 'auto' (default) continues the active rc cycle on
+          this branch if there is one, otherwise bumps patch from latest.
+          Choose 'patch' / 'minor' / 'major' to explicitly start or reset
+          an rc cycle.
+        required: false
+        default: 'auto'
+        type: choice
+        options:
+          - auto
+          - patch
+          - minor
+          - major
+      force:
+        description: 'Publish even when HEAD already has an rc marker'
+        required: false
+        default: 'false'
+        type: choice
+        options:
+          - 'false'
+          - 'true'
+
+# No workflow-level permissions — scoped per job below.
+permissions: {}
+
+# Concurrency convention: see CONTRIBUTING.md → "GitHub Actions — Concurrency Convention".
+# Serialize all runs on the same ref (push + workflow_dispatch) to prevent two publishes
+# racing on the rc counter. cancel-in-progress: false — the earlier merge publishes first.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  # ── Skip when HEAD already has an rc marker (retry / duplicate dispatch) ──
+  # The marker is a lightweight tag `rc/<HEAD_SHA>` pushed *before* `npm
+  # publish`, so a failed publish leaves the marker in place and the guard
+  # refuses to re-publish. Recovery path after a partial failure:
+  #   git push --delete origin rc/<HEAD_SHA> v<RC_VERSION>
+  # then redispatch with force=true.
+  guard:
+    name: Check if release candidate should run
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    outputs:
+      should_run: ${{ steps.decide.outputs.should_run }}
+      head_sha: ${{ steps.decide.outputs.head_sha }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+
+      - name: Decide
+        id: decide
+        shell: bash
+        env:
+          FORCE: ${{ inputs.force }}
+          BUMP_INPUT: ${{ inputs.bump }}
+          EVENT_NAME: ${{ github.event_name }}
+        run: |
+          set -euo pipefail
+          HEAD_SHA=$(git rev-parse HEAD)
+          echo "head_sha=$HEAD_SHA" >> "$GITHUB_OUTPUT"
+
+          if [ "$FORCE" = "true" ]; then
+            echo "Force flag set — running regardless of marker tag."
+            echo "should_run=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          # An explicit cycle reset on dispatch (bump != auto) also bypasses
+          # the dedup guard — the maintainer is deliberately asking for a
+          # new rc from the same commit.
+          if [ "$EVENT_NAME" = "workflow_dispatch" ] \
+             && [ -n "${BUMP_INPUT:-}" ] \
+             && [ "${BUMP_INPUT:-auto}" != "auto" ]; then
+            echo "Explicit bump=$BUMP_INPUT — bypassing marker dedup."
+            echo "should_run=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          # Dedup: is there already an rc/<HEAD_SHA> marker pointing at HEAD?
+          MARKER="rc/${HEAD_SHA}"
+          if git rev-parse "refs/tags/$MARKER" >/dev/null 2>&1; then
+            echo "HEAD already has marker $MARKER — skipping."
+            echo "should_run=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "No marker on HEAD — proceeding."
+            echo "should_run=true" >> "$GITHUB_OUTPUT"
+          fi
+
+  # ── Reuse the stable CI workflow ─────────────────────────────────────
+  ci:
+    needs: guard
+    if: needs.guard.outputs.should_run == 'true'
+    uses: ./.github/workflows/ci.yml
+    permissions:
+      contents: read
+    secrets: inherit
+
+  # ── Publish the rc build to npm + create GitHub prerelease ───────────
+  publish:
+    name: Publish release candidate to npm
+    needs: [guard, ci]
+    if: needs.guard.outputs.should_run == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      contents: write # push rc tag + marker
+      id-token: write # npm provenance
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+
+      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org
+          cache: npm
+          cache-dependency-path: gitnexus/package-lock.json
+
+      - name: Build gitnexus-shared
+        run: npm install && npm run build
+        working-directory: gitnexus-shared
+
+      - name: Install gitnexus dependencies
+        run: npm ci
+        working-directory: gitnexus
+
+      - name: Resolve rc version
+        id: version
+        shell: bash
+        working-directory: gitnexus
+        env:
+          BUMP_INPUT: ${{ inputs.bump }}
+          EVENT_NAME: ${{ github.event_name }}
+          PKG_NAME: gitnexus
+        run: |
+          set -euo pipefail
+
+          # 1. Current published `latest` — the floor for any new rc base.
+          #    Only E404 ("never published") falls back to package.json; any
+          #    other error (network, auth, malformed response) fails fast.
+          NPM_STDERR_LATEST="$(mktemp)"
+          if CURRENT_LATEST="$(npm view "$PKG_NAME" version 2>"$NPM_STDERR_LATEST")"; then
+            :
+          else
+            if grep -q 'E404' "$NPM_STDERR_LATEST"; then
+              CURRENT_LATEST="$(node -p "require('./package.json').version")"
+              echo "Package not on registry (E404) — seeding from package.json: $CURRENT_LATEST"
+            else
+              echo "::error::npm registry unreachable for 'view version':" >&2
+              cat "$NPM_STDERR_LATEST" >&2
+              rm -f "$NPM_STDERR_LATEST"
+              exit 1
+            fi
+          fi
+          rm -f "$NPM_STDERR_LATEST"
+          CURRENT_LATEST_CLEAN="${CURRENT_LATEST%%-*}"
+
+          # 2. Full version list — needed for the counter and for active-cycle
+          #    inference. Same E404-only fallback.
+          NPM_STDERR_VERSIONS="$(mktemp)"
+          if VERSIONS_JSON="$(npm view "$PKG_NAME" versions --json 2>"$NPM_STDERR_VERSIONS")"; then
+            :
+          else
+            if grep -q 'E404' "$NPM_STDERR_VERSIONS"; then
+              VERSIONS_JSON='[]'
+              echo "No published versions for $PKG_NAME yet (E404)."
+            else
+              echo "::error::npm registry unreachable for 'view versions':" >&2
+              cat "$NPM_STDERR_VERSIONS" >&2
+              rm -f "$NPM_STDERR_VERSIONS"
+              exit 1
+            fi
+          fi
+          rm -f "$NPM_STDERR_VERSIONS"
+
+          # 3. Base selection.
+          #    - workflow_dispatch + bump ∈ {patch,minor,major} → explicit cycle
+          #      reset from latest.
+          #    - Everything else (push, or dispatch with bump=auto) → continue
+          #      the highest active rc base > latest if one exists; else
+          #      default to patch from latest.
+          if [ "$EVENT_NAME" = "workflow_dispatch" ] \
+             && [ -n "${BUMP_INPUT:-}" ] \
+             && [ "${BUMP_INPUT:-auto}" != "auto" ]; then
+            BASE="$(npx --yes -p semver@7 semver -i "$BUMP_INPUT" "$CURRENT_LATEST_CLEAN")"
+            echo "Explicit bump=$BUMP_INPUT → BASE=$BASE"
+          else
+            cat > /tmp/active_base.mjs <<'NODESCRIPT'
+          const latest = process.env.LATEST;
+          let v;
+          try { v = JSON.parse(process.env.VERSIONS_JSON); } catch { v = []; }
+          if (!Array.isArray(v)) v = [v];
+          const parse = s => s.split(".").map(n => parseInt(n, 10));
+          const gt = (a, b) => {
+            const [A, B] = [parse(a), parse(b)];
+            for (let i = 0; i < 3; i++) if (A[i] !== B[i]) return A[i] > B[i];
+            return false;
+          };
+          const bases = new Set();
+          for (const s of v) {
+            const m = /^(\d+\.\d+\.\d+)-rc\.\d+$/.exec(s);
+            if (m && gt(m[1], latest)) bases.add(m[1]);
+          }
+          if (!bases.size) { process.stdout.write(""); process.exit(0); }
+          const sorted = [...bases].sort((a, b) => gt(a, b) ? 1 : -1);
+          process.stdout.write(sorted[sorted.length - 1]);
+          NODESCRIPT
+            ACTIVE_BASE="$(LATEST="$CURRENT_LATEST_CLEAN" VERSIONS_JSON="$VERSIONS_JSON" node /tmp/active_base.mjs)"
+            if [ -n "$ACTIVE_BASE" ]; then
+              BASE="$ACTIVE_BASE"
+              echo "Continuing active rc cycle → BASE=$BASE"
+            else
+              BASE="$(npx --yes -p semver@7 semver -i patch "$CURRENT_LATEST_CLEAN")"
+              echo "No active rc cycle → patch bump from latest → BASE=$BASE"
+            fi
+          fi
+
+          # 4. Counter: 1 + max existing N for `${BASE}-rc.*`, else 1.
+          cat > /tmp/next_rc.mjs <<'NODESCRIPT'
+          const base = process.env.BASE;
+          const prefix = base + "-rc.";
+          let v;
+          try { v = JSON.parse(process.env.VERSIONS_JSON); } catch { v = []; }
+          if (!Array.isArray(v)) v = [v];
+          const ns = v
+            .filter(s => typeof s === "string" && s.startsWith(prefix))
+            .map(s => parseInt(s.slice(prefix.length), 10))
+            .filter(n => Number.isInteger(n) && n >= 0);
+          process.stdout.write(String(ns.length ? Math.max(...ns) + 1 : 1));
+          NODESCRIPT
+          NEXT_N="$(BASE="$BASE" VERSIONS_JSON="$VERSIONS_JSON" node /tmp/next_rc.mjs)"
+          RC_VERSION="${BASE}-rc.${NEXT_N}"
+          echo "Computed rc: $RC_VERSION"
+
+          # 5. Defensive: if the exact version already exists on the registry
+          #    (e.g., race with another run), abort before re-publishing.
+          #    Same E404-only pattern used above — a transient network
+          #    failure must fail loudly, not pretend the version is missing.
+          NPM_STDERR_EXISTS="$(mktemp)"
+          if npm view "$PKG_NAME@$RC_VERSION" version 2>"$NPM_STDERR_EXISTS" >/dev/null; then
+            rm -f "$NPM_STDERR_EXISTS"
+            echo "::error::Version $RC_VERSION already exists on npm — aborting."
+            exit 1
+          else
+            if grep -qiE 'E404|not found' "$NPM_STDERR_EXISTS"; then
+              rm -f "$NPM_STDERR_EXISTS"
+              # Version doesn't exist — safe to proceed.
+            else
+              echo "::error::npm registry unreachable for existence check:" >&2
+              cat "$NPM_STDERR_EXISTS" >&2
+              rm -f "$NPM_STDERR_EXISTS"
+              exit 1
+            fi
+          fi
+
+          echo "base=$BASE"             >> "$GITHUB_OUTPUT"
+          echo "rc_n=$NEXT_N"           >> "$GITHUB_OUTPUT"
+          echo "rc_version=$RC_VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Apply rc version in-CI
+        shell: bash
+        working-directory: gitnexus
+        run: |
+          set -euo pipefail
+          npm version "${{ steps.version.outputs.rc_version }}" \
+            --no-git-tag-version --allow-same-version
+
+      - name: Build gitnexus
+        run: npm run build
+        working-directory: gitnexus
+
+      - name: Dry-run publish
+        run: npm publish --dry-run --tag rc
+        working-directory: gitnexus
+
+      # ── Acquire the "rc lock" BEFORE publishing (fixes idempotency) ─────
+      # We create two tags and push them atomically:
+      #   v<RC_VERSION>      → annotated tag on a detached release commit
+      #                        whose tree contains the rewritten package.json
+      #                        (so the tag's source matches the npm tarball)
+      #   rc/<HEAD_SHA>      → lightweight tag on HEAD; the guard's dedup key
+      # If this push fails, nothing is published — safe.
+      # If this push succeeds but npm publish fails, the marker stays on
+      # the remote and blocks retries until an operator manually cleans up.
+      - name: Create and push rc tags
+        id: reltag
+        shell: bash
+        working-directory: gitnexus
+        env:
+          RC_VERSION: ${{ steps.version.outputs.rc_version }}
+          HEAD_SHA: ${{ needs.guard.outputs.head_sha }}
+        run: |
+          set -euo pipefail
+          VTAG="v${RC_VERSION}"
+          MARKER="rc/${HEAD_SHA}"
+          git config user.name  'github-actions[bot]'
+          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+
+          # Detached release commit with the version bump — keeps `main`
+          # pristine but gives the v-tag a tree that matches the published
+          # package contents exactly (fixes release-integrity gap).
+          git add package.json package-lock.json 2>/dev/null || git add package.json
+          git commit -m "release: ${VTAG}" --allow-empty
+          RELEASE_SHA="$(git rev-parse HEAD)"
+          echo "Detached release commit: $RELEASE_SHA"
+
+          # Annotated release tag on the release commit.
+          git tag -a "$VTAG" "$RELEASE_SHA" -m "$VTAG"
+          # Lightweight marker on the user-visible HEAD for the guard.
+          git tag "$MARKER" "$HEAD_SHA"
+
+          # Atomic push of both refs. If either would clobber an existing
+          # remote ref, the push fails and we stop before npm publish.
+          git push --atomic origin "refs/tags/$VTAG" "refs/tags/$MARKER"
+
+          echo "vtag=$VTAG"     >> "$GITHUB_OUTPUT"
+          echo "marker=$MARKER" >> "$GITHUB_OUTPUT"
+          echo "release_sha=$RELEASE_SHA" >> "$GITHUB_OUTPUT"
+
+      - name: Publish to npm (rc dist-tag)
+        run: npm publish --provenance --access public --tag rc
+        working-directory: gitnexus
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Create GitHub prerelease
+        uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda # v2
+        with:
+          tag_name: ${{ steps.reltag.outputs.vtag }}
+          name: Release Candidate ${{ steps.reltag.outputs.vtag }}
+          prerelease: true
+          make_latest: 'false'
+          generate_release_notes: true
+          body: |
+            Automated release candidate build from `main`.
+
+            **npm:** `npm install gitnexus@rc`
+            **Version:** `${{ steps.version.outputs.rc_version }}`
+            **Target base:** `${{ steps.version.outputs.base }}` (rc #${{ steps.version.outputs.rc_n }})
+            **Source commit (main):** ${{ needs.guard.outputs.head_sha }}
+            **Release commit (versioned tree):** ${{ steps.reltag.outputs.release_sha }}
+
+            Release candidates are pre-stable builds intended for early testing.
+            Stable releases remain on the `latest` dist-tag.

.github/workflows/tree-sitter-upgrade-readiness.yml

@@ -0,0 +1,185 @@
+name: Tree-sitter Upgrade Readiness
+
+# Monitors readiness for upgrading tree-sitter to 0.25.x. Tracks:
+#   1. Peer-dep compatibility — can each grammar install cleanly with
+#      tree-sitter@0.25.0 without --legacy-peer-deps?
+#   2. Vendored proto drift — has coder3101/tree-sitter-proto moved
+#      ahead of our vendored snapshot?
+# See .github/scripts/check-tree-sitter-upgrade-readiness.py for the logic.
+#
+# Concurrency convention: see CONTRIBUTING.md → "GitHub Actions — Concurrency Convention".
+
+on:
+  schedule:
+    # Daily at 09:00 UTC. Matches Dependabot's daily cadence so drift
+    # and dep PRs surface together.
+    - cron: '0 9 * * *'
+  workflow_dispatch:
+  pull_request:
+    paths:
+      - '.github/scripts/check-tree-sitter-upgrade-readiness.py'
+      - '.github/workflows/tree-sitter-upgrade-readiness.yml'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: read
+
+jobs:
+  readiness:
+    name: Check upgrade readiness
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      # Needed to open/update the tracking issue on scheduled runs.
+      issues: write
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - uses: ./.github/actions/setup-gitnexus
+        with:
+          build: 'false'
+
+      - name: Run upgrade readiness check
+        id: readiness
+        shell: bash
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set +e
+          python3 .github/scripts/check-tree-sitter-upgrade-readiness.py > drift-report.md
+          code=$?
+          set -e
+          echo "exit_code=$code" >> "$GITHUB_OUTPUT"
+          {
+            echo 'report<<DRIFT_EOF'
+            cat drift-report.md
+            echo 'DRIFT_EOF'
+          } >> "$GITHUB_OUTPUT"
+          echo "=== Report ==="
+          cat drift-report.md
+
+      # On PR runs, the script validates that it runs correctly. Blockers
+      # are informational — the scheduled run opens a tracking issue.
+      - name: Annotate PR with readiness status
+        if: github.event_name == 'pull_request' && steps.readiness.outputs.exit_code != '0'
+        run: |
+          echo "::warning::Tree-sitter 0.25 upgrade has blockers. See job output for the full readiness report."
+
+      - name: Upsert tracking issue on scheduled runs
+        if: >
+          github.event_name == 'schedule' &&
+          steps.readiness.outputs.exit_code != '0'
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          REPORT: ${{ steps.readiness.outputs.report }}
+        with:
+          script: |
+            const title = 'Tree-sitter 0.25 upgrade readiness';
+            const report = process.env.REPORT;
+            const body = report + '\n\n' +
+              '<sub>Generated daily by `.github/workflows/tree-sitter-upgrade-readiness.yml`. ' +
+              'Closes automatically when all blockers are resolved.</sub>';
+            const { data: open } = await github.rest.issues.listForRepo({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              state: 'open',
+              labels: 'tree-sitter-drift',
+              per_page: 10,
+            });
+            const existing = open.find(i => i.title === title);
+            if (existing) {
+              // Extract ready/total count for the changelog comment.
+              const readyMatch = report.match(/\*\*(\d+)\/(\d+)\*\* grammars ready/);
+              const blockerMatch = report.match(/\*\*(\d+) blocker/);
+              const ready = readyMatch ? readyMatch[1] : '?';
+              const total = readyMatch ? readyMatch[2] : '?';
+              const blockers = blockerMatch ? blockerMatch[1] : '?';
+
+              // Find grammars whose status changed by diffing the old and
+              // new table rows.  Each row looks like:
+              //   | `tree-sitter-foo` | ... | Ready |
+              //   | `tree-sitter-foo` | ... | Blocking |
+              const parseRows = (md) => {
+                const map = {};
+                for (const m of md.matchAll(/\| `(tree-sitter-[^`]+)` \|.*?\| (\S+(?:\s\S+)*?) \|$/gm)) {
+                  map[m[1]] = m[2].trim();
+                }
+                return map;
+              };
+              const oldRows = parseRows(existing.body || '');
+              const newRows = parseRows(report);
+              const changes = [];
+              for (const [name, newStatus] of Object.entries(newRows)) {
+                const oldStatus = oldRows[name];
+                if (oldStatus && oldStatus !== newStatus) {
+                  changes.push(`\`${name}\`: ${oldStatus} → ${newStatus}`);
+                }
+              }
+
+              const today = new Date().toISOString().slice(0, 10);
+              let comment = `**${today}:** ${ready}/${total} ready. ${blockers} blocker(s) remaining.`;
+              if (changes.length > 0) {
+                comment += '\n\nChanges:\n' + changes.map(c => `- ${c}`).join('\n');
+              } else {
+                comment += ' No changes from previous run.';
+              }
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: existing.number,
+                body: comment,
+              });
+
+              await github.rest.issues.update({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: existing.number,
+                body,
+              });
+              core.info(`Updated existing issue #${existing.number}`);
+            } else {
+              const { data: created } = await github.rest.issues.create({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                title,
+                body,
+                labels: ['tree-sitter-drift', 'dependencies'],
+              });
+              core.info(`Opened issue #${created.number}`);
+            }
+
+      - name: Close tracking issue on clean scheduled runs
+        if: >
+          github.event_name == 'schedule' &&
+          steps.readiness.outputs.exit_code == '0'
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const title = 'Tree-sitter 0.25 upgrade readiness';
+            const { data: open } = await github.rest.issues.listForRepo({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              state: 'open',
+              labels: 'tree-sitter-drift',
+              per_page: 10,
+            });
+            const existing = open.find(i => i.title === title);
+            if (existing) {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: existing.number,
+                body: 'All grammars are now compatible with tree-sitter@0.25. Upgrade is ready! Closing automatically.',
+              });
+              await github.rest.issues.update({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: existing.number,
+                state: 'closed',
+              });
+              core.info(`Closed issue #${existing.number}`);
+            }

.github/workflows/triage-sweep.yml

@@ -47,8 +47,10 @@ permissions:
   issues: write
   pull-requests: write
 
+# Concurrency convention: see CONTRIBUTING.md → "GitHub Actions — Concurrency Convention".
+# Single global slot — newest manual dispatch supersedes any in-flight run.
 concurrency:
-  group: triage-sweep
+  group: ${{ github.workflow }}
   cancel-in-progress: true
 
 jobs:
@@ -74,7 +76,7 @@ jobs:
         run: pip install -r .github/scripts/triage/requirements.txt
 
       - name: Cache FastEmbed model weights
-        uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5
         with:
           path: ${{ github.workspace }}/.fastembed_cache
           key: fastembed-bge-small-en-v1.5

.gitignore

@@ -23,6 +23,7 @@ Thumbs.db
 .env
 .env.local
 .env.*.local
+docker/.env
 
 # Logs
 *.log
@@ -81,6 +82,11 @@ GitNexus.sln
 # Git worktrees
 .worktrees/
 
+# Vendored tree-sitter grammar build artifacts (created at install time,
+# never committed). See docs/plans/2026-04-15-002-fix-tree-sitter-proto-vendor-deps-plan.md
+gitnexus/vendor/**/build/
+gitnexus/vendor/**/node_modules/
+
 /github/scripts/triage/__pycache__/
 
 .claude-flow/
@@ -93,4 +99,7 @@ GitNexus.sln
 
 .history/
 
-.swarm/
+.swarm/
+
+local_docs/
+

.husky/pre-commit

@@ -1,33 +1,26 @@
 #!/usr/bin/env bash
-# Pre-commit hook (husky): typecheck + unit tests for both packages.
-# Mirrors CI checks from ci-quality.yml and ci-tests.yml.
+# Pre-commit hook: format staged files + typecheck.
+# Tests run in CI (ci-tests.yml), not here.
 # Skip with: git commit --no-verify
-#
-# CI coverage:
-#   quality / typecheck      → tsc --noEmit in gitnexus/
-#   quality / typecheck-web  → tsc -b --noEmit in gitnexus-web/
-#   tests / ubuntu+coverage  → vitest run in gitnexus/ (all projects)
-#   e2e / chromium           → playwright (requires servers — skipped)
 
 ROOT="$(git rev-parse --show-toplevel)"
 
+# 1. Format staged files with prettier via lint-staged
+echo "pre-commit: formatting staged files..."
+"$ROOT/node_modules/.bin/lint-staged" || exit 1
+
+# 2. Typecheck changed packages
 WEB_CHANGED=$(git diff --cached --name-only -- 'gitnexus-web/' | head -1)
 CLI_CHANGED=$(git diff --cached --name-only -- 'gitnexus/' | head -1)
 
 if [ -n "$WEB_CHANGED" ]; then
   echo "pre-commit: typechecking gitnexus-web (tsc -b)..."
-  cd "$ROOT/gitnexus-web" && npx tsc -b --noEmit
-
-  echo "pre-commit: running gitnexus-web unit tests..."
-  npx vitest run --reporter=dot
+  cd "$ROOT/gitnexus-web" && ./node_modules/.bin/tsc -b --noEmit || exit 1
 fi
 
 if [ -n "$CLI_CHANGED" ]; then
   echo "pre-commit: typechecking gitnexus..."
-  cd "$ROOT/gitnexus" && npx tsc --noEmit
-
-  echo "pre-commit: running gitnexus unit tests (default project)..."
-  npx vitest run --project default --reporter=dot
+  cd "$ROOT/gitnexus" && ./node_modules/.bin/tsc --noEmit || exit 1
 fi
 
 echo "pre-commit: all checks passed"

.prettierignore

@@ -0,0 +1,16 @@
+dist/
+coverage/
+gitnexus/vendor/
+gitnexus/test/fixtures/
+gitnexus-web/playwright-report/
+gitnexus-web/test-results/
+*.d.ts
+*.snap
+*.wasm
+*.md
+.gitnexus/
+.vercel/
+.claude-flow/
+.swarm/
+assets/
+repomix-output*

.prettierrc

@@ -0,0 +1,10 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "printWidth": 100,
+  "tabWidth": 2,
+  "endOfLine": "lf",
+  "plugins": ["prettier-plugin-tailwindcss"],
+  "tailwindStylesheet": "./gitnexus-web/src/index.css"
+}

AGENTS.md

@@ -1,116 +1,122 @@
-<!-- version: 1.2.0 -->
-<!--
-  Metadata: version, last reviewed, scope, model policy, reference docs, changelog.
-  Last updated: 2026-03-22
--->
+<!-- version: 1.4.0 -->
+<!-- Last updated: 2026-04-16 -->
 
-Last reviewed: 2026-03-24
+Last reviewed: 2026-04-16
 
 **Project:** GitNexus · **Environment:** dev · **Maintainer:** repository maintainers (see GitHub)
 
-This file uses a standard agent header (version, scope, model policy, reference docs, changelog), adapted for this **TypeScript/JavaScript monorepo**.
-
 ## Scope
 
-| | |
-|--|--|
-| **Reads** | Repository tree as needed for the task: `gitnexus/`, `gitnexus-web/`, `eval/`, plugin packages, `.github/`, `.gitnexus/` when present, and docs. |
-| **Writes** | Only paths required for the requested change; keep diffs minimal. Update lockfiles when dependencies change. |
-| **Executes** | `npm`, `npx`, `node` under `gitnexus/` and `gitnexus-web/`; `uv run` for Python under `eval/` when applicable; shell utilities for documented CI/dev workflows. |
-| **Off-limits** | User secrets (e.g. real `.env`), production deployment credentials, unrelated repositories, destructive git history operations without explicit human confirmation. |
+| Boundary | Rule |
+|----------|------|
+| **Reads** | `gitnexus/`, `gitnexus-web/`, `eval/`, plugin packages, `.github/`, `.gitnexus/`, docs. |
+| **Writes** | Only paths required for the change; keep diffs minimal. Update lockfiles when deps change. |
+| **Executes** | `npm`, `npx`, `node` under `gitnexus/` and `gitnexus-web/`; `uv run` for Python under `eval/`; documented CI/dev workflows. |
+| **Off-limits** | Real `.env` / secrets, production credentials, unrelated repos, destructive git ops without confirmation. |
 
 ## Model Configuration
 
-- **Primary:** Pin in **Cursor** (Settings → model). Use a **named** model (e.g. GPT-5.2, Claude Sonnet 4.x). Avoid relying on **Auto** when reproducibility or audit trail matters.
-- **Fallback:** As configured in Cursor or your organization (do not encode `latest` or wildcards in automation configs).
-- **Notes:** The open-source GitNexus CLI indexer does not call an LLM. Optional Nexus AI in the web UI uses end-user provider keys and models.
+- **Primary:** Use a named model (e.g. Claude Sonnet 4.x). Avoid `Auto` or unversioned `latest` when reproducibility matters.
+- **Notes:** The GitNexus CLI indexer does not call an LLM.
 
 ## Execution Sequence (complex tasks)
 
-Long sessions dilute instructions. For **multi-step** work, state up front:
-
+For multi-step work, state up front:
 1. Which rules in this file and **[GUARDRAILS.md](GUARDRAILS.md)** apply (and any relevant Signs).
-2. Current **Scope** boundaries (Reads / Writes / Off-limits).
-3. Which **validation commands** you will run (e.g. `cd gitnexus && npm test`, `npx tsc --noEmit`).
+2. Current **Scope** boundaries.
+3. Which **validation commands** you will run (`cd gitnexus && npm test`, `npx tsc --noEmit`).
 
-On very long threads, the human may add *“Remember: apply all AGENTS.md rules”* to re-weight rule tokens against context dilution.
+On long threads, *"Remember: apply all AGENTS.md rules"* re-weights these instructions against context dilution.
 
 ## Claude Code hooks
 
-Hooks enforce gates that prompts cannot. In **Claude Code**, **PreToolUse** hooks can block tools such as `git_commit` until checks pass. Adapt to this repo: e.g. `cd gitnexus && npm test` before commit.
+**PreToolUse** hooks can block tools (e.g. `git_commit`) until checks pass. Adapt to this repo: `cd gitnexus && npm test` before commit.
 
-## Context budget (Cursor / standards)
+## Context budget
 
-Generic “core standards” playbooks are often long and stack-specific. For this monorepo, commands and gotchas live under **Cursor Cloud specific instructions** below and in **[CONTRIBUTING.md](CONTRIBUTING.md)**. If always-on rules grow, split domain rules into **`.cursor/rules/*.mdc`** (globs). **Cursor:** project-wide rules live in **`.cursor/index.mdc`** (YAML frontmatter with `alwaysApply: true`). **Claude Code:** optionally load a **`STANDARDS.md`** only when needed (e.g. *“When writing new code, read STANDARDS.md”*) to save context.
+Commands and gotchas live under **Repo reference** below and in **[CONTRIBUTING.md](CONTRIBUTING.md)**. If always-on rules grow, split into **`.cursor/rules/*.mdc`** (globs). **Cursor:** project-wide rules in `.cursor/index.mdc`. **Claude Code:** load `STANDARDS.md` only when needed.
 
-## Reference Documentation
+## Reference docs
 
-- **This repository:** **[ARCHITECTURE.md](ARCHITECTURE.md)**, **[CONTRIBUTING.md](CONTRIBUTING.md)**, **[GUARDRAILS.md](GUARDRAILS.md)**.
-- **Cursor:** `.cursor/index.mdc` (always-on rules); optional `.cursor/rules/*.mdc` (glob-scoped). Legacy `.cursorrules` is deprecated — see `.cursor/index.mdc`.
-- **Optional local files:** `NOTES.md` (short vendor-neutral project snapshot). For handoffs, keep notes local (e.g., a scratch file outside the repo) rather than committing `HANDOFF.md`.
-- **GitNexus:** skills under `.claude/skills/gitnexus/`; machine-oriented rules in the `gitnexus:start` … `gitnexus:end` block below.
+- **[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`.
+- **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.
 
 ## Changelog
 
 | Date | Version | Change |
 |------|---------|--------|
-| 2026-03-24 | 1.2.0 | Fixed gitnexus:start block duplication (was inlined in Reference Docs bullet). |
-| 2026-03-23 | 1.1.0 | Updated agent instructions (sections, references, Cursor layout). |
-| 2026-03-22 | 1.0.0 | Added structured agent header and changelog. |
+| 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. |
+| 2026-03-23 | 1.1.0 | Updated agent instructions, references, Cursor layout. |
+| 2026-03-22 | 1.0.0 | Initial structured header and changelog. |
 
 ---
 
 <!-- gitnexus:start -->
 # GitNexus — Code Intelligence
 
-This project is indexed by GitNexus as **GitNexus**. Use the GitNexus MCP tools to understand code, assess impact, and navigate safely. For current symbol stats, run `npx gitnexus analyze` and inspect `.gitnexus/meta.json`.
+Indexed as **GitNexus** (4325 symbols, 10556 relationships, 300 execution flows). Use MCP tools to understand code, assess impact, and navigate safely.
 
-> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
+> If any tool warns the index is stale, run `npx gitnexus analyze` first.
 
 ## Always Do
 
-- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
-- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
-- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
-- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
-- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.
+- **MUST run impact analysis before editing any symbol.** `gitnexus_impact({target: "symbolName", direction: "upstream"})` — report blast radius to the user.
+- **MUST run `gitnexus_detect_changes()` before committing** — verify only expected symbols and flows are affected.
+- **MUST warn the user** if impact returns HIGH or CRITICAL risk.
+- Explore unfamiliar code with `gitnexus_query({query: "concept"})` (process-grouped, ranked) instead of grepping.
+- Full context on a symbol: `gitnexus_context({name: "symbolName"})`.
 
 ## When Debugging
 
-1. `gitnexus_query({query: "<error or symptom>"})` — find execution flows related to the issue
-2. `gitnexus_context({name: "<suspect function>"})` — see all callers, callees, and process participation
-3. `READ gitnexus://repo/GitNexus/process/{processName}` — trace the full execution flow step by step
-4. For regressions: `gitnexus_detect_changes({scope: "compare", base_ref: "main"})` — see what your branch changed
+1. `gitnexus_query({query: "<error or symptom>"})` — find related execution flows
+2. `gitnexus_context({name: "<suspect function>"})` — callers, callees, process participation
+3. `READ gitnexus://repo/GitNexus/process/{processName}` — trace flow step by step
+4. Regressions: `gitnexus_detect_changes({scope: "compare", base_ref: "main"})`
 
 ## When Refactoring
 
-- **Renaming**: MUST use `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` first. Review the preview — graph edits are safe, text_search edits need manual review. Then run with `dry_run: false`.
-- **Extracting/Splitting**: MUST run `gitnexus_context({name: "target"})` to see all incoming/outgoing refs, then `gitnexus_impact({target: "target", direction: "upstream"})` to find all external callers before moving code.
-- After any refactor: run `gitnexus_detect_changes({scope: "all"})` to verify only expected files changed.
+- **Rename:** `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` first. Graph edits are safe; text_search edits need manual review.
+- **Extract/Split:** `gitnexus_context` (incoming/outgoing refs) then `gitnexus_impact` (upstream callers) before moving code.
+- **After any refactor:** `gitnexus_detect_changes({scope: "all"})` to verify scope.
 
 ## Never Do
 
-- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
-- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
-- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
-- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.
+- Edit a symbol without running `gitnexus_impact` first.
+- Ignore HIGH/CRITICAL risk warnings.
+- Rename with find-and-replace — use `gitnexus_rename`.
+- Commit without `gitnexus_detect_changes()`.
+- Add language-specific behavior to shared ingestion code (`gitnexus/src/core/ingestion/`) — use a `LanguageProvider` hook. Seeing `provider.mroStrategy === 'xxx'` or an import from `languages/xxx.ts` in shared code means stop and add a hook.
 
 ## Tools Quick Reference
 
-| Tool | When to use | Command |
+| Tool | When to use | Example |
 |------|-------------|---------|
+| `list_repos` | Discover indexed repos | `gitnexus_list_repos({})` |
 | `query` | Find code by concept | `gitnexus_query({query: "auth validation"})` |
 | `context` | 360-degree view of one symbol | `gitnexus_context({name: "validateUser"})` |
 | `impact` | Blast radius before editing | `gitnexus_impact({target: "X", direction: "upstream"})` |
 | `detect_changes` | Pre-commit scope check | `gitnexus_detect_changes({scope: "staged"})` |
 | `rename` | Safe multi-file rename | `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` |
 | `cypher` | Custom graph queries | `gitnexus_cypher({query: "MATCH ..."})` |
+| `api_impact` | Pre-change API route impact | `gitnexus_api_impact({route: "/api/users", method: "GET"})` |
+| `route_map` | Route → handler → consumer map | `gitnexus_route_map({})` |
+| `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"})` |
 
 ## Impact Risk Levels
 
 | Depth | Meaning | Action |
 |-------|---------|--------|
-| d=1 | WILL BREAK — direct callers/importers | MUST update these |
+| d=1 | WILL BREAK — direct callers/importers | MUST update |
 | d=2 | LIKELY AFFECTED — indirect deps | Should test |
 | d=3 | MAY NEED TESTING — transitive | Test if critical path |
 
@@ -118,87 +124,80 @@ This project is indexed by GitNexus as **GitNexus**. Use the GitNexus MCP tools
 
 | Resource | Use for |
 |----------|---------|
-| `gitnexus://repo/GitNexus/context` | Codebase overview, check index freshness |
+| `gitnexus://repo/GitNexus/context` | Codebase overview, index freshness |
 | `gitnexus://repo/GitNexus/clusters` | All functional areas |
 | `gitnexus://repo/GitNexus/processes` | All execution flows |
 | `gitnexus://repo/GitNexus/process/{name}` | Step-by-step execution trace |
 
 ## Self-Check Before Finishing
 
-Before completing any code modification task, verify:
 1. `gitnexus_impact` was run for all modified symbols
-2. No HIGH/CRITICAL risk warnings were ignored
-3. `gitnexus_detect_changes()` confirms changes match expected scope
-4. All d=1 (WILL BREAK) dependents were updated
+2. No HIGH/CRITICAL warnings were ignored
+3. `gitnexus_detect_changes()` confirms expected scope
+4. All d=1 dependents were updated
 
 ## Keeping the Index Fresh
 
-After committing code changes, the GitNexus index becomes stale. Re-run analyze to update it:
-
 ```bash
-npx gitnexus analyze
+npx gitnexus analyze              # basic refresh
+npx gitnexus analyze --embeddings # preserve embeddings
 ```
 
-If the index previously included embeddings, preserve them by adding `--embeddings`:
+Check `.gitnexus/meta.json` `stats.embeddings` (0 = none). Running without `--embeddings` deletes existing vectors.
 
-```bash
-npx gitnexus analyze --embeddings
-```
+> Claude Code: PostToolUse hook handles this after `git commit` and `git merge`.
 
-To check whether embeddings exist, inspect `.gitnexus/meta.json` — the `stats.embeddings` field shows the count (0 means no embeddings). **Running analyze without `--embeddings` will delete any previously generated embeddings.**
+## CLI Skills
 
-> Claude Code users: A PostToolUse hook handles this automatically after `git commit` and `git merge`.
-
-## CLI
-
-| Task | Read this skill file |
-|------|---------------------|
-| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
-| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
-| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
-| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
-| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
-| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
+| Task | Skill file |
+|------|-----------|
+| Architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
+| Blast radius / "What breaks?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
+| Debugging / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
+| Refactoring | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
+| Tools/resources/schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
+| CLI commands (index, status, clean, wiki) | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
 
 <!-- gitnexus:end -->
 
-## Cursor Cloud specific instructions
+## Repo reference
 
-### Repository structure
+### Packages
 
-This is a monorepo with two main products and supporting config packages:
-
-| Component | Path | Purpose |
-|-----------|------|---------|
-| **GitNexus CLI/Core** | `gitnexus/` | Main product — TypeScript CLI, indexing pipeline, MCP server. Published to npm. |
-| **GitNexus Web UI** | `gitnexus-web/` | React/Vite browser app — graph explorer + AI chat. Runs entirely in WASM. |
-| Claude Plugin | `gitnexus-claude-plugin/` | Static config for Claude marketplace (no build). |
-| Cursor Integration | `gitnexus-cursor-integration/` | Static config for Cursor editor (no build). |
-| SWE-bench Eval | `eval/` | Python evaluation harness (optional; needs Docker + LLM API keys). |
+| Package | Path | Purpose |
+|---------|------|---------|
+| **CLI/Core** | `gitnexus/` | TypeScript CLI, indexing pipeline, MCP server. Published to npm. |
+| **Web UI** | `gitnexus-web/` | React/Vite thin client. All queries via `gitnexus serve` HTTP API. |
+| **Shared** | `gitnexus-shared/` | Shared TypeScript types and constants. |
+| Claude Plugin | `gitnexus-claude-plugin/` | Static config for Claude marketplace. |
+| Cursor Integration | `gitnexus-cursor-integration/` | Static config for Cursor editor. |
+| Eval | `eval/` | Python evaluation harness (Docker + LLM API keys). |
 
 ### Running services
 
-- **CLI/Core**: `cd gitnexus && npm run dev` (tsx watch mode) or `npm run build && node dist/cli/index.js <command>`
-- **Web UI**: `cd gitnexus-web && npm run dev` (Vite on port 5173)
-- **Backend mode**: `cd <indexed-repo> && node /workspace/gitnexus/dist/cli/index.js serve` (HTTP API on port 3741 by default)
+```bash
+cd gitnexus && npm run dev                 # CLI: tsx watch mode
+cd gitnexus-web && npm run dev             # Web UI: Vite on port 5173
+npx gitnexus serve                         # HTTP API on port 4747 (from any indexed repo)
+```
 
 ### Testing
 
 **CLI / Core (`gitnexus/`)**
-- **Unit tests**: `cd gitnexus && npm test` (vitest, ~2000 tests)
-- **Integration tests**: `cd gitnexus && npm run test:integration` (vitest, ~1850 tests). Two LadybugDB file-locking tests (`lbug-core-adapter`, `search-core`) may fail in containerized environments due to `/tmp` locking limitations — this is a known environment issue, not a code bug.
-- **TypeScript check**: `cd gitnexus && npx tsc --noEmit`
+- `npm test` — full vitest suite (~2000 tests)
+- `npm run test:unit` — unit tests only
+- `npm run test:integration` — integration (~1850 tests). LadybugDB file-locking tests may fail in containers (known env issue).
+- `npx tsc --noEmit` — typecheck
 
 **Web UI (`gitnexus-web/`)**
-- **Unit tests**: `cd gitnexus-web && npm test` (vitest, ~200 tests)
-- **E2E tests**: `cd gitnexus-web && E2E=1 npx playwright test` (Playwright, 5 tests — requires `gitnexus serve` + `npm run dev` running)
-- **TypeScript check**: `cd gitnexus-web && npx tsc -b --noEmit`
+- `npm test` — vitest (~200 tests)
+- `npm run test:e2e` — Playwright (7 spec files; requires `gitnexus serve` + `npm run dev`)
+- `npx tsc -b --noEmit` — typecheck
 
-No separate lint command is configured; TypeScript strict checking serves as the primary static analysis.
+**Pre-commit hook** (`.husky/pre-commit`): formatting (prettier via lint-staged) + typecheck for staged packages. Tests do **not** run in pre-commit — CI only.
 
 ### Gotchas
 
-- `npm install` in `gitnexus/` triggers `prepare` (builds via `tsc`) and `postinstall` (patches tree-sitter-swift). Native tree-sitter bindings require `python3`, `make`, and `g++` to be present.
-- `tree-sitter-kotlin` and `tree-sitter-swift` are optional dependencies — install warnings for these are expected and non-blocking.
-- The Web UI uses `vite-plugin-wasm` and requires `Cross-Origin-Opener-Policy`/`Cross-Origin-Embedder-Policy` headers for `SharedArrayBuffer` (handled automatically by Vite dev server).
-- There is no ESLint/Prettier configuration in this repo.
+- `npm install` in `gitnexus/` triggers `prepare` (builds via `tsc`) and `postinstall` (patches tree-sitter-swift, builds tree-sitter-proto). Native bindings need `python3`, `make`, `g++`.
+- `tree-sitter-kotlin` and `tree-sitter-swift` are optional — install warnings expected.
+- ESLint configured via `eslint.config.mjs` (TS, React Hooks, unused-imports). No `npm run lint` script; use `npx eslint .`. Prettier runs via lint-staged. CI checks both in `ci-quality.yml`.

ARCHITECTURE.md

@@ -1,66 +1,365 @@
 # Architecture — GitNexus
 
-This repository is a **monorepo** with two main products: the **CLI / MCP package** (`gitnexus/`) and the **browser UI** (`gitnexus-web/`). Supporting folders ship editor integrations and plugins without changing the core graph engine.
+Monorepo: **CLI/MCP** (`gitnexus/`) + **browser UI** (`gitnexus-web/`).
 
 ## Repository layout
 
 | Path | Role |
 |------|------|
-| `gitnexus/` | Published npm package `gitnexus`: CLI, MCP server (stdio), local HTTP API for bridge mode, ingestion pipeline, LadybugDB graph, embeddings (optional). |
-| `gitnexus-web/` | Vite + React UI: in-browser indexing (WASM), graph visualization, optional connection to `gitnexus serve`. |
-| `.claude/`, `gitnexus-claude-plugin/`, `gitnexus-cursor-integration/` | Packaged **skills** and plugin metadata so agents discover the same workflows as documented in `AGENTS.md`. |
-| `eval/` | Evaluation harnesses and docs for benchmarking tool usage. |
-| `.github/` | CI workflows (quality, unit, integration, E2E) and composite actions. |
+| `gitnexus/` | npm package `gitnexus`: CLI, MCP server (stdio), HTTP API, ingestion pipeline, LadybugDB graph, embeddings. |
+| `gitnexus-web/` | Vite + React thin client: graph explorer + AI chat. All queries via `gitnexus serve` HTTP API. |
+| `gitnexus-shared/` | Shared TypeScript types and constants (consumed by CLI and Web). |
+| `.claude/`, `gitnexus-claude-plugin/`, `gitnexus-cursor-integration/` | Agent skills and plugin metadata. |
+| `eval/` | Evaluation harnesses for benchmarking tool usage. |
+| `.github/` | CI workflows + composite actions (`setup-gitnexus/`, `setup-gitnexus-web/`). |
 
 ## End-to-end flow: index → graph → tools
 
-1. **Ingestion** (`gitnexus analyze`)  
-   - Entry: `gitnexus/src/cli/analyze.ts` → `runPipelineFromRepo` in `gitnexus/src/core/ingestion/pipeline.ts`.  
-   - Walks the git working tree, parses supported languages via **Tree-sitter**, resolves imports/calls/inheritance, detects **communities** and **processes** (execution flows), and builds an in-memory **knowledge graph** (`gitnexus/src/core/graph/`).  
-   - Output is loaded into **LadybugDB** under **`.gitnexus/`** at the repo root (`lbug/`, `meta.json`, etc.). Optional **FTS** indexes and **embeddings** attach to the same store.  
-   - The repo is registered in **`~/.gitnexus/registry.json`** so MCP can find it from any working directory.
+1. **Ingestion** — `analyze.ts` → `runFullAnalysis` (`run-analyze.ts`) → `runPipelineFromRepo` (`pipeline.ts`). DAG of 12 phases builds a `KnowledgeGraph` in memory, then loads into LadybugDB under `.gitnexus/`. Repo registered in `~/.gitnexus/registry.json` for MCP discovery.
 
-2. **Persistence & metadata**  
-   - `gitnexus/src/storage/repo-manager.ts` — paths, registry, cleanup of legacy Kuzu artifacts.  
-   - `gitnexus/src/core/lbug/lbug-adapter.ts` — graph load, queries, embedding restore batches.
+2. **Persistence** — `repo-manager.ts` (paths, registry, KuzuDB cleanup). `lbug-adapter.ts` (graph load, queries, embedding batches).
 
-3. **Query & agents**  
-   - **MCP (stdio):** `gitnexus/src/cli/mcp.ts` → `startMCPServer` → `LocalBackend` (`gitnexus/src/mcp/local/local-backend.ts`) opens registered repos and serves **tools** from `gitnexus/src/mcp/tools.ts` and **resources** from `gitnexus/src/mcp/resources.ts`.  
-   - **Bridge HTTP:** `gitnexus/src/cli/serve.ts` → Express app in `gitnexus/src/server/api.ts` (CORS-limited) exposes REST + MCP-over-HTTP for the web UI.  
-   - **CLI tools (no MCP):** `gitnexus query`, `context`, `impact`, `cypher` in `gitnexus/src/cli/tool.ts` call the same backend for scripts and CI.
+3. **Query layer** — three interfaces to the same backend:
+   - **MCP (stdio):** `mcp.ts` → `LocalBackend` → tools (`tools.ts`) + resources (`resources.ts`)
+   - **HTTP bridge:** `serve.ts` → Express (`api.ts`, `mcp-http.ts`) for web UI
+   - **CLI direct:** `gitnexus query|context|impact|cypher` in `tool.ts`
 
-4. **Staleness**  
-   - `gitnexus/src/mcp/staleness.ts` compares indexed `lastCommit` to `HEAD` and surfaces hints when the graph is behind git.
+4. **Staleness** — `staleness.ts` compares indexed `lastCommit` to `HEAD`, surfaces hints.
 
-## MCP tools (summary)
+## MCP tools
 
 | Tool | Purpose |
 |------|---------|
-| `list_repos` | Discover indexed repositories when more than one is registered. |
-| `query` | Natural-language / keyword search over the graph (hybrid BM25 + optional vectors). |
-| `cypher` | Ad hoc **Cypher** against the schema (see resource `gitnexus://repo/{name}/schema`). |
-| `context` | Callers, callees, processes for one symbol (with disambiguation). |
-| `impact` | Blast radius (upstream/downstream) with depth and risk summary. |
-| `detect_changes` | Map git diffs to affected symbols and processes. |
-| `rename` | Graph-assisted rename with `dry_run` preview (`graph` vs `text_search` confidence). |
+| `list_repos` | Discover indexed repos |
+| `query` | Hybrid BM25 + vector search over the graph |
+| `cypher` | Ad hoc Cypher against the schema |
+| `context` | Callers, callees, processes for one symbol |
+| `impact` | Blast radius (upstream/downstream) with risk summary |
+| `detect_changes` | Map git diffs to affected symbols and processes |
+| `rename` | Graph-assisted multi-file rename with `dry_run` preview |
+| `api_impact` | Pre-change impact report for an API route handler |
+| `route_map` | API route → handler → consumer mappings |
+| `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 |
 
 ## Where to change what
 
-| If you are changing… | Start in… |
-|----------------------|-----------|
-| CLI commands / flags | `gitnexus/src/cli/` (`index.ts`, per-command modules). |
-| Parsing or graph construction | `gitnexus/src/core/ingestion/` (pipeline, processors, resolvers, type-extractors). |
-| Graph schema / DB access | `gitnexus/src/core/lbug/` (`schema.ts`, `lbug-adapter.ts`), `gitnexus/src/mcp/core/lbug-adapter.ts` if MCP-specific. |
-| MCP protocol, tools, resources | `gitnexus/src/mcp/server.ts`, `tools.ts`, `resources.ts`. |
-| Search ranking | `gitnexus/src/core/search/` (BM25, hybrid fusion). |
-| Embeddings | `gitnexus/src/core/embeddings/`, phases in `analyze.ts`. |
-| Wiki generation | `gitnexus/src/core/wiki/`. |
-| Web UI behavior | `gitnexus-web/src/` (components, workers, graph client). |
-| CI | `.github/workflows/*.yml`, `.github/actions/setup-gitnexus/`. |
+| Concern | Start in |
+|---------|----------|
+| CLI commands/flags | `src/cli/` (`index.ts`, per-command modules) |
+| 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` |
+| Search ranking | `src/core/search/` (BM25, hybrid fusion) |
+| Embeddings | `src/core/embeddings/` + `src/core/run-analyze.ts` |
+| Wiki generation | `src/core/wiki/` |
+| Language support | `src/core/ingestion/languages/` + `tree-sitter-queries.ts` + `gitnexus-shared/src/languages.ts` |
+| Import resolution | `src/core/ingestion/import-processor.ts` + `import-resolvers/configs/` + `model/resolution-context.ts` |
+| Call resolution/MRO | `src/core/ingestion/call-processor.ts` + `model/resolve.ts` |
+| Type extraction | `src/core/ingestion/type-extractors/` |
+| Worker pool | `src/core/ingestion/workers/` |
+| Web UI | `gitnexus-web/src/` |
+| CI | `.github/workflows/*.yml`, `.github/actions/` |
+
+> Paths above are relative to `gitnexus/` unless they start with `gitnexus-web/` or `.github/`.
+
+---
+
+## Pipeline Phase DAG
+
+12 phases defined in `gitnexus/src/core/ingestion/pipeline-phases/`, each with explicit `deps` and typed output.
+
+```
+scan → structure → [markdown, cobol] → parse → [routes, tools, orm]
+  → crossFile → mro → communities → processes
+```
+
+| Phase | File | Deps | Output |
+|-------|------|------|--------|
+| `scan` | `scan.ts` | (root) | File paths + sizes |
+| `structure` | `structure.ts` | `scan` | File/Folder nodes, CONTAINS edges, `allPathSet` |
+| `markdown` | `markdown.ts` | `structure` | Section nodes, cross-link edges from .md/.mdx |
+| `cobol` | `cobol.ts` | `structure` | COBOL program/paragraph/section nodes (regex, no tree-sitter) |
+| `parse` | `parse.ts` + `parse-impl.ts` | `structure`, `markdown`, `cobol` | Symbol nodes, IMPORTS/CALLS/EXTENDS edges, extracted routes/tools/ORM queries |
+| `routes` | `routes.ts` | `parse` | Route nodes + HANDLES_ROUTE edges (Next.js, Expo, PHP, decorators) |
+| `tools` | `tools.ts` | `parse` | Tool nodes + HANDLES_TOOL edges |
+| `orm` | `orm.ts` | `parse` | QUERIES edges (Prisma, Supabase) |
+| `crossFile` | `cross-file.ts` + `cross-file-impl.ts` | `parse`, `routes`, `tools`, `orm` | Cross-file type propagation in topological import order |
+| `mro` | `mro.ts` | `crossFile`, `structure` | METHOD_OVERRIDES + METHOD_IMPLEMENTS edges |
+| `communities` | `communities.ts` | `mro`, `structure` | Community nodes + MEMBER_OF edges (Leiden algorithm) |
+| `processes` | `processes.ts` | `communities`, `routes`, `tools`, `structure` | Process nodes + STEP_IN_PROCESS edges |
+
+**Non-phase files in the same directory:** `parse-impl.ts`, `cross-file-impl.ts` (implementation), `wildcard-synthesis.ts` (whole-module import expansion), `orm-extraction.ts` (sequential ORM fallback), `types.ts`, `runner.ts`, `index.ts`.
+
+### DAG runner
+
+`runner.ts` — static phase graph, no plugins, compile-time type safety.
+
+1. **Validation** — Kahn's topological sort. Rejects on: duplicate names, missing deps, cycles (DFS traces the concrete cycle path, e.g., `A -> B -> C -> A`, plus count of transitively blocked dependents).
+
+2. **Execution** — sequential in topological order. Each phase receives:
+   - `ctx: PipelineContext` — shared mutable `KnowledgeGraph`, `repoPath`, progress callback, options
+   - `deps: ReadonlyMap<string, PhaseResult>` — **declared deps only** (runner filters the results map to prevent hidden coupling)
+
+3. **Error handling** — wraps phase errors with the phase name, emits terminal `error` progress event, swallows progress handler errors to preserve the original cause.
+
+4. **Timing** — per-phase `durationMs` in `PhaseResult`, dev-mode console logging.
+
+**Design patterns:**
+- **Single graph accumulator** — all phases mutate the same `KnowledgeGraph` in `ctx`; the graph is the primary output.
+- **Typed phase access** — `getPhaseOutput<T>(deps, 'name')` for type-safe upstream results.
+- **Binding accumulator lifecycle** — created in `parse`, disposed by `crossFile` (in `finally`). No other phase should take ownership.
+- **Skippable phases** — `skipGraphPhases` omits MRO/communities/processes (faster tests). `skipWorkers` forces sequential parsing.
+
+### How to add a new phase
+
+1. Create `pipeline-phases/my-phase.ts` with a `PipelinePhase<MyOutput>` (name, deps, execute)
+2. Export from `pipeline-phases/index.ts`
+3. Add to `buildPhaseList()` in `pipeline.ts`
+
+```typescript
+import type { PipelinePhase, PhaseResult } from './types.js';
+import { getPhaseOutput } from './types.js';
+import type { ParseOutput } from './parse.js';
+
+export interface MyPhaseOutput { /* ... */ }
+
+export const myPhase: PipelinePhase<MyPhaseOutput> = {
+  name: 'myPhase',
+  deps: ['parse'],
+  async execute(ctx, deps) {
+    const { allPaths } = getPhaseOutput<ParseOutput>(deps, 'parse');
+    // ... write to ctx.graph ...
+    return { /* typed output */ };
+  },
+};
+```
+
+---
+
+## Call-Resolution DAG
+
+Typed 6-stage pipeline in `call-processor.ts` (inside the `parse` phase) that resolves method/function calls and emits CALLS edges. Language behavior plugs in at two `LanguageProvider` hook points (stages 3–4); shared code names no languages. Scope: call resolution only — import resolution, type extraction, heritage, and symbol-table population live in other phases.
+
+### Stages
+
+```
+extract-call ──▶ classify-form ──▶ infer-receiver ──▶ select-dispatch ──▶ resolve-target ──▶ emit-edge
+     (1)              (2)            (3)  [hook]       (4)  [hook]         (5)                 (6)
+```
+
+| Stage | Produces | Location |
+|-------|----------|----------|
+| **extract-call** | `ExtractedCallSite` (name, form, receiver, argCount) | `call-extractors/` (per-language); runs in worker |
+| **classify-form** | callForm (`free`/`member`/`constructor`) + arity | `call-analysis.ts` → `inferCallForm`; shared, runs in worker |
+| **infer-receiver** | `ReceiverEnriched` (receiver type finalized) | `call-processor.ts`; shared default chain, then `inferImplicitReceiver` hook |
+| **select-dispatch** | `DispatchDecision` (primary, fallback, ancestryView) | `selectDispatch` hook, falls back to shared default |
+| **resolve-target** | `TieredCandidates` | `model/resolve.ts` → `lookupMethodByOwnerWithMRO` (MRO walk) |
+| **emit-edge** | CALLS edge in graph | `call-processor.ts`; writes edge with confidence tier |
+
+### Provider hooks
+
+Both hooks are optional on `LanguageProvider`. Ruby is the only current implementer.
+
+**`inferImplicitReceiver`** — called after shared infer-receiver defaults. Returns `ImplicitReceiverOverride | null`.
+
+| | |
+|---|---|
+| Inputs | `calledName`, `callForm`, `receiverName`, `receiverTypeName`, `callNode` (AST), `filePath` |
+| Non-null fields | `callForm`, `receiverName`, `receiverTypeName` (required); `receiverSource: 'implicit-self'` (fixed); `hint?` (opaque, passed to `selectDispatch`) |
+| Null | Keep existing `ReceiverEnriched` state |
+
+**`selectDispatch`** — called after infer-receiver (including hook). Returns `DispatchDecision | null`; null uses shared default (constructor → `primary:'constructor'`; typed receiver → `primary:'owner-scoped'`; else → `primary:'free'`).
+
+| | |
+|---|---|
+| Inputs | `calledName`, `callForm`, `receiverName`, `receiverTypeName`, `receiverSource`, `hint` |
+| Non-null fields | `primary: 'owner-scoped' \| 'free' \| 'constructor'`; `fallback?: 'free-arity-narrowed'`; `ancestryView?: 'instance' \| 'singleton'`; `hint?` |
+
+**`DispatchDecision` field semantics:**
+- `primary: 'owner-scoped'` — MRO walk from receiver's type; used when receiver type is known.
+- `fallback: 'free-arity-narrowed'` — after owner-scoped miss, search free-call candidates by arity only (Ruby uses this for implicit-self calls that miss their owner's MRO).
+- `ancestryView: 'singleton'` — walk singleton/class ancestry instead of instance ancestry (Ruby `def self.foo` bodies, so `extend`-ed methods are found).
+
+### Adding language behavior
+
+1. **Implicit receivers** — implement `inferImplicitReceiver`: return null if call already has a receiver; otherwise use `findEnclosingClassInfo` (`ast-helpers.ts`) to find the enclosing context, return `ImplicitReceiverOverride` with `receiverSource: 'implicit-self'`, and optionally set `hint` for `selectDispatch`.
+2. **Custom dispatch** — implement `selectDispatch`: inspect `receiverSource` and `hint`, return `DispatchDecision` with `primary`, optional `fallback`, optional `ancestryView`; return null to keep shared defaults.
+3. **MRO strategy** — confirm `mroStrategy` is `'first-wins'`, `'c3'`, `'ruby-mixin'`, or `'none'`; consumed by `lookupMethodByOwnerWithMRO`.
+
+**Ruby example** (`languages/ruby.ts` + `utils/ruby-self-call.ts`): `inferImplicitReceiver` rewrites bare-identifier calls to `self.method` and sets `hint` to `'instance'`/`'singleton'`; `selectDispatch` uses hint for `ancestryView` and adds `fallback: 'free-arity-narrowed'` for implicit-self calls.
+
+### Code references
+
+| Module | Purpose |
+|--------|---------|
+| `core/ingestion/call-types.ts` | DAG types: `ReceiverEnriched`, `DispatchDecision`, `ImplicitReceiverOverride` |
+| `core/ingestion/language-provider.ts` | Hook signatures: `inferImplicitReceiver`, `selectDispatch` |
+| `core/ingestion/call-processor.ts` | `processCalls`: stages 3–6 |
+| `core/ingestion/model/resolve.ts` | `lookupMethodByOwnerWithMRO`: stage 5 MRO walk |
+| `core/ingestion/languages/ruby.ts` | Both hooks + `mroStrategy: 'ruby-mixin'` |
+| `core/ingestion/utils/ruby-self-call.ts` | Bare-call rewrite for `inferImplicitReceiver` |
+
+---
+
+## Language-agnostic graph feeding
+
+16 languages → single unified graph. Four abstraction layers:
+
+```
+ Unified Graph Schema (44 node types, 21 relationship types)
+           ↑
+ Unified Resolution (3-tier name lookup + MRO walk)
+           ↑
+ Language Providers (import semantics, type config, export checker, MRO strategy)
+           ↑
+ Tree-Sitter Queries (per-language S-expressions, unified capture tags)
+```
+
+### Language providers
+
+Each language implements `LanguageProvider` (`language-provider.ts`). Key fields:
+
+| Field | Purpose |
+|-------|---------|
+| `id`, `extensions` | Language identity and file matching |
+| `treeSitterQueries` | S-expression queries for AST extraction |
+| `importSemantics` | `named` / `wildcard-leaf` / `wildcard-transitive` / `namespace` |
+| `importResolver` | Language-specific path → file resolution |
+| `exportChecker` | Public/exported symbol detection |
+| `typeConfig` | Type annotation extraction rules |
+| `mroStrategy` | `first-wins` / `c3` / `none` |
+
+16 providers in `languages/index.ts` via `satisfies Record<SupportedLanguages, LanguageProvider>` — missing a language is a compile error.
+
+### Unified capture tags
+
+Per-language tree-sitter queries use different AST node names but produce the **same semantic capture tags**: `@definition.class`, `@definition.function`, `@call.name`, `@import.source`, `@heritage.extends`. Downstream extraction needs no language branching. Defined in `tree-sitter-queries.ts`.
+
+### Import resolution
+
+Per-language import resolution uses the **configs + factory** pattern (like call/method/class extractors). Each language declares an `ImportResolutionConfig` in `import-resolvers/configs/`, listing an ordered chain of `ImportResolverStrategy` functions. `createImportResolver()` (in `resolver-factory.ts`) composes them: first non-null result wins. Low-level helpers shared across strategies live alongside the configs in `import-resolvers/` (e.g. `go.ts`, `rust.ts`, `python.ts`).
+
+Unified 3-tier algorithm (`model/resolution-context.ts`), per-language `importSemantics` controls which tier activates:
+
+| Tier | Confidence | Mechanism |
+|------|-----------|-----------|
+| 1 — same-file | 0.95 | Symbol table for caller's file |
+| 2 — import-scoped | 0.9 | `NamedImportMap` chains (named) or all files in `importMap` (wildcard) |
+| 3 — global | 0.5 | O(1) index lookups: class, impl, callable. Fallback only |
+
+| Import strategy | Languages | Behavior |
+|----------------|-----------|----------|
+| `named` | TS, JS, Java, C#, Rust, PHP, Kotlin | Only explicitly imported names visible |
+| `wildcard-leaf` | Go, Ruby, Swift, Dart | Whole-package import, no transitive re-exports |
+| `wildcard-transitive` | C, C++ | `#include` closure chains through re-exports |
+| `namespace` | Python | Module aliases resolved at call site |
+
+### Chunked parse-and-resolve
+
+`parse` processes files in ~20 MB byte-budget chunks to bound memory. Per chunk:
+1. Worker pool dispatches files (or sequential fallback via `skipWorkers`)
+2. Each worker: detect language → load grammar → run queries → return unified `ParseWorkerResult`
+3. Synthesize wildcard bindings (`wildcard-synthesis.ts`)
+4. Resolve imports and heritage
+5. Collect `BindingAccumulator` entries for cross-file propagation
+
+Workers: `workers/worker-pool.ts`, `workers/parse-worker.ts`.
+
+### Heritage and MRO
+
+All languages emit unified `ExtractedHeritage` (child, parent, `EXTENDS`/`IMPLEMENTS`). MRO phase walks the heritage graph using per-language strategy:
+- **`first-wins`** — Java, C#, C++, TS, Ruby, Go
+- **`c3`** — Python (C3 linearization)
+- **`none`** — single-inheritance languages
+
+Unified walk: `lookupMethodByOwnerWithMRO()` in `model/resolve.ts`.
+
+---
+
+## Full analysis flow
+
+`runFullAnalysis` in `run-analyze.ts` orchestrates everything around the pipeline:
+
+```
+CLI (analyze.ts) → runFullAnalysis(repoPath, options, callbacks)
+  1. Early exit if lastCommit == HEAD (unless --force)     [0%]
+  2. Cache existing embeddings from prior index             [0%]
+  3. runPipelineFromRepo() → KnowledgeGraph                [0-60%]
+  4. Clean up legacy KuzuDB files                          [60%]
+  5. initLbug() → loadGraphToLbug() via CSV streaming      [60-85%]
+  6. Create FTS indexes (File, Function, Class, Method...) [85-90%]
+  7. Restore cached embeddings (batch insert)              [88%]
+  8. Generate new embeddings if --embeddings               [90-98%]
+  9. Save metadata + register repo + update .gitignore     [98-100%]
+ 10. Generate AI context files (AGENTS.md, CLAUDE.md)      [100%]
+```
+
+**Options:** `--force` (rebuild regardless), `--embeddings` (opt-in, skipped if >50k nodes), `--skipGit`, `--noStats`.
+
+## Storage
+
+```
+<repo>/.gitnexus/
+  ├── lbug           # LadybugDB database
+  ├── lbug.wal       # Write-ahead log
+  ├── lbug.lock      # Single-writer lock
+  └── meta.json      # lastCommit, indexedAt, stats
+
+~/.gitnexus/
+  └── registry.json  # Global repo registry (MCP discovery)
+```
+
+Managed by `repo-manager.ts`.
+
+## LadybugDB schema
+
+Defined in `lbug/schema.ts`. Separate node tables per type, single `CodeRelation` table.
+
+**Node tables:** File, Folder, Function, Class, Interface, Method, Constructor, CodeElement, Struct, Enum, Macro, Typedef, Union, Namespace, Trait, Impl, TypeAlias, Const, Static, Property, Record, Delegate, Annotation, Template, Module, Community, Process, Route, Tool, Section, Embedding.
+
+**Relation types** (`CodeRelation.type`): CONTAINS, DEFINES, CALLS, IMPORTS, EXTENDS, IMPLEMENTS, HAS_METHOD, HAS_PROPERTY, ACCESSES, METHOD_OVERRIDES, METHOD_IMPLEMENTS, MEMBER_OF, STEP_IN_PROCESS, HANDLES_ROUTE, FETCHES, HANDLES_TOOL, ENTRY_POINT_OF.
+
+## Embeddings and search
+
+**Embeddings** (`src/core/embeddings/`): Snowflake arctic-embed-xs (384D). Embeddable: File, Function, Class, Method, Interface. Incremental via SHA1 content hash. Separate `Embedding` table.
+
+**Search** (`src/core/search/`): Hybrid BM25 + semantic vector, merged via Reciprocal Rank Fusion (K=60).
+
+## Known limitations
+
+### Overloaded method resolution
+
+Node IDs use arity suffix (`#<paramCount>`): `Method:file:Class.method#1` vs `#2`.
+
+**Same-arity disambiguation:** type-hash suffix `~type1,type2` when collision detected and type annotations present. Languages without types (Python, Ruby, JS) use arity-only. TS/JS overload signatures excluded (collapse to implementation body). See #651.
+
+**C++ const-qualified:** `$const` suffix after type-hash when non-const collision exists: `Method:file:Container.begin#0$const`.
+
+**Generic/template types:** type-hash uses `rawType` (full AST text including generics): `~vector<int>` vs `~vector<std::string>`.
+
+**ID stability:** collision-only tags mean IDs change when overloads are added. `save#1` becomes `save#1~int` when `save(String)` is added.
+
+**Variadic matching:** confidence 0.7 when one side is variadic and the other has fixed count.
+
+**METHOD_IMPLEMENTS confidence tiering:**
+
+| Match quality | Confidence |
+|---|---|
+| Exact parameter types match | 1.0 |
+| Arity match, types unavailable | 1.0 |
+| Variadic vs fixed | 0.7 |
+| Insufficient info | 0.7 |
 
 ## Related docs
 
-- [RUNBOOK.md](RUNBOOK.md) — operational commands and recovery.  
-- [GUARDRAILS.md](GUARDRAILS.md) — safety boundaries for humans and agents.  
-- [TESTING.md](TESTING.md) — how to run tests.  
-- `AGENTS.md` / `CLAUDE.md` — agent workflows and tool usage expectations for **this** repo when indexed by GitNexus.
+- [MIGRATION.md](MIGRATION.md) — breaking changes and migration guidance
+- [RUNBOOK.md](RUNBOOK.md) — operational commands and recovery
+- [GUARDRAILS.md](GUARDRAILS.md) — safety boundaries for humans and agents
+- [TESTING.md](TESTING.md) — how to run tests
+- `AGENTS.md` / `CLAUDE.md` — agent workflows and tool usage

CHANGELOG.md

@@ -10,6 +10,19 @@ All notable changes to GitNexus will be documented in this file.
 - Added automatic cleanup of stale KuzuDB index files
 - LadybugDB v0.15 requires explicit VECTOR extension loading for semantic search
 
+## [1.5.3] - 2026-04-01
+
+### Added
+
+- **TypeScript/JavaScript MethodExtractor config** — shared extraction config covering abstract methods, visibility modifiers, async/override keywords, decorators, rest/optional/destructured parameters, and return types (#588) — @compound-ai
+
+### Fixed
+
+- **Azure OpenAI compatibility** — use `max_completion_tokens` instead of deprecated `max_tokens` (newer models reject `max_tokens`); skip `temperature` for Azure provider (some models reject non-default values) (#618)
+- **Simplified Azure interactive setup** — 3 prompts (endpoint, deployment, key) instead of 7 (#618)
+- **Wiki HTML viewer script injection** — escape `</script>` in embedded JSON so LLM-generated markdown no longer breaks the viewer (#618)
+- Ensure import rewrites survive npm publish lifecycle
+
 ## [1.4.0] - 2026-03-13
 
 ### Added

CLAUDE.md

@@ -1,10 +1,10 @@
-<!-- version: 1.2.0 -->
+<!-- version: 1.3.0 -->
 <!--
   Metadata: version, last reviewed, scope, model policy, reference docs, changelog.
   Last updated: 2026-03-22
 -->
 
-Last reviewed: 2026-03-24
+Last reviewed: 2026-04-13
 
 **Project:** GitNexus · **Environment:** dev · **Maintainer:** repository maintainers (see GitHub)
 
@@ -35,12 +35,14 @@ If always-on instructions grow, load deep conventions via conditional reads (e.g
 ## Reference Documentation
 
 - **This repository:** [AGENTS.md](AGENTS.md) (Cursor + monorepo notes), [ARCHITECTURE.md](ARCHITECTURE.md), [CONTRIBUTING.md](CONTRIBUTING.md), [GUARDRAILS.md](GUARDRAILS.md).
+- **Call-resolution DAG:** See ARCHITECTURE.md § Call-Resolution DAG. Shared pipeline code in `gitnexus/src/core/ingestion/` must not name languages — use `LanguageProvider` hooks instead (see AGENTS.md).
 - **GitNexus:** `.claude/skills/gitnexus/`; MCP and indexed-repo rules live only in [AGENTS.md](AGENTS.md) (`gitnexus:start` … `gitnexus:end`). See **GitNexus rules** below.
 
 ## Changelog
 
 | Date | Version | Change |
 |------|---------|--------|
+| 2026-04-13 | 1.3.0 | Updated GitNexus index stats after DAG refactor. |
 | 2026-03-24 | 1.2.0 | Removed duplicated gitnexus:start block and scope table; replaced with pointers to AGENTS.md. |
 | 2026-03-23 | 1.1.0 | Updated agent instructions to match AGENTS.md. |
 | 2026-03-22 | 1.0.0 | Added structured header and changelog. |
@@ -49,4 +51,4 @@ If always-on instructions grow, load deep conventions via conditional reads (e.g
 
 ## GitNexus rules
 
-GitNexus MCP rules are in the `<!-- gitnexus:start -->` … `<!-- gitnexus:end -->` block in **[AGENTS.md](AGENTS.md)** — load that section when working with MCP tools or the graph index.
+See the `<!-- gitnexus:start --> … <!-- gitnexus:end -->` block in **[AGENTS.md](AGENTS.md)** for the canonical MCP tools, impact analysis rules, and index instructions.

CONTRIBUTING.md

@@ -21,30 +21,127 @@ This project uses the [PolyForm Noncommercial License 1.0.0](https://polyformpro
 ## Branch and pull requests
 
 - Use short-lived branches off the default branch of the repo you are targeting.
-- Prefer **conventional commits** (short prefix + description), for example:
-
-  ```text
-  feat: add graph export option
-  fix: correct MCP tool schema for query
-  test: cover cluster merge edge case
-  docs: clarify analyze flags
-  ```
-
-- **PR title:** `[area] Short description` (e.g. `[cli] Fix index refresh race`).
+- **PR titles MUST follow the conventional-commit format** — `pr-labeler.yml` enforces this on every PR and auto-applies the matching label so release notes group the change correctly.
 - **PR description:** what changed, why, how to verify (commands), and any risk or rollback notes.
 
+### Pull request titles
+
+Format: `<type>[(scope)][!]: <subject>`
+
+Allowed types and the release-notes section each one lands in (defined in `.github/release.yml`):
+
+| Type | Label applied | Release-notes section |
+|------|---------------|-----------------------|
+| `feat` | `enhancement` | 🚀 Features |
+| `fix` | `bug` | 🐛 Bug Fixes |
+| `perf` | `performance` | 🏎️ Performance |
+| `refactor` | `refactor` | 🔄 Refactoring |
+| `test` | `test` | 🧪 Tests |
+| `ci` | `ci` | 👷 CI/CD |
+| `build` / `deps` | `dependencies` | 📦 Dependencies |
+| `docs` | `documentation` | (grouped under Other Changes unless a Docs section is added) |
+| `chore` / `revert` | `chore` | (excluded from release notes) |
+
+Append `!` to the type (e.g. `feat(api)!: drop /v1 endpoint`) or include `BREAKING CHANGE:` in the PR body to flag a breaking change — the labeler then adds the `breaking` label and the 💥 Breaking Changes section is rendered first.
+
+Examples:
+
+```text
+feat(web): add smart chat scroll
+fix(extractors): resolve silent contract mis-resolution
+perf: avoid O(n²) traversal in heritage walker
+chore(deps): bump vitest to 3.0.0
+ci: standardize workflow concurrency
+```
+
+Commits within a PR may use any style — only the **merged PR title** shows up in release notes, so that's the one the convention applies to.
+
 ## Before you open a PR
 
 - [ ] Tests pass for the packages you touched (`gitnexus` and/or `gitnexus-web`).
 - [ ] Typecheck passes: `npx tsc --noEmit` in `gitnexus/` and `npx tsc -b --noEmit` in `gitnexus-web/`.
 - [ ] No secrets, tokens, or machine-specific paths committed.
 - [ ] Documentation updated if behavior or public CLI/MCP contract changes.
-- [ ] Pre-commit hook runs clean (`.husky/pre-commit` — typecheck + unit tests for staged packages).
+- [ ] Pre-commit hook runs clean (`.husky/pre-commit` — formatting via lint-staged + typecheck for staged packages; tests run in CI only).
 
 ## Code review
 
 Maintainers may request changes for correctness, tests, performance, or consistency with existing patterns. Keeping diffs focused makes review faster.
 
+## GitHub Actions — Concurrency Convention
+
+Every workflow under `.github/workflows/` MUST declare a top-level `concurrency:` block using this convention:
+
+- **Group key** starts with `${{ github.workflow }}` so no two workflows can collide on the same group name. The discriminator that follows is chosen per event shape:
+  - Branch/tag scope: `${{ github.workflow }}-${{ github.ref }}`
+  - 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).
+  - **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:**
+
+  | Event | `cancel-in-progress` | Why |
+  |-------|----------------------|-----|
+  | `pull_request` CI run | `true` | New push supersedes old run |
+  | `push` to `main` | `false` | Every main commit gets validated |
+  | Tag push (`v*` publish) | `false` | Never cancel mid-publish |
+  | `push` to `main` for release-candidate | `false` | Never cancel mid-RC publish |
+  | `workflow_dispatch` (release/publish) | `false` | Manual runs are intentional |
+  | `workflow_run` (sticky-comment reports) | `false` | Serialize, don't race |
+  | Per-PR bot workflows (`@claude`, review) | `false` | Serialize comments per PR |
+  | PR-meta re-checks (pr-description-check) | `true` | Cheap, latest wins |
+  | Single-slot utilities (triage sweep) | `true` | Latest dispatch supersedes |
+
+- For workflows that serve multiple events at once (e.g. `ci.yml` handles `pull_request`, `push`, and `workflow_call`), make `cancel-in-progress` event-aware:
+
+  ```yaml
+  concurrency:
+    group: ${{ github.workflow }}-${{ github.ref }}
+    cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+  ```
+
+- When adding a new workflow, copy the concurrency block from an existing workflow of the same event shape.
+
 ## AI-assisted contributions
 
 If you use coding agents, follow project context files (e.g. `AGENTS.md`, `CLAUDE.md`) and avoid drive-by refactors unrelated to the issue. Prefer incremental, test-backed changes.
+
+## Releases
+
+Two publish workflows ship `gitnexus` to npm:
+
+- **Stable** (`.github/workflows/publish.yml`) — triggered by pushing any `v*`
+  tag. Publishes to the `latest` dist-tag with a changelog-backed GitHub
+  release. Maintainers are expected to tag from `main` as a convention; the
+  workflow itself does not enforce branch reachability.
+- **Release Candidate** (`.github/workflows/release-candidate.yml`) — runs on
+  every push to `main` (typically a merged PR) plus manual dispatch. Docs-only
+  changes are skipped via `paths-ignore`. Publishes to the `rc` dist-tag with
+  version `X.Y.Z-rc.N` and a GitHub prerelease, where:
+  - `X.Y.Z` is selected automatically. On push (and on dispatch with
+    `bump: auto`, the default) the workflow **continues the active rc cycle**:
+    if the registry already has `X.Y.Z-rc.*` versions with `X.Y.Z` > current
+    `latest`, it reuses the highest such base; otherwise it patch-bumps
+    from `latest`. Dispatching with `bump: patch|minor|major` **resets**
+    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`.
+
+  Idempotency: the workflow pushes an `rc/<HEAD_SHA>` marker tag and a
+  `v<RC>` release tag **atomically, before** calling `npm publish`. The guard
+  refuses to re-run once the marker exists, so a post-publish failure will
+  not mint a duplicate rc for the same commit. The `v<RC>` tag points at a
+  detached release commit whose `package.json` matches the npm tarball
+  exactly (traceable releases). Recovery after a partial failure:
+
+  ```bash
+  git push --delete origin rc/<HEAD_SHA> v<RC>
+  # then redispatch the workflow with force: true
+  ```
+
+The rc workflow never moves `latest`. To verify after a change, inspect dist-tags:
+
+```bash
+npm view gitnexus dist-tags
+```

Dockerfile

@@ -0,0 +1,36 @@
+ARG BUILDPLATFORM
+ARG TARGETPLATFORM
+
+FROM --platform=$BUILDPLATFORM node:22-alpine AS builder
+
+WORKDIR /app
+
+COPY gitnexus-shared/package.json gitnexus-shared/package-lock.json ./gitnexus-shared/
+RUN npm ci --prefix gitnexus-shared
+
+COPY gitnexus-shared ./gitnexus-shared
+RUN npm run build --prefix gitnexus-shared
+
+COPY gitnexus/package.json ./gitnexus/package.json
+COPY gitnexus-web/package.json gitnexus-web/package-lock.json ./gitnexus-web/
+RUN npm ci --prefix gitnexus-web
+
+COPY gitnexus-web ./gitnexus-web
+RUN npm run build --prefix gitnexus-web
+
+FROM node:22-alpine AS runtime
+
+RUN apk add --no-cache curl
+
+WORKDIR /app
+
+COPY --from=builder /app/gitnexus-web/dist ./dist
+COPY docker-server.mjs ./docker-server.mjs
+
+RUN chown -R node:node /app
+
+USER node
+
+EXPOSE 4173
+
+CMD ["node", "docker-server.mjs"]

GUARDRAILS.md

@@ -1,72 +1,69 @@
-# Guardrails — GitNexus (repo + agents)
+# Guardrails — GitNexus
 
-Rules for **human contributors** and **AI agents** working on this codebase or publishing artifacts. These complement `AGENTS.md` / `CLAUDE.md` (which focus on GitNexus-in-GitNexus workflows).
+Rules for **human contributors** and **AI agents**. Complements `AGENTS.md` (workflows) and `CONTRIBUTING.md` (PR process).
 
-## Scope (typical agent session)
+## Scope (least privilege)
 
-When automating changes in this repository, treat scope as **least privilege**:
+- **Read:** Source, tests, docs, public config as needed.
+- **Write:** Only files required for the fix or feature; no unrelated formatting or refactors.
+- **Execute:** Tests, typecheck, documented CLI commands. No destructive commands on user data without approval.
+- **Off-limits:** Other people's machines, production deployments you don't own, credentials you lack permission to use.
 
-- **Read:** Source, tests, docs, public config as needed for the task.  
-- **Write:** Only files required for the requested fix or feature; avoid unrelated formatting or refactors.  
-- **Execute:** Tests, typecheck, and documented CLI commands; do not run destructive commands on user data outside the repo without explicit approval.  
-- **Off-limits:** Other people’s machines, production deployments you don’t own, and credentials you didn’t receive permission to use.
-
-Adjust explicitly if the maintainer defines a different scope for a task.
+Maintainer may widen scope per task.
 
 ---
 
 ## Non-negotiables
 
-1. **Never commit secrets** — API keys, tokens, `.env` with real values, private URLs, or session cookies. Use `.env.example` with placeholders only.  
-2. **Never rename symbols with blind find-and-replace** when working in a GitNexus-indexed project — use the **`rename` MCP tool** with **`dry_run: true` first**, then review `graph` vs `text_search` edits. (There is no separate `gitnexus rename` CLI; renaming goes through MCP or editor integration.)  
-3. **Run impact analysis before editing shared symbols** — use **`impact`** (upstream) for functions/classes/methods others call; do not ignore **HIGH** / **CRITICAL** risk without maintainer sign-off.  
-4. **Prefer `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, run `npx gitnexus analyze --embeddings` when refreshing the index; plain `analyze` can drop them.
+1. **Never commit secrets** — API keys, tokens, real `.env` values, private URLs, session cookies. Use `.env.example` with placeholders.
+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.
 
 ---
 
 ## Signs (recurring failure patterns)
 
-Use this format: **Trigger → Instruction → Reason**.  
-Append new Signs here when the same mistake repeats (e.g. CI broken twice the same way).
+Format: **Trigger → Instruction → Reason**. Append new Signs when the same mistake repeats.
 
-### Sign: Stale graph after edits
+### Stale graph after edits
 
-- **Trigger:** MCP or resources warn the index is behind `HEAD`, or code search doesn’t match latest commit.  
-- **Instruction:** Run `npx gitnexus analyze` from the repo root (plus `--embeddings` if the project used them).  
-- **Reason:** Tools query LadybugDB built at last analyze; git changes are invisible until re-indexed.
+- **Trigger:** MCP warns index is behind `HEAD`, or search doesn't match latest commit.
+- **Do:** `npx gitnexus analyze` (plus `--embeddings` if used).
+- **Why:** Tools query LadybugDB from last analyze; git changes are invisible until re-indexed.
 
-### Sign: Embeddings vanished after analyze
+### Embeddings vanished after analyze
 
-- **Trigger:** Semantic search quality drops; `stats.embeddings` in `.gitnexus/meta.json` is 0 after a refresh.  
-- **Instruction:** Re-run `npx gitnexus analyze --embeddings` and confirm `meta.json` reflects stored embeddings.  
-- **Reason:** Embedding generation is opt-in; analyze without the flag does not preserve prior vectors.
+- **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.
 
-### Sign: MCP lists no repos
+### MCP lists no repos
 
-- **Trigger:** MCP stderr says no indexed repos.  
-- **Instruction:** Run `npx gitnexus analyze` in the target repository; verify `npx gitnexus list` shows it.  
-- **Reason:** The MCP server discovers repos via `~/.gitnexus/registry.json`, populated by analyze.
+- **Trigger:** MCP stderr says no indexed repos.
+- **Do:** `npx gitnexus analyze` in the target repo; verify `npx gitnexus list` shows it.
+- **Why:** MCP discovers repos via `~/.gitnexus/registry.json`, populated by analyze.
 
-### Sign: Wrong repo in multi-repo setups
+### Wrong repo in multi-repo setups
 
-- **Trigger:** Query/impact results clearly belong to another project.  
-- **Instruction:** Call `list_repos`, then pass **`repo`** on subsequent tools (or use per-workspace MCP config).  
-- **Reason:** Default target may be ambiguous when multiple repos are registered.
+- **Trigger:** Query/impact results belong to another project.
+- **Do:** Call `list_repos`, then pass `repo` on subsequent tools.
+- **Why:** Default target is ambiguous when multiple repos are registered.
 
-### Sign: LadybugDB lock / “database busy”
+### LadybugDB lock / "database busy"
 
-- **Trigger:** Errors opening `.gitnexus/lbug` while MCP and analyze both run.  
-- **Instruction:** Stop overlapping processes; one writer at a time. Retry analyze or restart MCP.  
-- **Reason:** Embedded DB expects single-process ownership of the store.
+- **Trigger:** Errors opening `.gitnexus/lbug` while MCP and analyze both run.
+- **Do:** Stop overlapping processes (one writer at a time). Retry analyze or restart MCP.
+- **Why:** Embedded DB expects single-process ownership.
 
 ---
 
 ## Publishing & supply chain
 
-- **npm:** Do not publish from unreviewed automation; follow maintainer release process. Bump version intentionally; tag releases to match `package.json`.  
-- **Dependencies:** Prefer minimal, auditable changes to `package.json`; run tests and CI after lockfile updates.  
-- **License:** This project ships under **PolyForm Noncommercial 1.0.0** — do not relicense or imply a different license in docs or metadata without maintainer approval.
+- **npm:** Do not publish from unreviewed automation. Bump version intentionally; tag releases to match `package.json`.
+- **Dependencies:** Minimal, auditable `package.json` changes; run tests and CI after lockfile updates.
+- **License:** PolyForm Noncommercial 1.0.0 — do not relicense without maintainer approval.
 
 ---
 
@@ -74,15 +71,15 @@ Append new Signs here when the same mistake repeats (e.g. CI broken twice the sa
 
 Stop and ask a **human maintainer** when:
 
-- Impact analysis shows **HIGH** / **CRITICAL** risk and the task still requires the change.  
-- You need to alter **CI**, **release**, or **security-sensitive** config.  
-- Requirements conflict (e.g. “speed up analyze” vs “must keep all embeddings on huge repo”).  
+- Impact analysis shows HIGH/CRITICAL risk and the task still requires the change.
+- You need to alter CI, release, or security-sensitive config.
+- Requirements conflict (e.g. "speed up analyze" vs "must keep all embeddings on huge repo").
 - You are unsure whether data loss is acceptable (`clean`, forced migrations, schema changes).
 
 ---
 
 ## Related docs
 
-- [ARCHITECTURE.md](ARCHITECTURE.md) — components and data flow.  
-- [RUNBOOK.md](RUNBOOK.md) — commands for recovery.  
-- [CONTRIBUTING.md](CONTRIBUTING.md) — PR and commit expectations.
+- [ARCHITECTURE.md](ARCHITECTURE.md) — components and data flow
+- [RUNBOOK.md](RUNBOOK.md) — commands for recovery
+- [CONTRIBUTING.md](CONTRIBUTING.md) — PR and commit expectations

MIGRATION.md

@@ -0,0 +1,27 @@
+# Migration Guide
+
+## OVERRIDES → METHOD_OVERRIDES (PR #642)
+
+The `OVERRIDES` relationship type has been renamed to `METHOD_OVERRIDES` for
+consistency with the new `METHOD_IMPLEMENTS` edge type.
+
+### Do I need to migrate?
+
+**No.** Backward compatibility is handled automatically at runtime:
+
+- `local-backend.ts` dual-reads both `OVERRIDES` and `METHOD_OVERRIDES` in all
+  impact-analysis and context queries. Existing stored graphs with `OVERRIDES`
+  edges continue to return correct results without any manual intervention.
+- The `REL_TYPES` array in `schema-constants.ts` includes both names so Cypher
+  queries that reference either will work.
+
+### What happens on re-index?
+
+Running `npx gitnexus analyze` on a repository produces `METHOD_OVERRIDES`
+edges going forward. The old `OVERRIDES` edges are replaced as part of the
+normal full re-index.
+
+### When will the legacy alias be removed?
+
+The `OVERRIDES` compat alias will remain until a future major version. Removal
+will be announced in this file and in the changelog before it happens.

README.md

@@ -19,6 +19,8 @@
     <img src="https://img.shields.io/badge/License-PolyForm%20Noncommercial-blue.svg" alt="License: PolyForm Noncommercial"/>
   </a>
 
+  <p><strong>Enterprise (SaaS & Self-hosted)</strong> - <a href="https://akonlabs.com">akonlabs.com</a></p>
+
 </div>
 
 **Building nervous system for agent context.**
@@ -50,7 +52,7 @@ https://github.com/user-attachments/assets/172685ba-8e54-4ea7-9ad1-e31a3398da72
 | **What**    | Index repos locally, connect AI agents via MCP                 | Visual graph explorer + AI chat in browser                   |
 | **For**     | Daily development with Cursor, Claude Code, Codex, Windsurf, OpenCode | Quick exploration, demos, one-off analysis                   |
 | **Scale**   | Full repos, any size                                           | Limited by browser memory (~5k files), or unlimited via backend mode |
-| **Install** | `npm install -g gitnexus`                                    | No install —[gitnexus.vercel.app](https://gitnexus.vercel.app) |
+| **Install** | `npm install -g gitnexus`                                    | No install — [gitnexus.vercel.app](https://gitnexus.vercel.app) |
 | **Storage** | LadybugDB native (fast, persistent)                               | LadybugDB WASM (in-memory, per session)                         |
 | **Parsing** | Tree-sitter native bindings                                    | Tree-sitter WASM                                             |
 | **Privacy** | Everything local, no network                                   | Everything in-browser, no server                             |
@@ -59,6 +61,28 @@ https://github.com/user-attachments/assets/172685ba-8e54-4ea7-9ad1-e31a3398da72
 
 ---
 
+## Enterprise
+
+GitNexus is available as an **enterprise offering** - either as a fully managed **SaaS** or a **self-hosted** deployment. Also available for **commercial use** of the OSS version with proper licensing.
+
+Enterprise includes:
+- **PR Review** - automated blast radius analysis on pull requests
+- **Auto-updating Code Wiki** - always up-to-date documentation (Code Wiki is also available in OSS)
+- **Auto-reindexing** - knowledge graph stays fresh automatically
+- **Multi-repo support** - unified graph across repositories
+- **OCaml support** - additional language coverage
+- **Priority feature/language support** - request new languages or features
+
+**Upcoming:**
+- Auto regression forensics
+- End-to-end test generation
+
+👉 Learn more at [akonlabs.com](https://akonlabs.com)
+
+💬 For commercial licensing or enterprise inquiries, ping us on [Discord](https://discord.gg/AAsRVT6fGb) or drop an email at founders@akonlabs.com
+
+---
+
 ## Development
 
 - [ARCHITECTURE.md](ARCHITECTURE.md) — packages, index → graph → MCP flow, where to change code
@@ -95,7 +119,6 @@ To configure MCP for your editor, run `npx gitnexus setup` once — or set it up
 | **Codex**       | Yes | Yes    | —                   | MCP + Skills   |
 | **Windsurf**    | Yes | —     | —                   | MCP            |
 | **OpenCode**    | Yes | Yes    | —                   | MCP + Skills   |
-| **Codex**       | Yes | —     | —                   | MCP            |
 
 > **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.
 
@@ -147,8 +170,8 @@ codex mcp add gitnexus -- npx -y gitnexus@latest mcp
 {
   "mcp": {
     "gitnexus": {
-      "command": "npx",
-      "args": ["-y", "gitnexus@latest", "mcp"]
+      "type": "local",
+      "command": ["gitnexus", "mcp"]
     }
   }
 }
@@ -165,13 +188,14 @@ args = ["-y", "gitnexus@latest", "mcp"]
 ### CLI Commands
 
 ```bash
-gitnexus setup                    # Configure MCP for your editors (one-time)
-gitnexus analyze [path]           # Index a repository (or update stale index)
-gitnexus analyze --force          # Force full re-index
-gitnexus analyze --skills         # Generate repo-specific skill files from detected communities
+gitnexus setup                   # Configure MCP for your editors (one-time)
+gitnexus analyze [path]          # Index a repository (or update stale index)
+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 --embeddings     # Enable embedding generation (slower, better search)
-gitnexus analyze --verbose        # Log skipped files when parsers are unavailable
+gitnexus analyze --skip-agents-md  # Preserve custom AGENTS.md/CLAUDE.md gitnexus section edits
+gitnexus analyze --embeddings    # Enable embedding generation (slower, better search)
+gitnexus analyze --verbose       # Log skipped files when parsers are unavailable
 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
@@ -181,11 +205,21 @@ gitnexus clean --all --force     # Delete all indexes
 gitnexus wiki [path]             # Generate repository wiki from knowledge graph
 gitnexus wiki --model <model>    # Wiki with custom LLM model (default: gpt-4o-mini)
 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 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
 ```
 
 ### What Your AI Agent Gets
 
-**7 tools** exposed via MCP:
+**16 tools** exposed via MCP (11 per-repo + 5 group):
 
 | Tool               | What It Does                                                      | `repo` Param |
 | ------------------ | ----------------------------------------------------------------- | -------------- |
@@ -196,6 +230,11 @@ gitnexus wiki --base-url <url>   # Wiki with custom LLM API base URL
 | `detect_changes` | Git-diff impact — maps changed lines to affected processes       | Optional       |
 | `rename`         | Multi-file coordinated rename with graph + text search            | Optional       |
 | `cypher`         | Raw Cypher graph queries                                          | Optional       |
+| `group_list`     | List configured repository groups                                 | —             |
+| `group_sync`     | Extract contracts and match across repos/services                 | —             |
+| `group_contracts`| Inspect extracted contracts and cross-links                       | —             |
+| `group_query`    | Search execution flows across all repos in a group                | —             |
+| `group_status`   | Check staleness of repos in a group                               | —             |
 
 > When only one repo is indexed, the `repo` parameter is optional. With multiple repos, specify which one: `query({query: "auth", repo: "my-app"})`.
 
@@ -291,11 +330,47 @@ Or run locally:
 
 ```bash
 git clone https://github.com/abhigyanpatwari/gitnexus.git
-cd gitnexus/gitnexus-web
-npm install
+cd gitnexus/gitnexus-shared && npm install && npm run build
+cd ../gitnexus-web && npm install
 npm run dev
 ```
 
+## Docker
+
+```bash
+docker run --rm \
+  --name gitnexus \
+  -p 4173:4173 \
+  ghcr.io/abhigyanpatwari/gitnexus:latest
+```
+
+Or with Docker Compose:
+
+```bash
+docker compose up -d
+```
+
+Optional env file:
+
+```bash
+cp .env.example .env
+set -a
+source .env
+set +a
+```
+
+Docker files:
+
+- [Dockerfile](Dockerfile) is the source for the published `gitnexus` image. It builds `gitnexus-shared` and `gitnexus-web`, then serves the production frontend.
+- [docker-compose.yaml](docker-compose.yaml) starts the published image with Docker Compose.
+- [.env.example](.env.example) sets the image name, container name, and exposed port for the example commands.
+
+Notes:
+
+- The published image serves the production frontend only. It does not start `gitnexus serve`.
+- In backend mode, the app still defaults to `http://localhost:4747` unless you change the server URL in the UI.
+- If you do not want an env file, the defaults are `ghcr.io/abhigyanpatwari/gitnexus:latest`, container name `gitnexus`, and port `4173`.
+
 The web UI uses the same indexing pipeline as the CLI but runs entirely in WebAssembly (Tree-sitter WASM, LadybugDB WASM, in-browser embeddings). It's great for quick exploration but limited by browser memory for larger repos.
 
 **Local Backend Mode:** Run `gitnexus serve` and open the web UI locally — it auto-detects the server and shows all your indexed repos, with full AI chat support. No need to re-upload or re-index. The agent's tools (Cypher queries, search, code navigation) route through the backend HTTP API automatically.

TESTING.md

@@ -20,9 +20,9 @@ From repository root, unless noted:
 cd gitnexus
 npm install
 npm run build
-npm test                    # unit: vitest run test/unit
+npm test                    # full suite: vitest run
+npm run test:unit           # unit only: vitest run test/unit
 npm run test:integration    # integration suite
-npm run test:all
 npm run test:coverage
 npx tsc --noEmit            # typecheck (matches CI)
 ```
@@ -42,8 +42,11 @@ npm run test:e2e            # Playwright (requires gitnexus serve + npm run dev)
 
 A husky pre-commit hook (`.husky/pre-commit`) runs automatically on every `git commit`:
 
-- **`gitnexus-web/` files staged** → `tsc -b --noEmit` + `vitest run`
-- **`gitnexus/` files staged** → `tsc --noEmit` + `vitest run --project default`
+1. **Formatting** — `lint-staged` runs prettier on staged files
+2. **`gitnexus-web/` files staged** → `tsc -b --noEmit`
+3. **`gitnexus/` files staged** → `tsc --noEmit`
+
+Tests do **not** run in the pre-commit hook — they run in CI (`ci-tests.yml`) only.
 
 Skip with `git commit --no-verify` (use sparingly).
 
@@ -77,7 +80,7 @@ Re-run the full relevant suite when:
 
 GitHub Actions (`.github/workflows/ci.yml`) orchestrate:
 
-- **`ci-quality.yml`** — `tsc --noEmit` for `gitnexus/` + `tsc -b --noEmit` for `gitnexus-web/`
+- **`ci-quality.yml`** — prettier format check, eslint lint, `tsc --noEmit` for `gitnexus/`, `tsc -b --noEmit` for `gitnexus-web/`
 - **`ci-tests.yml`** — `vitest run` with coverage (ubuntu) + cross-platform (macOS, Windows)
 - **`ci-e2e.yml`** — Playwright E2E tests, gated on `gitnexus-web/**` changes
 

docker-compose.yaml

@@ -0,0 +1,13 @@
+services:
+  gitnexus:
+    image: ${IMAGE_NAME:-ghcr.io/brainifii/gitnexus:latest}
+    container_name: ${CONTAINER_NAME:-gitnexus}
+    ports:
+      - '${HOST_PORT:-4173}:4173'
+    restart: unless-stopped
+    healthcheck:
+      test: ['CMD', 'curl', '-f', 'http://localhost:4173/']
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s

docker-server.mjs

@@ -0,0 +1,81 @@
+import { createReadStream } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import { extname, join, normalize, sep } from 'node:path';
+
+const host = '0.0.0.0';
+const port = Number(process.env.PORT || '4173');
+const root = join(process.cwd(), 'dist');
+
+const contentTypes = {
+  '.css': 'text/css; charset=utf-8',
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.map': 'application/json; charset=utf-8',
+  '.png': 'image/png',
+  '.svg': 'image/svg+xml',
+  '.txt': 'text/plain; charset=utf-8',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+};
+
+function resolvePath(urlPath) {
+  let decoded;
+  try {
+    decoded = decodeURIComponent(urlPath);
+  } catch {
+    return null;
+  }
+  if (decoded.includes('\0')) return null;
+  const cleanPath = normalize(decoded.replace(/^\/+/, ''));
+  const candidate = join(root, cleanPath);
+  if (candidate !== root && !candidate.startsWith(root + sep)) return null;
+  return candidate;
+}
+
+const server = createServer(async (req, res) => {
+  const requestPath = req.url?.split('?')[0] || '/';
+  let filePath = resolvePath(requestPath);
+
+  if (!filePath) {
+    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 finalStat = await stat(filePath).catch(() => null);
+    if (!finalStat?.isFile()) {
+      res.writeHead(404);
+      res.end('Not found');
+      return;
+    }
+
+    res.writeHead(200, {
+      'Cache-Control': filePath.includes('/assets/')
+        ? 'public, max-age=31536000, immutable'
+        : 'no-cache',
+      'Content-Type': contentTypes[extname(filePath)] || 'application/octet-stream',
+      'Cross-Origin-Opener-Policy': 'same-origin',
+      'Cross-Origin-Embedder-Policy': 'require-corp',
+    });
+    const stream = createReadStream(filePath);
+    stream.on('error', () => res.destroy());
+    stream.pipe(res);
+  } catch (error) {
+    res.writeHead(500);
+    res.end(error instanceof Error ? error.message : 'Internal server error');
+  }
+});
+
+server.listen(port, host, () => {
+  console.log(`gitnexus-web listening on http://${host}:${port}`);
+});

docker-server.test.mjs

@@ -0,0 +1,107 @@
+import { mkdir, mkdtemp, rm, unlink, writeFile } from 'node:fs/promises';
+import http, { createServer } from 'node:http';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { after, before, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const serverScript = join(__dirname, 'docker-server.mjs');
+
+function getFreePort() {
+  return new Promise((resolve) => {
+    const s = createServer();
+    s.listen(0, '127.0.0.1', () => {
+      const { port } = s.address();
+      s.close(() => resolve(port));
+    });
+  });
+}
+
+function rawGet(port, path) {
+  return new Promise((resolve, reject) => {
+    const req = http.request({ host: '127.0.0.1', port, path }, (res) => {
+      let body = '';
+      res.setEncoding('utf8');
+      res.on('data', (chunk) => {
+        body += chunk;
+      });
+      res.on('end', () => resolve({ status: res.statusCode, headers: res.headers, body }));
+    });
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+async function waitForServer(port, retries = 30) {
+  for (let i = 0; i < retries; i++) {
+    try {
+      await rawGet(port, '/');
+      return;
+    } catch {
+      await new Promise((r) => setTimeout(r, 100));
+    }
+  }
+  throw new Error('Server did not start in time');
+}
+
+let tmpDir, serverPort, child;
+
+before(async () => {
+  tmpDir = await mkdtemp(join(tmpdir(), 'gitnexus-docker-test-'));
+  const distDir = join(tmpDir, 'dist');
+  const assetsDir = join(distDir, 'assets');
+  await mkdir(assetsDir, { recursive: true });
+  await writeFile(join(distDir, 'index.html'), '<html><body>spa</body></html>');
+  await writeFile(join(assetsDir, 'app.abc123.js'), 'console.log("app")');
+
+  serverPort = await getFreePort();
+  child = spawn(process.execPath, [serverScript], {
+    cwd: tmpDir,
+    env: { ...process.env, PORT: String(serverPort) },
+    stdio: 'pipe',
+  });
+  child.on('error', (err) => {
+    throw err;
+  });
+
+  await waitForServer(serverPort);
+});
+
+after(async () => {
+  child?.kill();
+  if (tmpDir) await rm(tmpDir, { recursive: true, force: true });
+});
+
+it('serves a valid asset with immutable cache header', async () => {
+  const res = await rawGet(serverPort, '/assets/app.abc123.js');
+  assert.equal(res.status, 200);
+  assert.match(res.headers['cache-control'], /immutable/);
+  assert.equal(res.headers['cross-origin-opener-policy'], 'same-origin');
+  assert.equal(res.headers['cross-origin-embedder-policy'], 'require-corp');
+});
+
+it('serves SPA fallback for unknown routes', async () => {
+  const res = await rawGet(serverPort, '/some/unknown/route');
+  assert.equal(res.status, 200);
+  assert.match(res.body, /spa/);
+  assert.match(res.headers['cache-control'], /no-cache/);
+});
+
+it('rejects path traversal with 400', async () => {
+  const res = await rawGet(serverPort, '/../../../etc/passwd');
+  assert.equal(res.status, 400);
+});
+
+it('rejects percent-encoded null bytes with 400', async () => {
+  const res = await rawGet(serverPort, '/foo%00bar');
+  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');
+  assert.equal(res.status, 404);
+});

docs/superpowers/plans/2026-04-02-pr626-high-fixes.md

@@ -0,0 +1,725 @@
+# PR #626 HIGH-Priority Fixes Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Fix 4 HIGH-priority issues from PR #626 code review before merge.
+
+**Architecture:** Minimal targeted fixes — each task is independent. TDD: tests first, then implementation. No refactoring beyond what's needed.
+
+**Tech Stack:** TypeScript, Vitest, Node.js fs/path APIs
+
+**Spec:** `docs/superpowers/specs/2026-04-02-pr626-high-fixes-design.md`
+
+**Paths:** All file paths are relative to the monorepo root (`GitNexus/`). Git commands run from the root. The `gitnexus/` prefix is a package subdirectory, not a separate repo.
+
+---
+
+### Task 1: Path Traversal — Validate Group Name
+
+**Files:**
+- Modify: `gitnexus/src/core/group/storage.ts:17-19` (getGroupDir) and `:63-68` (createGroupDir)
+- Test: `gitnexus/test/unit/group/storage.test.ts`
+
+- [ ] **Step 1: Write failing tests for validateGroupName**
+
+In `gitnexus/test/unit/group/storage.test.ts`, add `createGroupDir` and `validateGroupName` to the existing import from `'../../../src/core/group/storage.js'` (line 6-11). Then add these describe blocks at the end of the outer `describe('Group storage', ...)`:
+
+```typescript
+  describe('validateGroupName', () => {
+    it('test_validateGroupName_traversal_path_throws', () => {
+      expect(() => validateGroupName('../../evil')).toThrow(/Invalid group name/);
+    });
+
+    it('test_validateGroupName_slash_in_name_throws', () => {
+      expect(() => validateGroupName('foo/bar')).toThrow(/Invalid group name/);
+    });
+
+    it('test_validateGroupName_empty_string_throws', () => {
+      expect(() => validateGroupName('')).toThrow(/Invalid group name/);
+    });
+
+    it('test_validateGroupName_starts_with_dash_throws', () => {
+      expect(() => validateGroupName('-leading-dash')).toThrow(/Invalid group name/);
+    });
+
+    it('test_validateGroupName_starts_with_underscore_throws', () => {
+      expect(() => validateGroupName('_leading')).toThrow(/Invalid group name/);
+    });
+
+    it('test_validateGroupName_dots_throws', () => {
+      expect(() => validateGroupName('com.example')).toThrow(/Invalid group name/);
+    });
+
+    it('test_validateGroupName_valid_alphanumeric_passes', () => {
+      expect(() => validateGroupName('my-group_01')).not.toThrow();
+    });
+
+    it('test_validateGroupName_single_char_passes', () => {
+      expect(() => validateGroupName('A')).not.toThrow();
+    });
+
+    it('test_validateGroupName_all_digits_passes', () => {
+      expect(() => validateGroupName('123')).not.toThrow();
+    });
+  });
+
+  describe('getGroupDir rejects invalid names', () => {
+    it('test_getGroupDir_traversal_throws', () => {
+      expect(() => getGroupDir(tmpDir, '../../etc')).toThrow(/Invalid group name/);
+    });
+
+    it('test_getGroupDir_valid_name_returns_path', () => {
+      const dir = getGroupDir(tmpDir, 'company');
+      expect(dir).toBe(path.join(tmpDir, 'groups', 'company'));
+    });
+  });
+
+  describe('createGroupDir rejects invalid names', () => {
+    it('test_createGroupDir_traversal_throws', async () => {
+      await expect(createGroupDir(tmpDir, '../evil')).rejects.toThrow(/Invalid group name/);
+    });
+  });
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `cd gitnexus && npx vitest run test/unit/group/storage.test.ts`
+Expected: FAIL — `validateGroupName` is not exported, `getGroupDir` does not throw.
+
+- [ ] **Step 3: Implement validateGroupName and wire into getGroupDir and createGroupDir**
+
+In `gitnexus/src/core/group/storage.ts`, add the validation function before `getGroupDir` and call it:
+
+```typescript
+const GROUP_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
+
+export function validateGroupName(name: string): void {
+  if (!GROUP_NAME_RE.test(name)) {
+    throw new Error(
+      `Invalid group name "${name}". Names must start with a letter or digit and contain only [a-zA-Z0-9_-].`,
+    );
+  }
+}
+
+export function getGroupDir(gitnexusDir: string, groupName: string): string {
+  validateGroupName(groupName);
+  return path.join(gitnexusDir, 'groups', groupName);
+}
+```
+
+`createGroupDir` already calls `getGroupDir` at line 68, so it inherits validation automatically. No change needed in `createGroupDir`.
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cd gitnexus && npx vitest run test/unit/group/storage.test.ts`
+Expected: ALL PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+cd gitnexus && git add src/core/group/storage.ts test/unit/group/storage.test.ts
+git commit -m "fix(group): validate group name to prevent path traversal
+
+Add validateGroupName() with regex [a-zA-Z0-9][a-zA-Z0-9_-]*.
+Called in getGroupDir (defense in depth) which covers all CLI entry
+points: create, add, remove, status, sync.
+
+Addresses PR #626 review item 1 (HIGH).
+
+Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+### Task 2: Directory Exclusions in Service Boundary Detector
+
+**Files:**
+- Modify: `gitnexus/src/core/group/service-boundary-detector.ts:24-51` (add constant), `:78` (walkForBoundaries), `:130` (hasSourceFilesInSubdirs)
+- Test: `gitnexus/test/unit/group/service-boundary-detector.test.ts`
+
+- [ ] **Step 1: Write failing tests for excluded directories**
+
+Add this describe block inside the existing `detectServiceBoundaries` describe in `gitnexus/test/unit/group/service-boundary-detector.test.ts`:
+
+```typescript
+    it('test_detect_skips_vendor_directory', async () => {
+      writeFile('services/auth/package.json', '{}');
+      writeFile('services/auth/src/index.ts', '');
+      // vendor should be skipped — its contents should not create a boundary
+      writeFile('vendor/some-dep/package.json', '{}');
+      writeFile('vendor/some-dep/src/lib.go', '');
+
+      const boundaries = await detectServiceBoundaries(tmpDir);
+
+      const paths = boundaries.map((b) => b.servicePath);
+      expect(paths).toContain('services/auth');
+      expect(paths).not.toContain('vendor/some-dep');
+    });
+
+    it('test_detect_skips_target_directory', async () => {
+      writeFile('services/api/go.mod', 'module api');
+      writeFile('services/api/main.go', '');
+      writeFile('target/classes/Main.java', '');
+      writeFile('target/pom.xml', '<project/>');
+
+      const boundaries = await detectServiceBoundaries(tmpDir);
+
+      const paths = boundaries.map((b) => b.servicePath);
+      expect(paths).toContain('services/api');
+      expect(paths).not.toContain('target');
+    });
+
+    it('test_detect_skips_pycache_directory', async () => {
+      writeFile('services/ml/pyproject.toml', '[project]');
+      writeFile('services/ml/model.py', '');
+      // __pycache__ with a marker + source files — would be detected as
+      // a boundary if not excluded, since it has package.json + .py file
+      writeFile('__pycache__/package.json', '{}');
+      writeFile('__pycache__/cached.py', '');
+
+      const boundaries = await detectServiceBoundaries(tmpDir);
+
+      const paths = boundaries.map((b) => b.servicePath);
+      expect(paths).toContain('services/ml');
+      expect(paths.every((p) => !p.includes('__pycache__'))).toBe(true);
+    });
+
+    it('test_detect_skips_dotfile_directories_regression', async () => {
+      writeFile('services/api/package.json', '{}');
+      writeFile('services/api/src/index.ts', '');
+      writeFile('.hidden/package.json', '{}');
+      writeFile('.hidden/src/index.ts', '');
+
+      const boundaries = await detectServiceBoundaries(tmpDir);
+
+      const paths = boundaries.map((b) => b.servicePath);
+      expect(paths).toContain('services/api');
+      expect(paths).not.toContain('.hidden');
+    });
+
+    it('test_detect_does_not_skip_regular_source_directories', async () => {
+      writeFile('services/api/package.json', '{}');
+      writeFile('services/api/src/index.ts', '');
+
+      const boundaries = await detectServiceBoundaries(tmpDir);
+
+      expect(boundaries).toHaveLength(1);
+      expect(boundaries[0].serviceName).toBe('api');
+    });
+```
+
+- [ ] **Step 2: Run tests to verify `vendor` and `target` tests fail**
+
+Run: `cd gitnexus && npx vitest run test/unit/group/service-boundary-detector.test.ts`
+Expected: `test_detect_skips_vendor_directory` and `test_detect_skips_target_directory` FAIL (vendor/target not excluded). Other new tests may pass since dotfile exclusion already exists.
+
+- [ ] **Step 3: Add EXCLUDED_DIRS constant and update both walking functions**
+
+In `gitnexus/src/core/group/service-boundary-detector.ts`:
+
+After `SOURCE_EXTENSIONS` (after line 51), add:
+
+```typescript
+const EXCLUDED_DIRS = new Set([
+  'node_modules',
+  'vendor',
+  'target',
+  'build',
+  'dist',
+  '__pycache__',
+  '.venv',
+  'venv',
+  '.tox',
+  '.mypy_cache',
+  '.gradle',
+  '.mvn',
+  'out',
+  'bin',
+]);
+```
+
+In `walkForBoundaries`, replace line 78:
+```typescript
+    if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+```
+with:
+```typescript
+    if (entry.name.startsWith('.') || EXCLUDED_DIRS.has(entry.name)) continue;
+```
+
+In `hasSourceFilesInSubdirs`, replace line 130:
+```typescript
+      if (entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'node_modules') {
+```
+with:
+```typescript
+      if (entry.isDirectory() && !entry.name.startsWith('.') && !EXCLUDED_DIRS.has(entry.name)) {
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cd gitnexus && npx vitest run test/unit/group/service-boundary-detector.test.ts`
+Expected: ALL PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+cd gitnexus && git add src/core/group/service-boundary-detector.ts test/unit/group/service-boundary-detector.test.ts
+git commit -m "fix(group): add directory exclusions to service boundary detector
+
+Add EXCLUDED_DIRS set: vendor, target, build, dist, __pycache__,
+.venv, venv, .tox, .mypy_cache, .gradle, .mvn, out, bin.
+Applied in walkForBoundaries and hasSourceFilesInSubdirs.
+Replaces inline node_modules check.
+
+Addresses PR #626 review item 3 (HIGH).
+
+Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+### Task 3: Remove Double-Close of LadybugDB Pools
+
+**Files:**
+- Modify: `gitnexus/src/cli/group.ts:160` (remove import), `:187-189` (remove finally block body)
+- Test: `gitnexus/test/unit/group/sync.test.ts` (add pool cleanup test)
+- Test: `gitnexus/test/integration/group/group-cli.test.ts` (verify no blanket close in source)
+
+- [ ] **Step 1: Write unit tests for per-id pool cleanup in sync.ts**
+
+Add to `gitnexus/test/unit/group/sync.test.ts`, inside the existing `describe('syncGroup', ...)`:
+
+```typescript
+  it('test_syncGroup_closes_only_opened_pools', async () => {
+    const config = makeConfig({
+      'app/backend': 'backend-repo',
+      'app/frontend': 'frontend-repo',
+    });
+
+    const closedIds: string[] = [];
+
+    // Mock initLbug/closeLbug via per-repo override that tracks pool lifecycle
+    const { vi } = await import('vitest');
+    const poolAdapter = await import('../../../src/core/lbug/pool-adapter.js');
+    const initSpy = vi.spyOn(poolAdapter, 'initLbug').mockResolvedValue(undefined);
+    const closeSpy = vi.spyOn(poolAdapter, 'closeLbug').mockImplementation(async (id?: string) => {
+      if (id) closedIds.push(id);
+    });
+
+    try {
+      await syncGroup(config, {
+        resolveRepoHandle: async (_name, groupPath) => ({
+          id: groupPath.replace(/\//g, '-'),
+          path: groupPath,
+          repoPath: '/tmp/' + groupPath,
+          storagePath: '/tmp/' + groupPath + '/.gitnexus',
+        }),
+        skipWrite: true,
+      }).catch(() => {});
+      // Regardless of extraction errors, closeLbug should be called per id
+      // closeLbug should only receive specific pool ids, never undefined/empty
+      for (const id of closedIds) {
+        expect(id).toBeTruthy();
+        expect(typeof id).toBe('string');
+      }
+      // No blanket close (no-arg call)
+      const blanketCalls = closeSpy.mock.calls.filter((args) => args.length === 0 || !args[0]);
+      expect(blanketCalls).toHaveLength(0);
+    } finally {
+      initSpy.mockRestore();
+      closeSpy.mockRestore();
+    }
+  });
+```
+
+- [ ] **Step 2: Run sync unit test to verify it passes (sync.ts already does per-id cleanup)**
+
+Run: `cd gitnexus && npx vitest run test/unit/group/sync.test.ts`
+Expected: PASS — sync.ts already cleans up correctly. This test locks the behavior.
+
+- [ ] **Step 3: Write test verifying CLI source has no blanket closeLbug()**
+
+Add to `gitnexus/test/integration/group/group-cli.test.ts`:
+
+```typescript
+  it('test_sync_command_source_does_not_call_blanket_closeLbug', () => {
+    const cliGroupPath = path.join(repoRoot, 'src', 'cli', 'group.ts');
+    const source = fs.readFileSync(cliGroupPath, 'utf-8');
+
+    // closeLbug() without arguments (blanket close) must not appear.
+    // closeLbug(id) with argument is fine (that's in sync.ts, not here).
+    // Match closeLbug() but not closeLbug(someArg)
+    const blanketClosePattern = /closeLbug\s*\(\s*\)/;
+    expect(source).not.toMatch(blanketClosePattern);
+  });
+```
+
+- [ ] **Step 4: Run test to verify it fails**
+
+Run: `cd gitnexus && npx vitest run test/integration/group/group-cli.test.ts`
+Expected: FAIL — `closeLbug()` (no args) exists at line 188.
+
+- [ ] **Step 5: Remove blanket closeLbug() from cli/group.ts**
+
+In `gitnexus/src/cli/group.ts`:
+
+Remove the `closeLbug` import at line 160:
+```typescript
+      const { closeLbug } = await import('../core/lbug/pool-adapter.js');
+```
+
+Replace the try/finally wrapper (lines 162-189):
+```typescript
+      try {
+        const groupDir = getGroupDir(getDefaultGitnexusDir(), name);
+        const config = await loadGroupConfig(groupDir);
+
+        console.log(`Syncing group "${name}" (${Object.keys(config.repos).length} repos)...\n`);
+
+        const result = await syncGroup(config, {
+          groupDir,
+          allowStale: Boolean(opts.allowStale),
+          verbose: Boolean(opts.verbose),
+          skipEmbeddings: Boolean(opts.skipEmbeddings),
+          exactOnly: Boolean(opts.exactOnly),
+        });
+
+        if (opts.json) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          console.log(`\nMatching cascade:`);
+          const exactLinks = result.crossLinks.filter((l) => l.matchType === 'exact');
+          console.log(`  exact:     ${exactLinks.length} cross-links (confidence 1.0)`);
+          console.log(`  unmatched: ${result.unmatched.length} contracts`);
+          console.log(
+            `\nWrote contracts.json (${result.contracts.length} contracts, ${result.crossLinks.length} cross-links)`,
+          );
+        }
+      } finally {
+        await closeLbug().catch(() => {});
+      }
+```
+
+Becomes (remove try/finally entirely, since sync.ts handles its own cleanup):
+```typescript
+        const groupDir = getGroupDir(getDefaultGitnexusDir(), name);
+        const config = await loadGroupConfig(groupDir);
+
+        console.log(`Syncing group "${name}" (${Object.keys(config.repos).length} repos)...\n`);
+
+        const result = await syncGroup(config, {
+          groupDir,
+          allowStale: Boolean(opts.allowStale),
+          verbose: Boolean(opts.verbose),
+          skipEmbeddings: Boolean(opts.skipEmbeddings),
+          exactOnly: Boolean(opts.exactOnly),
+        });
+
+        if (opts.json) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          console.log(`\nMatching cascade:`);
+          const exactLinks = result.crossLinks.filter((l) => l.matchType === 'exact');
+          console.log(`  exact:     ${exactLinks.length} cross-links (confidence 1.0)`);
+          console.log(`  unmatched: ${result.unmatched.length} contracts`);
+          console.log(
+            `\nWrote contracts.json (${result.contracts.length} contracts, ${result.crossLinks.length} cross-links)`,
+          );
+        }
+```
+
+- [ ] **Step 6: Run tests to verify they pass**
+
+Run: `cd gitnexus && npx vitest run test/integration/group/group-cli.test.ts test/unit/group/sync.test.ts`
+Expected: ALL PASS
+
+- [ ] **Step 7: Commit**
+
+```bash
+cd gitnexus && git add src/cli/group.ts test/integration/group/group-cli.test.ts test/unit/group/sync.test.ts
+git commit -m "fix(group): remove blanket closeLbug() from CLI sync command
+
+sync.ts already closes pools per-id in its finally block.
+The blanket closeLbug() in cli/group.ts tears down ALL active pools
+including unrelated ones in MCP server context.
+
+Addresses PR #626 review item 4 (HIGH).
+
+Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+### Task 4: gRPC Proto Regex — Brace-Depth Counter
+
+**Files:**
+- Modify: `gitnexus/src/core/group/extractors/grpc-extractor.ts:101-130` (parseProtoFile)
+- Test: `gitnexus/test/unit/group/grpc-extractor.test.ts`
+
+- [ ] **Step 1: Write failing tests for nested braces in proto services**
+
+Add this describe block inside the existing `proto file parsing` describe in `gitnexus/test/unit/group/grpc-extractor.test.ts`:
+
+```typescript
+    it('test_extract_proto_with_google_api_http_nested_braces', async () => {
+      writeFile(
+        'api/gateway.proto',
+        `syntax = "proto3";
+package gateway.v1;
+
+import "google/api/annotations.proto";
+
+service GatewayService {
+  rpc GetUser (GetUserRequest) returns (UserResponse) {
+    option (google.api.http) = {
+      get: "/v1/users/{user_id}"
+    };
+  }
+  rpc CreateUser (CreateUserRequest) returns (UserResponse) {
+    option (google.api.http) = {
+      post: "/v1/users"
+      body: "*"
+    };
+  }
+}`,
+      );
+
+      const contracts = await extractor.extract(null, tmpDir, makeRepo(tmpDir));
+      const providers = contracts.filter(
+        (c) => c.role === 'provider' && c.symbolRef.filePath === 'api/gateway.proto',
+      );
+
+      expect(providers).toHaveLength(2);
+      const ids = providers.map((c) => c.contractId).sort();
+      expect(ids).toEqual([
+        'grpc::gateway.v1.GatewayService/CreateUser',
+        'grpc::gateway.v1.GatewayService/GetUser',
+      ]);
+    });
+
+    it('test_extract_proto_with_multiple_services', async () => {
+      writeFile(
+        'api/multi.proto',
+        `syntax = "proto3";
+package multi;
+
+service ServiceA {
+  rpc MethodA (Req) returns (Res);
+}
+
+service ServiceB {
+  rpc MethodB1 (Req) returns (Res);
+  rpc MethodB2 (Req) returns (Res);
+}`,
+      );
+
+      const contracts = await extractor.extract(null, tmpDir, makeRepo(tmpDir));
+      const providers = contracts.filter(
+        (c) => c.role === 'provider' && c.symbolRef.filePath === 'api/multi.proto',
+      );
+
+      expect(providers).toHaveLength(3);
+      const ids = providers.map((c) => c.contractId).sort();
+      expect(ids).toEqual([
+        'grpc::multi.ServiceA/MethodA',
+        'grpc::multi.ServiceB/MethodB1',
+        'grpc::multi.ServiceB/MethodB2',
+      ]);
+    });
+
+    it('test_extract_proto_with_nested_option_blocks_in_rpc', async () => {
+      writeFile(
+        'api/nested.proto',
+        `syntax = "proto3";
+package nested;
+
+service DeepService {
+  rpc DeepMethod (Req) returns (Res) {
+    option (google.api.http) = {
+      post: "/v1/deep"
+      body: "*"
+      additional_bindings {
+        get: "/v1/deep/{id}"
+      }
+    };
+  }
+}`,
+      );
+
+      const contracts = await extractor.extract(null, tmpDir, makeRepo(tmpDir));
+      const providers = contracts.filter(
+        (c) => c.role === 'provider' && c.symbolRef.filePath === 'api/nested.proto',
+      );
+
+      expect(providers).toHaveLength(1);
+      expect(providers[0].contractId).toBe('grpc::nested.DeepService/DeepMethod');
+    });
+
+    it('test_extract_proto_malformed_unclosed_brace_skips_service', async () => {
+      writeFile(
+        'api/broken.proto',
+        `syntax = "proto3";
+package broken;
+
+service IncompleteService {
+  rpc SomeMethod (Req) returns (Res);
+  // Missing closing brace — EOF before depth returns to 0
+`,
+      );
+
+      // Should not throw; incomplete service is silently skipped
+      const contracts = await extractor.extract(null, tmpDir, makeRepo(tmpDir));
+      const providers = contracts.filter(
+        (c) => c.role === 'provider' && c.symbolRef.filePath === 'api/broken.proto',
+      );
+
+      // The old regex would find partial match; the new parser should skip it
+      expect(providers).toHaveLength(0);
+    });
+```
+
+- [ ] **Step 2: Run tests to verify the nested brace test fails**
+
+Run: `cd gitnexus && npx vitest run test/unit/group/grpc-extractor.test.ts`
+Expected: `test_extract_proto_with_google_api_http_nested_braces` FAIL — regex stops at first `}` inside the `option` block.
+
+- [ ] **Step 3: Replace serviceRe regex with extractServiceBlocks function**
+
+In `gitnexus/src/core/group/extractors/grpc-extractor.ts`, replace the `parseProtoFile` method (lines 101-130):
+
+```typescript
+  private parseProtoFile(content: string, filePath: string): ExtractedContract[] {
+    const out: ExtractedContract[] = [];
+
+    const pkgMatch = content.match(/^package\s+([\w.]+)\s*;/m);
+    const pkg = pkgMatch ? pkgMatch[1] : '';
+
+    for (const { name: serviceName, body } of extractServiceBlocks(content)) {
+      const rpcRe = /rpc\s+(\w+)\s*\(/g;
+      let rpcMatch: RegExpExecArray | null;
+      while ((rpcMatch = rpcRe.exec(body)) !== null) {
+        const methodName = rpcMatch[1];
+        const cid = contractId(pkg, serviceName, methodName);
+        out.push(
+          makeContract(cid, 'provider', filePath, `${serviceName}.${methodName}`, 0.85, {
+            package: pkg,
+            service: serviceName,
+            method: methodName,
+            source: 'proto',
+          }),
+        );
+      }
+    }
+
+    return out;
+  }
+```
+
+Add this function before the class (e.g. after `serviceOnlyContractId`, around line 26):
+
+```typescript
+function extractServiceBlocks(content: string): Array<{ name: string; body: string }> {
+  const results: Array<{ name: string; body: string }> = [];
+  const headerRe = /service\s+(\w+)\s*\{/g;
+  let headerMatch: RegExpExecArray | null;
+
+  while ((headerMatch = headerRe.exec(content)) !== null) {
+    const serviceName = headerMatch[1];
+    const bodyStart = headerMatch.index + headerMatch[0].length;
+    let depth = 1;
+    let pos = bodyStart;
+
+    while (pos < content.length && depth > 0) {
+      const ch = content[pos];
+      if (ch === '{') depth++;
+      else if (ch === '}') depth--;
+      pos++;
+    }
+
+    // If EOF before depth returns to 0, skip incomplete service
+    if (depth !== 0) continue;
+
+    // body is between opening { (consumed by regex) and closing } (pos is one past it)
+    const body = content.slice(bodyStart, pos - 1);
+    results.push({ name: serviceName, body });
+  }
+
+  return results;
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cd gitnexus && npx vitest run test/unit/group/grpc-extractor.test.ts`
+Expected: ALL PASS (including existing regression tests)
+
+- [ ] **Step 5: Commit**
+
+```bash
+cd gitnexus && git add src/core/group/extractors/grpc-extractor.ts test/unit/group/grpc-extractor.test.ts
+git commit -m "fix(group): replace gRPC proto regex with brace-depth counter
+
+The serviceRe regex used [^}]* which stopped at the first '}'.
+Proto services with google.api.http annotations contain nested {}
+blocks, causing methods to be missed.
+
+New extractServiceBlocks() uses a brace-depth counter (init depth=1
+after opening {, scan char-by-char). Malformed protos with unclosed
+braces are silently skipped.
+
+Addresses PR #626 review item 2 (HIGH).
+
+Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>"
+```
+
+---
+
+### Task 5: Run Full Test Suite
+
+- [ ] **Step 1: Run all group-related tests**
+
+Run: `cd gitnexus && npx vitest run test/unit/group/ test/integration/group/`
+Expected: ALL PASS
+
+- [ ] **Step 2: Run full test suite to catch regressions**
+
+Run: `cd gitnexus && npx vitest run`
+Expected: ALL PASS, 0 failures
+
+- [ ] **Step 3: Run typecheck**
+
+Run: `cd gitnexus && npx tsc --noEmit`
+Expected: No errors
+
+---
+
+### Task 6: CLI Integration Smoke Test
+
+- [ ] **Step 1: Add CLI smoke test for path traversal**
+
+Add to `gitnexus/test/integration/group/group-cli.test.ts` inside the existing `group CLI` describe:
+
+```typescript
+  it('test_create_with_invalid_name_fails', () => {
+    const result = runGroup(['create', '../../evil']);
+    expect(result.status).not.toBe(0);
+    expect(result.stderr).toContain('Invalid group name');
+  });
+```
+
+- [ ] **Step 2: Run test**
+
+Run: `cd gitnexus && npx vitest run test/integration/group/group-cli.test.ts`
+Expected: ALL PASS
+
+- [ ] **Step 3: Commit**
+
+```bash
+cd gitnexus && git add test/integration/group/group-cli.test.ts
+git commit -m "test(group): add CLI smoke test for path traversal rejection
+
+Verifies that 'group create ../../evil' fails with Invalid group name.
+
+Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>"
+```

docs/superpowers/specs/2026-04-02-pr626-high-fixes-design.md

@@ -0,0 +1,175 @@
+# PR #626 HIGH-Priority Fixes Design
+
+**Date:** 2026-04-02
+**PR:** abhigyanpatwari/GitNexus#626 — Intra-repo service communication tracking
+**Scope:** 4 HIGH-priority issues identified by abhigyanpatwari and xkonjin
+**Approach:** Minimal targeted fixes (option A) — no refactoring, no scope creep
+
+---
+
+## Fix 1: Path Traversal via Group Name
+
+**File:** `gitnexus/src/core/group/storage.ts`
+**Risk:** A group name like `../../etc` creates directories outside the intended path.
+
+### Solution
+
+Add `validateGroupName(name: string): void` that enforces `/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/`.
+
+- Call in `createGroupDir` (primary entry point)
+- Call in `getGroupDir` (defense in depth)
+- Throw descriptive error on invalid names
+
+**Legacy:** Groups already on disk with names outside this pattern are not auto-renamed; only new `create` / resolved paths are validated.
+
+### Why regex over path.resolve + startsWith
+
+- abhigyanpatwari explicitly requested `[a-zA-Z0-9_-]`
+- Stricter: disallows spaces, dots, Unicode edge cases
+- Simpler to reason about
+
+### Tests
+
+- `../../evil` throws
+- `foo/bar` throws
+- Empty string throws
+- `my-group_01` passes
+- `A` (single char) passes
+- CLI smoke: one integration test that hits `getGroupDir` / `createGroupDir` (e.g. `group create` or `group add`) with an invalid name proves wiring for every subcommand that resolves a group through storage
+
+### CLI/API entry points accepting groupName
+
+All paths flow through `getGroupDir` (which validates), so coverage is implicit. For reference:
+
+| Command | Entry | Calls |
+|---------|-------|-------|
+| `group create` | `cli/group.ts` action | `createGroupDir` -> `getGroupDir` |
+| `group add` | `cli/group.ts` action | `getGroupDir` |
+| `group remove` | `cli/group.ts` action | `getGroupDir` |
+| `group list` | `cli/group.ts` action | reads `groups/` dir directly — no traversal risk (reads, not writes) |
+| `group status` | `cli/group.ts` action | `getGroupDir` |
+| `group sync` | `cli/group.ts` action | `getGroupDir` |
+
+**`listGroups`:** Reads directory names from disk without validation. Not a write path, so no traversal risk. May surface manually-created directories with non-conforming names — accepted as-is, not in scope.
+
+---
+
+## Fix 2: gRPC Proto Regex -> Brace-Depth Counter
+
+**File:** `gitnexus/src/core/group/extractors/grpc-extractor.ts`
+**Risk:** `serviceRe = /service\s+(\w+)\s*\{([^}]*)}/gs` stops at first `}`. Proto services with `google.api.http` annotations inside RPCs contain nested `{ }` blocks.
+
+### Solution
+
+Replace `serviceRe` regex with `extractServiceBlocks(content: string): Array<{ name: string; body: string }>`:
+
+1. Use regex only to find `service <Name> {` start positions (regex consumes the opening `{`)
+2. Initialise depth to 1 immediately after the opening `{`
+3. Scan forward char by char: `{` -> depth++, `}` -> depth--; collect into body
+4. Stop when depth reaches 0 (the matching closing `}`)
+5. Return name + body pairs
+
+Inner `rpcRe` regex remains unchanged — it operates on the already-extracted body.
+
+**Malformed input:** If EOF is reached before `depth` returns to 0, skip the incomplete service (do not add to results). Lock this in the test.
+
+**Scope limitation (v1):** Brace-depth only — no lexer for string literals or comments containing `{`/`}`. Sufficient for `google.api.http` annotations. Known false positive: braces inside `//` comments or quoted strings within proto options. Accepted for v1; a proper proto lexer is out of scope.
+
+### Tests
+
+- Proto with single service, no nesting (regression)
+- Proto with `google.api.http` nested braces inside RPC options
+- Proto with multiple services
+- Proto with nested `option` blocks inside RPC (e.g. `google.api.http`)
+- Malformed proto with unclosed brace (graceful handling)
+
+---
+
+## Fix 3: Directory Exclusions in Service Boundary Detector
+
+**File:** `gitnexus/src/core/group/service-boundary-detector.ts`
+**Risk:** Walks entire repo tree, only skipping dotfiles and `node_modules`. Extremely slow on repos with `vendor/`, `target/`, `__pycache__/`, `.venv/`.
+
+### Solution
+
+Create `EXCLUDED_DIRS` as a `Set<string>` (alongside existing `SERVICE_MARKERS`, `SOURCE_EXTENSIONS`), for example:
+
+```text
+node_modules, vendor, target, build, dist,
+__pycache__, .venv, venv, .tox, .mypy_cache,
+.gradle, .mvn, out, bin
+```
+
+(Implement as `new Set([...])` — the list above is the membership, not a string literal.)
+
+Apply in both:
+- `walkForBoundaries` (line 77-78) — replace current inline `=== 'node_modules'` check with `EXCLUDED_DIRS.has(entry.name)`
+- `hasSourceFilesInSubdirs` (line 130) — replace `entry.name !== 'node_modules'` with `!EXCLUDED_DIRS.has(entry.name)`
+
+Note: remove the old `=== 'node_modules'` literal from both locations — it is covered by `EXCLUDED_DIRS`.
+Dotfile exclusion (`.` prefix) remains as a separate check since it's a pattern, not a name.
+Exclusions apply only to `isDirectory()` entries — file names are never checked against `EXCLUDED_DIRS`.
+
+**Tradeoff:** Rare layouts that keep source under names like `out/` or `bin/` will be skipped; accepted for performance on typical monorepos.
+
+**Case sensitivity:** `Set.has` is case-sensitive (matches current `=== 'node_modules'` behavior). Windows case-insensitive FS not handled — accepted as-is, consistent with existing code.
+
+### Tests
+
+- Directory named `vendor/` is skipped
+- Directory named `target/` is skipped
+- Directory named `__pycache__/` is skipped
+- Regular source directories are NOT skipped
+- Dotfile directories still skipped (regression)
+
+---
+
+## Fix 4: Double-Close of LadybugDB Pools
+
+**Files:**
+- `gitnexus/src/core/group/sync.ts` (lines 155-157) — per-id cleanup (KEEP)
+- `gitnexus/src/cli/group.ts` (line 188) — blanket `closeLbug()` (REMOVE)
+
+**Risk:** In MCP server context, `closeLbug()` without arguments tears down ALL active pools, including ones from unrelated operations.
+
+### Solution
+
+Remove the `closeLbug()` call (no arguments) from `cli/group.ts` finally block. The per-id cleanup in `sync.ts` is sufficient:
+
+```typescript
+// sync.ts — KEEP: cleans up only pools opened by this sync
+finally {
+  for (const id of [...new Set(openPoolIds)]) {
+    await closeLbug(id).catch(() => {});
+  }
+}
+```
+
+```typescript
+// cli/group.ts — REMOVE: blanket close that kills all pools
+finally {
+  await closeLbug().catch(() => {});  // DELETE THIS
+}
+```
+
+Remove the `closeLbug` import from `cli/group.ts` — after removing the `finally` call it has no remaining usages.
+
+### Tests (unit level — mock pool adapter)
+
+- `syncGroup` closes only the pools it opened (mock `closeLbug`, assert called with specific ids)
+- Two-pool scenario: sync opens pools A and B, both closed in finally; pool C (opened elsewhere) not touched
+- CLI `sync` command does not call blanket `closeLbug()` (verify no zero-arg call in source — static check or grep-based test)
+
+---
+
+## Out of Scope
+
+- JSON -> LadybugDB migration (tracked in #606)
+- MEDIUM/LOW issues (items 5-10 from review summary)
+- Test gap coverage beyond what's needed for these 4 fixes
+- Any refactoring or architectural changes
+
+## Execution Order
+
+Fixes are independent — can be implemented in parallel or any order.
+Recommended order for review clarity: 1 -> 3 -> 4 -> 2 (simplest to most complex).

eslint.config.mjs

@@ -0,0 +1,83 @@
+import tsPlugin from '@typescript-eslint/eslint-plugin';
+import tsParser from '@typescript-eslint/parser';
+import unusedImports from 'eslint-plugin-unused-imports';
+import reactHooks from 'eslint-plugin-react-hooks';
+import prettierConfig from 'eslint-config-prettier';
+
+export default [
+  // Global ignores
+  {
+    ignores: [
+      '**/dist/**',
+      '**/node_modules/**',
+      '**/coverage/**',
+      'gitnexus/vendor/**',
+      'gitnexus-web/src/vendor/**',
+      'gitnexus/test/fixtures/**',
+      'gitnexus-web/playwright-report/**',
+      'gitnexus-web/test-results/**',
+      '**/*.d.ts',
+      '.claude/**',
+      '.history/**',
+    ],
+  },
+
+  // Base TypeScript config for all packages
+  {
+    files: ['**/*.{ts,tsx}'],
+    languageOptions: {
+      parser: tsParser,
+      parserOptions: {
+        ecmaVersion: 2022,
+        sourceType: 'module',
+      },
+    },
+    plugins: {
+      '@typescript-eslint': tsPlugin,
+      'unused-imports': unusedImports,
+    },
+    rules: {
+      // Unused imports — auto-fixable
+      'unused-imports/no-unused-imports': 'error',
+      'unused-imports/no-unused-vars': [
+        'warn',
+        { vars: 'all', varsIgnorePattern: '^_', args: 'after-used', argsIgnorePattern: '^_' },
+      ],
+
+      // TypeScript quality
+      '@typescript-eslint/no-unused-vars': 'off', // handled by unused-imports plugin
+      'no-unused-vars': 'off', // handled by unused-imports plugin
+      '@typescript-eslint/no-explicit-any': 'warn',
+      '@typescript-eslint/no-non-null-assertion': 'warn',
+
+      // General quality
+      'no-debugger': 'error',
+      'prefer-const': 'error',
+      'no-var': 'error',
+      eqeqeq: ['error', 'always', { null: 'ignore' }],
+    },
+  },
+
+  // CLI package — allow console.log (it's a CLI tool)
+  {
+    files: ['gitnexus/src/cli/**/*.ts', 'gitnexus/src/server/**/*.ts'],
+    rules: {
+      'no-console': 'off',
+    },
+  },
+
+  // React-specific rules for gitnexus-web
+  {
+    files: ['gitnexus-web/src/**/*.{ts,tsx}'],
+    plugins: {
+      'react-hooks': reactHooks,
+    },
+    rules: {
+      'react-hooks/rules-of-hooks': 'error',
+      'react-hooks/exhaustive-deps': 'warn',
+    },
+  },
+
+  // Disable formatting rules (prettier handles those)
+  prettierConfig,
+];

eval/configs/models/claude-haiku.yaml

@@ -1,8 +1,8 @@
 # Claude Haiku 4.5 — fast, cheap, good baseline
 # Via OpenRouter (set OPENROUTER_API_KEY in .env)
 model:
-  model_name: "openrouter/anthropic/claude-haiku-4.5"
-  cost_tracking: "ignore_errors"
+  model_name: 'openrouter/anthropic/claude-haiku-4.5'
+  cost_tracking: 'ignore_errors'
   model_kwargs:
     max_tokens: 8192
     temperature: 0

eval/configs/models/claude-opus.yaml

@@ -2,8 +2,8 @@
 # Via OpenRouter (set OPENROUTER_API_KEY in .env)
 # To use Anthropic directly, change to: anthropic/claude-opus-4-20250514
 model:
-  model_name: "openrouter/anthropic/claude-opus-4"
-  cost_tracking: "ignore_errors"
+  model_name: 'openrouter/anthropic/claude-opus-4'
+  cost_tracking: 'ignore_errors'
   model_kwargs:
     max_tokens: 16384
     temperature: 0

eval/configs/models/claude-sonnet.yaml

@@ -2,8 +2,8 @@
 # Via OpenRouter (set OPENROUTER_API_KEY in .env)
 # To use Anthropic directly, change to: anthropic/claude-sonnet-4-20250514
 model:
-  model_name: "openrouter/anthropic/claude-sonnet-4"
-  cost_tracking: "ignore_errors"
+  model_name: 'openrouter/anthropic/claude-sonnet-4'
+  cost_tracking: 'ignore_errors'
   model_kwargs:
     max_tokens: 16384
     temperature: 0

eval/configs/models/deepseek-chat.yaml

@@ -1,9 +1,9 @@
 model: deepseek-ai/deepseek-chat
 provider: openrouter
 cost:
-  input: 0.14  # per 1M tokens
-  output: 0.28  # per 1M tokens
-  
+  input: 0.14 # per 1M tokens
+  output: 0.28 # per 1M tokens
+
 # Native DeepSeek API (direct)
 api_key: null
 base_url: null

eval/configs/models/deepseek-v3.yaml

@@ -1,9 +1,9 @@
 model: deepseek-ai/DeepSeek-V3
 provider: openrouter
 cost:
-  input: 0.27  # per 1M tokens
-  output: 1.10  # per 1M tokens
-  
+  input: 0.27 # per 1M tokens
+  output: 1.10 # per 1M tokens
+
 # Native DeepSeek API (direct)
 # Get your API key at: https://platform.deepseek.com/
 # Or use OpenRouter with: OPENROUTER_API_KEY

eval/configs/models/glm-4.7.yaml

@@ -1,7 +1,7 @@
 # GLM 4.7 — via OpenRouter (set OPENROUTER_API_KEY in .env)
 model:
-  model_name: "openrouter/zhipuai/glm-4.7"
-  cost_tracking: "ignore_errors"
+  model_name: 'openrouter/zhipuai/glm-4.7'
+  cost_tracking: 'ignore_errors'
   model_kwargs:
     max_tokens: 8192
     temperature: 0

eval/configs/models/glm-5.yaml

@@ -1,7 +1,7 @@
 # GLM 5 — via OpenRouter (set OPENROUTER_API_KEY in .env)
 model:
-  model_name: "openrouter/zhipuai/glm-5"
-  cost_tracking: "ignore_errors"
+  model_name: 'openrouter/zhipuai/glm-5'
+  cost_tracking: 'ignore_errors'
   model_kwargs:
     max_tokens: 8192
     temperature: 0

eval/configs/models/minimax-2.5.yaml

@@ -1,7 +1,7 @@
 # MiniMax M1 2.5 — via OpenRouter (set OPENROUTER_API_KEY in .env)
 model:
-  model_name: "openrouter/minimax/minimax-m1-2.5"
-  cost_tracking: "ignore_errors"
+  model_name: 'openrouter/minimax/minimax-m1-2.5'
+  cost_tracking: 'ignore_errors'
   model_kwargs:
     max_tokens: 8192
     temperature: 0

eval/configs/models/minimax-m2.1.yaml

@@ -3,9 +3,9 @@
 # The action_regex tells mini-swe-agent to parse ```bash blocks from responses.
 model:
   model_class: litellm_textbased
-  model_name: "openrouter/minimax/minimax-m2.5"
+  model_name: 'openrouter/minimax/minimax-m2.5'
   action_regex: "```(?:bash|mswea_bash_command)\\s*\\n(.*?)\\n```"
-  cost_tracking: "ignore_errors"
+  cost_tracking: 'ignore_errors'
   model_kwargs:
     max_tokens: 8192
     temperature: 0

eval/configs/modes/baseline.yaml

@@ -1,9 +1,9 @@
 # Baseline mode — no GitNexus, pure mini-swe-agent (control group)
 agent:
-  agent_class: "eval.agents.gitnexus_agent.GitNexusAgent"
-  gitnexus_mode: "baseline"
+  agent_class: 'eval.agents.gitnexus_agent.GitNexusAgent'
+  gitnexus_mode: 'baseline'
   step_limit: 30
   cost_limit: 3.0
 
 environment:
-  environment_class: "docker"
+  environment_class: 'docker'

eval/configs/modes/native.yaml

@@ -5,14 +5,14 @@
 #
 # Use this mode to isolate the value of explicit tools without grep augmentation.
 agent:
-  agent_class: "eval.agents.gitnexus_agent.GitNexusAgent"
-  gitnexus_mode: "native"
+  agent_class: 'eval.agents.gitnexus_agent.GitNexusAgent'
+  gitnexus_mode: 'native'
   step_limit: 30
   cost_limit: 3.0
   track_gitnexus_usage: true
 
 environment:
-  environment_class: "eval.environments.gitnexus_docker.GitNexusDockerEnvironment"
+  environment_class: 'eval.environments.gitnexus_docker.GitNexusDockerEnvironment'
   enable_gitnexus: true
   skip_embeddings: true
   gitnexus_timeout: 120

eval/configs/modes/native_augment.yaml

@@ -8,8 +8,8 @@
 #
 # The agent decides when to use explicit tools vs rely on enriched grep results.
 agent:
-  agent_class: "eval.agents.gitnexus_agent.GitNexusAgent"
-  gitnexus_mode: "native_augment"
+  agent_class: 'eval.agents.gitnexus_agent.GitNexusAgent'
+  gitnexus_mode: 'native_augment'
   step_limit: 30
   cost_limit: 3.0
   augment_timeout: 5.0
@@ -17,7 +17,7 @@ agent:
   track_gitnexus_usage: true
 
 environment:
-  environment_class: "eval.environments.gitnexus_docker.GitNexusDockerEnvironment"
+  environment_class: 'eval.environments.gitnexus_docker.GitNexusDockerEnvironment'
   enable_gitnexus: true
   skip_embeddings: true
   gitnexus_timeout: 120

eval/pyproject.toml

@@ -6,7 +6,7 @@ readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [
     "mini-swe-agent>=2.0.0",
-    "litellm>=1.50.0",
+    "litellm>=1.50.0,!=1.82.7,!=1.82.8",
     "datasets>=3.0.0",
     "typer>=0.12.0",
     "rich>=13.0.0",

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

@@ -64,10 +64,26 @@ function extractPattern(toolName, toolInput) {
     const tokens = cmd.split(/\s+/);
     let foundCmd = false;
     let skipNext = false;
-    const flagsWithValues = new Set(['-e', '-f', '-m', '-A', '-B', '-C', '-g', '--glob', '-t', '--type', '--include', '--exclude']);
+    const flagsWithValues = new Set([
+      '-e',
+      '-f',
+      '-m',
+      '-A',
+      '-B',
+      '-C',
+      '-g',
+      '--glob',
+      '-t',
+      '--type',
+      '--include',
+      '--exclude',
+    ]);
 
     for (const token of tokens) {
-      if (skipNext) { skipNext = false; continue; }
+      if (skipNext) {
+        skipNext = false;
+        continue;
+      }
       if (!foundCmd) {
         if (/\brg$|\bgrep$/.test(token)) foundCmd = true;
         continue;
@@ -98,33 +114,42 @@ function runGitNexusCli(args, cwd, timeout) {
   // Detect whether 'gitnexus' is on PATH (cheap check, no execution)
   let useDirectBinary = false;
   try {
-    const which = spawnSync(
-      isWin ? 'where' : 'which', ['gitnexus'],
-      { encoding: 'utf-8', timeout: 3000, stdio: ['pipe', 'pipe', 'pipe'] }
-    );
+    const which = spawnSync(isWin ? 'where' : 'which', ['gitnexus'], {
+      encoding: 'utf-8',
+      timeout: 3000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
     useDirectBinary = which.status === 0;
-  } catch { /* not on PATH */ }
+  } catch {
+    /* not on PATH */
+  }
 
   if (useDirectBinary) {
-    return spawnSync(
-      isWin ? 'gitnexus.cmd' : 'gitnexus', args,
-      { encoding: 'utf-8', timeout, cwd, stdio: ['pipe', 'pipe', 'pipe'] }
-    );
+    return spawnSync(isWin ? 'gitnexus.cmd' : 'gitnexus', args, {
+      encoding: 'utf-8',
+      timeout,
+      cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
   }
   // npx fallback needs shell on Windows since npx is a .cmd script
-  return spawnSync(
-    isWin ? 'npx.cmd' : 'npx', ['-y', 'gitnexus', ...args],
-    { encoding: 'utf-8', timeout: timeout + 5000, cwd, stdio: ['pipe', 'pipe', 'pipe'] }
-  );
+  return spawnSync(isWin ? 'npx.cmd' : 'npx', ['-y', 'gitnexus', ...args], {
+    encoding: 'utf-8',
+    timeout: timeout + 5000,
+    cwd,
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
 }
 
 /**
  * Emit a hook response with additional context for the agent.
  */
 function sendHookResponse(hookEventName, message) {
-  console.log(JSON.stringify({
-    hookSpecificOutput: { hookEventName, additionalContext: message }
-  }));
+  console.log(
+    JSON.stringify({
+      hookSpecificOutput: { hookEventName, additionalContext: message },
+    }),
+  );
 }
 
 /**
@@ -149,7 +174,9 @@ function handlePreToolUse(input) {
     if (!child.error && child.status === 0) {
       result = child.stderr || '';
     }
-  } catch { /* graceful failure */ }
+  } catch {
+    /* graceful failure */
+  }
 
   if (result && result.trim()) {
     sendHookResponse('PreToolUse', result.trim());
@@ -185,10 +212,15 @@ function handlePostToolUse(input) {
   let currentHead = '';
   try {
     const headResult = spawnSync('git', ['rev-parse', 'HEAD'], {
-      encoding: 'utf-8', timeout: 3000, cwd, stdio: ['pipe', 'pipe', 'pipe'],
+      encoding: 'utf-8',
+      timeout: 3000,
+      cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
     });
     currentHead = (headResult.stdout || '').trim();
-  } catch { return; }
+  } catch {
+    return;
+  }
 
   if (!currentHead) return;
 
@@ -197,16 +229,19 @@ function handlePostToolUse(input) {
   try {
     const meta = JSON.parse(fs.readFileSync(path.join(gitNexusDir, 'meta.json'), 'utf-8'));
     lastCommit = meta.lastCommit || '';
-    hadEmbeddings = (meta.stats && meta.stats.embeddings > 0);
-  } catch { /* no meta — treat as stale */ }
+    hadEmbeddings = meta.stats && meta.stats.embeddings > 0;
+  } catch {
+    /* no meta — treat as stale */
+  }
 
   // If HEAD matches last indexed commit, no reindex needed
   if (currentHead && currentHead === lastCommit) return;
 
   const analyzeCmd = `npx gitnexus analyze${hadEmbeddings ? ' --embeddings' : ''}`;
-  sendHookResponse('PostToolUse',
+  sendHookResponse(
+    'PostToolUse',
     `GitNexus index is stale (last indexed: ${lastCommit ? lastCommit.slice(0, 7) : 'never'}). ` +
-    `Run \`${analyzeCmd}\` to update the knowledge graph.`
+      `Run \`${analyzeCmd}\` to update the knowledge graph.`,
   );
 }
 

gitnexus-shared/package-lock.json

@@ -0,0 +1,29 @@
+{
+  "name": "gitnexus-shared",
+  "version": "1.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "gitnexus-shared",
+      "version": "1.0.0",
+      "devDependencies": {
+        "typescript": "^6.0.2"
+      }
+    },
+    "node_modules/typescript": {
+      "version": "6.0.2",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-6.0.2.tgz",
+      "integrity": "sha512-bGdAIrZ0wiGDo5l8c++HWtbaNCWTS4UTv7RaTH/ThVIgjkveJt83m74bBHMJkuCbslY8ixgLBVZJIOiQlQTjfQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    }
+  }
+}

gitnexus-shared/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "gitnexus-shared",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Shared type definitions for GitNexus CLI and web",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "devDependencies": {
+    "typescript": "^6.0.2"
+  }
+}

gitnexus-shared/src/graph/types.ts

@@ -0,0 +1,134 @@
+/**
+ * Graph type definitions — single source of truth.
+ *
+ * Both gitnexus (CLI) and gitnexus-web import from this package.
+ * Do NOT add Node.js-specific or browser-specific imports here.
+ */
+
+import { SupportedLanguages } from '../languages.js';
+
+export type NodeLabel =
+  | 'Project'
+  | 'Package'
+  | 'Module'
+  | 'Folder'
+  | 'File'
+  | 'Class'
+  | 'Function'
+  | 'Method'
+  | 'Variable'
+  | 'Interface'
+  | 'Enum'
+  | 'Decorator'
+  | 'Import'
+  | 'Type'
+  | 'CodeElement'
+  | 'Community'
+  | 'Process'
+  // Multi-language node types
+  | 'Struct'
+  | 'Macro'
+  | 'Typedef'
+  | 'Union'
+  | 'Namespace'
+  | 'Trait'
+  | 'Impl'
+  | 'TypeAlias'
+  | 'Const'
+  | 'Static'
+  | 'Property'
+  | 'Record'
+  | 'Delegate'
+  | 'Annotation'
+  | 'Constructor'
+  | 'Template'
+  | 'Section'
+  | 'Route'
+  | 'Tool';
+
+export type NodeProperties = {
+  name: string;
+  filePath: string;
+  startLine?: number;
+  endLine?: number;
+  language?: SupportedLanguages | string;
+  isExported?: boolean;
+  astFrameworkMultiplier?: number;
+  astFrameworkReason?: string;
+  // Community
+  heuristicLabel?: string;
+  cohesion?: number;
+  symbolCount?: number;
+  keywords?: string[];
+  description?: string;
+  enrichedBy?: 'heuristic' | 'llm';
+  // Process
+  processType?: 'intra_community' | 'cross_community';
+  stepCount?: number;
+  communities?: string[];
+  entryPointId?: string;
+  terminalId?: string;
+  entryPointScore?: number;
+  entryPointReason?: string;
+  // Method/property
+  parameterCount?: number;
+  level?: number;
+  returnType?: string;
+  declaredType?: string;
+  visibility?: string;
+  isStatic?: boolean;
+  isReadonly?: boolean;
+  isAbstract?: boolean;
+  isFinal?: boolean;
+  isVirtual?: boolean;
+  isOverride?: boolean;
+  isAsync?: boolean;
+  isPartial?: boolean;
+  annotations?: string[];
+  // Route/response
+  responseKeys?: string[];
+  errorKeys?: string[];
+  middleware?: string[];
+  // Extensible
+  [key: string]: unknown;
+};
+
+export type RelationshipType =
+  | 'CONTAINS'
+  | 'CALLS'
+  | 'INHERITS'
+  | 'METHOD_OVERRIDES'
+  | 'METHOD_IMPLEMENTS'
+  | 'IMPORTS'
+  | 'USES'
+  | 'DEFINES'
+  | 'DECORATES'
+  | 'IMPLEMENTS'
+  | 'EXTENDS'
+  | 'HAS_METHOD'
+  | 'HAS_PROPERTY'
+  | 'ACCESSES'
+  | 'MEMBER_OF'
+  | 'STEP_IN_PROCESS'
+  | 'HANDLES_ROUTE'
+  | 'FETCHES'
+  | 'HANDLES_TOOL'
+  | 'ENTRY_POINT_OF'
+  | 'WRAPS'
+  | 'QUERIES';
+
+export interface GraphNode {
+  id: string;
+  label: NodeLabel;
+  properties: NodeProperties;
+}
+
+export interface GraphRelationship {
+  id: string;
+  sourceId: string;
+  targetId: string;
+  type: RelationshipType;
+  confidence: number;
+  reason: string;
+  step?: number;
+}

gitnexus-shared/src/index.ts

@@ -0,0 +1,25 @@
+// Graph types
+export type {
+  NodeLabel,
+  NodeProperties,
+  RelationshipType,
+  GraphNode,
+  GraphRelationship,
+} from './graph/types.js';
+
+// Schema constants
+export {
+  NODE_TABLES,
+  REL_TABLE_NAME,
+  REL_TYPES,
+  EMBEDDING_TABLE_NAME,
+} from './lbug/schema-constants.js';
+export type { NodeTableName, RelType } from './lbug/schema-constants.js';
+
+// Language support
+export { SupportedLanguages } from './languages.js';
+export { getLanguageFromFilename, getSyntaxLanguageFromFilename } from './language-detection.js';
+export type { MroStrategy } from './mro-strategy.js';
+
+// Pipeline progress
+export type { PipelinePhase, PipelineProgress } from './pipeline.js';

gitnexus-shared/src/language-detection.ts

@@ -0,0 +1,148 @@
+/**
+ * Language Detection — maps file paths to SupportedLanguages enum values.
+ *
+ * Shared between CLI (ingestion pipeline) and web (syntax highlighting).
+ *
+ * ADDING A NEW LANGUAGE:
+ * 1. Add enum member to SupportedLanguages in languages.ts
+ * 2. Add file extensions to EXTENSION_MAP below
+ * 3. TypeScript will error if you miss either step (exhaustive Record)
+ */
+
+import { SupportedLanguages } from './languages.js';
+
+/** Ruby extensionless filenames recognised as Ruby source */
+const RUBY_EXTENSIONLESS_FILES = new Set([
+  'Rakefile',
+  'Gemfile',
+  'Guardfile',
+  'Vagrantfile',
+  'Brewfile',
+]);
+
+/**
+ * Exhaustive map: every SupportedLanguages member → its file extensions.
+ *
+ * If a new language is added to the enum without adding an entry here,
+ * TypeScript emits a compile error: "Property 'NewLang' is missing in type..."
+ */
+const EXTENSION_MAP: Record<SupportedLanguages, readonly string[]> = {
+  [SupportedLanguages.JavaScript]: ['.js', '.jsx', '.mjs', '.cjs'],
+  [SupportedLanguages.TypeScript]: ['.ts', '.tsx', '.mts', '.cts'],
+  [SupportedLanguages.Python]: ['.py'],
+  [SupportedLanguages.Java]: ['.java'],
+  [SupportedLanguages.C]: ['.c'],
+  [SupportedLanguages.CPlusPlus]: ['.cpp', '.cc', '.cxx', '.h', '.hpp', '.hxx', '.hh'],
+  [SupportedLanguages.CSharp]: ['.cs'],
+  [SupportedLanguages.Go]: ['.go'],
+  [SupportedLanguages.Ruby]: ['.rb', '.rake', '.gemspec'],
+  [SupportedLanguages.Rust]: ['.rs'],
+  [SupportedLanguages.PHP]: ['.php', '.phtml', '.php3', '.php4', '.php5', '.php8'],
+  [SupportedLanguages.Kotlin]: ['.kt', '.kts'],
+  [SupportedLanguages.Swift]: ['.swift'],
+  [SupportedLanguages.Dart]: ['.dart'],
+  [SupportedLanguages.Vue]: ['.vue'],
+  [SupportedLanguages.Cobol]: ['.cbl', '.cob', '.cpy', '.cobol'],
+} satisfies Record<SupportedLanguages, readonly string[]>; // Ensure exhaustiveness
+
+/** Pre-built reverse lookup: extension → language (built once at module load). */
+const extToLang = new Map<string, SupportedLanguages>();
+for (const [lang, exts] of Object.entries(EXTENSION_MAP) as [
+  SupportedLanguages,
+  readonly string[],
+][]) {
+  for (const ext of exts) {
+    extToLang.set(ext, lang);
+  }
+}
+
+/**
+ * Map file extension to SupportedLanguage enum.
+ * Returns null if the file extension is not recognized.
+ */
+export const getLanguageFromFilename = (filename: string): SupportedLanguages | null => {
+  // Fast path: check the extension map
+  const lastDot = filename.lastIndexOf('.');
+  if (lastDot >= 0) {
+    const ext = filename.slice(lastDot).toLowerCase();
+    const lang = extToLang.get(ext);
+    if (lang !== undefined) return lang;
+  }
+
+  // Ruby extensionless files (Rakefile, Gemfile, etc.)
+  const basename = filename.split('/').pop() || filename;
+  if (RUBY_EXTENSIONLESS_FILES.has(basename)) {
+    return SupportedLanguages.Ruby;
+  }
+
+  return null;
+};
+
+/**
+ * Exhaustive map: every SupportedLanguages member → Prism syntax identifier.
+ *
+ * If a new language is added to the enum without adding an entry here,
+ * TypeScript emits a compile error.
+ */
+const SYNTAX_MAP: Record<SupportedLanguages, string> = {
+  [SupportedLanguages.JavaScript]: 'javascript',
+  [SupportedLanguages.TypeScript]: 'typescript',
+  [SupportedLanguages.Python]: 'python',
+  [SupportedLanguages.Java]: 'java',
+  [SupportedLanguages.C]: 'c',
+  [SupportedLanguages.CPlusPlus]: 'cpp',
+  [SupportedLanguages.CSharp]: 'csharp',
+  [SupportedLanguages.Go]: 'go',
+  [SupportedLanguages.Ruby]: 'ruby',
+  [SupportedLanguages.Rust]: 'rust',
+  [SupportedLanguages.PHP]: 'php',
+  [SupportedLanguages.Kotlin]: 'kotlin',
+  [SupportedLanguages.Swift]: 'swift',
+  [SupportedLanguages.Dart]: 'dart',
+  [SupportedLanguages.Vue]: 'typescript',
+  [SupportedLanguages.Cobol]: 'cobol',
+} satisfies Record<SupportedLanguages, string>; // Ensure exhaustiveness
+
+/** Non-code file extensions → Prism-compatible syntax identifiers */
+const AUXILIARY_SYNTAX_MAP: Record<string, string> = {
+  json: 'json',
+  yaml: 'yaml',
+  yml: 'yaml',
+  md: 'markdown',
+  mdx: 'markdown',
+  html: 'markup',
+  htm: 'markup',
+  erb: 'markup',
+  xml: 'markup',
+  css: 'css',
+  scss: 'css',
+  sass: 'css',
+  sh: 'bash',
+  bash: 'bash',
+  zsh: 'bash',
+  sql: 'sql',
+  toml: 'toml',
+  ini: 'ini',
+  dockerfile: 'docker',
+};
+
+/** Extensionless filenames → Prism-compatible syntax identifiers */
+const AUXILIARY_BASENAME_MAP: Record<string, string> = {
+  Makefile: 'makefile',
+  Dockerfile: 'docker',
+};
+
+/**
+ * Map file path to a Prism-compatible syntax highlight language string.
+ * Covers all SupportedLanguages (code files) plus common non-code formats.
+ * Returns 'text' for unrecognised files.
+ */
+export const getSyntaxLanguageFromFilename = (filePath: string): string => {
+  const lang = getLanguageFromFilename(filePath);
+  if (lang) return SYNTAX_MAP[lang];
+  const ext = filePath.split('.').pop()?.toLowerCase();
+  if (ext && ext in AUXILIARY_SYNTAX_MAP) return AUXILIARY_SYNTAX_MAP[ext];
+  const basename = filePath.split('/').pop() || '';
+  if (basename in AUXILIARY_BASENAME_MAP) return AUXILIARY_BASENAME_MAP[basename];
+  return 'text';
+};

gitnexus-shared/src/languages.ts

@@ -0,0 +1,25 @@
+/**
+ * Supported language enum — single source of truth.
+ *
+ * Both CLI and web use this to identify which language a file/node belongs to.
+ * The CLI uses it throughout the ingestion pipeline; the web uses it for display.
+ */
+export enum SupportedLanguages {
+  JavaScript = 'javascript',
+  TypeScript = 'typescript',
+  Python = 'python',
+  Java = 'java',
+  C = 'c',
+  CPlusPlus = 'cpp',
+  CSharp = 'csharp',
+  Go = 'go',
+  Ruby = 'ruby',
+  Rust = 'rust',
+  PHP = 'php',
+  Kotlin = 'kotlin',
+  Swift = 'swift',
+  Dart = 'dart',
+  Vue = 'vue',
+  /** Standalone regex processor — no tree-sitter, no LanguageProvider. */
+  Cobol = 'cobol',
+}

gitnexus-shared/src/lbug/schema-constants.ts

@@ -0,0 +1,74 @@
+/**
+ * LadybugDB schema constants — single source of truth.
+ *
+ * NODE_TABLES and REL_TYPES define what the knowledge graph can contain.
+ * Both CLI and web must agree on these for data compatibility.
+ *
+ * Full DDL schemas remain in each package's own schema.ts because
+ * the CLI uses native LadybugDB and the web uses WASM.
+ */
+
+export const NODE_TABLES = [
+  'File',
+  'Folder',
+  'Function',
+  'Class',
+  'Interface',
+  'Method',
+  'CodeElement',
+  'Community',
+  'Process',
+  'Section',
+  'Struct',
+  'Enum',
+  'Macro',
+  'Typedef',
+  'Union',
+  'Namespace',
+  'Trait',
+  'Impl',
+  'TypeAlias',
+  'Const',
+  'Static',
+  'Variable',
+  'Property',
+  'Record',
+  'Delegate',
+  'Annotation',
+  'Constructor',
+  'Template',
+  'Module',
+  'Route',
+  'Tool',
+] as const;
+
+export type NodeTableName = (typeof NODE_TABLES)[number];
+
+export const REL_TABLE_NAME = 'CodeRelation';
+
+export const REL_TYPES = [
+  'CONTAINS',
+  'DEFINES',
+  'IMPORTS',
+  'CALLS',
+  'EXTENDS',
+  'IMPLEMENTS',
+  'HAS_METHOD',
+  'HAS_PROPERTY',
+  'ACCESSES',
+  'METHOD_OVERRIDES',
+  'OVERRIDES', // Legacy compat alias — kept until all stored indexes are migrated
+  'METHOD_IMPLEMENTS',
+  'MEMBER_OF',
+  'STEP_IN_PROCESS',
+  'HANDLES_ROUTE',
+  'FETCHES',
+  'HANDLES_TOOL',
+  'ENTRY_POINT_OF',
+  'WRAPS',
+  'QUERIES',
+] as const;
+
+export type RelType = (typeof REL_TYPES)[number];
+
+export const EMBEDDING_TABLE_NAME = 'CodeEmbedding';

gitnexus-shared/src/mro-strategy.ts

@@ -0,0 +1,46 @@
+/**
+ * MRO (Method Resolution Order) strategy — shared canonical definition.
+ *
+ * Lives in `gitnexus-shared` so `model/resolve.ts` and `mro-processor.ts` share
+ * the type without importing the language registry (avoids circular coupling).
+ *
+ * `first-wins` (default, Java/C#/Kotlin/Go/Swift/Dart):
+ *   BFS ancestor walk in declaration order; first match wins.
+ *
+ * `leftmost-base` (C++):
+ *   BFS walk; HeritageMap preserves source insertion order, so BFS naturally
+ *   picks the leftmost base in diamond inheritance.
+ *
+ * `c3` (Python):
+ *   C3-linearization; falls back to BFS on cyclic/inconsistent hierarchy.
+ *   See model/resolve.ts § c3Linearize.
+ *
+ * `implements-split` (Java/C#/Kotlin):
+ *   Low-level lookup is BFS; graph-level mro-processor detects and warns on
+ *   interface-default method ambiguity.
+ *
+ * `qualified-syntax` (Rust):
+ *   No auto-resolution — `lookupMethodByOwnerWithMRO` returns undefined immediately.
+ *   Rust requires explicit `<Type as Trait>::method` syntax.
+ *
+ * `ruby-mixin` (Ruby):
+ *   Kind-aware walk that does NOT short-circuit on direct owner first (`prepend`
+ *   must beat the class's own method). Walk order:
+ *     1. Prepend providers (reverse declaration — last-prepended wins)
+ *     2. Direct owner's own methods
+ *     3. Include providers (reverse declaration)
+ *     4. Transitive ancestors (BFS fallback)
+ *   Singleton dispatch: caller passes `ancestryOverride` (extend providers only);
+ *   becomes a simple left-to-right scan. Miss NEVER falls through to file-scoped
+ *   lookup — null-routes or honors `fallback`.
+ *
+ * @see model/resolve.ts § lookupMethodByOwnerWithMRO
+ * @see languages/ruby.ts § selectDispatch
+ */
+export type MroStrategy =
+  | 'first-wins'
+  | 'c3'
+  | 'leftmost-base'
+  | 'implements-split'
+  | 'qualified-syntax'
+  | 'ruby-mixin';

gitnexus-shared/src/pipeline.ts

@@ -0,0 +1,29 @@
+/**
+ * Pipeline progress types — shared between CLI and web.
+ */
+
+export type PipelinePhase =
+  | 'idle'
+  | 'extracting'
+  | 'structure'
+  | 'parsing'
+  | 'imports'
+  | 'calls'
+  | 'heritage'
+  | 'communities'
+  | 'processes'
+  | 'enriching'
+  | 'complete'
+  | 'error';
+
+export interface PipelineProgress {
+  phase: PipelinePhase;
+  percent: number;
+  message: string;
+  detail?: string;
+  stats?: {
+    filesProcessed: number;
+    totalFiles: number;
+    nodesCreated: number;
+  };
+}

gitnexus-shared/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "composite": true,
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"]
+}

gitnexus-web/api/proxy.ts

@@ -1,104 +0,0 @@
-import type { VercelRequest, VercelResponse } from '@vercel/node';
-
-/**
- * CORS Proxy for isomorphic-git
- * 
- * isomorphic-git calls: /api/proxy?url=https://github.com/...
- */
-export default async function handler(req: VercelRequest, res: VercelResponse) {
-  // Handle CORS preflight
-  if (req.method === 'OPTIONS') {
-    res.setHeader('Access-Control-Allow-Origin', '*');
-    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
-    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, Git-Protocol, Accept');
-    res.status(200).end();
-    return;
-  }
-
-  // Get URL from query parameter
-  const { url } = req.query;
-  
-  if (!url || typeof url !== 'string') {
-    res.status(400).json({ error: 'Missing url query parameter' });
-    return;
-  }
-
-  // Only allow GitHub URLs for security
-  const allowedHosts = ['github.com', 'raw.githubusercontent.com'];
-  let parsedUrl: URL;
-  
-  try {
-    parsedUrl = new URL(url);
-  } catch {
-    res.status(400).json({ error: 'Invalid URL' });
-    return;
-  }
-  
-  if (!allowedHosts.some(host => parsedUrl.hostname.endsWith(host))) {
-    res.status(403).json({ error: 'Only GitHub URLs are allowed' });
-    return;
-  }
-
-  try {
-    const headers: Record<string, string> = {
-      'User-Agent': 'git/isomorphic-git',
-    };
-    
-    // Forward relevant headers
-    if (req.headers.authorization) {
-      headers['Authorization'] = req.headers.authorization as string;
-    }
-    if (req.headers['content-type']) {
-      headers['Content-Type'] = req.headers['content-type'] as string;
-    }
-    if (req.headers['git-protocol']) {
-      headers['Git-Protocol'] = req.headers['git-protocol'] as string;
-    }
-    if (req.headers.accept) {
-      headers['Accept'] = req.headers.accept as string;
-    }
-
-    // Get request body for POST requests
-    let body: Buffer | undefined;
-    if (req.method === 'POST') {
-      const chunks: Buffer[] = [];
-      for await (const chunk of req) {
-        chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
-      }
-      body = Buffer.concat(chunks);
-    }
-
-    const response = await fetch(url, {
-      method: req.method || 'GET',
-      headers,
-      body: body ? new Uint8Array(body) : undefined,
-    });
-
-    // Set CORS headers
-    res.setHeader('Access-Control-Allow-Origin', '*');
-    res.setHeader('Access-Control-Expose-Headers', '*');
-
-    // Forward response headers (except ones that cause issues)
-    const skipHeaders = [
-      'content-encoding', 
-      'transfer-encoding', 
-      'connection',
-      'www-authenticate', // IMPORTANT: Strip this to prevent browser's native auth popup!
-    ];
-    
-    response.headers.forEach((value, key) => {
-      if (!skipHeaders.includes(key.toLowerCase())) {
-        res.setHeader(key, value);
-      }
-    });
-
-    res.status(response.status);
-    const buffer = await response.arrayBuffer();
-    res.send(Buffer.from(buffer));
-    
-  } catch (error) {
-    console.error('Proxy error:', error);
-    res.status(500).json({ error: 'Proxy request failed', details: String(error) });
-  }
-}
-

gitnexus-web/e2e/debug-issues.spec.ts

@@ -1,4 +1,4 @@
-import { test, expect, type TestInfo } from '@playwright/test';
+import { test, expect } from '@playwright/test';
 
 /**
  * Debug harnesses for investigating specific UI issues.
@@ -9,7 +9,7 @@ const BACKEND_URL = process.env.BACKEND_URL ?? 'http://localhost:4747';
 const debugTest = process.env.DEBUG_E2E ? test : test.skip;
 
 async function connectToServer(page: import('@playwright/test').Page) {
-  page.on('console', msg => {
+  page.on('console', (msg) => {
     if (msg.type() === 'error') console.log(`[error] ${msg.text()}`);
   });
 
@@ -86,7 +86,10 @@ debugTest('debug: process view Reset View button', async ({ page }, testInfo) =>
 
   const transformAfterReset = await diagramDiv.getAttribute('style');
   console.log('Transform AFTER reset:', transformAfterReset);
-  await page.screenshot({ path: testInfo.outputPath('debug-modal-after-reset.png'), fullPage: true });
+  await page.screenshot({
+    path: testInfo.outputPath('debug-modal-after-reset.png'),
+    fullPage: true,
+  });
 
   // Verify transform actually changed back
   expect(transformAfterZoom).not.toBe(transformBefore);
@@ -123,5 +126,8 @@ debugTest('debug: lightbulb clears node selection dimming', async ({ page }, tes
   // Click it again to toggle back on
   await lightbulbBtn.click();
   await page.waitForTimeout(500);
-  await page.screenshot({ path: testInfo.outputPath('debug-after-lightbulb-toggle-back.png'), fullPage: true });
+  await page.screenshot({
+    path: testInfo.outputPath('debug-after-lightbulb-toggle-back.png'),
+    fullPage: true,
+  });
 });

gitnexus-web/e2e/heartbeat-reconnect.spec.ts

@@ -0,0 +1,109 @@
+import { test, expect } from '@playwright/test';
+
+/**
+ * E2E tests for heartbeat disconnect/reconnect behavior.
+ *
+ * Verifies the key regression: when the heartbeat fails, the UI shows a
+ * "reconnecting" banner instead of resetting to the onboarding screen.
+ *
+ * Strategy: block /api/heartbeat via route interception BEFORE loading the
+ * graph. The heartbeat EventSource can never connect, so onReconnecting
+ * fires on the first retry attempt. This reliably tests the banner behavior
+ * without depending on setOffline timing (which varies across CI environments).
+ */
+
+const BACKEND_URL = process.env.BACKEND_URL ?? 'http://localhost:4747';
+const FRONTEND_URL = process.env.FRONTEND_URL ?? 'http://localhost:5173';
+
+test.beforeAll(async () => {
+  if (process.env.E2E) return;
+  try {
+    const [backendRes, frontendRes] = await Promise.allSettled([
+      fetch(`${BACKEND_URL}/api/repos`),
+      fetch(FRONTEND_URL),
+    ]);
+    if (
+      backendRes.status === 'rejected' ||
+      (backendRes.status === 'fulfilled' && !backendRes.value.ok)
+    ) {
+      test.skip(true, 'gitnexus serve not available');
+      return;
+    }
+    if (
+      frontendRes.status === 'rejected' ||
+      (frontendRes.status === 'fulfilled' && !frontendRes.value.ok)
+    ) {
+      test.skip(true, 'Vite dev server not available');
+      return;
+    }
+    if (backendRes.status === 'fulfilled') {
+      const repos = await backendRes.value.json();
+      if (!repos.length) {
+        test.skip(true, 'No indexed repos');
+        return;
+      }
+    }
+  } catch {
+    test.skip(true, 'servers not available');
+  }
+});
+
+test.describe('Heartbeat Reconnect', () => {
+  test('shows reconnecting banner instead of onboarding reset when heartbeat is unavailable', async ({
+    page,
+  }) => {
+    // Block the heartbeat BEFORE navigating — the EventSource will fail
+    // immediately on every connection attempt, triggering onReconnecting.
+    await page.route('**/api/heartbeat', (route) => route.abort('connectionrefused'));
+
+    // Load the app and connect to a repo (all other endpoints work normally)
+    await page.goto('/');
+
+    const landingCard = page.locator('[data-testid="landing-repo-card"]').first();
+    try {
+      await landingCard.waitFor({ state: 'visible', timeout: 15_000 });
+      await landingCard.click();
+    } catch {
+      // auto-connect may skip the landing screen
+    }
+
+    // Wait for graph to load (heartbeat is blocked, but graph loads fine)
+    await expect(page.locator('[data-testid="status-ready"]')).toBeVisible({ timeout: 30_000 });
+
+    // The reconnecting banner should appear (heartbeat is failing)
+    const banner = page.getByText('Server connection lost');
+    await expect(banner).toBeVisible({ timeout: 15_000 });
+
+    // The graph canvas should STILL be visible — NOT reset to onboarding
+    await expect(page.locator('canvas').first()).toBeVisible();
+  });
+
+  test('banner clears when heartbeat becomes available', async ({ page }) => {
+    // Start with heartbeat blocked
+    await page.route('**/api/heartbeat', (route) => route.abort('connectionrefused'));
+
+    await page.goto('/');
+    const landingCard = page.locator('[data-testid="landing-repo-card"]').first();
+    try {
+      await landingCard.waitFor({ state: 'visible', timeout: 15_000 });
+      await landingCard.click();
+    } catch {
+      // auto-connect may skip the landing screen
+    }
+
+    await expect(page.locator('[data-testid="status-ready"]')).toBeVisible({ timeout: 30_000 });
+
+    // Verify banner appears
+    const banner = page.getByText('Server connection lost');
+    await expect(banner).toBeVisible({ timeout: 15_000 });
+
+    // Unblock heartbeat — the real server is running, so reconnect will succeed
+    await page.unroute('**/api/heartbeat');
+
+    // Banner should disappear as heartbeat reconnects
+    await expect(banner).not.toBeVisible({ timeout: 30_000 });
+
+    // Graph should still be there
+    await expect(page.locator('[data-testid="status-ready"]')).toBeVisible();
+  });
+});

gitnexus-web/e2e/manual-record.spec.ts

@@ -12,16 +12,16 @@ import { test } from '@playwright/test';
  */
 test.skip(
   !!process.env.CI || process.env.PWDEBUG !== '1',
-  'Manual recording requires --headed and PWDEBUG=1. Run: PWDEBUG=1 npx playwright test e2e/manual-record.spec.ts --headed --timeout=0'
+  'Manual recording requires --headed and PWDEBUG=1. Run: PWDEBUG=1 npx playwright test e2e/manual-record.spec.ts --headed --timeout=0',
 );
 
 test('manual recording session', async ({ page }) => {
-  page.on('console', msg => {
+  page.on('console', (msg) => {
     if (msg.type() === 'error' || msg.type() === 'warning') {
       console.log(`[${msg.type()}] ${msg.text()}`);
     }
   });
-  page.on('pageerror', err => console.log(`[crash] ${err.message}`));
+  page.on('pageerror', (err) => console.log(`[crash] ${err.message}`));
 
   await page.goto('http://localhost:5173');
   await page.pause();

gitnexus-web/e2e/multi-repo-scoping.spec.ts

@@ -0,0 +1,131 @@
+import { test, expect } from '@playwright/test';
+
+/**
+ * E2E tests for multi-repo scoping and URL persistence.
+ *
+ * Verifies that:
+ * - Connecting via ?server= loads data and sets ?project= in the URL
+ * - The repo name appears in the UI after connecting
+ * - F5 with ?server=&project= reconnects to the correct repo
+ *
+ * Runs against the single indexed repo in CI — validates the plumbing
+ * works end-to-end even with one repo.
+ */
+
+const BACKEND_URL = process.env.BACKEND_URL ?? 'http://localhost:4747';
+const FRONTEND_URL = process.env.FRONTEND_URL ?? 'http://localhost:5173';
+
+let firstRepoName: string;
+
+test.beforeAll(async () => {
+  if (process.env.E2E) {
+    // Still need to fetch the repo name for assertions
+    try {
+      const res = await fetch(`${BACKEND_URL}/api/repos`);
+      const repos = await res.json();
+      firstRepoName = repos[0]?.name ?? '';
+    } catch {
+      firstRepoName = '';
+    }
+    return;
+  }
+  try {
+    const [backendRes, frontendRes] = await Promise.allSettled([
+      fetch(`${BACKEND_URL}/api/repos`),
+      fetch(FRONTEND_URL),
+    ]);
+    if (
+      backendRes.status === 'rejected' ||
+      (backendRes.status === 'fulfilled' && !backendRes.value.ok)
+    ) {
+      test.skip(true, 'gitnexus serve not available');
+      return;
+    }
+    if (
+      frontendRes.status === 'rejected' ||
+      (frontendRes.status === 'fulfilled' && !frontendRes.value.ok)
+    ) {
+      test.skip(true, 'Vite dev server not available');
+      return;
+    }
+    if (backendRes.status === 'fulfilled') {
+      const repos = await backendRes.value.json();
+      if (!repos.length) {
+        test.skip(true, 'No indexed repos');
+        return;
+      }
+      firstRepoName = repos[0].name;
+    }
+  } catch {
+    test.skip(true, 'servers not available');
+  }
+});
+
+// Auto-connect downloads the full graph from the backend; under parallel
+// workers in CI the same backend serves multiple downloads concurrently, so
+// reaching the "Ready" state can take noticeably longer than a single-worker
+// run. Match the 45s budget used by waitForGraphLoaded() in
+// server-connect.spec.ts which has been stable on the same backend.
+const READY_TIMEOUT_MS = 45_000;
+
+test.describe('Multi-Repo Scoping', () => {
+  test('auto-connect via ?server= sets ?project= in URL', async ({ page }) => {
+    // Navigate with ?server= param (the bookmarkable shortcut)
+    await page.goto(`/?server=${encodeURIComponent(BACKEND_URL)}`);
+
+    // Wait for graph to load
+    await expect(page.locator('[data-testid="status-ready"]')).toBeVisible({
+      timeout: READY_TIMEOUT_MS,
+    });
+
+    // URL should now contain ?project= with the repo name
+    const url = new URL(page.url());
+    const project = url.searchParams.get('project');
+    expect(project).toBeTruthy();
+    expect(project).toBe(firstRepoName);
+  });
+
+  test('?server= is preserved in URL for F5 recovery', async ({ page }) => {
+    // Two sequential auto-connects (initial + reload), each up to READY_TIMEOUT_MS,
+    // can exceed the default 60s test timeout under parallel workers.
+    test.slow();
+
+    await page.goto(`/?server=${encodeURIComponent(BACKEND_URL)}`);
+    await expect(page.locator('[data-testid="status-ready"]')).toBeVisible({
+      timeout: READY_TIMEOUT_MS,
+    });
+
+    // URL should still have ?server=
+    const url = new URL(page.url());
+    expect(url.searchParams.get('server')).toBeTruthy();
+
+    // F5 should reconnect (not show onboarding)
+    await page.reload();
+    await expect(page.locator('[data-testid="status-ready"]')).toBeVisible({
+      timeout: READY_TIMEOUT_MS,
+    });
+  });
+
+  test('node count in status bar matches backend data', async ({ page }) => {
+    await page.goto(`/?server=${encodeURIComponent(BACKEND_URL)}`);
+    await expect(page.locator('[data-testid="status-ready"]')).toBeVisible({
+      timeout: READY_TIMEOUT_MS,
+    });
+
+    // Fetch expected node count from backend
+    const res = await fetch(`${BACKEND_URL}/api/repo?repo=${encodeURIComponent(firstRepoName)}`);
+    const repoInfo = await res.json();
+    const expectedNodes = repoInfo.stats?.nodes;
+
+    if (expectedNodes) {
+      // Status bar shows node count — use the status-ready area to avoid
+      // matching multiple elements (file tree, header may also show counts)
+      const statusBar = page.locator('footer');
+      const nodeText = statusBar.getByText(/\d+ nodes/).first();
+      await expect(nodeText).toBeVisible({ timeout: 10_000 });
+      const text = await nodeText.textContent();
+      const displayedNodes = parseInt(text?.match(/(\d+)\s*nodes/)?.[1] ?? '0', 10);
+      expect(displayedNodes).toBeGreaterThan(0);
+    }
+  });
+});

gitnexus-web/e2e/onboarding.spec.ts

@@ -0,0 +1,307 @@
+import { test, expect } from '@playwright/test';
+
+/**
+ * E2E tests for the onboarding and analysis user flows.
+ *
+ * These tests cover:
+ *   - Flow 1: OnboardingGuide shown when no server is running
+ *   - Flow 2: Analyze form when server has zero repos
+ *   - Flow 3: Auto-connect when server has repos
+ *   - Flow 4: Repo dropdown in exploring view
+ *
+ * Most tests mock the backend at the network level so they don't
+ * require a live gitnexus server.
+ */
+
+const BACKEND_URL = 'http://localhost:4747';
+
+async function enterExploringView(page: import('@playwright/test').Page) {
+  await page.goto('/');
+
+  const landingCard = page.locator('[data-testid="landing-repo-card"]').first();
+  try {
+    await landingCard.waitFor({ state: 'visible', timeout: 15_000 });
+    await landingCard.click();
+  } catch {
+    // Landing screen may not appear (e.g. ?server auto-connect)
+  }
+
+  // Match the 45s budget used by waitForGraphLoaded() in
+  // server-connect.spec.ts; under parallel CI workers, downloading the full
+  // graph can occasionally exceed 30s.
+  await expect(page.locator('[data-testid="status-ready"]')).toBeVisible({ timeout: 45_000 });
+}
+
+// ── Flow 1: Onboarding (no server running) ─────────────────────────────────
+
+test.describe('Flow 1: Onboarding — no server', () => {
+  test('shows OnboardingGuide when backend is unreachable', async ({ page }, testInfo) => {
+    // Block all requests to the backend so the probe fails
+    await page.route(`${BACKEND_URL}/**`, (route) => route.abort('connectionrefused'));
+
+    await page.goto('/');
+
+    // Wait for initial probe to complete and onboarding to appear
+    await expect(page.getByText('Start your local server')).toBeVisible({ timeout: 10_000 });
+    await page.screenshot({ path: testInfo.outputPath('onboarding-visible.png') });
+  });
+
+  test('shows step-by-step instructions', async ({ page }) => {
+    await page.route(`${BACKEND_URL}/**`, (route) => route.abort('connectionrefused'));
+    await page.goto('/');
+
+    // Step 1 is active (done once polling starts)
+    await expect(page.getByText('Copy the command')).toBeAttached({ timeout: 10_000 });
+    // Step 2 title changes to "Waiting for server to start" once polling begins
+    await expect(page.getByText('Waiting for server to start')).toBeAttached({ timeout: 10_000 });
+    // Step 3 is always rendered
+    await expect(page.getByText('Auto-connects and opens the graph')).toBeAttached({
+      timeout: 5_000,
+    });
+  });
+
+  test('shows terminal window with command', async ({ page }) => {
+    await page.route(`${BACKEND_URL}/**`, (route) => route.abort('connectionrefused'));
+    await page.goto('/');
+
+    // Should show either dev or prod command in a terminal block
+    const terminal = page.locator('code');
+    await expect(terminal.first()).toBeVisible({ timeout: 10_000 });
+
+    // The $ prompt should be present
+    await expect(page.getByText('$')).toBeVisible();
+  });
+
+  test('shows polling indicator', async ({ page }) => {
+    await page.route(`${BACKEND_URL}/**`, (route) => route.abort('connectionrefused'));
+    await page.goto('/');
+
+    // Polling starts after initial probe fails
+    await expect(page.getByText('Listening for server')).toBeVisible({ timeout: 10_000 });
+  });
+
+  test('shows Node.js version requirement', async ({ page }) => {
+    await page.route(`${BACKEND_URL}/**`, (route) => route.abort('connectionrefused'));
+    await page.goto('/');
+
+    await expect(page.getByText(/Node\.js.*\d+/)).toBeVisible({ timeout: 10_000 });
+    await expect(page.getByText('Port 4747')).toBeVisible();
+  });
+
+  test('copy button has accessible label', async ({ page }) => {
+    await page.route(`${BACKEND_URL}/**`, (route) => route.abort('connectionrefused'));
+    await page.goto('/');
+
+    await expect(page.getByText('Copy the command')).toBeVisible({ timeout: 10_000 });
+    const copyBtn = page.getByLabel('Copy to clipboard').first();
+    await expect(copyBtn).toBeVisible();
+  });
+});
+
+// ── Flow 2: Server detected → success → auto-connect ──────────────────────
+
+test.describe('Flow 2: Server detected — auto-connect', () => {
+  test('shows success card when server becomes reachable', async ({ page }, testInfo) => {
+    // Start with server unreachable
+    let blockBackend = true;
+    await page.route(`${BACKEND_URL}/**`, (route) => {
+      if (blockBackend) return route.abort('connectionrefused');
+      // Let it through to the real handler below
+      return route.fallback();
+    });
+
+    // Mock the backend responses for when we "start" the server
+    await page.route(`${BACKEND_URL}/api/repos`, async (route) => {
+      if (blockBackend) return route.abort('connectionrefused');
+      await route.fulfill({ json: [{ name: 'test-repo', path: '/tmp/test' }] });
+    });
+    await page.route(`${BACKEND_URL}/api/repo`, async (route) => {
+      if (blockBackend) return route.abort('connectionrefused');
+      await route.fulfill({
+        json: { name: 'test-repo', path: '/tmp/test', repoPath: '/tmp/test' },
+      });
+    });
+    await page.route(`${BACKEND_URL}/api/graph**`, async (route) => {
+      if (blockBackend) return route.abort('connectionrefused');
+      await route.fulfill({ json: { nodes: [], relationships: [] } });
+    });
+    await page.route(`${BACKEND_URL}/api/heartbeat`, async (route) => {
+      if (blockBackend) return route.abort('connectionrefused');
+      // SSE response
+      await route.fulfill({
+        status: 200,
+        headers: { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache' },
+        body: ':ok\n\n',
+      });
+    });
+
+    await page.goto('/');
+
+    // Verify onboarding is shown first
+    await expect(page.getByText('Start your local server')).toBeVisible({ timeout: 10_000 });
+    await page.screenshot({ path: testInfo.outputPath('before-server-start.png') });
+
+    // "Start" the server by unblocking requests
+    blockBackend = false;
+
+    // Wait for success card
+    await expect(page.getByText('Server Connected')).toBeVisible({ timeout: 15_000 });
+    await page.screenshot({ path: testInfo.outputPath('success-card.png') });
+  });
+
+  test('transitions to analyze phase when server has zero repos', async ({ page }, testInfo) => {
+    // Mock server with zero repos — repos endpoint returns empty array
+    await page.route(`${BACKEND_URL}/api/repos`, (route) => route.fulfill({ json: [] }));
+    await page.route(`${BACKEND_URL}/api/info`, (route) =>
+      route.fulfill({ json: { version: '1.0.0', launchContext: 'npx', nodeVersion: 'v22.0.0' } }),
+    );
+    await page.route(`${BACKEND_URL}/api/heartbeat`, (route) =>
+      route.fulfill({
+        status: 200,
+        headers: { 'Content-Type': 'text/event-stream' },
+        body: ':ok\n\n',
+      }),
+    );
+
+    await page.goto('/');
+
+    // Should transition: onboarding → success → analyze (zero repos)
+    // The analyze form tabs should be visible
+    await expect(page.getByRole('tab', { name: 'GitHub URL' })).toBeVisible({ timeout: 20_000 });
+    await expect(page.getByRole('tab', { name: 'Local Folder' })).toBeVisible();
+    await page.screenshot({ path: testInfo.outputPath('analyze-empty-state.png') });
+  });
+});
+
+// ── Flow 3: Analyze form ───────────────────────────────────────────────────
+
+test.describe('Flow 3: Analyze form', () => {
+  test.beforeEach(async ({ page }) => {
+    // Mock server with zero repos to show the analyze form
+    await page.route(`${BACKEND_URL}/api/repos`, (route) => route.fulfill({ json: [] }));
+    await page.route(`${BACKEND_URL}/api/info`, (route) =>
+      route.fulfill({ json: { version: '1.0.0', launchContext: 'npx', nodeVersion: 'v22.0.0' } }),
+    );
+    await page.route(`${BACKEND_URL}/api/heartbeat`, (route) =>
+      route.fulfill({
+        status: 200,
+        headers: { 'Content-Type': 'text/event-stream' },
+        body: ':ok\n\n',
+      }),
+    );
+  });
+
+  test('GitHub URL tab validates input', async ({ page }, testInfo) => {
+    await page.goto('/');
+
+    // Wait for analyze form (transition: onboarding → success → analyze)
+    await expect(page.getByRole('tab', { name: 'GitHub URL' })).toBeVisible({ timeout: 20_000 });
+
+    // Type an invalid URL
+    const input = page.locator('input[type="url"]');
+    await input.fill('not-a-url');
+
+    // Analyze button should be visible but disabled
+    const analyzeBtn = page.getByRole('button', { name: /Analyze Repository/ });
+    await expect(analyzeBtn).toBeVisible();
+
+    // Type a valid GitHub URL
+    await input.fill('https://github.com/anthropics/courses');
+    await page.screenshot({ path: testInfo.outputPath('valid-github-url.png') });
+  });
+
+  test('Local Folder tab shows browse button', async ({ page }, testInfo) => {
+    await page.goto('/');
+
+    await expect(page.getByRole('tab', { name: 'Local Folder' })).toBeVisible({ timeout: 20_000 });
+
+    // Switch to Local Folder tab
+    await page.getByRole('tab', { name: 'Local Folder' }).click();
+
+    // Browse button should be visible
+    await expect(page.getByText('Browse for folder')).toBeVisible();
+    await page.screenshot({ path: testInfo.outputPath('local-folder-tab.png') });
+  });
+
+  test('switching tabs clears input', async ({ page }) => {
+    await page.goto('/');
+
+    await expect(page.getByRole('tab', { name: 'GitHub URL' })).toBeVisible({ timeout: 20_000 });
+
+    // Type in GitHub URL
+    const urlInput = page.locator('input[type="url"]');
+    await urlInput.fill('https://github.com/test/repo');
+
+    // Switch to Local Folder
+    await page.getByRole('tab', { name: 'Local Folder' }).click();
+
+    // Switch back to GitHub URL — input should be empty
+    await page.getByRole('tab', { name: 'GitHub URL' }).click();
+    const newUrlInput = page.locator('input[type="url"]');
+    await expect(newUrlInput).toHaveValue('');
+  });
+});
+
+// ── Flow 4: Repo dropdown (requires running server) ────────────────────────
+
+test.describe('Flow 4: Repo dropdown in exploring view', () => {
+  const SKIP_MSG = 'Requires running gitnexus server with indexed repos';
+
+  // enterExploringView() can take up to ~45s under parallel CI workers; combined
+  // with the dropdown interactions this can exceed the default 60s test budget.
+  test.slow();
+
+  test.beforeAll(async () => {
+    if (process.env.E2E) return;
+    try {
+      const res = await fetch(`${BACKEND_URL}/api/repos`);
+      if (!res.ok) {
+        test.skip(true, SKIP_MSG);
+        return;
+      }
+      const repos = await res.json();
+      if (!repos.length) {
+        test.skip(true, 'Server has no indexed repos');
+        return;
+      }
+    } catch {
+      test.skip(true, SKIP_MSG);
+    }
+  });
+
+  test('project badge opens repo dropdown', async ({ page }, testInfo) => {
+    await enterExploringView(page);
+    await page.screenshot({ path: testInfo.outputPath('exploring-loaded.png') });
+
+    // Click the project badge (has a chevron)
+    const badge = page
+      .locator('header button')
+      .filter({ has: page.locator('svg') })
+      .first();
+    await badge.click();
+
+    // Repo dropdown should be visible
+    await expect(page.getByText('Repositories')).toBeVisible({ timeout: 5_000 });
+    await expect(page.getByText('Analyze a new repository')).toBeVisible();
+    await page.screenshot({ path: testInfo.outputPath('repo-dropdown-open.png') });
+  });
+
+  test('analyze option opens inline form', async ({ page }, testInfo) => {
+    await enterExploringView(page);
+
+    // Open repo dropdown
+    const badge = page
+      .locator('header button')
+      .filter({ has: page.locator('svg') })
+      .first();
+    await badge.click();
+
+    // Click "Analyze a new repository..."
+    await page.getByText('Analyze a new repository').click();
+
+    // Should show the analyze form inline
+    await expect(page.getByText('GitHub URL')).toBeVisible({ timeout: 5_000 });
+    await expect(page.getByText('Local Folder')).toBeVisible();
+    await page.screenshot({ path: testInfo.outputPath('inline-analyze-form.png') });
+  });
+});

gitnexus-web/e2e/repo-switching.spec.ts

@@ -0,0 +1,189 @@
+import { test, expect } from '@playwright/test';
+
+/**
+ * E2E tests for the repo-switching and false-404 fixes.
+ *
+ * Most tests use the live backend (same pattern as multi-repo-scoping.spec.ts).
+ * The 503 hold-queue test uses route interception to simulate a slow analysis.
+ */
+
+const BACKEND_URL = process.env.BACKEND_URL ?? 'http://localhost:4747';
+const FRONTEND_URL = process.env.FRONTEND_URL ?? 'http://localhost:5173';
+
+let firstRepoName: string;
+
+test.beforeAll(async () => {
+  if (process.env.E2E) {
+    try {
+      const res = await fetch(`${BACKEND_URL}/api/repos`);
+      const repos = await res.json();
+      firstRepoName = repos[0]?.name ?? '';
+    } catch {
+      firstRepoName = '';
+    }
+    return;
+  }
+  try {
+    const [backendRes, frontendRes] = await Promise.allSettled([
+      fetch(`${BACKEND_URL}/api/repos`),
+      fetch(FRONTEND_URL),
+    ]);
+    if (
+      backendRes.status === 'rejected' ||
+      (backendRes.status === 'fulfilled' && !backendRes.value.ok)
+    ) {
+      test.skip(true, 'gitnexus serve not available');
+      return;
+    }
+    if (
+      frontendRes.status === 'rejected' ||
+      (frontendRes.status === 'fulfilled' && !frontendRes.value.ok)
+    ) {
+      test.skip(true, 'Vite dev server not available');
+      return;
+    }
+    if (backendRes.status === 'fulfilled') {
+      const repos = await backendRes.value.json();
+      if (!repos.length) {
+        test.skip(true, 'No indexed repos');
+        return;
+      }
+      firstRepoName = repos[0].name;
+    }
+  } catch {
+    test.skip(true, 'servers not available');
+  }
+});
+
+// ── 1. Hold-queue: 503 → descriptive user message ────────────────────────────
+
+test.describe('Hold-queue timeout error', () => {
+  test('shows descriptive message when /api/repo returns 503', async ({ page }, testInfo) => {
+    // Intercept only /api/repo (singular) — not /api/repos — to return a 503
+    // regex: /api/repo followed by end, ?, or # — NOT /api/repos
+    await page.route(/\/api\/repo(?!s)(\?.*)?$/, (route) =>
+      route.fulfill({
+        status: 503,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          error: `Repository analysis for "${firstRepoName}" is taking longer than expected. Please try again in a moment.`,
+        }),
+      }),
+    );
+
+    await page.goto(`/?server=${encodeURIComponent(BACKEND_URL)}`);
+
+    // UI should show the 503 error message
+    await expect(page.getByText(/taking longer than expected/i)).toBeVisible({
+      timeout: 20_000,
+    });
+
+    await page.screenshot({ path: testInfo.outputPath('hold-queue-503.png') });
+  });
+});
+
+// ── 2. ?project= URL persistence ─────────────────────────────────────────────
+
+// Auto-connect downloads the full graph from the backend; under parallel
+// workers in CI the same backend serves multiple downloads concurrently, so
+// reaching the "Ready" state can take noticeably longer than a single-worker
+// run. Match the 45s budget used by waitForGraphLoaded() in
+// server-connect.spec.ts which has been stable on the same backend.
+const READY_TIMEOUT_MS = 45_000;
+
+test.describe('?project= URL persistence', () => {
+  test('?project= is set in URL after connecting via ?server=', async ({ page }) => {
+    await page.goto(`/?server=${encodeURIComponent(BACKEND_URL)}`);
+
+    await expect(page.locator('[data-testid="status-ready"]')).toBeVisible({
+      timeout: READY_TIMEOUT_MS,
+    });
+
+    const url = new URL(page.url());
+    const project = url.searchParams.get('project');
+    expect(project).toBeTruthy();
+    // first repo returned by the live backend
+    if (firstRepoName) expect(project).toBe(firstRepoName);
+  });
+
+  test('?project= is still present after F5 reload', async ({ page }) => {
+    // Two sequential auto-connects (initial + reload), each up to READY_TIMEOUT_MS,
+    // can exceed the default 60s test timeout under parallel workers.
+    test.slow();
+
+    await page.goto(`/?server=${encodeURIComponent(BACKEND_URL)}`);
+    await expect(page.locator('[data-testid="status-ready"]')).toBeVisible({
+      timeout: READY_TIMEOUT_MS,
+    });
+
+    // After connect, URL has ?server=&project= — F5 re-uses both params
+    await page.reload();
+    await expect(page.locator('[data-testid="status-ready"]')).toBeVisible({
+      timeout: READY_TIMEOUT_MS,
+    });
+
+    const url = new URL(page.url());
+    expect(url.searchParams.get('project')).toBeTruthy();
+  });
+});
+
+// ── 3. ?project= + ?server= combined auto-connect ────────────────────────────
+
+test.describe('?project= auto-connect', () => {
+  test('navigating with ?server=&project= connects to the correct repo', async ({
+    page,
+  }, testInfo) => {
+    if (!firstRepoName) test.skip(true, 'no repo name available');
+
+    await page.goto(
+      `/?server=${encodeURIComponent(BACKEND_URL)}&project=${encodeURIComponent(firstRepoName)}`,
+    );
+
+    await expect(page.locator('[data-testid="status-ready"]')).toBeVisible({
+      timeout: READY_TIMEOUT_MS,
+    });
+
+    // ?project= in URL should match what we passed in
+    const url = new URL(page.url());
+    expect(url.searchParams.get('project')).toBe(firstRepoName);
+
+    await page.screenshot({ path: testInfo.outputPath('project-param-connect.png') });
+  });
+});
+
+// ── 4. Windows path normalization ─────────────────────────────────────────────
+
+test.describe('Windows path normalization', () => {
+  test('project name uses basename when /api/repo returns a Windows-style repoPath', async ({
+    page,
+  }) => {
+    const repoName = firstRepoName || 'test-repo';
+    const windowsPath = `C:\\Users\\LENOVO\\.gitnexus\\repos\\${repoName}`;
+
+    // Mock /api/repo to return a Windows backslash path while keeping name correct
+    await page.route(/\/api\/repo(?!s)(\?.*)?$/, (route) =>
+      route.fulfill({
+        contentType: 'application/json',
+        body: JSON.stringify({
+          // intentionally omit `name` to force path-based extraction
+          path: windowsPath,
+          repoPath: windowsPath,
+        }),
+      }),
+    );
+
+    await page.goto(`/?server=${encodeURIComponent(BACKEND_URL)}`);
+
+    await expect(page.locator('[data-testid="status-ready"]')).toBeVisible({
+      timeout: READY_TIMEOUT_MS,
+    });
+
+    // URL ?project= must be the short basename, NOT the full Windows path
+    const url = new URL(page.url());
+    const project = url.searchParams.get('project');
+    expect(project).toBeTruthy();
+    expect(project).not.toContain('\\');
+    expect(project).not.toContain('LENOVO');
+    expect(project).toBe(repoName);
+  });
+});

gitnexus-web/e2e/server-connect.spec.ts

@@ -1,9 +1,10 @@
-import { test, expect, type TestInfo } from '@playwright/test';
+import { test, expect } from '@playwright/test';
 
 /**
- * E2E tests for the GitNexus web UI.
+ * E2E tests for the GitNexus web UI — exploring view features.
+ *
  * Requires:
- *   - gitnexus serve running on localhost:4747
+ *   - gitnexus serve running on localhost:4747 with at least one indexed repo
  *   - gitnexus-web dev server running on localhost:5173
  *
  * Skipped when servers aren't available (CI without services, etc.).
@@ -12,95 +13,103 @@ import { test, expect, type TestInfo } from '@playwright/test';
 
 const BACKEND_URL = process.env.BACKEND_URL ?? 'http://localhost:4747';
 const FRONTEND_URL = process.env.FRONTEND_URL ?? 'http://localhost:5173';
-// Skip all tests if the gitnexus server or Vite dev server isn't reachable
+
 test.beforeAll(async () => {
-  if (process.env.E2E) return; // force-run
+  if (process.env.E2E) return;
   try {
     const [backendRes, frontendRes] = await Promise.allSettled([
       fetch(`${BACKEND_URL}/api/repos`),
       fetch(FRONTEND_URL),
     ]);
-    if (backendRes.status === 'rejected' || (backendRes.status === 'fulfilled' && !backendRes.value.ok)) {
+    if (
+      backendRes.status === 'rejected' ||
+      (backendRes.status === 'fulfilled' && !backendRes.value.ok)
+    ) {
       test.skip(true, 'gitnexus serve not available on :4747');
       return;
     }
-    if (frontendRes.status === 'rejected' || (frontendRes.status === 'fulfilled' && !frontendRes.value.ok)) {
+    if (
+      frontendRes.status === 'rejected' ||
+      (frontendRes.status === 'fulfilled' && !frontendRes.value.ok)
+    ) {
       test.skip(true, 'Vite dev server not available on :5173');
       return;
     }
+    // Check there's at least one indexed repo
+    if (backendRes.status === 'fulfilled') {
+      const repos = await backendRes.value.json();
+      if (!repos.length) {
+        test.skip(true, 'No indexed repos — run gitnexus analyze first');
+        return;
+      }
+    }
   } catch {
     test.skip(true, 'servers not available');
   }
 });
 
-/** Shared helper: connect to the local server and wait for the graph to load */
-async function connectAndWaitForGraph(page: import('@playwright/test').Page, testInfo: TestInfo) {
-  // Signal to the app that we are running under Playwright (used to skip heavy Ladybug loads).
-  await page.addInitScript(() => {
-    (window as unknown as { __PLAYWRIGHT_TEST__?: boolean }).__PLAYWRIGHT_TEST__ = true;
-  });
-
+/**
+ * Wait for the server-detection flow to complete.
+ *
+ * The app auto-detects the server, then either:
+ *   - shows the landing screen when indexed repos exist, or
+ *   - goes straight into analyze onboarding when there are zero repos.
+ *
+ * For these tests we require at least one indexed repo, so pick the first
+ * landing card when present and then wait for the exploring view.
+ */
+async function waitForGraphLoaded(page: import('@playwright/test').Page) {
   await page.goto('/');
 
-  // Wait for the app to fully render before interacting
-  const serverTab = page.getByRole('button', { name: 'Server' });
-  await expect(serverTab).toBeVisible({ timeout: 15_000 });
-  await page.screenshot({ path: testInfo.outputPath('step-1-landing.png') });
+  const landingCards = page.locator('[data-testid="landing-repo-card"]');
+  const preferredLandingCard = landingCards
+    .filter({ hasText: /GitNexus|local-integration/ })
+    .first();
+  try {
+    await landingCards.first().waitFor({ state: 'visible', timeout: 15_000 });
+    const landingCard =
+      (await preferredLandingCard.count()) > 0 ? preferredLandingCard : landingCards.first();
+    await landingCard.click();
+  } catch {
+    // Landing screen may not appear (e.g. ?server auto-connect)
+  }
 
-  // Click "Server" tab and wait for the input to appear
-  await serverTab.click();
-  const serverInput = page.locator('input[name="server-url-input"]');
-  await expect(serverInput).toBeVisible({ timeout: 15_000 });
-  await page.screenshot({ path: testInfo.outputPath('step-2-server-tab.png') });
-  await serverInput.fill(BACKEND_URL);
-  await page.screenshot({ path: testInfo.outputPath('step-3-url-filled.png') });
-
-  await page.getByRole('button', { name: /Connect/ }).click();
-
-  // Wait for graph to load — status bar shows "Ready"
-  await expect(page.locator('[data-testid="status-ready"]')).toBeVisible({ timeout: 30_000 });
-  await expect(page.getByText(/\d+ nodes/).first()).toBeVisible();
-  await page.screenshot({ path: testInfo.outputPath('step-4-graph-loaded.png') });
+  const statusBar = page.getByRole('contentinfo');
+  await expect(statusBar.getByText('Ready', { exact: true })).toBeVisible({ timeout: 45_000 });
+  await expect(statusBar).toContainText(/nodes/, {
+    timeout: 20_000,
+  });
 }
 
 test.describe('Server Connection & Graph Loading', () => {
-  test('connects to server and loads graph', async ({ page }, testInfo) => {
-    await connectAndWaitForGraph(page, testInfo);
-    await page.screenshot({ path: testInfo.outputPath('graph-loaded.png'), fullPage: true });
+  test('selects a repo from landing and loads graph', async ({ page }) => {
+    await waitForGraphLoaded(page);
   });
 });
 
 test.describe('Nexus AI', () => {
-  test('panel opens and agent initializes without error', async ({ page }, testInfo) => {
-    await connectAndWaitForGraph(page, testInfo);
+  test('panel opens and agent initializes without error', async ({ page }) => {
+    await waitForGraphLoaded(page);
 
-    // Click Nexus AI button to open the panel
     await page.getByRole('button', { name: 'Nexus AI' }).click();
-
-    // Should see the Nexus AI tab content
     await expect(page.getByText('Ask me anything')).toBeVisible({ timeout: 15_000 });
 
-    await page.screenshot({ path: testInfo.outputPath('nexus-ai-panel.png'), fullPage: true });
-
-    // "Database not ready" should NOT be visible
     const errorBanner = page.getByText('Database not ready');
     expect(await errorBanner.isVisible().catch(() => false)).toBe(false);
   });
 });
 
 test.describe('Processes Panel', () => {
-  test('shows process list and View button works', async ({ page }, testInfo) => {
-    await connectAndWaitForGraph(page, testInfo);
+  test('shows process list and View button works', async ({ page }) => {
+    await waitForGraphLoaded(page);
 
-    // Open Nexus AI panel, switch to Processes tab
     await page.getByRole('button', { name: 'Nexus AI' }).click();
     await page.getByText('Processes').click();
 
-    // Should show process count — wait for data-testid instead of fixed timeout
-    await expect(page.locator('[data-testid="process-list-loaded"]')).toBeVisible({ timeout: 15_000 });
-    await page.screenshot({ path: testInfo.outputPath('processes-panel.png'), fullPage: true });
+    await expect(page.locator('[data-testid="process-list-loaded"]')).toBeVisible({
+      timeout: 15_000,
+    });
 
-    // Hover first process item to reveal View button, then click it
     const processRow = page.locator('[data-testid="process-row"]').first();
     await expect(processRow).toBeVisible({ timeout: 10_000 });
     await processRow.hover();
@@ -108,21 +117,18 @@ test.describe('Processes Panel', () => {
     const viewBtn = processRow.locator('[data-testid="process-view-button"]');
     await viewBtn.waitFor({ state: 'visible', timeout: 5_000 });
     await viewBtn.click();
-    // Wait for modal to appear
     await expect(page.locator('[data-testid="process-modal"]')).toBeVisible({ timeout: 5_000 });
-    await page.screenshot({ path: testInfo.outputPath('process-view-clicked.png'), fullPage: true });
   });
 
-  test('lightbulb highlights nodes in graph', async ({ page }, testInfo) => {
-    await connectAndWaitForGraph(page, testInfo);
+  test('lightbulb highlights nodes in graph', async ({ page }) => {
+    await waitForGraphLoaded(page);
 
     await page.getByRole('button', { name: 'Nexus AI' }).click();
     await page.getByText('Processes').click();
-    await expect(page.locator('[data-testid="process-list-loaded"]')).toBeVisible({ timeout: 15_000 });
+    await expect(page.locator('[data-testid="process-list-loaded"]')).toBeVisible({
+      timeout: 15_000,
+    });
 
-    await page.screenshot({ path: testInfo.outputPath('before-highlight.png'), fullPage: true });
-
-    // Hover first process to reveal lightbulb
     const processRow = page.locator('[data-testid="process-row"]').first();
     await expect(processRow).toBeVisible({ timeout: 10_000 });
     await processRow.hover();
@@ -130,36 +136,28 @@ test.describe('Processes Panel', () => {
     const lightbulb = processRow.locator('[data-testid="process-highlight-button"]');
     await lightbulb.waitFor({ state: 'visible', timeout: 5_000 });
     await lightbulb.click();
-    // Wait for highlight to apply — the process row gets amber styling when focused
     await expect(processRow).toHaveClass(/bg-amber-950/, { timeout: 5_000 });
-    await page.screenshot({ path: testInfo.outputPath('after-highlight.png'), fullPage: true });
   });
 });
 
 test.describe('Turn Off All Highlights', () => {
-  test('selecting a node dims others, button clears it', async ({ page }, testInfo) => {
-    await connectAndWaitForGraph(page, testInfo);
+  test('selecting a node dims others, button clears it', async ({ page }) => {
+    await waitForGraphLoaded(page);
 
-    // Wait for graph to fully render by checking for canvas element
     await expect(page.locator('canvas').first()).toBeVisible({ timeout: 10_000 });
 
-    await page.screenshot({ path: testInfo.outputPath('before-select.png'), fullPage: true });
-
-    // Click a file in the file tree to select a node
     const fileItem = page.getByText('package.json').first();
     await expect(fileItem).toBeVisible({ timeout: 10_000 });
     await fileItem.click();
 
-    // Wait for highlight toggle to show "Turn off" (indicates highlights are active)
     const highlightToggle = page.locator('[data-testid="ai-highlights-toggle"]');
-    await expect(highlightToggle).toHaveAttribute('title', 'Turn off all highlights', { timeout: 5_000 });
-    await page.screenshot({ path: testInfo.outputPath('node-selected.png'), fullPage: true });
+    await expect(highlightToggle).toHaveAttribute('title', 'Turn off all highlights', {
+      timeout: 5_000,
+    });
 
-    // Click the toggle to clear all highlights
     await highlightToggle.click();
-
-    // Verify highlights are now off — button title changes to "Turn on"
-    await expect(highlightToggle).toHaveAttribute('title', 'Turn on AI highlights', { timeout: 5_000 });
-    await page.screenshot({ path: testInfo.outputPath('highlights-cleared.png'), fullPage: true });
+    await expect(highlightToggle).toHaveAttribute('title', 'Turn on AI highlights', {
+      timeout: 5_000,
+    });
   });
 });

gitnexus-web/index.html

@@ -4,9 +4,12 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>GitNexus</title>
-    <link rel="preconnect" href="https://fonts.googleapis.com">
-    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-    <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600&family=Outfit:wght@300;400;500;600;700&display=swap" rel="stylesheet">
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600&family=Outfit:wght@300;400;500;600;700&display=swap"
+      rel="stylesheet"
+    />
   </head>
   <body>
     <div id="root"></div>

gitnexus-web/package.json

@@ -18,9 +18,7 @@
     "test:e2e:report": "playwright show-report"
   },
   "dependencies": {
-    "@huggingface/transformers": "^3.0.0",
-    "@isomorphic-git/lightning-fs": "^4.6.2",
-    "@ladybugdb/wasm-core": "^0.15.1",
+    "gitnexus-shared": "file:../gitnexus-shared",
     "@langchain/anthropic": "^1.3.10",
     "@langchain/core": "^1.1.15",
     "@langchain/google-genai": "^2.1.10",
@@ -30,8 +28,6 @@
     "@sigma/edge-curve": "^3.1.0",
     "@tailwindcss/vite": "^4.1.18",
     "axios": "^1.13.2",
-    "buffer": "^6.0.3",
-    "comlink": "^4.4.2",
     "d3": "^7.9.0",
     "dompurify": "^3.3.3",
     "graphology": "^0.26.0",
@@ -40,13 +36,10 @@
     "graphology-layout-forceatlas2": "^0.10.1",
     "graphology-layout-noverlap": "^0.4.2",
     "graphology-utils": "^2.3.0",
-    "isomorphic-git": "^1.36.1",
-    "jszip": "^3.10.1",
     "langchain": "^1.2.10",
     "lru-cache": "^11.2.4",
     "lucide-react": "^0.562.0",
-    "mermaid": "^11.12.2",
-    "minisearch": "^7.2.0",
+    "mermaid": "^11.14.0",
     "mnemonist": "^0.39.0",
     "pandemonium": "^2.4.0",
     "react": "^18.3.1",
@@ -56,11 +49,8 @@
     "react-zoom-pan-pinch": "^3.7.0",
     "remark-gfm": "^4.0.1",
     "sigma": "^3.0.2",
-    "tailwindcss": "^4.1.18",
+    "tailwindcss": "^4.2.2",
     "uuid": "^13.0.0",
-    "vite-plugin-top-level-await": "^1.6.0",
-    "vite-plugin-wasm": "^3.5.0",
-    "web-tree-sitter": "^0.20.8",
     "zod": "^3.25.76"
   },
   "devDependencies": {
@@ -70,7 +60,6 @@
     "@testing-library/react": "^16.3.2",
     "@testing-library/user-event": "^14.6.1",
     "@types/dompurify": "^3.0.5",
-    "@types/jszip": "^3.4.0",
     "@types/node": "^24.10.1",
     "@types/react": "^18.3.5",
     "@types/react-dom": "^18.3.0",
@@ -78,12 +67,11 @@
     "@vercel/node": "^5.5.16",
     "@vitejs/plugin-react": "^5.1.0",
     "@vitest/coverage-v8": "^3.2.4",
-    "jsdom": "^29.0.0",
+    "jsdom": "^29.0.2",
     "tree-sitter-wasms": "^0.1.13",
     "typescript": "^5.4.5",
     "vite": "^5.2.0",
-    "vite-plugin-static-copy": "^3.1.4",
     "vitest": "^3.2.4",
-    "wait-on": "^8.0.5"
+    "wait-on": "^9.0.5"
   }
 }

gitnexus-web/playwright.config.ts

@@ -40,9 +40,6 @@ export default defineConfig({
       use: { browserName: 'chromium' },
     },
   ],
-  reporter: [
-    ['list'],
-    ['html', { open: 'never', outputFolder: 'playwright-report' }],
-  ],
+  reporter: [['list'], ['html', { open: 'never', outputFolder: 'playwright-report' }]],
   outputDir: 'test-results',
 });

gitnexus-web/src/App.tsx

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useRef } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 import { AppStateProvider, useAppState } from './hooks/useAppState';
 import { DropZone } from './components/DropZone';
 import { LoadingOverlay } from './components/LoadingOverlay';
@@ -9,10 +9,17 @@ import { SettingsPanel } from './components/SettingsPanel';
 import { StatusBar } from './components/StatusBar';
 import { FileTreePanel } from './components/FileTreePanel';
 import { CodeReferencesPanel } from './components/CodeReferencesPanel';
-import { FileEntry } from './services/zip';
 import { getActiveProviderConfig } from './core/llm/settings-service';
 import { createKnowledgeGraph } from './core/graph/graph';
-import { connectToServer, fetchRepos, normalizeServerUrl, type ConnectToServerResult } from './services/server-connection';
+import {
+  connectToServer,
+  fetchRepos,
+  normalizeServerUrl,
+  connectHeartbeat,
+  BackendError,
+  type ConnectResult,
+  type BackendRepo,
+} from './services/backend-client';
 import { ERROR_RESET_DELAY_MS } from './config/ui-constants';
 
 const AppContent = () => {
@@ -20,19 +27,15 @@ const AppContent = () => {
     viewMode,
     setViewMode,
     setGraph,
-    setFileContents,
     setProgress,
     setProjectName,
     progress,
     isRightPanelOpen,
-    runPipeline,
-    runPipelineFromFiles,
     isSettingsPanelOpen,
     setSettingsPanelOpen,
     refreshLLMSettings,
     initializeAgent,
     startEmbeddingsWithFallback,
-    embeddingStatus,
     codeReferences,
     selectedNode,
     isCodePanelOpen,
@@ -41,185 +44,143 @@ const AppContent = () => {
     availableRepos,
     setAvailableRepos,
     switchRepo,
-    loadServerGraph,
+    setCurrentRepo,
   } = useAppState();
 
   const graphCanvasRef = useRef<GraphCanvasHandle>(null);
+  const [serverDisconnected, setServerDisconnected] = useState(false);
 
-  const handleFileSelect = useCallback(async (file: File) => {
-    const projectName = file.name.replace('.zip', '');
-    setProjectName(projectName);
-    setProgress({ phase: 'extracting', percent: 0, message: 'Starting...', detail: 'Preparing to extract files' });
-    setViewMode('loading');
+  const handleServerConnect = useCallback(
+    async (result: ConnectResult): Promise<void> => {
+      // Use the canonical repo name from the server response so all subsequent
+      // backend calls (queries, search, grep, readFile) scope to this repo.
+      const repoName = result.repoInfo.name;
+      const repoPath = result.repoInfo.repoPath ?? result.repoInfo.path;
+      // Normalize both Windows (\) and Unix (/) path separators before splitting
+      const projectName =
+        result.repoInfo.name ||
+        (repoPath || '').replace(/\\/g, '/').split('/').filter(Boolean).pop() ||
+        'server-project';
+      setProjectName(projectName);
+      setCurrentRepo(projectName);
 
-    try {
-      const result = await runPipeline(file, (progress) => {
-        setProgress(progress);
-      });
+      // Build KnowledgeGraph from server data for visualization
+      const graph = createKnowledgeGraph();
+      for (const node of result.nodes) {
+        graph.addNode(node);
+      }
+      for (const rel of result.relationships) {
+        graph.addRelationship(rel);
+      }
+      setGraph(graph);
 
-      setGraph(result.graph);
-      setFileContents(result.fileContents);
+      // Persist the active project in the URL for bookmarkability and F5 refresh resilience
+      const urlObj = new URL(window.location.href);
+      urlObj.searchParams.set('project', projectName);
+      window.history.replaceState(null, '', urlObj.toString());
+
+      // Transition directly to exploring view
       setViewMode('exploring');
 
-      // Initialize (or re-initialize) the agent AFTER a repo loads so it captures
-      // the current codebase context (file contents + graph tools) in the worker.
-      if (getActiveProviderConfig()) {
-        initializeAgent(projectName);
-      }
-
-      // Auto-start embeddings pipeline in background
-      // Uses WebGPU if available, falls back to WASM
-      startEmbeddingsWithFallback();
-    } catch (error) {
-      console.error('Pipeline error:', error);
-      setProgress({
-        phase: 'error',
-        percent: 0,
-        message: 'Error processing file',
-        detail: error instanceof Error ? error.message : 'Unknown error',
-      });
-      setTimeout(() => {
-        setViewMode('onboarding');
-        setProgress(null);
-      }, ERROR_RESET_DELAY_MS);
-    }
-  }, [setViewMode, setGraph, setFileContents, setProgress, setProjectName, runPipeline, startEmbeddingsWithFallback, initializeAgent]);
-
-  const handleGitClone = useCallback(async (files: FileEntry[], repoName?: string) => {
-    let projectName = repoName;
-    if (!projectName) {
-      const firstPath = files[0]?.path || 'repository';
-      projectName = firstPath.split('/')[0].replace(/-\d+$/, '') || 'repository';
-    }
-
-    setProjectName(projectName);
-    setProgress({ phase: 'extracting', percent: 0, message: 'Starting...', detail: 'Preparing to process files' });
-    setViewMode('loading');
-
-    try {
-      const result = await runPipelineFromFiles(files, (progress) => {
-        setProgress(progress);
-      });
-
-      setGraph(result.graph);
-      setFileContents(result.fileContents);
-      setViewMode('exploring');
-
-      if (getActiveProviderConfig()) {
-        initializeAgent(projectName);
-      }
-
-      startEmbeddingsWithFallback();
-    } catch (error) {
-      console.error('Pipeline error:', error);
-      setProgress({
-        phase: 'error',
-        percent: 0,
-        message: 'Error processing repository',
-        detail: error instanceof Error ? error.message : 'Unknown error',
-      });
-      setTimeout(() => {
-        setViewMode('onboarding');
-        setProgress(null);
-      }, ERROR_RESET_DELAY_MS);
-    }
-  }, [setViewMode, setGraph, setFileContents, setProgress, setProjectName, runPipelineFromFiles, startEmbeddingsWithFallback, initializeAgent]);
-
-  const handleServerConnect = useCallback((result: ConnectToServerResult): Promise<void> => {
-    // Extract project name from repoPath
-    const repoPath = result.repoInfo.repoPath;
-    const parts = repoPath.split('/').filter(p => p && !p.startsWith('.'));
-    const projectName = parts[parts.length - 1] || parts[0] || 'server-project';
-    setProjectName(projectName);
-
-    // Build KnowledgeGraph from server data for visualization
-    const graph = createKnowledgeGraph();
-    for (const node of result.nodes) {
-      graph.addNode(node);
-    }
-    for (const rel of result.relationships) {
-      graph.addRelationship(rel);
-    }
-    setGraph(graph);
-
-    // Set file contents from extracted File node content
-    const fileMap = new Map<string, string>();
-    for (const [path, content] of Object.entries(result.fileContents)) {
-      fileMap.set(path, content);
-    }
-    setFileContents(fileMap);
-
-    // Transition directly to exploring view
-    setViewMode('exploring');
-
-    // Load graph into LadybugDB (in-browser WASM database) for Nexus AI queries,
-    // then initialize agent once the database is ready
-    const loadGraphPromise = loadServerGraph(result.nodes, result.relationships, result.fileContents)
-      .then(() => {
+      // Initialize agent with backend queries, then start embeddings
+      try {
         if (getActiveProviderConfig()) {
-          return initializeAgent(projectName);
+          await initializeAgent(projectName);
         }
-      })
-      .then(() => {
         startEmbeddingsWithFallback();
-      })
-      .catch((err) => {
-        console.warn('Failed to load graph into LadybugDB:', err);
-        // Agent won't work but graph visualization still does
-      });
+      } catch (err) {
+        console.warn('Failed to initialize agent:', err);
+      }
+    },
+    [
+      setViewMode,
+      setGraph,
+      setProjectName,
+      setCurrentRepo,
+      initializeAgent,
+      startEmbeddingsWithFallback,
+    ],
+  );
 
-    return loadGraphPromise;
-  }, [setViewMode, setGraph, setFileContents, setProjectName, loadServerGraph, initializeAgent, startEmbeddingsWithFallback]);
-
-  // Auto-connect when ?server query param is present (bookmarkable shortcut)
+  // Auto-connect when ?server or ?project query param is present (bookmarkable shortcut)
   const autoConnectRan = useRef(false);
   useEffect(() => {
     if (autoConnectRan.current) return;
     const params = new URLSearchParams(window.location.search);
-    if (!params.has('server')) return;
+    const serverUrlParam = params.get('server');
+    const projectParam = params.get('project');
+
+    if (!serverUrlParam && !projectParam) return;
     autoConnectRan.current = true;
 
-    // Clean the URL so a refresh won't re-trigger
-    const cleanUrl = window.location.pathname + window.location.hash;
-    window.history.replaceState(null, '', cleanUrl);
-
-    setProgress({ phase: 'extracting', percent: 0, message: 'Connecting to server...', detail: 'Validating server' });
+    setProgress({
+      phase: 'extracting',
+      percent: 0,
+      message: 'Connecting to server...',
+      detail: 'Validating server',
+    });
     setViewMode('loading');
 
-    const serverUrl = params.get('server') || window.location.origin;
-
+    const serverUrl = serverUrlParam || window.location.origin;
     const baseUrl = normalizeServerUrl(serverUrl);
 
-    connectToServer(serverUrl, (phase, downloaded, total) => {
-      if (phase === 'validating') {
-        setProgress({ phase: 'extracting', percent: 5, message: 'Connecting to server...', detail: 'Validating server' });
-      } else if (phase === 'downloading') {
-        const pct = total ? Math.round((downloaded / total) * 90) + 5 : 50;
-        const mb = (downloaded / (1024 * 1024)).toFixed(1);
-        setProgress({ phase: 'extracting', percent: pct, message: 'Downloading graph...', detail: `${mb} MB downloaded` });
-      } else if (phase === 'extracting') {
-        setProgress({ phase: 'extracting', percent: 97, message: 'Processing...', detail: 'Extracting file contents' });
-      }
-    }).then(async (result) => {
-      await handleServerConnect(result);
-      setProgress(null);
-      setServerBaseUrl(baseUrl);
-      fetchRepos(baseUrl)
-        .then((repos) => setAvailableRepos(repos))
-        .catch((e) => console.warn('Failed to fetch repo list:', e));
-    }).catch((err) => {
-      console.error('Auto-connect failed:', err);
-      setProgress({
-        phase: 'error',
-        percent: 0,
-        message: 'Failed to connect to server',
-        detail: err instanceof Error ? err.message : 'Unknown error',
-      });
-      setTimeout(() => {
-        setViewMode('onboarding');
+    const tryConnect = async () => {
+      return await connectToServer(
+        serverUrl,
+        (phase, downloaded, total) => {
+          if (phase === 'validating') {
+            setProgress({
+              phase: 'extracting',
+              percent: 5,
+              message: 'Connecting to server...',
+              detail: 'Validating server',
+            });
+          } else if (phase === 'downloading') {
+            const pct = total ? Math.round((downloaded / total) * 90) + 5 : 50;
+            const mb = (downloaded / (1024 * 1024)).toFixed(1);
+            setProgress({
+              phase: 'extracting',
+              percent: pct,
+              message: 'Downloading graph...',
+              detail: `${mb} MB downloaded`,
+            });
+          } else if (phase === 'extracting') {
+            setProgress({
+              phase: 'extracting',
+              percent: 97,
+              message: 'Processing...',
+              detail: 'Extracting file contents',
+            });
+          }
+        },
+        undefined,
+        projectParam || undefined,
+        { awaitAnalysis: true }, // enable backend hold-queue for repos still being analyzed
+      );
+    };
+
+    tryConnect()
+      .then(async (result) => {
+        await handleServerConnect(result);
         setProgress(null);
-      }, ERROR_RESET_DELAY_MS);
-    });
+        setServerBaseUrl(baseUrl);
+        fetchRepos()
+          .then((repos) => setAvailableRepos(repos))
+          .catch((e) => console.warn('Failed to fetch repo list:', e));
+      })
+      .catch((err) => {
+        console.error('Auto-connect failed:', err);
+        setProgress({
+          phase: 'error',
+          percent: 0,
+          message: 'Failed to connect to server',
+          detail: err instanceof Error ? err.message : 'Unknown error',
+        });
+        setTimeout(() => {
+          setViewMode('onboarding');
+          setProgress(null);
+        }, ERROR_RESET_DELAY_MS);
+      });
   }, [handleServerConnect, setProgress, setViewMode, setServerBaseUrl, setAvailableRepos]);
 
   const handleFocusNode = useCallback((nodeId: string) => {
@@ -233,21 +194,38 @@ const AppContent = () => {
     initializeAgent();
   }, [refreshLLMSettings, initializeAgent]);
 
+  // ── Server heartbeat: detect when server goes down while exploring ────────
+  // Uses SSE (EventSource) for instant detection — no polling delay.
+  // On disconnect: show a reconnecting banner instead of resetting to onboarding.
+  // The heartbeat retries indefinitely with capped backoff and recovers automatically.
+  useEffect(() => {
+    if (viewMode !== 'exploring') return;
+
+    const cleanup = connectHeartbeat(
+      () => setServerDisconnected(false),
+      () => setServerDisconnected(true),
+    );
+
+    return cleanup;
+  }, [viewMode]);
+
   // Render based on view mode
   if (viewMode === 'onboarding') {
     return (
       <DropZone
-        onFileSelect={handleFileSelect}
-        onGitClone={handleGitClone}
         onServerConnect={async (result, serverUrl) => {
+          // Refresh repo list before transitioning so it's ready in the header
+          const repos = await fetchRepos().catch(() => [] as BackendRepo[]);
+          setAvailableRepos(repos);
           await handleServerConnect(result);
           setProgress(null);
           if (serverUrl) {
-            const baseUrl = normalizeServerUrl(serverUrl);
-            setServerBaseUrl(baseUrl);
-            fetchRepos(baseUrl)
-              .then((repos) => setAvailableRepos(repos))
-              .catch((e) => console.warn('Failed to fetch repo list:', e));
+            const base = normalizeServerUrl(serverUrl);
+            setServerBaseUrl(base);
+            // Add ?server= so F5 reconnects to this server
+            const url = new URL(window.location.href);
+            url.searchParams.set('server', base);
+            window.history.replaceState(null, '', url.toString());
           }
         }}
       />
@@ -260,20 +238,54 @@ const AppContent = () => {
 
   // Exploring view
   return (
-    <div className="flex flex-col h-screen bg-void overflow-hidden">
-      <Header onFocusNode={handleFocusNode} availableRepos={availableRepos} onSwitchRepo={switchRepo} />
+    <div className="flex h-screen flex-col overflow-hidden bg-void">
+      <Header
+        onFocusNode={handleFocusNode}
+        availableRepos={availableRepos}
+        onSwitchRepo={switchRepo}
+        onReposChanged={(repos) => setAvailableRepos(repos)}
+        onAnalyzeComplete={async (repoName) => {
+          // A new repo was just indexed via the header dropdown.
+          // Refresh the repo list, connect to the new repo, and switch to it.
+          // Retry once after 1s if the repo isn't found yet (server may still
+          // be reinitializing after the worker completed).
+          const url = serverBaseUrl ?? 'http://localhost:4747';
+          for (let attempt = 0; attempt < 2; attempt++) {
+            try {
+              const repos = await fetchRepos();
+              setAvailableRepos(repos);
+              const result = await connectToServer(url, undefined, undefined, repoName);
+              await handleServerConnect(result);
+              setServerBaseUrl(normalizeServerUrl(url));
+              setProgress(null);
+              return;
+            } catch (err: unknown) {
+              if (attempt === 0 && err instanceof BackendError && err.status === 404) {
+                // Server may still be reinitializing — wait and retry
+                await new Promise((r) => setTimeout(r, 1500));
+                continue;
+              }
+              console.error('Failed to connect after analyze:', err);
+              fetchRepos()
+                .then((repos) => setAvailableRepos(repos))
+                .catch(() => {});
+              return;
+            }
+          }
+        }}
+      />
 
-      <main className="flex-1 flex min-h-0">
+      <main className="flex min-h-0 flex-1">
         {/* Left Panel - File Tree */}
         <FileTreePanel onFocusNode={handleFocusNode} />
 
         {/* Graph area - takes remaining space */}
-        <div className="flex-1 relative min-w-0">
+        <div className="relative min-w-0 flex-1">
           <GraphCanvas ref={graphCanvasRef} />
 
           {/* Code References Panel (overlay) - does NOT resize the graph, it overlaps on top */}
           {isCodePanelOpen && (codeReferences.length > 0 || !!selectedNode) && (
-            <div className="absolute inset-y-0 left-0 z-30 pointer-events-auto">
+            <div className="pointer-events-auto absolute inset-y-0 left-0 z-30">
               <CodeReferencesPanel onFocusNode={handleFocusNode} />
             </div>
           )}
@@ -285,13 +297,18 @@ const AppContent = () => {
 
       <StatusBar />
 
+      {serverDisconnected && (
+        <div className="fixed bottom-12 left-1/2 z-50 -translate-x-1/2 rounded-lg border border-yellow-500/30 bg-yellow-900/80 px-4 py-2 text-sm text-yellow-200 shadow-lg backdrop-blur">
+          Server connection lost — reconnecting&hellip;
+        </div>
+      )}
+
       {/* Settings Panel (modal) */}
       <SettingsPanel
         isOpen={isSettingsPanelOpen}
         onClose={() => setSettingsPanelOpen(false)}
         onSettingsSaved={handleSettingsSaved}
       />
-
     </div>
   );
 };

gitnexus-web/src/components/AnalyzeOnboarding.tsx

@@ -0,0 +1,70 @@
+/**
+ * AnalyzeOnboarding
+ *
+ * The "empty state" card rendered inside DropZone's Crossfade when the server
+ * is connected but zero repos are indexed. Replaces the generic error message
+ * with a first-class GitHub URL input flow.
+ *
+ * Rendering context:
+ *   DropZone (Crossfade, phase="analyze")
+ *     └─ AnalyzeOnboarding
+ *          └─ RepoAnalyzer (variant="onboarding")
+ *
+ * When the analysis job completes, onComplete fires with the repoName, and
+ * DropZone's handleAutoConnect re-runs (now that repos > 0), transitioning
+ * the app to the graph explorer.
+ */
+
+import { Sparkles, Github } from '@/lib/lucide-icons';
+import { RepoAnalyzer } from './RepoAnalyzer';
+
+interface AnalyzeOnboardingProps {
+  /** Called when analysis finishes and the repo is ready to load. */
+  onComplete: (repoName: string) => void;
+}
+
+export const AnalyzeOnboarding = ({ onComplete }: AnalyzeOnboardingProps) => {
+  return (
+    <div className="relative animate-fade-in overflow-hidden rounded-3xl border border-border-default bg-surface p-7">
+      {/* Ambient glows — mirrors OnboardingGuide aesthetic */}
+      <div className="pointer-events-none absolute -top-28 -right-28 h-72 w-72 rounded-full bg-accent/6 blur-3xl" />
+      <div className="pointer-events-none absolute -bottom-24 -left-24 h-56 w-56 rounded-full bg-node-function/6 blur-3xl" />
+
+      {/* Header */}
+      <div className="relative mb-6">
+        <div className="text-center">
+          {/* Eyebrow */}
+          <div className="mb-2 inline-flex items-center gap-1.5">
+            <Sparkles className="h-3.5 w-3.5 text-accent/70" />
+            <span className="text-[11px] font-medium tracking-widest text-accent/80 uppercase">
+              GitNexus
+            </span>
+          </div>
+
+          {/* Icon */}
+          <div className="mx-auto mb-4 flex h-14 w-14 items-center justify-center rounded-2xl border border-accent/30 bg-gradient-to-br from-accent/20 to-accent-dim/10 shadow-glow-soft">
+            <Github className="h-7 w-7 text-accent" />
+          </div>
+
+          <h2 className="text-lg leading-snug font-semibold text-text-primary">
+            Analyze your first repository
+          </h2>
+          <p className="mx-auto mt-1.5 max-w-xs text-sm leading-relaxed text-text-secondary">
+            Paste a GitHub URL and GitNexus will clone it, parse the code, and build a live
+            knowledge graph — right in your browser.
+          </p>
+        </div>
+      </div>
+
+      {/* Analyzer form */}
+      <div className="relative">
+        <RepoAnalyzer variant="onboarding" onComplete={onComplete} />
+      </div>
+
+      {/* Footer hint */}
+      <p className="mt-5 text-center text-[11px] leading-relaxed text-text-muted">
+        Public repos only &middot; Cloned locally by the server &middot; No data leaves your machine
+      </p>
+    </div>
+  );
+};

gitnexus-web/src/components/AnalyzeProgress.tsx

@@ -0,0 +1,77 @@
+import { useState, useEffect } from 'react';
+import { X } from '@/lib/lucide-icons';
+import type { JobProgress as AnalyzeJobProgress } from '../services/backend-client';
+
+interface AnalyzeProgressProps {
+  progress: AnalyzeJobProgress;
+  onCancel: () => void;
+}
+
+const PHASE_LABELS: Record<string, string> = {
+  queued: 'Queued',
+  cloning: 'Cloning repository',
+  pulling: 'Pulling latest',
+  extracting: 'Scanning files',
+  structure: 'Building structure',
+  parsing: 'Parsing code',
+  imports: 'Resolving imports',
+  calls: 'Tracing calls',
+  heritage: 'Extracting inheritance',
+  communities: 'Detecting communities',
+  processes: 'Detecting processes',
+  complete: 'Pipeline complete',
+  lbug: 'Loading into database',
+  fts: 'Creating search indexes',
+  embeddings: 'Generating embeddings',
+  done: 'Done',
+  retrying: 'Retrying after crash',
+};
+
+export const AnalyzeProgress = ({ progress, onCancel }: AnalyzeProgressProps) => {
+  const [startTime] = useState(() => Date.now());
+  const [elapsed, setElapsed] = useState(0);
+
+  useEffect(() => {
+    const timer = setInterval(() => setElapsed(Date.now() - startTime), 1000);
+    return () => clearInterval(timer);
+  }, [startTime]);
+
+  const formatElapsed = (ms: number) => {
+    const s = Math.floor(ms / 1000);
+    if (s < 60) return `${s}s`;
+    return `${Math.floor(s / 60)}m ${s % 60}s`;
+  };
+
+  const label = PHASE_LABELS[progress.phase] || progress.message || progress.phase;
+  const pct = Math.max(0, Math.min(100, progress.percent));
+
+  return (
+    <div className="space-y-4">
+      {/* Phase label + elapsed */}
+      <div className="flex items-center justify-between text-sm">
+        <span className="font-medium text-text-secondary">{label}</span>
+        <span className="font-mono text-xs text-text-muted">{formatElapsed(elapsed)}</span>
+      </div>
+
+      {/* Progress bar */}
+      <div className="h-2 overflow-hidden rounded-full bg-elevated">
+        <div
+          className="h-full rounded-full bg-accent transition-all duration-300 ease-out"
+          style={{ width: `${pct}%` }}
+        />
+      </div>
+
+      {/* Percent + cancel */}
+      <div className="flex items-center justify-between">
+        <span className="font-mono text-xs text-text-muted">{pct}%</span>
+        <button
+          onClick={onCancel}
+          className="flex items-center gap-1.5 rounded-lg bg-red-500/10 px-3 py-1.5 text-xs text-red-400 transition-all duration-200 hover:bg-red-500/20"
+        >
+          <X className="h-3.5 w-3.5" />
+          Cancel
+        </button>
+      </div>
+    </div>
+  );
+};

gitnexus-web/src/components/BackendRepoSelector.tsx

@@ -1,88 +0,0 @@
-import { Server, ArrowRight } from '@/lib/lucide-icons';
-import { BackendRepo } from '../services/backend';
-
-interface BackendRepoSelectorProps {
-  repos: BackendRepo[];
-  onSelectRepo: (repoName: string) => void;
-  backendUrl: string;
-  isConnected: boolean;
-}
-
-export const BackendRepoSelector = ({
-  repos,
-  onSelectRepo,
-  backendUrl,
-  isConnected,
-}: BackendRepoSelectorProps) => {
-  return (
-    <div className="p-8 bg-surface border border-border-default rounded-3xl">
-      {/* Icon */}
-      <div className="mx-auto w-20 h-20 mb-6 flex items-center justify-center bg-gradient-to-br from-accent to-node-interface rounded-2xl shadow-glow">
-        <Server className="w-10 h-10 text-white" />
-      </div>
-
-      {/* Title */}
-      <h2 className="text-xl font-semibold text-text-primary text-center mb-2">
-        Local Repositories
-      </h2>
-      <p className="text-sm text-text-secondary text-center mb-4">
-        Select an indexed repository from your local GitNexus server
-      </p>
-
-      {/* Connected status badge */}
-      {isConnected && (
-        <div className="flex items-center justify-center gap-2 mb-6">
-          <span className="w-2 h-2 bg-green-400 rounded-full animate-pulse" />
-          <span className="text-xs text-green-400">Connected to {backendUrl}</span>
-        </div>
-      )}
-
-      {/* Repo list or empty state */}
-      {repos.length > 0 ? (
-        <div className="max-h-80 overflow-y-auto space-y-2">
-          {repos.map((repo) => (
-            <button
-              key={repo.name}
-              onClick={() => onSelectRepo(repo.name)}
-              className="w-full p-4 bg-elevated border border-border-subtle rounded-xl hover:border-accent/50 hover:bg-hover transition-all text-left group"
-            >
-              <div className="flex items-center justify-between mb-2">
-                <span className="font-medium text-text-primary group-hover:text-accent transition-colors">
-                  {repo.name}
-                </span>
-                <ArrowRight className="w-4 h-4 text-text-muted group-hover:text-accent transition-colors" />
-              </div>
-              <div className="flex items-center gap-3 text-xs text-text-muted">
-                {repo.stats?.files != null && <span>{repo.stats.files} files</span>}
-                {repo.stats?.nodes != null && <span>{repo.stats.nodes} nodes</span>}
-                {repo.stats?.edges != null && <span>{repo.stats.edges} edges</span>}
-              </div>
-              <div className="text-xs text-text-muted mt-1">
-                Indexed {new Date(repo.indexedAt).toLocaleDateString()}
-              </div>
-            </button>
-          ))}
-        </div>
-      ) : (
-        <div className="text-center text-text-muted py-8">
-          <p className="text-sm mb-2">No indexed repositories found</p>
-          <p className="text-xs">
-            Run{' '}
-            <code className="px-1 py-0.5 bg-elevated rounded">gitnexus analyze</code>{' '}
-            in a repository
-          </p>
-        </div>
-      )}
-
-      {/* Bottom hints */}
-      <div className="mt-4 flex items-center justify-center gap-3 text-xs text-text-muted">
-        <span className="px-3 py-1.5 bg-elevated border border-border-subtle rounded-md">
-          {repos.length} {repos.length === 1 ? 'repo' : 'repos'}
-        </span>
-        <span className="px-3 py-1.5 bg-elevated border border-border-subtle rounded-md">
-          Pre-indexed
-        </span>
-      </div>
-    </div>
-  );
-};