@

fix(docker): eliminate TOCTOU race and format web components

Use fs.promises.open() to get a file handle, then fstat/readFile/
createReadStream from the same fd — eliminates the CodeQL
"file system race condition" alert between stat() and read.

Also runs prettier on the 5 web component files that were failing
the format CI check.
@

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

@@ -17,11 +17,11 @@ npx gitnexus analyze
 
 Run from the project root. This parses all source files, builds the knowledge graph, writes it to `.gitnexus/`, and generates CLAUDE.md / AGENTS.md context files.
 
-| Flag                | Effect                                                                                                  |
-| ------------------- | ------------------------------------------------------------------------------------------------------- |
-| `--force`           | Force full re-index even if up to date                                                                  |
-| `--embeddings`      | Enable embedding generation for semantic search (off by default)                                        |
-| `--drop-embeddings` | Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` preserves them.    |
+| Flag           | Effect                                                           |
+| -------------- | ---------------------------------------------------------------- |
+| `--force`      | Force full re-index even if up to date                           |
+| `--embeddings` | Enable embedding generation for semantic search (off by default) |
+| `--drop-embeddings` | Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` preserves them. |
 
 **When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale. In Claude Code, a PostToolUse hook detects staleness after `git commit` and `git merge` and notifies the agent to run `analyze` — the hook does not run analyze itself, to avoid blocking the agent for up to 120s and risking KuzuDB corruption on timeout.
 

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

@@ -24,6 +24,19 @@ name: Scope Resolution Parity
 # When the set is empty (e.g. mid-Ring-3 for every language), the parity
 # matrix is skipped and the workflow reports success — no-op until a
 # language is explicitly claimed migrated.
+#
+# ── Consolidation (chore/vitest-speed-strategy) ────────────────────────
+# Previously each language was a separate GitHub Actions matrix job,
+# meaning N languages × 1 checkout+install+build per shard. The build
+# cost dwarfed the test cost (~5 min setup for ~15 sec test execution).
+#
+# Now a single job runs `scripts/run-parity.ts` which loops through all
+# migrated languages sequentially (2 vitest invocations per language:
+# legacy + registry-primary). All failures are collected and reported
+# at the end (equivalent to the old fail-fast: false behavior).
+#
+# Adding a new language to MIGRATED_LANGUAGES still requires no workflow
+# edit — the script auto-discovers the set at runtime.
 
 on:
   workflow_call:
@@ -37,7 +50,6 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 5
     outputs:
-      languages: ${{ steps.read.outputs.languages }}
       has-any: ${{ steps.read.outputs.has-any }}
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
@@ -49,65 +61,27 @@ jobs:
         working-directory: gitnexus
         run: |
           set -euo pipefail
-          # `tsx` evaluates the TS source directly (no build step), imports
-          # the exported `Set`, and emits a GH-Actions-friendly JSON matrix.
           LANGS=$(npx tsx scripts/ci-list-migrated-languages.ts)
           COUNT=$(printf '%s' "$LANGS" | jq 'length')
           HAS_ANY="false"
           if [[ "$COUNT" -gt 0 ]]; then HAS_ANY="true"; fi
-          echo "languages=$LANGS" >> "$GITHUB_OUTPUT"
           echo "has-any=$HAS_ANY" >> "$GITHUB_OUTPUT"
           echo "Discovered $COUNT migrated language(s): $LANGS"
-          echo "Parity matrix will run: $HAS_ANY"
+          echo "Parity will run: $HAS_ANY"
 
   parity:
-    name: ${{ matrix.lang.slug }} parity
+    name: scope-resolution parity
     needs: discover
     if: needs.discover.outputs.has-any == 'true'
     runs-on: ubuntu-latest
-    timeout-minutes: 20
-    strategy:
-      # One language failing must not abort the others — we want the full
-      # parity matrix result on a single CI run so a reviewer sees every
-      # regression at once rather than one-at-a-time.
-      fail-fast: false
-      matrix:
-        lang: ${{ fromJSON(needs.discover.outputs.languages) }}
+    timeout-minutes: 30
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - uses: ./.github/actions/setup-gitnexus
         with:
           build: 'true'
 
-      - name: Verify resolver test file exists
+      - name: Run parity for all migrated languages
         shell: bash
         working-directory: gitnexus
-        run: |
-          set -euo pipefail
-          TEST_FILE="test/integration/resolvers/${{ matrix.lang.slug }}.test.ts"
-          if [[ ! -f "$TEST_FILE" ]]; then
-            echo "::error title=Missing resolver test::\
-          Expected $TEST_FILE for '${{ matrix.lang.slug }}' (listed in \
-          MIGRATED_LANGUAGES). Either fix the slug or add the test file \
-          before listing this language as migrated."
-            exit 1
-          fi
-
-      - name: Resolver tests — legacy DAG (REGISTRY_PRIMARY_${{ matrix.lang.envvar }}=0)
-        shell: bash
-        working-directory: gitnexus
-        env:
-          FLAG_NAME: REGISTRY_PRIMARY_${{ matrix.lang.envvar }}
-        # Explicitly force the flag to `0` even though it also defaults to
-        # `MIGRATED_LANGUAGES.has(lang)` — once a language is in the set,
-        # the default flips to registry-primary, so an unset env var would
-        # silently re-run the same path as step #2. `env FOO=0 cmd` spawns
-        # `cmd` with the override scoped to just this invocation.
-        run: env "$FLAG_NAME=0" npx vitest run "test/integration/resolvers/${{ matrix.lang.slug }}.test.ts"
-
-      - name: Resolver tests — registry-primary (REGISTRY_PRIMARY_${{ matrix.lang.envvar }}=1)
-        shell: bash
-        working-directory: gitnexus
-        env:
-          FLAG_NAME: REGISTRY_PRIMARY_${{ matrix.lang.envvar }}
-        run: env "$FLAG_NAME=1" npx vitest run "test/integration/resolvers/${{ matrix.lang.slug }}.test.ts"
+        run: npx tsx scripts/run-parity.ts

.github/workflows/ci-tests.yml

@@ -59,19 +59,125 @@ jobs:
             gitnexus-web/web-test-results.json
           retention-days: 5
 
+  # Platform-sensitive subset only — the full suite runs on Ubuntu above.
+  # See gitnexus/scripts/cross-platform-tests.ts for the file list and
+  # rationale for each included test.
   cross-platform:
-    name: ${{ matrix.os }}
+    name: ${{ matrix.os }} (platform-sensitive)
     strategy:
       fail-fast: false
       matrix:
         # Ubuntu already covered by the coverage job above
         os: [windows-latest, macos-latest]
     runs-on: ${{ matrix.os }}
-    timeout-minutes: 25
+    timeout-minutes: 20
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - uses: ./.github/actions/setup-gitnexus
         with:
           build: 'true'
-      - run: npx vitest run
+      - name: Run platform-sensitive tests
+        run: npx tsx scripts/run-cross-platform.ts
         working-directory: gitnexus
+
+  # End-to-end smoke test for the #1728 packaging fix: pack the published
+  # tarball, install it globally into a temp prefix, and assert no junction
+  # creation (the EPERM root cause) plus working CLI plus vendor cleanliness
+  # (#836). Runs on windows-latest because that is the platform the fix
+  # targets; the in-repo `npm ci` job above only exercises the dev-tree path
+  # and skips the tarball reify step where the historical EPERM occurred.
+  packaged-install-smoke:
+    name: packaged install smoke (${{ matrix.os }})
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [windows-latest, ubuntu-latest]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    steps:
+      # persist-credentials: false — this job runs npm pack + npm install -g
+      # from a tarball and never pushes back; the token in .git/config would
+      # be at risk of leaking through any future artifact-upload step
+      # (zizmor artipacked audit). Disable upfront.
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - uses: ./.github/actions/setup-gitnexus
+        with:
+          build: 'true'
+
+      - name: Pack gitnexus tarball
+        shell: bash
+        run: npm pack
+        working-directory: gitnexus
+
+      - name: Install gitnexus tarball into isolated prefix
+        shell: bash
+        run: |
+          set -euo pipefail
+          PREFIX="$RUNNER_TEMP/gitnexus-smoke"
+          mkdir -p "$PREFIX"
+          TARBALL=$(find . -maxdepth 1 -name 'gitnexus-*.tgz' -print -quit)
+          if [ -z "$TARBALL" ]; then
+            echo "ERROR: no gitnexus-*.tgz tarball found in $(pwd)" >&2
+            exit 1
+          fi
+          echo "Installing $TARBALL into $PREFIX"
+          npm install -g --prefix "$PREFIX" "./$TARBALL" --no-audit --no-fund
+          echo "PREFIX=$PREFIX" >> "$GITHUB_ENV"
+        working-directory: gitnexus
+
+      - name: Assert no junctions or vendor build artifacts
+        shell: bash
+        run: |
+          set -euo pipefail
+          # Locate the installed gitnexus package across npm prefix layouts
+          # (lib/node_modules on POSIX, node_modules on Windows).
+          for candidate in "$PREFIX/lib/node_modules/gitnexus" "$PREFIX/node_modules/gitnexus"; do
+            if [ -d "$candidate" ]; then
+              INSTALLED="$candidate"
+              break
+            fi
+          done
+          if [ -z "${INSTALLED:-}" ]; then
+            echo "ERROR: installed gitnexus package not found under $PREFIX" >&2
+            ls -la "$PREFIX" || true
+            exit 1
+          fi
+          echo "Installed package at: $INSTALLED"
+
+          # #836 invariant: no node_modules/ or build/ under any vendor/*.
+          BAD=$(find "$INSTALLED/vendor" \( -name node_modules -o -name build \) -print 2>/dev/null || true)
+          if [ -n "$BAD" ]; then
+            echo "ERROR: vendor tree contains forbidden build artifacts (#836):" >&2
+            echo "$BAD" >&2
+            exit 1
+          fi
+
+          # #1728 invariant: materialized grammar dirs are real directories,
+          # not junctions/symlinks (which is what the EPERM regression created).
+          for name in tree-sitter-dart tree-sitter-proto tree-sitter-swift; do
+            entry="$INSTALLED/node_modules/$name"
+            if [ ! -e "$entry" ]; then
+              echo "WARN: $name not materialized (toolchain/prebuild may be unavailable on $RUNNER_OS)"
+              continue
+            fi
+            if [ -L "$entry" ]; then
+              echo "ERROR: $entry is a symlink/junction — #1728 regression" >&2
+              exit 1
+            fi
+            if [ ! -d "$entry" ]; then
+              echo "ERROR: $entry is not a directory" >&2
+              exit 1
+            fi
+          done
+
+      - name: Assert gitnexus --version works
+        shell: bash
+        run: |
+          set -euo pipefail
+          if [ "$RUNNER_OS" = "Windows" ]; then
+            "$PREFIX/gitnexus.cmd" --version
+          else
+            "$PREFIX/bin/gitnexus" --version
+          fi

.github/workflows/ci.yml

@@ -11,14 +11,14 @@ permissions:
 
 # 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 `pull_request` invocations use `CI-<ref>`; invocations from a
-# reusable-workflow caller fall into a per-run-unique group that never serializes
-# with the caller. `push` to main is handled by release-candidate.yml, which
-# calls this workflow once before publishing.
+# invoked as a reusable workflow from publish.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 `pull_request`
+# invocations use `CI-<ref>`; invocations from a reusable-workflow caller fall
+# into a per-run-unique group that never serializes with the caller. `push` to
+# main is handled by publish.yml (RC mode), which calls this workflow once
+# before publishing.
 concurrency:
   group: ${{ github.event_name == 'pull_request' && format('CI-{0}', github.ref) || format('CI-nested-{0}', github.run_id) }}
   cancel-in-progress: ${{ github.event_name == 'pull_request' }}

.github/workflows/codeql.yml

@@ -48,7 +48,7 @@ jobs:
           persist-credentials: false
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@e46ed2cbd01164d986452f91f178727624ae40d7 # v4.35.3
+        uses: github/codeql-action/init@68bde559dea0fdcac2102bfdf6230c5f70eb485e # v4.35.4
         with:
           languages: ${{ matrix.language }}
           queries: security-and-quality
@@ -69,6 +69,6 @@ jobs:
               - '**/test/fixtures/**'
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@e46ed2cbd01164d986452f91f178727624ae40d7 # v4.35.3
+        uses: github/codeql-action/analyze@68bde559dea0fdcac2102bfdf6230c5f70eb485e # v4.35.4
         with:
           category: '/language:${{ matrix.language }}'

.github/workflows/dependency-review.yml

@@ -33,7 +33,7 @@ jobs:
           persist-credentials: false
 
       - name: Dependency Review
-        uses: actions/dependency-review-action@2031cfc080254a8a887f58cffee85186f0e49e48 # v4.9.0
+        uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 # v5.0.0
         with:
           fail-on-severity: high
           comment-summary-in-pr: on-failure

.github/workflows/docker.yml

@@ -25,6 +25,15 @@ on:
           a gitnexus/package.json whose version matches the tag.
         required: true
         type: string
+    # Explicit secret contract — callers pass these by name. Replaces the
+    # blanket `secrets: inherit` pattern (zizmor `secrets-inherit` audit).
+    # GHCR auth uses the implicit GITHUB_TOKEN; only Docker Hub credentials
+    # need to be passed through.
+    secrets:
+      DOCKERHUB_USERNAME:
+        required: true
+      DOCKERHUB_TOKEN:
+        required: true
 
 permissions:
   contents: read
@@ -73,7 +82,7 @@ jobs:
 
     steps:
       # Only the workflow_call path requires a non-empty `inputs.tag` — callers
-      # (e.g. release-candidate.yml) must pass the RC tag explicitly. On direct
+      # (publish.yml in RC mode) must pass the RC tag explicitly. On direct
       # tag pushes the tag comes from `github.ref`, so `inputs.tag` is always
       # empty and validating it here would break every real release (#1064).
       # The downstream "Verify tag matches gitnexus/package.json version" step
@@ -135,7 +144,7 @@ jobs:
         uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
 
       - name: Install Cosign
-        uses: sigstore/cosign-installer@cad07c2e89fa2edd6e2d7bab4c1aa38e53f76003 # v4.1.1
+        uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
 
       - name: Log in to GitHub Container Registry
         if: ${{ github.event_name != 'pull_request' && !inputs.dry_run }}

.github/workflows/pr-labeler.yml

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

.github/workflows/publish.yml

@@ -1,62 +1,421 @@
-name: Publish to npm
+name: Publish
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Sole publisher for the `gitnexus` npm package, GitHub Releases, and Docker
+# images. Replaces the former two-workflow design — see issue #1609 for the
+# double-publish race this unification closes.
+#
+# Two release modes, both routed through this file:
+#   • Release candidate (rc)  — triggered by push to `main` or workflow_dispatch.
+#       The RC path computes the next rc version, applies it in-CI, pushes a
+#       detached release commit with v<X.Y.Z>-rc.<N> + rc/<SHA> marker
+#       atomically, then publishes to npm with --tag rc and creates a GitHub
+#       prerelease. RC-only docker.yml invocation follows.
+#   • Stable                  — triggered by push of a v<X.Y.Z> tag (no -rc.*
+#       suffix). Verifies package.json matches the tag, publishes to npm with
+#       --tag latest, creates a stable GitHub Release. No docker (RC-only).
+#
+# ⚠️  SELF-TRIGGER INVARIANT — DO NOT WEAKEN ⚠️
+# The `tags:` filter below uses a negative glob `'!v*-rc.*'` to prevent the
+# workflow from re-triggering itself when the RC path pushes its own v-tag.
+# Without this exclusion, every RC publish double-fires (the bug fixed by
+# #1609). If a NEW prerelease channel is introduced (e.g. `-beta.N`,
+# `-alpha.N`, `-next.N`), the negative-glob list MUST be extended in
+# lock-step or self-trigger returns. The same invariant applies to the
+# `Classify` step further below — its accepted-tag regex must align with
+# the trigger filter's exclusion list.
+# ─────────────────────────────────────────────────────────────────────────────
 
 on:
   push:
+    branches: [main]
+    paths-ignore:
+      - '**.md'
+      - 'docs/**'
+      - 'LICENSE'
     tags:
+      # Negative-globbed exclusion of RC tags this workflow itself produces
+      # (see the SELF-TRIGGER INVARIANT in the header comment).
       - 'v*'
-
-# No workflow-level permissions — scoped per job below.
+      - '!v*-rc.*'
+  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'
+# Workflow-level deny-all; each job declares the minimum it needs.
 permissions: {}
 
-# 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.
+# Distinct refs (refs/heads/main, refs/tags/v*) run in parallel. The
+# release-PR-skip in rc-guard is the load-bearing invariant that prevents
+# an RC main-push and a stable tag-push colliding on the same release commit.
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: false
 
 jobs:
+  # ── Phase 1: classify the triggering event into a release mode ─────────────
+  route:
+    name: Classify release event
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    permissions:
+      contents: read
+    outputs:
+      mode: ${{ steps.classify.outputs.mode }}
+      head_sha: ${{ steps.classify.outputs.head_sha }}
+      bump_input: ${{ inputs.bump }}
+      force_input: ${{ inputs.force }}
+    steps:
+      - name: Classify
+        id: classify
+        shell: bash
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          GH_REF: ${{ github.ref }}
+          GH_REF_NAME: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+
+          HEAD_SHA="${GITHUB_SHA}"
+          echo "head_sha=${HEAD_SHA}" >> "$GITHUB_OUTPUT"
+
+          # Sanitize before logging (annotation-injection defense in depth).
+          REF_SAFE="${GH_REF//::/__}"
+          REF_NAME_SAFE="${GH_REF_NAME//::/__}"
+          echo "event=${EVENT_NAME} ref=${REF_SAFE} ref_name=${REF_NAME_SAFE}"
+
+          MODE=""
+          case "${EVENT_NAME}" in
+            workflow_dispatch)
+              # Manual dispatch is only valid on main — that's the only ref
+              # where a real publish makes sense.
+              if [ "${GH_REF}" = "refs/heads/main" ]; then
+                MODE="rc"
+              else
+                echo "::error::workflow_dispatch is only permitted on refs/heads/main (got ${REF_SAFE})."
+                exit 1
+              fi
+              ;;
+            push)
+              case "${GH_REF}" in
+                refs/heads/main)
+                  MODE="rc"
+                  ;;
+                refs/tags/v*)
+                  # The trigger filter already excluded v*-rc.* tags. Anything
+                  # reaching here is either a stable semver or a malformed v*.
+                  TAG="${GH_REF#refs/tags/}"
+                  if [[ "${TAG}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+                    MODE="stable"
+                  else
+                    echo "::error::malformed v* tag rejected: ${REF_NAME_SAFE}"
+                    echo "::error::stable tags must match ^v[0-9]+\\.[0-9]+\\.[0-9]+\$"
+                    exit 1
+                  fi
+                  ;;
+                *)
+                  echo "::error::unexpected push ref ${REF_SAFE} reached publish workflow."
+                  exit 1
+                  ;;
+              esac
+              ;;
+            *)
+              echo "::error::unsupported event ${EVENT_NAME}."
+              exit 1
+              ;;
+          esac
+
+          echo "mode=${MODE}" >> "$GITHUB_OUTPUT"
+          echo "Classified as mode=${MODE}"
+
+  # ── Phase 2 (RC only): dedup marker + release-PR skip ──────────────────────
+  rc-guard:
+    name: RC guard (marker + release-PR skip)
+    needs: route
+    if: needs.route.outputs.mode == 'rc'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+      pull-requests: 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
+          # rc-guard reads only — no git pushes from this job. Skip the
+          # default extraheader credential persistence (artipacked audit).
+          persist-credentials: false
+
+      - name: Decide
+        id: decide
+        shell: bash
+        env:
+          FORCE: ${{ inputs.force }}
+          BUMP_INPUT: ${{ inputs.bump }}
+          EVENT_NAME: ${{ github.event_name }}
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+        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
+
+          # Explicit cycle reset on dispatch bypasses dedup.
+          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
+
+          # ── Skip when the merge commit corresponds to a release ───────────
+          # This skip is load-bearing: it prevents an RC build firing on the
+          # release-PR commit from racing the imminent stable-tag push on the
+          # same SHA. Two complementary checks:
+          #   1. HEAD subject matches `chore: release vX.Y.Z` (the canonical
+          #      release-PR title). Anchored to require the bare title or the
+          #      squash-merge `(#NNNN)` suffix exactly. Case-insensitive so
+          #      `Chore: Release v1.2.3` (IDE auto-capitalization) still
+          #      matches — prior commit-author conventions left the door open.
+          #   2. Squash-merged PR carries the `release` label.
+          # Either match suppresses the rc build — stable releases publish on
+          # the v-tag instead.
+          HEAD_SUBJECT="$(git log -1 --pretty=%s HEAD)"
+          # Sanitize GitHub-Actions annotation prefixes before logging — even
+          # though %s strips newlines, a crafted subject containing `::error::`
+          # could forge log annotations.
+          HEAD_SUBJECT_SAFE="${HEAD_SUBJECT//::/__}"
+          RELEASE_SUBJECT_RE='^chore:[[:space:]]*release[[:space:]]+v[0-9]+\.[0-9]+\.[0-9]+([[:space:]]+\(#[0-9]+\))?$'
+          shopt -s nocasematch
+          if [[ "$HEAD_SUBJECT" =~ $RELEASE_SUBJECT_RE ]]; then
+            shopt -u nocasematch
+            echo "HEAD commit subject matches a release commit — skipping rc."
+            echo "  subject (sanitised): $HEAD_SUBJECT_SAFE"
+            echo "should_run=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          shopt -u nocasematch
+
+          # Squash-merge commits include `(#NNNN)` at the end of the subject.
+          if [[ "$HEAD_SUBJECT" =~ \(#([0-9]+)\)[[:space:]]*$ ]]; then
+            PR_NUM="${BASH_REMATCH[1]}"
+            echo "Detected squash-merge of PR #$PR_NUM — checking labels."
+            if LABELS_JSON="$(gh pr view "$PR_NUM" --repo "$REPO" --json labels 2>/dev/null)"; then
+              if printf '%s' "$LABELS_JSON" | jq -e '.labels[] | select(.name == "release")' >/dev/null; then
+                echo "PR #$PR_NUM has the 'release' label — skipping rc."
+                echo "should_run=false" >> "$GITHUB_OUTPUT"
+                exit 0
+              fi
+              echo "PR #$PR_NUM has no 'release' label — proceeding."
+            else
+              # Lookup failure is not fatal — fall through to dedup check.
+              echo "::warning::Could not read labels for PR #${PR_NUM} — falling through."
+            fi
+          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
+
+  # ── Phase 3: reusable CI gate ──────────────────────────────────────────────
+  # Runs for both rc (when guard says go) and stable. No `secrets:` passed —
+  # ci.yml and its entire reusable-workflow chain (ci-quality, ci-tests,
+  # ci-e2e, ci-scope-parity, ci-report) reference zero `secrets.*` values;
+  # passing any would be unused surface. GITHUB_TOKEN is implicit.
   ci:
+    needs: [route, rc-guard]
+    if: ${{ always() && (needs.route.outputs.mode == 'stable' || needs.rc-guard.outputs.should_run == 'true') }}
     uses: ./.github/workflows/ci.yml
     permissions:
       contents: read
       actions: read
-      # 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.
 
+  # ── Phase 4: publish to npm + push refs (RC path) ──────────────────────────
+  # INVARIANT: `timeout-minutes` MUST stay below the App-token TTL (~60 min
+  # for actions/create-github-app-token installation tokens). The atomic
+  # tag-push step relies on the token minted at job start; if the job ever
+  # runs longer than the TTL, the push fails with an opaque 401. If you
+  # need to raise the timeout, re-mint the token immediately before the
+  # `Create and push rc tags` step instead.
   publish:
-    needs: ci
+    name: Publish to npm
+    needs: [route, rc-guard, ci]
+    if: ${{ always() && needs.ci.result == 'success' && (needs.route.outputs.mode == 'stable' || needs.rc-guard.outputs.should_run == 'true') }}
     runs-on: ubuntu-latest
-    timeout-minutes: 15
+    timeout-minutes: 20
     permissions:
+      # contents: write — RC path needs it for `git push --atomic` (v-tag +
+      # marker). Stable path runs in the same job and inherits the grant; it
+      # never invokes `git push`, so the elevated scope is unused there.
+      # id-token: write — npm provenance attestation.
       contents: write
       id-token: write
+    outputs:
+      # Two distinct step IDs feed this output; exactly one fires per run.
+      vtag: ${{ steps.rc-tags.outputs.vtag || steps.stable-vtag.outputs.vtag }}
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      # ── Mint short-lived GitHub App token (RC only) ──────────────────────
+      # Industry direction (2025-2026): GitHub Apps with
+      # `actions/create-github-app-token` over long-lived PATs for
+      # workflow-touching tag pushes. Same fine-grained permission surface,
+      # ~1h expiry, not tied to a user seat, organizationally auditable.
+      # Replaces a prior fine-grained PAT.
+      #
+      # Required secrets (set in repo Settings → Secrets and variables → Actions):
+      #   secrets.RELEASE_APP_ID         — the App's numeric ID
+      #   secrets.RELEASE_APP_PRIVATE_KEY — the App's PEM private key
+      # (The App ID is technically not sensitive — it's visible on the App's
+      # settings page — but storing it as a secret is harmless and avoids
+      # mixing storage classes for the same App.)
+      # The App must be installed on this repository with:
+      #   - Contents: write         (push the v-tag and rc marker)
+      #   - Workflows: write        (because the v-tag's tree may touch
+      #                              .github/workflows/**, which the default
+      #                              GITHUB_TOKEN cannot author)
+      #   - Metadata: read          (required for the `gh api /users/<slug>[bot]`
+      #                              bot-identity lookup in the tag-push step)
+      - name: Mint GitHub App token (RC)
+        if: needs.route.outputs.mode == 'rc'
+        id: app-token
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        with:
+          # `client-id` is the renamed input that supersedes the deprecated
+          # `app-id` in v3.x. The action accepts the App's numeric ID or
+          # its Client ID under this name. We pass the numeric App ID,
+          # which the action resolves correctly.
+          client-id: ${{ secrets.RELEASE_APP_ID }}
+          private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
+
+      # ── Separate checkout steps per mode ─────────────────────────────────
+      # Conditional `token:` expressions are footguns: empty string passed to
+      # actions/checkout fails opaquely, and `|| github.token` silently
+      # degrades a missing token to GITHUB_TOKEN, masking auth failures until
+      # the eventual `git push`. Two distinct steps make the auth contract
+      # explicit and fail loudly at checkout when the App token mint failed
+      # on the RC path.
+      - name: Checkout (RC)
+        if: needs.route.outputs.mode == 'rc'
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+          # Short-lived GitHub App installation token. Required because the
+          # v-tag push lands at a SHA whose tree may touch
+          # `.github/workflows/**`, which the default GITHUB_TOKEN cannot
+          # author.
+          token: ${{ steps.app-token.outputs.token }}
+          # Do not persist the token in .git/config (artipacked audit). The
+          # RC tag push uses an inline `http.extraheader` at push time only;
+          # the credential never lands on disk. See the
+          # `Create and push rc tags` step below.
+          persist-credentials: false
+
+      - name: Checkout (stable)
+        if: needs.route.outputs.mode == 'stable'
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        # No `token:` — actions/checkout uses GITHUB_TOKEN by default. Stable
+        # path performs no git pushes; the default scope is sufficient.
+        with:
+          # No git pushes from the stable path either. Skip credential
+          # persistence (artipacked audit).
+          persist-credentials: false
+
+      - name: Working-tree sanity
+        # Defense in depth (mirrors the vtag integrity gate, but on the input side):
+        # if a route-mode regression skipped both checkout `if:` gates, all
+        # downstream steps would run on a bare runner and produce confusing
+        # ENOENT errors. Fail loudly and early here instead.
+        shell: bash
+        run: |
+          if [ ! -f gitnexus/package.json ]; then
+            echo "::error::no working tree at gitnexus/package.json — route classification likely failed silently."
+            exit 1
+          fi
+
       - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
-          node-version: 22
-          registry-url: https://registry.npmjs.org
-          # Hermetic install for the published artifact — no cache carry-over
-          # from non-tag contexts. setup-node v5+ caches by default when a
-          # packageManager field is present in package.json, so the explicit
-          # opt-out is required to clear the zizmor cache-poisoning audit.
-          # ~30s slower per release; runs rarely.
+          # Node 24 ships with npm >= 11.5.x, which is the minimum that
+          # supports npm Trusted Publishing OIDC. Node 22 ships with npm
+          # 10.9.x (no OIDC) and `npm install -g npm@latest` to self-upgrade
+          # is fragile — it can crash the in-flight reify with
+          # `MODULE_NOT_FOUND` on `promise-retry` etc. Bumping the Node
+          # version is the clean fix; the package's `engines` field is
+          # `>=22.0.0` so consumer-side compatibility is unaffected (this
+          # Node version is only used during publish, not by package users).
+          node-version: 24
+          # `registry-url:` is intentionally OMITTED. Under npm Trusted
+          # Publishing, OIDC only engages when no credential is configured.
+          # Setting `registry-url:` would make setup-node write
+          # `//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}` into the
+          # runner's .npmrc AND export NODE_AUTH_TOKEN from its `token:`
+          # input (default github.token). `npm publish` would then attempt
+          # GITHUB_TOKEN as the npm token, get rejected with 404, and OIDC
+          # would never be tried. See actions/setup-node#1440 and the GitHub
+          # Community discussion #176761 for the upstream bug and consensus
+          # workaround.
+          #
+          # Hermetic install for published artifacts — opt out of the v5+
+          # default packageManager-based caching (clears the zizmor
+          # cache-poisoning audit). ~30s slower per release; runs rarely.
           package-manager-cache: false
+
       - name: Build gitnexus-shared
         run: npm install && npm run build
         working-directory: gitnexus-shared
 
-      - run: npm ci
+      - name: Install gitnexus dependencies
+        run: npm ci
         working-directory: gitnexus
 
-      - name: Verify version consistency
+      # ── Stable-only: verify the tag and package.json agree ───────────────
+      - name: Verify version consistency (stable)
+        if: needs.route.outputs.mode == 'stable'
         shell: bash
+        working-directory: gitnexus
         run: |
+          set -euo pipefail
           TAG_VERSION="${GITHUB_REF#refs/tags/v}"
-          if ! [[ "$TAG_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$ ]]; then
-            echo "::error::Tag does not follow semver: v$TAG_VERSION"
+          # Stable mode REJECTS prerelease suffixes — those are filtered at
+          # trigger by the negative-glob filter, but defend at the bash layer too.
+          if ! [[ "$TAG_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "::error::Stable tag must be ^v[0-9]+.[0-9]+.[0-9]+$ — got v$TAG_VERSION"
             exit 1
           fi
           PKG_VERSION=$(node -p "require('./package.json').version")
@@ -65,24 +424,376 @@ jobs:
             exit 1
           fi
           echo "Version verified: $PKG_VERSION"
-        working-directory: gitnexus
 
-      - name: Build
+      # ── RC-only: compute the next rc version against the live registry ──
+      - name: Resolve rc version (rc)
+        id: rc-version
+        if: needs.route.outputs.mode == 'rc'
+        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
+          #    (retry-loud policy: never silently substitute on transient errors).
+          NPM_STDERR_LATEST="$(mktemp)"
+          if CURRENT_LATEST="$(npm view "$PKG_NAME" version 2>"$NPM_STDERR_LATEST")"; then
+            :
+          else
+            if grep -qiE 'E404|not found' "$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 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 -qiE 'E404|not found' "$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 != auto → explicit cycle reset.
+          #    - Otherwise (push, or dispatch with bump=auto) → continue the
+          #      highest active rc base > latest if any; else patch from latest.
+          # Curated wrapper around `npx semver` — bare npx errors are noisy
+          # and don't distinguish registry-unreachable from invalid-bump-spec.
+          semver_bump() {
+            local kind="$1" current="$2" stderr_file out
+            stderr_file="$(mktemp)"
+            if out="$(npx --yes -p semver@7 semver -i "$kind" "$current" 2>"$stderr_file")"; then
+              rm -f "$stderr_file"
+              printf '%s' "$out"
+              return 0
+            fi
+            echo "::error::semver bump failed (kind=${kind}, current=${current}):" >&2
+            cat "$stderr_file" >&2
+            rm -f "$stderr_file"
+            return 1
+          }
+
+          if [ "$EVENT_NAME" = "workflow_dispatch" ] \
+             && [ -n "${BUMP_INPUT:-}" ] \
+             && [ "${BUMP_INPUT:-auto}" != "auto" ]; then
+            BASE="$(semver_bump "$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="$(semver_bump 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
+          #    (race with another run), abort before re-publishing.
+          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"
+            echo "rc_n=$NEXT_N"
+            echo "rc_version=$RC_VERSION"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Apply rc version in-CI
+        if: needs.route.outputs.mode == 'rc'
+        shell: bash
+        working-directory: gitnexus
+        run: |
+          set -euo pipefail
+          npm version "${{ steps.rc-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
-        working-directory: gitnexus
-
-      - name: Publish to npm
-        run: npm publish --provenance --access public
+        # Cheap verification that the tarball assembles before the real publish.
+        shell: bash
         working-directory: gitnexus
         env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NPM_TAG: ${{ needs.route.outputs.mode == 'rc' && 'rc' || 'latest' }}
+        run: npm publish --dry-run --tag "$NPM_TAG"
 
-      - name: Extract release notes from CHANGELOG
+      # ── Acquire the "rc lock" BEFORE publishing (idempotency anchor) ─────
+      # We create two refs and push 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.
+      # Push fails → nothing published. Push succeeds, npm fails → marker
+      # blocks retries until manual cleanup (see Rollback Runbook in plan).
+      - name: Create and push rc tags
+        id: rc-tags
+        if: needs.route.outputs.mode == 'rc'
+        shell: bash
+        working-directory: gitnexus
+        env:
+          RC_VERSION: ${{ steps.rc-version.outputs.rc_version }}
+          HEAD_SHA: ${{ needs.rc-guard.outputs.head_sha }}
+          # Short-lived GitHub App token. Auth is supplied inline at push
+          # time via `http.extraheader` (per GitHub's documented
+          # x-access-token Basic pattern). It is NOT persisted in
+          # .git/config (artipacked audit) — checkout above ran with
+          # `persist-credentials: false`.
+          PUSH_TOKEN: ${{ steps.app-token.outputs.token }}
+          # App's slug from create-github-app-token (e.g. `gitnexus-release-bot`).
+          # Used to attribute the release commit to the App identity rather
+          # than the generic github-actions[bot]. The bot's numeric user-id
+          # is resolved at runtime via the GitHub API (the action does not
+          # expose it directly as of v3.2.0).
+          APP_SLUG: ${{ steps.app-token.outputs.app-slug }}
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: |
+          set -euo pipefail
+          VTAG="v${RC_VERSION}"
+          MARKER="rc/${HEAD_SHA}"
+
+          # Resolve the App's bot user-id and construct the noreply email
+          # in the GitHub-canonical `<id>+<slug>[bot]@users.noreply.github.com`
+          # shape. `[bot]` is part of the actual login on GitHub.
+          #
+          # The lookup is wrapped in a bounded retry because the first RC
+          # after App installation may hit propagation delay (404), and
+          # transient api.github.com 5xx during heavy org activity is a real
+          # failure class. Without retry, every transient blip aborts the
+          # entire release after CI has already succeeded.
+          BOT_LOGIN="${APP_SLUG}[bot]"
+          BOT_USER_ID=""
+          api_stderr="$(mktemp)"
+          for attempt in 1 2 3; do
+            if BOT_USER_ID="$(gh api "/users/${BOT_LOGIN}" --jq .id 2>"$api_stderr")" \
+               && [[ "${BOT_USER_ID}" =~ ^[0-9]+$ ]]; then
+              break
+            fi
+            BOT_USER_ID=""
+            if [ "$attempt" -lt 3 ]; then
+              echo "::warning::bot user-id lookup attempt ${attempt} failed; retrying in $((attempt * 5))s"
+              sleep $((attempt * 5))
+            fi
+          done
+          if ! [[ "${BOT_USER_ID}" =~ ^[0-9]+$ ]]; then
+            echo "::error::Could not resolve bot user-id for ${BOT_LOGIN} after 3 attempts."
+            echo "::error::gh api stderr:"
+            cat "$api_stderr" >&2 || true
+            echo "::error::Common causes: (a) newly-installed App — user record still propagating to /users/ (wait ~5min, redispatch with force=true); (b) App lacks Metadata: read permission; (c) transient api.github.com 5xx (redispatch)."
+            rm -f "$api_stderr"
+            exit 1
+          fi
+          rm -f "$api_stderr"
+          git config user.name  "${BOT_LOGIN}"
+          git config user.email "${BOT_USER_ID}+${BOT_LOGIN}@users.noreply.github.com"
+
+          # Detached release commit with the version bump — main stays
+          # pristine, but the v-tag's tree matches the published package
+          # exactly (release-integrity).
+          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"
+
+          git tag -a "$VTAG" "$RELEASE_SHA" -m "$VTAG"
+          git tag "$MARKER" "$HEAD_SHA"
+
+          # Inline auth header. The base64-encoded form is masked as well
+          # as the raw token, because GitHub's secret-masker only masks the
+          # raw value — any subsequent `set -x` / GIT_TRACE line would
+          # otherwise expose the encoded credential.
+          #
+          # `set +x` wraps the compute+mask pair so that if an operator
+          # enables ACTIONS_STEP_DEBUG=true for triage (which turns on
+          # `set -x` globally), the assignment is NOT traced for the one
+          # line between compute and mask-registration. Without this wrap,
+          # debug mode would log `+ auth_header='Authorization: Basic <encoded>'`
+          # exposing a still-valid (~1h) App token.
+          { set +x; } 2>/dev/null
+          auth_header="Authorization: Basic $(printf 'x-access-token:%s' "${PUSH_TOKEN}" | base64 -w0)"
+          echo "::add-mask::${auth_header}"
+          # Re-enable tracing only when explicitly requested via step-debug.
+          if [ "${ACTIONS_STEP_DEBUG:-false}" = "true" ]; then set -x; fi
+
+          # Atomic push of both refs. If either would clobber an existing
+          # remote ref, the push fails and we stop before npm publish.
+          git -c http.extraheader="${auth_header}" \
+              push --atomic origin "refs/tags/$VTAG" "refs/tags/$MARKER"
+
+          {
+            echo "vtag=$VTAG"
+            echo "marker=$MARKER"
+            echo "release_sha=$RELEASE_SHA"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Set vtag (stable)
+        id: stable-vtag
+        if: needs.route.outputs.mode == 'stable'
+        shell: bash
+        # github.ref_name flows in via env to avoid templating into the
+        # shell source (template-injection audit). Even though refs are
+        # constrained by git naming rules, the env-passthrough pattern
+        # makes injection structurally impossible.
+        env:
+          REF_NAME: ${{ github.ref_name }}
+        run: |
+          echo "vtag=${REF_NAME}" >> "$GITHUB_OUTPUT"
+
+      # ── vtag integrity gate ──────────────────────────────────────────────
+      # Fail closed before any artifact-producing step (npm publish, Release,
+      # Docker) runs against an empty or mode-mismatched vtag. Prevents the
+      # silent "Release named main" / "Docker tagged from ref fallback"
+      # failure modes that the previous draft was vulnerable to.
+      - name: vtag integrity gate
+        id: vtag-gate
+        shell: bash
+        env:
+          MODE: ${{ needs.route.outputs.mode }}
+          VTAG: ${{ steps.rc-tags.outputs.vtag || steps.stable-vtag.outputs.vtag }}
+        run: |
+          set -euo pipefail
+
+          if [ -z "$VTAG" ]; then
+            echo "::error::vtag is empty — refusing to create GitHub Release or trigger Docker."
+            exit 1
+          fi
+
+          case "$MODE" in
+            rc)
+              if ! [[ "$VTAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+-rc\.[0-9]+$ ]]; then
+                echo "::error::vtag '${VTAG}' does not match rc shape ^v[0-9]+.[0-9]+.[0-9]+-rc.[0-9]+$"
+                exit 1
+              fi
+              ;;
+            stable)
+              if ! [[ "$VTAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+                echo "::error::vtag '${VTAG}' does not match stable shape ^v[0-9]+.[0-9]+.[0-9]+$"
+                exit 1
+              fi
+              ;;
+            *)
+              echo "::error::unknown mode '${MODE}' at vtag integrity gate."
+              exit 1
+              ;;
+          esac
+
+          echo "vtag verified: ${VTAG} (mode=${MODE})"
+          echo "vtag=${VTAG}" >> "$GITHUB_OUTPUT"
+
+      # npm Trusted Publishing (GA'd 2025-07-31). OIDC authentication only
+      # engages when no npm credential is configured anywhere — the absence
+      # is the signal. Two upstream behaviors had to be neutralized for
+      # this to work:
+      #
+      #   1. setup-node's `registry-url:` is omitted (see the setup-node
+      #      step above). With it, setup-node writes
+      #      `//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}` into
+      #      .npmrc and exports NODE_AUTH_TOKEN from `token:` (defaulting
+      #      to github.token). npm publish then sends GITHUB_TOKEN as the
+      #      bearer credential and the registry returns 404. OIDC is never
+      #      tried because npm thinks it already has a credential.
+      #   2. The runner's bundled npm (10.9.x on Node 22) has no OIDC
+      #      support; the upgrade step above pins it to >= 11.5.1.
+      #
+      # Provenance is auto-attached by the registry on trusted-publisher
+      # publishes — no --provenance flag needed.
+      #
+      # Prerequisite: register the package as a trusted publisher at
+      # https://www.npmjs.com/package/gitnexus/access (Publishing access →
+      # Trusted Publishers → GitHub Actions):
+      #   Owner:       abhigyanpatwari
+      #   Repository:  GitNexus
+      #   Workflow:    publish.yml
+      #   Environment: (none)
+      - name: Publish to npm
+        shell: bash
+        working-directory: gitnexus
+        env:
+          NPM_TAG: ${{ needs.route.outputs.mode == 'rc' && 'rc' || 'latest' }}
+        run: npm publish --access public --tag "$NPM_TAG"
+
+      # ── Stable-only: pull CHANGELOG body if present ──────────────────────
+      - name: Extract release notes from CHANGELOG (stable)
         id: changelog
+        if: needs.route.outputs.mode == 'stable'
         shell: bash
         run: |
           VERSION="${GITHUB_REF#refs/tags/v}"
@@ -98,5 +809,90 @@ jobs:
       - name: Create GitHub Release
         uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda # v2
         with:
-          body_path: ${{ steps.changelog.outputs.fallback == 'false' && '/tmp/release-notes.md' || '' }}
-          generate_release_notes: ${{ steps.changelog.outputs.fallback == 'true' }}
+          tag_name: ${{ steps.vtag-gate.outputs.vtag }}
+          name: >-
+            ${{ needs.route.outputs.mode == 'rc'
+                && format('Release Candidate {0}', steps.vtag-gate.outputs.vtag)
+                || steps.vtag-gate.outputs.vtag }}
+          prerelease: ${{ needs.route.outputs.mode == 'rc' }}
+          make_latest: ${{ needs.route.outputs.mode == 'stable' && 'true' || 'false' }}
+          # Stable: prefer CHANGELOG body, fall back to auto-generated.
+          # RC: always auto-generated + the prerelease body block below.
+          body_path: >-
+            ${{ needs.route.outputs.mode == 'stable' && steps.changelog.outputs.fallback == 'false'
+                && '/tmp/release-notes.md' || '' }}
+          generate_release_notes: >-
+            ${{ needs.route.outputs.mode == 'rc'
+                || steps.changelog.outputs.fallback == 'true' }}
+          body: >-
+            ${{ needs.route.outputs.mode == 'rc' && format(
+              'Automated release candidate build from `main`.{0}{0}**npm:** `npm install gitnexus@rc`{0}**Version:** `{1}`{0}**Target base:** `{2}` (rc #{3}){0}**Source commit (main):** {4}{0}**Release commit (versioned tree):** {5}{0}{0}Release candidates are pre-stable builds intended for early testing. Stable releases remain on the `latest` dist-tag.',
+              '\n',
+              steps.rc-version.outputs.rc_version,
+              steps.rc-version.outputs.base,
+              steps.rc-version.outputs.rc_n,
+              needs.rc-guard.outputs.head_sha,
+              steps.rc-tags.outputs.release_sha
+            ) || '' }}
+
+      # ── RC partial-failure cleanup ───────────────────────────────────────
+      # If anything after the atomic tag-push step failed (npm publish
+      # blew up, GitHub Release call timed out, etc.), the v-tag and
+      # rc/<SHA> marker are already on origin. External consumers
+      # (Renovate, Dependabot, Releases RSS) can ingest a phantom tag for
+      # a version that was never published to npm. This step deletes them
+      # automatically so the operator's recovery is just "redispatch with
+      # force=true on the next commit", not a manual ref cleanup.
+      #
+      # Scoped strictly to RC + real (non-dry-run) + the rc-tags step
+      # actually produced a vtag (otherwise nothing to clean up). The
+      # App token is still valid (~1h TTL, job timeout 20min).
+      - name: Cleanup pushed tags on partial failure
+        if: ${{ failure() && needs.route.outputs.mode == 'rc' && steps.rc-tags.outputs.vtag != '' }}
+        shell: bash
+        working-directory: gitnexus
+        env:
+          VTAG: ${{ steps.rc-tags.outputs.vtag }}
+          MARKER: ${{ steps.rc-tags.outputs.marker }}
+          PUSH_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: |
+          set -uo pipefail
+          echo "::warning::Publish step failed after tag push. Cleaning up remote refs to prevent phantom-version ingestion by downstream consumers."
+
+          { set +x; } 2>/dev/null
+          auth_header="Authorization: Basic $(printf 'x-access-token:%s' "${PUSH_TOKEN}" | base64 -w0)"
+          echo "::add-mask::${auth_header}"
+          if [ "${ACTIONS_STEP_DEBUG:-false}" = "true" ]; then set -x; fi
+
+          # Delete v-tag and marker. Each delete is best-effort — if one
+          # is already absent (atomic push partially rejected, or earlier
+          # cleanup ran), the other still gets attempted.
+          for ref in "refs/tags/${VTAG}" "refs/tags/${MARKER}"; do
+            if git -c http.extraheader="${auth_header}" push origin --delete "${ref}" 2>&1; then
+              echo "deleted origin ${ref}"
+            else
+              echo "::warning::could not delete origin ${ref} — may already be absent or protected. Manual cleanup may be required."
+            fi
+          done
+
+          echo "::notice::Cleanup complete. To retry the release, redispatch the workflow with force=true on the same SHA, or push a new commit to main."
+
+  # ── Phase 5 (RC only): Docker images ───────────────────────────────────────
+  # R6: Docker remains RC-only. Stable Docker builds are explicitly deferred.
+  # Secrets are passed explicitly (not via `secrets: inherit`) so the
+  # callee's secret surface is auditable from the caller's source.
+  docker:
+    name: Build & Push RC Docker images
+    needs: [route, publish]
+    if: ${{ needs.route.outputs.mode == 'rc' && needs.publish.outputs.vtag != '' }}
+    uses: ./.github/workflows/docker.yml
+    secrets:
+      DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
+      DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
+    permissions:
+      contents: read
+      packages: write
+      id-token: write
+      attestations: write
+    with:
+      tag: ${{ needs.publish.outputs.vtag }}

.github/workflows/release-candidate.yml

@@ -1,459 +0,0 @@
-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
-      pull-requests: read # read PR labels on the merge commit
-    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 }}
-          GH_TOKEN: ${{ github.token }}
-          REPO: ${{ github.repository }}
-        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
-
-          # ── Skip when the merge commit corresponds to a release ─────────
-          # Two complementary checks (belt-and-suspenders):
-          #   1. The HEAD commit subject matches `chore: release vX.Y.Z`
-          #      (the canonical release-PR title in this repo). Anchored
-          #      at both ends to require the bare title or the squash-merge
-          #      `(#NNNN)` suffix exactly — rejects noisy variants like
-          #      `chore: release v1.0.0 (something unrelated)`.
-          #   2. The squash-merged PR carries the `release` label.
-          # Either match suppresses the rc build — stable releases publish
-          # via publish.yml on the v-tag, so the rc cycle should pause for
-          # them rather than racing the npm publish.
-          HEAD_SUBJECT="$(git log -1 --pretty=%s HEAD)"
-          # Sanitise GitHub-Actions annotation prefixes before logging the
-          # raw subject — defence-in-depth so a hypothetical commit subject
-          # containing `::error::` or `::set-output::` cannot forge log
-          # annotations even though %s strips newlines.
-          HEAD_SUBJECT_SAFE="${HEAD_SUBJECT//::/__}"
-          RELEASE_SUBJECT_RE='^chore:[[:space:]]*release[[:space:]]+v[0-9]+\.[0-9]+\.[0-9]+([[:space:]]+\(#[0-9]+\))?$'
-          if [[ "$HEAD_SUBJECT" =~ $RELEASE_SUBJECT_RE ]]; then
-            echo "HEAD commit subject matches a release commit — skipping rc."
-            echo "  subject (sanitised): $HEAD_SUBJECT_SAFE"
-            echo "should_run=false" >> "$GITHUB_OUTPUT"
-            exit 0
-          fi
-
-          # Squash-merge commits include `(#NNNN)` at the end of the subject.
-          if [[ "$HEAD_SUBJECT" =~ \(#([0-9]+)\)[[:space:]]*$ ]]; then
-            PR_NUM="${BASH_REMATCH[1]}"
-            echo "Detected squash-merge of PR #$PR_NUM — checking labels."
-            if LABELS_JSON="$(gh pr view "$PR_NUM" --repo "$REPO" --json labels 2>/dev/null)"; then
-              if printf '%s' "$LABELS_JSON" | jq -e '.labels[] | select(.name == "release")' >/dev/null; then
-                echo "PR #$PR_NUM has the 'release' label — skipping rc."
-                echo "should_run=false" >> "$GITHUB_OUTPUT"
-                exit 0
-              fi
-              echo "PR #$PR_NUM has no 'release' label — proceeding."
-            else
-              # Lookup failure is not fatal — fall through to the dedup check
-              # so a transient GH API hiccup doesn't silently suppress rc builds.
-              echo "::warning::Could not read labels for PR #${PR_NUM} — falling through."
-            fi
-          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:
-      # The default GITHUB_TOKEN cannot be granted `workflows: write`, so
-      # tag pushes that reach a commit which modified `.github/workflows/**`
-      # are rejected with: "refusing to allow a GitHub App to create or
-      # update workflow ... without `workflows` permission". We pass a
-      # fine-grained PAT (RELEASE_PUSH_TOKEN, scoped to this repo with
-      # Contents: write + Workflows: write) to `actions/checkout` so that
-      # the subsequent `git push --atomic` of the v-tag and rc marker
-      # carries the PAT's identity. Job-level GITHUB_TOKEN keeps its
-      # scoped permissions for everything else (npm provenance, etc.).
-      contents: write # push rc tag + marker (via PAT)
-      id-token: write # npm provenance
-    outputs:
-      vtag: ${{ steps.reltag.outputs.vtag }}
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-        with:
-          fetch-depth: 0
-          fetch-tags: true
-          # Use the PAT so `origin` is preauthed for `git push`. Without
-          # this the default GITHUB_TOKEN is wired into the remote, and a
-          # workflows-touching tag push is rejected — see the permissions
-          # block above.
-          token: ${{ secrets.RELEASE_PUSH_TOKEN }}
-
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
-        with:
-          node-version: 22
-          registry-url: https://registry.npmjs.org
-          # Hermetic install — release-candidate produces shipped artifacts.
-          # setup-node v5+ caches by default when a packageManager field is
-          # present in package.json; explicit opt-out is required to clear
-          # the zizmor cache-poisoning audit. See cache-poisoning audit.
-          package-manager-cache: false
-
-      - name: Build gitnexus-shared
-        run: npm install && npm run build
-        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"
-            echo "rc_n=$NEXT_N"
-            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"
-            echo "marker=$MARKER"
-            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.
-
-  # ── Build & push RC Docker images ────────────────────────────────────
-  # Calls docker.yml as a reusable workflow so that the build, signing, and
-  # attestation logic stays in one place. The publish job exposes `vtag`
-  # (e.g. `v1.2.3-rc.1`) as an output so we can pass it as the tag input.
-  # RC images are signed with Cosign keyless signing; the OIDC identity
-  # will be `docker.yml@refs/heads/main` (the caller's ref) rather than a
-  # tag ref — see README.md § Docker for the correct verify command for RCs.
-  docker:
-    name: Build & Push RC Docker images
-    needs: [guard, publish]
-    if: needs.guard.outputs.should_run == 'true' && needs.publish.outputs.vtag != ''
-    uses: ./.github/workflows/docker.yml
-    # Reusable workflows do not receive caller secrets unless inherited; without
-    # this, DOCKERHUB_* / GITHUB_TOKEN are empty in docker.yml → "Username and
-    # password required" on Docker Hub login (see same pattern on `ci:` above).
-    secrets: inherit
-    permissions:
-      contents: read
-      packages: write
-      id-token: write
-      attestations: write
-    with:
-      tag: ${{ needs.publish.outputs.vtag }}

.github/workflows/scorecard.yml

@@ -53,6 +53,6 @@ jobs:
           retention-days: 5
 
       - name: Upload to Security tab
-        uses: github/codeql-action/upload-sarif@e46ed2cbd01164d986452f91f178727624ae40d7 # v4.35.3
+        uses: github/codeql-action/upload-sarif@68bde559dea0fdcac2102bfdf6230c5f70eb485e # v4.35.4
         with:
           sarif_file: results.sarif

.github/workflows/trivy.yml

@@ -76,7 +76,7 @@ jobs:
           exit-code: '0'
 
       - name: Upload to Security tab
-        uses: github/codeql-action/upload-sarif@e46ed2cbd01164d986452f91f178727624ae40d7 # v4.35.3
+        uses: github/codeql-action/upload-sarif@68bde559dea0fdcac2102bfdf6230c5f70eb485e # v4.35.4
         with:
           sarif_file: trivy-${{ matrix.image.name }}.sarif
           category: trivy-${{ matrix.image.name }}

.github/workflows/workflow-lint.yml

@@ -76,7 +76,7 @@ jobs:
         continue-on-error: true
 
       - name: Upload SARIF
-        uses: github/codeql-action/upload-sarif@e46ed2cbd01164d986452f91f178727624ae40d7 # v4.35.3
+        uses: github/codeql-action/upload-sarif@68bde559dea0fdcac2102bfdf6230c5f70eb485e # v4.35.4
         with:
           sarif_file: zizmor.sarif
           category: zizmor

.github/zizmor.yml

@@ -37,7 +37,8 @@ rules:
       - pr-labeler.yml
 
   # Note: cache-poisoning is NOT exempted. The two prior findings in
-  # publish.yml and release-candidate.yml were fixed structurally by
-  # dropping `cache: npm` from those workflows (matches the pattern used
-  # by PyO3/maturin for the same audit). See the commit that added this
-  # file for the rationale.
+  # publish.yml and the former release-candidate.yml were fixed structurally
+  # by dropping `cache: npm` from those workflows (matches the pattern used
+  # by PyO3/maturin for the same audit). After the publish-workflow
+  # unification (issue #1609), only publish.yml remains; the same
+  # cache-poisoning hardening applies there.

.gitignore

@@ -68,8 +68,8 @@ gitnexus-web/test-results/
 eval/.coverage
 eval/.hypothesis/
 
-# Design docs (local only)
-docs/plans/
+# Local docs
+docs/
 
 gitnexus/test/fixtures/mini-repo/*.md
 gitnexus/test/fixtures/mini-repo/.claude

AGENTS.md

@@ -48,6 +48,7 @@ Commands and gotchas live under **Repo reference** below and in **[CONTRIBUTING.
 
 | Date | Version | Change |
 |------|---------|--------|
+| 2026-05-22 | 1.8.0 | Kotlin added to `MIGRATED_LANGUAGES` (registry-primary call resolution by default). Closes #1756 (companion-vs-instance dispatch) and #1757 (lambda scopes); refs #1746. RFC §6.4 corpus criterion waived (corpus-mode wiring is #927-scope); fixture criterion met. |
 | 2026-04-23 | 1.7.0 | TypeScript added to `MIGRATED_LANGUAGES` (registry-primary call resolution by default). |
 | 2026-04-20 | 1.6.0 | Added scope-resolution pipeline pointer (RFC #909 Ring 3); Python migrated to registry-primary. |
 | 2026-04-19 | 1.5.0 | Cross-repo impact (#794): `impact`/`query`/`context` accept `repo: "@<group>"` + `service`. Removed `group_query`/`group_contracts`/`group_status` MCP tools; added `gitnexus://group/{name}/contracts` and `gitnexus://group/{name}/status` resources. |
@@ -62,117 +63,64 @@ Commands and gotchas live under **Repo reference** below and in **[CONTRIBUTING.
 <!-- gitnexus:start -->
 # GitNexus — Code Intelligence
 
-Indexed as **GitNexus** (4325 symbols, 10556 relationships, 300 execution flows). Use MCP tools to understand code, assess impact, and navigate safely.
+This project is indexed by GitNexus as **GitNexus** (26675 symbols, 35395 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
 
-> If any tool warns the index is stale, run `npx gitnexus analyze` first.
+> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
 
 ## Always Do
 
-- **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 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
-
-- **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.
+- **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"})`.
 
 ## Never Do
 
-- 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 | 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_sync` | Rebuild group Contract Registry | `gitnexus_group_sync({name: "myGroup"})` |
-| `query` (group mode) | Cross-repo search in a group (RRF-merged) | `gitnexus_query({repo: "@myGroup", query: "auth"})` |
-| `context` (group mode) | 360° view across all member repos | `gitnexus_context({repo: "@myGroup", name: "validateUser"})` |
-| `impact` (group mode) | Cross-repo blast radius via Contract Bridge | `gitnexus_impact({repo: "@myGroup", target: "X", direction: "upstream"})` |
-
-> Group mode: pass `repo: "@<groupName>"` to fan out across all member repos, or `repo: "@<groupName>/<memberPath>"` to target a single member (path keys from `group.yaml`). Optional `service: "<monorepo/path>"` filters by service root. Group-level state (contracts, staleness) lives in the resources table below — there are **no** `group_query` / `group_context` / `group_impact` / `group_contracts` / `group_status` MCP tools.
->
-> For a full walkthrough of setting up a group across multiple repos that communicate over gRPC, see [docs/guides/microservices-grpc.md](docs/guides/microservices-grpc.md).
-
-## Impact Risk Levels
-
-| Depth | Meaning | Action |
-|-------|---------|--------|
-| 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 |
+- 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.
 
 ## Resources
 
 | Resource | Use for |
 |----------|---------|
-| `gitnexus://repo/GitNexus/context` | Codebase overview, index freshness |
+| `gitnexus://repo/GitNexus/context` | Codebase overview, check 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 |
-| `gitnexus://group/{name}/contracts` | Group Contract Registry (provider/consumer rows + cross-links) |
-| `gitnexus://group/{name}/status` | Per-member index + Contract Registry staleness report |
 
-## Self-Check Before Finishing
+## CLI
 
-1. `gitnexus_impact` was run for all modified symbols
-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
-
-```bash
-npx gitnexus analyze                 # incremental by default; preserves embeddings
-npx gitnexus analyze --force         # full rebuild from scratch (opt out of incremental)
-npx gitnexus analyze --embeddings    # also generate embeddings for new/changed nodes
-npx gitnexus analyze --drop-embeddings  # explicit opt-in to wipe existing embeddings
-```
-
-`analyze` runs **incrementally by default**. The pipeline still parses every file every run (cross-file resolution requires it), but tree-sitter parsing is **served from a content-addressed cache** at `.gitnexus/parse-cache.json` for chunks whose file contents haven't changed since the last run. Only changed-file rows (and their importers) are rewritten in LadybugDB; unchanged-file rows are preserved. Output is byte-equivalent to a full rebuild. Pass `--force` to wipe and re-index from scratch (e.g., to recover from a corrupt index, or after upgrading GitNexus).
-
-The parse cache key is **content-addressed and version-tagged**: it survives `--force` runs, and is automatically invalidated by a `gitnexus` package upgrade (so a new tree-sitter grammar doesn't silently replay stale parse output). Safe to delete `.gitnexus/parse-cache.json` at any time — it'll be rebuilt on the next analyze.
-
-Check `.gitnexus/meta.json` `stats.embeddings` (0 = none). A plain `analyze` no longer drops existing vectors — pass `--drop-embeddings` to wipe.
-
-> Claude Code: PostToolUse hook detects a stale index after `git commit` and `git merge` and prompts the agent to run `analyze`. The hook does not invoke `analyze` itself.
-
-## CLI Skills
-
-| 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` |
+| 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` |
+| Work in the Ingestion area (239 symbols) | `.claude/skills/generated/ingestion/SKILL.md` |
+| Work in the Extractors area (135 symbols) | `.claude/skills/generated/extractors/SKILL.md` |
+| Work in the Components area (112 symbols) | `.claude/skills/generated/components/SKILL.md` |
+| Work in the Lbug area (96 symbols) | `.claude/skills/generated/lbug/SKILL.md` |
+| Work in the Group area (94 symbols) | `.claude/skills/generated/group/SKILL.md` |
+| Work in the Cli area (92 symbols) | `.claude/skills/generated/cli/SKILL.md` |
+| Work in the Configs area (92 symbols) | `.claude/skills/generated/configs/SKILL.md` |
+| Work in the Type-extractors area (90 symbols) | `.claude/skills/generated/type-extractors/SKILL.md` |
+| Work in the Hooks area (88 symbols) | `.claude/skills/generated/hooks/SKILL.md` |
+| Work in the Unit area (80 symbols) | `.claude/skills/generated/unit/SKILL.md` |
+| Work in the Cpp area (73 symbols) | `.claude/skills/generated/cpp/SKILL.md` |
+| Work in the Scope-resolution area (72 symbols) | `.claude/skills/generated/scope-resolution/SKILL.md` |
+| Work in the Server area (66 symbols) | `.claude/skills/generated/server/SKILL.md` |
+| Work in the Local area (61 symbols) | `.claude/skills/generated/local/SKILL.md` |
+| Work in the Wiki area (60 symbols) | `.claude/skills/generated/wiki/SKILL.md` |
+| Work in the Workers area (57 symbols) | `.claude/skills/generated/workers/SKILL.md` |
+| Work in the Embeddings area (56 symbols) | `.claude/skills/generated/embeddings/SKILL.md` |
+| Work in the Typescript area (53 symbols) | `.claude/skills/generated/typescript/SKILL.md` |
+| Work in the Storage area (51 symbols) | `.claude/skills/generated/storage/SKILL.md` |
+| Work in the Php area (48 symbols) | `.claude/skills/generated/php/SKILL.md` |
 
 <!-- gitnexus:end -->
 

CLAUDE.md

@@ -52,3 +52,67 @@ If always-on instructions grow, load deep conventions via conditional reads (e.g
 ## GitNexus rules
 
 See the `<!-- gitnexus:start --> … <!-- gitnexus:end -->` block in **[AGENTS.md](AGENTS.md)** for the canonical MCP tools, impact analysis rules, and index instructions.
+
+<!-- gitnexus:start -->
+# GitNexus — Code Intelligence
+
+This project is indexed by GitNexus as **GitNexus** (26675 symbols, 35395 relationships, 300 execution flows). Use the GitNexus 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.
+
+## 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"})`.
+
+## 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.
+
+## Resources
+
+| Resource | Use for |
+|----------|---------|
+| `gitnexus://repo/GitNexus/context` | Codebase overview, check 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 |
+
+## 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` |
+| Work in the Ingestion area (239 symbols) | `.claude/skills/generated/ingestion/SKILL.md` |
+| Work in the Extractors area (135 symbols) | `.claude/skills/generated/extractors/SKILL.md` |
+| Work in the Components area (112 symbols) | `.claude/skills/generated/components/SKILL.md` |
+| Work in the Lbug area (96 symbols) | `.claude/skills/generated/lbug/SKILL.md` |
+| Work in the Group area (94 symbols) | `.claude/skills/generated/group/SKILL.md` |
+| Work in the Cli area (92 symbols) | `.claude/skills/generated/cli/SKILL.md` |
+| Work in the Configs area (92 symbols) | `.claude/skills/generated/configs/SKILL.md` |
+| Work in the Type-extractors area (90 symbols) | `.claude/skills/generated/type-extractors/SKILL.md` |
+| Work in the Hooks area (88 symbols) | `.claude/skills/generated/hooks/SKILL.md` |
+| Work in the Unit area (80 symbols) | `.claude/skills/generated/unit/SKILL.md` |
+| Work in the Cpp area (73 symbols) | `.claude/skills/generated/cpp/SKILL.md` |
+| Work in the Scope-resolution area (72 symbols) | `.claude/skills/generated/scope-resolution/SKILL.md` |
+| Work in the Server area (66 symbols) | `.claude/skills/generated/server/SKILL.md` |
+| Work in the Local area (61 symbols) | `.claude/skills/generated/local/SKILL.md` |
+| Work in the Wiki area (60 symbols) | `.claude/skills/generated/wiki/SKILL.md` |
+| Work in the Workers area (57 symbols) | `.claude/skills/generated/workers/SKILL.md` |
+| Work in the Embeddings area (56 symbols) | `.claude/skills/generated/embeddings/SKILL.md` |
+| Work in the Typescript area (53 symbols) | `.claude/skills/generated/typescript/SKILL.md` |
+| Work in the Storage area (51 symbols) | `.claude/skills/generated/storage/SKILL.md` |
+| Work in the Php area (48 symbols) | `.claude/skills/generated/php/SKILL.md` |
+
+<!-- gitnexus:end -->

CONTRIBUTING.md

@@ -144,16 +144,18 @@ If you use coding agents, follow project context files (e.g. `AGENTS.md`, `CLAUD
 
 ## Releases
 
-Two publish workflows ship `gitnexus` to npm:
+One workflow ships `gitnexus` to npm — `.github/workflows/publish.yml`. It
+routes between two modes based on the triggering event:
 
-- **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:
+- **Stable mode** — triggered by pushing any `v<X.Y.Z>` tag (no `-rc.*`
+  suffix; RC tags are excluded at trigger via a negative glob). 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. No Docker build (RC-only).
+- **Release-candidate mode** — runs on every push to `main` (typically a
+  merged PR) plus manual `workflow_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
@@ -170,36 +172,64 @@ Two publish workflows ship `gitnexus` to npm:
     caller's ref — see README.md § Docker for the verify command).
 
   Idempotency: the workflow pushes an `rc/<HEAD_SHA>` marker tag and a
-  `v<RC>` release tag **atomically, before** calling `npm publish`. The guard
-  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:
+  `v<RC>` release tag **atomically, before** calling `npm publish`. The
+  RC 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). The RC tag is excluded
+  from this workflow's `push: tags:` filter, so it does **not** re-trigger
+  publishing — preventing the double-publish failure mode tracked in #1609.
+  Recovery after a partial failure: the workflow's `if: failure()` cleanup
+  step in the `publish` job auto-deletes the v-tag and marker on most
+  post-publish failures, so the typical retry is just:
+
+  ```bash
+  gh workflow run publish.yml --ref main -f force=true
+  # or push a new commit to main, which will cut a fresh RC
+  ```
+
+  If auto-cleanup didn't run (e.g. the cleanup step itself failed, or the
+  failure happened in the route/rc-guard phase before the marker was
+  pushed), manual cleanup is:
 
   ```bash
   git push --delete origin rc/<HEAD_SHA> v<RC>
-  # then redispatch the workflow with force: true
+  # then redispatch with force: true
   ```
 
+  **Release-PR-skip subject pattern.** The rc-guard job recognizes a
+  squash-merged release commit by matching the commit subject against
+  `^chore: release vX.Y.Z` (optionally followed by ` (#NNNN)` for the
+  squash-merge PR-number suffix). Match is case-insensitive — `Chore: Release v1.2.3`
+  works too. PRs that should suppress the RC build must either use this
+  subject shape, or carry the `release` label so the label-based fallback
+  fires. Other release-style subjects (`chore(release): v1.2.3`,
+  `release: v1.2.3`) will NOT trigger the skip — please name the release
+  PR exactly `chore: release vX.Y.Z` to keep the dedup deterministic.
+
   **Docker-only partial failure:** if `publish` succeeds (npm tarball + tags
   are live) but the `docker` job subsequently fails (e.g. GHCR flakiness),
   the npm RC is already published and the `rc/<HEAD_SHA>` marker is in place.
-  Re-running `release-candidate.yml` with `force: true` will abort at the
-  "Version already exists on npm" guard. To recover without cutting a new RC:
+  Recovery without cutting a new RC:
 
   ```bash
-  # 1. Manually trigger only the docker workflow, passing the existing RC tag:
-  gh workflow run docker.yml --ref main -f tag=v<RC_VERSION>
-  # (requires a workflow_dispatch trigger on docker.yml — see note below)
+  # Re-run only the failed docker job from the original workflow run:
+  gh run rerun <run-id> --failed
   ```
 
-  Because `docker.yml` intentionally has no `workflow_dispatch` (images are
-  tag-driven by design), the practical recovery options are:
-  - Wait for the next commit on `main`, which will cut a new RC that includes
-    the Docker build.
-  - Manually run `docker build` + `docker push` locally and sign with Cosign
-    against the same digest.
-  - Delete `rc/<HEAD_SHA>` and `v<RC>` tags, then redispatch with `force: true` to re-run the full RC pipeline (cuts a new RC number).
+  Find the run ID via `gh run list --workflow=publish.yml --branch main`.
+  `docker.yml` intentionally has no `workflow_dispatch` trigger (images are
+  tag-driven by design), so the gh-run-rerun path is the supported recovery.
+
+  **GitHub Release transient failure** (npm publish succeeded, Release step
+  failed): the npm artifact is live but no GitHub Release page exists.
+  Recover by either re-running the failed job (`gh run rerun <run-id> --failed`),
+  or creating the Release manually:
+
+  ```bash
+  gh release create v<RC> --prerelease --generate-notes        # RC
+  gh release create v<X.Y.Z> --notes-file gitnexus/CHANGELOG.md # stable
+  ```
 
 The rc workflow never moves `latest`. To verify after a change, inspect dist-tags:
 

Dockerfile.cli

@@ -40,8 +40,8 @@ RUN npm prune --omit=dev --prefix gitnexus
 # node:22-bookworm-slim
 FROM node:22-bookworm-slim@sha256:9f6d5975c7dca860947d3915877f85607946403fc55349f39b4bc3688448bb6e AS runtime
 
-# curl for the healthcheck; git so `gitnexus` can clone repos at runtime.
-RUN apt-get update && apt-get install -y --no-install-recommends curl git && rm -rf /var/lib/apt/lists/* \
+# curl for the healthcheck; git for cloning; ca-certificates for TLS verification.
+RUN apt-get update && apt-get install -y --no-install-recommends curl git ca-certificates && rm -rf /var/lib/apt/lists/* \
     && rm -rf /usr/local/lib/node_modules/npm \
     && rm -rf /usr/local/lib/node_modules/corepack \
     && rm -f /usr/local/bin/npm /usr/local/bin/npx /usr/local/bin/corepack
@@ -58,6 +58,15 @@ COPY --from=builder --chown=node:node /app/gitnexus/package.json ./gitnexus/pack
 COPY --from=builder --chown=node:node /app/gitnexus/scripts/install-duckdb-extension.mjs ./gitnexus/scripts/install-duckdb-extension.mjs
 COPY --from=builder --chown=node:node /app/gitnexus/vendor ./gitnexus/vendor
 
+# Expose the `gitnexus` binary on PATH so the documented Docker workflow
+# (`docker compose exec gitnexus-server gitnexus index /workspace/<repo>`)
+# works without users having to invoke `node /app/gitnexus/dist/cli/index.js`.
+# `npm prune --omit=dev` in the builder stage strips `node_modules/.bin/`
+# entries, so the `gitnexus` bin declared in package.json (`dist/cli/index.js`,
+# which already carries `#!/usr/bin/env node` and 755 perms) is otherwise
+# unreachable from $PATH.
+RUN ln -s /app/gitnexus/dist/cli/index.js /usr/local/bin/gitnexus
+
 USER node
 
 # The web UI defaults to http://localhost:4747 - keep that contract.

GUARDRAILS.md

@@ -36,7 +36,7 @@ Format: **Trigger → Instruction → Reason**. Append new Signs when the same m
 ### Index seems corrupt or "incremental" is misbehaving
 
 - **Trigger:** `analyze` produces unexpected results, or `meta.json.incrementalInProgress` is set, or the index is in a half-state after a crash.
-- **Do:** `npx gitnexus analyze --force` to rebuild from scratch. The dirty-flag check forces this automatically when a previous incremental run didn't complete cleanly, but `--force` is the manual escape hatch. Safe to delete `.gitnexus/parse-cache.json` at any time — content-addressed, will be regenerated.
+- **Do:** `npx gitnexus analyze --force` to rebuild from scratch. The dirty-flag check forces this automatically when a previous incremental run didn't complete cleanly, but `--force` is the manual escape hatch. Safe to delete the `.gitnexus/parse-cache/` directory (and any legacy `.gitnexus/parse-cache.json`) at any time — content-addressed, will be regenerated.
 - **Why:** Incremental writeback is selective DB row replacement; if the on-disk state is inconsistent for any reason, a full rebuild is the cheapest path back to a known-good index.
 
 ### Embeddings vanished after analyze

README.md

@@ -1,4 +1,5 @@
 # GitNexus
+
 **⚠️ Important Notice:** GitNexus has NO official cryptocurrency, token, or coin. Any token/coin using the GitNexus name on Pump.fun or any other platform is **not affiliated with, endorsed by, or created by** this project or its maintainers. Do not purchase any cryptocurrency claiming association with GitNexus.
 
 <div align="center">
@@ -30,14 +31,9 @@
 
 Indexes any codebase into a knowledge graph — every dependency, call chain, cluster, and execution flow — then exposes it through smart tools so AI agents never miss code.
 
-
-
-
 https://github.com/user-attachments/assets/172685ba-8e54-4ea7-9ad1-e31a3398da72
 
-
-
-> *Like DeepWiki, but deeper.* DeepWiki helps you *understand* code. GitNexus lets you *analyze* it — because a knowledge graph tracks every relationship, not just descriptions.
+> _Like DeepWiki, but deeper._ DeepWiki helps you _understand_ code. GitNexus lets you _analyze_ it — because a knowledge graph tracks every relationship, not just descriptions.
 
 **TL;DR:** The **Web UI** is a quick way to chat with any repo. The **CLI + MCP** is how you make your AI agent actually reliable — it gives Cursor, Claude Code, Codex, and friends a deep architectural view of your codebase so they stop missing dependencies, breaking call chains, and shipping blind edits. Even smaller models get full architectural clarity, making it compete with Goliath models.
 
@@ -47,18 +43,17 @@ https://github.com/user-attachments/assets/172685ba-8e54-4ea7-9ad1-e31a3398da72
 
 [![Star History Chart](https://api.star-history.com/svg?repos=abhigyanpatwari/GitNexus&type=date&legend=top-left)](https://www.star-history.com/#abhigyanpatwari/GitNexus&type=date&legend=top-left)
 
-
 ## Two Ways to Use GitNexus
 
-|                   | **CLI + MCP**                                            | **Web UI**                                             |
-| ----------------- | -------------------------------------------------------------- | ------------------------------------------------------------ |
-| **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) |
-| **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                             |
+|             | **CLI + MCP**                                                         | **Web UI**                                                           |
+| ----------- | --------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| **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)      |
+| **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                                     |
 
 > **Bridge mode:** `gitnexus serve` connects the two — the web UI auto-detects the local server and can browse all your CLI-indexed repos without re-uploading or re-indexing.
 
@@ -69,6 +64,7 @@ https://github.com/user-attachments/assets/172685ba-8e54-4ea7-9ad1-e31a3398da72
 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
@@ -77,6 +73,7 @@ Enterprise includes:
 - **Priority feature/language support** - request new languages or features
 
 **Upcoming:**
+
 - Auto regression forensics
 - End-to-end test generation
 
@@ -109,7 +106,7 @@ That's it. This indexes the codebase, installs agent skills, registers Claude Co
 
 To configure MCP for your editor, run `npx gitnexus setup` once — or set it up manually below.
 
-> **Faster install (no C++ toolchain needed):** set `GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1` before `npm install -g gitnexus` to skip the native `tree-sitter-dart` and `tree-sitter-proto` builds. Dart/Proto files won't be parsed, but install completes in seconds without `python3`/`make`/`g++`. Strict `=1` only — any other value falls through to the rebuild.
+> **Faster install (no C++ toolchain needed):** set `GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1` before `npm install -g gitnexus` to skip vendored grammar materialize/build (`tree-sitter-dart`, `tree-sitter-proto`, `tree-sitter-swift`). Dart/Proto/Swift files won't be parsed, but install completes in seconds without `python3`/`make`/`g++`. Strict `=1` only — any other value falls through to the rebuild.
 
 ### MCP Setup
 
@@ -117,13 +114,13 @@ To configure MCP for your editor, run `npx gitnexus setup` once — or set it up
 
 ### Editor Support
 
-| Editor                | MCP | Skills | Hooks (auto-augment) | Support        |
-| --------------------- | --- | ------ | -------------------- | -------------- |
-| **Claude Code** | Yes | Yes    | Yes (PreToolUse + PostToolUse) | **Full** |
-| **Cursor**      | Yes | Yes    | Yes (postToolUse, [manual install](gitnexus-cursor-integration/README.md#hook-install)) | **Full** |
-| **Codex**       | Yes | Yes    | —                   | MCP + Skills   |
-| **Windsurf**    | Yes | —     | —                   | MCP            |
-| **OpenCode**    | Yes | Yes    | —                   | MCP + Skills   |
+| Editor          | MCP | Skills | Hooks (auto-augment)                                                                    | Support      |
+| --------------- | --- | ------ | --------------------------------------------------------------------------------------- | ------------ |
+| **Claude Code** | Yes | Yes    | Yes (PreToolUse + PostToolUse)                                                          | **Full**     |
+| **Cursor**      | Yes | Yes    | Yes (postToolUse, [manual install](gitnexus-cursor-integration/README.md#hook-install)) | **Full**     |
+| **Codex**       | Yes | Yes    | —                                                                                       | MCP + Skills |
+| **Windsurf**    | Yes | —      | —                                                                                       | MCP          |
+| **OpenCode**    | Yes | Yes    | —                                                                                       | MCP + Skills |
 
 > **Claude Code** gets the deepest integration: MCP tools + agent skills + PreToolUse hooks that enrich searches with graph context + PostToolUse hooks that detect a stale index after commits and prompt the agent to reindex.
 
@@ -131,10 +128,10 @@ To configure MCP for your editor, run `npx gitnexus setup` once — or set it up
 
 Built by the community — not officially maintained, but worth checking out.
 
-| Project | Author | Description |
-|---------|--------|-------------|
-| [pi-gitnexus](https://github.com/tintinweb/pi-gitnexus) | [@tintinweb](https://github.com/tintinweb) | GitNexus plugin for [pi](https://pi.dev) — `pi install npm:pi-gitnexus` |
-| [gitnexus-stable-ops](https://github.com/ShunsukeHayashi/gitnexus-stable-ops) | [@ShunsukeHayashi](https://github.com/ShunsukeHayashi) | Stable ops & deployment workflows (Miyabi ecosystem) |
+| Project                                                                       | Author                                                 | Description                                                             |
+| ----------------------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------- |
+| [pi-gitnexus](https://github.com/tintinweb/pi-gitnexus)                       | [@tintinweb](https://github.com/tintinweb)             | GitNexus plugin for [pi](https://pi.dev) — `pi install npm:pi-gitnexus` |
+| [gitnexus-stable-ops](https://github.com/ShunsukeHayashi/gitnexus-stable-ops) | [@ShunsukeHayashi](https://github.com/ShunsukeHayashi) | Stable ops & deployment workflows (Miyabi ecosystem)                    |
 
 > Have a project built on GitNexus? Open a PR to add it here!
 
@@ -197,7 +194,8 @@ args = ["-y", "gitnexus@latest", "mcp"]
 ```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 --repair-fts    # Fast path: rebuild/verify only FTS indexes on existing index data
+gitnexus analyze --force         # Full rebuild: re-parse + graph rebuild + FTS rebuild
 gitnexus analyze --skills        # Generate repo-specific skill files from detected communities
 gitnexus analyze --skip-embeddings  # Skip embedding generation (faster)
 gitnexus analyze --skip-agents-md  # Preserve custom AGENTS.md/CLAUDE.md gitnexus section edits
@@ -205,6 +203,8 @@ gitnexus analyze --skip-git        # Index folders that are not Git repositories
 gitnexus analyze --embeddings    # Enable embedding generation (slower, better search)
 gitnexus analyze --verbose       # Log skipped files when parsers are unavailable
 gitnexus analyze --worker-timeout 60  # Increase worker idle timeout for slow parses
+gitnexus analyze --wal-checkpoint-threshold 67108864  # 64 MiB. Control LadybugDB WAL auto-checkpoint threshold (default: 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB)
+gitnexus analyze --workers <n>        # Parse worker pool size (default: cores-1, capped at 16; 0 = sequential)
 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
@@ -229,6 +229,28 @@ gitnexus group status <name>     # Check staleness of repos in a group
 
 If `analyze` reports a worker parse timeout on a large or unusual repository, it keeps running and falls back safely. To give slow worker jobs more time, use `gitnexus analyze --worker-timeout 60` or set `GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=60000`. For very large files, `GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES` controls the worker job byte budget.
 
+#### Environment variables
+
+Most `analyze` knobs are also CLI flags (`--workers`, `--worker-timeout`, `--max-file-size`, `--verbose`). Use the env-var form when you'd otherwise repeat the same flag every run, or when invoking GitNexus from a long-running host (MCP server, eval-server, CI shell) that already manages its own environment. CLI flags take precedence over env vars; env vars take precedence over built-in defaults.
+
+| Variable                               | Default                   | Effect                                                                                                                                                     | Tune when…                                                                                                                                  |
+| -------------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GITNEXUS_WORKER_POOL_SIZE`            | `cores - 1`, capped at 16 | Parse worker pool size. `0` disables the pool (sequential fallback). Equivalent to `--workers <n>`.                                                        | Constrained containers (cgroup CPU limits), CI runners with explicit quotas, or debugging a worker-only crash via `0`.                      |
+| `GITNEXUS_PARSE_CHUNK_CONCURRENCY`     | `2`                       | Number of chunks whose file contents may be read into memory in parallel while the pool dispatches the current chunk. Worker dispatch itself stays serial. | Repos large enough to chunk (multi-MB total source) where disk I/O is a measurable fraction of analyze wall-clock.                          |
+| `GITNEXUS_VERBOSE`                     | unset                     | When `1`, enables verbose ingestion logs (skipped-file warnings, per-chunk throughput, parse-cache stats). Equivalent to `--verbose`.                      | Debugging an analyze that "completed" but seems to have missed files; tuning `--workers` / chunk concurrency against observable throughput. |
+| `GITNEXUS_PROFILE_DEFERRED`            | unset                     | When `1`, emits `[deferred-profile]` timing/progress logs for the post-chunk deferred resolution band (imports → heritage → buildHeritageMap → legacy call resolution). Implied by `GITNEXUS_VERBOSE`. | Diagnosing analyze stalls in "Resolving calls (all chunks)" on large Java/Kotlin repos (issue #1741) without the full verbose ingestion noise. |
+| `GITNEXUS_PROFILE_DEFERRED_SLOW_MS`    | `3000` (verbose) / `5000` | Per-file threshold in ms above which `processCallsFromExtracted` emits a `slow file …` log line. Parsed via `Number()`: accepts integers (`5000`), scientific notation (`2.5e3`), decimals (`.5`), and hex (`0x10`). Non-finite or non-positive values fall back to the default. | Hunting a few outlier files dominating the deferred call-resolution stage; lower to surface more, raise to focus only on the worst.          |
+| `GITNEXUS_MAX_FILE_SIZE`               | `512` (KB)                | Walker skip threshold in KB. Hard cap is `32768` (tree-sitter buffer ceiling). Equivalent to `--max-file-size <kb>`.                                       | Indexing repos with intentionally-large source files (generated parsers, vendored bundles) that should still be parsed.                     |
+| `GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS` | `30000`                   | Worker idle timeout in milliseconds before retry/fallback. Equivalent to `--worker-timeout <seconds>` × 1000.                                              | Slow-parsing files (large minified JS, deeply-nested TS types) that legitimately need more than 30s.                                        |
+| `GITNEXUS_WAL_CHECKPOINT_THRESHOLD`       | `67108864` (64 MiB)       | LadybugDB WAL auto-checkpoint threshold in bytes. Equivalent to `--wal-checkpoint-threshold <bytes>`. `-1` keeps LadybugDB's stock threshold (~16 MiB). Larger thresholds reduce checkpoint frequency but increase the WAL size at rotation time — choose a smaller value on disk-constrained environments. | You need a larger or smaller WAL auto-checkpoint threshold for your analyze workload.                                                         |
+| `GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES`  | `8388608` (8 MB)          | Per-job byte budget the pool will send to a worker in one `postMessage`.                                                                                   | Very large individual files; mostly diagnostic — bumping past 8 MB risks structured-clone memory pressure.                                  |
+| `GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT`        | `3`                       | Max replacement spawns per worker slot before the slot is dropped from the active rotation. Bounds respawn loops on a chronically-crashing slot.           | Hosts where a flaky worker should retry more (raise) or fail-fast (lower) before the slot is dropped.                                       |
+| `GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS`    | `5 × subBatchTimeoutMs`   | Total retry wall-time budget per job before quarantining. Combined with `timeoutBackoffFactor`, prevents exponentially-growing retries from stalling for hours. | Slow files that legitimately need long total retry windows; lower to fail-fast on stalls.                                                    |
+| `GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD`| `max(3, poolSize)`        | Per-slot consecutive deaths before the pool's circuit breaker trips. After tripping, every subsequent dispatch rejects until a fresh pool is created.       | Hosts where a SIGSEGV-prone native grammar should trip the breaker sooner; CI runners that should fail loudly.                              |
+| `GITNEXUS_CHUNK_BYTE_BUDGET`           | `2097152` (2 MB)          | Chunk boundary used for cache-key composition and dispatch. Smaller = finer-grained cache hits but more dispatch overhead.                                 | Tuning incremental-analyze cache behavior on monorepos.                                                                                     |
+| `GITNEXUS_NO_GITIGNORE`                | unset                     | When set, skips `.gitignore` parsing. `.gitnexusignore` is still honored.                                                                                  | Indexing a repo whose `.gitignore` excludes files you actually want indexed (e.g., generated code committed for cross-repo lookup).         |
+| `GITNEXUS_SKIP_OPTIONAL_GRAMMARS`      | unset                     | When `=1` strictly, skips vendored grammar materialize/build for `tree-sitter-dart`, `tree-sitter-proto`, and `tree-sitter-swift` at install time.        | Installing on a host without a C++ toolchain or where Swift prebuilds don't match; you're willing to skip Dart/Proto/Swift parsing.         |
+
 #### Publishing to understand-quickly (opt-in)
 
 [`looptech-ai/understand-quickly`](https://github.com/looptech-ai/understand-quickly) is a public registry of code-knowledge graphs that lists `gitnexus@1` as a first-class format. After registering your repo once (`npx @understand-quickly/cli add` or the [wizard](https://looptech-ai.github.io/understand-quickly/add.html)), `gitnexus publish` fires a single `repository_dispatch` event so the registry resyncs your entry on demand instead of waiting for the nightly job.
@@ -239,27 +261,27 @@ It is opt-in and a no-op without `UNDERSTAND_QUICKLY_TOKEN` — a fine-grained G
 
 **16 tools** exposed via MCP (11 per-repo + 5 group):
 
-| Tool               | What It Does                                                      | `repo` Param |
-| ------------------ | ----------------------------------------------------------------- | -------------- |
-| `list_repos`     | Discover all indexed repositories                                 | —             |
-| `query`          | Process-grouped hybrid search (BM25 + semantic + RRF)             | Optional       |
-| `context`        | 360-degree symbol view — categorized refs, process participation | Optional       |
-| `impact`         | Blast radius analysis with depth grouping and confidence          | Optional       |
-| `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                               | —             |
+| Tool              | What It Does                                                     | `repo` Param |
+| ----------------- | ---------------------------------------------------------------- | ------------ |
+| `list_repos`      | Discover all indexed repositories                                | —            |
+| `query`           | Process-grouped hybrid search (BM25 + semantic + RRF)            | Optional     |
+| `context`         | 360-degree symbol view — categorized refs, process participation | Optional     |
+| `impact`          | Blast radius analysis with depth grouping and confidence         | Optional     |
+| `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"})`.
 
 **Resources** for instant context:
 
-| Resource                                  | Purpose                                              |
-| ----------------------------------------- | ---------------------------------------------------- |
+| Resource                                | Purpose                                              |
+| --------------------------------------- | ---------------------------------------------------- |
 | `gitnexus://repos`                      | List all indexed repositories (read this first)      |
 | `gitnexus://repo/{name}/context`        | Codebase stats, staleness check, and available tools |
 | `gitnexus://repo/{name}/clusters`       | All functional clusters with cohesion scores         |
@@ -270,9 +292,9 @@ It is opt-in and a no-op without `UNDERSTAND_QUICKLY_TOKEN` — a fine-grained G
 
 **2 MCP prompts** for guided workflows:
 
-| Prompt            | What It Does                                                              |
-| ----------------- | ------------------------------------------------------------------------- |
-| `detect_impact` | Pre-commit change analysis — scope, affected processes, risk level       |
+| Prompt          | What It Does                                                              |
+| --------------- | ------------------------------------------------------------------------- |
+| `detect_impact` | Pre-commit change analysis — scope, affected processes, risk level        |
 | `generate_map`  | Architecture documentation from the knowledge graph with mermaid diagrams |
 
 **4 agent skills** installed to `.claude/skills/` automatically:
@@ -359,10 +381,10 @@ npx gitnexus@latest serve
 
 The official Docker setup ships **two signed images** orchestrated by `docker-compose.yaml`. Each image is published to both **GitHub Container Registry** (GHCR) and **Docker Hub** — same build, same digest, same Cosign signature — so pick whichever registry you prefer:
 
-| Purpose                                                                | GHCR (default in `docker-compose.yaml`)       | Docker Hub mirror                           |
-| ---------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------- |
-| CLI / `gitnexus serve` backend (HTTP API on port `4747`, MCP, indexer) | `ghcr.io/abhigyanpatwari/gitnexus:latest`     | `akonlabs/gitnexus:latest`                  |
-| Static web UI (port `4173`)                                            | `ghcr.io/abhigyanpatwari/gitnexus-web:latest` | `akonlabs/gitnexus-web:latest`              |
+| Purpose                                                                | GHCR (default in `docker-compose.yaml`)       | Docker Hub mirror              |
+| ---------------------------------------------------------------------- | --------------------------------------------- | ------------------------------ |
+| CLI / `gitnexus serve` backend (HTTP API on port `4747`, MCP, indexer) | `ghcr.io/abhigyanpatwari/gitnexus:latest`     | `akonlabs/gitnexus:latest`     |
+| Static web UI (port `4173`)                                            | `ghcr.io/abhigyanpatwari/gitnexus-web:latest` | `akonlabs/gitnexus-web:latest` |
 
 > **Heads-up — image rename.** Earlier releases published the web UI under
 > `ghcr.io/abhigyanpatwari/gitnexus`. Starting with the introduction of the
@@ -429,7 +451,7 @@ The Docker images are version-locked to the npm package:
   Both registries receive the same digest from a single build step, so you can
   pull from either and the signature verifies identically.
 - Release-candidate images (e.g. `:1.7.0-rc.1`) are published alongside each
-  RC npm release. They are built by `release-candidate.yml` calling `docker.yml`
+  RC npm release. They are built by `publish.yml` calling `docker.yml`
   as a reusable workflow after the RC tag is created and pushed.
 - `:latest` is auto-promoted only from non-prerelease tags by the Docker
   metadata action, so it always points at a real, npm-published version.
@@ -462,7 +484,7 @@ registries because both sets of tags were signed at the same digest in one
 workflow run.
 
 **Release candidates** — signed from `refs/heads/main` (the caller's ref when
-`release-candidate.yml` invokes `docker.yml` as a reusable workflow):
+`publish.yml` invokes `docker.yml` as a reusable workflow):
 
 ```bash
 cosign verify ghcr.io/abhigyanpatwari/gitnexus:1.7.0-rc.1 \
@@ -578,22 +600,22 @@ GitNexus builds a complete knowledge graph of your codebase through a multi-phas
 
 ### Supported Languages
 
-| Language | Imports | Named Bindings | Exports | Heritage | Type Annotations | Constructor Inference | Config | Frameworks | Entry Points |
-|----------|---------|----------------|---------|----------|-----------------|---------------------|--------|------------|-------------|
-| TypeScript | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-| JavaScript | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ | ✓ | ✓ |
-| Python | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-| Java | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ |
-| Kotlin | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ |
-| C# | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-| Go | ✓ | — | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-| Rust | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ |
-| PHP | ✓ | ✓ | ✓ | — | ✓ | ✓ | ✓ | ✓ | ✓ |
-| Ruby | ✓ | — | ✓ | ✓ | — | ✓ | — | ✓ | ✓ |
-| Swift | — | — | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-| C | — | — | ✓ | — | ✓ | ✓ | — | ✓ | ✓ |
-| C++ | — | — | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ |
-| Dart | ✓ | — | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ |
+| Language   | Imports | Named Bindings | Exports | Heritage | Type Annotations | Constructor Inference | Config | Frameworks | Entry Points |
+| ---------- | ------- | -------------- | ------- | -------- | ---------------- | --------------------- | ------ | ---------- | ------------ |
+| TypeScript | ✓       | ✓              | ✓       | ✓        | ✓                | ✓                     | ✓      | ✓          | ✓            |
+| JavaScript | ✓       | ✓              | ✓       | ✓        | —                | ✓                     | ✓      | ✓          | ✓            |
+| Python     | ✓       | ✓              | ✓       | ✓        | ✓                | ✓                     | ✓      | ✓          | ✓            |
+| Java       | ✓       | ✓              | ✓       | ✓        | ✓                | ✓                     | —      | ✓          | ✓            |
+| Kotlin     | ✓       | ✓              | ✓       | ✓        | ✓                | ✓                     | —      | ✓          | ✓            |
+| C#         | ✓       | ✓              | ✓       | ✓        | ✓                | ✓                     | ✓      | ✓          | ✓            |
+| Go         | ✓       | —              | ✓       | ✓        | ✓                | ✓                     | ✓      | ✓          | ✓            |
+| Rust       | ✓       | ✓              | ✓       | ✓        | ✓                | ✓                     | —      | ✓          | ✓            |
+| PHP        | ✓       | ✓              | ✓       | —        | ✓                | ✓                     | ✓      | ✓          | ✓            |
+| Ruby       | ✓       | —              | ✓       | ✓        | —                | ✓                     | —      | ✓          | ✓            |
+| Swift      | —       | —              | ✓       | ✓        | ✓                | ✓                     | ✓      | ✓          | ✓            |
+| C          | —       | —              | ✓       | —        | ✓                | ✓                     | —      | ✓          | ✓            |
+| C++        | —       | —              | ✓       | ✓        | ✓                | ✓                     | —      | ✓          | ✓            |
+| Dart       | ✓       | —              | ✓       | ✓        | ✓                | ✓                     | —      | ✓          | ✓            |
 
 **Imports** — cross-file import resolution · **Named Bindings** — `import { X as Y }` / re-export tracking · **Exports** — public/exported symbol detection · **Heritage** — class inheritance, interfaces, mixins · **Type Annotations** — explicit type extraction for receiver resolution · **Constructor Inference** — infer receiver type from constructor calls (`self`/`this` resolution included for all languages) · **Config** — language toolchain config parsing (tsconfig, go.mod, etc.) · **Frameworks** — AST-based framework pattern detection · **Entry Points** — entry point scoring heuristics
 
@@ -722,6 +744,14 @@ gitnexus wiki --base-url https://api.anthropic.com/v1
 
 # Force full regeneration
 gitnexus wiki --force
+
+
+# Increase the timeout or retries for large codebase or slow LLM providers
+gitnexus wiki --timeout <seconds> # LLM request timeout in seconds (default: disabled)
+gitnexus wiki --retries <n>      # Max LLM retry attempts per request (default: 3)
+
+# Change the language generation for wiki
+gitnexus wiki --lang <lang>  # Output language for generated documentation (e.g. english, chinese, spanish, japanese)
 ```
 
 The wiki generator reads the indexed graph structure, groups files into modules via LLM, generates per-module documentation pages, and creates an overview page — all with cross-references to the knowledge graph.
@@ -730,16 +760,16 @@ The wiki generator reads the indexed graph structure, groups files into modules
 
 ## Tech Stack
 
-| Layer                     | CLI                                   | Web                                     |
-| ------------------------- | ------------------------------------- | --------------------------------------- |
+| Layer               | CLI                                   | Web                                     |
+| ------------------- | ------------------------------------- | --------------------------------------- |
 | **Runtime**         | Node.js (native)                      | Browser (WASM)                          |
 | **Parsing**         | Tree-sitter native bindings           | Tree-sitter WASM                        |
-| **Database**        | LadybugDB native                         | LadybugDB WASM                             |
+| **Database**        | LadybugDB native                      | LadybugDB WASM                          |
 | **Embeddings**      | HuggingFace transformers.js (GPU/CPU) | transformers.js (WebGPU/WASM)           |
 | **Search**          | BM25 + semantic + RRF                 | BM25 + semantic + RRF                   |
 | **Agent Interface** | MCP (stdio)                           | LangChain ReAct agent                   |
-| **Visualization**   | —                                    | Sigma.js + Graphology (WebGL)           |
-| **Frontend**        | —                                    | React 18, TypeScript, Vite, Tailwind v4 |
+| **Visualization**   | —                                     | Sigma.js + Graphology (WebGL)           |
+| **Frontend**        | —                                     | React 18, TypeScript, Vite, Tailwind v4 |
 | **Clustering**      | Graphology                            | Graphology                              |
 | **Concurrency**     | Worker threads + async                | Web Workers + Comlink                   |
 
@@ -755,12 +785,12 @@ The wiki generator reads the indexed graph structure, groups files into modules
 
 ### Recently Completed
 
-- [X] Constructor-Inferred Type Resolution, `self`/`this` Receiver Mapping
-- [X] Wiki Generation, Multi-File Rename, Git-Diff Impact Analysis
-- [X] Process-Grouped Search, 360-Degree Context, Claude Code Hooks
-- [X] Multi-Repo MCP, Zero-Config Setup, 14 Language Support
-- [X] Community Detection, Process Detection, Confidence Scoring
-- [X] Hybrid Search, Vector Index
+- [x] Constructor-Inferred Type Resolution, `self`/`this` Receiver Mapping
+- [x] Wiki Generation, Multi-File Rename, Git-Diff Impact Analysis
+- [x] Process-Grouped Search, 360-Degree Context, Claude Code Hooks
+- [x] Multi-Repo MCP, Zero-Config Setup, 14 Language Support
+- [x] Community Detection, Process Detection, Confidence Scoring
+- [x] Hybrid Search, Vector Index
 
 ---
 

TESTING.md

@@ -10,32 +10,37 @@ How we structure tests and which commands to run locally and in CI.
 | Web UI         | `gitnexus-web/`| Vitest   | Unit/component tests           |
 | Web UI E2E     | `gitnexus-web/`| Playwright | Run when changing UI flows   |
 
-## Commands (local)
+## Test lanes
 
-From repository root, unless noted:
+### `gitnexus/` commands
 
-**`gitnexus` (CLI / library)**
+From `gitnexus/`:
+
+| Command                  | What it runs                                         | When to use                     |
+| ------------------------ | ---------------------------------------------------- | ------------------------------- |
+| `npm test`               | Full suite (all 3 vitest projects)                   | Before opening a PR             |
+| `npm run test:unit`      | Unit tests only (`test/unit/`)                       | Tight development loop          |
+| `npm run test:integration` | Integration tests (`test/integration/`)            | After changing pipelines, DB, workers |
+| `npm run test:coverage`  | Full suite + v8 coverage with thresholds             | Checking coverage impact        |
+| `npm run test:parity`    | Scope-resolution parity for all migrated languages   | After changing resolver or scope code |
+| `npm run test:cross-platform` | Platform-sensitive subset only                  | Debugging a Windows/macOS issue |
+| `npm run test:watch`     | Vitest in watch mode                                 | Active development              |
+
+### `gitnexus-web/` commands
+
+From `gitnexus-web/`:
+
+| Command               | What it runs                      | When to use                    |
+| ---------------------- | --------------------------------- | ------------------------------ |
+| `npm test`             | Unit/component tests (vitest)     | After changing web code        |
+| `npm run test:coverage`| Unit tests + coverage             | Checking coverage impact       |
+| `npm run test:e2e`     | Playwright browser tests          | After changing UI flows (requires `gitnexus serve` + `npm run dev`) |
+
+### Before opening a PR
 
 ```bash
-cd gitnexus
-npm install
-npm run build
-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:coverage
-npx tsc --noEmit            # typecheck (matches CI)
-```
-
-**`gitnexus-web`**
-
-```bash
-cd gitnexus-web
-npm install
-npm test                    # unit tests (vitest)
-npx tsc -b --noEmit         # typecheck (matches CI)
-npm run test:coverage
-npm run test:e2e            # Playwright (requires gitnexus serve + npm run dev)
+cd gitnexus && npx tsc --noEmit && npm test
+cd ../gitnexus-web && npx tsc -b --noEmit && npm test
 ```
 
 ## Pre-commit hook
@@ -50,22 +55,79 @@ Tests do **not** run in the pre-commit hook — they run in CI (`ci-tests.yml`)
 
 Skip with `git commit --no-verify` (use sparingly).
 
+## Vitest projects
+
+`gitnexus/vitest.config.ts` defines three projects for safety isolation:
+
+| Project    | Files                         | Parallelism | Purpose                                       |
+| ---------- | ----------------------------- | ----------- | ---------------------------------------------- |
+| `lbug-db`  | Native LadybugDB integration tests (explicit list) | Sequential  | Prevents file-lock conflicts from native mmap addon |
+| `cli-e2e`  | `skills-e2e.test.ts`          | Sequential  | CLI process spawning requires serial execution |
+| `default`  | Everything else               | Parallel    | Fast execution for pure logic and parser tests |
+
+When adding a new test that uses native LadybugDB (`@ladybugdb/core`), add it to the `lbug-db` project's explicit include list and the `default` project's exclude list.
+
 ## Test categories
 
 - **Unit** — Pure logic, parsers, graph/query helpers; fast; no network.
 - **Integration** — Real combinations (filesystem, MCP wiring, larger pipelines) as already organized under `gitnexus/test/integration`.
-- **Eval-style / golden sets** — For agent- or classification-style behavior, keep labeled inputs and expected outputs (JSON or table-driven tests) and run them in CI when relevant.
+- **Resolver / parity** — Language-specific call-resolution tests in `test/integration/resolvers/`.
 - **E2E (web)** — Critical user paths only; prefer `data-testid` attributes for stable selectors. Tests run against real backend (`gitnexus serve`) and Vite dev server.
 
-## Performance metrics (targets)
+## Scope-resolution parity
 
-Set targets to match team expectations, then tune to this repo’s CI reality:
+Migrated languages (listed in `MIGRATED_LANGUAGES` in `src/core/ingestion/registry-primary-flag.ts`) are tested in both legacy and registry-primary modes on every PR.
 
-| Metric              | Target (initial) | Notes                                      |
-| ------------------- | ---------------- | ------------------------------------------ |
-| Unit coverage       | Align with CI    | CI runs Vitest with coverage in `gitnexus` |
-| Unit wall time      | Fast PR feedback | Use `vitest run test/unit` for tight loop  |
-| Integration duration| < few minutes | Guard heavy tests with env flags if needed |
+For each migrated language, CI runs the resolver test file twice:
+1. `REGISTRY_PRIMARY_<LANG>=0` — legacy DAG path
+2. `REGISTRY_PRIMARY_<LANG>=1` — registry-primary path
+
+Both must pass. Known legacy gaps are listed in `LEGACY_RESOLVER_PARITY_EXPECTED_FAILURES` in `test/integration/resolvers/helpers.ts` and are automatically skipped in legacy mode.
+
+Adding a language to `MIGRATED_LANGUAGES` automatically enrolls it in parity — no workflow or config edit needed. The test file must exist at `test/integration/resolvers/<slug>.test.ts`.
+
+Run parity locally: `cd gitnexus && npm run test:parity`
+
+Run for a single language: `cd gitnexus && npx tsx scripts/run-parity.ts --language python`
+
+## Cross-platform testing
+
+Windows and macOS CI runs only the platform-sensitive test subset (~50 files out of 373). The full suite runs on Ubuntu.
+
+The subset is defined in `gitnexus/scripts/cross-platform-tests.ts` and includes:
+
+- **Platform-specific logic** — tests with `process.platform` guards, path.sep behavior, EPERM/EBUSY error classification
+- **Native LadybugDB** — all `lbug-*` integration tests (N-API addon with known platform-varying behavior)
+- **Process spawning / CLI** — tests using real `child_process.spawn`, shell quoting, CLI invocations
+- **Worker threads** — tests spawning real `worker_threads`
+- **Native addon loading** — tree-sitter grammar loading smoke tests
+- **Filesystem behavior** — CRLF handling, directory walking, symlinks
+
+When adding a platform-sensitive test, add it to the appropriate section in `scripts/cross-platform-tests.ts`.
+
+### Confirming no tests are orphaned
+
+Every test file matches one of the three vitest projects. To verify:
+
+```bash
+cd gitnexus
+npx vitest list 2>/dev/null | wc -l  # should match total test count
+```
+
+To check the cross-platform list is up to date, run `npm run test:cross-platform` — it fails fast if any listed file is missing.
+
+## CI integration
+
+GitHub Actions (`.github/workflows/ci.yml`) orchestrate:
+
+| Workflow              | Jobs                           | Purpose                                         |
+| --------------------- | ------------------------------ | ------------------------------------------------ |
+| `ci-quality.yml`      | format, lint, typecheck, typecheck-web, workflow-convention | Code quality gates |
+| `ci-tests.yml`        | ubuntu/coverage, cross-platform (Win/Mac), packaged-install-smoke | Full suite + coverage on Ubuntu; platform-sensitive subset on Win/Mac |
+| `ci-scope-parity.yml` | discover, parity               | Scope-resolution parity for all migrated languages |
+| `ci-e2e.yml`          | e2e (chromium)                 | Playwright E2E, gated on `gitnexus-web/**` changes |
+
+The `CI Gate` job in `ci.yml` is the single required check for branch protection. It requires quality, tests, e2e, and scope-parity to all pass.
 
 ## Regression testing
 
@@ -76,23 +138,6 @@ Re-run the full relevant suite when:
 - Graph schema, query contracts, or MCP tool shapes change
 - Dependencies with parsing or runtime impact upgrade
 
-## CI integration
-
-GitHub Actions (`.github/workflows/ci.yml`) orchestrate:
-
-- **`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
-
-Local checks before pushing:
-
-```bash
-cd gitnexus && npx tsc --noEmit && npm test
-cd ../gitnexus-web && npx tsc -b --noEmit && npm test
-```
-
-Or rely on the pre-commit hook which runs these automatically for staged files.
-
 ## User acceptance / beta (optional)
 
 For staged releases or UI betas: deploy to a staging environment, collect structured feedback, watch errors and latency, then iterate before a wider release.

docker-compose.yaml

@@ -30,6 +30,19 @@ services:
     container_name: ${WEB_CONTAINER_NAME:-gitnexus-web}
     ports:
       - '${WEB_HOST_PORT:-4173}:4173'
+    # Optional: override the backend URL served to the browser.
+    # Required when the gitnexus-server is not reachable at http://localhost:4747
+    # from the user's browser (e.g. remote server deployments).
+    #
+    # Docker Desktop (Mac/Windows):
+    #   GITNEXUS_BACKEND_URL=http://host.docker.internal:4747
+    #
+    # Linux / remote server:
+    #   GITNEXUS_BACKEND_URL=http://<server-ip>:4747
+    #   (host.docker.internal requires extra_hosts on Linux Docker Engine)
+    #
+    # environment:
+    #   - GITNEXUS_BACKEND_URL=http://host.docker.internal:4747
     depends_on:
       gitnexus-server:
         condition: service_healthy

docker-server.mjs

@@ -1,12 +1,39 @@
-import { createReadStream } from 'node:fs';
-import { stat } from 'node:fs/promises';
+import { open, stat } from 'node:fs/promises';
 import { createServer } from 'node:http';
-import { extname, isAbsolute, normalize, relative, resolve } from 'node:path';
+import { extname, isAbsolute, normalize, relative, resolve, sep } from 'node:path';
 
 const host = '0.0.0.0';
 const port = Number(process.env.PORT || '4173');
 const root = resolve(process.cwd(), 'dist');
 
+function isValidUrl(value) {
+  try {
+    const u = new URL(value);
+    return u.protocol === 'http:' || u.protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
+function jsonForScriptTag(obj) {
+  return JSON.stringify(obj)
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(/&/g, '\\u0026');
+}
+
+const rawBackendUrl = process.env.GITNEXUS_BACKEND_URL ?? null;
+if (rawBackendUrl && !isValidUrl(rawBackendUrl)) {
+  const safeRaw = rawBackendUrl.replace(/[\x00-\x1f\x7f]/g, ' ').slice(0, 200);
+  console.warn(
+    `[gitnexus-web] GITNEXUS_BACKEND_URL "${safeRaw}" is not a valid http/https URL -- ignoring.`,
+  );
+}
+const backendUrl = rawBackendUrl && isValidUrl(rawBackendUrl) ? rawBackendUrl : null;
+const configScript = backendUrl
+  ? `<script>window.__GITNEXUS_CONFIG__=${jsonForScriptTag({ backendUrl })};</script>`
+  : '';
+
 const contentTypes = {
   '.css': 'text/css; charset=utf-8',
   '.html': 'text/html; charset=utf-8',
@@ -22,22 +49,14 @@ const contentTypes = {
 
 // Static asset server for the gitnexus-web Docker image.
 //
-// Path-injection containment: the request handler is intentionally a single
-// inline pipeline with no helper functions on the path-data flow. Each
-// filesystem sink (stat, createReadStream) is immediately preceded by the
-// canonical `path.relative` containment check that CodeQL's
-// `js/path-injection` query recognizes as a sanitizer barrier:
+// Path-injection containment: each filesystem sink is preceded by the
+// canonical `path.relative` containment check that CodeQL recognizes as
+// a sanitizer barrier.
 //
-//     const rel = relative(root, candidate);
-//     if (rel.startsWith('..') || isAbsolute(rel)) reject;
-//     // candidate is now proven inside `root`
-//
-// Earlier iterations of this file used a helper (`resolveWithinRoot`) and a
-// `startsWith(root + sep)` check. Both were semantically correct but neither
-// was recognized by CodeQL: `startsWith(root + sep)` is not in the analyzer's
-// barrier-pattern set, and helper-based sanitization is not followed across
-// the request handler's reassignment paths in vanilla JS. The inline-at-sink
-// shape below is the documented analyzer-friendly idiom.
+// TOCTOU prevention: after the path barrier, the file is opened once via
+// fs.promises.open() and all subsequent operations (stat, readFile,
+// createReadStream) use the file handle, eliminating any race between
+// the existence check and the read.
 const server = createServer(async (req, res) => {
   const urlPath = req.url?.split('?')[0] || '/';
 
@@ -66,6 +85,7 @@ const server = createServer(async (req, res) => {
     return;
   }
 
+  let handle;
   try {
     const initialStat = await stat(initialPath).catch(() => null);
 
@@ -80,10 +100,9 @@ const server = createServer(async (req, res) => {
       finalPath = initialPath;
     }
 
-    // Sanitizer barrier #2 — guards both the second stat() and the
-    // createReadStream() sinks. No reassignment of finalPath happens
-    // between this guard and either sink, so the analyzer can prove
-    // containment for both.
+    // Sanitizer barrier #2 — guards the open() sink below. No
+    // reassignment of finalPath happens between this guard and the
+    // open(), so the analyzer can prove containment.
     const finalRel = relative(root, finalPath);
     if (finalRel.startsWith('..') || isAbsolute(finalRel)) {
       res.writeHead(400);
@@ -91,27 +110,60 @@ const server = createServer(async (req, res) => {
       return;
     }
 
-    const finalStat = await stat(finalPath).catch(() => null);
-    if (!finalStat?.isFile()) {
+    handle = await open(finalPath, 'r').catch(() => null);
+    if (!handle) {
+      res.writeHead(404);
+      res.end('Not found');
+      return;
+    }
+    const finalStat = await handle.stat();
+    if (!finalStat.isFile()) {
       res.writeHead(404);
       res.end('Not found');
       return;
     }
 
-    res.writeHead(200, {
-      'Cache-Control': finalPath.includes('/assets/')
-        ? 'public, max-age=31536000, immutable'
-        : 'no-cache',
-      'Content-Type': contentTypes[extname(finalPath)] || 'application/octet-stream',
-      'Cross-Origin-Opener-Policy': 'same-origin',
-      'Cross-Origin-Embedder-Policy': 'require-corp',
-    });
-    const stream = createReadStream(finalPath);
-    stream.on('error', () => res.destroy());
-    stream.pipe(res);
+    const isHtml = extname(finalPath) === '.html' || !extname(finalPath);
+    const cacheControl = finalPath.includes(`${sep}assets${sep}`)
+      ? 'public, max-age=31536000, immutable'
+      : 'no-cache';
+    const contentType = contentTypes[extname(finalPath)] || 'application/octet-stream';
+
+    if (isHtml && configScript) {
+      const raw = await handle.readFile('utf8');
+      await handle.close();
+      handle = null;
+      if (!raw.includes('</head>')) {
+        console.warn('[gitnexus-web] Could not inject config: no </head> tag found in HTML');
+      }
+      const html = raw.includes('</head>') ? raw.replace('</head>', `${configScript}</head>`) : raw;
+      const buf = Buffer.from(html, 'utf8');
+      res.writeHead(200, {
+        'Cache-Control': cacheControl,
+        'Content-Type': 'text/html; charset=utf-8',
+        'Content-Length': buf.length,
+        'Cross-Origin-Opener-Policy': 'same-origin',
+        'Cross-Origin-Embedder-Policy': 'require-corp',
+      });
+      res.end(buf);
+    } else {
+      res.writeHead(200, {
+        'Cache-Control': cacheControl,
+        'Content-Type': contentType,
+        'Cross-Origin-Opener-Policy': 'same-origin',
+        'Cross-Origin-Embedder-Policy': 'require-corp',
+      });
+      const stream = handle.createReadStream();
+      handle = null;
+      stream.on('error', () => res.destroy());
+      stream.pipe(res);
+    }
   } catch (error) {
+    console.error(error);
     res.writeHead(500);
-    res.end(error instanceof Error ? error.message : 'Internal server error');
+    res.end('Internal server error');
+  } finally {
+    if (handle) await handle.close().catch(() => {});
   }
 });
 

docker-server.test.mjs

@@ -70,8 +70,20 @@ before(async () => {
   await waitForServer(serverPort);
 });
 
+function killAndWait(proc) {
+  return new Promise((resolve) => {
+    if (!proc || proc.exitCode !== null) {
+      resolve();
+      return;
+    }
+    proc.once('exit', resolve);
+    proc.kill();
+    if (proc.exitCode !== null) resolve();
+  });
+}
+
 after(async () => {
-  child?.kill();
+  await killAndWait(child);
   if (tmpDir) await rm(tmpDir, { recursive: true, force: true });
 });
 
@@ -122,3 +134,132 @@ it('returns 404 when dist/index.html is missing', async () => {
   const res = await rawGet(serverPort, '/nonexistent-page');
   assert.equal(res.status, 404);
 });
+
+// -- Config injection: server-level integration tests ---
+
+function spawnServerWithEnv(cwd, port, env) {
+  const proc = spawn(process.execPath, [serverScript], {
+    cwd,
+    env: { ...process.env, PORT: String(port), ...env },
+    stdio: 'pipe',
+  });
+  proc.on('error', (err) => {
+    throw err;
+  });
+  return proc;
+}
+
+async function withInjectionServer(envOverrides, fn) {
+  const dir = await mkdtemp(join(tmpdir(), 'gitnexus-inject-'));
+  const distDir = join(dir, 'dist');
+  const assetsDir = join(distDir, 'assets');
+  await mkdir(assetsDir, { recursive: true });
+  await writeFile(
+    join(distDir, 'index.html'),
+    '<!doctype html><html><head><meta charset="utf-8"></head><body>app</body></html>',
+  );
+  await writeFile(join(assetsDir, 'style.abc.css'), 'body{}');
+
+  const port = await getFreePort();
+  const proc = spawnServerWithEnv(dir, port, envOverrides);
+  try {
+    await waitForServer(port);
+    await fn(port);
+  } finally {
+    await killAndWait(proc);
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+it('injects __GITNEXUS_CONFIG__ into / when GITNEXUS_BACKEND_URL is valid', async () => {
+  await withInjectionServer({ GITNEXUS_BACKEND_URL: 'http://10.0.0.1:4747' }, async (port) => {
+    const res = await rawGet(port, '/');
+    assert.equal(res.status, 200);
+    assert.ok(
+      res.body.includes('window.__GITNEXUS_CONFIG__'),
+      'Expected __GITNEXUS_CONFIG__ in response body',
+    );
+    assert.ok(res.body.includes('http://10.0.0.1:4747'), 'Expected backend URL in response body');
+  });
+});
+
+it('injects __GITNEXUS_CONFIG__ into SPA fallback routes', async () => {
+  await withInjectionServer({ GITNEXUS_BACKEND_URL: 'http://10.0.0.1:4747' }, async (port) => {
+    const res = await rawGet(port, '/some/deep/link');
+    assert.equal(res.status, 200);
+    assert.ok(
+      res.body.includes('window.__GITNEXUS_CONFIG__'),
+      'Expected __GITNEXUS_CONFIG__ in SPA fallback response',
+    );
+    assert.ok(
+      res.body.includes('http://10.0.0.1:4747'),
+      'Expected backend URL in SPA fallback response',
+    );
+  });
+});
+
+it('does not inject when GITNEXUS_BACKEND_URL is not set', async () => {
+  await withInjectionServer({}, async (port) => {
+    const res = await rawGet(port, '/');
+    assert.equal(res.status, 200);
+    assert.ok(
+      !res.body.includes('__GITNEXUS_CONFIG__'),
+      'Expected no __GITNEXUS_CONFIG__ when env var is unset',
+    );
+  });
+});
+
+it('does not inject when GITNEXUS_BACKEND_URL is invalid', async () => {
+  await withInjectionServer({ GITNEXUS_BACKEND_URL: 'not-a-url' }, async (port) => {
+    const res = await rawGet(port, '/');
+    assert.equal(res.status, 200);
+    assert.ok(
+      !res.body.includes('__GITNEXUS_CONFIG__'),
+      'Expected no __GITNEXUS_CONFIG__ for invalid URL',
+    );
+  });
+});
+
+it('does not inject when GITNEXUS_BACKEND_URL uses a non-http protocol', async () => {
+  await withInjectionServer({ GITNEXUS_BACKEND_URL: 'ftp://somehost:21' }, async (port) => {
+    const res = await rawGet(port, '/');
+    assert.equal(res.status, 200);
+    assert.ok(
+      !res.body.includes('__GITNEXUS_CONFIG__'),
+      'Expected no __GITNEXUS_CONFIG__ for non-http protocol',
+    );
+  });
+});
+
+it('escapes </script> in GITNEXUS_BACKEND_URL to prevent XSS', async () => {
+  const xssUrl = 'http://example.com/?x=</script><script>alert(1)</script>';
+  await withInjectionServer({ GITNEXUS_BACKEND_URL: xssUrl }, async (port) => {
+    const res = await rawGet(port, '/');
+    assert.equal(res.status, 200);
+
+    const scriptMatches = res.body.match(/<script>/gi) || [];
+    assert.equal(
+      scriptMatches.length,
+      1,
+      `Expected exactly 1 <script> tag but found ${scriptMatches.length}: XSS breakout detected`,
+    );
+
+    assert.ok(
+      !res.body.includes('</script><script>'),
+      '</script> must not appear unescaped -- would allow script breakout',
+    );
+    assert.ok(res.body.includes('\\u003c'), 'Angle brackets must be escaped as \\u003c');
+  });
+});
+
+it('does not inject config into static assets', async () => {
+  await withInjectionServer({ GITNEXUS_BACKEND_URL: 'http://10.0.0.1:4747' }, async (port) => {
+    const res = await rawGet(port, '/assets/style.abc.css');
+    assert.equal(res.status, 200);
+    assert.ok(
+      !res.body.includes('__GITNEXUS_CONFIG__'),
+      'Static assets must not contain injected config',
+    );
+    assert.equal(res.body, 'body{}');
+  });
+});

docs/code-indexing/cobol/README.md

@@ -1,100 +0,0 @@
-# COBOL Code Indexing
-
-GitNexus indexes COBOL codebases using a **regex-only extraction** strategy, bypassing tree-sitter entirely. This document explains why, how the pipeline works, and links to detailed sub-documents.
-
-## Why Regex-Only?
-
-The tree-sitter-cobol grammar (v0.0.1) has three critical limitations that make it unusable for production indexing:
-
-| Issue | Impact | Severity |
-|-------|--------|----------|
-| External scanner hangs on ~5% of files | No timeout mechanism exists for the C scanner; the process blocks indefinitely | **Blocking** |
-| Only ~15% of paragraph headers detected | Most procedure-division paragraphs are invisible to the grammar | High |
-| Patch markers in cols 1-6 cause parse errors | Enterprise COBOL uses non-standard sequence area content (e.g., `mzADD`, `estero`, `#FIX`) | High |
-
-Because the external scanner hang cannot be interrupted (there is no `setTimeoutMicros` equivalent for tree-sitter), using tree-sitter-cobol would hang the indexing pipeline on a non-trivial fraction of real-world files.
-
-The regex-only approach provides:
-
-- **Speed**: ~1ms per file average extraction time
-- **Reliability**: zero hangs, zero crashes across 13,000+ files
-- **Coverage**: captures all critical symbols -- program name, paragraphs, sections, CALL, PERFORM, COPY, data items (01-77, 88-level), file declarations, FD entries, EXEC SQL/CICS blocks, ENTRY points, and MOVE statements
-
-## Architecture
-
-```mermaid
-flowchart TD
-    A[Repository Scan] --> B{File Detection}
-    B -->|Extension match| C[COBOL file]
-    B -->|GITNEXUS_COBOL_DIRS match| C
-    B -->|No match| Z[Skip]
-
-    C --> D{Copybook?}
-    D -->|Yes| E[Add to Copybook Map]
-    D -->|No| F[Source Program]
-
-    E --> G[COPY Expansion Engine]
-    F --> G
-
-    G -->|Inline copybook content| H[Expanded Source]
-    H --> I[Patch Marker Cleanup]
-    I --> J[Regex State Machine]
-
-    J --> K[Extracted Symbols]
-    K --> L[Graph Model Builder]
-    L --> M[Knowledge Graph]
-
-    subgraph "Per-Chunk Processing"
-        G
-        H
-        I
-        J
-        K
-        L
-    end
-
-    subgraph "Post-Processing"
-        M --> N[Community Detection]
-        M --> O[Process Detection]
-        M --> P[Contract Detection]
-    end
-
-    style J fill:#e8f5e9,stroke:#2e7d32
-    style G fill:#e3f2fd,stroke:#1565c0
-```
-
-## COBOL vs Tree-Sitter Languages
-
-| Feature | COBOL (Regex) | Tree-Sitter Languages |
-|---------|--------------|----------------------|
-| Parser | Single-pass regex state machine | tree-sitter grammar + queries |
-| Speed | ~1ms/file | ~5ms/file |
-| AST available | No | Yes |
-| COPY expansion | Yes (pre-processing step) | N/A |
-| Deep indexing | Data items, SQL, CICS, FD, ENTRY | Type annotations, generics, etc. |
-| Call extraction | PERFORM (intra-file) + CALL (cross-program) | AST-based call site detection |
-| Import extraction | COPY statements | `import`/`require`/`use`/`#include` |
-| Coverage | All critical symbols | Language-dependent query coverage |
-| Failure mode | Never hangs | External scanner can hang (COBOL only) |
-
-## Sub-Documents
-
-| Document | Description |
-|----------|-------------|
-| [File Detection](./file-detection.md) | Extension mapping, `GITNEXUS_COBOL_DIRS`, copybook classification |
-| [COPY Expansion](./copy-expansion.md) | Copybook inlining, REPLACING transformations, cycle detection |
-| [Regex Extraction](./regex-extraction.md) | State machine, regex patterns, line processing |
-| [Deep Indexing](./deep-indexing.md) | Data items, EXEC SQL/CICS, file declarations, FD, ENTRY, MOVE |
-| [Graph Model](./graph-model.md) | COBOL-specific node types, edge types, full annotated example |
-| [Performance](./performance.md) | Benchmarks, worker pool tuning, caps, troubleshooting |
-
-## Key Source Files
-
-| File | Purpose |
-|------|---------|
-| `gitnexus/src/core/ingestion/cobol-preprocessor.ts` | Patch marker cleanup + regex extraction engine |
-| `gitnexus/src/core/ingestion/cobol-copy-expander.ts` | COPY statement expansion with REPLACING |
-| `gitnexus/src/core/ingestion/utils.ts` | `getLanguageFromPath`, `getLanguageFromFilename` |
-| `gitnexus/src/core/ingestion/pipeline.ts` | `isCobolCopybook`, `expandCobolCopies`, `detectCrossProgamContracts` |
-| `gitnexus/src/core/ingestion/workers/parse-worker.ts` | `processCobolRegexOnly` -- graph model builder |
-| `gitnexus/src/core/ingestion/workers/worker-pool.ts` | Configurable sub-batch size for COBOL |

docs/code-indexing/cobol/copy-expansion.md

@@ -1,157 +0,0 @@
-# COBOL COPY Expansion
-
-The COPY statement is COBOL's include mechanism -- analogous to `#include` in C or `import` in modern languages. GitNexus expands COPY statements **before** regex extraction so that symbols defined inside copybooks (data items, paragraphs, etc.) are visible in the program's extracted graph.
-
-## Supported Syntax
-
-### Basic COPY
-
-```cobol
-COPY CPSESP.
-COPY "WORKGRID.CPY".
-```
-
-Inlines the content of the named copybook, replacing the COPY line(s).
-
-### COPY with REPLACING
-
-```cobol
-COPY CPSESP REPLACING "ANAZI-KEY" BY "LK-KEY".
-COPY CPSESP REPLACING LEADING "ESP-" BY "LK-ESP-"
-                       LEADING "KPSESPL" BY "LK-KPSESPL".
-COPY LINKAGE REPLACING TRAILING "-IN" BY "-OUT".
-```
-
-Three REPLACING types are supported:
-
-| Type         | Syntax                               | Behavior                                | Example                          |
-| ------------ | ------------------------------------ | --------------------------------------- | -------------------------------- |
-| **EXACT**    | `REPLACING "OLD" BY "NEW"`           | Replace exact identifier matches        | `ANAZI-KEY` becomes `LK-KEY`     |
-| **LEADING**  | `REPLACING LEADING "PFX-" BY "NEW-"` | Replace prefix on all COBOL identifiers | `ESP-NAME` becomes `LK-ESP-NAME` |
-| **TRAILING** | `REPLACING TRAILING "-IN" BY "-OUT"` | Replace suffix on all COBOL identifiers | `DATA-IN` becomes `DATA-OUT`     |
-
-Multiple REPLACING clauses can appear in a single COPY statement. They are applied in order to each COBOL identifier in the copybook content.
-
-### Multi-Line COPY
-
-COPY statements can span multiple lines (standard COBOL continuation rules apply):
-
-```cobol
-       COPY CPSESP REPLACING
-      -    LEADING "ESP-" BY "LK-ESP-"
-      -    LEADING "KPSESPL" BY "LK-KPSESPL".
-```
-
-Continuation lines (indicator `-` in column 7) are merged before COPY statement scanning.
-
-## Expansion Flow
-
-```mermaid
-sequenceDiagram
-    participant Pipeline
-    participant Expander as COPY Expander
-    participant Resolver
-    participant Reader
-
-    Pipeline->>Pipeline: Identify all COBOL files
-    Pipeline->>Pipeline: Classify copybooks vs programs
-    Pipeline->>Reader: Read all copybook content upfront
-    Reader-->>Pipeline: Copybook content map (name -> content)
-
-    loop For each source file in chunk
-        Pipeline->>Expander: expandCopies(content, filePath, resolveFile, readFile)
-        Expander->>Expander: Merge continuation lines
-        Expander->>Expander: Detect COPY statements via regex
-
-        loop For each COPY statement (reverse order)
-            Expander->>Resolver: resolveFile(copyTarget)
-            Resolver-->>Expander: Copybook key or null
-
-            alt Resolved successfully
-                Expander->>Reader: readFile(resolvedKey)
-                Reader-->>Expander: Copybook content
-
-                Expander->>Expander: Apply REPLACING transformations
-                Expander->>Expander: Recurse for nested COPYs (depth + 1)
-                Expander->>Expander: Splice expanded content into output
-            else Not resolved
-                Expander->>Expander: Keep original COPY line
-            end
-        end
-
-        Expander-->>Pipeline: Expanded content + resolution metadata
-        Pipeline->>Pipeline: Replace file content with expanded content
-    end
-```
-
-The return type `CopyExpansionResult` contains `expandedContent` and `copyResolutions`. The `expansionDepth` field has been removed from the return type (it was unused by callers).
-
-COPY statement line numbers in `CopyResolution` are 1-based (consistent with the preprocessor's line numbering). The splice operation that replaces COPY lines with expanded content adjusts for 0-based array indexing internally.
-
-## Cycle Detection
-
-Circular COPY references (e.g., copybook A includes copybook B which includes copybook A) are detected and handled:
-
-1. Each expansion chain maintains a `visited` set of resolved copybook paths
-2. If a copybook path is already in the visited set, the expansion is skipped
-3. A `warnedCircular` set (internal to `expandCopies()`, not a parameter) deduplicates warning messages within a single file expansion
-
-Known circular copybooks in PROJECT-NAME: `ANAZI`, `ANDIP`, `QDIPE` (self-referential includes).
-
-## Max Depth
-
-Nested COPY expansion is limited to **10 levels** (`DEFAULT_MAX_DEPTH`). If a COPY chain exceeds this depth, a warning is logged and the remaining COPY statements are left unexpanded.
-
-## Max Total Expansions
-
-A breadth amplification guard caps the total number of COPY expansions across all branches within a single file to **500** (`MAX_TOTAL_EXPANSIONS`). This prevents exponential blowup from diamond-shaped COPY graphs where N copybooks each include N other copybooks. Once the limit is reached, further COPY statements in that file are left unexpanded and a single warning is logged.
-
-## REPLACING Application Detail
-
-The REPLACING engine works by scanning all COBOL identifiers (matching `\b[A-Z][A-Z0-9-]*\b`) in the copybook content and applying each replacement rule:
-
-```
-Original copybook content:
-       05  ESP-NAME          PIC X(30).
-       05  ESP-CODE          PIC X(10).
-       05  KPSESPL-FLAG      PIC X(01).
-
-After REPLACING LEADING "ESP-" BY "LK-ESP-" LEADING "KPSESPL" BY "LK-KPSESPL":
-       05  LK-ESP-NAME       PIC X(30).
-       05  LK-ESP-CODE       PIC X(10).
-       05  LK-KPSESPL-FLAG   PIC X(01).
-```
-
-For LEADING replacements, the engine checks if each identifier starts with the `from` prefix (case-insensitive) and replaces only the prefix portion, preserving the rest of the identifier.
-
-For TRAILING replacements, the same logic applies to suffixes.
-
-For EXACT replacements, only identifiers that match the `from` value exactly (case-insensitive) are replaced.
-
-## Copybook Resolution
-
-The resolver tries multiple strategies to match a COPY target name to a copybook file:
-
-1. **Exact match**: `COPY CPSESP` resolves to copybook named `CPSESP`
-2. **Strip extension**: `COPY WORKGRID.CPY` strips `.CPY` and resolves to `WORKGRID`
-3. **Add extension**: `COPY CPSESP` tries `CPSESP.CPY` and `CPSESP.COPY`
-
-If no match is found, the COPY statement is left in place (unexpanded) and a resolution record with `resolvedPath: null` is created.
-
-## Pipeline Integration
-
-The expansion runs **per chunk**, after file content is read but before dispatch to worker threads:
-
-1. All copybook files are read upfront (they are typically small, collectively under 100MB)
-2. Per chunk, the copybook map is merged with chunk content (in case a chunk contains copybooks)
-3. Only programs (not copybooks themselves) undergo expansion
-4. The expanded content replaces the original content in-place before worker dispatch
-
-## Inline Comment Handling
-
-The copy expander's `stripInlineComment()` helper is quote-aware: pipe characters (`|`) inside single- or double-quoted strings are preserved. This matches the same quote-aware logic used by the preprocessor.
-
-## Source Files
-
-- `gitnexus/src/core/ingestion/cobol-copy-expander.ts` -- `expandCopies()`, `parseReplacingClause()`, `applyReplacing()`
-- `gitnexus/src/core/ingestion/pipeline.ts` -- `expandCobolCopies()`, copybook map construction, chunk integration

docs/code-indexing/cobol/deep-indexing.md

@@ -1,312 +0,0 @@
-# COBOL Deep Indexing
-
-Beyond basic symbol extraction (program name, paragraphs, CALL, PERFORM, COPY), GitNexus performs deep indexing of COBOL-specific constructs: data items, EXEC SQL/CICS blocks, file declarations, FD entries, ENTRY points, and MOVE statements.
-
-## Data Items
-
-### Level Numbers
-
-| Level Range | Meaning | Graph Node Type |
-|-------------|---------|-----------------|
-| 01 | Record (group item) | `Record` |
-| 02-49 | Elementary/group items | `Property` |
-| 66 | RENAMES | `Property` |
-| 77 | Independent item | `Property` |
-| 88 | Condition name | `Const` |
-
-FILLER items are skipped (no useful name for the graph).
-
-### Clauses Parsed
-
-The `parseDataItemClauses()` function extracts these clauses from the trailing text of a data item declaration:
-
-| Clause | Pattern | Example |
-|--------|---------|---------|
-| `PIC` / `PICTURE` | `\bPIC(?:TURE)?\s+(?:IS\s+)?(\S+)` | `PIC X(30)`, `PICTURE IS 9(5)V99` |
-| `USAGE` | `\bUSAGE\s+(?:IS\s+)?(COMP\|BINARY\|...)` | `USAGE IS COMP-3`, `BINARY` |
-| `REDEFINES` | `\bREDEFINES\s+([A-Z][A-Z0-9-]+)` | `REDEFINES WK-DATE-NUM` |
-| `OCCURS` | `\bOCCURS\s+(\d+)` | `OCCURS 12 TIMES` |
-
-Standalone COMP variants (without the `USAGE` keyword) are also detected: `COMP`, `COMP-1` through `COMP-6`, `COMP-X`, `BINARY`, `PACKED-DECIMAL`.
-
-### Data Hierarchy
-
-Data items form a hierarchical structure based on level numbers. The extractor uses a **stack algorithm**:
-
-```
-Processing order:
-  01 WK-RECORD          -> push {01, WK-RECORD}   -> parent: Module
-  05 WK-NAME            -> push {05, WK-NAME}     -> parent: WK-RECORD (01 < 05)
-  10 WK-FIRST           -> push {10, WK-FIRST}    -> parent: WK-NAME (05 < 10)
-  10 WK-LAST            -> pop WK-FIRST, push      -> parent: WK-NAME (05 < 10)
-  05 WK-CODE            -> pop WK-LAST, WK-NAME    -> parent: WK-RECORD (01 < 05)
-  88 WK-ACTIVE          -> (88 handled separately)  -> parent: WK-CODE
-```
-
-The stack maintains items where each entry's level is strictly less than the next. When a new item arrives with a level <= the top of stack, items are popped until the stack top has a smaller level. A `CONTAINS` edge is created from the stack top to the new item.
-
-For 88-level condition names, the parent is the immediately preceding non-88 data item (found by scanning backwards).
-
-### Annotated Example
-
-```cobol
-       01  WK-EMPLOYEE.
-           05  WK-EMP-ID          PIC 9(6).
-           05  WK-EMP-NAME        PIC X(30).
-           05  WK-EMP-STATUS      PIC X(01).
-               88  WK-ACTIVE      VALUE "A".
-               88  WK-INACTIVE    VALUE "I".
-           05  WK-SALARY          PIC 9(7)V99 COMP-3.
-           05  WK-DEPT            PIC X(04) OCCURS 3 TIMES.
-```
-
-Produces:
-- `Record` node: `WK-EMPLOYEE` (level 01, section: working-storage)
-- `Property` nodes: `WK-EMP-ID`, `WK-EMP-NAME`, `WK-EMP-STATUS`, `WK-SALARY`, `WK-DEPT`
-- `Const` nodes: `WK-ACTIVE` (values: `A`), `WK-INACTIVE` (values: `I`)
-- `CONTAINS` edges: `WK-EMPLOYEE -> WK-EMP-ID`, `WK-EMPLOYEE -> WK-EMP-NAME`, etc.
-- `CONTAINS` edges: `WK-EMP-STATUS -> WK-ACTIVE`, `WK-EMP-STATUS -> WK-INACTIVE`
-
-### Data Item Cap
-
-A maximum of **500 data items per file** (`MAX_DATA_ITEMS_PER_FILE`) are processed. Some COBOL programs (especially after COPY expansion) can have 10,000+ data items, which would cause graph bloat and push the V8 relationship Map past its 16.7M entry limit across thousands of files.
-
-The cap applies after extraction: the first 500 items in source order are kept. Since 01-level records appear first, critical top-level structure is preserved.
-
-## EXEC SQL
-
-EXEC SQL blocks are accumulated across lines between `EXEC SQL` and `END-EXEC`, then parsed as a unit.
-
-### Operation Classification
-
-The first SQL keyword determines the operation:
-
-| First Keyword | Operation |
-|---------------|-----------|
-| `SELECT` | SELECT |
-| `INSERT` | INSERT |
-| `UPDATE` | UPDATE |
-| `DELETE` | DELETE |
-| `DECLARE` | DECLARE |
-| `OPEN` | OPEN |
-| `CLOSE` | CLOSE |
-| `FETCH` | FETCH |
-| *(anything else)* | OTHER |
-
-### Table Extraction
-
-Tables are extracted from SQL clauses:
-
-| Clause Pattern | Example |
-|----------------|---------|
-| `FROM <table>` | `SELECT * FROM EMPLOYEES` |
-| `INSERT INTO <table>` | `INSERT INTO EMPLOYEES` |
-| `UPDATE <table>` | `UPDATE EMPLOYEES SET ...` |
-| `JOIN <table>` | `LEFT JOIN DEPARTMENTS ON ...` |
-
-Note: The `INTO` pattern is restricted to `INSERT INTO` to avoid false positives from `FETCH ... INTO :host-var` and `SELECT ... INTO :host-var` statements, where `INTO` introduces host variables rather than table names.
-
-### Cursor Detection
-
-```cobol
-           EXEC SQL
-               DECLARE C-EMPLOYEES CURSOR FOR
-               SELECT EMP-ID, EMP-NAME FROM EMPLOYEES
-               WHERE DEPT = :WK-DEPT
-           END-EXEC
-```
-
-Extracts: cursor `C-EMPLOYEES`, table `EMPLOYEES`, host variable `WK-DEPT`.
-
-### Host Variables
-
-Host variables are COBOL variables referenced in SQL with a `:` prefix. The colon is stripped:
-
-```sql
-WHERE EMP-ID = :WK-EMP-ID AND DEPT = :WK-DEPT
-```
-
-Extracts: `WK-EMP-ID`, `WK-DEPT`.
-
-### Graph Output
-
-- `CodeElement` node per table, with description `sql-table op:{OP}`
-- `CodeElement` node per cursor, with description `sql-cursor`
-- `ACCESSES` edge from Module to each CodeElement
-- Deduplication: if the same table appears in multiple SQL blocks, only one node is created
-
-## EXEC CICS
-
-EXEC CICS blocks are accumulated and parsed similarly to SQL blocks.
-
-### Command Detection
-
-Two-word commands are detected first (matched against the block start):
-
-```
-SEND MAP, RECEIVE MAP, SEND TEXT, SEND CONTROL, READ NEXT, READ PREV
-```
-
-If no two-word command matches, the first word is used (e.g., `LINK`, `XCTL`, `RETURN`, `READ`, `WRITE`).
-
-### Extraction
-
-| Element | Pattern | Example |
-|---------|---------|---------|
-| MAP name | `MAP('name')` or `MAP("name")` | `EXEC CICS SEND MAP('EMPMENU')` |
-| PROGRAM name | `PROGRAM('name')` or `PROGRAM("name")` | `EXEC CICS LINK PROGRAM('BGTABUP')` |
-| TRANSID | `TRANSID('name')` or `TRANSID("name")` | `EXEC CICS START TRANSID('EMP1')` |
-
-### Graph Output
-
-- MAP: `CodeElement` node with description `cics-map cmd:{CMD}` + `ACCESSES` edge from Module
-- PROGRAM: `CALLS` edge (cross-program call via CICS LINK/XCTL)
-- TRANSID: `CodeElement` node with description `cics-transid cmd:{CMD}` + `ACCESSES` edge from Module
-
-### Annotated Example
-
-```cobol
-           EXEC CICS
-               SEND MAP('EMPMENU')
-               MAPSET('EMPSET')
-               FROM(WK-MAP-DATA)
-               ERASE
-           END-EXEC
-```
-
-Produces:
-- `CodeElement` node: `EMPMENU` (description: `cics-map cmd:SEND MAP`)
-- `ACCESSES` edge: Module -> `EMPMENU`
-
-## File Declarations
-
-SELECT statements in the INPUT-OUTPUT SECTION are accumulated across multiple lines (until a period terminator) and parsed for:
-
-| Clause | Pattern | Example |
-|--------|---------|---------|
-| SELECT | `SELECT <name>` | `SELECT MASTER-FILE` |
-| ASSIGN | `ASSIGN TO <file>` | `ASSIGN TO "MASTER.DAT"` |
-| ORGANIZATION | `ORGANIZATION IS <type>` | `ORGANIZATION IS INDEXED` |
-| ACCESS | `ACCESS MODE IS <mode>` | `ACCESS MODE IS DYNAMIC` |
-| RECORD KEY | `RECORD KEY IS <field>` | `RECORD KEY IS WK-EMP-ID` |
-| FILE STATUS | `FILE STATUS IS <field>` | `FILE STATUS IS WK-FILE-STATUS` |
-
-### Graph Output
-
-- `CodeElement` node with description containing all parsed clauses (e.g., `select org:INDEXED access:DYNAMIC key:WK-EMP-ID status:WK-FILE-STATUS assign:MASTER.DAT`)
-- `RECORD_KEY_OF` edge: from Property node to CodeElement (confidence 0.8)
-- `FILE_STATUS_OF` edge: from Property node to CodeElement (confidence 0.8)
-
-## FD Entries
-
-FD (File Description) entries associate a file name with its record layout:
-
-```cobol
-       FD  MASTER-FILE.
-       01  MASTER-RECORD.
-           05  MR-EMP-ID       PIC 9(6).
-           05  MR-EMP-NAME     PIC X(30).
-```
-
-The extractor tracks `pendingFdName` state: when an `FD` line is seen, the next 01-level data item becomes its record.
-
-### Graph Output
-
-- `CodeElement` node with description `fd record:{recordName}`
-- `CONTAINS` edge: FD CodeElement -> Record node
-- `CONTAINS` edge: SELECT CodeElement -> FD CodeElement (linking file declaration to file description)
-
-## ENTRY Points
-
-The `ENTRY` statement defines additional entry points into a COBOL program (in addition to the main program entry):
-
-```cobol
-       ENTRY "SUBPROG" USING WK-PARAM-1 WK-PARAM-2.
-```
-
-### Graph Output
-
-- `Constructor` node with description `entry params:{param1},{param2}` (or just `entry` if no parameters)
-- `CONTAINS` edge: Module -> Constructor
-- Symbol table entry (so the entry point is discoverable by name)
-
-## PROCEDURE DIVISION USING
-
-```cobol
-       PROCEDURE DIVISION USING WK-INPUT-REC WK-OUTPUT-REC.
-```
-
-The USING clause identifies parameters received by the program from its caller.
-
-### Graph Output
-
-- `RECEIVES` edge: Module -> Property (for each parameter name, confidence 0.8)
-
-## MOVE Statements
-
-MOVE statements produce `ACCESSES` edges in the graph:
-
-```cobol
-       MOVE WK-NAME TO OUT-NAME.
-       MOVE CORRESPONDING WK-INPUT TO WK-OUTPUT.
-       MOVE CORR WK-IN TO WK-OUT.
-```
-
-### Extraction Details
-
-- Source and target identifiers are captured
-- `CORRESPONDING` and its abbreviation `CORR` are both recognized (bulk field-by-field move)
-- Figurative constants (SPACES, ZEROS, LOW-VALUES, HIGH-VALUES, QUOTES, ALL) are skipped
-- The enclosing paragraph (`caller`) is tracked for context
-
-### MOVE CORRESPONDING / CORR Edge Reasons
-
-MOVE CORRESPONDING (and CORR) produces distinct edge reasons to differentiate from simple MOVE:
-
-| Edge | Reason (simple MOVE) | Reason (CORRESPONDING/CORR) |
-|------|---------------------|-----------------------------|
-| Read (source) | `cobol-move-read` | `cobol-move-corresponding-read` |
-| Write (target) | `cobol-move-write` | `cobol-move-corresponding-write` |
-
-This distinction allows queries to find bulk field-by-field moves separately from simple variable assignments.
-
-## GO TO DEPENDING ON
-
-The `GO TO` statement with multiple targets and a `DEPENDING ON` clause is a computed branch:
-
-```cobol
-       GO TO PARA-1 PARA-2 PARA-3
-           DEPENDING ON WK-SELECTOR.
-```
-
-All target paragraph names are extracted and emitted as separate `gotos` entries. Each target produces a `CALLS` edge in the graph (same semantics as PERFORM). The `DEPENDING ON` variable is not currently tracked as a data-flow dependency.
-
-## SORT INPUT/OUTPUT PROCEDURE
-
-SORT and MERGE statements can specify procedural entry points instead of file-based I/O:
-
-```cobol
-       SORT SORT-FILE ON ASCENDING KEY SORT-KEY
-           INPUT PROCEDURE IS PREPARE-INPUT
-           OUTPUT PROCEDURE IS FORMAT-OUTPUT.
-```
-
-`INPUT PROCEDURE IS` and `OUTPUT PROCEDURE IS` targets are extracted as control-flow targets (same as PERFORM). They produce `performs` entries and corresponding `CALLS` edges in the graph.
-
-## Fixed-Format Literal Continuation
-
-In fixed-format COBOL, string literals can span multiple lines using the continuation indicator (`-` in column 7). When a continuation line starts with a quote character, the extractor joins it with the predecessor by removing the trailing quote from the previous line and the opening quote from the continuation:
-
-```
-Line N:          MOVE "THIS IS A LONG STRI
-Line N+1 (cont): -    "NG VALUE" TO WK-FIELD.
-Merged:          MOVE "THIS IS A LONG STRING VALUE" TO WK-FIELD.
-```
-
-The trailing `"` on line N and the opening `"` on line N+1 are both removed, producing a seamless literal. If no matching quote is found on the predecessor line, the continuation is appended as-is.
-
-## Source Files
-
-- `gitnexus/src/core/ingestion/cobol-preprocessor.ts` -- All extraction logic, clause parsers, EXEC block parsers
-- `gitnexus/src/core/ingestion/workers/parse-worker.ts` -- `processCobolRegexOnly()`, graph node/edge emission
-- `gitnexus/src/core/ingestion/parsing-processor.ts` -- Sequential fallback with same `MAX_DATA_ITEMS_PER_FILE` cap

docs/code-indexing/cobol/file-detection.md

@@ -1,126 +0,0 @@
-# COBOL File Detection
-
-GitNexus detects COBOL files through two mechanisms: extension-based mapping and directory-based override for extensionless files. This document covers both, plus the copybook/program classification logic.
-
-## Extension Mapping
-
-### Program Extensions
-
-| Extension | Type |
-|-----------|------|
-| `.cbl` | COBOL program |
-| `.cob` | COBOL program |
-| `.cobol` | COBOL program |
-
-### Copybook Extensions
-
-| Extension | Type | Notes |
-|-----------|------|-------|
-| `.cpy` | Copybook | Standard |
-| `.copy` | Copybook | Standard |
-| `.gnm` / `.GNM` | Copybook | Enterprise (GnuCOBOL naming) |
-| `.fd` / `.FD` | Copybook | File Description fragment |
-| `.wrk` / `.WRK` | Copybook | Working-Storage fragment |
-| `.sel` / `.SEL` | Copybook | SELECT clause fragment |
-| `.open` / `.OPEN` | Copybook | File OPEN fragment |
-| `.close` / `.CLOSE` | Copybook | File CLOSE fragment |
-| `.ini` / `.INI` | Copybook | Initialization fragment |
-| `.def` / `.DEF` | Copybook | Definition fragment |
-
-All extension matching is case-sensitive in `getLanguageFromFilename` (the extensions above are matched as written, including uppercase variants like `.GNM`).
-
-## Extensionless File Detection: `GITNEXUS_COBOL_DIRS`
-
-Many enterprise COBOL repositories use extensionless files -- the filename alone identifies the program (e.g., `s/BGTABFL` is the source for program `BGTABFL`). GitNexus handles this via the `GITNEXUS_COBOL_DIRS` environment variable.
-
-### Configuration
-
-Set `GITNEXUS_COBOL_DIRS` to a comma-separated list of directory names:
-
-```bash
-# Files in s/, c/, and wfproc/ directories (at any depth) are treated as COBOL
-export GITNEXUS_COBOL_DIRS=s,c,wfproc
-```
-
-The matching is **case-insensitive** and checks all path segments:
-
-- `/repo/s/BGTABFL` -- matches segment `s` -- COBOL
-- `/repo/src/c/CPSESP` -- matches segment `c` -- COBOL
-- `/repo/wfproc/WF001` -- matches segment `wfproc` -- COBOL
-- `/repo/docs/README` -- no matching segment -- skipped
-
-### Decision Tree
-
-```mermaid
-flowchart TD
-    A[getLanguageFromPath] --> B[getLanguageFromFilename]
-    B --> C{Known extension?}
-    C -->|Yes .cbl/.cob/.cobol/.cpy/...| D[Return COBOL]
-    C -->|Yes .ts/.py/.java/...| E[Return other language]
-    C -->|No match| F{Has extension?}
-
-    F -->|"Has dot in basename"| G[Return null]
-    F -->|"No dot = extensionless"| H{GITNEXUS_COBOL_DIRS set?}
-
-    H -->|No| G
-    H -->|Yes| I{Any path segment<br/>matches a configured dir?}
-
-    I -->|Yes| D
-    I -->|No| G
-
-    style D fill:#e8f5e9,stroke:#2e7d32
-    style G fill:#ffebee,stroke:#c62828
-```
-
-### Implementation Detail
-
-The `GITNEXUS_COBOL_DIRS` value is parsed once (on first call) and cached in a `Set<string>`:
-
-```typescript
-// From gitnexus/src/core/ingestion/utils.ts
-const getCobolDirs = (): Set<string> => {
-  if (_cobolDirs) return _cobolDirs;
-  const raw = process.env.GITNEXUS_COBOL_DIRS;
-  _cobolDirs = raw
-    ? new Set(raw.split(',').map(d => d.trim().toLowerCase()))
-    : new Set();
-  return _cobolDirs;
-};
-```
-
-The path segment check splits the full path on `/` and tests each segment against the cached set.
-
-## Copybook vs Program Classification
-
-After a file is identified as COBOL, it must be classified as either a **program** (to be parsed for symbols) or a **copybook** (to be loaded into the copybook map for COPY expansion).
-
-### Classification Rules
-
-A COBOL file is classified as a **copybook** if ANY of these conditions is true:
-
-1. It has a recognized copybook extension (`.cpy`, `.copy`, `.gnm`, `.fd`, `.wrk`, `.sel`, `.open`, `.close`, `.ini`, `.def`)
-2. It is an extensionless file whose path contains a directory segment matching one of: `c`, `copy`, `copybooks`, `copylib`, `cpy`
-
-A file is classified as a **program** if:
-
-1. It has a program extension (`.cbl`, `.cob`, `.cobol`), OR
-2. It is extensionless and does NOT match any copybook directory pattern
-
-### Copybook Name Resolution
-
-Copybook names are derived from the filename:
-
-- Strip the extension (if any)
-- Convert to uppercase
-
-Examples:
-- `c/CPSESP` -- name: `CPSESP`
-- `copy/workgrid.cpy` -- name: `WORKGRID`
-- `c/ANAZI.GNM` -- name: `ANAZI`
-
-This name is used to resolve `COPY CPSESP.` statements during expansion.
-
-## Source Files
-
-- `gitnexus/src/core/ingestion/utils.ts` -- `getLanguageFromPath()`, `getLanguageFromFilename()`, `getCobolDirs()`
-- `gitnexus/src/core/ingestion/pipeline.ts` -- `isCobolCopybook()`, `getCopybookName()`, `COPYBOOK_EXTENSIONS`, `COBOL_PROGRAM_EXTENSIONS`

docs/code-indexing/cobol/graph-model.md

@@ -1,193 +0,0 @@
-# COBOL Graph Model
-
-This document describes the graph nodes and edges that GitNexus creates for COBOL codebases. The COBOL graph model is richer than most tree-sitter languages because it captures domain-specific constructs: file declarations, FD entries, data hierarchies, SQL tables, CICS maps, and cross-program contracts.
-
-## Entity-Relationship Diagram
-
-```mermaid
-erDiagram
-    File ||--o{ Module : DEFINES
-    File ||--o{ Function : DEFINES
-    File ||--o{ Namespace : DEFINES
-    File ||--o{ Record : DEFINES
-    File ||--o{ Property : DEFINES
-    File ||--o{ Const : DEFINES
-    File ||--o{ CodeElement : DEFINES
-    File ||--o{ Constructor : DEFINES
-    File }o--o{ File : IMPORTS
-
-    Module ||--o{ Record : CONTAINS
-    Module ||--o{ Constructor : CONTAINS
-    Module }o--o{ CodeElement : ACCESSES
-    Module }o--o{ Module : CALLS
-    Module }o--o{ Module : CONTRACTS
-    Module }o--o{ Property : RECEIVES
-
-    Record ||--o{ Property : CONTAINS
-    Record ||--o{ Const : CONTAINS
-    Record }o--o{ Record : REDEFINES
-
-    Property ||--o{ Property : CONTAINS
-    Property ||--o{ Const : CONTAINS
-    Property }o--o{ Property : REDEFINES
-    Property }o--o{ CodeElement : RECORD_KEY_OF
-    Property }o--o{ CodeElement : FILE_STATUS_OF
-
-    CodeElement ||--o{ CodeElement : CONTAINS
-    CodeElement ||--o{ Record : CONTAINS
-
-    Function }o--o{ Function : CALLS
-```
-
-## Node Types
-
-| Node Type | COBOL Concept | Created From | Example |
-|-----------|--------------|--------------|---------|
-| `Module` | PROGRAM-ID | `PROGRAM-ID. BGTABFL` | Name: `BGTABFL`, description may include author and date |
-| `Function` | Paragraph | `PROCESS-RECORD.` at column 8 | Name: `PROCESS-RECORD` |
-| `Namespace` | Procedure section | `MAIN-LOGIC SECTION.` at column 8 | Name: `MAIN-LOGIC` |
-| `Record` | 01-level data item | `01 WK-EMPLOYEE.` | Description: `level:01 section:working-storage` |
-| `Property` | 02-49/66/77 data item | `05 WK-NAME PIC X(30).` | Description: `level:05 pic:X(30) section:working-storage` |
-| `Const` | 88-level condition | `88 WK-ACTIVE VALUE "A".` | Description: `level:88 values:A` |
-| `CodeElement` | SELECT, FD, SQL table, CICS map, cursor, transid | Various | Description varies by subtype |
-| `Constructor` | ENTRY point | `ENTRY "SUBPROG" USING WK-DATA` | Description: `entry params:WK-DATA` |
-
-### CodeElement Subtypes
-
-CodeElement is used for multiple COBOL constructs, distinguished by their description prefix:
-
-| Subtype | ID Pattern | Description Format | Example |
-|---------|-----------|-------------------|---------|
-| File SELECT | `CodeElement:{path}:SELECT:{name}` | `select org:INDEXED access:DYNAMIC ...` | `SELECT MASTER-FILE` |
-| FD entry | `CodeElement:{path}:FD:{name}` | `fd record:{recordName}` | `FD MASTER-FILE` |
-| SQL table | `CodeElement:{path}:sql-table:{name}` | `sql-table op:SELECT` | Table `EMPLOYEES` |
-| SQL cursor | `CodeElement:{path}:sql-cursor:{name}` | `sql-cursor` | Cursor `C-EMPLOYEES` |
-| CICS map | `CodeElement:{path}:cics-map:{name}` | `cics-map cmd:SEND MAP` | Map `EMPMENU` |
-| CICS transid | `CodeElement:{path}:cics-transid:{name}` | `cics-transid cmd:START` | Transid `EMP1` |
-
-## Edge Types
-
-| Edge Type | Source | Target | Created By | Confidence | Example |
-|-----------|--------|--------|-----------|------------|---------|
-| `DEFINES` | File | any node | File defines its symbols | 1.0 | File -> Module `BGTABFL` |
-| `CALLS` | Function | Function | `PERFORM X [THRU Y]` | (via call-processor) | `PROCESS-RECORD` -> `CALC-TAX` |
-| `CALLS` | Module | Module | `CALL "BGTABUP"` | (via call-processor) | `BGTABFL` -> `BGTABUP` |
-| `CALLS` | Module | Module | `EXEC CICS LINK PROGRAM('X')` | (via call-processor) | `BGTABFL` -> `BGTABUP` |
-| `IMPORTS` | File | File | `COPY copybook` | (via import-processor) | Source file -> Copybook file |
-| `CONTAINS` | Module | Record | Data hierarchy root | 1.0 | `BGTABFL` -> `WK-EMPLOYEE` |
-| `CONTAINS` | Record | Property | Data hierarchy | 1.0 | `WK-EMPLOYEE` -> `WK-NAME` |
-| `CONTAINS` | Property | Property | Nested data items | 1.0 | `WK-ADDRESS` -> `WK-CITY` |
-| `CONTAINS` | Record/Property | Const | 88-level parent | 1.0 | `WK-STATUS` -> `WK-ACTIVE` |
-| `CONTAINS` | CodeElement (FD) | Record | FD record link | 1.0 | `FD:MASTER-FILE` -> `MASTER-RECORD` |
-| `CONTAINS` | CodeElement (SELECT) | CodeElement (FD) | SELECT-FD link | 0.9 | `SELECT:MASTER-FILE` -> `FD:MASTER-FILE` |
-| `CONTAINS` | Module | Constructor | ENTRY in module | 1.0 | `BGTABFL` -> `SUBPROG` |
-| `REDEFINES` | Record | Record | `01 X REDEFINES Y` | 1.0 | `WK-DATE-NUM` -> `WK-DATE-ALPHA` |
-| `REDEFINES` | Property | Property | `05 X REDEFINES Y` | 1.0 | `WK-CODE-NUM` -> `WK-CODE-ALPHA` |
-| `RECORD_KEY_OF` | Property | CodeElement (SELECT) | `RECORD KEY IS field` | 0.8 | `WK-EMP-ID` -> `SELECT:MASTER-FILE` |
-| `FILE_STATUS_OF` | Property | CodeElement (SELECT) | `FILE STATUS IS field` | 0.8 | `WK-FS` -> `SELECT:MASTER-FILE` |
-| `ACCESSES` | Module | CodeElement | EXEC SQL/CICS | 0.9 | `BGTABFL` -> `sql-table:EMPLOYEES` |
-| `RECEIVES` | Module | Property | `PROCEDURE USING` | 0.8 | `BGTABFL` -> `WK-INPUT-REC` |
-| `CONTRACTS` | Module | Module | Shared copybook detection | 0.9 | `BGTABFL` -> `BGTABUP` (via `CPSESP`) |
-
-## Full Annotated Example
-
-Given this COBOL program:
-
-```cobol
-       IDENTIFICATION DIVISION.
-       PROGRAM-ID. EMPMAINT.
-       AUTHOR. Development Team.
-
-       ENVIRONMENT DIVISION.
-       INPUT-OUTPUT SECTION.
-       FILE-CONTROL.
-           SELECT EMP-FILE
-               ASSIGN TO "EMPLOYEE.DAT"
-               ORGANIZATION IS INDEXED
-               ACCESS MODE IS DYNAMIC
-               RECORD KEY IS EMP-ID
-               FILE STATUS IS WS-FILE-STATUS.
-
-       DATA DIVISION.
-       FILE SECTION.
-       FD  EMP-FILE.
-       01  EMP-RECORD.
-           05  EMP-ID             PIC 9(6).
-           05  EMP-NAME           PIC X(30).
-
-       WORKING-STORAGE SECTION.
-       01  WS-FLAGS.
-           05  WS-FILE-STATUS     PIC X(02).
-           05  WS-EOF-FLAG        PIC X(01).
-               88  WS-EOF         VALUE "Y".
-
-       LINKAGE SECTION.
-       01  LK-SEARCH-KEY          PIC 9(6).
-
-       PROCEDURE DIVISION USING LK-SEARCH-KEY.
-       MAIN-LOGIC SECTION.
-       MAIN-START.
-           PERFORM OPEN-FILE
-           PERFORM PROCESS-RECORDS
-           PERFORM CLOSE-FILE
-           STOP RUN.
-
-       OPEN-FILE.
-           OPEN I-O EMP-FILE.
-
-       PROCESS-RECORDS.
-           MOVE LK-SEARCH-KEY TO EMP-ID
-           EXEC SQL
-               SELECT EMP_SALARY INTO :WS-SALARY
-               FROM EMPLOYEES
-               WHERE EMP_ID = :EMP-ID
-           END-EXEC
-           CALL "EMPREPORT".
-
-       CLOSE-FILE.
-           CLOSE EMP-FILE.
-```
-
-The graph produced contains:
-
-**Nodes:**
-- `Module`: EMPMAINT (description: `author:Development Team`)
-- `Namespace`: MAIN-LOGIC
-- `Function`: MAIN-START, OPEN-FILE, PROCESS-RECORDS, CLOSE-FILE
-- `Record`: EMP-RECORD, WS-FLAGS, LK-SEARCH-KEY
-- `Property`: EMP-ID, EMP-NAME, WS-FILE-STATUS, WS-EOF-FLAG
-- `Const`: WS-EOF (values: Y)
-- `CodeElement`: SELECT:EMP-FILE, FD:EMP-FILE, sql-table:EMPLOYEES
-- (COPY imports, if any, would produce File IMPORTS edges)
-
-**Edges:**
-- `DEFINES`: File -> all nodes
-- `CONTAINS`: EMPMAINT -> EMP-RECORD, EMPMAINT -> WS-FLAGS, EMPMAINT -> LK-SEARCH-KEY
-- `CONTAINS`: EMP-RECORD -> EMP-ID, EMP-RECORD -> EMP-NAME
-- `CONTAINS`: WS-FLAGS -> WS-FILE-STATUS, WS-FLAGS -> WS-EOF-FLAG
-- `CONTAINS`: WS-EOF-FLAG -> WS-EOF
-- `CONTAINS`: FD:EMP-FILE -> EMP-RECORD
-- `CONTAINS`: SELECT:EMP-FILE -> FD:EMP-FILE
-- `CALLS`: MAIN-START -> OPEN-FILE, MAIN-START -> PROCESS-RECORDS, MAIN-START -> CLOSE-FILE
-- `CALLS`: EMPMAINT -> EMPREPORT (external CALL)
-- `ACCESSES`: EMPMAINT -> sql-table:EMPLOYEES
-- `RECEIVES`: EMPMAINT -> LK-SEARCH-KEY (PROCEDURE USING)
-- `RECORD_KEY_OF`: EMP-ID -> SELECT:EMP-FILE
-- `FILE_STATUS_OF`: WS-FILE-STATUS -> SELECT:EMP-FILE
-
-## How COBOL Differs from Tree-Sitter Languages
-
-| Aspect | COBOL | Tree-Sitter Languages |
-|--------|-------|----------------------|
-| Node variety | 8 types (Module, Function, Namespace, Record, Property, Const, CodeElement, Constructor) | Typically 4-6 (Function, Class, Method, Interface, Module, Const) |
-| Domain edges | RECORD_KEY_OF, FILE_STATUS_OF, ACCESSES, RECEIVES, CONTRACTS, REDEFINES | Primarily CALLS, IMPORTS, EXTENDS, IMPLEMENTS |
-| Data hierarchy | Deep CONTAINS chains (01 -> 05 -> 10 -> 88) | Flat class members |
-| Cross-program calls | CALL "name" + CICS LINK PROGRAM | Import-based resolution |
-| Contract detection | Shared COPY copybook between caller/callee | Not applicable |
-| Metadata | AUTHOR, DATE-WRITTEN on Module | JSDoc/docstring (not indexed) |
-
-## Source Files
-
-- `gitnexus/src/core/ingestion/workers/parse-worker.ts` -- `processCobolRegexOnly()`, node/edge emission logic
-- `gitnexus/src/core/ingestion/pipeline.ts` -- `detectCrossProgamContracts()` for CONTRACTS edges
-- `gitnexus/src/core/ingestion/cobol-preprocessor.ts` -- `CobolRegexResults` interface (all extracted data)

docs/code-indexing/cobol/performance.md

@@ -1,261 +0,0 @@
-# COBOL Performance and Tuning
-
-This document covers real-world benchmarks, worker pool configuration, memory management, known limitations, and troubleshooting for COBOL indexing.
-
-## PROJECT-NAME Benchmark
-
-The PROJECT-NAME project is a large Italian payroll system written in COBOL. It serves as the primary benchmark for COBOL indexing performance.
-
-### Input
-
-| Metric                      | Value                                                                        |
-| --------------------------- | ---------------------------------------------------------------------------- |
-| Paths scanned               | 14,217                                                                       |
-| Parseable files             | 13,129                                                                       |
-| Total source size           | 224 MB                                                                       |
-| Chunks                      | 12 (at 20 MB budget)                                                         |
-| Copybooks loaded            | 2,976                                                                        |
-| Copybooks used in expansion | 2,955                                                                        |
-| Key directories             | `s/` (7773 programs), `c/` (3036 copybooks), `wfproc/` (1973 workflow files) |
-
-### Output
-
-| Metric                 | Value  |
-| ---------------------- | ------ |
-| Graph nodes            | 2.79M  |
-| Graph edges            | 5.67M  |
-| Clusters (communities) | 16,679 |
-| Execution flows        | 300    |
-
-### Timing
-
-| Phase                           | Duration          |
-| ------------------------------- | ----------------- |
-| Total                           | ~251s             |
-| KuzuDB write                    | 132s              |
-| Full-text search indexing       | 6.7s              |
-| Regex extraction (avg per file) | ~1ms              |
-| COPY expansion + deep indexing  | Remainder (~112s) |
-
-### Indexing Command
-
-```bash
-cd /path/to/PROJECT-NAME
-GITNEXUS_COBOL_DIRS=s,c,wfproc GITNEXUS_VERBOSE=1 node --max-old-space-size=8192 \
-  /path/to/gitnexus/dist/cli/index.js analyze --force
-```
-
-## Open-Source Benchmarks
-
-### CardDemo (AWS)
-
-| Metric | Value |
-| ------ | ----- |
-| Graph nodes | 12,323 |
-| Graph edges | 8,893 |
-| Total time | 7.4s |
-
-### ACAS
-
-| Metric | Value |
-| ------ | ----- |
-| Graph nodes | 14,016 |
-| Graph edges | 15,452 |
-| Total time | 9.3s |
-
-### Micro-Benchmark (Single-File Extraction)
-
-| Metric | Value |
-| ------ | ----- |
-| Per-iteration | 0.65ms |
-| Throughput | ~382K lines/sec |
-
-## Worker Pool Tuning
-
-### Sub-Batch Size
-
-The worker pool splits each worker's chunk into sub-batches to bound peak memory per `postMessage` serialization. COBOL repos use a smaller sub-batch size than the default:
-
-| Parameter             | Default     | COBOL Mode          |
-| --------------------- | ----------- | ------------------- |
-| Sub-batch size        | 1,500 files | 200 files           |
-| Per sub-batch timeout | 120s        | 120s (configurable) |
-
-**Why 200?** COBOL regex extraction + preprocessing takes ~1ms per file on average, but with COPY expansion and deep indexing the effective time is ~150ms per file. At sub-batch size 1500, that would be ~225s per sub-batch, exceeding the 120s timeout.
-
-COBOL mode is activated automatically when `GITNEXUS_COBOL_DIRS` is set:
-
-```typescript
-// From pipeline.ts
-const cobolSubBatch = process.env.GITNEXUS_COBOL_DIRS ? 200 : undefined;
-workerPool = createWorkerPool(workerUrl, undefined, cobolSubBatch);
-```
-
-### Worker Count
-
-Workers default to `min(8, cpus - 1)`. For COBOL repos, this is usually sufficient since regex extraction is CPU-bound but fast. The bottleneck is typically KuzuDB write, not extraction.
-
-### Timeout Configuration
-
-| Environment Variable                 | Default         | Purpose                                             |
-| ------------------------------------ | --------------- | --------------------------------------------------- |
-| `GITNEXUS_WORKER_TIMEOUT_MS`         | 120,000 (2 min) | Per sub-batch processing timeout                    |
-| `GITNEXUS_WORKER_STARTUP_TIMEOUT_MS` | 60,000 (1 min)  | Worker initialization timeout (tree-sitter loading) |
-
-For COBOL-only repos, worker startup is faster because tree-sitter native modules are loaded lazily (skipped entirely if only COBOL files are present).
-
-## Data Item Cap
-
-### Configuration
-
-```typescript
-const MAX_DATA_ITEMS_PER_FILE = 500;
-```
-
-This constant appears in both `parse-worker.ts` (worker path) and `parsing-processor.ts` (sequential fallback).
-
-### Rationale
-
-Some COBOL programs, especially after COPY expansion, can have 10,000+ data items. At that scale:
-
-- The in-memory relationship Map (for CONTAINS, REDEFINES, etc.) approaches the V8 16.7M entry limit across thousands of files
-- KuzuDB write time increases linearly with edge count
-- Most deep-nested items (level 20+) are rarely queried individually
-
-### Impact
-
-The cap truncates data items beyond the 500th in source order. Since 01-level Records appear first in COBOL source, the cap preserves:
-
-- All 01-level record definitions
-- The most important 02-49 level items (those closest to the record root)
-- 88-level conditions associated with early items
-
-To increase the cap for specific needs, modify the `MAX_DATA_ITEMS_PER_FILE` constant in both files.
-
-## Memory Management
-
-### COPY Expansion Breadth Guard
-
-A per-file `MAX_TOTAL_EXPANSIONS = 500` limit prevents exponential blowup from diamond-shaped COPY graphs (e.g., N copybooks each containing N COPY statements). Once the limit is reached, further COPY statements in that file are left unexpanded. See [copy-expansion.md](copy-expansion.md) for details.
-
-### COPY Expansion Memory
-
-All copybook content is loaded upfront into a Map before chunk processing begins. For PROJECT-NAME:
-
-- 2,976 copybooks, typically under 100MB total
-- The Map is shared (read-only) across chunk iterations
-- Per-chunk, the copybook map is merged with chunk file content (in case a chunk contains copybooks not in the pre-loaded set)
-- After all chunks are processed, the copybook map is freed (`cobolCopybookContents = undefined`)
-
-### Chunk Budget
-
-Source files are grouped into chunks of max 20MB (`CHUNK_BYTE_BUDGET`). Each chunk's lifecycle:
-
-1. Read file content into memory
-2. Expand COPY statements (mutates content in-place)
-3. Dispatch to workers for extraction
-4. Workers return serialized results
-5. Merge results into graph
-6. Chunk content goes out of scope (GC reclaims)
-
-This ensures only ~20MB of source + ~200-400MB of working memory (ASTs, extracted records, serialization) is active at any time.
-
-### Shared Warning Deduplication
-
-The `warnedCircular` set (used by the COPY expansion engine) is shared across all files in a chunk. This prevents the same circular copybook warning (e.g., `ANAZI includes itself`) from being logged thousands of times.
-
-## Known Limitations
-
-| Limitation                               | Impact                                                                                                          | Workaround                                                 |
-| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
-| tree-sitter-cobol hangs on ~5% of files  | Cannot use tree-sitter for COBOL                                                                                | Regex-only extraction (current approach)                   |
-| Data item cap (500/file)                 | May miss deeply nested items in large programs                                                                  | Increase `MAX_DATA_ITEMS_PER_FILE` in source               |
-| Circular copybooks (ANAZI, ANDIP, QDIPE) | Self-referential includes cannot be expanded                                                                    | Detected and skipped with warning                          |
-| wfproc/ files may not be pure COBOL      | Workflow files may produce extraction noise                                                                     | Exclude `wfproc` from `GITNEXUS_COBOL_DIRS` if problematic |
-| No MOVE DATA_FLOW edges yet              | Data flow between variables not in graph                                                                        | Reserved for future release                                |
-| Continuation line handling               | Some complex multi-line continuations (especially in string literals spanning 3+ lines) may not merge correctly | Known edge case; affects <0.1% of lines                    |
-| Single-line EXEC blocks                  | `EXEC SQL SELECT ... END-EXEC` on one line is handled, but pathological nesting is not                          | Extremely rare in practice                                 |
-| Extension case sensitivity               | `.GNM` and `.gnm` are matched differently                                                                       | Use the exact case from the codebase                       |
-
-## Troubleshooting
-
-### "COPY expansion failed"
-
-```
-[pipeline] COPY expansion failed for s/BGTABFL: Cannot read properties of null
-```
-
-**Cause:** A copybook referenced by a COPY statement cannot be found.
-
-**Fix:**
-
-1. Verify `GITNEXUS_COBOL_DIRS` includes the directory containing copybooks (typically `c`)
-2. Check that copybook filenames match the COPY target (case-insensitive, after stripping extensions)
-3. Ensure copybook files are not in `.gitignore`
-
-### Worker sub-batch timeout
-
-```
-Worker 3 sub-batch timed out after 120s (chunk: 200 items)
-```
-
-**Cause:** A sub-batch took longer than the timeout. Typically happens when one file is extremely large (50,000+ lines after COPY expansion).
-
-**Fix:** Increase the timeout:
-
-```bash
-GITNEXUS_WORKER_TIMEOUT_MS=300000 gitnexus analyze
-```
-
-### Memory errors (heap out of memory)
-
-```
-FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory
-```
-
-**Fix:** Increase Node.js heap size:
-
-```bash
-node --max-old-space-size=16384 /path/to/gitnexus/dist/cli/index.js analyze
-```
-
-For very large repos (>500MB source), consider `--max-old-space-size=32768`.
-
-### Concurrent analyze corruption
-
-**Rule:** Only ONE `gitnexus analyze` process should run at a time per repository. Concurrent writes to KuzuDB corrupt the database.
-
-If corruption occurs:
-
-```bash
-# Remove the KuzuDB directory and re-index
-rm -rf .gitnexus/kuzu
-gitnexus analyze --force
-```
-
-### Slow KuzuDB write phase
-
-The KuzuDB write phase (132s for PROJECT-NAME) is the bottleneck for large COBOL repos. This is proportional to the number of nodes and edges being written. Reducing `MAX_DATA_ITEMS_PER_FILE` or excluding non-essential directories from `GITNEXUS_COBOL_DIRS` can help.
-
-### Verbose output
-
-Enable verbose logging to see per-phase timing and statistics:
-
-```bash
-GITNEXUS_VERBOSE=1 gitnexus analyze
-```
-
-This outputs:
-
-- Scan statistics (paths, parseable files, chunk count)
-- Worker pool configuration (worker count, sub-batch size)
-- COPY expansion statistics (copybooks loaded, files expanded)
-- Community and process detection results
-- Contract detection results
-
-## Source Files
-
-- `gitnexus/src/core/ingestion/workers/worker-pool.ts` -- `DEFAULT_SUB_BATCH_SIZE`, `SUB_BATCH_TIMEOUT_MS`, `WORKER_STARTUP_TIMEOUT_MS`
-- `gitnexus/src/core/ingestion/pipeline.ts` -- `CHUNK_BYTE_BUDGET`, COBOL sub-batch configuration, chunk lifecycle
-- `gitnexus/src/core/ingestion/workers/parse-worker.ts` -- `MAX_DATA_ITEMS_PER_FILE`, `processCobolRegexOnly()`
-- `gitnexus/src/core/ingestion/parsing-processor.ts` -- Sequential fallback `MAX_DATA_ITEMS_PER_FILE`

docs/code-indexing/cobol/regex-extraction.md

@@ -1,206 +0,0 @@
-# COBOL Regex Extraction
-
-The `extractCobolSymbolsWithRegex()` function in `cobol-preprocessor.ts` performs single-pass, state-machine-driven extraction of all COBOL symbols. This document describes the state machine, line processing flow, and every regex pattern used.
-
-## State Machine: Division Tracking
-
-The extractor tracks which COBOL division is currently being processed. Division transitions are detected by the `RE_DIVISION` pattern.
-
-```mermaid
-stateDiagram-v2
-    [*] --> null : Start of file
-    null --> identification : IDENTIFICATION DIVISION
-    identification --> environment : ENVIRONMENT DIVISION
-    environment --> data : DATA DIVISION
-    data --> procedure : PROCEDURE DIVISION
-
-    note right of identification
-        Extracts: PROGRAM-ID, AUTHOR, DATE-WRITTEN
-    end note
-    note right of environment
-        Extracts: SELECT ... ASSIGN ... (file declarations)
-    end note
-    note right of data
-        Extracts: FD entries, data items (01-77, 88), COPY
-    end note
-    note right of procedure
-        Extracts: paragraphs, sections, PERFORM, CALL,
-        ENTRY, MOVE, EXEC SQL/CICS
-    end note
-```
-
-## State Machine: Data Section Tracking
-
-Within the DATA DIVISION, a secondary state machine tracks the current section to tag data items with their origin.
-
-```mermaid
-stateDiagram-v2
-    [*] --> unknown : DATA DIVISION entered
-    unknown --> working_storage : WORKING-STORAGE SECTION
-    unknown --> linkage : LINKAGE SECTION
-    unknown --> file : FILE SECTION
-    unknown --> local_storage : LOCAL-STORAGE SECTION
-    working_storage --> linkage : LINKAGE SECTION
-    working_storage --> file : FILE SECTION
-    linkage --> working_storage : WORKING-STORAGE SECTION
-    file --> working_storage : WORKING-STORAGE SECTION
-    file --> linkage : LINKAGE SECTION
-    local_storage --> working_storage : WORKING-STORAGE SECTION
-```
-
-Within the ENVIRONMENT DIVISION, the `currentEnvSection` tracks whether we are in `INPUT-OUTPUT` or `CONFIGURATION` section. SELECT statement accumulation only occurs in `INPUT-OUTPUT`.
-
-## Line Processing Flow
-
-Each raw source line goes through this pipeline:
-
-```
-Raw line
-  |
-  v
-Length < 7? ---------> Skip (flush pending if any)
-  |
-  v
-Indicator col 7
-  |
-  +-- '*' or '/' -----> Comment: skip entirely
-  |
-  +-- '-' ------------> Continuation: append to pending line
-  |
-  +-- other ----------> Normal: flush pending, strip inline comments (|),
-                        buffer as new pending logical line
-```
-
-After all lines are processed, the final pending line is flushed, along with any accumulated SELECT statement, SORT/MERGE accumulator, and any open EXEC block (truncated file without `END-EXEC`).
-
-### Inline Comment Stripping
-
-Enterprise COBOL (particularly Italian dialect) uses the pipe character `|` as an inline comment marker. The `stripInlineComment()` helper is **quote-aware**: it tracks whether the scan position is inside a single- or double-quoted string and only treats `|` as a comment marker when outside quotes. Pipe characters inside string literals are preserved.
-
-Free-format `*>` inline comment stripping uses the same quote-aware approach: the scanner walks character by character, toggling quote state, and only recognizes `*>` as a comment marker when not inside a quoted string.
-
-### Patch Marker Handling
-
-The `preprocessCobolSource()` function (run before extraction in the worker) replaces non-standard content in columns 1-6. Standard COBOL expects spaces or digit sequence numbers in this area. If any letter or `#` character is found, the entire sequence area is replaced with 6 spaces:
-
-```
-Before: mzADD MOVE WK-AMT TO WK-TOTAL
-After:        MOVE WK-AMT TO WK-TOTAL
-```
-
-This preserves exact line count for position mapping.
-
-## Regex Pattern Reference
-
-All patterns are compiled once as module-level constants and reused across calls.
-
-### Division and Section Detection
-
-| Constant | Pattern | Purpose | Example Match |
-|----------|---------|---------|---------------|
-| `RE_DIVISION` | `\b(IDENTIFICATION\|ENVIRONMENT\|DATA\|PROCEDURE)\s+DIVISION\b` | Division boundary | `PROCEDURE DIVISION` |
-| `RE_SECTION` | `\b(WORKING-STORAGE\|LINKAGE\|FILE\|LOCAL-STORAGE\|INPUT-OUTPUT\|CONFIGURATION)\s+SECTION\b` | Section boundary | `WORKING-STORAGE SECTION` |
-
-### IDENTIFICATION DIVISION
-
-| Constant | Pattern | Purpose | Example Match |
-|----------|---------|---------|---------------|
-| `RE_PROGRAM_ID` | `\bPROGRAM-ID\.\s*([A-Z][A-Z0-9-]*)` | Program name | `PROGRAM-ID. BGTABFL` |
-| `RE_AUTHOR` | `^\s+AUTHOR\.\s*(.+)` | Author metadata | `AUTHOR. D. Smith` |
-| `RE_DATE_WRITTEN` | `^\s+DATE-WRITTEN\.\s*(.+)` | Date metadata | `DATE-WRITTEN. 2024-01-15` |
-
-### ENVIRONMENT DIVISION
-
-| Constant | Pattern | Purpose | Example Match |
-|----------|---------|---------|---------------|
-| `RE_SELECT_START` | `\bSELECT\s+(?:OPTIONAL\s+)?([A-Z][A-Z0-9-]+)` | File SELECT start (with optional `SELECT OPTIONAL` support) | `SELECT MASTER-FILE`, `SELECT OPTIONAL TRANS-FILE` |
-
-SELECT statements are accumulated across multiple lines until a period terminator is found, then parsed for ASSIGN, ORGANIZATION, ACCESS, RECORD KEY, and FILE STATUS clauses.
-
-### DATA DIVISION
-
-| Constant | Pattern | Purpose | Example Match |
-|----------|---------|---------|---------------|
-| `RE_FD` | `^\s+FD\s+([A-Z][A-Z0-9-]+)` | File description | `FD MASTER-FILE` |
-| `RE_DATA_ITEM` | `^\s+(\d{1,2})\s+([A-Z][A-Z0-9-]+)\s*(.*)` | Data item (01-77) | `05 WK-NAME PIC X(30)` |
-| `RE_ANONYMOUS_REDEFINES` | `^\s+(\d{1,2})\s+REDEFINES\s+([A-Z][A-Z0-9-]+)` | Anonymous REDEFINES | `01 REDEFINES WK-REC` |
-| `RE_88_LEVEL` | `^\s+88\s+([A-Z][A-Z0-9-]+)\s+VALUES?\s+(?:ARE\s+)?(.+)` | Condition name | `88 WK-ACTIVE VALUE "Y"` |
-
-The trailing clauses of `RE_DATA_ITEM` are parsed by `parseDataItemClauses()` for PIC, USAGE, OCCURS, and REDEFINES.
-
-### PROCEDURE DIVISION
-
-| Constant | Pattern | Purpose | Example Match |
-|----------|---------|---------|---------------|
-| `RE_PROC_SECTION` | `^       ([A-Z][A-Z0-9-]+)\s+SECTION\.\s*$` | Procedure section header | `       MAIN-LOGIC SECTION.` |
-| `RE_PROC_PARAGRAPH` | `^       ([A-Z][A-Z0-9-]+)\.\s*$` | Paragraph header | `       PROCESS-RECORD.` |
-| `RE_PERFORM` | `\bPERFORM\s+([A-Z][A-Z0-9-]+)(?:\s+THRU\s+([A-Z][A-Z0-9-]+))?` | PERFORM call | `PERFORM CALC-TAX THRU CALC-TAX-EXIT` |
-| `RE_PROC_USING` | `\bPROCEDURE\s+DIVISION\s+USING\s+([\s\S]*?)(?:\.\|$)` | USING parameters | `PROCEDURE DIVISION USING WK-PARAM` |
-| `RE_ENTRY` | `\bENTRY\s+"([^"]+)"(?:\s+USING\s+([\s\S]*?))?(?:\.\|$)` | ENTRY point | `ENTRY "SUBPROG" USING WK-DATA` |
-| `RE_MOVE` | `\bMOVE\s+((?:CORRESPONDING\|CORR)\s+)?([A-Z][A-Z0-9-]+)\s+TO\s+(.+)` | MOVE statement (supports CORR abbreviation and multi-target) | `MOVE WK-NAME TO OUT-NAME`, `MOVE CORR WK-IN TO WK-OUT` |
-
-The USING parameter list (`RE_PROC_USING`) is split on `\bRETURNING\b` before tokenization -- any RETURNING clause and everything after it is excluded from the parameter list (`.split(/\bRETURNING\b/i)[0]`).
-
-Note: `RE_PROC_SECTION` and `RE_PROC_PARAGRAPH` require exactly 7 spaces of leading indentation (COBOL area A starting at column 8). This is the standard COBOL paragraph indentation.
-
-### All-Division Patterns
-
-These patterns are checked regardless of current division:
-
-| Constant | Pattern | Purpose | Example Match |
-|----------|---------|---------|---------------|
-| `RE_CALL` | `\bCALL\s+"([^"]+)"` | External program call | `CALL "BGTABUP"` |
-| `RE_COPY_UNQUOTED` | `\bCOPY\s+([A-Z][A-Z0-9-]+)(?:\s\|\.)` | COPY (unquoted) | `COPY CPSESP.` |
-| `RE_COPY_QUOTED` | `\bCOPY\s+"([^"]+)"(?:\s\|\.)` | COPY (quoted) | `COPY "WORKGRID.CPY".` |
-
-### SORT/MERGE Support
-
-| Constant | Purpose |
-|----------|---------|
-| `SORT_CLAUSE_NOISE` | Set of SORT/MERGE clause keywords filtered from USING/GIVING file lists: `ON`, `ASCENDING`, `DESCENDING`, `KEY`, `WITH`, `DUPLICATES`, `IN`, `ORDER`, `COLLATING`, `SEQUENCE`, `IS`, `THROUGH`, `THRU`, `INPUT`, `OUTPUT`, `PROCEDURE` |
-
-SORT and MERGE statements are accumulated across multiple lines (like SELECT) until a period terminator is found, then parsed for USING/GIVING file lists and INPUT/OUTPUT PROCEDURE targets. The `flushSort()` helper encapsulates the flush-and-parse logic, mirroring the existing `flushSelect()` pattern. Both helpers are called at EOF to handle truncated files.
-
-### GO TO Multi-Target
-
-`RE_GOTO` captures all paragraph names in a `GO TO` statement, including the multi-target form `GO TO p1 p2 p3 DEPENDING ON x`. The captured group contains all target names (space-separated), which are split into individual targets. Each target produces a separate `gotos` entry.
-
-### PROGRAM-ID Detection
-
-PROGRAM-ID is detected regardless of the current division state. This handles sibling programs that appear after `END PROGRAM` and omit the `IDENTIFICATION DIVISION` header -- the extractor will still capture the PROGRAM-ID and push a new program boundary.
-
-### EXEC Block Patterns
-
-| Constant | Pattern | Purpose | Example Match |
-|----------|---------|---------|---------------|
-| `RE_EXEC_SQL_START` | `\bEXEC\s+SQL\b` | Start of EXEC SQL block | `EXEC SQL` |
-| `RE_EXEC_CICS_START` | `\bEXEC\s+CICS\b` | Start of EXEC CICS block | `EXEC CICS` |
-| `RE_END_EXEC` | `\bEND-EXEC\b` | End of EXEC block | `END-EXEC` |
-
-EXEC blocks accumulate all lines between `EXEC SQL/CICS` and `END-EXEC`, then delegate to `parseExecSqlBlock()` or `parseExecCicsBlock()` for detailed extraction.
-
-## Excluded Paragraph Names
-
-The following names are excluded from paragraph detection to avoid false positives from division/section headers:
-
-```
-DECLARATIVES, END, PROCEDURE, IDENTIFICATION,
-ENVIRONMENT, DATA, WORKING-STORAGE, LINKAGE,
-FILE, LOCAL-STORAGE, COMMUNICATION, REPORT,
-SCREEN, INPUT-OUTPUT, CONFIGURATION
-```
-
-Additionally, paragraph candidates containing `DIVISION` or `SECTION` as substrings are excluded.
-
-## MOVE Skip List (Figurative Constants)
-
-MOVE statements where the source is a figurative constant are skipped:
-
-```
-SPACES, ZEROS, ZEROES, LOW-VALUES, LOW-VALUE,
-HIGH-VALUES, HIGH-VALUE, QUOTES, QUOTE, ALL
-```
-
-## Source Files
-
-- `gitnexus/src/core/ingestion/cobol-preprocessor.ts` -- `preprocessCobolSource()`, `extractCobolSymbolsWithRegex()`, all regex constants

docs/guides/microservices-grpc.md

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

docs/guides/microservices-thrift.md

@@ -1,185 +0,0 @@
-# Using GitNexus across Apache Thrift microservices
-
-## When to use this guide
-
-Use this guide when several repositories communicate through Apache Thrift and you want GitNexus to trace impact across provider and consumer boundaries. The walkthrough assumes each service is indexed on its own, then joined through a GitNexus group.
-
-This is not a framework integration guide. GitNexus reads portable Thrift IDL and common Java generated-code shapes. Framework-specific wiring, service discovery, deployment metadata, and private annotations belong outside the open-source core.
-
-## Mental model
-
-- `.thrift` files define the canonical service contract. A method in an IDL service becomes a stable contract id in the form `thrift::<namespace>.<Service>/<Method>`.
-- Service wildcard ids in the form `thrift::<namespace>.<Service>/*` are supported as manifest and matching fallback forms when a service-level link is needed.
-- Java generated-code usage points GitNexus toward implementation and call sites. Providers commonly implement generated `Service.Iface`; consumers commonly hold or construct generated service interfaces or clients.
-- Group sync matches provider and consumer contracts with the same id, then cross-repo impact can hop through those links.
-- Framework-specific wiring should be modeled by extractor plugins, manifest links, or downstream integrations rather than hard-coded into core Thrift support.
-
-## Fictional IDL
-
-```thrift
-namespace java billing.v1
-
-struct PlaceOrderRequest {
-  1: string orderId
-  2: double amount
-}
-
-struct PlaceOrderResponse {
-  1: bool accepted
-}
-
-struct GetOrderRequest {
-  1: string orderId
-}
-
-struct GetOrderResponse {
-  1: string orderId
-  2: string status
-}
-
-service OrderService {
-  PlaceOrderResponse PlaceOrder(1: PlaceOrderRequest request)
-  GetOrderResponse GetOrder(1: GetOrderRequest request)
-}
-```
-
-The service methods above produce canonical ids:
-
-- `thrift::billing.v1.OrderService/PlaceOrder`
-- `thrift::billing.v1.OrderService/GetOrder`
-- `thrift::billing.v1.OrderService/*` as a service-level manifest or matching fallback form
-
-## Java provider example
-
-Generated Java code usually exposes an `Iface` interface for the service. A provider implementation can be detected when it implements that generated interface.
-
-```java
-package example.billing;
-
-import billing.v1.GetOrderRequest;
-import billing.v1.GetOrderResponse;
-import billing.v1.OrderService;
-import billing.v1.PlaceOrderRequest;
-import billing.v1.PlaceOrderResponse;
-
-public final class OrderServiceHandler implements OrderService.Iface {
-  @Override
-  public PlaceOrderResponse PlaceOrder(PlaceOrderRequest request) {
-    return new PlaceOrderResponse(true);
-  }
-
-  @Override
-  public GetOrderResponse GetOrder(GetOrderRequest request) {
-    return new GetOrderResponse(request.getOrderId(), "CREATED");
-  }
-}
-```
-
-With the IDL available, GitNexus can connect the implementation to `thrift::billing.v1.OrderService/PlaceOrder` and `thrift::billing.v1.OrderService/GetOrder`.
-
-## Java consumer examples
-
-Consumers are strongest when Java usage can be tied back to the IDL namespace and service.
-
-```java
-package example.checkout;
-
-import billing.v1.OrderService;
-import billing.v1.PlaceOrderRequest;
-
-public final class CheckoutWorkflow {
-  private final OrderService.Iface orders;
-
-  public CheckoutWorkflow(OrderService.Iface orders) {
-    this.orders = orders;
-  }
-
-  public void submit(String orderId) throws Exception {
-    orders.PlaceOrder(new PlaceOrderRequest(orderId, 42.0));
-  }
-}
-```
-
-Some generated-code styles use the generated service type directly while keeping enough IDL context through imports and method calls.
-
-```java
-package example.reporting;
-
-import billing.v1.GetOrderRequest;
-import billing.v1.OrderService;
-
-public final class OrderLookup {
-  private final OrderService.Client client;
-
-  public OrderLookup(OrderService.Client client) {
-    this.client = client;
-  }
-
-  public String status(String orderId) throws Exception {
-    return client.GetOrder(new GetOrderRequest(orderId)).getStatus();
-  }
-}
-```
-
-When IDL context is missing, GitNexus may still emit a weaker consumer signal for generated `Iface` or `Client` shapes, but confidence is lower.
-
-## Group configuration
-
-New group configs enable Thrift contract detection by default. Keep `detect.thrift: true`
-when a group should scan for Thrift contracts, or set it to `false` to skip Thrift
-extraction for that group.
-
-```yaml
-version: 1
-name: billing-platform
-description: Fictional services connected by Apache Thrift
-
-repos:
-  checkout: checkout-service
-  billing: billing-service
-
-links: []
-
-detect:
-  http: true
-  grpc: false
-  thrift: true
-  topics: false
-  shared_libs: true
-```
-
-To disable Thrift extraction explicitly:
-
-```yaml
-detect:
-  thrift: false
-```
-
-After indexing each member repository, run group sync to extract contracts and write cross-repo links:
-
-```bash
-npx gitnexus group sync billing-platform
-```
-
-## Manifest escape hatch
-
-Use manifest links when automatic extraction cannot see a provider or consumer, or when generated code is wrapped behind an abstraction. Write the contract without the `thrift::` prefix; GitNexus canonicalizes it to the full Thrift contract id.
-
-```yaml
-links:
-  - from: checkout
-    to: billing
-    type: thrift
-    contract: billing.v1.OrderService/PlaceOrder
-    role: consumer
-```
-
-GitNexus canonicalizes that manifest entry to `thrift::billing.v1.OrderService/PlaceOrder` and uses it to connect the two repositories.
-
-## Known limitations
-
-- Java detection currently targets v1 generated-code patterns.
-- Maven and POM dependency coordinates are not used for inference.
-- Framework-specific annotations and service discovery metadata are ignored by open-source Thrift extraction.
-- Ambiguous same-name services are skipped instead of guessed.
-- Java consumers without IDL context are lower confidence and limited to generated `Iface` and `Client` shapes.

docs/plans/2026-03-26-feat-cobol-full-language-coverage-plan.md

@@ -1,326 +0,0 @@
----
-title: "feat: Complete COBOL language feature coverage for maximum knowledge graph value"
-type: feat
-status: active
-date: 2026-03-26
-origin: Feature audit from v3-integration-architect agent (session 8642401e)
----
-
-## Enhancement Summary
-
-**Deepened on:** 2026-03-26
-**Research agents used:** COBOL expert (Phase 1+2), graph value analyst, codebase explorer
-**Sections enhanced:** Phase 1 (5 features), Phase 2 (4 features), graph value ranking
-
-### Key Improvements from Research
-1. **CALL USING** is the #1 highest-value edge type (9.2/10) — fixes ~40% of missing caller references
-2. **EXEC DLI** requires dual-interface support (EXEC DLI + CBLTDLI CALL) for full IMS coverage
-3. **DECLARATIVES** is lowest-risk Phase 2 item — existing section/paragraph detection already captures structure
-4. **SET TO TRUE** accounts for 80-90% of all SET statements — prioritize this form
-5. **INSPECT** needs multi-line accumulator (like SORT) — can span 5+ continuation lines
-6. **Graph value ranking**: cobol-call-using (9.2) > cobol-error-handler (9.0) > dli-gu (8.2) > cobol-string (6.2)
-
-### New Edge Cases Discovered
-- CALL USING supports mixed modes: `USING BY REFERENCE WS-A BY CONTENT WS-B BY VALUE WS-C`
-- CALL USING `ADDRESS OF` and `OMITTED` must be filtered from parameter lists
-- EXEC DLI can have multiple SEGMENT levels in hierarchical retrieval (use matchAll)
-- DECLARATIVES can have multiple USE sections (one per file + catch-all for INPUT/OUTPUT/I-O/EXTEND)
-- INSPECT TALLYING can have multiple counters in a single statement
-- STRING/UNSTRING can span multiple lines (need accumulator pattern)
-
----
-
-# Complete COBOL Language Feature Coverage
-
-## Overview
-
-Implement the remaining 25 unhandled COBOL language features and fix 10 partial features to achieve ~95% coverage (up from 71.9%). The goal is to build the richest possible knowledge graph from COBOL codebases, enabling a future `modernize` MCP command (out of scope for this plan) that would use the graph to assist with COBOL-to-modern-language migration.
-
-## Problem Statement
-
-The COBOL processor currently handles 54 of 89 applicable language features (71.9%). The 25 unhandled features represent real data loss in the knowledge graph:
-- **Cross-program data flow** is invisible (CALL ... USING parameters not extracted)
-- **IMS/DB programs** produce empty graphs (EXEC DLI not recognized)
-- **String transformation logic** is invisible (STRING/UNSTRING/INSPECT not tracked)
-- **SQL copybook dependencies** are missing (EXEC SQL INCLUDE not mapped)
-- **Error handling flows** are lost (DECLARATIVES/USE AFTER not captured)
-
-## Proposed Solution
-
-Implement features in 4 phases, ordered by graph value density (edges created per LOC of implementation). Each phase is independently shippable and testable.
-
-## Technical Approach
-
-### Phase 1: High-Value Data Flow Edges (~150 LOC, ~8 new edge types)
-
-The highest-ROI features: they create new ACCESSES and IMPORTS edges that directly improve impact analysis.
-
-**Critical research finding**: Multi-line statement accumulation is the dominant challenge. CALL USING, STRING/UNSTRING, and multi-line data item clauses all span multiple lines in production COBOL. The free-format path processes each line independently — these features need statement accumulators (like SORT/SELECT) or the free-format path needs multi-line awareness. Estimated LOC increased from 110 to 150 to account for accumulator infrastructure.
-
-#### 1.1 EXEC SQL INCLUDE -> IMPORTS edges
-- **File:** `cobol-preprocessor.ts` (parseExecSqlBlock)
-- **What:** Detect `INCLUDE` as the operation, extract member name, emit as a `copies[]` entry
-- **Graph:** IMPORTS edge from File to included copybook/SQLCA with reason `sql-include`
-- **Tests:** Unit test for `EXEC SQL INCLUDE SQLCA END-EXEC` and `EXEC SQL INCLUDE CUSTCOPY END-EXEC`
-
-**Research insights (EXEC SQL INCLUDE):**
-- DB2 member names can contain underscores: `EXEC SQL INCLUDE CUST_TBL_DCL END-EXEC` — regex must use `[A-Z][A-Z0-9_-]+`
-- Quoted literal form: `EXEC SQL INCLUDE 'DBRMLIB.MEMBER' END-EXEC` (z/OS PDS qualified name)
-- SQLCA/SQLDA are DB2 builtins — won't resolve to repo files. Emit unresolved IMPORTS edge (still valuable)
-- No REPLACING support on EXEC SQL INCLUDE (unlike COPY)
-- Add `INCLUDE` to `OP_MAP` in `parseExecSqlBlock`; extract member via `RE_SQL_INCLUDE = /^INCLUDE\s+(?:'([^']+)'|"([^"]+)"|([A-Z][A-Z0-9_-]+))/i`
-
-#### 1.2 CALL ... USING parameter extraction -> ACCESSES edges (Graph value: 9.2/10)
-- **File:** `cobol-preprocessor.ts` (processLogicalLine CALL section)
-- **What:** After capturing CALL target, scan for USING clause. Extract parameter names (reuse USING_KEYWORDS filter). Store as `calls[].parameters: string[]`
-- **Interface:** Add `parameters?: string[]` to calls array type in CobolRegexResults
-- **File:** `cobol-processor.ts` (CALL edge block)
-- **Graph:** For each USING parameter, create ACCESSES edge from caller to data item Property node with reason `cobol-call-using`
-- **Tests:** `CALL 'AUDITLOG' USING CUST-ID WS-AMOUNT` -> 2 ACCESSES edges
-
-**Research insights (CALL USING forms):**
-- Mixed modes: `CALL 'PGM' USING BY REFERENCE WS-A BY CONTENT WS-B BY VALUE WS-C`
-- Pointer passing: `CALL 'PGM' USING ADDRESS OF WS-A`
-- Placeholder: `CALL 'PGM' USING OMITTED WS-B`
-- Filter keywords: add `ADDRESS`, `OMITTED`, `LENGTH` to USING_KEYWORDS (already has BY/VALUE/REFERENCE/CONTENT)
-- **Impact tool enhancement:** CALL-USING edges enable BFS traversal through parameter data flow — single most impactful edge type for COBOL impact analysis
-
-#### 1.3 STRING/UNSTRING data flow -> ACCESSES edges
-- **File:** `cobol-preprocessor.ts` (new section in extractProcedure)
-- **What:** Accumulate multi-line STRING/UNSTRING until period or END-STRING/END-UNSTRING. Extract sources and INTO targets.
-- **Interface:** Add `strings: Array<{ sources: string[]; target: string; type: 'string' | 'unstring'; line: number; caller: string | null }>` to CobolRegexResults
-- **Graph:** read-ACCESSES on sources, write-ACCESSES on INTO target with reason `cobol-string-read` / `cobol-string-write`
-- **Tests:** 2 unit tests + integration test assertions
-
-**Research insights (STRING/UNSTRING):**
-- **Needs statement accumulator** — STRING/UNSTRING always span multiple lines in production
-- Terminate accumulation at: period, END-STRING/END-UNSTRING, or start of next COBOL verb
-- STRING sources: identifiers before each `DELIMITED BY`. Filter: STRING, DELIMITED, BY, SIZE, ALL, INTO, WITH, POINTER, ON, OVERFLOW, NOT, END-STRING
-- UNSTRING: source is first identifier after UNSTRING; INTO targets are identifiers after INTO. Filter: DELIMITER, IN, COUNT, TALLYING, OR
-- WITH POINTER field is both read AND written (starting position updated)
-- TALLYING IN / COUNT IN fields are write targets
-- Literal sources (`'text'`) must be filtered — quote-aware tokenization needed
-- **Edge case**: STRING terminated by next verb, not period — existing fixture has `STRING ... DISPLAY` without period between them
-
-#### 1.4 OCCURS DEPENDING ON -> ACCESSES edge
-- **File:** `cobol-preprocessor.ts` (parseDataItemClauses)
-- **What:** Extend OCCURS regex to capture DEPENDING ON field, KEY fields, and INDEXED BY names
-- **Interface:** Add `dependingOn?: string`, `occursMax?: number`, `occursKeys?: Array<{direction: string; fields: string[]}>`, `indexedBy?: string[]` to data items
-- **Graph:** ACCESSES edge from table item to controlling field with reason `cobol-depends-on`
-- **Tests:** `05 WS-TABLE OCCURS 100 DEPENDING ON WS-COUNT` -> edge
-
-**Research insights (OCCURS):**
-- IBM allows `OCCURS 0 TO n DEPENDING ON` (zero minimum) and `OCCURS UNBOUNDED DEPENDING ON` (V6.4)
-- Subscripted controlling fields: `DEPENDING ON WS-COUNT(WS-IDX)` — strip subscripts before storing
-- **Pre-existing gap**: Multi-line data item clauses without continuation indicator are NOT captured. `05 WS-TABLE\n    OCCURS 100\n    DEPENDING ON WS-COUNT.` — the current RE_DATA_ITEM only gets the first line, `rest` is empty. Fixing properly requires a data item accumulator (like SELECT). **Defer full fix to Phase 3; implement same-line capture now.**
-- KEY IS fields: `ASCENDING KEY IS WS-KEY-1 WS-KEY-2` — capture for SEARCH ALL resolution
-- INDEXED BY: `INDEXED BY IDX-1 IDX-2` — capture for SET/SEARCH context
-
-#### 1.5 VALUE clause for standard data items
-- **File:** `cobol-preprocessor.ts` (parseDataItemClauses)
-- **What:** Extract VALUE using a pragmatic function that handles quoted strings, numerics, figurative constants, hex/national literals
-- **Interface:** Already exists as `values?: string[]` on data items (currently only populated for 88-level)
-- **Graph:** Stored in Property node description (no new edges)
-- **Tests:** `01 WS-STATUS PIC X VALUE 'A'` -> values: ['A']
-
-**Research insights (VALUE forms):**
-- Hex literals: `VALUE X'F1F2F3F4'`, National: `VALUE N'text'`, DBCS: `VALUE G'text'`
-- Figurative constants: SPACES, ZEROS, ZEROES, LOW-VALUES, HIGH-VALUES, QUOTES, NULL, NULLS
-- ALL literal: `VALUE ALL '*'`
-- Numeric with sign/decimal: `VALUE -123.45`, `VALUE +1`
-- `VALUE IS` optional — both `VALUE 'A'` and `VALUE IS 'A'` valid
-- **Decimal vs period ambiguity**: `VALUE 100.` — is `.` decimal or terminator? `parseDataItemClauses` already strips trailing period, so this is handled
-- IBM V6.4: floating-point `VALUE 1.0E5` — extend numeric regex if needed
-- Implementation: use a pragmatic `extractValue(rest)` function, not a single complex regex
-
-### Phase 2: EXEC DLI + DECLARATIVES (~90 LOC, ~4 new edge types)
-
-IMS/DB support and error handling flows.
-
-#### 2.1 EXEC DLI (IMS/DB) -> ACCESSES edges (Graph value: 8.2/10)
-- **File:** `cobol-preprocessor.ts` (processLogicalLine — add RE_EXEC_DLI_START check alongside SQL/CICS)
-- **What:** Accumulate EXEC DLI blocks like EXEC SQL. Parse DLI verbs (GU, GN, GNP, GHU, GHN, GHNP, ISRT, DLET, REPL, CHKP, SCHD, TERM). Extract segment name, PCB number, INTO/FROM areas, WHERE fields, PSB name.
-- **Interface:** Add `execDliBlocks: Array<{ line: number; verb: string; pcbNumber?: number; segmentName?: string; intoField?: string; fromField?: string; whereField?: string; psbName?: string }>` to CobolRegexResults
-- **Graph:** CodeElement node + ACCESSES edge to `<ims>:<segmentName>` Record node with reason `dli-{verb}`; ACCESSES edges to INTO/FROM data areas; PSB ACCESSES for SCHD
-- **Tests:** `EXEC DLI GU USING PCB(1) SEGMENT(CUSTOMER) INTO(WS-CUST) END-EXEC`
-
-**Research insights (dual IMS interface):**
-- **EXEC DLI**: Embedded command interface for CICS-DL/I programs only
-- **CBLTDLI CALL**: Batch interface via `CALL 'CBLTDLI' USING function-code PCB io-area SSA1..SSA15`
-- CBLTDLI is already captured as a CALL to 'CBLTDLI' — enrich with USING parameter semantics later
-- Multiple SEGMENT levels in hierarchical retrieval — use `matchAll` on segment regex
-- DLI verbs: GU (most common), GN, GNP, GHU, GHN, GHNP, ISRT, REPL, DLET, CHKP, SCHD, TERM, ROLL, ROLB
-- **Edge case**: DLET/REPL have no SEGMENT clause (operate on current position)
-- **Recommended order**: Implement AFTER DECLARATIVES and SET (lower risk, higher frequency)
-
-#### 2.2 DECLARATIVES / USE AFTER STANDARD EXCEPTION (Graph value: 9.0/10)
-- **File:** `cobol-preprocessor.ts` (processLogicalLine — detect DECLARATIVES keyword, track USE AFTER blocks)
-- **What:** When `DECLARATIVES.` is encountered, switch to declaratives mode. Extract USE statements binding sections to files/modes.
-- **Interface:** Add `declaratives: Array<{ sectionName: string; useType: 'error' | 'debug' | 'label' | 'reporting'; target: string; line: number }>` to CobolRegexResults
-- **Graph:** ACCESSES edge from declarative Namespace to file Record with reason `cobol-declarative-error-handler`
-- **Tests:** Unit test with DECLARATIVES section, integration test for error flow
-
-**Research insights (DECLARATIVES syntax):**
-- `USE AFTER STANDARD {EXCEPTION|ERROR} ON {file-name|INPUT|OUTPUT|I-O|EXTEND}`
-- EXCEPTION and ERROR are synonymous; STANDARD is optional in IBM dialects
-- Multiple USE sections allowed (one per file + catch-all for I/O modes)
-- `END DECLARATIVES.` must NOT reset PROCEDURE DIVISION state
-- `DECLARATIVES` is already in EXCLUDED_PARA_NAMES — no false paragraph risk
-- Existing section/paragraph detection already captures structural elements — just need USE binding
-- **Lowest risk Phase 2 item** — implement first
-
-#### 2.3 SET statement -> ACCESSES edges
-- **File:** `cobol-preprocessor.ts` (extractProcedure — new RE_SET regex)
-- **Interface:** Add `sets: Array<{ targets: string[]; form: 'to-true'|'to-value'|'up-by'|'down-by'|'address-of'|'to-null'|'to-entry'; value?: string; entryTarget?: string; entryIsLiteral?: boolean; line: number; caller: string | null }>` to CobolRegexResults
-- **Graph:** ACCESSES write edge with reason `cobol-set-condition` (TO TRUE), `cobol-set-index` (TO/UP/DOWN), `cobol-set-address` (ADDRESS OF). SET ENTRY with literal -> CALLS edge.
-- **Tests:** `SET WS-EOF TO TRUE`, `SET IDX-1 TO 5`, `SET IDX-1 UP BY 1`
-
-**Research insights (SET forms by frequency):**
-- `SET condition TO TRUE` — 80-90% of all SET usage. Multiple targets: `SET COND-A COND-B TO TRUE`
-- `SET index TO/UP BY/DOWN BY` — ~8%. Multiple indices: `SET IDX-1 IDX-2 UP BY 1`
-- `SET pointer TO ADDRESS OF data-item` / `SET ADDRESS OF data-item TO pointer` — ~2%
-- `SET proc-ptr TO ENTRY "PROGNAME"` — rare but creates CALLS edge (like dynamic CALL)
-- Filter OF/IN qualifiers: `SET COND-A OF WS-RECORD TO TRUE` (strip OF WS-RECORD)
-- **Prioritize**: SET TO TRUE alone covers 80-90% — implement this form first
-
-#### 2.4 INSPECT -> ACCESSES edges
-- **File:** `cobol-preprocessor.ts` (extractProcedure — new `inspectAccum` accumulator like SORT)
-- **What:** Accumulate multi-line INSPECT until period. Extract inspected field + tally counters.
-- **Interface:** Add `inspects: Array<{ inspectedField: string; counters: string[]; form: 'tallying'|'replacing'|'converting'|'tallying-replacing'; line: number; caller: string | null }>` to CobolRegexResults
-- **Graph:** ACCESSES read on inspected field always; write if REPLACING/CONVERTING. Write edges for tally counters. Reason: `cobol-inspect-read`/`cobol-inspect-write`/`cobol-inspect-tally`
-- **Tests:** `INSPECT WS-FIELD TALLYING WS-COUNT FOR ALL 'A'` -> read on WS-FIELD, write on WS-COUNT
-
-**Research insights (INSPECT forms by frequency):**
-- REPLACING (~60%): `INSPECT WS-STR REPLACING ALL 'A' BY 'B'`
-- TALLYING (~25%): `INSPECT WS-STR TALLYING WS-CNT FOR ALL 'A'` — multiple counters possible
-- CONVERTING (~10%): `INSPECT WS-STR CONVERTING 'abc' TO 'ABC'`
-- Combined (~5%): TALLYING + REPLACING in single statement
-- **Needs multi-line accumulator** — INSPECT frequently spans 3-5 lines in production
-- Extract tally counters with `([A-Z][A-Z0-9-]+)\s+FOR\b` matchAll pattern
-- Filter figurative constants (SPACES, ZEROS) using existing MOVE_SKIP set
-
-### Phase 3: Completeness Fixes (~60 LOC)
-
-Fix the 10 partial features and small gaps.
-
-#### 3.1 CALL ... RETURNING extraction
-- Extend RE_CALL processing to capture RETURNING target after the USING clause
-- Store as `calls[].returning?: string`
-- Graph: ACCESSES write edge with reason `cobol-call-returning`
-
-#### 3.2 SELECT OPTIONAL flag preservation
-- Store `isOptional: boolean` in FileDeclaration interface
-- Include in Record node description
-
-#### 3.3 ALTERNATE RECORD KEY extraction
-- Add regex in parseSelectStatement: `/\bALTERNATE\s+RECORD\s+KEY\s+(?:IS\s+)?([A-Z][A-Z0-9-]+)/i`
-- Store as `alternateKeys?: string[]`
-
-#### 3.4 COMMON attribute on nested programs
-- Extend RE_PROGRAM_ID: `/\bPROGRAM-ID\.\s*([A-Z][A-Z0-9-]+)(?:\s+IS\s+COMMON)?/i`
-- Store `isCommon: boolean` on Module node
-- Affects cross-program CALL resolution scope
-
-#### 3.5 IS EXTERNAL / IS GLOBAL as first-class properties
-- Change from usage string hack to proper boolean fields on data items
-- Add `isExternal?: boolean`, `isGlobal?: boolean` to data item interface
-
-#### 3.6 AUTHOR / DATE-WRITTEN mapped to Module node
-- Already extracted as programMetadata — map to Module node properties
-- `graph.addNode({ ..., properties: { ..., author, dateWritten } })`
-
-#### 3.7 REPLACE statement
-- Track REPLACE / REPLACE OFF state in preprocessor
-- Apply text substitutions during preprocessing (before regex extraction)
-- Complex: requires careful scoping rules
-
-### Phase 4: Niche Features (~30 LOC)
-
-Low-priority but nice for completeness.
-
-#### 4.1 INITIALIZE statement -> write ACCESSES
-- `/\bINITIALIZE\s+([A-Z][A-Z0-9-]+)/i`
-- ACCESSES write edge with reason `cobol-initialize`
-
-#### 4.2 Remaining IDENTIFICATION DIVISION paragraphs
-- DATE-COMPILED, INSTALLATION, SECURITY, REMARKS
-- Map to Module node description properties
-
-#### 4.3 EXEC SQL INCLUDE -> IMPORTS edge (expansion)
-- For EXEC SQL INCLUDE inside EXEC blocks that reference copybooks containing SQL
-- Create IMPORTS edge similar to COPY
-
-## Acceptance Criteria
-
-### Functional Requirements
-
-- [ ] Phase 1: All 5 features implemented with unit + integration tests
-- [ ] Phase 2: All 4 features implemented with unit + integration tests
-- [ ] Phase 3: All 7 partial features fixed
-- [ ] Phase 4: At least 2 of 3 niche features implemented
-- [ ] All existing 145 tests continue to pass
-- [ ] TypeScript compiles cleanly
-
-### Non-Functional Requirements
-
-- [ ] No performance regression: CardDemo benchmark stays under 8s
-- [ ] No file exceeds 1500 LOC (preprocessor currently 1326)
-- [ ] ACAS benchmark shows increased node/edge counts (more data extracted)
-- [ ] CardDemo benchmark shows increased edge counts (CALL USING, STRING, etc.)
-
-### Quality Gates
-
-- [ ] Each phase has its own commit
-- [ ] Integration test assertions updated with exact counts per phase
-- [ ] Benchmark run after each phase to track graph growth
-
-## Dependencies & Risks
-
-### Dependencies
-- None. All changes are additive to existing COBOL processor code.
-- No LanguageProvider changes needed.
-- No graph schema changes needed (all new constructs map to existing node labels + edge types).
-
-### Risks
-- **preprocessor.ts size**: Currently 1326 LOC. Phase 1+2 adds ~200 LOC -> 1526 LOC. May need to extract helpers into a separate `cobol-data-flow.ts` module if it exceeds 1500.
-- **REPLACE statement** (Phase 3.7) is the most complex feature — requires tracking text substitution state across logical lines. Consider deferring to a separate PR if it takes >100 LOC.
-- **EXEC DLI** (Phase 2.1) is only testable against IMS codebases. Need fixture data or synthetic test cases.
-
-## Graph Value Ranking by MCP Tool Impact
-
-Research agent analyzed all 5 MCP tools (query, context, impact, detect_changes, rename) against planned edge types:
-
-| Edge Type | QUERY | CONTEXT | IMPACT | DETECT | RENAME | **Overall** |
-|-----------|-------|---------|--------|--------|--------|-------------|
-| `cobol-call-using` | 4/5 | 5/5 | 5/5 | 4/5 | 4/5 | **9.2/10** |
-| `cobol-error-handler` | 5/5 | 4/5 | 5/5 | 5/5 | 2/5 | **9.0/10** |
-| `dli-*` (IMS verbs) | 4/5 | 4/5 | 5/5 | 4/5 | 2/5 | **8.2/10** |
-| `cobol-string-*` | 4/5 | 3/5 | 3/5 | 3/5 | 2/5 | **6.2/10** |
-
-**Key finding**: `cobol-call-using` alone would fix ~40% of missing caller references in COBOL graphs.
-
-## Future Considerations
-
-This plan provides the graph data foundation for a future `modernize` MCP command (out of scope) that would:
-- Use CALL USING edges to map data contracts between programs
-- Use STRING/UNSTRING edges to identify data transformation logic
-- Use EXEC SQL/DLI edges to map database access patterns
-- Use DECLARATIVES to understand error handling architecture
-- Use the complete knowledge graph to generate migration plans
-
-**MCP tool enhancements needed** (after this plan ships):
-- Add `cobol-call-using`, `cobol-error-handler`, `dli-*` to IMPACT tool's default `relationTypes` for COBOL repos
-- Add confidence floors for new edge types in `IMPACT_RELATION_CONFIDENCE`
-- Register new edge types in `VALID_RELATION_TYPES` set (`local-backend.ts:52`)
-
-## Sources & References
-
-### Internal References
-- Feature audit: session 8642401e (COBOL expert agent, 123 features audited)
-- Prior plans: `docs/plans/2026-03-25-feat-cobol-100-percent-feature-coverage-plan.md`
-- Architecture: `docs/code-indexing/cobol/` (7 documentation files)
-
-### External References
-- COBOL features reference: mainframestechhelp.com/tutorials/cobol/features.htm
-- COBOL-85 standard: ISO/IEC 1989:1985
-- IBM Enterprise COBOL reference

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

@@ -1,725 +0,0 @@
-# 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

@@ -1,175 +0,0 @@
-# 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).

eval/README.md

@@ -162,8 +162,8 @@ Each mode has a `system_{mode}.jinja` + `instance_{mode}.jinja` pair. The agent
 
 ```
 Agent → bash command → /usr/local/bin/gitnexus-query
-  → curl localhost:4848/tool/query     (fast path: eval-server, ~100ms)
-  → npx gitnexus query                 (fallback: cold CLI, ~5-10s)
+  → curl http://127.0.0.1:4848/tool/query   (fast path: eval-server, ~100ms)
+  → npx gitnexus query                       (fallback: cold CLI, ~5-10s)
 ```
 
 Each tool script in `/usr/local/bin/` is standalone — no sourcing, no env inheritance needed. This is critical because mini-swe-agent runs every command via `subprocess.run` in a fresh subshell.
@@ -176,6 +176,61 @@ The eval-server is a lightweight HTTP daemon that:
 - Includes next-step hints to guide tool chaining (query → context → impact → fix)
 - Auto-shuts down after idle timeout
 
+**CLI flags:**
+
+| Flag | Default | Purpose |
+|------|---------|---------|
+| `--port <port>` | `4848` | Port to listen on |
+| `--host <host>` | `127.0.0.1` | Bind address — use `0.0.0.0` for cross-container access |
+| `--idle-timeout <seconds>` | `0` (disabled) | Auto-shutdown after N seconds of inactivity |
+
+**READY signal:**
+
+When the server is ready, it writes to stdout:
+
+```
+# IPv4
+GITNEXUS_EVAL_SERVER_READY:127.0.0.1:4848
+
+# IPv6 (bracketed to avoid colon ambiguity)
+GITNEXUS_EVAL_SERVER_READY:[::1]:4848
+```
+
+Parse the port as the last colon-segment (`split(':').pop()`) — not `split(':')[1]`, which breaks for IPv6 and for non-loopback IPv4 hosts added in this release.
+
+### Custom port and host
+
+`run_eval.py` does not expose `--port` or `--host` as CLI flags. Configure them in your mode YAML under the `environment:` key:
+
+```yaml
+# configs/modes/native_augment.yaml (or whichever mode you're running)
+environment:
+  eval_server_port: 4849         # change if 4848 is already in use on the host
+  eval_server_host: "0.0.0.0"   # bind all interfaces — needed for cross-container setups
+```
+
+Defaults are `port: 4848` and `host: 127.0.0.1` (loopback only). Use `0.0.0.0` only when the agent container needs to reach the eval-server from a separate network namespace. The health probe and tool scripts connect via the configured bind host (defaulting to `127.0.0.1`), which is reachable for both loopback and all-interface binds.
+
+`"localhost"` is also a valid `eval_server_host` value. The OS resolves it at bind time — typically `127.0.0.1` on dual-stack or IPv4-only systems, and `::1` on IPv6-only systems. The exact result depends on your `/etc/hosts` and `gai.conf`. The READY signal will reflect the actual bound address (e.g. `GITNEXUS_EVAL_SERVER_READY:127.0.0.1:4848` or `GITNEXUS_EVAL_SERVER_READY:[::1]:4848`), not the literal string `localhost`. Use this when you want the server to bind to whichever loopback address the OS prefers rather than forcing IPv4.
+
+**Running eval-server directly in Docker / Docker Compose:**
+
+```bash
+# Bind to all interfaces so sibling containers can reach it
+gitnexus eval-server --host 0.0.0.0 --port 4848
+
+# Then probe from a sibling container via its service hostname
+curl http://eval-container:4848/health
+```
+
+If you need a non-default port (e.g. to avoid conflicts), pass `--port <port>` alongside `--host`. The READY signal will reflect both:
+
+```
+GITNEXUS_EVAL_SERVER_READY:0.0.0.0:5000
+```
+
+Parse the port as the last colon-segment (`split(':').pop()`) — safe for both IPv4 and bracketed IPv6 forms.
+
 ### Index caching
 
 SWE-bench repos repeat (Django has 200+ instances at different commits). The harness caches GitNexus indexes per `(repo, commit)` hash in `~/.gitnexus-eval-cache/` to avoid redundant re-indexing.

eval/environments/gitnexus_docker.py

@@ -39,6 +39,7 @@ logger = logging.getLogger("gitnexus_docker")
 
 DEFAULT_CACHE_DIR = Path.home() / ".gitnexus-eval-cache"
 EVAL_SERVER_PORT = 4848
+EVAL_SERVER_HOST = "127.0.0.1"
 
 
 class GitNexusDockerEnvironment(DockerEnvironment):
@@ -62,6 +63,7 @@ class GitNexusDockerEnvironment(DockerEnvironment):
         skip_embeddings: bool = True,
         gitnexus_timeout: int = 120,
         eval_server_port: int = EVAL_SERVER_PORT,
+        eval_server_host: str = EVAL_SERVER_HOST,
         **kwargs,
     ):
         super().__init__(**kwargs)
@@ -70,6 +72,7 @@ class GitNexusDockerEnvironment(DockerEnvironment):
         self.skip_embeddings = skip_embeddings
         self.gitnexus_timeout = gitnexus_timeout
         self.eval_server_port = eval_server_port
+        self.eval_server_host = eval_server_host
         self.index_time: float = 0.0
         self._gitnexus_ready = False
 
@@ -165,22 +168,29 @@ class GitNexusDockerEnvironment(DockerEnvironment):
 
     def _start_eval_server(self):
         """Start the GitNexus eval-server daemon in the background."""
-        logger.info(f"Starting eval-server on port {self.eval_server_port}...")
+        logger.info(
+            f"Starting eval-server on {self.eval_server_host}:{self.eval_server_port}..."
+        )
 
         self.execute({
             "command": (
                 f"nohup npx gitnexus eval-server --port {self.eval_server_port} "
+                f"--host {self.eval_server_host} "
                 f"--idle-timeout 600 "
                 f"> /tmp/gitnexus-eval-server.log 2>&1 &"
             ),
             "timeout": 5,
         })
 
+        # Use 127.0.0.1 for the health probe — reachable whether server binds
+        # loopback or all interfaces (0.0.0.0), avoiding DNS resolution issues.
+        health_host = "127.0.0.1"
+
         # Wait for the server to be ready (up to ~15s for KuzuDB init)
         for i in range(EVAL_SERVER_HEALTH_RETRIES):
             time.sleep(EVAL_SERVER_HEALTH_INTERVAL_SECONDS)
             health = self.execute({
-                "command": f"curl -sf http://127.0.0.1:{self.eval_server_port}/health 2>/dev/null || echo 'NOT_READY'",
+                "command": f"curl -sf http://{health_host}:{self.eval_server_port}/health 2>/dev/null || echo 'NOT_READY'",
                 "timeout": EVAL_SERVER_HEALTH_TIMEOUT_SECONDS,
             })
             output = health.get("output", "").strip()
@@ -201,7 +211,7 @@ class GitNexusDockerEnvironment(DockerEnvironment):
         )
 
     @staticmethod
-    def _render_tool_script(spec: ToolScriptSpec, port: str) -> str:
+    def _render_tool_script(spec: ToolScriptSpec, port: str, host: str = EVAL_SERVER_HOST) -> str:
         """
         Render a standalone bash script for a GitNexus tool.
 
@@ -212,6 +222,7 @@ class GitNexusDockerEnvironment(DockerEnvironment):
 
         if spec.endpoint:
             lines.append(f'PORT="${{GITNEXUS_EVAL_PORT:-{port}}}"')
+            lines.append(f'HOST="${{GITNEXUS_EVAL_HOST:-{host}}}"')
 
         if spec.header:
             lines.append(spec.header.strip())
@@ -221,7 +232,7 @@ class GitNexusDockerEnvironment(DockerEnvironment):
 
         if spec.endpoint:
             lines.append(
-                f'result=$(curl -sf -X POST "http://127.0.0.1:${{PORT}}{spec.endpoint}" '
+                f'result=$(curl -sf -X POST "http://${{HOST}}:${{PORT}}{spec.endpoint}" '
                 '-H "Content-Type: application/json" -d "$payload" 2>/dev/null)'
             )
             lines.append('if [ $? -eq 0 ] && [ -n "$result" ]; then echo "$result"; exit 0; fi')
@@ -244,9 +255,10 @@ class GitNexusDockerEnvironment(DockerEnvironment):
         Uses heredocs with quoted delimiter to avoid all quoting/escaping issues.
         """
         port = str(self.eval_server_port)
+        host = self.eval_server_host
 
         for spec in TOOL_SPECS.values():
-            script_content = self._render_tool_script(spec, port).strip()
+            script_content = self._render_tool_script(spec, port, host).strip()
             # Use heredoc with quoted delimiter — prevents all variable expansion and quoting issues
             self.execute({
                 "command": (
@@ -387,5 +399,6 @@ class GitNexusDockerEnvironment(DockerEnvironment):
             "index_time_seconds": round(self.index_time, 2),
             "skip_embeddings": self.skip_embeddings,
             "eval_server_port": self.eval_server_port,
+            "eval_server_host": self.eval_server_host,
         }
         return base

eval/uv.lock

@@ -760,11 +760,11 @@ wheels = [
 
 [[package]]
 name = "idna"
-version = "3.11"
+version = "3.15"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/6f/6d/0703ccc57f3a7233505399edb88de3cbd678da106337b9fcde432b65ed60/idna-3.11.tar.gz", hash = "sha256:795dafcc9c04ed0c1fb032c2aa73654d8e8c5023a7df64a53f39190ada629902", size = 194582, upload-time = "2025-10-12T14:55:20.501Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/82/77/7b3966d0b9d1d31a36ddf1746926a11dface89a83409bf1483f0237aa758/idna-3.15.tar.gz", hash = "sha256:ca962446ea538f7092a95e057da437618e886f4d349216d2b1e294abfdb65fdc", size = 199245, upload-time = "2026-05-12T22:45:57.011Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/0e/61/66938bbb5fc52dbdf84594873d5b51fb1f7c7794e9c0f5bd885f30bc507b/idna-3.11-py3-none-any.whl", hash = "sha256:771a87f49d9defaf64091e6e6fe9c18d4833f140bd19464795bc32d966ca37ea", size = 71008, upload-time = "2025-10-12T14:55:18.883Z" },
+    { url = "https://files.pythonhosted.org/packages/d2/23/408243171aa9aaba178d3e2559159c24c1171a641aa83b67bdd3394ead8e/idna-3.15-py3-none-any.whl", hash = "sha256:048adeaf8c2d788c40fee287673ccaa74c24ffd8dcf09ffa555a2fbb59f10ac8", size = 72340, upload-time = "2026-05-12T22:45:55.733Z" },
 ]
 
 [[package]]
@@ -2278,11 +2278,11 @@ wheels = [
 
 [[package]]
 name = "urllib3"
-version = "2.6.3"
+version = "2.7.0"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/c7/24/5f1b3bdffd70275f6661c76461e25f024d5a38a46f04aaca912426a2b1d3/urllib3-2.6.3.tar.gz", hash = "sha256:1b62b6884944a57dbe321509ab94fd4d3b307075e0c2eae991ac71ee15ad38ed", size = 435556, upload-time = "2026-01-07T16:24:43.925Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/53/0c/06f8b233b8fd13b9e5ee11424ef85419ba0d8ba0b3138bf360be2ff56953/urllib3-2.7.0.tar.gz", hash = "sha256:231e0ec3b63ceb14667c67be60f2f2c40a518cb38b03af60abc813da26505f4c", size = 433602, upload-time = "2026-05-07T16:13:18.596Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/39/08/aaaad47bc4e9dc8c725e68f9d04865dbcb2052843ff09c97b08904852d84/urllib3-2.6.3-py3-none-any.whl", hash = "sha256:bf272323e553dfb2e87d9bfd225ca7b0f467b919d7bbd355436d3fd37cb0acd4", size = 131584, upload-time = "2026-01-07T16:24:42.685Z" },
+    { url = "https://files.pythonhosted.org/packages/7f/3e/5db95bcf282c52709639744ca2a8b149baccf648e39c8cc87553df9eae0c/urllib3-2.7.0-py3-none-any.whl", hash = "sha256:9fb4c81ebbb1ce9531cce37674bbc6f1360472bc18ca9a553ede278ef7276897", size = 131087, upload-time = "2026-05-07T16:13:17.151Z" },
 ]
 
 [[package]]

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

@@ -14,6 +14,8 @@
 const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
+const { acquireHookSlot } = require('./hook-lock.js');
+const { hasGitNexusDbLockedByGitNexusServer } = require('./hook-db-lock-probe.cjs');
 
 /**
  * Read JSON input from stdin synchronously.
@@ -75,6 +77,7 @@ function findCanonicalRepoRoot(cwd) {
       timeout: 2000,
       cwd,
       stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true,
     });
     if (result.error || result.status !== 0) return null;
     const commonDir = (result.stdout || '').trim();
@@ -102,6 +105,28 @@ function findGitNexusDir(startDir) {
   return null;
 }
 
+function hasGitNexusServerOwner(gitNexusDir) {
+  return hasGitNexusDbLockedByGitNexusServer(path.join(gitNexusDir, 'lbug'), process.pid);
+}
+
+function extractAugmentContext(stderr) {
+  const output = (stderr || '').trim();
+  const marker = output.indexOf('[GitNexus]');
+  const debug = process.env.GITNEXUS_DEBUG === '1' || process.env.GITNEXUS_DEBUG === 'true';
+  if (debug && output.length > 0) {
+    // Emit the FULL discarded prefix (everything before the marker, or all of
+    // it when no marker is present) so suppressed diagnostics — LadybugDB lock
+    // warnings, parser errors, etc. — remain recoverable on the hook's own
+    // stderr. The untruncated payload lets operators see exactly what was
+    // filtered out instead of a 180-char JSON-quoted preview.
+    const discarded = marker === -1 ? output : output.slice(0, marker).trim();
+    if (discarded.length > 0) {
+      process.stderr.write(`[GitNexus hook] augment stderr discarded prefix:\n${discarded}\n`);
+    }
+  }
+  return marker === -1 ? '' : output.slice(marker).trim();
+}
+
 /**
  * Extract search pattern from tool input.
  */
@@ -169,6 +194,16 @@ function extractPattern(toolName, toolInput) {
  */
 function runGitNexusCli(args, cwd, timeout) {
   const isWin = process.platform === 'win32';
+  const hookCli = process.env.GITNEXUS_HOOK_CLI_PATH;
+  if (hookCli !== undefined && String(hookCli).trim() && fs.existsSync(String(hookCli))) {
+    return spawnSync(process.execPath, [String(hookCli), ...args], {
+      encoding: 'utf-8',
+      timeout,
+      cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+  }
 
   // Detect whether 'gitnexus' is on PATH (cheap check, no execution)
   let useDirectBinary = false;
@@ -177,6 +212,7 @@ function runGitNexusCli(args, cwd, timeout) {
       encoding: 'utf-8',
       timeout: 3000,
       stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true,
     });
     useDirectBinary = which.status === 0;
   } catch {
@@ -189,6 +225,7 @@ function runGitNexusCli(args, cwd, timeout) {
       timeout,
       cwd,
       stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true,
     });
   }
   // npx fallback needs shell on Windows since npx is a .cmd script
@@ -197,6 +234,7 @@ function runGitNexusCli(args, cwd, timeout) {
     timeout: timeout + 5000,
     cwd,
     stdio: ['pipe', 'pipe', 'pipe'],
+    windowsHide: true,
   });
 }
 
@@ -217,7 +255,8 @@ function sendHookResponse(hookEventName, message) {
 function handlePreToolUse(input) {
   const cwd = input.cwd || process.cwd();
   if (!path.isAbsolute(cwd)) return;
-  if (!findGitNexusDir(cwd)) return;
+  const gitNexusDir = findGitNexusDir(cwd);
+  if (!gitNexusDir) return;
 
   const toolName = input.tool_name || '';
   const toolInput = input.tool_input || {};
@@ -226,19 +265,28 @@ function handlePreToolUse(input) {
 
   const pattern = extractPattern(toolName, toolInput);
   if (!pattern || pattern.length < 3) return;
+  if (hasGitNexusServerOwner(gitNexusDir)) {
+    process.stderr.write('[GitNexus] augment skipped: MCP server owns DB\n');
+    return;
+  }
+
+  const release = acquireHookSlot(gitNexusDir);
+  if (!release) return;
 
   let result = '';
   try {
     const child = runGitNexusCli(['augment', '--', pattern], cwd, 7000);
     if (!child.error && child.status === 0) {
-      result = child.stderr || '';
+      result = extractAugmentContext(child.stderr || '');
     }
   } catch {
     /* graceful failure */
+  } finally {
+    release();
   }
 
-  if (result && result.trim()) {
-    sendHookResponse('PreToolUse', result.trim());
+  if (result) {
+    sendHookResponse('PreToolUse', result);
   }
 }
 
@@ -275,6 +323,7 @@ function handlePostToolUse(input) {
       timeout: 3000,
       cwd,
       stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true,
     });
     currentHead = (headResult.stdout || '').trim();
   } catch {

gitnexus-claude-plugin/hooks/hook-db-lock-probe.cjs

@@ -0,0 +1,241 @@
+/**
+ * Cross-platform best-effort probe: does another process hold dbPath open
+ * with a command line that looks like a GitNexus MCP/serve server?
+ *
+ * Backends (no user-installed Sysinternals):
+ * - Linux: scan procfs under /proc (per-PID fd entries) via stat(2) (dev+inode); works without lsof;
+ *   optional lsof fallback when proc scan finds nothing.
+ * - macOS / *BSD / etc.: trusted lsof + ps (absolute paths first).
+ * - Windows: Restart Manager (rstrtmgr) via bundled PowerShell script +
+ *   Win32_Process for command lines; trusted powershell.exe under %SystemRoot%.
+ *
+ * Fail-open on most errors; fail-closed only on lsof ETIMEDOUT (Unix) or
+ * PowerShell ETIMEDOUT (Windows), matching the hook contract.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+function isGitNexusServerCommand(command) {
+  const hasServerMode = /(?:^|\s)(mcp|serve)(?:\s|$)/.test(command);
+  const hasGitNexus =
+    /(?:^|[/\\\s])gitnexus(?:\.cmd)?(?:\s|$)/.test(command) ||
+    /node_modules[/\\]gitnexus[/\\]/.test(command);
+  return hasServerMode && hasGitNexus;
+}
+
+function resolveHookBinary(tool) {
+  const envKey = tool === 'lsof' ? 'GITNEXUS_HOOK_LSOF_PATH' : 'GITNEXUS_HOOK_PS_PATH';
+  const fromEnv = process.env[envKey];
+  if (fromEnv && String(fromEnv).trim() && fs.existsSync(String(fromEnv))) {
+    return String(fromEnv);
+  }
+  const candidates =
+    tool === 'lsof'
+      ? ['/usr/bin/lsof', '/usr/sbin/lsof', '/sbin/lsof', tool]
+      : ['/bin/ps', '/usr/bin/ps', tool];
+  for (const candidate of candidates) {
+    if (candidate === tool) return tool;
+    try {
+      if (fs.existsSync(candidate)) return candidate;
+    } catch {
+      /* ignore */
+    }
+  }
+  return tool;
+}
+
+function resolveWindowsPowerShellPath() {
+  const fromEnv = process.env.GITNEXUS_HOOK_POWERSHELL_PATH;
+  if (fromEnv && String(fromEnv).trim() && fs.existsSync(String(fromEnv).trim())) {
+    return String(fromEnv).trim();
+  }
+  const root = process.env.SystemRoot || 'C:\\Windows';
+  const ps = path.join(root, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+  if (fs.existsSync(ps)) return ps;
+  const psWow = path.join(root, 'SysWOW64', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+  if (fs.existsSync(psWow)) return psWow;
+  return 'powershell.exe';
+}
+
+// Sentinel:
+//   undefined = not loaded yet (try the read)
+//   string    = encoded PowerShell command (successful load)
+//   null      = load attempted and failed (do not retry; warning already emitted)
+let windowsRmListPsEncodedCommandCache;
+let windowsRmListPsLoadFailureWarned = false;
+function getWindowsRmListEncodedCommand() {
+  if (windowsRmListPsEncodedCommandCache !== undefined) {
+    return windowsRmListPsEncodedCommandCache;
+  }
+  try {
+    const ps1Path = path.join(__dirname, 'win-rm-list-json.ps1');
+    const src = fs
+      .readFileSync(ps1Path, 'utf8')
+      .replace(/^\uFEFF/, '')
+      .replace(/\r\n/g, '\n');
+    windowsRmListPsEncodedCommandCache = Buffer.from(src, 'utf16le').toString('base64');
+  } catch (err) {
+    windowsRmListPsEncodedCommandCache = null;
+    if (
+      !windowsRmListPsLoadFailureWarned &&
+      (process.env.GITNEXUS_DEBUG === '1' || process.env.GITNEXUS_DEBUG === 'true')
+    ) {
+      windowsRmListPsLoadFailureWarned = true;
+      const msg = err && err.message ? String(err.message).slice(0, 200) : 'unknown';
+      process.stderr.write(`[GitNexus hook] win-rm-list-json.ps1 load failed: ${msg}\n`);
+    }
+  }
+  return windowsRmListPsEncodedCommandCache;
+}
+
+function hasGitNexusServerOwnerWindows(dbPathAbs, myPid) {
+  const encoded = getWindowsRmListEncodedCommand();
+  if (!encoded) return false;
+  const psExe = resolveWindowsPowerShellPath();
+  const r = spawnSync(
+    psExe,
+    [
+      '-NoProfile',
+      '-NonInteractive',
+      '-ExecutionPolicy',
+      'Bypass',
+      '-STA',
+      '-EncodedCommand',
+      encoded,
+    ],
+    {
+      encoding: 'utf-8',
+      timeout: 6000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      windowsHide: true,
+      env: { ...process.env, GITNEXUS_HOOK_RM_TARGET: dbPathAbs },
+    },
+  );
+  // ETIMEDOUT means the PowerShell probe didn't return in time; treat as 'unresponsive process holds DB' → fail-closed (skip augment).
+  if (r.error) return r.error.code === 'ETIMEDOUT';
+  if (r.status !== 0) return false;
+  let rows;
+  try {
+    rows = JSON.parse(String(r.stdout || '').trim() || '[]');
+  } catch {
+    return false;
+  }
+  if (!Array.isArray(rows)) return false;
+  for (const row of rows) {
+    const procId = Number(row.pid);
+    const cmd = String(row.cmd || '');
+    if (!Number.isFinite(procId) || procId === myPid) continue;
+    if (isGitNexusServerCommand(cmd)) return true;
+  }
+  return false;
+}
+
+function readLinuxCmdline(pidStr) {
+  try {
+    return fs.readFileSync(`/proc/${pidStr}/cmdline`, 'utf8').replace(/\0+/g, ' ').trim();
+  } catch {
+    return '';
+  }
+}
+
+function linuxProcScanFindGitNexusServer(dbPathAbs, myPid) {
+  const raw = process.env.GITNEXUS_HOOK_LINUX_PROC_BUDGET_MS;
+  const budget = Number(raw && String(raw).trim()) ? Number.parseInt(String(raw), 10) : 1200;
+  const start = Date.now();
+  let targetStat;
+  try {
+    targetStat = fs.statSync(dbPathAbs);
+  } catch {
+    return false;
+  }
+  let procEntries;
+  try {
+    procEntries = fs.readdirSync('/proc', { withFileTypes: true });
+  } catch {
+    return false;
+  }
+  for (const ent of procEntries) {
+    if (Date.now() - start > budget) return false;
+    if (!ent.isDirectory() || !/^\d+$/.test(ent.name)) continue;
+    const pid = Number.parseInt(ent.name, 10);
+    if (!Number.isFinite(pid) || pid === myPid) continue;
+    const fdDir = path.join('/proc', ent.name, 'fd');
+    let fds;
+    try {
+      fds = fs.readdirSync(fdDir);
+    } catch {
+      continue;
+    }
+    let holds = false;
+    for (const fd of fds) {
+      if (Date.now() - start > budget) return false;
+      try {
+        const st = fs.statSync(path.join(fdDir, fd));
+        if (st.dev === targetStat.dev && st.ino === targetStat.ino) {
+          holds = true;
+          break;
+        }
+      } catch {
+        /* ignore */
+      }
+    }
+    if (!holds) continue;
+    if (isGitNexusServerCommand(readLinuxCmdline(ent.name))) return true;
+  }
+  return false;
+}
+
+function unixLsofPsFindGitNexusServer(dbPathAbs, myPid) {
+  const lsofPath = resolveHookBinary('lsof');
+  const lsof = spawnSync(lsofPath, ['-nP', '-t', '--', dbPathAbs], {
+    encoding: 'utf-8',
+    timeout: 1000,
+    stdio: ['ignore', 'pipe', 'ignore'],
+    windowsHide: true,
+  });
+  if (lsof.error) return lsof.error.code === 'ETIMEDOUT';
+
+  const pids = (lsof.stdout || '').split(/\s+/).filter(Boolean);
+  const psPath = resolveHookBinary('ps');
+  for (const pid of pids) {
+    if (Number(pid) === myPid) continue;
+    const ps = spawnSync(psPath, ['-p', pid, '-o', 'command='], {
+      encoding: 'utf-8',
+      timeout: 500,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      windowsHide: true,
+    });
+    if (ps.error) {
+      if (ps.error.code === 'ETIMEDOUT') return true;
+      continue;
+    }
+    if (isGitNexusServerCommand(ps.stdout || '')) return true;
+  }
+  return false;
+}
+
+/**
+ * @param {string} dbPath Absolute or relative path to the DB file (e.g. .../lbug).
+ * @param {number} myPid Current process PID (hook runner), excluded from matches.
+ */
+function hasGitNexusDbLockedByGitNexusServer(dbPath, myPid) {
+  if (!fs.existsSync(dbPath)) return false;
+  const dbPathAbs = path.resolve(dbPath);
+
+  if (process.platform === 'win32') {
+    return hasGitNexusServerOwnerWindows(dbPathAbs, myPid);
+  }
+
+  if (process.platform === 'linux') {
+    if (linuxProcScanFindGitNexusServer(dbPathAbs, myPid)) return true;
+    return unixLsofPsFindGitNexusServer(dbPathAbs, myPid);
+  }
+
+  return unixLsofPsFindGitNexusServer(dbPathAbs, myPid);
+}
+
+module.exports = {
+  hasGitNexusDbLockedByGitNexusServer,
+};

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

@@ -0,0 +1,119 @@
+const fs = require('fs');
+const path = require('path');
+
+const HOOK_LOCK_SUBDIR = '.hook-locks';
+const HOOK_LOCK_MAX_INFLIGHT = 3;
+const HOOK_LOCK_STALE_MS = 30000;
+
+function acquireHookSlot(gitNexusDir) {
+  const lockDir = path.join(gitNexusDir, HOOK_LOCK_SUBDIR);
+  try {
+    fs.mkdirSync(lockDir, { recursive: true });
+  } catch {
+    // Cannot create lock dir (read-only fs, cross-user perm denial, out of
+    // inodes, etc.) — fail closed by returning null. Caller skips augment.
+    // Fail-open here would let N concurrent hooks all proceed unguarded and
+    // reintroduce the #1486 fan-out the guard exists to prevent.
+    return null;
+  }
+
+  const myPidStr = String(process.pid);
+
+  for (let slot = 0; slot < HOOK_LOCK_MAX_INFLIGHT; slot++) {
+    const slotPath = path.join(lockDir, `slot-${slot}.lock`);
+    for (let attempt = 0; attempt < 2; attempt++) {
+      try {
+        fs.writeFileSync(slotPath, myPidStr, { flag: 'wx' });
+        let released = false;
+        const release = () => {
+          if (released) return;
+          released = true;
+          try {
+            // Only unlink if we still own the slot. If we appeared stale and
+            // another hook took over, the file now belongs to it — leave alone.
+            const content = fs.readFileSync(slotPath, 'utf-8').trim();
+            if (content === myPidStr) fs.unlinkSync(slotPath);
+          } catch {
+            /* already removed or unreadable */
+          }
+        };
+        process.on('exit', release);
+        return release;
+      } catch {
+        // Slot exists. Decide whether to take it over.
+        // Open once and inspect mtime + content via the same fd so there's
+        // no TOCTOU between the metadata check and the content read
+        // (codeql js/file-system-race).
+        let fd;
+        try {
+          fd = fs.openSync(slotPath, 'r');
+        } catch {
+          continue; // Vanished between EEXIST and open — retry this slot.
+        }
+        let isLive = false;
+        let mtimeMs = Date.now();
+        try {
+          mtimeMs = fs.fstatSync(fd).mtimeMs;
+          const buf = Buffer.alloc(32);
+          const n = fs.readSync(fd, buf, 0, 32, 0);
+          const ownerStr = buf.slice(0, n).toString('utf-8').trim();
+          if (ownerStr === '') {
+            // Owner created the file but hasn't written its PID yet. The
+            // wx open+write window is microseconds; give it the benefit
+            // of the doubt and treat as live.
+            isLive = true;
+          } else {
+            const owner = Number.parseInt(ownerStr, 10);
+            if (Number.isFinite(owner) && owner > 0) {
+              try {
+                process.kill(owner, 0);
+                isLive = true;
+              } catch (e) {
+                // ESRCH = process gone → treat as dead. EPERM = process exists
+                // but owned by another user (cross-user lock dir) → still alive,
+                // keep the slot. Anything else: be conservative, assume alive.
+                if (e && e.code === 'ESRCH') {
+                  isLive = false;
+                } else {
+                  isLive = true;
+                }
+              }
+            }
+          }
+        } catch {
+          /* unreadable — treat as dead */
+        } finally {
+          try {
+            fs.closeSync(fd);
+          } catch {
+            /* already closed */
+          }
+        }
+        // For slots younger than HOOK_LOCK_STALE_MS, PID-liveness wins —
+        // a slow-but-alive hook is never wrongly evicted. For older slots,
+        // age is the final arbiter as a defense against PID reuse on long-
+        // abandoned slots. 30s >> the 7s augment timeout, so a healthy run
+        // never crosses this threshold.
+        if (isLive && Date.now() - mtimeMs > HOOK_LOCK_STALE_MS) {
+          isLive = false;
+        }
+        if (isLive) break; // Try the next slot.
+        try {
+          fs.unlinkSync(slotPath);
+        } catch {
+          /* another hook beat us to it — retry will hit EEXIST */
+        }
+        // Loop and retry this slot.
+      }
+    }
+  }
+
+  return null;
+}
+
+module.exports = {
+  HOOK_LOCK_SUBDIR,
+  HOOK_LOCK_MAX_INFLIGHT,
+  HOOK_LOCK_STALE_MS,
+  acquireHookSlot,
+};

gitnexus-claude-plugin/hooks/win-rm-list-json.ps1

@@ -0,0 +1,76 @@
+$ErrorActionPreference = 'Stop'
+$target = $env:GITNEXUS_HOOK_RM_TARGET
+if ([string]::IsNullOrWhiteSpace($target)) { Write-Output '[]'; exit 0 }
+$target = (Resolve-Path -LiteralPath $target).ProviderPath
+
+if (-not ([Management.Automation.PSTypeName]'GitNexusHookRm.Native').Type) {
+Add-Type @'
+using System;
+using System.Runtime.InteropServices;
+namespace GitNexusHookRm {
+  public static class Native {
+    public const int ErrorMoreData = 234;
+    [StructLayout(LayoutKind.Sequential, Pack = 4)]
+    public struct RM_UNIQUE_PROCESS {
+      public int dwProcessId;
+      public long ProcessStartTime;
+    }
+    [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
+    public struct RM_PROCESS_INFO {
+      public RM_UNIQUE_PROCESS Process;
+      [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 256)]
+      public string strAppName;
+      [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 64)]
+      public string strServiceShortName;
+      public uint ApplicationType;
+      public uint AppStatus;
+      public uint TSSessionId;
+      public uint bRestartable;
+    }
+    [DllImport("rstrtmgr.dll", CharSet = CharSet.Unicode)]
+    public static extern int RmStartSession(out uint pSessionHandle, uint dwSessionFlags, string strSessionKey);
+    [DllImport("rstrtmgr.dll", CharSet = CharSet.Unicode)]
+    public static extern int RmRegisterResources(uint pSessionHandle, uint nFiles, string[] rgsFileNames, uint nApplications, IntPtr rgApplications, uint nServices, string[] rgsServiceNames);
+    [DllImport("rstrtmgr.dll")]
+    public static extern int RmGetList(uint dwSessionHandle, out uint pnProcInfoNeeded, ref uint pnProcInfo, [In, Out] RM_PROCESS_INFO[] rgAffectedApps, ref uint lpdwRebootReasons);
+    [DllImport("rstrtmgr.dll")]
+    public static extern int RmEndSession(uint pSessionHandle);
+  }
+}
+'@
+}
+
+$h = [uint32]0
+$key = [guid]::NewGuid().ToString('N')
+$rmErr = [GitNexusHookRm.Native]::RmStartSession([ref]$h, 0, $key)
+if ($rmErr -ne 0) { Write-Output '[]'; exit 0 }
+$files = @($target)
+$err = [GitNexusHookRm.Native]::RmRegisterResources($h, 1, $files, 0, [IntPtr]::Zero, 0, $null)
+if ($err -ne 0) {
+  [void][GitNexusHookRm.Native]::RmEndSession($h)
+  Write-Output '[]'
+  exit 0
+}
+$need = [uint32]0
+$n = [uint32]0
+$reboot = [uint32]0
+$err = [GitNexusHookRm.Native]::RmGetList($h, [ref]$need, [ref]$n, $null, [ref]$reboot)
+if ($err -ne [GitNexusHookRm.Native]::ErrorMoreData) {
+  [void][GitNexusHookRm.Native]::RmEndSession($h)
+  Write-Output '[]'
+  exit 0
+}
+$n = $need
+$buf = New-Object GitNexusHookRm.Native+RM_PROCESS_INFO[] ([int]$n)
+$err = [GitNexusHookRm.Native]::RmGetList($h, [ref]$need, [ref]$n, $buf, [ref]$reboot)
+[void][GitNexusHookRm.Native]::RmEndSession($h)
+if ($err -ne 0) { Write-Output '[]'; exit 0 }
+
+$out = @()
+for ($i = 0; $i -lt [int]$n; $i++) {
+  $procId = $buf[$i].Process.dwProcessId
+  $p = Get-CimInstance -ClassName Win32_Process -Filter "ProcessId=$procId" -ErrorAction SilentlyContinue
+  $cmd = if ($p) { $p.CommandLine } else { '' }
+  $out += [PSCustomObject]@{ pid = [int]$procId; cmd = $cmd }
+}
+ConvertTo-Json -InputObject @($out) -Compress

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

@@ -56,13 +56,15 @@ Generates repository documentation from the knowledge graph using an LLM. Requir
 
 | Flag | Effect |
 |------|--------|
-| `--force` | Force full regeneration |
+| `--force` | Force full regeneration, also required to re-gerenate an existing wiki in a different language |
 | `--model <model>` | LLM model (default: minimax/minimax-m2.5) |
 | `--base-url <url>` | LLM API base URL |
 | `--api-key <key>` | LLM API key |
 | `--concurrency <n>` | Parallel LLM calls (default: 3) |
 | `--gist` | Publish wiki as a public GitHub Gist |
-
+| `--timeout <seconds>` | LLM request timeout in seconds (default: disabled) |
+| `--retries <n>` | Max LLM retry attempts per request (default: 3) |
+| `--lang <lang>`  | Output language for generated documentation (e.g. english, chinese, spanish, japanese)|
 ### list — Show all indexed repos
 
 ```bash

gitnexus-cursor-integration/README.md

@@ -10,20 +10,21 @@ Static config that adds GitNexus knowledge-graph augmentation and skill files to
 | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
 | **MCP**                   | `gitnexus` MCP server with 16 tools (`query`, `context`, `impact`, `detect_changes`, `rename`, …)                                         | `npx gitnexus setup` writes `~/.cursor/mcp.json` automatically.                 |
 | **Skills**                | `/gitnexus-exploring`, `/gitnexus-debugging`, `/gitnexus-impact-analysis`, `/gitnexus-refactoring`, `/gitnexus-pr-review` markdown skills | `npx gitnexus setup` copies them to `~/.cursor/skills/gitnexus/`.               |
-| **Hooks** _(this README)_ | `postToolUse` hook that enriches `Shell` / `Read` / `Grep` tool calls with graph context — same augmentation Claude Code gets             | **Manual** — copy the two files described below into your project's `.cursor/`. |
+| **Hooks** _(this README)_ | `postToolUse` hook that enriches `Shell` / `Read` / `Grep` tool calls with graph context — same augmentation Claude Code gets             | **Manual** — copy the files described below into your project's `.cursor/`. |
 
 ## Hook install
 
 Cursor 2.4+ reads `.cursor/hooks.json` from the project root and runs hook commands with the project root as the working directory ([docs](https://cursor.com/docs/agent/hooks)).
 
-From this repo's `gitnexus-cursor-integration/hooks/`, copy the two files into your **project root**:
+From this repo's `gitnexus-cursor-integration/hooks/`, copy the files below into your **project root**:
 
 ```text
 <your-project>/
 ├── .cursor/
 │   └── hooks.json              ← from gitnexus-cursor-integration/hooks/hooks.json
 └── hooks/
-    └── gitnexus-hook.cjs       ← from gitnexus-cursor-integration/hooks/gitnexus-hook.cjs
+    ├── gitnexus-hook.cjs       ← from gitnexus-cursor-integration/hooks/gitnexus-hook.cjs
+    └── hook-lock.cjs           ← from gitnexus-cursor-integration/hooks/hook-lock.cjs
 ```
 
 Equivalent shell commands (run from your project root, with `$GITNEXUS_REPO` pointing at a clone of this repo):
@@ -32,6 +33,7 @@ Equivalent shell commands (run from your project root, with `$GITNEXUS_REPO` poi
 mkdir -p .cursor hooks
 cp "$GITNEXUS_REPO/gitnexus-cursor-integration/hooks/hooks.json"        .cursor/hooks.json
 cp "$GITNEXUS_REPO/gitnexus-cursor-integration/hooks/gitnexus-hook.cjs" hooks/gitnexus-hook.cjs
+cp "$GITNEXUS_REPO/gitnexus-cursor-integration/hooks/hook-lock.cjs"     hooks/hook-lock.cjs
 ```
 
 If you already have a `.cursor/hooks.json`, merge the `hooks.postToolUse` array rather than overwriting.
@@ -49,7 +51,7 @@ If you already have a `.cursor/hooks.json`, merge the `hooks.postToolUse` array
 | -------------------------------------------------------------------- | ------------------------------ |
 | `~/.cursor/mcp.json`                                                 | ✅                             |
 | `~/.cursor/skills/gitnexus/*`                                        | ✅                             |
-| `<project>/.cursor/hooks.json` + `<project>/hooks/gitnexus-hook.cjs` | ❌ — copy manually (see above) |
+| `<project>/.cursor/hooks.json` + `<project>/hooks/gitnexus-hook.cjs` + `<project>/hooks/hook-lock.cjs` | ❌ — copy manually (see above) |
 
 Hook install is per-project (Cursor scopes hooks to a project root); skills and MCP config are global.
 
@@ -84,6 +86,6 @@ Empty stdout means "no augmentation, continue normally" — the hook never block
 
 ## Troubleshooting
 
-- **Nothing happens** — Confirm Cursor is on 2.4+ and the project root has both `.cursor/hooks.json` and the script at `hooks/gitnexus-hook.cjs`. Then `npx gitnexus list` to confirm the project is indexed.
+- **Nothing happens** — Confirm Cursor is on 2.4+ and the project root has `.cursor/hooks.json` plus both hook files at `hooks/gitnexus-hook.cjs` and `hooks/hook-lock.cjs`. Then `npx gitnexus list` to confirm the project is indexed.
 - **`gitnexus` not found** — The hook prefers a locally-resolvable `gitnexus/dist/cli/index.js` and falls back to `npx -y gitnexus`. Install globally with `npm i -g gitnexus` to skip the npx cold-start latency.
 - **Wrong pattern extracted** — Set `GITNEXUS_DEBUG=1` and run a tool call. The raw stdin payload is logged to stderr; use it to confirm Cursor's actual `tool_input` field names against the table above. If they differ, file an issue with the captured payload.

gitnexus-cursor-integration/hooks/gitnexus-hook.cjs

@@ -18,6 +18,7 @@
 const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
+const { acquireHookSlot } = require('./hook-lock.cjs');
 
 function readInput() {
   try {
@@ -57,6 +58,7 @@ function findCanonicalRepoRoot(cwd) {
       timeout: 2000,
       cwd,
       stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true,
     });
     if (result.error || result.status !== 0) return null;
     const commonDir = (result.stdout || '').trim();
@@ -200,6 +202,7 @@ function runGitNexusCli(cliPath, args, cwd, timeout) {
       timeout,
       cwd,
       stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true,
     });
   }
   return spawnSync(isWin ? 'npx.cmd' : 'npx', ['-y', 'gitnexus', ...args], {
@@ -207,6 +210,7 @@ function runGitNexusCli(cliPath, args, cwd, timeout) {
     timeout: timeout + 5000,
     cwd,
     stdio: ['pipe', 'pipe', 'pipe'],
+    windowsHide: true,
   });
 }
 
@@ -227,7 +231,8 @@ function main() {
     }
     const cwd = input.cwd || process.cwd();
     if (!path.isAbsolute(cwd)) return;
-    if (!findGitNexusDir(cwd)) return;
+    const gitNexusDir = findGitNexusDir(cwd);
+    if (!gitNexusDir) return;
 
     const toolName = input.tool_name || '';
     const toolInput = input.tool_input || {};
@@ -235,6 +240,9 @@ function main() {
     const pattern = extractPattern(toolName, toolInput);
     if (!pattern || pattern.length < 3) return;
 
+    const release = acquireHookSlot(gitNexusDir);
+    if (!release) return;
+
     const cliPath = resolveCliPath();
     let result = '';
     try {
@@ -244,6 +252,8 @@ function main() {
       }
     } catch {
       /* graceful failure */
+    } finally {
+      release();
     }
 
     if (result && result.trim()) {

gitnexus-cursor-integration/hooks/hook-lock.cjs

@@ -0,0 +1,119 @@
+const fs = require('fs');
+const path = require('path');
+
+const HOOK_LOCK_SUBDIR = '.hook-locks';
+const HOOK_LOCK_MAX_INFLIGHT = 3;
+const HOOK_LOCK_STALE_MS = 30000;
+
+function acquireHookSlot(gitNexusDir) {
+  const lockDir = path.join(gitNexusDir, HOOK_LOCK_SUBDIR);
+  try {
+    fs.mkdirSync(lockDir, { recursive: true });
+  } catch {
+    // Cannot create lock dir (read-only fs, cross-user perm denial, out of
+    // inodes, etc.) — fail closed by returning null. Caller skips augment.
+    // Fail-open here would let N concurrent hooks all proceed unguarded and
+    // reintroduce the #1486 fan-out the guard exists to prevent.
+    return null;
+  }
+
+  const myPidStr = String(process.pid);
+
+  for (let slot = 0; slot < HOOK_LOCK_MAX_INFLIGHT; slot++) {
+    const slotPath = path.join(lockDir, `slot-${slot}.lock`);
+    for (let attempt = 0; attempt < 2; attempt++) {
+      try {
+        fs.writeFileSync(slotPath, myPidStr, { flag: 'wx' });
+        let released = false;
+        const release = () => {
+          if (released) return;
+          released = true;
+          try {
+            // Only unlink if we still own the slot. If we appeared stale and
+            // another hook took over, the file now belongs to it — leave alone.
+            const content = fs.readFileSync(slotPath, 'utf-8').trim();
+            if (content === myPidStr) fs.unlinkSync(slotPath);
+          } catch {
+            /* already removed or unreadable */
+          }
+        };
+        process.on('exit', release);
+        return release;
+      } catch {
+        // Slot exists. Decide whether to take it over.
+        // Open once and inspect mtime + content via the same fd so there's
+        // no TOCTOU between the metadata check and the content read
+        // (codeql js/file-system-race).
+        let fd;
+        try {
+          fd = fs.openSync(slotPath, 'r');
+        } catch {
+          continue; // Vanished between EEXIST and open — retry this slot.
+        }
+        let isLive = false;
+        let mtimeMs = Date.now();
+        try {
+          mtimeMs = fs.fstatSync(fd).mtimeMs;
+          const buf = Buffer.alloc(32);
+          const n = fs.readSync(fd, buf, 0, 32, 0);
+          const ownerStr = buf.slice(0, n).toString('utf-8').trim();
+          if (ownerStr === '') {
+            // Owner created the file but hasn't written its PID yet. The
+            // wx open+write window is microseconds; give it the benefit
+            // of the doubt and treat as live.
+            isLive = true;
+          } else {
+            const owner = Number.parseInt(ownerStr, 10);
+            if (Number.isFinite(owner) && owner > 0) {
+              try {
+                process.kill(owner, 0);
+                isLive = true;
+              } catch (e) {
+                // ESRCH = process gone → treat as dead. EPERM = process exists
+                // but owned by another user (cross-user lock dir) → still alive,
+                // keep the slot. Anything else: be conservative, assume alive.
+                if (e && e.code === 'ESRCH') {
+                  isLive = false;
+                } else {
+                  isLive = true;
+                }
+              }
+            }
+          }
+        } catch {
+          /* unreadable — treat as dead */
+        } finally {
+          try {
+            fs.closeSync(fd);
+          } catch {
+            /* already closed */
+          }
+        }
+        // For slots younger than HOOK_LOCK_STALE_MS, PID-liveness wins —
+        // a slow-but-alive hook is never wrongly evicted. For older slots,
+        // age is the final arbiter as a defense against PID reuse on long-
+        // abandoned slots. 30s >> the 7s augment timeout, so a healthy run
+        // never crosses this threshold.
+        if (isLive && Date.now() - mtimeMs > HOOK_LOCK_STALE_MS) {
+          isLive = false;
+        }
+        if (isLive) break; // Try the next slot.
+        try {
+          fs.unlinkSync(slotPath);
+        } catch {
+          /* another hook beat us to it — retry will hit EEXIST */
+        }
+        // Loop and retry this slot.
+      }
+    }
+  }
+
+  return null;
+}
+
+module.exports = {
+  HOOK_LOCK_SUBDIR,
+  HOOK_LOCK_MAX_INFLIGHT,
+  HOOK_LOCK_STALE_MS,
+  acquireHookSlot,
+};

gitnexus-shared/src/index.ts

@@ -18,7 +18,11 @@ export type { NodeTableName, RelType } from './lbug/schema-constants.js';
 
 // Language support
 export { SupportedLanguages } from './languages.js';
-export { getLanguageFromFilename, getSyntaxLanguageFromFilename } from './language-detection.js';
+export {
+  getLanguageFromFilename,
+  getSyntaxLanguageFromFilename,
+  isBladeTemplateFilename,
+} from './language-detection.js';
 export type { MroStrategy } from './mro-strategy.js';
 
 // Pipeline progress
@@ -26,7 +30,7 @@ export type { PipelinePhase, PipelineProgress } from './pipeline.js';
 
 // ─── Scope-based resolution — RFC #909 (Ring 1 #910) ────────────────────────
 // Data model (RFC §2)
-export type { SymbolDefinition } from './scope-resolution/symbol-definition.js';
+export type { ParameterTypeClass, SymbolDefinition } from './scope-resolution/symbol-definition.js';
 export type {
   ScopeId,
   DefId,
@@ -127,8 +131,10 @@ export { CLASS_KINDS, METHOD_KINDS, FIELD_KINDS } from './scope-resolution/regis
 export type {
   RegistryContext,
   RegistryProviders,
+  OwnedMembersByOwnerLookup,
   OwnerScopedContributor,
   ArityVerdict,
+  ConstraintContext,
 } from './scope-resolution/registries/context.js';
 
 // Scope tree spine + position lookup (RFC §2.2 + §3.1; Ring 2 SHARED #912)

gitnexus-shared/src/language-detection.ts

@@ -56,11 +56,21 @@ for (const [lang, exts] of Object.entries(EXTENSION_MAP) as [
   }
 }
 
+/**
+ * Laravel Blade templates are source templates whose filename convention ends
+ * in `.blade.php`.  They may contain PHP snippets, but the full file is not a
+ * pure PHP translation unit and must not enter the generic PHP provider path.
+ */
+export const isBladeTemplateFilename = (filePath: string): boolean =>
+  filePath.replace(/\\/g, '/').toLowerCase().endsWith('.blade.php');
+
 /**
  * Map file extension to SupportedLanguage enum.
  * Returns null if the file extension is not recognized.
  */
 export const getLanguageFromFilename = (filename: string): SupportedLanguages | null => {
+  if (isBladeTemplateFilename(filename)) return null;
+
   // Fast path: check the extension map
   const lastDot = filename.lastIndexOf('.');
   if (lastDot >= 0) {
@@ -138,6 +148,8 @@ const AUXILIARY_BASENAME_MAP: Record<string, string> = {
  * Returns 'text' for unrecognised files.
  */
 export const getSyntaxLanguageFromFilename = (filePath: string): string => {
+  if (isBladeTemplateFilename(filePath)) return 'markup';
+
   const lang = getLanguageFromFilename(filePath);
   if (lang) return SYNTAX_MAP[lang];
   const ext = filePath.split('.').pop()?.toLowerCase();

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

@@ -833,7 +833,16 @@ function expandWildcard(
   if (target === undefined) return [edge];
 
   const names = hooks.expandsWildcardTo(edge.targetModuleScope, workspace);
-  if (names.length === 0) return [];
+  if (names.length === 0) {
+    // Resolved wildcard with zero propagating names is still a real file-
+    // level dependency (e.g. a C++ header that only declares classes —
+    // `#include` is a valid IMPORTS edge, but unqualified-binding names
+    // are correctly empty since class methods require `Class::method`).
+    // Preserve the original wildcard edge so the file→file IMPORTS edge
+    // survives; downstream binding materialization sees no propagated
+    // names because the edge has no `targetExportedName`/`localName`.
+    return [edge];
+  }
 
   const expanded: ImportEdge[] = [];
   for (const name of names) {

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

@@ -21,6 +21,7 @@
  * (defined in `./types.ts`).
  */
 
+import type { ParameterTypeClass } from './symbol-definition.js';
 import type { Range, ScopeId } from './types.js';
 
 /**
@@ -79,4 +80,11 @@ export interface ReferenceSite {
    * (C#: `42` → `'int'`, `"alice"` → `'string'`).
    */
   readonly argumentTypes?: readonly string[];
+  /**
+   * Optional per-argument type-shape sidecar for languages that need
+   * cv/ref/pointer distinctions during constraint filtering. This is
+   * intentionally separate from `argumentTypes`, which stays normalized
+   * for existing overload narrowing and conversion-rank logic.
+   */
+  readonly argumentTypeClasses?: readonly ParameterTypeClass[];
 }

gitnexus-shared/src/scope-resolution/registries/context.ts

@@ -13,7 +13,7 @@
  */
 
 import type { NodeLabel } from '../../graph/types.js';
-import type { SymbolDefinition } from '../symbol-definition.js';
+import type { ParameterTypeClass, SymbolDefinition } from '../symbol-definition.js';
 import type { Callsite, DefId } from '../types.js';
 import type { DefIndex } from '../def-index.js';
 import type { QualifiedNameIndex } from '../qualified-name-index.js';
@@ -30,10 +30,50 @@ export interface RegistryProviders {
    * when absent, every candidate receives `'unknown'` (neutral signal).
    */
   arityCompatibility?(callsite: Callsite, def: SymbolDefinition): ArityVerdict;
+
+  /**
+   * Language-specific constraint compatibility between a callsite and a
+   * candidate `def`. Mirrors `arityCompatibility` and shares its three-valued
+   * verdict shape; the third value `'unknown'` MUST keep the candidate
+   * (monotonicity: adding a predicate can only narrow correctly, never
+   * produce a wrong edge). Consulted by `narrowOverloadCandidates` after
+   * arity + type filters when a candidate carries `templateConstraints`.
+   *
+   * Optional; when absent the constraint filter is a pass-through. Languages
+   * with no constrained-overload semantics leave this undefined.
+   */
+  constraintCompatibility?(
+    callsite: Callsite,
+    def: SymbolDefinition,
+    ctx: ConstraintContext,
+  ): ArityVerdict;
 }
 
 export type ArityVerdict = 'compatible' | 'unknown' | 'incompatible';
 
+/**
+ * Context threaded into `constraintCompatibility`. Kept minimal in the
+ * Tier-A scope (only `argumentTypes`, riding here until a separate
+ * `Callsite`-widening refactor moves them onto the call site directly).
+ * Future Tier-B graph-aware predicates (`is_base_of_v`, etc.) will widen
+ * this interface with `lookupTypeByName` and similar helpers.
+ */
+export interface ConstraintContext {
+  /**
+   * Per-slot argument types at the call site, normalized per the language
+   * adapter. Empty string means unknown. Same convention as
+   * `narrowOverloadCandidates`' `argTypes` parameter.
+   */
+  readonly argumentTypes?: readonly string[];
+  /**
+   * Optional shape-preserving sidecar aligned with `argumentTypes`.
+   * Unknown or unsupported slots should be omitted by producers or
+   * marked with `indirection: 'unknown'`; consumers must preserve the
+   * monotonic fallback and return 'unknown' instead of guessing.
+   */
+  readonly argumentTypeClasses?: readonly ParameterTypeClass[];
+}
+
 // ─── Owner-scoped contributor (concrete shape for `RegistryContributor`) ────
 
 /**
@@ -60,6 +100,19 @@ export interface OwnerScopedContributor {
   byName(name: string): readonly SymbolDefinition[];
 }
 
+/**
+ * Required owner-keyed lookup hook for Step 2 receiver/MRO member walks.
+ * Production callers wire this to the SemanticModel's authoritative
+ * method/field/nested-type registries so each `(ownerDefId, memberName)`
+ * probe is O(1). Implementations MUST return `[]` on an indexed miss —
+ * Step 2 treats `[]` as authoritative and does not consult `defs` for a
+ * fallback scan.
+ */
+export type OwnedMembersByOwnerLookup = (
+  ownerDefId: DefId,
+  memberName: string,
+) => readonly SymbolDefinition[];
+
 // ─── Top-level context threaded through every lookup ───────────────────────
 
 export interface RegistryContext {
@@ -67,6 +120,7 @@ export interface RegistryContext {
   readonly defs: DefIndex;
   readonly qualifiedNames: QualifiedNameIndex;
   readonly moduleScopes: ModuleScopeIndex;
+  readonly ownedMembersByOwner: OwnedMembersByOwnerLookup;
   /**
    * Method-dispatch index; required for method/field registries that
    * honor `useReceiverTypeBinding`. Omit for class-only lookups.

gitnexus-shared/src/scope-resolution/registries/lookup-core.ts

@@ -27,8 +27,10 @@
  *   is true, resolve the receiver's type at `startScope` (from
  *   `scope.typeBindings`), then walk the MRO via
  *   `MethodDispatchIndex.mroFor(ownerDefId)`. Membership per owner comes
- *   through `RegistryContext.methodDispatch` + owner lookups into
- *   `scope.ownedDefs`; each hit records a raw signal with the owner's
+ *   through an optional `RegistryContext.ownedMembersByOwner` hook when
+ *   supplied (`undefined` → fall back to `defs.byId`; `[]` → indexed
+ *   miss), otherwise via the compatibility fallback scan over
+ *   `defs.byId`; each hit records a raw signal with the owner's
  *   MRO depth.
  *
  * **Step 3 — Owner-scoped contributor.** When
@@ -263,13 +265,14 @@ function walkReceiverTypeBinding(
   // Walk the owner itself at depth 0, then its MRO chain.
   const walk: DefId[] = [ownerDefId, ...ctx.methodDispatch.mroFor(ownerDefId)];
 
-  for (let mroDepth = 0; mroDepth < walk.length; mroDepth++) {
-    const currentOwnerId = walk[mroDepth]!;
+  let mroDepth = 0;
+  for (const currentOwnerId of walk) {
     const members = collectOwnedMembers(currentOwnerId, name, ctx);
     for (const def of members) {
       if (!acceptedKinds.has(def.type)) continue;
       recordTypeBindingHit(perCandidate, def, mroDepth, ownerDefId);
     }
+    mroDepth++;
   }
 }
 
@@ -333,23 +336,7 @@ function collectOwnedMembers(
   memberName: string,
   ctx: RegistryContext,
 ): readonly SymbolDefinition[] {
-  // An owner's members are defs whose `ownerId === ownerDefId` and whose
-  // simple name matches `memberName`. We iterate `defs.byId` — O(D) per
-  // call today. A future by-owner index would make this O(K); tracked as
-  // a follow-up optimization before Ring 3 flips go production.
-  const out: SymbolDefinition[] = [];
-  for (const def of ctx.defs.byId.values()) {
-    if (def.ownerId !== ownerDefId) continue;
-    if (simpleNameOf(def) !== memberName) continue;
-    out.push(def);
-  }
-  return out;
-}
-
-function simpleNameOf(def: SymbolDefinition): string | undefined {
-  if (def.qualifiedName === undefined || def.qualifiedName.length === 0) return undefined;
-  const dot = def.qualifiedName.lastIndexOf('.');
-  return dot === -1 ? def.qualifiedName : def.qualifiedName.slice(dot + 1);
+  return ctx.ownedMembersByOwner(ownerDefId, memberName);
 }
 
 function recordTypeBindingHit(

gitnexus-shared/src/scope-resolution/symbol-definition.ts

@@ -11,6 +11,17 @@
 
 import type { NodeLabel } from '../graph/types.js';
 
+export interface ParameterTypeClass {
+  /** Normalized base type, matching the coarse `parameterTypes` vocabulary when known. */
+  base: string;
+  /** Top-level cv signal preserved from the original C++ parameter spelling. */
+  cv: 'none' | 'const' | 'volatile' | 'const volatile' | 'unknown';
+  /** Coarse value/reference/pointer shape. */
+  indirection: 'value' | 'lvalue-ref' | 'rvalue-ref' | 'pointer' | 'unknown';
+  /** Number of pointer markers when indirection is `pointer`; otherwise 0. */
+  pointerDepth: number;
+}
+
 export interface SymbolDefinition {
   nodeId: string;
   filePath: string;
@@ -26,10 +37,22 @@ export interface SymbolDefinition {
   /** Per-parameter type names for overload disambiguation (e.g. ['int', 'String']).
    *  Populated when parameter types are resolvable from AST (any typed language). */
   parameterTypes?: string[];
+  /** Additive per-parameter type shape sidecar for languages that need cv/ref/pointer distinctions.
+   *  Does not participate in graph node identity unless a resolver explicitly opts in. */
+  parameterTypeClasses?: ParameterTypeClass[];
   /** Raw return type text extracted from AST (e.g. 'User', 'Promise<User>') */
   returnType?: string;
   /** Declared type for non-callable symbols — fields/properties (e.g. 'Address', 'List<User>') */
   declaredType?: string;
+  /** Generic/template specialization arguments for class-like symbols (e.g. ['User'], ['T*']). */
+  templateArguments?: string[];
+  /** Per-language constraint payload for template / generic overloads
+   *  (e.g. C++ `enable_if_t<P, T>` predicate trees, C++20 `requires` clauses).
+   *  Opaque to shared code — the producing language adapter owns the shape
+   *  and is the only consumer. Read via the optional
+   *  `ScopeResolver.constraintCompatibility` hook during overload narrowing.
+   *  Absent for symbols that have no constraints (the common case). */
+  templateConstraints?: unknown;
   /** Links Method/Constructor/Property to owning Class/Struct/Trait nodeId */
   ownerId?: string;
 }

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

@@ -0,0 +1,71 @@
+import { test, expect, type Page } from '@playwright/test';
+
+const BACKEND_URL = 'http://localhost:4747';
+const REPO_NAME = 'mock-repo';
+
+async function mockBackend(page: Page) {
+  const repo = {
+    name: REPO_NAME,
+    path: '/tmp/mock-repo',
+    repoPath: '/tmp/mock-repo',
+    indexedAt: new Date().toISOString(),
+    stats: { files: 1, nodes: 0, edges: 0, processes: 0 },
+  };
+
+  await page.route(
+    (url) => url.origin === BACKEND_URL && url.pathname === '/api/repos',
+    (route) => route.fulfill({ json: [repo] }),
+  );
+  await page.route(
+    (url) => url.origin === BACKEND_URL && url.pathname === '/api/repo',
+    (route) => route.fulfill({ json: repo }),
+  );
+  await page.route(
+    (url) => url.origin === BACKEND_URL && url.pathname === '/api/graph',
+    (route) => route.fulfill({ json: { nodes: [], relationships: [] } }),
+  );
+  await page.route(
+    (url) => url.origin === BACKEND_URL && url.pathname === '/api/heartbeat',
+    (route) =>
+      route.fulfill({
+        status: 200,
+        headers: { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache' },
+        body: ':ok\n\n',
+      }),
+  );
+}
+
+async function enterExploringView(page: Page) {
+  await page.goto('/');
+  await page.locator('[data-testid="landing-repo-card"]').first().click();
+  await expect(page.getByTestId('language-switcher')).toBeVisible({ timeout: 20_000 });
+}
+
+test.describe('language switching', () => {
+  test('switches Header language, updates document metadata, and persists after reload', async ({
+    page,
+  }) => {
+    await mockBackend(page);
+    await page.goto('/');
+    await page.evaluate(() => window.localStorage.clear());
+
+    await enterExploringView(page);
+
+    await page.getByTestId('language-switcher').selectOption('zh-CN');
+
+    await expect(page.locator('html')).toHaveAttribute('lang', 'zh-CN');
+    await expect(page.getByText('觉得不错就点星')).toBeVisible();
+    await expect
+      .poll(() => page.evaluate(() => window.localStorage.getItem('gitnexus.lng')))
+      .toBe('zh-CN');
+
+    await page.reload();
+
+    await expect(page.getByTestId('language-switcher')).toHaveValue('zh-CN', { timeout: 20_000 });
+    await expect(page.locator('html')).toHaveAttribute('lang', 'zh-CN');
+    await expect(page.getByText('觉得不错就点星')).toBeVisible();
+
+    await page.getByTestId('language-switcher').selectOption('en');
+    await expect(page.locator('html')).toHaveAttribute('lang', 'en');
+  });
+});

gitnexus-web/package.json

@@ -18,40 +18,43 @@
     "test:e2e:report": "playwright show-report"
   },
   "dependencies": {
-    "gitnexus-shared": "file:../gitnexus-shared",
     "@langchain/anthropic": "^1.3.29",
     "@langchain/core": "^1.1.44",
-    "@langchain/google-genai": "^2.1.28",
+    "@langchain/google-genai": "^2.1.30",
     "@langchain/langgraph": "^1.2.9",
     "@langchain/ollama": "^1.2.6",
     "@langchain/openai": "^1.4.5",
     "@sigma/edge-curve": "^3.1.0",
-    "@tailwindcss/vite": "^4.2.4",
+    "@tailwindcss/vite": "^4.3.0",
     "axios": "^1.16.0",
     "d3": "^7.9.0",
-    "dompurify": "^3.4.2",
+    "dompurify": "^3.4.3",
+    "gitnexus-shared": "file:../gitnexus-shared",
     "graphology": "^0.26.0",
     "graphology-indices": "^0.17.0",
     "graphology-layout-force": "^0.2.4",
     "graphology-layout-forceatlas2": "^0.10.1",
     "graphology-layout-noverlap": "^0.4.2",
     "graphology-utils": "^2.3.0",
+    "i18next": "^26.2.0",
+    "i18next-browser-languagedetector": "^8.2.1",
     "langchain": "^1.3.5",
     "lru-cache": "^11.2.4",
     "lucide-react": "^1.14.0",
-    "mermaid": "^11.14.0",
+    "mermaid": "^11.15.0",
     "mnemonist": "^0.39.0",
     "pandemonium": "^2.4.0",
     "react": "^19.2.5",
     "react-dom": "^19.2.6",
+    "react-i18next": "^17.0.8",
     "react-markdown": "^10.1.0",
-    "react-syntax-highlighter": "^16.1.0",
+    "react-syntax-highlighter": "^16.1.1",
     "react-zoom-pan-pinch": "^4.0.3",
     "remark-gfm": "^4.0.1",
     "sigma": "^3.0.2",
     "tailwindcss": "^4.2.4",
     "uuid": "^14.0.0",
-    "zod": "^3.25.76"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@babel/types": "^7.29.0",
@@ -64,14 +67,27 @@
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@types/react-syntax-highlighter": "^15.5.13",
-    "@vercel/node": "^5.5.16",
+    "@vercel/node": "^5.8.2",
     "@vitejs/plugin-react": "^5.1.4",
     "@vitest/coverage-v8": "^4.1.5",
     "jsdom": "^29.1.1",
     "tree-sitter-wasms": "^0.1.13",
     "typescript": "^5.4.5",
-    "vite": "^8.0.10",
+    "vite": "^8.0.11",
     "vitest": "^4.1.5",
     "wait-on": "^9.0.5"
+  },
+  "overrides": {
+    "@vercel/static-config": {
+      "ajv": "8.18.0"
+    },
+    "@vercel/node": {
+      "path-to-regexp": "6.3.0",
+      "undici": "6.24.0"
+    },
+    "@vercel/python-analysis": {
+      "minimatch": "10.2.3",
+      "smol-toml": "1.6.1"
+    }
   }
 }

gitnexus-web/src/App.tsx

@@ -21,8 +21,11 @@ import {
   type BackendRepo,
 } from './services/backend-client';
 import { ERROR_RESET_DELAY_MS } from './config/ui-constants';
+import { formatBackendError } from './i18n/error-messages';
+import { useTranslation } from 'react-i18next';
 
 const AppContent = () => {
+  const { t } = useTranslation(['common', 'errors']);
   const {
     viewMode,
     setViewMode,
@@ -54,7 +57,6 @@ const AppContent = () => {
     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 =
@@ -104,6 +106,11 @@ const AppContent = () => {
 
   // Auto-connect when ?server or ?project query param is present (bookmarkable shortcut)
   const autoConnectRan = useRef(false);
+  const tRef = useRef(t);
+  useEffect(() => {
+    tRef.current = t;
+  }, [t]);
+
   useEffect(() => {
     if (autoConnectRan.current) return;
     const params = new URLSearchParams(window.location.search);
@@ -116,8 +123,8 @@ const AppContent = () => {
     setProgress({
       phase: 'extracting',
       percent: 0,
-      message: 'Connecting to server...',
-      detail: 'Validating server',
+      message: tRef.current('common:progress.connecting'),
+      detail: tRef.current('common:progress.validatingServer'),
     });
     setViewMode('loading');
 
@@ -132,8 +139,8 @@ const AppContent = () => {
             setProgress({
               phase: 'extracting',
               percent: 5,
-              message: 'Connecting to server...',
-              detail: 'Validating server',
+              message: tRef.current('common:progress.connecting'),
+              detail: tRef.current('common:progress.validatingServer'),
             });
           } else if (phase === 'downloading') {
             const pct = total ? Math.round((downloaded / total) * 90) + 5 : 50;
@@ -141,15 +148,15 @@ const AppContent = () => {
             setProgress({
               phase: 'extracting',
               percent: pct,
-              message: 'Downloading graph...',
-              detail: `${mb} MB downloaded`,
+              message: tRef.current('common:progress.downloadingGraph'),
+              detail: tRef.current('common:progress.downloadedMb', { mb }),
             });
           } else if (phase === 'extracting') {
             setProgress({
               phase: 'extracting',
               percent: 97,
-              message: 'Processing...',
-              detail: 'Extracting file contents',
+              message: tRef.current('common:progress.processing'),
+              detail: tRef.current('common:progress.extractingFileContents'),
             });
           }
         },
@@ -173,8 +180,8 @@ const AppContent = () => {
         setProgress({
           phase: 'error',
           percent: 0,
-          message: 'Failed to connect to server',
-          detail: err instanceof Error ? err.message : 'Unknown error',
+          message: tRef.current('errors:connectFailed'),
+          detail: formatBackendError(err, tRef.current),
         });
         setTimeout(() => {
           setViewMode('onboarding');
@@ -299,7 +306,7 @@ const AppContent = () => {
 
       {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;
+          {t('errors:backend.reconnecting')}
         </div>
       )}
 

gitnexus-web/src/components/AnalyzeOnboarding.tsx

@@ -17,6 +17,7 @@
 
 import { Sparkles, Github } from '@/lib/lucide-icons';
 import { RepoAnalyzer } from './RepoAnalyzer';
+import { useTranslation } from 'react-i18next';
 
 interface AnalyzeOnboardingProps {
   /** Called when analysis finishes and the repo is ready to load. */
@@ -24,6 +25,8 @@ interface AnalyzeOnboardingProps {
 }
 
 export const AnalyzeOnboarding = ({ onComplete }: AnalyzeOnboardingProps) => {
+  const { t } = useTranslation('onboarding');
+
   return (
     <div className="relative animate-fade-in overflow-hidden rounded-3xl border border-border-default bg-surface p-7">
       {/* Ambient glows — mirrors OnboardingGuide aesthetic */}
@@ -47,11 +50,10 @@ export const AnalyzeOnboarding = ({ onComplete }: AnalyzeOnboardingProps) => {
           </div>
 
           <h2 className="text-lg leading-snug font-semibold text-text-primary">
-            Analyze your first repository
+            {t('analyzeFirst.title')}
           </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.
+            {t('analyzeFirst.description')}
           </p>
         </div>
       </div>
@@ -63,7 +65,7 @@ export const AnalyzeOnboarding = ({ onComplete }: AnalyzeOnboardingProps) => {
 
       {/* 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
+        {t('analyzeFirst.footer')}
       </p>
     </div>
   );

gitnexus-web/src/components/AnalyzeProgress.tsx

@@ -1,33 +1,16 @@
 import { useState, useEffect } from 'react';
 import { X } from '@/lib/lucide-icons';
 import type { JobProgress as AnalyzeJobProgress } from '../services/backend-client';
+import { useTranslation } from 'react-i18next';
+import { translateAnalyzePhase } from '../i18n/progress';
 
 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 { t } = useTranslation('common');
   const [startTime] = useState(() => Date.now());
   const [elapsed, setElapsed] = useState(0);
 
@@ -38,11 +21,11 @@ export const AnalyzeProgress = ({ progress, onCancel }: AnalyzeProgressProps) =>
 
   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`;
+    if (s < 60) return t('units.elapsedSeconds', { seconds: s });
+    return t('units.elapsedMinutesSeconds', { minutes: Math.floor(s / 60), seconds: s % 60 });
   };
 
-  const label = PHASE_LABELS[progress.phase] || progress.message || progress.phase;
+  const label = translateAnalyzePhase(progress.phase, progress.message, t);
   const pct = Math.max(0, Math.min(100, progress.percent));
 
   return (
@@ -69,7 +52,7 @@ export const AnalyzeProgress = ({ progress, onCancel }: AnalyzeProgressProps) =>
           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
+          {t('actions.cancel')}
         </button>
       </div>
     </div>

gitnexus-web/src/components/CodeReferencesPanel.tsx

@@ -17,6 +17,7 @@ import { useAppState } from '../hooks/useAppState';
 import { type GraphNode, getSyntaxLanguageFromFilename } from 'gitnexus-shared';
 import { NODE_COLORS } from '../lib/constants';
 import { readFile, type ReadFileResult } from '../services/backend-client';
+import { useTranslation } from 'react-i18next';
 
 const getSyntaxLanguage = (filePath: string | undefined): string => {
   if (!filePath) return 'text';
@@ -46,6 +47,7 @@ export interface CodeReferencesPanelProps {
 }
 
 export const CodeReferencesPanel = ({ onFocusNode }: CodeReferencesPanelProps) => {
+  const { t } = useTranslation(['common', 'graph']);
   const {
     graph,
     selectedNode,
@@ -294,14 +296,14 @@ export const CodeReferencesPanel = ({ onFocusNode }: CodeReferencesPanelProps) =
         <button
           onClick={() => setIsCollapsed(false)}
           className="rounded p-2 text-text-secondary transition-colors hover:bg-cyan-500/10 hover:text-cyan-400"
-          title="Expand Code Panel"
+          title={t('graph:codePanel.expand')}
         >
           <PanelLeft className="h-5 w-5" />
         </button>
         <div className="my-1 h-px w-6 bg-border-subtle" />
         {showSelectedViewer && (
           <div className="rotate-90 text-[9px] font-medium tracking-wide whitespace-nowrap text-amber-400">
-            SELECTED
+            {t('graph:codePanel.selected')}
           </div>
         )}
         {showCitations && (
@@ -325,20 +327,22 @@ export const CodeReferencesPanel = ({ onFocusNode }: CodeReferencesPanelProps) =
       <div
         onMouseDown={startResize}
         className="absolute top-0 right-0 h-full w-2 cursor-col-resize bg-transparent transition-colors hover:bg-cyan-500/25"
-        title="Drag to resize"
+        title={t('graph:codePanel.dragResize')}
       />
       {/* Header */}
       <div className="flex items-center justify-between border-b border-border-subtle bg-gradient-to-r from-elevated/60 to-surface/60 px-3 py-2.5">
         <div className="flex items-center gap-2">
           <Code className="h-4 w-4 text-cyan-400" />
-          <span className="text-sm font-semibold text-text-primary">Code Inspector</span>
+          <span className="text-sm font-semibold text-text-primary">
+            {t('graph:codePanel.title')}
+          </span>
         </div>
         <div className="flex items-center gap-1.5">
           {showCitations && (
             <button
               onClick={() => clearCodeReferences()}
               className="rounded p-1.5 text-text-muted transition-colors hover:bg-red-500/10 hover:text-red-400"
-              title="Clear AI citations"
+              title={t('graph:codePanel.clearCitations')}
             >
               <Trash2 className="h-4 w-4" />
             </button>
@@ -346,7 +350,7 @@ export const CodeReferencesPanel = ({ onFocusNode }: CodeReferencesPanelProps) =
           <button
             onClick={() => setIsCollapsed(true)}
             className="rounded p-1.5 text-text-muted transition-colors hover:bg-hover hover:text-text-primary"
-            title="Collapse Panel"
+            title={t('common:actions.collapse')}
           >
             <PanelLeftClose className="h-4 w-4" />
           </button>
@@ -361,7 +365,7 @@ export const CodeReferencesPanel = ({ onFocusNode }: CodeReferencesPanelProps) =
               <div className="flex items-center gap-1.5 rounded-md border border-amber-500/25 bg-amber-500/15 px-2 py-0.5">
                 <MousePointerClick className="h-3 w-3 text-amber-400" />
                 <span className="text-[10px] font-semibold tracking-wide text-amber-300 uppercase">
-                  Selected
+                  {t('graph:codePanel.selected')}
                 </span>
               </div>
               <FileCode className="ml-1 h-3.5 w-3.5 text-amber-400/70" />
@@ -372,16 +376,16 @@ export const CodeReferencesPanel = ({ onFocusNode }: CodeReferencesPanelProps) =
               <button
                 onClick={() => setSelectedNode(null)}
                 className="rounded p-1 text-text-muted transition-colors hover:bg-amber-500/10 hover:text-amber-400"
-                title="Clear selection"
+                title={t('graph:codePanel.clearSelection')}
               >
                 <X className="h-4 w-4" />
               </button>
             </div>
-            <div ref={selectedViewerRef} className="scrollbar-thin min-h-0 flex-1 overflow-auto">
+            <div ref={selectedViewerRef} className="min-h-0 flex-1 scrollbar-thin overflow-auto">
               {isLoadingFile ? (
                 <div className="flex items-center justify-center gap-2 py-8 text-text-muted">
                   <Loader2 className="h-4 w-4 animate-spin" />
-                  <span className="text-sm">Loading source...</span>
+                  <span className="text-sm">{t('graph:codePanel.loadingSource')}</span>
                 </div>
               ) : selectedFileContent ? (
                 <SyntaxHighlighter
@@ -420,12 +424,9 @@ export const CodeReferencesPanel = ({ onFocusNode }: CodeReferencesPanelProps) =
               ) : (
                 <div className="px-3 py-3 text-sm text-text-muted">
                   {selectedIsFile ? (
-                    <>
-                      Code not available in memory for{' '}
-                      <span className="font-mono">{selectedFilePath}</span>
-                    </>
+                    <>{t('graph:codePanel.codeNotAvailable', { path: selectedFilePath })}</>
                   ) : (
-                    <>Select a file node to preview its contents.</>
+                    <>{t('graph:codePanel.selectFile')}</>
                   )}
                 </div>
               )}
@@ -446,14 +447,14 @@ export const CodeReferencesPanel = ({ onFocusNode }: CodeReferencesPanelProps) =
               <div className="flex items-center gap-1.5 rounded-md border border-cyan-500/25 bg-cyan-500/15 px-2 py-0.5">
                 <Sparkles className="h-3 w-3 text-cyan-400" />
                 <span className="text-[10px] font-semibold tracking-wide text-cyan-300 uppercase">
-                  AI Citations
+                  {t('graph:codePanel.aiCitations')}
                 </span>
               </div>
               <span className="ml-1 text-xs text-text-muted">
-                {aiReferences.length} reference{aiReferences.length !== 1 ? 's' : ''}
+                {t('graph:codePanel.references', { count: aiReferences.length })}
               </span>
             </div>
-            <div className="scrollbar-thin min-h-0 flex-1 space-y-3 overflow-y-auto p-3">
+            <div className="min-h-0 flex-1 scrollbar-thin space-y-3 overflow-y-auto p-3">
               {refsWithSnippets.map(
                 ({ ref, content, start, highlightStart, highlightEnd, totalLines }) => {
                   const nodeColor = ref.label
@@ -483,9 +484,9 @@ export const CodeReferencesPanel = ({ onFocusNode }: CodeReferencesPanelProps) =
                         <span
                           className="mt-0.5 flex-shrink-0 rounded px-2 py-0.5 text-[10px] font-semibold tracking-wide uppercase"
                           style={{ backgroundColor: nodeColor, color: '#06060a' }}
-                          title={ref.label ?? 'Code'}
+                          title={ref.label ?? t('graph:codePanel.code')}
                         >
-                          {ref.label ?? 'Code'}
+                          {ref.label ?? t('graph:codePanel.code')}
                         </span>
                         <div className="min-w-0 flex-1">
                           <div className="truncate text-xs font-medium text-text-primary">
@@ -501,7 +502,10 @@ export const CodeReferencesPanel = ({ onFocusNode }: CodeReferencesPanelProps) =
                               </span>
                             )}
                             {totalLines > 0 && (
-                              <span className="text-text-muted"> • {totalLines} lines</span>
+                              <span className="text-text-muted">
+                                {' '}
+                                • {t('graph:codePanel.lines', { count: totalLines })}
+                              </span>
                             )}
                           </div>
                         </div>
@@ -518,7 +522,7 @@ export const CodeReferencesPanel = ({ onFocusNode }: CodeReferencesPanelProps) =
                                 onFocusNode(nodeId);
                               }}
                               className="rounded p-1.5 text-text-muted transition-colors hover:bg-hover hover:text-text-primary"
-                              title="Focus in graph"
+                              title={t('common:actions.focusInGraph')}
                             >
                               <Target className="h-4 w-4" />
                             </button>
@@ -526,7 +530,7 @@ export const CodeReferencesPanel = ({ onFocusNode }: CodeReferencesPanelProps) =
                           <button
                             onClick={() => removeCodeReference(ref.id)}
                             className="rounded p-1.5 text-text-muted transition-colors hover:bg-hover hover:text-text-primary"
-                            title="Remove"
+                            title={t('common:actions.remove')}
                           >
                             <X className="h-4 w-4" />
                           </button>
@@ -572,8 +576,7 @@ export const CodeReferencesPanel = ({ onFocusNode }: CodeReferencesPanelProps) =
                           </SyntaxHighlighter>
                         ) : (
                           <div className="px-3 py-3 text-sm text-text-muted">
-                            Code not available in memory for{' '}
-                            <span className="font-mono">{ref.filePath}</span>
+                            {t('graph:codePanel.codeNotAvailable', { path: ref.filePath })}
                           </div>
                         )}
                       </div>

gitnexus-web/src/components/DropZone.tsx

@@ -10,6 +10,8 @@ import { useBackend } from '../hooks/useBackend';
 import { OnboardingGuide } from './OnboardingGuide';
 import { AnalyzeOnboarding } from './AnalyzeOnboarding';
 import { RepoLanding } from './RepoLanding';
+import { useTranslation } from 'react-i18next';
+import { formatBackendError } from '../i18n/error-messages';
 
 interface DropZoneProps {
   onServerConnect?: (result: ConnectResult, serverUrl?: string) => void | Promise<void>;
@@ -60,6 +62,8 @@ function Crossfade({ activeKey, children }: { activeKey: string; children: React
 // ── Phase cards ─────────────────────────────────────────────────────────────
 
 function SuccessCard() {
+  const { t } = useTranslation('onboarding');
+
   return (
     <div
       className="relative overflow-hidden rounded-3xl border border-emerald-500/20 bg-surface p-7"
@@ -76,10 +80,10 @@ function SuccessCard() {
         </div>
 
         <h2 className="mb-2 text-center text-lg font-semibold text-emerald-400">
-          Server Connected
+          {t('success.title')}
         </h2>
         <p className="text-center text-sm leading-relaxed text-text-secondary">
-          Preparing your code knowledge graph...
+          {t('success.description')}
         </p>
 
         {/* Subtle progress hint */}
@@ -100,6 +104,8 @@ function SuccessCard() {
 }
 
 function LoadingCard({ message }: { message: string }) {
+  const { t } = useTranslation(['common', 'onboarding']);
+
   return (
     <div
       className="relative overflow-hidden rounded-3xl border border-accent/20 bg-surface p-7"
@@ -116,10 +122,10 @@ function LoadingCard({ message }: { message: string }) {
         </div>
 
         <h2 className="mb-2 text-center text-lg font-semibold text-text-primary">
-          {message || 'Connecting...'}
+          {message || t('common:progress.connectingShort')}
         </h2>
         <p className="text-center text-sm leading-relaxed text-text-secondary">
-          This may take a moment for large repositories
+          {t('onboarding:loading.largeRepoHint')}
         </p>
 
         {/* Decorative sparkle */}
@@ -134,6 +140,7 @@ function LoadingCard({ message }: { message: string }) {
 // ── DropZone ─────────────────────────────────────────────────────────────────
 
 export const DropZone = ({ onServerConnect }: DropZoneProps) => {
+  const { t } = useTranslation(['common', 'errors']);
   const [error, setError] = useState<string | null>(null);
 
   // Backend polling for server detection
@@ -163,7 +170,7 @@ export const DropZone = ({ onServerConnect }: DropZoneProps) => {
   // appropriate screen (landing with repo cards, or analyze for zero repos).
   const handleAutoConnect = async () => {
     setPhase('loading');
-    setLoadingMessage('Connecting...');
+    setLoadingMessage(t('common:progress.connectingShort'));
     setError(null);
 
     try {
@@ -179,8 +186,7 @@ export const DropZone = ({ onServerConnect }: DropZoneProps) => {
       setPhase('landing');
     } catch (err) {
       if ((err as Error).name === 'AbortError') return;
-      const message = err instanceof Error ? err.message : 'Failed to connect';
-      setError(message);
+      setError(formatBackendError(err, t));
       setPhase('onboarding');
     }
   };
@@ -193,7 +199,7 @@ export const DropZone = ({ onServerConnect }: DropZoneProps) => {
   const connectToRepo = (repoName: string) => {
     autoConnectRan.current = true;
     setPhase('loading');
-    setLoadingMessage('Loading graph...');
+    setLoadingMessage(t('common:progress.loadingGraph'));
     setError(null);
 
     (async () => {
@@ -204,13 +210,17 @@ export const DropZone = ({ onServerConnect }: DropZoneProps) => {
           detectedBackendUrl,
           (p, downloaded, total) => {
             if (p === 'validating') {
-              setLoadingMessage('Validating server...');
+              setLoadingMessage(t('common:progress.validatingServerEllipsis'));
             } else if (p === 'downloading') {
               const pct = total ? Math.round((downloaded / total) * 100) : null;
               const mb = (downloaded / (1024 * 1024)).toFixed(1);
-              setLoadingMessage(pct ? `Downloading graph... ${pct}%` : `Downloading... ${mb} MB`);
+              setLoadingMessage(
+                pct
+                  ? t('common:progress.downloadingWithPercent', { percent: pct })
+                  : t('common:progress.downloadingMb', { mb }),
+              );
             } else if (p === 'extracting') {
-              setLoadingMessage('Processing graph...');
+              setLoadingMessage(t('common:progress.processingGraph'));
             }
           },
           abortController.signal,
@@ -221,7 +231,7 @@ export const DropZone = ({ onServerConnect }: DropZoneProps) => {
         }
       } catch (err) {
         if ((err as Error).name === 'AbortError') return;
-        setError(err instanceof Error ? err.message : 'Failed to load graph');
+        setError(formatBackendError(err, t));
         setPhase(detectedRepos.length > 0 ? 'landing' : 'analyze');
       } finally {
         abortControllerRef.current = null;

gitnexus-web/src/components/EmbeddingStatus.tsx

@@ -2,12 +2,14 @@ import { Brain, Loader2, Check, AlertCircle, Zap } from '@/lib/lucide-icons';
 import { useAppState } from '../hooks/useAppState';
 import { useState } from 'react';
 import { WebGPUFallbackDialog } from './WebGPUFallbackDialog';
+import { useTranslation } from 'react-i18next';
 
 /**
  * Embedding status indicator and trigger button
  * Shows in header when graph is loaded
  */
 export const EmbeddingStatus = () => {
+  const { t } = useTranslation('graph');
   const { embeddingStatus, embeddingProgress, startEmbeddings, graph, viewMode, serverBaseUrl } =
     useAppState();
 
@@ -63,10 +65,10 @@ export const EmbeddingStatus = () => {
           <button
             onClick={() => handleStartEmbeddings()}
             className="group flex items-center gap-2 rounded-lg border border-border-subtle bg-surface px-3 py-1.5 text-sm text-text-secondary transition-all hover:border-accent/50 hover:bg-hover hover:text-text-primary"
-            title="Generate embeddings for semantic search"
+            title={t('embedding.generateTitle')}
           >
             <Brain className="h-4 w-4 text-node-interface transition-colors group-hover:text-accent" />
-            <span className="hidden sm:inline">Enable Semantic Search</span>
+            <span className="hidden sm:inline">{t('embedding.enable')}</span>
             <Zap className="h-3 w-3 text-text-muted" />
           </button>
         </div>
@@ -83,7 +85,7 @@ export const EmbeddingStatus = () => {
         <div className="flex items-center gap-2.5 rounded-lg border border-accent/30 bg-surface px-3 py-1.5 text-sm">
           <Loader2 className="h-4 w-4 animate-spin text-accent" />
           <div className="flex flex-col gap-0.5">
-            <span className="text-xs text-text-secondary">Loading AI model...</span>
+            <span className="text-xs text-text-secondary">{t('embedding.loadingModel')}</span>
             <div className="h-1 w-24 overflow-hidden rounded-full bg-elevated">
               <div
                 className="h-full rounded-full bg-gradient-to-r from-accent to-node-interface transition-all duration-300"
@@ -108,7 +110,7 @@ export const EmbeddingStatus = () => {
         <Loader2 className="h-4 w-4 animate-spin text-node-function" />
         <div className="flex flex-col gap-0.5">
           <span className="text-xs text-text-secondary">
-            Embedding {processed}/{total} nodes
+            {t('embedding.embeddingNodes', { processed, total })}
           </span>
           <div className="h-1 w-24 overflow-hidden rounded-full bg-elevated">
             <div
@@ -126,7 +128,7 @@ export const EmbeddingStatus = () => {
     return (
       <div className="flex items-center gap-2 rounded-lg border border-node-interface/30 bg-surface px-3 py-1.5 text-sm text-text-secondary">
         <Loader2 className="h-4 w-4 animate-spin text-node-interface" />
-        <span className="text-xs">Creating vector index...</span>
+        <span className="text-xs">{t('embedding.creatingIndex')}</span>
       </div>
     );
   }
@@ -136,10 +138,10 @@ export const EmbeddingStatus = () => {
     return (
       <div
         className="flex items-center gap-2 rounded-lg border border-node-function/30 bg-node-function/10 px-3 py-1.5 text-sm text-node-function"
-        title="Semantic search is ready! Use natural language in the AI chat."
+        title={t('embedding.readyTitle')}
       >
         <Check className="h-4 w-4" />
-        <span className="text-xs font-medium">Semantic Ready</span>
+        <span className="text-xs font-medium">{t('embedding.ready')}</span>
       </div>
     );
   }
@@ -151,10 +153,10 @@ export const EmbeddingStatus = () => {
         <button
           onClick={() => handleStartEmbeddings()}
           className="flex items-center gap-2 rounded-lg border border-red-500/30 bg-red-500/10 px-3 py-1.5 text-sm text-red-400 transition-colors hover:bg-red-500/20"
-          title="Embedding failed. Click to retry."
+          title={t('embedding.errorTitle')}
         >
           <AlertCircle className="h-4 w-4" />
-          <span className="text-xs">Failed - Retry</span>
+          <span className="text-xs">{t('embedding.failedRetry')}</span>
         </button>
         {fallbackDialog}
       </>

gitnexus-web/src/components/FileTreePanel.tsx

@@ -19,6 +19,7 @@ import {
   Type,
 } from '@/lib/lucide-icons';
 import { useAppState } from '../hooks/useAppState';
+import { useTranslation } from 'react-i18next';
 import { FILTERABLE_LABELS, NODE_COLORS, ALL_EDGE_TYPES, EDGE_INFO } from '../lib/constants';
 import type { GraphNode, NodeLabel } from 'gitnexus-shared';
 
@@ -211,6 +212,7 @@ interface FileTreePanelProps {
 }
 
 export const FileTreePanel = ({ onFocusNode }: FileTreePanelProps) => {
+  const { t } = useTranslation(['common', 'graph']);
   const {
     graph,
     visibleLabels,
@@ -303,7 +305,7 @@ export const FileTreePanel = ({ onFocusNode }: FileTreePanelProps) => {
         <button
           onClick={() => setIsCollapsed(false)}
           className="rounded p-2 text-text-secondary transition-colors hover:bg-hover hover:text-text-primary"
-          title="Expand Panel"
+          title={t('graph:fileTree.expandPanel')}
         >
           <PanelLeft className="h-5 w-5" />
         </button>
@@ -314,7 +316,7 @@ export const FileTreePanel = ({ onFocusNode }: FileTreePanelProps) => {
             setActiveTab('files');
           }}
           className={`rounded p-2 transition-colors ${activeTab === 'files' ? 'bg-accent/10 text-accent' : 'text-text-secondary hover:bg-hover hover:text-text-primary'}`}
-          title="File Explorer"
+          title={t('graph:fileTree.fileExplorer')}
         >
           <Folder className="h-5 w-5" />
         </button>
@@ -324,7 +326,7 @@ export const FileTreePanel = ({ onFocusNode }: FileTreePanelProps) => {
             setActiveTab('filters');
           }}
           className={`rounded p-2 transition-colors ${activeTab === 'filters' ? 'bg-accent/10 text-accent' : 'text-text-secondary hover:bg-hover hover:text-text-primary'}`}
-          title="Filters"
+          title={t('graph:fileTree.filters')}
         >
           <Filter className="h-5 w-5" />
         </button>
@@ -345,7 +347,7 @@ export const FileTreePanel = ({ onFocusNode }: FileTreePanelProps) => {
                 : 'text-text-secondary hover:bg-hover hover:text-text-primary'
             }`}
           >
-            Explorer
+            {t('graph:fileTree.explorer')}
           </button>
           <button
             onClick={() => setActiveTab('filters')}
@@ -355,13 +357,13 @@ export const FileTreePanel = ({ onFocusNode }: FileTreePanelProps) => {
                 : 'text-text-secondary hover:bg-hover hover:text-text-primary'
             }`}
           >
-            Filters
+            {t('graph:fileTree.filters')}
           </button>
         </div>
         <button
           onClick={() => setIsCollapsed(true)}
           className="rounded p-1 text-text-muted transition-colors hover:bg-hover hover:text-text-primary"
-          title="Collapse Panel"
+          title={t('graph:fileTree.collapsePanel')}
         >
           <PanelLeftClose className="h-4 w-4" />
         </button>
@@ -375,7 +377,7 @@ export const FileTreePanel = ({ onFocusNode }: FileTreePanelProps) => {
               <Search className="absolute top-1/2 left-2.5 h-3.5 w-3.5 -translate-y-1/2 text-text-muted" />
               <input
                 type="text"
-                placeholder="Search files..."
+                placeholder={t('graph:fileTree.searchFiles')}
                 value={searchQuery}
                 onChange={(e) => setSearchQuery(e.target.value)}
                 className="w-full rounded border border-border-subtle bg-elevated py-1.5 pr-3 pl-8 text-xs text-text-primary placeholder:text-text-muted focus:border-accent focus:outline-none"
@@ -384,9 +386,11 @@ export const FileTreePanel = ({ onFocusNode }: FileTreePanelProps) => {
           </div>
 
           {/* File tree */}
-          <div className="scrollbar-thin flex-1 overflow-y-auto py-2">
+          <div className="flex-1 scrollbar-thin overflow-y-auto py-2">
             {fileTree.length === 0 ? (
-              <div className="px-3 py-4 text-center text-xs text-text-muted">No files loaded</div>
+              <div className="px-3 py-4 text-center text-xs text-text-muted">
+                {t('graph:fileTree.noFilesLoaded')}
+              </div>
             ) : (
               fileTree.map((node) => (
                 <TreeItem
@@ -406,14 +410,12 @@ export const FileTreePanel = ({ onFocusNode }: FileTreePanelProps) => {
       )}
 
       {activeTab === 'filters' && (
-        <div className="scrollbar-thin flex-1 overflow-y-auto p-3">
+        <div className="flex-1 scrollbar-thin overflow-y-auto p-3">
           <div className="mb-3">
             <h3 className="mb-2 text-xs font-medium tracking-wide text-text-secondary uppercase">
-              Node Types
+              {t('graph:fileTree.nodeTypes')}
             </h3>
-            <p className="mb-3 text-[11px] text-text-muted">
-              Toggle visibility of node types in the graph
-            </p>
+            <p className="mb-3 text-[11px] text-text-muted">{t('graph:fileTree.nodeTypesDesc')}</p>
           </div>
 
           <div className="flex flex-col gap-1">
@@ -449,11 +451,9 @@ export const FileTreePanel = ({ onFocusNode }: FileTreePanelProps) => {
           {/* Edge Type Toggles */}
           <div className="mt-6 border-t border-border-subtle pt-4">
             <h3 className="mb-2 text-xs font-medium tracking-wide text-text-secondary uppercase">
-              Edge Types
+              {t('graph:fileTree.edgeTypes')}
             </h3>
-            <p className="mb-3 text-[11px] text-text-muted">
-              Toggle visibility of relationship types
-            </p>
+            <p className="mb-3 text-[11px] text-text-muted">{t('graph:fileTree.edgeTypesDesc')}</p>
 
             <div className="flex flex-col gap-1">
               {ALL_EDGE_TYPES.map((edgeType) => {
@@ -488,19 +488,17 @@ export const FileTreePanel = ({ onFocusNode }: FileTreePanelProps) => {
           <div className="mt-6 border-t border-border-subtle pt-4">
             <h3 className="mb-2 text-xs font-medium tracking-wide text-text-secondary uppercase">
               <Target className="mr-1.5 inline h-3 w-3" />
-              Focus Depth
+              {t('graph:fileTree.focusDepth')}
             </h3>
-            <p className="mb-3 text-[11px] text-text-muted">
-              Show nodes within N hops of selection
-            </p>
+            <p className="mb-3 text-[11px] text-text-muted">{t('graph:fileTree.focusDepthDesc')}</p>
 
             <div className="flex flex-wrap gap-1.5">
               {[
-                { value: null, label: 'All' },
-                { value: 1, label: '1 hop' },
-                { value: 2, label: '2 hops' },
-                { value: 3, label: '3 hops' },
-                { value: 5, label: '5 hops' },
+                { value: null, label: t('graph:fileTree.all') },
+                { value: 1, label: t('graph:fileTree.hops', { count: 1 }) },
+                { value: 2, label: t('graph:fileTree.hops', { count: 2 }) },
+                { value: 3, label: t('graph:fileTree.hops', { count: 3 }) },
+                { value: 5, label: t('graph:fileTree.hops', { count: 5 }) },
               ].map(({ value, label }) => (
                 <button
                   key={label}
@@ -517,14 +515,16 @@ export const FileTreePanel = ({ onFocusNode }: FileTreePanelProps) => {
             </div>
 
             {depthFilter !== null && !selectedNode && (
-              <p className="mt-2 text-[10px] text-amber-400">Select a node to apply depth filter</p>
+              <p className="mt-2 text-[10px] text-amber-400">
+                {t('graph:fileTree.selectNodeDepth')}
+              </p>
             )}
           </div>
 
           {/* Legend */}
           <div className="mt-6 border-t border-border-subtle pt-4">
             <h3 className="mb-3 text-xs font-medium tracking-wide text-text-secondary uppercase">
-              Color Legend
+              {t('graph:fileTree.colorLegend')}
             </h3>
             <div className="grid grid-cols-2 gap-2">
               {(
@@ -558,8 +558,8 @@ export const FileTreePanel = ({ onFocusNode }: FileTreePanelProps) => {
       {graph && (
         <div className="border-t border-border-subtle bg-elevated/50 px-3 py-2">
           <div className="flex items-center justify-between text-[10px] text-text-muted">
-            <span>{graph.nodes.length} nodes</span>
-            <span>{graph.relationships.length} edges</span>
+            <span>{t('common:counts.nodes', { count: graph.nodes.length })}</span>
+            <span>{t('common:counts.edges', { count: graph.relationships.length })}</span>
           </div>
         </div>
       )}

gitnexus-web/src/components/GraphCanvas.tsx

@@ -21,12 +21,14 @@ import {
 import type { GraphNode } from 'gitnexus-shared';
 import { QueryFAB } from './QueryFAB';
 import Graph from 'graphology';
+import { useTranslation } from 'react-i18next';
 
 export interface GraphCanvasHandle {
   focusNode: (nodeId: string) => void;
 }
 
 export const GraphCanvas = forwardRef<GraphCanvasHandle>((_, ref) => {
+  const { t } = useTranslation('graph');
   const {
     graph,
     setSelectedNode,
@@ -268,7 +270,7 @@ export const GraphCanvas = forwardRef<GraphCanvasHandle>((_, ref) => {
             onClick={handleClearSelection}
             className="ml-2 rounded px-2 py-0.5 text-xs text-text-secondary transition-colors hover:bg-white/10 hover:text-text-primary"
           >
-            Clear
+            {t('canvas.clear')}
           </button>
         </div>
       )}
@@ -278,21 +280,21 @@ export const GraphCanvas = forwardRef<GraphCanvasHandle>((_, ref) => {
         <button
           onClick={zoomIn}
           className="flex h-9 w-9 items-center justify-center rounded-md border border-border-subtle bg-elevated text-text-secondary transition-colors hover:bg-hover hover:text-text-primary"
-          title="Zoom In"
+          title={t('canvas.zoomIn')}
         >
           <ZoomIn className="h-4 w-4" />
         </button>
         <button
           onClick={zoomOut}
           className="flex h-9 w-9 items-center justify-center rounded-md border border-border-subtle bg-elevated text-text-secondary transition-colors hover:bg-hover hover:text-text-primary"
-          title="Zoom Out"
+          title={t('canvas.zoomOut')}
         >
           <ZoomOut className="h-4 w-4" />
         </button>
         <button
           onClick={resetZoom}
           className="flex h-9 w-9 items-center justify-center rounded-md border border-border-subtle bg-elevated text-text-secondary transition-colors hover:bg-hover hover:text-text-primary"
-          title="Fit to Screen"
+          title={t('canvas.fit')}
         >
           <Maximize2 className="h-4 w-4" />
         </button>
@@ -305,7 +307,7 @@ export const GraphCanvas = forwardRef<GraphCanvasHandle>((_, ref) => {
           <button
             onClick={handleFocusSelected}
             className="flex h-9 w-9 items-center justify-center rounded-md border border-accent/30 bg-accent/20 text-accent transition-colors hover:bg-accent/30"
-            title="Focus on Selected Node"
+            title={t('canvas.focusSelected')}
           >
             <Focus className="h-4 w-4" />
           </button>
@@ -316,7 +318,7 @@ export const GraphCanvas = forwardRef<GraphCanvasHandle>((_, ref) => {
           <button
             onClick={handleClearSelection}
             className="flex h-9 w-9 items-center justify-center rounded-md border border-border-subtle bg-elevated text-text-secondary transition-colors hover:bg-hover hover:text-text-primary"
-            title="Clear Selection"
+            title={t('canvas.clearSelection')}
           >
             <RotateCcw className="h-4 w-4" />
           </button>
@@ -333,7 +335,7 @@ export const GraphCanvas = forwardRef<GraphCanvasHandle>((_, ref) => {
               ? 'animate-pulse border-accent bg-accent text-white shadow-glow'
               : 'border-border-subtle bg-elevated text-text-secondary hover:bg-hover hover:text-text-primary'
           } `}
-          title={isLayoutRunning ? 'Stop Layout' : 'Run Layout Again'}
+          title={isLayoutRunning ? t('canvas.stopLayout') : t('canvas.runLayout')}
         >
           {isLayoutRunning ? <Pause className="h-4 w-4" /> : <Play className="h-4 w-4" />}
         </button>
@@ -343,7 +345,9 @@ export const GraphCanvas = forwardRef<GraphCanvasHandle>((_, ref) => {
       {isLayoutRunning && (
         <div className="absolute bottom-4 left-1/2 z-10 flex -translate-x-1/2 animate-fade-in items-center gap-2 rounded-full border border-emerald-500/30 bg-emerald-500/20 px-3 py-1.5 backdrop-blur-sm">
           <div className="h-2 w-2 animate-ping rounded-full bg-emerald-400" />
-          <span className="text-xs font-medium text-emerald-400">Layout optimizing...</span>
+          <span className="text-xs font-medium text-emerald-400">
+            {t('canvas.layoutOptimizing')}
+          </span>
         </div>
       )}
 
@@ -359,7 +363,9 @@ export const GraphCanvas = forwardRef<GraphCanvasHandle>((_, ref) => {
               ? 'flex h-10 w-10 items-center justify-center rounded-lg border border-cyan-400/40 bg-cyan-500/15 text-cyan-200 transition-colors hover:border-cyan-300/60 hover:bg-cyan-500/20'
               : 'flex h-10 w-10 items-center justify-center rounded-lg border border-border-subtle bg-elevated text-text-muted transition-colors hover:bg-hover hover:text-text-primary'
           }
-          title={isAIHighlightsEnabled ? 'Turn off all highlights' : 'Turn on AI highlights'}
+          title={
+            isAIHighlightsEnabled ? t('canvas.turnOffHighlights') : t('canvas.turnOnHighlights')
+          }
           data-testid="ai-highlights-toggle"
         >
           {isAIHighlightsEnabled ? (

gitnexus-web/src/components/Header.tsx

@@ -21,9 +21,12 @@ import {
   type JobProgress,
 } from '../services/backend-client';
 import { useState, useMemo, useRef, useEffect } from 'react';
+import { useTranslation } from 'react-i18next';
 import { GraphNode } from 'gitnexus-shared';
 import { EmbeddingStatus } from './EmbeddingStatus';
 import { RepoAnalyzer } from './RepoAnalyzer';
+import { LanguageSwitcher } from './LanguageSwitcher';
+import { translateProgressMessage } from '../i18n/progress';
 
 // Color mapping for node types in search results
 const NODE_TYPE_COLORS: Record<string, string> = {
@@ -55,6 +58,7 @@ export const Header = ({
   onAnalyzeComplete,
   onReposChanged,
 }: HeaderProps) => {
+  const { t } = useTranslation(['common', 'header']);
   const {
     projectName,
     graph,
@@ -208,7 +212,7 @@ export const Header = ({
                     {availableRepos.length > 0 && (
                       <div>
                         <div className="px-3 pt-2.5 pb-1.5 text-[10px] font-medium tracking-wider text-text-muted uppercase">
-                          Repositories
+                          {t('header:repositories')}
                         </div>
                         {availableRepos.map((repo) => (
                           <div
@@ -232,7 +236,7 @@ export const Header = ({
                               </span>
                               {repo.name === projectName && (
                                 <span className="shrink-0 font-mono text-[10px] text-accent">
-                                  active
+                                  {t('header:active')}
                                 </span>
                               )}
                             </button>
@@ -245,7 +249,7 @@ export const Header = ({
                                 setReanalyzeProgress({
                                   phase: 'queued',
                                   percent: 0,
-                                  message: 'Starting...',
+                                  message: t('common:progress.starting'),
                                 });
                                 try {
                                   const { jobId } = await startAnalyze({
@@ -282,8 +286,8 @@ export const Header = ({
                               }`}
                               title={
                                 reanalyzing === repo.name
-                                  ? 'Re-analyzing...'
-                                  : `Re-analyze ${repo.name}`
+                                  ? t('header:reanalyzing')
+                                  : t('header:reanalyzeRepo', { repoName: repo.name })
                               }
                             >
                               <RefreshCw
@@ -317,7 +321,7 @@ export const Header = ({
                                 }
                               }}
                               className="cursor-pointer rounded p-1 text-text-muted/0 transition-all group-hover:text-text-muted hover:!text-red-400"
-                              title={`Delete ${repo.name}`}
+                              title={t('header:deleteRepo', { repoName: repo.name })}
                             >
                               <Trash2 className="h-3.5 w-3.5" />
                             </button>
@@ -332,7 +336,10 @@ export const Header = ({
                         <div className="mb-1.5 flex items-center gap-2">
                           <Loader2 className="h-3 w-3 shrink-0 animate-spin text-accent" />
                           <span className="truncate text-xs text-text-secondary">
-                            Re-analyzing {reanalyzing}: {reanalyzeProgress.message}
+                            {t('header:reanalyzingRepo', {
+                              repoName: reanalyzing,
+                              message: translateProgressMessage(reanalyzeProgress.message, t),
+                            })}
                           </span>
                         </div>
                         <div className="h-1 overflow-hidden rounded-full bg-elevated">
@@ -359,7 +366,7 @@ export const Header = ({
                       >
                         <Sparkles className="h-3.5 w-3.5 shrink-0 text-accent" />
                         <span className="text-sm text-text-secondary">
-                          Analyze a new repository...
+                          {t('header:analyzeNew')}
                         </span>
                       </button>
                     </div>
@@ -378,7 +385,7 @@ export const Header = ({
           <input
             ref={inputRef}
             type="text"
-            placeholder="Search nodes..."
+            placeholder={t('header:searchNodes')}
             value={searchQuery}
             onChange={(e) => {
               setSearchQuery(e.target.value);
@@ -399,7 +406,7 @@ export const Header = ({
           <div className="absolute top-full right-0 left-0 z-50 mt-1 overflow-hidden rounded-xl border border-border-subtle bg-surface shadow-xl">
             {searchResults.length === 0 ? (
               <div className="px-4 py-3 text-sm text-text-muted">
-                No nodes found for &ldquo;{searchQuery}&rdquo;
+                {t('header:noNodesFound', { query: searchQuery })}
               </div>
             ) : (
               <div className="max-h-80 overflow-y-auto">
@@ -441,7 +448,7 @@ export const Header = ({
           className="group flex items-center gap-2 rounded-lg bg-gradient-to-r from-purple-600 to-pink-600 px-3.5 py-2 text-sm font-medium text-white shadow-lg transition-all duration-200 hover:-translate-y-0.5 hover:from-purple-500 hover:to-pink-500 hover:shadow-xl"
         >
           <Github className="h-4 w-4" />
-          <span className="hidden sm:inline">Star if cool</span>
+          <span className="hidden sm:inline">{t('header:starIfCool')}</span>
           <Star className="h-3.5 w-3.5 transition-all group-hover:fill-yellow-300 group-hover:text-yellow-300" />
           <span className="hidden sm:inline">✨</span>
         </a>
@@ -449,24 +456,26 @@ export const Header = ({
         {/* Stats */}
         {graph && (
           <div className="mr-2 flex items-center gap-4 text-xs text-text-muted">
-            <span>{nodeCount} nodes</span>
-            <span>{edgeCount} edges</span>
+            <span>{t('common:counts.nodes', { count: nodeCount })}</span>
+            <span>{t('common:counts.edges', { count: edgeCount })}</span>
           </div>
         )}
 
         {/* Embedding Status */}
         <EmbeddingStatus />
 
+        <LanguageSwitcher />
+
         {/* Icon buttons */}
         <button
           onClick={() => setSettingsPanelOpen(true)}
           className="flex h-9 w-9 cursor-pointer items-center justify-center rounded-md text-text-secondary transition-colors hover:bg-hover hover:text-text-primary"
-          title="AI Settings"
+          title={t('header:aiSettings')}
         >
           <Settings className="h-4.5 w-4.5" />
         </button>
         <button
-          title="Help"
+          title={t('header:help')}
           onClick={() => setHelpDialogBoxOpen(true)}
           className="flex h-9 w-9 cursor-pointer items-center justify-center rounded-md text-text-secondary transition-colors hover:bg-hover hover:text-text-primary"
         >
@@ -483,7 +492,7 @@ export const Header = ({
           } `}
         >
           <Sparkles className="h-4 w-4" />
-          <span>Nexus AI</span>
+          <span>{t('common:app.nexusAI')}</span>
         </button>
       </div>
     </header>

gitnexus-web/src/components/HelpPanel.tsx

@@ -1,5 +1,6 @@
 import React, { useState } from 'react';
 import { X, GitBranch, Search, Filter, Zap, Keyboard, BarChart2, HelpCircle } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
 
 interface HelpPanelProps {
   isOpen: boolean;
@@ -12,34 +13,33 @@ type TabId = 'overview' | 'graph' | 'search' | 'ai' | 'shortcuts' | 'status';
 
 interface Tab {
   id: TabId;
-  label: string;
   icon: React.ReactNode;
 }
 
 const tabs: Tab[] = [
-  { id: 'overview', label: 'Overview', icon: <HelpCircle className="h-4 w-4" /> },
-  { id: 'graph', label: 'Graph & nodes', icon: <GitBranch className="h-4 w-4" /> },
-  { id: 'search', label: 'Search & filter', icon: <Search className="h-4 w-4" /> },
-  { id: 'ai', label: 'Nexus AI', icon: <Zap className="h-4 w-4" /> },
-  { id: 'shortcuts', label: 'Shortcuts', icon: <Keyboard className="h-4 w-4" /> },
-  { id: 'status', label: 'Status bar', icon: <BarChart2 className="h-4 w-4" /> },
+  { id: 'overview', icon: <HelpCircle className="h-4 w-4" /> },
+  { id: 'graph', icon: <GitBranch className="h-4 w-4" /> },
+  { id: 'search', icon: <Search className="h-4 w-4" /> },
+  { id: 'ai', icon: <Zap className="h-4 w-4" /> },
+  { id: 'shortcuts', icon: <Keyboard className="h-4 w-4" /> },
+  { id: 'status', icon: <BarChart2 className="h-4 w-4" /> },
 ];
 
 const shortcuts = [
-  { label: 'Search nodes', mac: '⌘ K', win: 'Ctrl K' },
-  { label: 'Deselect / close', mac: 'Esc', win: 'Esc' },
+  { labelKey: 'shortcuts.searchNodes', mac: '⌘ K', win: 'Ctrl K' },
+  { labelKey: 'shortcuts.deselectClose', mac: 'Esc', win: 'Esc' },
 ];
 
 const nodeColors = [
-  { color: '#10b981', label: 'Function', desc: 'Function declarations' },
-  { color: '#3b82f6', label: 'File', desc: 'Source files' },
-  { color: '#f59e0b', label: 'Class', desc: 'Class declarations' },
-  { color: '#14b8a6', label: 'Method', desc: 'Class methods' },
-  { color: '#ec4899', label: 'Interface', desc: 'TypeScript interfaces' },
-  { color: '#6366f1', label: 'Folder', desc: 'Directory nodes' },
+  { color: '#10b981', labelKey: 'nodeTypes.function', descKey: 'nodeTypes.functionDesc' },
+  { color: '#3b82f6', labelKey: 'nodeTypes.file', descKey: 'nodeTypes.fileDesc' },
+  { color: '#f59e0b', labelKey: 'nodeTypes.class', descKey: 'nodeTypes.classDesc' },
+  { color: '#14b8a6', labelKey: 'nodeTypes.method', descKey: 'nodeTypes.methodDesc' },
+  { color: '#ec4899', labelKey: 'nodeTypes.interface', descKey: 'nodeTypes.interfaceDesc' },
+  { color: '#6366f1', labelKey: 'nodeTypes.folder', descKey: 'nodeTypes.folderDesc' },
 ];
 
-const getStatusItems = (nodeCount: number, edgeCount: number) => [
+const getStatusItems = (t: (key: string) => string, nodeCount: number, edgeCount: number) => [
   {
     badge: (
       <span
@@ -53,8 +53,8 @@ const getStatusItems = (nodeCount: number, edgeCount: number) => [
         }}
       />
     ),
-    title: 'Ready',
-    desc: 'Graph is fully loaded and interactive',
+    title: t('status.ready'),
+    desc: t('status.readyDesc'),
   },
   {
     badge: (
@@ -62,8 +62,8 @@ const getStatusItems = (nodeCount: number, edgeCount: number) => [
         {nodeCount}
       </span>
     ),
-    title: 'Nodes count',
-    desc: 'Total files and symbols in the graph',
+    title: t('status.nodesCount'),
+    desc: t('status.nodesCountDesc'),
   },
   {
     badge: (
@@ -71,8 +71,8 @@ const getStatusItems = (nodeCount: number, edgeCount: number) => [
         {edgeCount}
       </span>
     ),
-    title: 'Edges count',
-    desc: 'Import / dependency connections',
+    title: t('status.edgesCount'),
+    desc: t('status.edgesCountDesc'),
   },
   {
     badge: (
@@ -85,11 +85,11 @@ const getStatusItems = (nodeCount: number, edgeCount: number) => [
           whiteSpace: 'nowrap',
         }}
       >
-        Semantic Ready
+        {t('status.semanticReadyBadge')}
       </span>
     ),
-    title: 'AI index status',
-    desc: 'Repo is fully indexed for AI queries',
+    title: t('status.aiIndexStatus'),
+    desc: t('status.aiIndexStatusDesc'),
   },
   // { badge: <span style={{ fontSize: 11, fontWeight: 500, color: '#9ca3af', flexShrink: 0 }}>typescript</span>, title: 'Language', desc: 'Primary language detected in the repo' },
 ];
@@ -119,6 +119,8 @@ function TabContent({
   nodeCount: number;
   edgeCount: number;
 }) {
+  const { t } = useTranslation('help');
+
   if (active === 'overview')
     return (
       <div style={{ display: 'flex', flexDirection: 'column', gap: 10 }}>
@@ -131,7 +133,7 @@ function TabContent({
             letterSpacing: '0.08em',
           }}
         >
-          Getting started
+          {t('overview.gettingStarted')}
         </p>
 
         <div
@@ -143,11 +145,10 @@ function TabContent({
           }}
         >
           <p style={{ fontSize: 13, fontWeight: 500, color: '#e2e2e8', margin: '0 0 4px' }}>
-            What is GitNexus?
+            {t('overview.whatIsTitle')}
           </p>
           <p style={{ fontSize: 12, color: '#9ca3af', margin: 0, lineHeight: 1.6 }}>
-            An interactive graph explorer for your codebase. Every file, function, and import
-            becomes a node you can explore, query, and navigate visually.
+            {t('overview.whatIsDescription')}
           </p>
         </div>
 
@@ -160,11 +161,10 @@ function TabContent({
           }}
         >
           <p style={{ fontSize: 13, fontWeight: 500, color: '#e2e2e8', margin: '0 0 4px' }}>
-            Your current repo
+            {t('overview.currentRepoTitle')}
           </p>
           <p style={{ fontSize: 12, color: '#9ca3af', margin: 0, lineHeight: 1.6 }}>
-            Loaded: <span style={{ color: '#a78bfa', fontFamily: 'monospace' }}></span> {nodeCount}{' '}
-            nodes · {edgeCount} edges
+            {t('overview.loadedCounts', { nodeCount, edgeCount })}
           </p>
         </div>
 
@@ -177,15 +177,16 @@ function TabContent({
           }}
         >
           <p style={{ fontSize: 13, fontWeight: 500, color: '#e2e2e8', margin: '0 0 4px' }}>
-            Three ways to explore
+            {t('overview.threeWaysTitle')}
           </p>
           <p style={{ fontSize: 12, color: '#9ca3af', margin: 0, lineHeight: 1.6 }}>
-            <strong style={{ color: '#e2e2e8', fontWeight: 500 }}>1.</strong> Click nodes to inspect
+            <strong style={{ color: '#e2e2e8', fontWeight: 500 }}>1.</strong>{' '}
+            {t('overview.wayInspect')}
             <br />
-            <strong style={{ color: '#e2e2e8', fontWeight: 500 }}>2.</strong> Search by name or type
+            <strong style={{ color: '#e2e2e8', fontWeight: 500 }}>2.</strong>{' '}
+            {t('overview.waySearch')}
             <br />
-            <strong style={{ color: '#e2e2e8', fontWeight: 500 }}>3.</strong> Ask Nexus AI a natural
-            language question
+            <strong style={{ color: '#e2e2e8', fontWeight: 500 }}>3.</strong> {t('overview.wayAsk')}
           </p>
         </div>
 
@@ -198,11 +199,11 @@ function TabContent({
           }}
         >
           <p style={{ fontSize: 13, fontWeight: 500, color: '#e2e2e8', margin: '0 0 4px' }}>
-            Navigation
+            {t('overview.navigationTitle')}
           </p>
           <p style={{ fontSize: 12, color: '#9ca3af', margin: 0, lineHeight: 1.6 }}>
-            · Scroll to zoom <br />
-            · Click and drag to pan <br />· Double-click a node to focus its subgraph
+            · {t('overview.navZoom')} <br />· {t('overview.navPan')} <br />·{' '}
+            {t('overview.navFocus')}
           </p>
         </div>
       </div>
@@ -220,44 +221,44 @@ function TabContent({
             letterSpacing: '0.08em',
           }}
         >
-          Node color legend
+          {t('graph.nodeColorLegend')}
         </p>
 
-        {nodeColors.map(({ color, label, desc }) => (
-          <div key={label} style={{ display: 'flex', gap: 10, alignItems: 'flex-start' }}>
-            <span
-              style={{
-                width: 12,
-                height: 12,
-                borderRadius: '50%',
-                background: color,
-                flexShrink: 0,
-                marginTop: 2,
-              }}
-            />
-            <div>
-              <p style={{ fontSize: 12, fontWeight: 500, color: '#e2e2e8', margin: '0 0 2px' }}>
-                {label} nodes
-              </p>
-              <p style={{ fontSize: 12, color: '#9ca3af', margin: 0 }}>{desc}</p>
+        {nodeColors.map(({ color, labelKey, descKey }) => {
+          const label = t(labelKey);
+          return (
+            <div key={labelKey} style={{ display: 'flex', gap: 10, alignItems: 'flex-start' }}>
+              <span
+                style={{
+                  width: 12,
+                  height: 12,
+                  borderRadius: '50%',
+                  background: color,
+                  flexShrink: 0,
+                  marginTop: 2,
+                }}
+              />
+              <div>
+                <p style={{ fontSize: 12, fontWeight: 500, color: '#e2e2e8', margin: '0 0 2px' }}>
+                  {t('graph.nodeLabel', { label })}
+                </p>
+                <p style={{ fontSize: 12, color: '#9ca3af', margin: 0 }}>{t(descKey)}</p>
+              </div>
             </div>
-          </div>
-        ))}
+          );
+        })}
 
         <div style={{ borderTop: '0.5px solid rgba(255,255,255,0.08)', margin: '4px 0' }} />
 
         <p style={{ fontSize: 12, color: '#9ca3af', margin: 0, lineHeight: 1.6 }}>
-          Node <strong style={{ color: '#e2e2e8', fontWeight: 500 }}>size</strong> reflects
-          connection count — larger nodes are depended on by more files. Edges point from importer →
-          imported.
+          {t('graph.sizeDescription')}
         </p>
 
         <div
           style={{ background: 'rgba(255,255,255,0.04)', borderRadius: 10, padding: '10px 14px' }}
         >
           <p style={{ fontSize: 12, color: '#9ca3af', margin: 0, lineHeight: 1.6 }}>
-            Click any node to open its detail panel — showing imports, exports, and reverse
-            dependencies.
+            {t('graph.detailDescription')}
           </p>
         </div>
       </div>
@@ -275,7 +276,7 @@ function TabContent({
             letterSpacing: '0.08em',
           }}
         >
-          Search & filter
+          {t('search.title')}
         </p>
 
         <div
@@ -284,12 +285,11 @@ function TabContent({
           <div style={{ display: 'flex', alignItems: 'center', gap: 8, marginBottom: 6 }}>
             <kbd style={kbdStyle}>⌘K</kbd>/<kbd style={kbdStyle}>Ctrl K</kbd>
             <p style={{ fontSize: 12, fontWeight: 500, color: '#e2e2e8', margin: 0 }}>
-              Search nodes
+              {t('search.searchNodes')}
             </p>
           </div>
           <p style={{ fontSize: 12, color: '#9ca3af', margin: 0, lineHeight: 1.6 }}>
-            Search by filename, function name, or import path. Matching nodes are highlighted live
-            in the graph.
+            {t('search.searchDescription')}
           </p>
         </div>
 
@@ -299,12 +299,11 @@ function TabContent({
           <div style={{ display: 'flex', alignItems: 'center', gap: 8, marginBottom: 6 }}>
             <Filter style={{ width: 14, height: 14, color: '#a78bfa', flexShrink: 0 }} />
             <p style={{ fontSize: 12, fontWeight: 500, color: '#e2e2e8', margin: 0 }}>
-              Filter panel
+              {t('search.filterPanel')}
             </p>
           </div>
           <p style={{ fontSize: 12, color: '#9ca3af', margin: 0, lineHeight: 1.6 }}>
-            Use the filter icon in the left sidebar to isolate specific node types, hide leaf nodes,
-            or focus on a depth range from a selected root.
+            {t('search.filterDescription')}
           </p>
         </div>
 
@@ -312,13 +311,13 @@ function TabContent({
           style={{ background: 'rgba(255,255,255,0.04)', borderRadius: 10, padding: '12px 14px' }}
         >
           <p style={{ fontSize: 12, fontWeight: 500, color: '#e2e2e8', margin: '0 0 6px' }}>
-            Search syntax
+            {t('search.syntax')}
           </p>
           {[
-            { query: 'auth', hint: 'match by name fragment' },
-            { query: './utils/', hint: 'match by path prefix' },
-            { query: 'type:config', hint: 'filter by node type' },
-          ].map(({ query, hint }) => (
+            { query: 'auth', hintKey: 'search.hints.nameFragment' },
+            { query: './utils/', hintKey: 'search.hints.pathPrefix' },
+            { query: 'type:config', hintKey: 'search.hints.nodeType' },
+          ].map(({ query, hintKey }) => (
             <div
               key={query}
               style={{ display: 'flex', alignItems: 'baseline', gap: 8, marginBottom: 4 }}
@@ -336,7 +335,7 @@ function TabContent({
               >
                 {query}
               </code>
-              <span style={{ fontSize: 12, color: '#6b7280' }}>{hint}</span>
+              <span style={{ fontSize: 12, color: '#6b7280' }}>{t(hintKey)}</span>
             </div>
           ))}
         </div>
@@ -355,7 +354,7 @@ function TabContent({
             letterSpacing: '0.08em',
           }}
         >
-          Nexus AI
+          {t('ai.title')}
         </p>
 
         <div
@@ -367,20 +366,19 @@ function TabContent({
           }}
         >
           <p style={{ fontSize: 12, fontWeight: 500, color: '#a78bfa', margin: '0 0 4px' }}>
-            ✓ Semantic Ready
+            {t('ai.semanticReady')}
           </p>
           <p style={{ fontSize: 12, color: '#9ca3af', margin: 0, lineHeight: 1.6 }}>
-            Your repo is indexed and ready for semantic queries. Nexus AI understands code structure
-            and relationships, not just file names.
+            {t('ai.description')}
           </p>
         </div>
 
-        <p style={{ fontSize: 12, color: '#9ca3af', margin: '4px 0 2px' }}>Try asking:</p>
+        <p style={{ fontSize: 12, color: '#9ca3af', margin: '4px 0 2px' }}>{t('tryAsking')}</p>
         {[
-          '"Which files depend on the auth module?"',
-          '"Find circular dependencies in this repo"',
-          '"What are the most connected components?"',
-          '"Show me all files that import useEffect"',
+          t('ai.questions.dependencies'),
+          t('ai.questions.circular'),
+          t('ai.questions.connected'),
+          t('ai.questions.imports'),
         ].map((q) => (
           <div
             key={q}
@@ -400,8 +398,7 @@ function TabContent({
         <div style={{ borderTop: '0.5px solid rgba(255,255,255,0.08)', margin: '4px 0' }} />
 
         <p style={{ fontSize: 12, color: '#6b7280', margin: 0, lineHeight: 1.6 }}>
-          Open the prompt via the <span style={{ color: '#e2e2e8' }}>Nexus AI</span> button
-          (top-right).
+          {t('ai.openPrompt')}
         </p>
       </div>
     );
@@ -428,7 +425,7 @@ function TabContent({
               letterSpacing: '0.08em',
             }}
           >
-            Action
+            {t('shortcuts.columns.action')}
           </span>
           <span
             style={{
@@ -454,9 +451,9 @@ function TabContent({
           </span>
         </div>
 
-        {shortcuts.map(({ label, mac, win }, i) => (
+        {shortcuts.map(({ labelKey, mac, win }, i) => (
           <div
-            key={label}
+            key={labelKey}
             style={{
               display: 'grid',
               gridTemplateColumns: '1fr 80px 88px',
@@ -467,7 +464,7 @@ function TabContent({
                 i < shortcuts.length - 1 ? '0.5px solid rgba(255,255,255,0.05)' : 'none',
             }}
           >
-            <span style={{ fontSize: 12, color: '#9ca3af' }}>{label}</span>
+            <span style={{ fontSize: 12, color: '#9ca3af' }}>{t(labelKey)}</span>
             <span style={{ display: 'flex', justifyContent: 'center' }}>
               <kbd style={kbdStyle}>{mac}</kbd>
             </span>
@@ -491,9 +488,9 @@ function TabContent({
             letterSpacing: '0.08em',
           }}
         >
-          Status bar explained
+          {t('status.explained')}
         </p>
-        {getStatusItems(nodeCount, edgeCount).map(({ badge, title, desc }) => (
+        {getStatusItems(t, nodeCount, edgeCount).map(({ badge, title, desc }) => (
           <div
             key={title}
             style={{
@@ -521,7 +518,9 @@ function TabContent({
 }
 
 export const HelpPanel = ({ isOpen, onClose, nodeCount, edgeCount }: HelpPanelProps) => {
+  const { t } = useTranslation('help');
   const [active, setActive] = useState<TabId>('overview');
+  const localizedTabs = tabs.map((tab) => ({ ...tab, label: t(`tabs.${tab.id}`) }));
 
   if (!isOpen) return null;
 
@@ -592,9 +591,9 @@ export const HelpPanel = ({ isOpen, onClose, nodeCount, edgeCount }: HelpPanelPr
             </div>
             <div>
               <h2 style={{ fontSize: 16, fontWeight: 600, color: '#e2e2e8', margin: 0 }}>
-                Help & Reference
+                {t('title')}
               </h2>
-              <p style={{ fontSize: 12, color: '#6b7280', margin: 0 }}>GitNexus — graph explorer</p>
+              <p style={{ fontSize: 12, color: '#6b7280', margin: 0 }}>{t('footer')}</p>
             </div>
           </div>
           <button
@@ -632,7 +631,7 @@ export const HelpPanel = ({ isOpen, onClose, nodeCount, edgeCount }: HelpPanelPr
               gap: 2,
             }}
           >
-            {tabs.map(({ id, label, icon }) => {
+            {localizedTabs.map(({ id, label, icon }) => {
               const isActive = active === id;
               return (
                 <button
@@ -699,16 +698,14 @@ export const HelpPanel = ({ isOpen, onClose, nodeCount, edgeCount }: HelpPanelPr
             background: 'rgba(255,255,255,0.01)',
           }}
         >
-          <span style={{ fontSize: 11, color: '#4b5563' }}>
-            GitNexus — open source codebase graph explorer
-          </span>
+          <span style={{ fontSize: 11, color: '#4b5563' }}>{t('footerLong')}</span>
           <a
             href="https://github.com/abhigyanpatwari/GitNexus"
             target="_blank"
             rel="noopener noreferrer"
             style={{ fontSize: 11, color: '#a78bfa', textDecoration: 'none' }}
           >
-            Docs & GitHub ↗
+            {t('docsGithub')}
           </a>
         </div>
       </div>

gitnexus-web/src/components/LanguageSwitcher.tsx

@@ -0,0 +1,43 @@
+import { Globe } from '@/lib/lucide-icons';
+import { useTranslation } from 'react-i18next';
+import { SUPPORTED_LANGUAGES, type SupportedLanguage } from '../i18n/languages';
+
+export const LanguageSwitcher = () => {
+  const { t, i18n } = useTranslation('header');
+  const currentLanguage = i18n.resolvedLanguage || i18n.language;
+  const currentLanguageMetadata =
+    SUPPORTED_LANGUAGES.find(
+      (language) => language.code.toLowerCase() === currentLanguage.toLowerCase(),
+    ) ?? SUPPORTED_LANGUAGES[0];
+
+  const handleChange = (language: SupportedLanguage) => {
+    void i18n.changeLanguage(language);
+  };
+
+  return (
+    <label
+      className="flex h-9 items-center gap-1.5 rounded-md border border-border-subtle bg-surface px-2 text-text-secondary transition-colors hover:border-border-default hover:bg-hover hover:text-text-primary"
+      title={t('selectLanguage')}
+    >
+      <Globe className="h-4 w-4" aria-hidden="true" />
+      <span className="sr-only">{t('language')}</span>
+      <select
+        data-testid="language-switcher"
+        value={currentLanguageMetadata.code}
+        aria-label={t('selectLanguage')}
+        onChange={(event) => handleChange(event.target.value as SupportedLanguage)}
+        className="cursor-pointer border-none bg-transparent text-xs font-medium outline-none"
+      >
+        {SUPPORTED_LANGUAGES.map((language) => (
+          <option
+            key={language.code}
+            value={language.code}
+            className="bg-surface text-text-primary"
+          >
+            {language.nativeName}
+          </option>
+        ))}
+      </select>
+    </label>
+  );
+};

gitnexus-web/src/components/LoadingOverlay.tsx

@@ -1,10 +1,16 @@
 import type { PipelineProgress } from 'gitnexus-shared';
+import { useTranslation } from 'react-i18next';
+import { translateProgressMessage } from '../i18n/progress';
 
 interface LoadingOverlayProps {
   progress: PipelineProgress;
 }
 
 export const LoadingOverlay = ({ progress }: LoadingOverlayProps) => {
+  const { t } = useTranslation(['common', 'graph']);
+  const message = translateProgressMessage(progress.message, t);
+  const detail = translateProgressMessage(progress.detail, t);
+
   return (
     <div className="fixed inset-0 z-50 flex flex-col items-center justify-center bg-void">
       {/* Background gradient effects */}
@@ -32,11 +38,11 @@ export const LoadingOverlay = ({ progress }: LoadingOverlayProps) => {
       {/* Status text */}
       <div className="text-center">
         <p className="mb-1 font-mono text-sm text-text-secondary">
-          {progress.message}
+          {message}
           <span className="animate-pulse">|</span>
         </p>
         {progress.detail && (
-          <p className="max-w-md truncate font-mono text-xs text-text-muted">{progress.detail}</p>
+          <p className="max-w-md truncate font-mono text-xs text-text-muted">{detail}</p>
         )}
       </div>
 
@@ -46,12 +52,15 @@ export const LoadingOverlay = ({ progress }: LoadingOverlayProps) => {
           <div className="flex items-center gap-2">
             <span className="h-2 w-2 rounded-full bg-node-file" />
             <span>
-              {progress.stats.filesProcessed} / {progress.stats.totalFiles} files
+              {t('graph:loading.filesProgress', {
+                processed: progress.stats.filesProcessed,
+                total: progress.stats.totalFiles,
+              })}
             </span>
           </div>
           <div className="flex items-center gap-2">
             <span className="h-2 w-2 rounded-full bg-node-function" />
-            <span>{progress.stats.nodesCreated} nodes</span>
+            <span>{t('common:counts.nodes', { count: progress.stats.nodesCreated })}</span>
           </div>
         </div>
       )}

gitnexus-web/src/components/MarkdownRenderer.tsx

@@ -5,6 +5,7 @@ import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter';
 import { vscDarkPlus } from 'react-syntax-highlighter/dist/esm/styles/prism';
 import { MermaidDiagram } from './MermaidDiagram';
 import { ToolCallCard } from './ToolCallCard';
+import { useTranslation } from 'react-i18next';
 import { Copy, Check } from '@/lib/lucide-icons';
 
 // Custom syntax theme
@@ -38,6 +39,7 @@ export const MarkdownRenderer: React.FC<MarkdownRendererProps> = ({
   toolCalls,
   showCopyButton = false,
 }) => {
+  const { t } = useTranslation('common');
   const [copied, setCopied] = useState(false);
   const copyTimerRef = useRef<ReturnType<typeof setTimeout>>(undefined);
 
@@ -125,7 +127,9 @@ export const MarkdownRenderer: React.FC<MarkdownRendererProps> = ({
               href={hrefStr}
               onClick={(e) => handleLinkClick(e, hrefStr)}
               className={`${baseParams} ${colorParams}`}
-              title={isNodeRef ? `View ${inner} in Code panel` : `Open in Code panel • ${inner}`}
+              title={t(isNodeRef ? 'chat.viewNodeInCodePanel' : 'chat.openInCodePanel', {
+                inner,
+              })}
               {...props}
             >
               <span className="text-inherit">{children}</span>
@@ -182,7 +186,7 @@ export const MarkdownRenderer: React.FC<MarkdownRendererProps> = ({
       },
       pre: ({ children }: any) => <>{children}</>,
     }),
-    [handleLinkClick],
+    [handleLinkClick, t],
   );
 
   return (
@@ -205,14 +209,14 @@ export const MarkdownRenderer: React.FC<MarkdownRendererProps> = ({
           <button
             onClick={handleCopy}
             className="flex items-center gap-1.5 rounded border border-transparent px-2 py-1 text-xs text-text-muted transition-all hover:border-border-subtle hover:bg-surface hover:text-text-primary"
-            title="Copy to clipboard"
+            title={t('actions.copy')}
           >
             {copied ? (
               <Check className="h-3.5 w-3.5 text-emerald-400" />
             ) : (
               <Copy className="h-3.5 w-3.5" />
             )}
-            <span>{copied ? 'Copied' : 'Copy'}</span>
+            <span>{copied ? t('actions.copied') : t('actions.copy')}</span>
           </button>
         </div>
       )}

gitnexus-web/src/components/MermaidDiagram.tsx

@@ -1,4 +1,5 @@
 import { Suspense, useEffect, useRef, useState, lazy } from 'react';
+import { useTranslation } from 'react-i18next';
 import mermaid from 'mermaid';
 import DOMPurify from 'dompurify';
 import { AlertTriangle, Maximize2 } from '@/lib/lucide-icons';
@@ -55,6 +56,7 @@ interface MermaidDiagramProps {
 }
 
 export const MermaidDiagram = ({ code }: MermaidDiagramProps) => {
+  const { t } = useTranslation(['graph']);
   const containerRef = useRef<HTMLDivElement>(null);
   const [error, setError] = useState<string | null>(null);
   const [showModal, setShowModal] = useState(false);
@@ -98,7 +100,7 @@ export const MermaidDiagram = ({ code }: MermaidDiagramProps) => {
   const processData: any = showModal
     ? {
         id: 'ai-generated',
-        label: 'AI Generated Diagram',
+        label: t('graph:diagram.aiGenerated'),
         processType: 'intra_community',
         steps: [], // Empty - we'll render raw mermaid
         edges: [],
@@ -112,12 +114,12 @@ export const MermaidDiagram = ({ code }: MermaidDiagramProps) => {
       <div className="my-3 rounded-lg border border-rose-500/30 bg-rose-500/10 p-4">
         <div className="mb-2 flex items-center gap-2 text-sm text-rose-300">
           <AlertTriangle className="h-4 w-4" />
-          <span className="font-medium">Diagram Error</span>
+          <span className="font-medium">{t('graph:diagram.error')}</span>
         </div>
         <pre className="font-mono text-xs whitespace-pre-wrap text-rose-200/70">{error}</pre>
         <details className="mt-2">
           <summary className="cursor-pointer text-xs text-text-muted hover:text-text-secondary">
-            Show source
+            {t('graph:diagram.showSource')}
           </summary>
           <pre className="mt-2 overflow-x-auto rounded bg-surface p-2 text-xs text-text-muted">
             {code}
@@ -134,12 +136,12 @@ export const MermaidDiagram = ({ code }: MermaidDiagramProps) => {
           {/* Header */}
           <div className="flex items-center justify-between border-b border-border-subtle bg-surface/60 px-3 py-2">
             <span className="text-[10px] font-medium tracking-wider text-text-muted uppercase">
-              Diagram
+              {t('graph:diagram.label')}
             </span>
             <button
               onClick={() => setShowModal(true)}
               className="rounded p-1 text-text-muted transition-colors hover:bg-hover hover:text-text-primary"
-              title="Expand"
+              title={t('graph:diagram.expandTitle')}
             >
               <Maximize2 className="h-3.5 w-3.5" />
             </button>
@@ -161,7 +163,9 @@ export const MermaidDiagram = ({ code }: MermaidDiagramProps) => {
 
       {/* Use ProcessFlowModal for expansion */}
       {showModal && processData && (
-        <Suspense fallback={<div className="p-4 text-sm text-text-muted">Loading diagram…</div>}>
+        <Suspense
+          fallback={<div className="p-4 text-sm text-text-muted">{t('graph:diagram.loading')}</div>}
+        >
           <ProcessFlowModal process={processData} onClose={() => setShowModal(false)} />
         </Suspense>
       )}

gitnexus-web/src/components/OnboardingGuide.tsx

@@ -1,6 +1,7 @@
 import { useState, useRef, useEffect } from 'react';
 import { Check, Copy, Terminal, Server, Zap, Sparkles } from '@/lib/lucide-icons';
 import { REQUIRED_NODE_VERSION } from '../config/ui-constants';
+import { useTranslation } from 'react-i18next';
 
 // ── Design constants ─────────────────────────────────────────────────────────
 
@@ -9,6 +10,7 @@ const isDev = import.meta.env.DEV;
 // ── Copy-to-clipboard button ─────────────────────────────────────────────────
 
 function CopyButton({ text }: { text: string }) {
+  const { t } = useTranslation('onboarding');
   const [copied, setCopied] = useState(false);
   const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
@@ -32,7 +34,7 @@ function CopyButton({ text }: { text: string }) {
   return (
     <button
       onClick={handleCopy}
-      aria-label={copied ? 'Copied!' : 'Copy to clipboard'}
+      aria-label={copied ? t('guide.copiedAria') : t('guide.copyAria')}
       className={`shrink-0 cursor-pointer rounded-md px-2 py-1 transition-all duration-200 focus-visible:ring-2 focus-visible:ring-accent/40 focus-visible:outline-none ${
         copied
           ? 'bg-emerald-400/10 text-emerald-400'
@@ -128,6 +130,7 @@ function StepRow({
   description?: string;
   children?: React.ReactNode;
 }) {
+  const { t } = useTranslation('onboarding');
   const isVisible = state !== 'waiting';
 
   return (
@@ -151,7 +154,7 @@ function StepRow({
             </span>
             {state === 'done' && (
               <span className="animate-fade-in font-mono text-[10px] tracking-wider text-emerald-400/60 uppercase">
-                done
+                {t('guide.done')}
               </span>
             )}
           </div>
@@ -168,6 +171,8 @@ function StepRow({
 // ── Polling status bar ────────────────────────────────────────────────────────
 
 function PollingBar() {
+  const { t } = useTranslation('onboarding');
+
   return (
     <div
       className="flex animate-fade-in items-center gap-3 rounded-xl border border-accent/15 bg-accent/5 px-4 py-3"
@@ -183,12 +188,12 @@ function PollingBar() {
 
       <div className="min-w-0 flex-1">
         <p className="text-xs font-medium text-text-secondary">
-          Listening for server
+          {t('guide.listeningForServer')}
           <span className="ml-0.5 inline-flex text-text-muted">
             <span className="animate-pulse">...</span>
           </span>
         </p>
-        <p className="mt-0.5 text-[11px] text-text-muted">Will auto-connect when detected</p>
+        <p className="mt-0.5 text-[11px] text-text-muted">{t('guide.willAutoConnect')}</p>
       </div>
     </div>
   );
@@ -201,8 +206,9 @@ interface OnboardingGuideProps {
 }
 
 export const OnboardingGuide = ({ isPolling }: OnboardingGuideProps) => {
+  const { t } = useTranslation('onboarding');
   const primary = isDev ? 'npm run --prefix gitnexus serve' : 'npx gitnexus@latest serve';
-  const termLabel = isDev ? 'Start backend' : 'Terminal';
+  const termLabel = isDev ? t('guide.startBackend') : t('guide.terminal');
 
   // Step states: step 1 = copy command, step 2 = run/wait, step 3 = auto-connect
   // Once polling starts the user has presumably run the command — mark step 1 done.
@@ -226,12 +232,10 @@ export const OnboardingGuide = ({ isPolling }: OnboardingGuideProps) => {
             </span>
           </div>
           <h2 className="text-lg leading-snug font-semibold text-text-primary">
-            Start your local server
+            {t('guide.startServer')}
           </h2>
           <p className="mx-auto mt-1 max-w-xs text-sm leading-relaxed text-text-secondary">
-            {isDev
-              ? 'Fire up the Express backend in a separate terminal to unlock the full graph.'
-              : 'One command is all it takes. The browser connects automatically.'}
+            {isDev ? t('guide.devDescription') : t('guide.prodDescription')}
           </p>
         </div>
       </div>
@@ -248,8 +252,8 @@ export const OnboardingGuide = ({ isPolling }: OnboardingGuideProps) => {
         <StepRow
           state={step1State}
           number={1}
-          title="Copy the command"
-          description={isPolling ? undefined : 'Click the icon in the terminal to copy.'}
+          title={t('guide.copyCommand')}
+          description={isPolling ? undefined : t('guide.copyCommandDescription')}
         >
           <TerminalWindow command={primary} label={termLabel} isActive={step1State === 'active'} />
 
@@ -259,13 +263,13 @@ export const OnboardingGuide = ({ isPolling }: OnboardingGuideProps) => {
               <div className="my-3 flex items-center gap-3">
                 <div className="h-px flex-1 bg-border-subtle" />
                 <span className="text-[11px] tracking-widest text-text-muted uppercase">
-                  or install globally
+                  {t('guide.orInstallGlobally')}
                 </span>
                 <div className="h-px flex-1 bg-border-subtle" />
               </div>
               <TerminalWindow
                 command="npm install -g gitnexus && gitnexus serve"
-                label="Global install"
+                label={t('guide.globalInstall')}
                 isActive={false}
               />
             </>
@@ -276,10 +280,8 @@ export const OnboardingGuide = ({ isPolling }: OnboardingGuideProps) => {
         <StepRow
           state={step2State}
           number={2}
-          title={isPolling ? 'Waiting for server to start' : 'Paste and run in your terminal'}
-          description={
-            isPolling ? undefined : 'Open a terminal at the project root, paste, and hit Enter.'
-          }
+          title={isPolling ? t('guide.waitingForServer') : t('guide.pasteAndRun')}
+          description={isPolling ? undefined : t('guide.pasteAndRunDescription')}
         >
           {isPolling && <PollingBar />}
         </StepRow>
@@ -288,8 +290,8 @@ export const OnboardingGuide = ({ isPolling }: OnboardingGuideProps) => {
         <StepRow
           state={step3State}
           number={3}
-          title="Auto-connects and opens the graph"
-          description="No refresh needed — the page detects the server automatically."
+          title={t('guide.autoConnects')}
+          description={t('guide.autoConnectsDescription')}
         />
       </div>
 
@@ -297,7 +299,7 @@ export const OnboardingGuide = ({ isPolling }: OnboardingGuideProps) => {
       <div className="mt-6 flex items-center justify-center gap-1.5 border-t border-border-subtle pt-5 text-xs text-text-muted">
         <Server className="h-3 w-3 shrink-0" />
         <span>
-          Requires{' '}
+          {t('guide.requires')}{' '}
           <a
             href="https://nodejs.org"
             target="_blank"
@@ -309,7 +311,7 @@ export const OnboardingGuide = ({ isPolling }: OnboardingGuideProps) => {
         </span>
         <span className="mx-1 text-border-default">·</span>
         <Terminal className="h-3 w-3 shrink-0" />
-        <span>Port 4747</span>
+        <span>{t('guide.port')}</span>
       </div>
     </div>
   );

gitnexus-web/src/components/ProcessFlowModal.tsx

@@ -5,6 +5,7 @@
  */
 
 import { useEffect, useRef, useCallback, useState } from 'react';
+import { useTranslation } from 'react-i18next';
 import { Copy, Focus, ZoomIn, ZoomOut } from 'lucide-react';
 import mermaid from 'mermaid';
 import DOMPurify from 'dompurify';
@@ -59,6 +60,7 @@ export const ProcessFlowModal = ({
   onFocusInGraph,
   isFullScreen = false,
 }: ProcessFlowModalProps) => {
+  const { t } = useTranslation(['graph', 'common']);
   const containerRef = useRef<HTMLDivElement>(null);
   const diagramRef = useRef<HTMLDivElement>(null);
   const scrollContainerRef = useRef<HTMLDivElement>(null);
@@ -171,13 +173,13 @@ export const ProcessFlowModal = ({
         diagramRef.current!.innerHTML = `
           <div class="text-center p-8">
             <div class="text-red-400 text-sm font-medium mb-2">
-              ${isSizeError ? '📊 Diagram Too Large' : '⚠️ Render Error'}
+              ${isSizeError ? t('graph:processFlow.diagramTooLarge') : t('graph:processFlow.renderError')}
             </div>
             <div class="text-slate-400 text-xs max-w-md">
               ${
                 isSizeError
-                  ? `This diagram has ${process.steps?.length || 0} steps and is too complex to render. Try viewing individual processes instead of "All Processes".`
-                  : `Unable to render diagram. Steps: ${process.steps?.length || 0}`
+                  ? t('graph:processFlow.tooComplex', { count: process.steps?.length || 0 })
+                  : t('graph:processFlow.unableToRender', { count: process.steps?.length || 0 })
               }
             </div>
           </div>
@@ -186,7 +188,7 @@ export const ProcessFlowModal = ({
     };
 
     renderDiagram();
-  }, [process]);
+  }, [process, t]);
 
   // Close on escape
   useEffect(() => {
@@ -242,7 +244,9 @@ export const ProcessFlowModal = ({
 
         {/* Header */}
         <div className="relative z-10 border-b border-white/10 px-6 py-5">
-          <h2 className="text-lg font-semibold text-white">Process: {process.label}</h2>
+          <h2 className="text-lg font-semibold text-white">
+            {t('graph:processFlow.title', { label: process.label })}
+          </h2>
         </div>
 
         {/* Diagram */}
@@ -271,7 +275,7 @@ export const ProcessFlowModal = ({
             <button
               onClick={handleZoomOut}
               className="rounded-md p-2 text-slate-300 transition-all hover:bg-white/10 hover:text-white"
-              title="Zoom out (-)"
+              title={t('graph:processFlow.zoomOutTitle')}
             >
               <ZoomOut className="h-4 w-4" />
             </button>
@@ -281,7 +285,7 @@ export const ProcessFlowModal = ({
             <button
               onClick={handleZoomIn}
               className="rounded-md p-2 text-slate-300 transition-all hover:bg-white/10 hover:text-white"
-              title="Zoom in (+)"
+              title={t('graph:processFlow.zoomInTitle')}
             >
               <ZoomIn className="h-4 w-4" />
             </button>
@@ -289,9 +293,9 @@ export const ProcessFlowModal = ({
           <button
             onClick={resetView}
             className="flex items-center gap-2 rounded-lg border border-white/10 bg-white/5 px-4 py-2.5 text-sm font-medium text-slate-300 transition-all hover:bg-white/10 hover:text-white"
-            title="Reset zoom and pan"
+            title={t('graph:processFlow.resetTitle')}
           >
-            Reset View
+            {t('graph:processFlow.resetView')}
           </button>
           {onFocusInGraph && (
             <button
@@ -299,7 +303,7 @@ export const ProcessFlowModal = ({
               className="flex items-center gap-2 rounded-lg bg-cyan-400 px-5 py-2.5 text-sm font-medium text-slate-900 shadow-lg shadow-cyan-500/20 transition-all hover:bg-cyan-300"
             >
               <Focus className="h-4 w-4" />
-              Toggle Focus
+              {t('graph:processFlow.toggleFocus')}
             </button>
           )}
           <button
@@ -307,13 +311,13 @@ export const ProcessFlowModal = ({
             className="flex items-center gap-2 rounded-lg bg-purple-600 px-5 py-2.5 text-sm font-medium text-white shadow-lg shadow-purple-500/20 transition-all hover:bg-purple-500"
           >
             <Copy className="h-4 w-4" />
-            Copy Mermaid
+            {t('graph:processFlow.copyMermaid')}
           </button>
           <button
             onClick={onClose}
             className="rounded-lg border border-white/10 bg-white/5 px-5 py-2.5 text-sm font-medium text-slate-300 transition-all hover:bg-white/10 hover:text-white"
           >
-            Close
+            {t('common:actions.close')}
           </button>
         </div>
       </div>

gitnexus-web/src/components/ProcessesPanel.tsx

@@ -6,6 +6,7 @@
  */
 
 import { useState, useMemo, useCallback, useEffect } from 'react';
+import { useTranslation } from 'react-i18next';
 import {
   GitBranch,
   Search,
@@ -26,6 +27,7 @@ import type { ProcessData, ProcessStep } from '../lib/mermaid-generator';
 const isSafeId = (id: string): boolean => /^[a-zA-Z0-9_:.\-/@]+$/.test(id);
 
 export const ProcessesPanel = () => {
+  const { t } = useTranslation(['graph']);
   const { graph, runQuery, setHighlightedNodeIds, highlightedNodeIds } = useAppState();
   const [searchQuery, setSearchQuery] = useState('');
   const [selectedProcess, setSelectedProcess] = useState<ProcessData | null>(null);
@@ -120,7 +122,7 @@ export const ProcessesPanel = () => {
         if (!allStepsMap.has(stepId)) {
           allStepsMap.set(stepId, {
             id: stepId,
-            name: row.name || row[1] || 'Unknown',
+            name: row.name || row[1] || t('graph:processes.unknownStep'),
             filePath: row.filePath || row[2],
             stepNumber: row.stepNumber || row.step || row[3] || 0,
           });
@@ -158,7 +160,7 @@ export const ProcessesPanel = () => {
 
       const combinedProcessData: ProcessData = {
         id: 'combined-all',
-        label: `All Processes (${allProcessIds.length} combined)`,
+        label: t('graph:processes.allProcessesLabel', { count: allProcessIds.length }),
         processType: 'cross_community', // Treat as cross-community for styling
         steps: allSteps,
         edges: allEdges,
@@ -171,7 +173,7 @@ export const ProcessesPanel = () => {
     } finally {
       setLoadingProcess(null);
     }
-  }, [processes, runQuery]);
+  }, [processes, runQuery, t]);
 
   // Load process steps and open modal
   const handleViewProcess = useCallback(
@@ -191,7 +193,7 @@ export const ProcessesPanel = () => {
 
         const steps: ProcessStep[] = stepsResult.map((row: any) => ({
           id: row.id || row[0],
-          name: row.name || row[1] || 'Unknown',
+          name: row.name || row[1] || t('graph:processes.unknownStep'),
           filePath: row.filePath || row[2],
           stepNumber: row.stepNumber || row.step || row[3] || 0,
         }));
@@ -244,7 +246,7 @@ export const ProcessesPanel = () => {
         setLoadingProcess(null);
       }
     },
-    [runQuery, graph],
+    [runQuery, graph, t],
   );
 
   // Cache for process steps (so we don't re-query when toggling focus)
@@ -327,10 +329,11 @@ export const ProcessesPanel = () => {
         <div className="mb-4 flex h-14 w-14 items-center justify-center rounded-xl bg-surface">
           <GitBranch className="h-7 w-7 text-text-muted" />
         </div>
-        <h3 className="mb-2 text-base font-medium text-text-primary">No Processes Detected</h3>
+        <h3 className="mb-2 text-base font-medium text-text-primary">
+          {t('graph:processes.emptyTitle')}
+        </h3>
         <p className="max-w-xs text-sm text-text-secondary">
-          Processes are execution flows traced from entry points. Load a codebase to see detected
-          processes.
+          {t('graph:processes.emptyDescription')}
         </p>
       </div>
     );
@@ -347,7 +350,7 @@ export const ProcessesPanel = () => {
               type="text"
               value={searchQuery}
               onChange={(e) => setSearchQuery(e.target.value)}
-              placeholder="Filter processes..."
+              placeholder={t('graph:processes.filterPlaceholder')}
               className="flex-1 border-none bg-transparent text-sm text-text-primary outline-none placeholder:text-text-muted"
             />
           </div>
@@ -356,12 +359,12 @@ export const ProcessesPanel = () => {
           className="flex items-center gap-2 text-xs text-text-muted"
           data-testid="process-list-loaded"
         >
-          <span>{totalCount} processes detected</span>
+          <span>{t('graph:processes.detected', { count: totalCount })}</span>
         </div>
       </div>
 
       {/* Process list */}
-      <div className="scrollbar-thin flex-1 overflow-y-auto">
+      <div className="flex-1 scrollbar-thin overflow-y-auto">
         {/* View All Processes Card */}
         <div className="px-4 py-3">
           <button
@@ -374,9 +377,11 @@ export const ProcessesPanel = () => {
             </div>
             <div className="flex-1">
               <h4 className="text-sm font-medium text-text-primary group-hover:text-cyan-200">
-                Full Process Map
+                {t('graph:processes.fullMap')}
               </h4>
-              <p className="text-xs text-text-muted">View combined map of {totalCount} processes</p>
+              <p className="text-xs text-text-muted">
+                {t('graph:processes.viewCombined', { count: totalCount })}
+              </p>
             </div>
             {loadingProcess === 'all' ? (
               <span className="mr-1 animate-spin">
@@ -401,7 +406,9 @@ export const ProcessesPanel = () => {
                 <ChevronRight className="h-4 w-4 text-text-muted" />
               )}
               <Zap className="h-4 w-4 text-amber-400" />
-              <span className="text-sm font-medium text-text-primary">Cross-Community</span>
+              <span className="text-sm font-medium text-text-primary">
+                {t('graph:processes.crossCommunity')}
+              </span>
               <span className="ml-auto rounded-full bg-surface px-2 py-0.5 text-xs text-text-muted">
                 {filteredProcesses.cross.length}
               </span>
@@ -438,7 +445,9 @@ export const ProcessesPanel = () => {
                 <ChevronRight className="h-4 w-4 text-text-muted" />
               )}
               <Home className="h-4 w-4 text-emerald-400" />
-              <span className="text-sm font-medium text-text-primary">Intra-Community</span>
+              <span className="text-sm font-medium text-text-primary">
+                {t('graph:processes.intraCommunity')}
+              </span>
               <span className="ml-auto rounded-full bg-surface px-2 py-0.5 text-xs text-text-muted">
                 {filteredProcesses.intra.length}
               </span>
@@ -492,6 +501,7 @@ const ProcessItem = ({
   onView,
   onToggleFocus,
 }: ProcessItemProps) => {
+  const { t } = useTranslation(['graph']);
   // Determine row styling - focused gets special highlight
   const rowClass = isFocused
     ? 'bg-amber-950/40 border border-amber-500/50 ring-1 ring-amber-400/30'
@@ -508,11 +518,11 @@ const ProcessItem = ({
       <div className="min-w-0 flex-1">
         <div className="truncate text-sm text-text-primary">{process.label}</div>
         <div className="flex items-center gap-2 text-xs text-text-muted">
-          <span>{process.stepCount} steps</span>
+          <span>{t('graph:processes.steps', { count: process.stepCount })}</span>
           {process.clusters.length > 0 && (
             <>
               <span>•</span>
-              <span>{process.clusters.length} clusters</span>
+              <span>{t('graph:processes.clusters', { count: process.clusters.length })}</span>
             </>
           )}
         </div>
@@ -525,7 +535,11 @@ const ProcessItem = ({
             ? 'animate-pulse border border-amber-400/40 bg-amber-500/20 text-amber-400 opacity-100 hover:bg-amber-500/30 hover:text-amber-300'
             : 'border border-white/10 bg-white/5 text-text-muted opacity-0 group-hover:opacity-100 hover:border-cyan-400/40 hover:bg-cyan-500/20 hover:text-cyan-400'
         }`}
-        title={isFocused ? 'Click to remove highlight from graph' : 'Click to highlight in graph'}
+        title={
+          isFocused
+            ? t('graph:processes.removeHighlightTitle')
+            : t('graph:processes.highlightTitle')
+        }
         data-testid="process-highlight-button"
       >
         <Lightbulb className="h-4 w-4" />
@@ -541,16 +555,16 @@ const ProcessItem = ({
         }`}
       >
         {isLoading ? (
-          <span className="animate-pulse">Loading...</span>
+          <span className="animate-pulse">{t('graph:processes.loading')}</span>
         ) : isSelected ? (
           <>
             <Eye className="h-3.5 w-3.5" />
-            Viewing
+            {t('graph:processes.viewing')}
           </>
         ) : (
           <>
             <Eye className="h-3.5 w-3.5" />
-            View
+            {t('graph:processes.view')}
           </>
         )}
       </button>

gitnexus-web/src/components/QueryFAB.tsx

@@ -10,31 +10,33 @@ import {
   Table,
 } from '@/lib/lucide-icons';
 import { useAppState } from '../hooks/useAppState';
+import { useTranslation } from 'react-i18next';
 
 const EXAMPLE_QUERIES = [
   {
-    label: 'All Functions',
+    labelKey: 'functions',
     query: `MATCH (n:Function) RETURN n.id AS id, n.name AS name, n.filePath AS path LIMIT 50`,
   },
   {
-    label: 'All Classes',
+    labelKey: 'classes',
     query: `MATCH (n:Class) RETURN n.id AS id, n.name AS name, n.filePath AS path LIMIT 50`,
   },
   {
-    label: 'All Interfaces',
+    labelKey: 'interfaces',
     query: `MATCH (n:Interface) RETURN n.id AS id, n.name AS name, n.filePath AS path LIMIT 50`,
   },
   {
-    label: 'Function Calls',
+    labelKey: 'calls',
     query: `MATCH (a:File)-[r:CodeRelation {type: 'CALLS'}]->(b:Function) RETURN a.id AS id, a.name AS caller, b.name AS callee LIMIT 50`,
   },
   {
-    label: 'Import Dependencies',
+    labelKey: 'imports',
     query: `MATCH (a:File)-[r:CodeRelation {type: 'IMPORTS'}]->(b:File) RETURN a.id AS id, a.name AS from, b.name AS imports LIMIT 50`,
   },
 ];
 
 export const QueryFAB = () => {
+  const { t } = useTranslation(['common', 'graph']);
   const {
     setHighlightedNodeIds,
     setQueryResult,
@@ -86,13 +88,13 @@ export const QueryFAB = () => {
     if (!query.trim() || isRunning) return;
 
     if (!graph) {
-      setError('No project loaded. Load a project first.');
+      setError(t('graph:queryFab.noProject'));
       return;
     }
 
     const ready = await isDatabaseReady();
     if (!ready) {
-      setError('Database not ready. Please wait for loading to complete.');
+      setError(t('graph:queryFab.dbNotReady'));
       return;
     }
 
@@ -147,13 +149,22 @@ export const QueryFAB = () => {
       setQueryResult({ rows, nodeIds, executionTime });
       setHighlightedNodeIds(new Set(nodeIds));
     } catch (err) {
-      setError(err instanceof Error ? err.message : 'Query execution failed');
+      setError(err instanceof Error ? err.message : t('graph:queryFab.executionFailed'));
       setQueryResult(null);
       setHighlightedNodeIds(new Set());
     } finally {
       setIsRunning(false);
     }
-  }, [query, isRunning, graph, isDatabaseReady, runQuery, setHighlightedNodeIds, setQueryResult]);
+  }, [
+    query,
+    isRunning,
+    graph,
+    isDatabaseReady,
+    runQuery,
+    setHighlightedNodeIds,
+    setQueryResult,
+    t,
+  ]);
 
   const handleKeyDown = (e: React.KeyboardEvent) => {
     if (e.key === 'Enter' && (e.ctrlKey || e.metaKey)) {
@@ -189,7 +200,7 @@ export const QueryFAB = () => {
         className="group absolute bottom-4 left-4 z-20 flex items-center gap-2 rounded-xl bg-gradient-to-r from-cyan-500 to-teal-500 px-4 py-2.5 text-sm font-medium text-white shadow-[0_0_20px_rgba(6,182,212,0.4)] transition-all duration-200 hover:-translate-y-0.5 hover:shadow-[0_0_30px_rgba(6,182,212,0.6)]"
       >
         <Terminal className="h-4 w-4" />
-        <span>Query</span>
+        <span>{t('graph:queryFab.query')}</span>
         {queryResult && queryResult.nodeIds.length > 0 && (
           <span className="ml-1 rounded-md bg-white/20 px-1.5 py-0.5 text-xs font-semibold">
             {queryResult.nodeIds.length}
@@ -209,7 +220,7 @@ export const QueryFAB = () => {
           <div className="flex h-7 w-7 items-center justify-center rounded-lg bg-gradient-to-br from-cyan-500 to-teal-500">
             <Terminal className="h-4 w-4 text-white" />
           </div>
-          <span className="text-sm font-medium">Cypher Query</span>
+          <span className="text-sm font-medium">{t('graph:queryFab.cypherQuery')}</span>
         </div>
         <button
           onClick={handleClose}
@@ -239,7 +250,7 @@ export const QueryFAB = () => {
               className="flex items-center gap-1.5 rounded-md px-3 py-1.5 text-xs text-text-secondary transition-colors hover:bg-hover hover:text-text-primary"
             >
               <Sparkles className="h-3.5 w-3.5" />
-              <span>Examples</span>
+              <span>{t('graph:queryFab.examples')}</span>
               <ChevronDown
                 className={`h-3.5 w-3.5 transition-transform ${showExamples ? 'rotate-180' : ''}`}
               />
@@ -249,11 +260,11 @@ export const QueryFAB = () => {
               <div className="absolute bottom-full left-0 mb-2 w-64 animate-fade-in rounded-lg border border-border-subtle bg-surface py-1 shadow-xl">
                 {EXAMPLE_QUERIES.map((example) => (
                   <button
-                    key={example.label}
+                    key={example.labelKey}
                     onClick={() => handleSelectExample(example.query)}
                     className="w-full px-3 py-2 text-left text-sm text-text-secondary transition-colors hover:bg-hover hover:text-text-primary"
                   >
-                    {example.label}
+                    {t(`graph:queryFab.exampleLabels.${example.labelKey}`)}
                   </button>
                 ))}
               </div>
@@ -266,7 +277,7 @@ export const QueryFAB = () => {
                 onClick={handleClear}
                 className="rounded-md px-3 py-1.5 text-xs text-text-secondary transition-colors hover:bg-hover hover:text-text-primary"
               >
-                Clear
+                {t('graph:queryFab.clear')}
               </button>
             )}
             <button
@@ -279,7 +290,7 @@ export const QueryFAB = () => {
               ) : (
                 <Play className="h-3.5 w-3.5" />
               )}
-              <span>Run</span>
+              <span>{t('graph:queryFab.run')}</span>
               <kbd className="ml-1 rounded bg-white/20 px-1 py-0.5 text-[10px]">⌘↵</kbd>
             </button>
           </div>
@@ -297,12 +308,13 @@ export const QueryFAB = () => {
           <div className="flex items-center justify-between bg-cyan-500/5 px-4 py-2.5">
             <div className="flex items-center gap-3 text-xs">
               <span className="text-text-secondary">
-                <span className="font-semibold text-cyan-400">{queryResult.rows.length}</span> rows
+                <span className="font-semibold text-cyan-400">{queryResult.rows.length}</span>{' '}
+                {t('graph:queryFab.rows')}
               </span>
               {queryResult.nodeIds.length > 0 && (
                 <span className="text-text-secondary">
                   <span className="font-semibold text-cyan-400">{queryResult.nodeIds.length}</span>{' '}
-                  highlighted
+                  {t('graph:queryFab.highlighted')}
                 </span>
               )}
               <span className="text-text-muted">{queryResult.executionTime.toFixed(1)}ms</span>
@@ -313,7 +325,7 @@ export const QueryFAB = () => {
                   onClick={clearQueryHighlights}
                   className="text-xs text-text-muted transition-colors hover:text-text-primary"
                 >
-                  Clear
+                  {t('graph:queryFab.clear')}
                 </button>
               )}
               <button
@@ -331,7 +343,7 @@ export const QueryFAB = () => {
           </div>
 
           {showResults && queryResult.rows.length > 0 && (
-            <div className="scrollbar-thin max-h-48 overflow-auto border-t border-border-subtle">
+            <div className="max-h-48 scrollbar-thin overflow-auto border-t border-border-subtle">
               <table className="w-full text-xs">
                 <thead className="sticky top-0 bg-surface">
                   <tr>
@@ -362,7 +374,7 @@ export const QueryFAB = () => {
               </table>
               {queryResult.rows.length > 50 && (
                 <div className="border-t border-border-subtle bg-surface px-3 py-2 text-xs text-text-muted">
-                  Showing 50 of {queryResult.rows.length} rows
+                  {t('graph:queryFab.showingRows', { count: queryResult.rows.length })}
                 </div>
               )}
             </div>

gitnexus-web/src/components/RepoAnalyzer.tsx

@@ -9,6 +9,7 @@
 import { useState, useRef, useEffect, useId } from 'react';
 import {
   Github,
+  Gitlab,
   FolderOpen,
   Loader2,
   Check,
@@ -23,23 +24,35 @@ import {
   type JobProgress,
 } from '../services/backend-client';
 import { AnalyzeProgress } from './AnalyzeProgress';
+import { useTranslation } from 'react-i18next';
 
 // ── Helpers ──────────────────────────────────────────────────────────────────
 
-type InputMode = 'github' | 'local';
+type InputMode = 'github' | 'gitlab' | 'local';
 
 const GITHUB_RE = /^https?:\/\/(www\.)?github\.com\/[^/\s]+\/[^/\s]+/i;
+const GITLAB_RE = /^https?:\/\/[^/\s]+\/[^/\s]+\/[^/\s]+(\/.*)?$/i;
 const IS_WINDOWS = navigator.userAgent.toLowerCase().includes('win');
 
 function isValidGithubUrl(value: string): boolean {
   return GITHUB_RE.test(value.trim());
 }
 
+function isValidGitlabUrl(value: string): boolean {
+  return GITLAB_RE.test(value.trim());
+}
+
 // ── Mode tabs ────────────────────────────────────────────────────────────────
 
 function ModeTabs({ mode, onChange }: { mode: InputMode; onChange: (m: InputMode) => void }) {
+  const { t } = useTranslation('onboarding');
+
   return (
-    <div className="flex gap-1 rounded-lg bg-elevated p-1" role="tablist" aria-label="Input type">
+    <div
+      className="flex gap-1 rounded-lg bg-elevated p-1"
+      role="tablist"
+      aria-label={t('repoAnalyzer.inputType')}
+    >
       <button
         role="tab"
         aria-selected={mode === 'github'}
@@ -51,7 +64,20 @@ function ModeTabs({ mode, onChange }: { mode: InputMode; onChange: (m: InputMode
         } `}
       >
         <Github className="h-3 w-3" />
-        GitHub URL
+        {t('repoAnalyzer.githubUrl')}
+      </button>
+      <button
+        role="tab"
+        aria-selected={mode === 'gitlab'}
+        onClick={() => onChange('gitlab')}
+        className={`flex flex-1 cursor-pointer items-center justify-center gap-1.5 rounded-md px-3 py-1.5 text-xs font-medium transition-all duration-150 ${
+          mode === 'gitlab'
+            ? 'bg-accent text-white shadow-sm'
+            : 'text-text-muted hover:text-text-secondary'
+        } `}
+      >
+        <Gitlab className="h-3 w-3" />
+        {t('repoAnalyzer.gitlabUrl')}
       </button>
       <button
         role="tab"
@@ -64,7 +90,7 @@ function ModeTabs({ mode, onChange }: { mode: InputMode; onChange: (m: InputMode
         } `}
       >
         <FolderOpen className="h-3 w-3" />
-        Local Folder
+        {t('repoAnalyzer.localFolder')}
       </button>
     </div>
   );
@@ -83,6 +109,7 @@ function AnalyzeButton({
   onClick: () => void;
   variant: 'onboarding' | 'sheet';
 }) {
+  const { t } = useTranslation('onboarding');
   const sizeClass =
     variant === 'onboarding' ? 'w-full px-5 py-3.5 text-sm' : 'w-full px-4 py-3 text-sm';
   return (
@@ -96,7 +123,7 @@ function AnalyzeButton({
       } `}
     >
       {isLoading ? <Loader2 className="h-4 w-4 animate-spin" /> : <Sparkles className="h-4 w-4" />}
-      <span>{isLoading ? 'Starting analysis...' : 'Analyze Repository'}</span>
+      <span>{isLoading ? t('repoAnalyzer.starting') : t('repoAnalyzer.analyzeRepository')}</span>
       {canSubmit && !isLoading && <ArrowRight className="h-3.5 w-3.5" />}
     </button>
   );
@@ -105,6 +132,8 @@ function AnalyzeButton({
 // ── Done state ───────────────────────────────────────────────────────────────
 
 function DoneState({ repoName }: { repoName: string }) {
+  const { t } = useTranslation('onboarding');
+
   return (
     <div
       className="flex animate-fade-in flex-col items-center gap-3 py-4"
@@ -115,10 +144,10 @@ function DoneState({ repoName }: { repoName: string }) {
         <Check className="h-6 w-6 text-emerald-400" />
       </div>
       <div className="text-center">
-        <p className="text-sm font-medium text-emerald-400">Analysis complete</p>
+        <p className="text-sm font-medium text-emerald-400">{t('repoAnalyzer.complete')}</p>
         <p className="mt-0.5 font-mono text-xs text-text-muted">{repoName}</p>
       </div>
-      <p className="text-xs text-text-secondary">Loading graph...</p>
+      <p className="text-xs text-text-secondary">{t('repoAnalyzer.loadingGraph')}</p>
     </div>
   );
 }
@@ -134,17 +163,19 @@ export interface RepoAnalyzerProps {
 }
 
 export const RepoAnalyzer = ({ variant, onComplete, onCancel }: RepoAnalyzerProps) => {
+  const { t } = useTranslation(['common', 'errors', 'onboarding']);
   const inputId = useId();
   const folderInputRef = useRef<HTMLInputElement>(null);
   const [mode, setMode] = useState<InputMode>('github');
   const [githubUrl, setGithubUrl] = useState('');
+  const [gitlabUrl, setGitlabUrl] = useState('');
   const [localPath, setLocalPath] = useState('');
   const [phase, setPhase] = useState<InternalPhase>('input');
   const [validationError, setValidationError] = useState<string | null>(null);
   const [progress, setProgress] = useState<JobProgress>({
     phase: 'queued',
     percent: 0,
-    message: 'Queued',
+    message: t('common:analyzePhases.queued'),
   });
   const [completedRepoName, setCompletedRepoName] = useState('');
 
@@ -162,6 +193,7 @@ export const RepoAnalyzer = ({ variant, onComplete, onCancel }: RepoAnalyzerProp
   const handleModeChange = (m: InputMode) => {
     setMode(m);
     setGithubUrl('');
+    setGitlabUrl('');
     setLocalPath('');
     setValidationError(null);
   };
@@ -175,15 +207,21 @@ export const RepoAnalyzer = ({ variant, onComplete, onCancel }: RepoAnalyzerProp
   const canSubmit =
     mode === 'github'
       ? isValidGithubUrl(githubUrl) && (phase === 'input' || phase === 'error')
-      : localPath.trim().length > 1 && (phase === 'input' || phase === 'error');
+      : mode === 'gitlab'
+        ? isValidGitlabUrl(gitlabUrl) && (phase === 'input' || phase === 'error')
+        : localPath.trim().length > 1 && (phase === 'input' || phase === 'error');
 
   const handleAnalyze = async () => {
     if (mode === 'github' && !isValidGithubUrl(githubUrl)) {
-      setValidationError('Please enter a valid GitHub repository URL.');
+      setValidationError(t('errors:invalidGithubUrl'));
+      return;
+    }
+    if (mode === 'gitlab' && !isValidGitlabUrl(gitlabUrl)) {
+      setValidationError('Please enter a valid GitLab repository URL.');
       return;
     }
     if (mode === 'local' && localPath.trim().length < 2) {
-      setValidationError('Please enter a folder path.');
+      setValidationError(t('errors:missingFolderPath'));
       return;
     }
 
@@ -191,18 +229,30 @@ export const RepoAnalyzer = ({ variant, onComplete, onCancel }: RepoAnalyzerProp
     setPhase('starting');
 
     try {
-      const request = mode === 'github' ? { url: githubUrl.trim() } : { path: localPath.trim() };
+      const request =
+        mode === 'github'
+          ? { url: githubUrl.trim() }
+          : mode === 'gitlab'
+            ? { url: gitlabUrl.trim() }
+            : { path: localPath.trim() };
       const { jobId } = await startAnalyze(request);
       jobIdRef.current = jobId;
       setPhase('analyzing');
 
-      const nameSource = mode === 'github' ? githubUrl.trim() : localPath.trim();
+      const nameSource =
+        mode === 'github'
+          ? githubUrl.trim()
+          : mode === 'gitlab'
+            ? gitlabUrl.trim()
+            : localPath.trim();
       const controller = streamAnalyzeProgress(
         jobId,
         (p) => setProgress(p),
         (data) => {
           const name =
-            data.repoName ?? nameSource.split(/[/\\]/).filter(Boolean).at(-1) ?? 'repository';
+            data.repoName ??
+            nameSource.split(/[/\\]/).filter(Boolean).at(-1) ??
+            t('onboarding:repoAnalyzer.defaultRepoName');
           setCompletedRepoName(name);
           setPhase('done');
           sseControllerRef.current = null;
@@ -212,13 +262,13 @@ export const RepoAnalyzer = ({ variant, onComplete, onCancel }: RepoAnalyzerProp
           }, 1200);
         },
         (errMsg) => {
-          setValidationError(errMsg || 'Analysis failed. Check server logs.');
+          setValidationError(errMsg || t('errors:analysisFailed'));
           setPhase('error');
         },
       );
       sseControllerRef.current = controller;
     } catch (err) {
-      setValidationError(err instanceof Error ? err.message : 'Failed to start analysis');
+      setValidationError(err instanceof Error ? err.message : t('errors:startAnalysisFailed'));
       setPhase('error');
     }
   };
@@ -233,7 +283,7 @@ export const RepoAnalyzer = ({ variant, onComplete, onCancel }: RepoAnalyzerProp
       jobIdRef.current = null;
     }
     setPhase('input');
-    setProgress({ phase: 'queued', percent: 0, message: 'Queued' });
+    setProgress({ phase: 'queued', percent: 0, message: t('common:analyzePhases.queued') });
   };
 
   const isLoading = phase === 'starting';
@@ -252,7 +302,7 @@ export const RepoAnalyzer = ({ variant, onComplete, onCancel }: RepoAnalyzerProp
             htmlFor={inputId}
             className="block text-xs font-medium tracking-wider text-text-secondary uppercase"
           >
-            GitHub Repository URL
+            {t('onboarding:repoAnalyzer.githubRepositoryUrl')}
           </label>
           <div
             className={`flex items-center gap-3 rounded-xl border bg-void px-4 py-3.5 transition-all duration-200 ${
@@ -297,6 +347,59 @@ export const RepoAnalyzer = ({ variant, onComplete, onCancel }: RepoAnalyzerProp
         </div>
       )}
 
+      {/* GitLab URL input */}
+      {showInput && mode === 'gitlab' && (
+        <div className="space-y-2">
+          <label
+            htmlFor={inputId}
+            className="block text-xs font-medium tracking-wider text-text-secondary uppercase"
+          >
+            {t('onboarding:repoAnalyzer.gitlabRepositoryUrl')}
+          </label>
+          <div
+            className={`flex items-center gap-3 rounded-xl border bg-void px-4 py-3.5 transition-all duration-200 ${
+              validationError && phase === 'error'
+                ? 'border-red-500/50'
+                : isValidGitlabUrl(gitlabUrl)
+                  ? 'border-accent/50 shadow-[0_0_0_3px_rgba(124,58,237,0.08)]'
+                  : 'border-border-default focus-within:border-accent/40'
+            } `}
+          >
+            <Gitlab className="h-4 w-4 shrink-0 text-text-muted" />
+            <input
+              id={inputId}
+              type="url"
+              value={gitlabUrl}
+              onChange={(e) => {
+                setGitlabUrl(e.target.value);
+                if (validationError) setValidationError(null);
+              }}
+              onKeyDown={(e) => {
+                if (e.key === 'Enter' && canSubmit && !isLoading) {
+                  e.preventDefault();
+                  handleAnalyze();
+                }
+              }}
+              disabled={isLoading}
+              placeholder="https://gitlab.com/owner/repo"
+              autoComplete="url"
+              spellCheck={false}
+              className="flex-1 border-none bg-transparent font-mono text-sm text-text-primary outline-none placeholder:text-text-muted disabled:opacity-50"
+            />
+            {gitlabUrl.length > 10 && (
+              <div className="shrink-0">
+                {isValidGitlabUrl(gitlabUrl) ? (
+                  <Check className="h-3.5 w-3.5 text-emerald-400" />
+                ) : (
+                  <AlertCircle className="h-3.5 w-3.5 text-text-muted" />
+                )}
+              </div>
+            )}
+          </div>
+          <p className="text-xs text-text-muted">{t('onboarding:repoAnalyzer.gitlabSupported')}</p>
+        </div>
+      )}
+
       {/* Local folder input */}
       {showInput && mode === 'local' && (
         <div className="space-y-2">
@@ -304,7 +407,7 @@ export const RepoAnalyzer = ({ variant, onComplete, onCancel }: RepoAnalyzerProp
             htmlFor={`${inputId}-local`}
             className="block text-xs font-medium tracking-wider text-text-secondary uppercase"
           >
-            Local Folder Path
+            {t('onboarding:repoAnalyzer.localFolderPath')}
           </label>
           <div
             className={`flex items-center gap-3 rounded-xl border bg-void px-4 py-3.5 transition-all duration-200 ${
@@ -367,7 +470,7 @@ export const RepoAnalyzer = ({ variant, onComplete, onCancel }: RepoAnalyzerProp
             className="flex w-full cursor-pointer items-center justify-center gap-2 rounded-lg border border-border-subtle bg-elevated px-3 py-2 text-xs font-medium text-text-secondary transition-all duration-150 hover:bg-hover hover:text-text-primary disabled:opacity-50"
           >
             <FolderOpen className="h-3.5 w-3.5" />
-            Browse for folder
+            {t('onboarding:repoAnalyzer.browseForFolder')}
           </button>
         </div>
       )}
@@ -410,14 +513,14 @@ export const RepoAnalyzer = ({ variant, onComplete, onCancel }: RepoAnalyzerProp
             }}
             className="flex-1 cursor-pointer rounded-xl border border-border-subtle bg-elevated px-4 py-2.5 text-sm text-text-secondary transition-all duration-200 hover:bg-hover hover:text-text-primary"
           >
-            Try again
+            {t('common:actions.tryAgain')}
           </button>
           {onCancel && (
             <button
               onClick={onCancel}
               className="cursor-pointer px-4 py-2.5 text-sm text-text-muted transition-colors hover:text-text-secondary"
             >
-              Dismiss
+              {t('common:actions.dismiss')}
             </button>
           )}
         </div>
@@ -429,7 +532,7 @@ export const RepoAnalyzer = ({ variant, onComplete, onCancel }: RepoAnalyzerProp
           onClick={onCancel}
           className="w-full cursor-pointer py-1 text-xs text-text-muted transition-colors hover:text-text-secondary"
         >
-          Hide (analysis continues in background)
+          {t('onboarding:repoAnalyzer.hideBackground')}
         </button>
       )}
     </div>

gitnexus-web/src/components/RepoLanding.tsx

@@ -15,26 +15,29 @@
 import { Sparkles, ArrowRight, GitBranch, FileCode, Layers } from '@/lib/lucide-icons';
 import { RepoAnalyzer } from './RepoAnalyzer';
 import type { BackendRepo } from '../services/backend-client';
+import type { TFunction } from 'i18next';
+import { useTranslation } from 'react-i18next';
 
 // ── Helpers ──────────────────────────────────────────────────────────────────
 
-function formatRelativeTime(dateStr: string): string {
+function formatRelativeTime(dateStr: string, t: TFunction): string {
   const date = new Date(dateStr);
   const now = new Date();
   const diffMs = now.getTime() - date.getTime();
   const diffMins = Math.floor(diffMs / 60_000);
-  if (diffMins < 1) return 'just now';
-  if (diffMins < 60) return `${diffMins}m ago`;
+  if (diffMins < 1) return t('onboarding:landing.time.justNow');
+  if (diffMins < 60) return t('onboarding:landing.time.minutesAgo', { count: diffMins });
   const diffHours = Math.floor(diffMins / 60);
-  if (diffHours < 24) return `${diffHours}h ago`;
+  if (diffHours < 24) return t('onboarding:landing.time.hoursAgo', { count: diffHours });
   const diffDays = Math.floor(diffHours / 24);
-  if (diffDays < 30) return `${diffDays}d ago`;
+  if (diffDays < 30) return t('onboarding:landing.time.daysAgo', { count: diffDays });
   return date.toLocaleDateString();
 }
 
 // ── Repo card ────────────────────────────────────────────────────────────────
 
 function RepoCard({ repo, onClick }: { repo: BackendRepo; onClick: () => void }) {
+  const { t } = useTranslation(['common', 'onboarding']);
   const stats = repo.stats;
 
   return (
@@ -53,7 +56,7 @@ function RepoCard({ repo, onClick }: { repo: BackendRepo; onClick: () => void })
           </div>
           {repo.indexedAt && (
             <p className="mt-1 pl-6 text-xs text-text-muted">
-              Indexed {formatRelativeTime(repo.indexedAt)}
+              {t('onboarding:landing.indexed', { time: formatRelativeTime(repo.indexedAt, t) })}
             </p>
           )}
         </div>
@@ -64,17 +67,18 @@ function RepoCard({ repo, onClick }: { repo: BackendRepo; onClick: () => void })
         <div className="mt-3 flex flex-wrap gap-2 pl-6">
           {stats.files != null && (
             <span className="inline-flex items-center gap-1 rounded-md bg-void px-2 py-0.5 text-[11px] text-text-muted">
-              <FileCode className="h-3 w-3" /> {stats.files.toLocaleString()} files
+              <FileCode className="h-3 w-3" /> {t('common:counts.files', { count: stats.files })}
             </span>
           )}
           {stats.nodes != null && (
             <span className="inline-flex items-center gap-1 rounded-md bg-void px-2 py-0.5 text-[11px] text-text-muted">
-              <Layers className="h-3 w-3" /> {stats.nodes.toLocaleString()} symbols
+              <Layers className="h-3 w-3" /> {t('common:counts.symbols', { count: stats.nodes })}
             </span>
           )}
           {stats.processes != null && stats.processes > 0 && (
             <span className="inline-flex items-center gap-1 rounded-md bg-void px-2 py-0.5 text-[11px] text-text-muted">
-              <Sparkles className="h-3 w-3" /> {stats.processes} flows
+              <Sparkles className="h-3 w-3" />{' '}
+              {t('common:counts.flows', { count: stats.processes })}
             </span>
           )}
         </div>
@@ -92,6 +96,8 @@ interface RepoLandingProps {
 }
 
 export const RepoLanding = ({ repos, onSelectRepo, onAnalyzeComplete }: RepoLandingProps) => {
+  const { t } = useTranslation('onboarding');
+
   return (
     <div className="relative animate-fade-in overflow-hidden rounded-3xl border border-border-default bg-surface p-7">
       {/* Ambient glows — mirrors OnboardingGuide aesthetic */}
@@ -109,10 +115,10 @@ export const RepoLanding = ({ repos, onSelectRepo, onAnalyzeComplete }: RepoLand
           </div>
 
           <h2 className="text-lg leading-snug font-semibold text-text-primary">
-            Choose a repository
+            {t('landing.chooseRepository')}
           </h2>
           <p className="mx-auto mt-1.5 max-w-xs text-sm leading-relaxed text-text-secondary">
-            Select an indexed repository to explore, or analyze a new one.
+            {t('landing.description')}
           </p>
         </div>
       </div>
@@ -128,7 +134,7 @@ export const RepoLanding = ({ repos, onSelectRepo, onAnalyzeComplete }: RepoLand
       <div className="mb-5 flex items-center gap-3">
         <div className="h-px flex-1 bg-border-subtle" />
         <span className="text-[11px] tracking-widest text-text-muted uppercase">
-          or analyze new
+          {t('landing.orAnalyzeNew')}
         </span>
         <div className="h-px flex-1 bg-border-subtle" />
       </div>
@@ -140,8 +146,7 @@ export const RepoLanding = ({ repos, onSelectRepo, onAnalyzeComplete }: RepoLand
 
       {/* Footer hint */}
       <p className="mt-5 text-center text-[11px] leading-relaxed text-text-muted">
-        Public &amp; private repos &middot; Cloned locally by the server &middot; No data leaves
-        your machine
+        {t('landing.footer')}
       </p>
     </div>
   );

gitnexus-web/src/components/RightPanel.tsx

@@ -16,7 +16,9 @@ import { ToolCallCard } from './ToolCallCard';
 import { isProviderConfigured } from '../core/llm/settings-service';
 import { MarkdownRenderer } from './MarkdownRenderer';
 import { ProcessesPanel } from './ProcessesPanel';
+import { useTranslation } from 'react-i18next';
 export const RightPanel = () => {
+  const { t } = useTranslation(['chat', 'common']);
   const {
     isRightPanelOpen,
     setRightPanelOpen,
@@ -202,10 +204,10 @@ export const RightPanel = () => {
   };
 
   const chatSuggestions = [
-    'Explain the project architecture',
-    'What does this project do?',
-    'Show me the most important files',
-    'Find all API handlers',
+    t('chat:suggestions.architecture'),
+    t('chat:suggestions.whatDoes'),
+    t('chat:suggestions.importantFiles'),
+    t('chat:suggestions.apiHandlers'),
   ];
 
   if (!isRightPanelOpen) return null;
@@ -225,7 +227,7 @@ export const RightPanel = () => {
             }`}
           >
             <Sparkles className="h-3.5 w-3.5" />
-            <span>Nexus AI</span>
+            <span>{t('chat:tabs.chat')}</span>
           </button>
 
           {/* Processes Tab */}
@@ -238,9 +240,9 @@ export const RightPanel = () => {
             }`}
           >
             <GitBranch className="h-3.5 w-3.5" />
-            <span>Processes</span>
+            <span>{t('chat:tabs.processes')}</span>
             <span className="rounded-full bg-gradient-to-r from-violet-500 to-fuchsia-500 px-1.5 py-0.5 text-[10px] font-semibold text-white">
-              NEW
+              {t('chat:newBadge')}
             </span>
           </button>
         </div>
@@ -249,7 +251,7 @@ export const RightPanel = () => {
         <button
           onClick={() => setRightPanelOpen(false)}
           className="rounded p-1.5 text-text-muted transition-colors hover:bg-hover hover:text-text-primary"
-          title="Close Panel"
+          title={t('chat:actions.closePanel')}
         >
           <PanelRightClose className="h-4 w-4" />
         </button>
@@ -270,12 +272,12 @@ export const RightPanel = () => {
             <div className="ml-auto flex items-center gap-2">
               {!isAgentReady && (
                 <span className="rounded-full border border-amber-500/30 bg-amber-500/15 px-2 py-1 text-[11px] text-amber-300">
-                  Configure AI
+                  {t('chat:badges.configureAI')}
                 </span>
               )}
               {isAgentInitializing && (
                 <span className="flex items-center gap-1 rounded-full border border-border-subtle bg-surface px-2 py-1 text-[11px] text-text-muted">
-                  <Loader2 className="h-3 w-3 animate-spin" /> Connecting
+                  <Loader2 className="h-3 w-3 animate-spin" /> {t('chat:badges.connecting')}
                 </span>
               )}
             </div>
@@ -290,16 +292,15 @@ export const RightPanel = () => {
           )}
 
           {/* Messages */}
-          <div ref={scrollContainerRef} className="scrollbar-thin flex-1 overflow-y-auto p-4">
+          <div ref={scrollContainerRef} className="flex-1 scrollbar-thin overflow-y-auto p-4">
             {chatMessages.length === 0 ? (
               <div className="flex h-full flex-col items-center justify-center px-4 text-center">
                 <div className="mb-4 flex h-14 w-14 items-center justify-center rounded-xl bg-gradient-to-br from-accent to-node-interface text-2xl shadow-glow">
                   🧠
                 </div>
-                <h3 className="mb-2 text-base font-medium">Ask me anything</h3>
+                <h3 className="mb-2 text-base font-medium">{t('chat:empty.title')}</h3>
                 <p className="mb-5 text-sm leading-relaxed text-text-secondary">
-                  I can help you understand the architecture, find functions, or explain
-                  connections.
+                  {t('chat:empty.description')}
                 </p>
                 <div className="flex flex-wrap justify-center gap-2">
                   {chatSuggestions.map((suggestion) => (
@@ -323,7 +324,7 @@ export const RightPanel = () => {
                         <div className="mb-2 flex items-center gap-2">
                           <User className="h-4 w-4 text-text-muted" />
                           <span className="text-xs font-medium tracking-wide text-text-muted uppercase">
-                            You
+                            {t('chat:roles.you')}
                           </span>
                         </div>
                         <div className="pl-6 text-sm text-text-primary">{message.content}</div>
@@ -336,7 +337,7 @@ export const RightPanel = () => {
                         <div className="mb-3 flex items-center gap-2">
                           <Sparkles className="h-4 w-4 text-accent" />
                           <span className="text-xs font-medium tracking-wide text-text-muted uppercase">
-                            Nexus AI
+                            {t('chat:roles.assistant')}
                           </span>
                           {isChatLoading && message === chatMessages[chatMessages.length - 1] && (
                             <Loader2 className="h-3 w-3 animate-spin text-accent" />
@@ -394,7 +395,7 @@ export const RightPanel = () => {
 
           {/* Scroll to bottom */}
           <button
-            aria-label="Scroll to bottom"
+            aria-label={t('chat:actions.scrollBottom')}
             onClick={() => scrollToBottom()}
             className={`absolute bottom-20 left-1/2 z-10 -translate-x-1/2 rounded-full border border-border-subtle bg-elevated px-3 py-1.5 text-xs text-text-secondary shadow-lg transition-all duration-200 hover:border-accent hover:text-accent ${
               !isAtBottom && chatMessages.length > 0
@@ -403,7 +404,7 @@ export const RightPanel = () => {
             }`}
           >
             <ArrowDown className="mr-1 inline h-3.5 w-3.5" />
-            Scroll to bottom
+            {t('chat:actions.scrollBottom')}
           </button>
 
           {/* Input */}
@@ -414,23 +415,23 @@ export const RightPanel = () => {
                 value={chatInput}
                 onChange={(e) => setChatInput(e.target.value)}
                 onKeyDown={handleKeyDown}
-                placeholder="Ask about the codebase..."
+                placeholder={t('chat:input.placeholder')}
                 rows={1}
-                className="scrollbar-thin min-h-[36px] flex-1 resize-none border-none bg-transparent text-sm text-text-primary outline-none placeholder:text-text-muted"
+                className="min-h-[36px] flex-1 resize-none scrollbar-thin border-none bg-transparent text-sm text-text-primary outline-none placeholder:text-text-muted"
                 style={{ height: '36px', overflowY: 'hidden' }}
               />
               <button
                 onClick={clearChat}
                 className="px-2 py-1 text-xs text-text-muted transition-colors hover:text-text-primary"
-                title="Clear chat"
+                title={t('chat:actions.clearChat')}
               >
-                Clear
+                {t('common:actions.clear')}
               </button>
               {isChatLoading ? (
                 <button
                   onClick={stopChatResponse}
                   className="flex h-9 w-9 items-center justify-center rounded-md bg-red-500/80 text-white transition-all hover:bg-red-500"
-                  title="Stop response"
+                  title={t('chat:actions.stopResponse')}
                 >
                   <Square className="h-3.5 w-3.5 fill-current" />
                 </button>
@@ -449,8 +450,8 @@ export const RightPanel = () => {
                 <AlertTriangle className="h-3.5 w-3.5" />
                 <span>
                   {isProviderConfigured()
-                    ? 'Initializing AI agent...'
-                    : 'Configure an LLM provider to enable chat.'}
+                    ? t('chat:input.initializing')
+                    : t('chat:input.configureProvider')}
                 </span>
               </div>
             )}

gitnexus-web/src/components/SettingsPanel.tsx

@@ -23,6 +23,7 @@ import {
 import type { LLMSettings, LLMProvider } from '../core/llm/types';
 import { DEFAULT_OLLAMA_BASE_URL } from '../config/ui-constants';
 import { ProviderConfigCard } from './settings/ProviderConfigCard';
+import { useTranslation } from 'react-i18next';
 
 interface SettingsPanelProps {
   isOpen: boolean;
@@ -51,6 +52,7 @@ const OpenRouterModelCombobox = ({
   isLoading,
   onLoadModels,
 }: OpenRouterModelComboboxProps) => {
+  const { t } = useTranslation('settings');
   const [isOpen, setIsOpen] = useState(false);
   const [searchTerm, setSearchTerm] = useState('');
   const inputRef = useRef<HTMLInputElement>(null);
@@ -142,7 +144,7 @@ const OpenRouterModelCombobox = ({
             value={searchTerm}
             onChange={handleInputChange}
             onKeyDown={handleKeyDown}
-            placeholder="Search or type model ID..."
+            placeholder={t('searchModelPlaceholder')}
             className="flex-1 bg-transparent font-mono text-sm text-text-primary outline-none placeholder:text-text-muted"
             onClick={(e) => e.stopPropagation()}
           />
@@ -150,7 +152,7 @@ const OpenRouterModelCombobox = ({
           <span
             className={`flex-1 truncate font-mono text-sm ${value ? 'text-text-primary' : 'text-text-muted'}`}
           >
-            {displayValue || 'Select or type a model...'}
+            {displayValue || t('selectModelPlaceholder')}
           </span>
         )}
         <div className="flex items-center gap-1">
@@ -167,20 +169,20 @@ const OpenRouterModelCombobox = ({
           {isLoading ? (
             <div className="flex items-center justify-center gap-2 px-4 py-6 text-center text-sm text-text-muted">
               <Loader2 className="h-4 w-4 animate-spin" />
-              Loading models...
+              {t('loadingModels')}
             </div>
           ) : filteredModels.length === 0 ? (
             <div className="px-4 py-4 text-center">
               {models.length === 0 ? (
                 <div className="text-sm text-text-muted">
                   <Search className="mx-auto mb-2 h-5 w-5 opacity-50" />
-                  <p>Type a model ID or press Enter</p>
-                  <p className="mt-1 text-xs">e.g. openai/gpt-4o</p>
+                  <p>{t('customModelHint')}</p>
+                  <p className="mt-1 text-xs">{t('customModelExample')}</p>
                 </div>
               ) : (
                 <div className="text-sm text-text-muted">
-                  <p>No models match "{searchTerm}"</p>
-                  <p className="mt-1 text-xs">Press Enter to use as custom ID</p>
+                  <p>{t('noModelsMatch', { searchTerm })}</p>
+                  <p className="mt-1 text-xs">{t('pressEnterCustom')}</p>
                 </div>
               )}
             </div>
@@ -198,7 +200,7 @@ const OpenRouterModelCombobox = ({
               ))}
               {filteredModels.length > 50 && (
                 <div className="border-t border-border-subtle px-4 py-2 text-center text-xs text-text-muted">
-                  +{filteredModels.length - 50} more • Refine your search
+                  {t('moreModels', { count: filteredModels.length - 50 })}
                 </div>
               )}
             </div>
@@ -248,6 +250,7 @@ export const SettingsPanel = ({
   isBackendConnected,
   onBackendUrlChange,
 }: SettingsPanelProps) => {
+  const { t } = useTranslation(['common', 'settings']);
   const [settings, setSettings] = useState<LLMSettings>(loadSettings);
   const [showApiKey, setShowApiKey] = useState<Record<string, boolean>>({});
   const [saveStatus, setSaveStatus] = useState<'idle' | 'saved' | 'error'>('idle');
@@ -338,6 +341,7 @@ export const SettingsPanel = ({
     'openrouter',
     'minimax',
     'glm',
+    'deepseek',
   ];
 
   return (
@@ -354,8 +358,8 @@ export const SettingsPanel = ({
               <Brain className="h-5 w-5 text-accent" />
             </div>
             <div>
-              <h2 className="text-lg font-semibold text-text-primary">AI Settings</h2>
-              <p className="text-xs text-text-muted">Configure your LLM provider</p>
+              <h2 className="text-lg font-semibold text-text-primary">{t('settings:title')}</h2>
+              <p className="text-xs text-text-muted">{t('settings:subtitle')}</p>
             </div>
           </div>
           <button
@@ -371,16 +375,18 @@ export const SettingsPanel = ({
           {/* Local Server */}
           {backendUrl !== undefined && onBackendUrlChange && (
             <div className="space-y-3">
-              <label className="block text-sm font-medium text-text-secondary">Local Server</label>
+              <label className="block text-sm font-medium text-text-secondary">
+                {t('settings:localServer')}
+              </label>
               <div className="space-y-2">
                 <div className="mb-2 flex items-center gap-2">
                   <Server className="h-4 w-4 text-text-muted" />
-                  <span className="text-sm text-text-secondary">Backend URL</span>
+                  <span className="text-sm text-text-secondary">{t('settings:backendUrl')}</span>
                   <span
                     className={`h-2 w-2 rounded-full ${isBackendConnected ? 'bg-green-400' : 'bg-red-400'}`}
                   />
                   <span className="text-xs text-text-muted">
-                    {isBackendConnected ? 'Connected' : 'Not connected'}
+                    {isBackendConnected ? t('settings:connected') : t('settings:notConnected')}
                   </span>
                 </div>
                 <input
@@ -390,17 +396,16 @@ export const SettingsPanel = ({
                   placeholder="http://localhost:4747"
                   className="w-full rounded-xl border border-border-subtle bg-elevated px-4 py-3 font-mono text-sm text-text-primary transition-all outline-none placeholder:text-text-muted focus:border-accent focus:ring-2 focus:ring-accent/20"
                 />
-                <p className="text-xs text-text-muted">
-                  Run <code className="rounded bg-elevated px-1 py-0.5">gitnexus serve</code> to
-                  start the local server
-                </p>
+                <p className="text-xs text-text-muted">{t('settings:runServeHint')}</p>
               </div>
             </div>
           )}
 
           {/* Provider Selection */}
           <div className="space-y-3">
-            <label className="block text-sm font-medium text-text-secondary">Provider</label>
+            <label className="block text-sm font-medium text-text-secondary">
+              {t('settings:provider')}
+            </label>
             <div className="grid grid-cols-1 gap-3 sm:grid-cols-3">
               {providers.map((provider) => (
                 <button
@@ -429,7 +434,9 @@ export const SettingsPanel = ({
                                 ? '⚡'
                                 : provider === 'glm'
                                   ? '🔮'
-                                  : '☁️'}
+                                  : provider === 'deepseek'
+                                    ? '🐋'
+                                    : '☁️'}
                   </div>
                   <span className="font-medium">{getProviderDisplayName(provider)}</span>
                 </button>
@@ -438,7 +445,7 @@ export const SettingsPanel = ({
           </div>
 
           <div className="rounded-xl border border-amber-500/30 bg-amber-500/10 p-3 text-xs text-amber-200">
-            API keys are stored in session storage and will be cleared when you close this tab.
+            {t('settings:apiKeySession')}
           </div>
 
           {/* OpenAI Settings */}
@@ -447,10 +454,10 @@ export const SettingsPanel = ({
               title="OpenAI"
               apiKey={{
                 value: settings.openai?.apiKey ?? '',
-                placeholder: 'Enter your OpenAI API key',
-                helperText: 'Get your API key from',
+                placeholder: t('settings:providers.openai.apiKeyPlaceholder'),
+                helperText: t('settings:providers.openai.helperText'),
                 helperLink: 'https://platform.openai.com/api-keys',
-                helperLinkLabel: 'OpenAI Platform',
+                helperLinkLabel: t('settings:providers.openai.helperLinkLabel'),
                 isVisible: !!showApiKey['openai'],
                 onChange: (value) =>
                   setSettings((prev) => ({
@@ -461,7 +468,7 @@ export const SettingsPanel = ({
               }}
               model={{
                 value: settings.openai?.model ?? 'gpt-5.2-chat',
-                placeholder: 'e.g., gpt-4o, gpt-4-turbo, gpt-3.5-turbo',
+                placeholder: t('settings:providers.openai.modelPlaceholder'),
                 onChange: (value) =>
                   setSettings((prev) => ({
                     ...prev,
@@ -472,7 +479,8 @@ export const SettingsPanel = ({
               <div className="space-y-2">
                 <label className="flex items-center gap-2 text-sm font-medium text-text-secondary">
                   <Server className="h-4 w-4" />
-                  Base URL <span className="font-normal text-text-muted">(optional)</span>
+                  {t('settings:baseUrl')}{' '}
+                  <span className="font-normal text-text-muted">({t('settings:optional')})</span>
                 </label>
                 <input
                   type="url"
@@ -483,12 +491,11 @@ export const SettingsPanel = ({
                       openai: { ...prev.openai!, baseUrl: e.target.value },
                     }))
                   }
-                  placeholder="https://api.openai.com/v1 (default)"
+                  placeholder={t('settings:providers.openai.baseUrlPlaceholder')}
                   className="w-full rounded-xl border border-border-subtle bg-elevated px-4 py-3 text-text-primary transition-all outline-none placeholder:text-text-muted focus:border-accent focus:ring-2 focus:ring-accent/20"
                 />
                 <p className="text-xs text-text-muted">
-                  Leave empty to use the default OpenAI API. Set a custom URL for proxies or
-                  compatible APIs.
+                  {t('settings:providers.openai.baseUrlHint')}
                 </p>
               </div>
             </ProviderConfigCard>
@@ -500,10 +507,10 @@ export const SettingsPanel = ({
               title="Google Gemini"
               apiKey={{
                 value: settings.gemini?.apiKey ?? '',
-                placeholder: 'Enter your Google AI API key',
-                helperText: 'Get your API key from',
+                placeholder: t('settings:providers.gemini.apiKeyPlaceholder'),
+                helperText: t('settings:providers.gemini.helperText'),
                 helperLink: 'https://aistudio.google.com/app/apikey',
-                helperLinkLabel: 'Google AI Studio',
+                helperLinkLabel: t('settings:providers.gemini.helperLinkLabel'),
                 isVisible: !!showApiKey['gemini'],
                 onChange: (value) =>
                   setSettings((prev) => ({
@@ -514,7 +521,7 @@ export const SettingsPanel = ({
               }}
               model={{
                 value: settings.gemini?.model ?? 'gemini-2.0-flash',
-                placeholder: 'e.g., gemini-2.0-flash, gemini-1.5-pro',
+                placeholder: t('settings:providers.gemini.modelPlaceholder'),
                 onChange: (value) =>
                   setSettings((prev) => ({
                     ...prev,
@@ -530,10 +537,10 @@ export const SettingsPanel = ({
               title="Anthropic"
               apiKey={{
                 value: settings.anthropic?.apiKey ?? '',
-                placeholder: 'Enter your Anthropic API key',
-                helperText: 'Get your API key from',
+                placeholder: t('settings:providers.anthropic.apiKeyPlaceholder'),
+                helperText: t('settings:providers.anthropic.helperText'),
                 helperLink: 'https://console.anthropic.com/settings/keys',
-                helperLinkLabel: 'Anthropic Console',
+                helperLinkLabel: t('settings:providers.anthropic.helperLinkLabel'),
                 isVisible: !!showApiKey['anthropic'],
                 onChange: (value) =>
                   setSettings((prev) => ({
@@ -544,7 +551,7 @@ export const SettingsPanel = ({
               }}
               model={{
                 value: settings.anthropic?.model ?? 'claude-sonnet-4-20250514',
-                placeholder: 'e.g., claude-sonnet-4-20250514, claude-3-opus',
+                placeholder: t('settings:providers.anthropic.modelPlaceholder'),
                 onChange: (value) =>
                   setSettings((prev) => ({
                     ...prev,
@@ -560,7 +567,7 @@ export const SettingsPanel = ({
               <div className="space-y-2">
                 <label className="flex items-center gap-2 text-sm font-medium text-text-secondary">
                   <Key className="h-4 w-4" />
-                  API Key
+                  {t('settings:apiKey')}
                 </label>
                 <div className="relative">
                   <input
@@ -572,7 +579,7 @@ export const SettingsPanel = ({
                         azureOpenAI: { ...prev.azureOpenAI!, apiKey: e.target.value },
                       }))
                     }
-                    placeholder="Enter your Azure OpenAI API key"
+                    placeholder={t('settings:providers.azure.apiKeyPlaceholder')}
                     className="w-full rounded-xl border border-border-subtle bg-elevated px-4 py-3 pr-12 text-text-primary transition-all outline-none placeholder:text-text-muted focus:border-accent focus:ring-2 focus:ring-accent/20"
                   />
                   <button
@@ -592,7 +599,7 @@ export const SettingsPanel = ({
               <div className="space-y-2">
                 <label className="flex items-center gap-2 text-sm font-medium text-text-secondary">
                   <Server className="h-4 w-4" />
-                  Endpoint
+                  {t('settings:endpoint')}
                 </label>
                 <input
                   type="url"
@@ -609,7 +616,9 @@ export const SettingsPanel = ({
               </div>
 
               <div className="space-y-2">
-                <label className="text-sm font-medium text-text-secondary">Deployment Name</label>
+                <label className="text-sm font-medium text-text-secondary">
+                  {t('settings:deploymentName')}
+                </label>
                 <input
                   type="text"
                   value={settings.azureOpenAI?.deploymentName ?? ''}
@@ -619,14 +628,16 @@ export const SettingsPanel = ({
                       azureOpenAI: { ...prev.azureOpenAI!, deploymentName: e.target.value },
                     }))
                   }
-                  placeholder="e.g., gpt-4o-deployment"
+                  placeholder={t('settings:providers.azure.deploymentNamePlaceholder')}
                   className="w-full rounded-xl border border-border-subtle bg-elevated px-4 py-3 text-text-primary transition-all outline-none placeholder:text-text-muted focus:border-accent focus:ring-2 focus:ring-accent/20"
                 />
               </div>
 
               <div className="grid grid-cols-2 gap-4">
                 <div className="space-y-2">
-                  <label className="text-sm font-medium text-text-secondary">Model</label>
+                  <label className="text-sm font-medium text-text-secondary">
+                    {t('settings:model')}
+                  </label>
                   <input
                     type="text"
                     value={settings.azureOpenAI?.model ?? 'gpt-4o'}
@@ -642,7 +653,9 @@ export const SettingsPanel = ({
                 </div>
 
                 <div className="space-y-2">
-                  <label className="text-sm font-medium text-text-secondary">API Version</label>
+                  <label className="text-sm font-medium text-text-secondary">
+                    {t('settings:apiVersion')}
+                  </label>
                   <input
                     type="text"
                     value={settings.azureOpenAI?.apiVersion ?? '2024-08-01-preview'}
@@ -659,14 +672,14 @@ export const SettingsPanel = ({
               </div>
 
               <p className="text-xs text-text-muted">
-                Configure your Azure OpenAI service in the{' '}
+                {t('settings:azureHint')}{' '}
                 <a
                   href="https://portal.azure.com/#view/Microsoft_Azure_ProjectOxford/CognitiveServicesHub/~/OpenAI"
                   target="_blank"
                   rel="noopener noreferrer"
                   className="text-accent hover:underline"
                 >
-                  Azure Portal
+                  {t('settings:azurePortal')}
                 </a>
               </p>
             </div>
@@ -678,7 +691,8 @@ export const SettingsPanel = ({
               {/* How to run Ollama */}
               <div className="rounded-xl border border-amber-500/30 bg-amber-500/10 p-3">
                 <p className="text-xs leading-relaxed text-amber-300">
-                  <span className="font-medium">📋 Quick Start:</span> Install Ollama from{' '}
+                  <span className="font-medium">{t('settings:providers.ollama.quickStart')}</span>{' '}
+                  {t('settings:providers.ollama.installFrom')}{' '}
                   <a
                     href="https://ollama.ai"
                     target="_blank"
@@ -687,7 +701,7 @@ export const SettingsPanel = ({
                   >
                     ollama.ai
                   </a>
-                  , then run:
+                  {t('settings:providers.ollama.thenRun')}
                 </p>
                 <code className="mt-2 block rounded-lg bg-black/30 px-3 py-2 font-mono text-sm text-amber-200">
                   ollama serve
@@ -697,7 +711,7 @@ export const SettingsPanel = ({
               <div className="space-y-2">
                 <label className="flex items-center gap-2 text-sm font-medium text-text-secondary">
                   <Server className="h-4 w-4" />
-                  Base URL
+                  {t('settings:baseUrl')}
                 </label>
                 <div className="flex gap-2">
                   <input
@@ -719,18 +733,21 @@ export const SettingsPanel = ({
                     }
                     disabled={isCheckingOllama}
                     className="rounded-xl border border-border-subtle bg-elevated px-3 py-3 text-text-secondary transition-colors hover:border-accent/50 hover:text-text-primary disabled:opacity-50"
-                    title="Check connection"
+                    title={t('settings:checkConnection')}
                   >
                     <RefreshCw className={`h-4 w-4 ${isCheckingOllama ? 'animate-spin' : ''}`} />
                   </button>
                 </div>
                 <p className="text-xs text-text-muted">
-                  Default port is <code className="rounded bg-elevated px-1 py-0.5">11434</code>.
+                  {t('settings:defaultPort')}{' '}
+                  <code className="rounded bg-elevated px-1 py-0.5">11434</code>.
                 </p>
               </div>
 
               <div className="space-y-2">
-                <label className="text-sm font-medium text-text-secondary">Model</label>
+                <label className="text-sm font-medium text-text-secondary">
+                  {t('settings:model')}
+                </label>
 
                 {ollamaError && !isCheckingOllama && (
                   <div className="rounded-lg border border-red-500/30 bg-red-500/10 p-2">
@@ -750,11 +767,11 @@ export const SettingsPanel = ({
                       ollama: { ...prev.ollama!, model: e.target.value },
                     }))
                   }
-                  placeholder="e.g., llama3.2, mistral, codellama"
+                  placeholder={t('settings:providers.ollama.modelPlaceholder')}
                   className="w-full rounded-xl border border-border-subtle bg-elevated px-4 py-3 font-mono text-sm text-text-primary transition-all outline-none placeholder:text-text-muted focus:border-accent focus:ring-2 focus:ring-accent/20"
                 />
                 <p className="text-xs text-text-muted">
-                  Pull a model with{' '}
+                  {t('settings:pullModel')}{' '}
                   <code className="rounded bg-elevated px-1 py-0.5">ollama pull llama3.2</code>
                 </p>
               </div>
@@ -767,10 +784,10 @@ export const SettingsPanel = ({
               title="OpenRouter"
               apiKey={{
                 value: settings.openrouter?.apiKey ?? '',
-                placeholder: 'Enter your OpenRouter API key',
-                helperText: 'Get your API key from',
+                placeholder: t('settings:providers.openrouter.apiKeyPlaceholder'),
+                helperText: t('settings:providers.openrouter.helperText'),
                 helperLink: 'https://openrouter.ai/keys',
-                helperLinkLabel: 'OpenRouter Keys',
+                helperLinkLabel: t('settings:providers.openrouter.helperLinkLabel'),
                 isVisible: !!showApiKey['openrouter'],
                 onChange: (value) =>
                   setSettings((prev) => ({
@@ -781,7 +798,9 @@ export const SettingsPanel = ({
               }}
             >
               <div className="space-y-2">
-                <label className="text-sm font-medium text-text-secondary">Model</label>
+                <label className="text-sm font-medium text-text-secondary">
+                  {t('settings:model')}
+                </label>
                 <OpenRouterModelCombobox
                   value={settings.openrouter?.model ?? ''}
                   onChange={(model) =>
@@ -795,14 +814,14 @@ export const SettingsPanel = ({
                   onLoadModels={loadOpenRouterModels}
                 />
                 <p className="text-xs text-text-muted">
-                  Browse all models at{' '}
+                  {t('settings:browseModels')}{' '}
                   <a
                     href="https://openrouter.ai/models"
                     target="_blank"
                     rel="noopener noreferrer"
                     className="text-accent hover:underline"
                   >
-                    OpenRouter Models
+                    {t('settings:openRouterModels')}
                   </a>
                 </p>
               </div>
@@ -815,10 +834,10 @@ export const SettingsPanel = ({
               title="MiniMax"
               apiKey={{
                 value: settings.minimax?.apiKey ?? '',
-                placeholder: 'Enter your MiniMax API key',
-                helperText: 'Get your API key from',
+                placeholder: t('settings:providers.minimax.apiKeyPlaceholder'),
+                helperText: t('settings:providers.minimax.helperText'),
                 helperLink: 'https://platform.minimax.io',
-                helperLinkLabel: 'MiniMax Platform',
+                helperLinkLabel: t('settings:providers.minimax.helperLinkLabel'),
                 isVisible: !!showApiKey['minimax'],
                 onChange: (value) =>
                   setSettings((prev) => ({
@@ -829,24 +848,61 @@ export const SettingsPanel = ({
               }}
               model={{
                 value: settings.minimax?.model ?? 'MiniMax-M2.5',
-                placeholder: 'e.g., MiniMax-M2.5, MiniMax-M2.5-highspeed',
+                placeholder: t('settings:providers.minimax.modelPlaceholder'),
                 onChange: (value) =>
                   setSettings((prev) => ({
                     ...prev,
                     minimax: { ...prev.minimax!, model: value },
                   })),
-                helperText: 'Available: MiniMax-M2.5 (default), MiniMax-M2.5-highspeed (faster)',
+                helperText: t('settings:providers.minimax.helperModel'),
               }}
             />
           )}
 
+          {/* DeepSeek Settings */}
+          {settings.activeProvider === 'deepseek' && (
+            <ProviderConfigCard
+              title="DeepSeek"
+              apiKey={{
+                value: settings.deepseek?.apiKey ?? '',
+                placeholder: 'Enter your DeepSeek API key',
+                helperText: 'Get your API key from',
+                helperLink: 'https://platform.deepseek.com/api_keys',
+                helperLinkLabel: 'DeepSeek Platform',
+                isVisible: !!showApiKey['deepseek'],
+                onChange: (value) =>
+                  setSettings((prev) => ({
+                    ...prev,
+                    deepseek: { ...prev.deepseek!, apiKey: value },
+                  })),
+                onToggleVisibility: () => toggleApiKeyVisibility('deepseek'),
+              }}
+              model={{
+                value: settings.deepseek?.model ?? 'deepseek-v4-flash',
+                placeholder: 'e.g., deepseek-v4-flash, deepseek-v4-pro, deepseek-chat',
+                onChange: (value) =>
+                  setSettings((prev) => ({
+                    ...prev,
+                    deepseek: { ...prev.deepseek!, model: value },
+                  })),
+                helperText:
+                  'deepseek-v4-flash (default), deepseek-v4-pro, deepseek-chat (V3), deepseek-reasoner (R1)',
+              }}
+            >
+              <p className="text-xs text-text-muted">
+                Compatible via OpenAI API format. The deepseek-reasoner model uses thinking mode and
+                requires round-tripping reasoning content.
+              </p>
+            </ProviderConfigCard>
+          )}
+
           {/* GLM Settings */}
           {settings.activeProvider === 'glm' && (
             <div className="animate-fade-in space-y-4">
               <div className="space-y-2">
                 <label className="flex items-center gap-2 text-sm font-medium text-text-secondary">
                   <Key className="h-4 w-4" />
-                  API Key
+                  {t('settings:apiKey')}
                 </label>
                 <div className="relative">
                   <input
@@ -858,7 +914,7 @@ export const SettingsPanel = ({
                         glm: { ...prev.glm!, apiKey: e.target.value },
                       }))
                     }
-                    placeholder="Enter your Z.AI API key"
+                    placeholder={t('settings:providers.glm.apiKeyPlaceholder')}
                     className="w-full rounded-xl border border-border-subtle bg-elevated px-4 py-3 pr-12 text-text-primary transition-all outline-none placeholder:text-text-muted focus:border-accent focus:ring-2 focus:ring-accent/20"
                   />
                   <button
@@ -874,20 +930,22 @@ export const SettingsPanel = ({
                   </button>
                 </div>
                 <p className="text-xs text-text-muted">
-                  Get your API key from{' '}
+                  {t('settings:providers.openai.helperText')}{' '}
                   <a
                     href="https://docs.z.ai"
                     target="_blank"
                     rel="noopener noreferrer"
                     className="text-accent hover:underline"
                   >
-                    Z.AI Platform
+                    {t('settings:zaiPlatform')}
                   </a>
                 </p>
               </div>
 
               <div className="space-y-2">
-                <label className="text-sm font-medium text-text-secondary">Model</label>
+                <label className="text-sm font-medium text-text-secondary">
+                  {t('settings:model')}
+                </label>
                 <select
                   value={settings.glm?.model ?? 'GLM-5'}
                   onChange={(e) =>
@@ -907,7 +965,9 @@ export const SettingsPanel = ({
               </div>
 
               <div className="space-y-2">
-                <label className="text-sm font-medium text-text-secondary">Base URL</label>
+                <label className="text-sm font-medium text-text-secondary">
+                  {t('settings:baseUrl')}
+                </label>
                 <input
                   type="text"
                   value={settings.glm?.baseUrl ?? 'https://api.z.ai/api/coding/paas/v4'}
@@ -920,9 +980,7 @@ export const SettingsPanel = ({
                   placeholder="https://api.z.ai/api/coding/paas/v4"
                   className="w-full rounded-xl border border-border-subtle bg-elevated px-4 py-3 font-mono text-sm text-text-primary transition-all outline-none placeholder:text-text-muted focus:border-accent focus:ring-2 focus:ring-accent/20"
                 />
-                <p className="text-xs text-text-muted">
-                  Coding API (default). Use https://api.z.ai/api/paas/v4 for the general API.
-                </p>
+                <p className="text-xs text-text-muted">{t('settings:glmCodingApi')}</p>
               </div>
             </div>
           )}
@@ -934,10 +992,10 @@ export const SettingsPanel = ({
                 🔒
               </div>
               <div className="text-xs leading-relaxed text-text-muted">
-                <span className="font-medium text-text-secondary">Privacy:</span> Your API keys are
-                stored only in your browser's session storage and are cleared when the tab closes.
-                They're sent directly to the LLM provider when you chat. Your code never leaves your
-                machine.
+                <span className="font-medium text-text-secondary">
+                  {t('settings:privacyLabel')}
+                </span>{' '}
+                {t('settings:privacyFull')}
               </div>
             </div>
           </div>
@@ -949,13 +1007,13 @@ export const SettingsPanel = ({
             {saveStatus === 'saved' && (
               <span className="flex animate-fade-in items-center gap-1.5 text-green-400">
                 <Check className="h-4 w-4" />
-                Settings saved
+                {t('settings:settingsSaved')}
               </span>
             )}
             {saveStatus === 'error' && (
               <span className="flex animate-fade-in items-center gap-1.5 text-red-400">
                 <AlertCircle className="h-4 w-4" />
-                Failed to save
+                {t('settings:failedToSave')}
               </span>
             )}
           </div>
@@ -964,13 +1022,13 @@ export const SettingsPanel = ({
               onClick={onClose}
               className="px-4 py-2 text-sm text-text-secondary transition-colors hover:text-text-primary"
             >
-              Cancel
+              {t('common:actions.cancel')}
             </button>
             <button
               onClick={handleSave}
               className="rounded-lg bg-accent px-5 py-2 text-sm font-medium text-white transition-colors hover:bg-accent-dim"
             >
-              Save Settings
+              {t('settings:saveSettings')}
             </button>
           </div>
         </div>

gitnexus-web/src/components/StatusBar.tsx

@@ -1,9 +1,12 @@
 import { useMemo } from 'react';
 import { Heart } from '@/lib/lucide-icons';
 import { useAppState } from '../hooks/useAppState';
+import { useTranslation } from 'react-i18next';
+import { translateProgressMessage } from '../i18n/progress';
 
 export const StatusBar = () => {
   const { graph, progress } = useAppState();
+  const { t } = useTranslation(['common', 'graph']);
 
   const nodeCount = graph?.nodes.length ?? 0;
   const edgeCount = graph?.relationships.length ?? 0;
@@ -37,12 +40,12 @@ export const StatusBar = () => {
                 style={{ width: `${progress.percent}%` }}
               />
             </div>
-            <span>{progress.message}</span>
+            <span>{translateProgressMessage(progress.message, t)}</span>
           </>
         ) : (
           <div className="flex items-center gap-1.5" data-testid="status-ready">
             <span className="h-1.5 w-1.5 rounded-full bg-node-function" />
-            <span>Ready</span>
+            <span>{t('common:progress.ready')}</span>
           </div>
         )}
       </div>
@@ -56,10 +59,10 @@ export const StatusBar = () => {
       >
         <Heart className="h-3.5 w-3.5 animate-pulse fill-pink-500/40 text-pink-500 transition-all duration-200 group-hover:scale-110 group-hover:fill-pink-500" />
         <span className="text-[11px] font-medium text-pink-400 transition-colors group-hover:text-pink-300">
-          Sponsor
+          {t('graph:statusBar.sponsor')}
         </span>
         <span className="hidden text-[10px] text-pink-300/50 italic transition-colors group-hover:text-pink-300/80 md:inline">
-          need to buy some API credits to run SWE-bench 😅
+          {t('graph:statusBar.sponsorHint')}
         </span>
       </a>
 
@@ -67,9 +70,9 @@ export const StatusBar = () => {
       <div className="flex items-center gap-3" data-testid="graph-stats">
         {graph && (
           <>
-            <span>{nodeCount} nodes</span>
+            <span>{t('common:counts.nodes', { count: nodeCount })}</span>
             <span className="text-border-default">•</span>
-            <span>{edgeCount} edges</span>
+            <span>{t('common:counts.edges', { count: edgeCount })}</span>
             {primaryLanguage && (
               <>
                 <span className="text-border-default">•</span>

gitnexus-web/src/components/ToolCallCard.tsx

@@ -15,6 +15,8 @@ import {
   AlertCircle,
 } from '@/lib/lucide-icons';
 import type { ToolCallInfo } from '../core/llm/types';
+import type { TFunction } from 'i18next';
+import { useTranslation } from 'react-i18next';
 
 interface ToolCallCardProps {
   toolCall: ToolCallInfo;
@@ -25,7 +27,7 @@ interface ToolCallCardProps {
 /**
  * Format tool arguments for display
  */
-const formatArgs = (args: Record<string, unknown>): string => {
+const formatArgs = (args: Record<string, unknown>, t: TFunction): string => {
   if (!args || Object.keys(args).length === 0) {
     return '';
   }
@@ -34,7 +36,7 @@ const formatArgs = (args: Record<string, unknown>): string => {
   if ('cypher' in args && typeof args.cypher === 'string') {
     let result = '';
     if ('query' in args && typeof args.query === 'string') {
-      result += `Search: "${args.query}"\n\n`;
+      result += t('graph:toolCall.searchPrefix', { query: args.query }) + '\n\n';
     }
     result += args.cypher;
     return result;
@@ -88,24 +90,25 @@ const getStatusDisplay = (status: ToolCallInfo['status']) => {
 /**
  * Get a friendly display name for the tool
  */
-const getToolDisplayName = (name: string): string => {
+const getToolDisplayName = (name: string, t: TFunction): string => {
   const names: Record<string, string> = {
     // Current 7-tool architecture
-    search: '🔍 Search Code',
-    cypher: '🔗 Cypher Query',
-    grep: '🔎 Pattern Search',
-    read: '📄 Read File',
-    overview: '🗺️ Codebase Overview',
-    explore: '🔬 Deep Dive',
-    impact: '💥 Impact Analysis',
+    search: t('graph:toolCall.tools.search'),
+    cypher: t('graph:toolCall.tools.cypher'),
+    grep: t('graph:toolCall.tools.grep'),
+    read: t('graph:toolCall.tools.read'),
+    overview: t('graph:toolCall.tools.overview'),
+    explore: t('graph:toolCall.tools.explore'),
+    impact: t('graph:toolCall.tools.impact'),
   };
   return names[name] || name;
 };
 
 export const ToolCallCard = ({ toolCall, defaultExpanded = false }: ToolCallCardProps) => {
+  const { t } = useTranslation(['common', 'graph']);
   const [isExpanded, setIsExpanded] = useState(defaultExpanded);
   const status = getStatusDisplay(toolCall.status);
-  const formattedArgs = formatArgs(toolCall.args);
+  const formattedArgs = formatArgs(toolCall.args, t);
 
   return (
     <div
@@ -131,13 +134,13 @@ export const ToolCallCard = ({ toolCall, defaultExpanded = false }: ToolCallCard
 
         {/* Tool name */}
         <span className="flex-1 text-sm font-medium text-text-primary">
-          {getToolDisplayName(toolCall.name)}
+          {getToolDisplayName(toolCall.name, t)}
         </span>
 
         {/* Status indicator */}
         <span className={`flex items-center gap-1 text-xs ${status.color}`}>
           {status.icon}
-          <span className="capitalize">{toolCall.status}</span>
+          <span className="capitalize">{t(`graph:toolCall.status.${toolCall.status}`)}</span>
         </span>
       </div>
 
@@ -148,7 +151,7 @@ export const ToolCallCard = ({ toolCall, defaultExpanded = false }: ToolCallCard
           {formattedArgs && (
             <div className="border-b border-border-subtle/50 px-3 py-2">
               <div className="mb-1.5 text-[10px] tracking-wider text-text-muted uppercase">
-                {toolCall.name === 'cypher' ? 'Query' : 'Input'}
+                {toolCall.name === 'cypher' ? t('graph:toolCall.query') : t('graph:toolCall.input')}
               </div>
               <pre className="overflow-x-auto rounded bg-surface/50 p-2 font-mono text-xs whitespace-pre-wrap text-text-secondary">
                 {formattedArgs}
@@ -160,12 +163,12 @@ export const ToolCallCard = ({ toolCall, defaultExpanded = false }: ToolCallCard
           {toolCall.result && (
             <div className="px-3 py-2">
               <div className="mb-1.5 text-[10px] tracking-wider text-text-muted uppercase">
-                Result
+                {t('graph:toolCall.result')}
               </div>
               <div className="max-h-[400px] overflow-y-auto rounded bg-surface/50">
                 <pre className="p-2 font-mono text-xs whitespace-pre-wrap text-text-secondary">
                   {toolCall.result.length > 3000
-                    ? toolCall.result.slice(0, 3000) + '\n\n... (truncated)'
+                    ? toolCall.result.slice(0, 3000) + '\n\n' + t('common:progress.truncated')
                     : toolCall.result}
                 </pre>
               </div>
@@ -176,7 +179,7 @@ export const ToolCallCard = ({ toolCall, defaultExpanded = false }: ToolCallCard
           {toolCall.status === 'running' && !toolCall.result && (
             <div className="flex items-center gap-2 px-3 py-3 text-xs text-text-muted">
               <Loader2 className="h-3 w-3 animate-spin" />
-              <span>Executing...</span>
+              <span>{t('common:progress.executing')}</span>
             </div>
           )}
         </div>

gitnexus-web/src/components/WebGPUFallbackDialog.tsx

@@ -1,5 +1,6 @@
 import { useState, useEffect } from 'react';
 import { X, Snail, Rocket, SkipForward } from '@/lib/lucide-icons';
+import { useTranslation } from 'react-i18next';
 
 interface WebGPUFallbackDialogProps {
   isOpen: boolean;
@@ -20,6 +21,7 @@ export const WebGPUFallbackDialog = ({
   onSkip,
   nodeCount,
 }: WebGPUFallbackDialogProps) => {
+  const { t } = useTranslation('graph');
   const [isAnimating, setIsAnimating] = useState(true);
   const [isVisible, setIsVisible] = useState(false);
 
@@ -69,10 +71,10 @@ export const WebGPUFallbackDialog = ({
               🤔
             </div>
             <div>
-              <h2 className="text-lg font-semibold text-text-primary">WebGPU said "nope"</h2>
-              <p className="mt-0.5 text-sm text-text-muted">
-                Your browser doesn't support GPU acceleration
-              </p>
+              <h2 className="text-lg font-semibold text-text-primary">
+                {t('embedding.fallback.title')}
+              </h2>
+              <p className="mt-0.5 text-sm text-text-muted">{t('embedding.fallback.subtitle')}</p>
             </div>
           </div>
         </div>
@@ -80,24 +82,31 @@ export const WebGPUFallbackDialog = ({
         {/* Content */}
         <div className="space-y-4 px-6 py-5">
           <p className="text-sm leading-relaxed text-text-secondary">
-            Couldn't create embeddings with WebGPU, so semantic search (Graph RAG) won't be as
-            smart. The graph still works fine though!
+            {t('embedding.fallback.description')}
           </p>
 
           <div className="rounded-lg border border-border-subtle bg-elevated/50 p-4">
             <p className="text-sm text-text-secondary">
-              <span className="font-medium text-text-primary">Your options:</span>
+              <span className="font-medium text-text-primary">
+                {t('embedding.fallback.options')}
+              </span>
             </p>
             <ul className="mt-2 space-y-1.5 text-sm text-text-muted">
               <li className="flex items-start gap-2">
                 <Snail className="mt-0.5 h-4 w-4 flex-shrink-0 text-amber-400" />
                 <span>
-                  <strong className="text-text-secondary">Use CPU</strong> — Works but{' '}
-                  {isSmallCodebase ? 'a bit' : 'way'} slower
+                  <strong className="text-text-secondary">{t('embedding.fallback.useCpu')}</strong>{' '}
+                  —{' '}
+                  {isSmallCodebase
+                    ? t('embedding.fallback.useCpuDescriptionSmall')
+                    : t('embedding.fallback.useCpuDescriptionLarge')}
                   {nodeCount > 0 && (
                     <span className="text-text-muted">
                       {' '}
-                      (~{estimatedMinutes} min for {nodeCount} nodes)
+                      {t('embedding.fallback.estimated', {
+                        minutes: estimatedMinutes,
+                        count: nodeCount,
+                      })}
                     </span>
                   )}
                 </span>
@@ -105,8 +114,8 @@ export const WebGPUFallbackDialog = ({
               <li className="flex items-start gap-2">
                 <SkipForward className="mt-0.5 h-4 w-4 flex-shrink-0 text-blue-400" />
                 <span>
-                  <strong className="text-text-secondary">Skip it</strong> — Graph works, just no AI
-                  semantic search
+                  <strong className="text-text-secondary">{t('embedding.fallback.skipIt')}</strong>{' '}
+                  — {t('embedding.fallback.skipDescription')}
                 </span>
               </li>
             </ul>
@@ -115,11 +124,11 @@ export const WebGPUFallbackDialog = ({
           {isSmallCodebase && (
             <p className="flex items-center gap-1.5 rounded-lg bg-node-function/10 px-3 py-2 text-xs text-node-function">
               <Rocket className="h-3.5 w-3.5" />
-              Small codebase detected! CPU should be fine.
+              {t('embedding.fallback.smallCodebase')}
             </p>
           )}
 
-          <p className="text-xs text-text-muted">💡 Tip: Try Chrome or Edge for WebGPU support</p>
+          <p className="text-xs text-text-muted">{t('embedding.fallback.tip')}</p>
         </div>
 
         {/* Actions */}
@@ -129,7 +138,7 @@ export const WebGPUFallbackDialog = ({
             className="flex flex-1 items-center justify-center gap-2 rounded-lg border border-border-subtle bg-surface px-4 py-2.5 text-sm font-medium text-text-secondary transition-all hover:bg-hover hover:text-text-primary"
           >
             <SkipForward className="h-4 w-4" />
-            Skip Embeddings
+            {t('embedding.fallback.skipEmbeddings')}
           </button>
           <button
             onClick={onUseCPU}
@@ -140,7 +149,9 @@ export const WebGPUFallbackDialog = ({
             }`}
           >
             <Snail className="h-4 w-4" />
-            Use CPU {isSmallCodebase ? '(Recommended)' : '(Slow)'}
+            {isSmallCodebase
+              ? t('embedding.fallback.useCpuRecommended')
+              : t('embedding.fallback.useCpuSlow')}
           </button>
         </div>
       </div>

gitnexus-web/src/components/settings/ProviderConfigCard.tsx

@@ -1,5 +1,6 @@
 import { ReactNode } from 'react';
 import { Eye, EyeOff, Key } from '@/lib/lucide-icons';
+import { useTranslation } from 'react-i18next';
 
 type ApiKeyField = {
   value: string;
@@ -35,6 +36,8 @@ export const ProviderConfigCard = ({
   model,
   children,
 }: ProviderConfigCardProps) => {
+  const { t } = useTranslation('settings');
+
   return (
     <div className="animate-fade-in space-y-4">
       <div className="flex items-center justify-between">
@@ -48,7 +51,7 @@ export const ProviderConfigCard = ({
         <div className="space-y-2">
           <label className="flex items-center gap-2 text-sm font-medium text-text-secondary">
             <Key className="h-4 w-4" />
-            API Key
+            {t('apiKey')}
           </label>
           <div className="relative">
             <input
@@ -76,7 +79,7 @@ export const ProviderConfigCard = ({
                   rel="noopener noreferrer"
                   className="text-accent hover:underline"
                 >
-                  {apiKey.helperLinkLabel ?? 'Learn more'}
+                  {apiKey.helperLinkLabel ?? t('learnMore')}
                 </a>
               ) : null}
             </p>
@@ -87,7 +90,7 @@ export const ProviderConfigCard = ({
       {model && (
         <div className="space-y-2">
           <label className="text-sm font-medium text-text-secondary">
-            {model.label ?? 'Model'}
+            {model.label ?? t('model')}
           </label>
           <input
             type="text"

gitnexus-web/src/config/ui-constants.ts

@@ -2,7 +2,9 @@
 export const ERROR_RESET_DELAY_MS = 3000;
 export const BACKEND_URL_DEBOUNCE_MS = 500;
 
-export const DEFAULT_BACKEND_URL = 'http://localhost:4747';
+export const DEFAULT_BACKEND_URL =
+  (typeof window !== 'undefined' && window.__GITNEXUS_CONFIG__?.backendUrl) ||
+  'http://localhost:4747';
 export const DEFAULT_OLLAMA_BASE_URL = 'http://localhost:11434';
 export const DEFAULT_OPENROUTER_BASE_URL = 'https://openrouter.ai/api/v1';
 

gitnexus-web/src/core/llm/agent.ts

@@ -6,7 +6,13 @@
  */
 
 import { createReactAgent } from '@langchain/langgraph/prebuilt';
-import { SystemMessage } from '@langchain/core/messages';
+import {
+  SystemMessage,
+  HumanMessage,
+  AIMessage,
+  ToolMessage,
+  type BaseMessage,
+} from '@langchain/core/messages';
 import { ChatOpenAI, AzureChatOpenAI } from '@langchain/openai';
 import { ChatGoogleGenerativeAI } from '@langchain/google-genai';
 import { ChatAnthropic } from '@langchain/anthropic';
@@ -23,10 +29,17 @@ import type {
   OpenRouterConfig,
   MiniMaxConfig,
   GLMConfig,
+  DeepSeekConfig,
   AgentStreamChunk,
+  AgentHistoryMessage,
 } from './types';
 import { type CodebaseContext, buildDynamicSystemPrompt } from './context-builder';
 import { DEFAULT_OLLAMA_BASE_URL, DEFAULT_OPENROUTER_BASE_URL } from '../../config/ui-constants';
+import {
+  DeepSeekChatOpenAI,
+  normalizeMessageContent,
+  normalizeToolCalls,
+} from './deepseek-chat-model';
 
 /**
  * System prompt for the Graph RAG agent
@@ -124,6 +137,7 @@ When generating diagrams:
 BAD:  A[User's Data] --> B(Process & Save)
 GOOD: A["User Data"] --> B["Process and Save"]
 `;
+
 export const createChatModel = (config: ProviderConfig): BaseChatModel => {
   switch (config.provider) {
     case 'openai': {
@@ -264,6 +278,26 @@ export const createChatModel = (config: ProviderConfig): BaseChatModel => {
       });
     }
 
+    case 'deepseek': {
+      const deepseekConfig = config as DeepSeekConfig;
+
+      if (!deepseekConfig.apiKey || deepseekConfig.apiKey.trim() === '') {
+        throw new Error('DeepSeek API key is required but was not provided');
+      }
+
+      return new DeepSeekChatOpenAI({
+        apiKey: deepseekConfig.apiKey,
+        modelName: deepseekConfig.model,
+        temperature: deepseekConfig.temperature ?? 0.1,
+        maxTokens: deepseekConfig.maxTokens,
+        configuration: {
+          apiKey: deepseekConfig.apiKey,
+          baseURL: 'https://api.deepseek.com',
+        },
+        streaming: true,
+      });
+    }
+
     default:
       throw new Error(`Unsupported provider: ${(config as any).provider}`);
   }
@@ -324,11 +358,65 @@ export const createGraphRAGAgent = (
 /**
  * Message type for agent conversation
  */
-export interface AgentMessage {
-  role: 'user' | 'assistant';
-  content: string;
+export type AgentMessage = { role: 'user'; content: string } | AgentHistoryMessage;
+
+export interface AgentRuntimeOptions {
+  /** Capture assistant/tool messages for providers that require exact transcript replay. */
+  captureHistory?: boolean;
 }
 
+export const buildLangChainMessages = (messages: AgentMessage[]): BaseMessage[] =>
+  messages.map((message) => {
+    if (message.role === 'user') {
+      return new HumanMessage(message.content);
+    }
+    if (message.role === 'tool') {
+      return new ToolMessage({
+        content: message.content,
+        tool_call_id: message.toolCallId,
+        ...(message.name ? { name: message.name } : {}),
+      });
+    }
+    return new AIMessage({
+      content: message.content,
+      ...(typeof message.reasoningContent === 'string'
+        ? { additional_kwargs: { reasoning_content: message.reasoningContent } }
+        : {}),
+      ...(message.toolCalls?.length ? { tool_calls: message.toolCalls } : {}),
+    } as any);
+  });
+
+export const serializeAgentHistoryMessages = (
+  messages: unknown[],
+  startIndex = 0,
+): AgentHistoryMessage[] => {
+  const serialized: AgentHistoryMessage[] = [];
+  for (const rawMessage of messages.slice(startIndex)) {
+    const msg: any = rawMessage;
+    const msgType = msg?._getType?.() || msg?.type || msg?.constructor?.name || 'unknown';
+    if (msgType === 'ai' || msgType === 'AIMessage') {
+      const reasoningContent = (msg.additional_kwargs || msg.kwargs)?.reasoning_content;
+      const toolCalls = normalizeToolCalls(msg.tool_calls);
+      serialized.push({
+        role: 'assistant',
+        content: normalizeMessageContent(msg.content),
+        ...(toolCalls?.length && typeof reasoningContent === 'string' ? { reasoningContent } : {}),
+        ...(toolCalls?.length ? { toolCalls } : {}),
+      });
+      continue;
+    }
+    if (msgType === 'tool' || msgType === 'ToolMessage') {
+      serialized.push({
+        role: 'tool',
+        content: normalizeMessageContent(msg.content),
+        toolCallId: String(msg.tool_call_id ?? ''),
+        ...(typeof msg.name === 'string' ? { name: msg.name } : {}),
+      });
+    }
+  }
+  return serialized;
+};
+
 /**
  * Stream a response from the agent
  * Uses BOTH streamModes for best of both worlds:
@@ -340,12 +428,10 @@ export interface AgentMessage {
 export async function* streamAgentResponse(
   agent: ReturnType<typeof createReactAgent>,
   messages: AgentMessage[],
+  options: AgentRuntimeOptions = {},
 ): AsyncGenerator<AgentStreamChunk> {
   try {
-    const formattedMessages = messages.map((m) => ({
-      role: m.role,
-      content: m.content,
-    }));
+    const formattedMessages = buildLangChainMessages(messages);
 
     // Use BOTH modes: 'values' for structure, 'messages' for token streaming
     const stream = await agent.stream({ messages: formattedMessages }, {
@@ -364,6 +450,9 @@ export async function* streamAgentResponse(
     // Anything before the first tool call should be treated as "reasoning/narration"
     // so the UI can show the Cursor-like loop: plan → tool → update → tool → answer.
     let hasSeenToolCallThisTurn = false;
+    // Track the last set of messages so we can persist the raw assistant/tool
+    // transcript for the next user turn.
+    let lastStepMessages: any[] | null = null;
 
     for await (const event of stream) {
       // Events come as [streamMode, data] tuples when using multiple modes
@@ -482,6 +571,9 @@ export async function* streamAgentResponse(
       // Handle 'values' mode - state snapshots for structure
       if (mode === 'values' && data?.messages) {
         const stepMessages = data.messages || [];
+        if (options.captureHistory) {
+          lastStepMessages = stepMessages;
+        }
 
         // Process new messages for tool calls/results we might have missed
         for (let i = lastProcessedMsgCount; i < stepMessages.length; i++) {
@@ -539,7 +631,14 @@ export async function* streamAgentResponse(
     if (import.meta.env.DEV) {
       console.log('✅ Stream completed normally, yielding done');
     }
-    yield { type: 'done' };
+
+    yield {
+      type: 'done',
+      historyMessages:
+        options.captureHistory && lastStepMessages
+          ? serializeAgentHistoryMessages(lastStepMessages, formattedMessages.length)
+          : undefined,
+    };
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     // DEBUG: Stream error
@@ -561,10 +660,7 @@ export const invokeAgent = async (
   agent: ReturnType<typeof createReactAgent>,
   messages: AgentMessage[],
 ): Promise<string> => {
-  const formattedMessages = messages.map((m) => ({
-    role: m.role,
-    content: m.content,
-  }));
+  const formattedMessages = buildLangChainMessages(messages);
 
   const result = await agent.invoke({ messages: formattedMessages });
 

gitnexus-web/src/core/llm/deepseek-chat-model.ts

@@ -0,0 +1,257 @@
+import {
+  ChatOpenAI,
+  ChatOpenAICompletions,
+  type ChatOpenAICallOptions,
+  type ChatOpenAICompletionsCallOptions,
+  type ChatOpenAIFields,
+} from '@langchain/openai';
+import type { BaseMessage } from '@langchain/core/messages';
+import type { BaseLanguageModelInput } from '@langchain/core/language_models/base';
+import type { AIMessageChunk } from '@langchain/core/messages';
+import type { Runnable } from '@langchain/core/runnables';
+import type { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager';
+import type { ChatGenerationChunk, ChatResult } from '@langchain/core/outputs';
+import type { AgentToolCall } from './types';
+
+/**
+ * DeepSeek's thinking-mode chat API requires assistant `reasoning_content`
+ * from prior turns to be replayed verbatim on the next request. LangChain
+ * preserves the inbound value on `AIMessage.additional_kwargs`, but its
+ * OpenAI-compatible outbound converter currently drops that provider-specific
+ * field. This completions subclass keeps the behavior scoped to DeepSeek by
+ * replacing only the serialized request messages immediately before the
+ * DeepSeek API call.
+ */
+export class DeepSeekChatOpenAICompletions<
+  CallOptions extends ChatOpenAICompletionsCallOptions = ChatOpenAICompletionsCallOptions,
+> extends ChatOpenAICompletions<CallOptions> {
+  private activeMessages: BaseMessage[] | null = null;
+
+  private setActiveMessages(messages: BaseMessage[]): void {
+    if (this.activeMessages !== null) {
+      throw new Error('DeepSeekChatOpenAICompletions does not support overlapping requests');
+    }
+    this.activeMessages = messages;
+  }
+
+  override async _generate(
+    messages: BaseMessage[],
+    options: this['ParsedCallOptions'],
+    runManager?: CallbackManagerForLLMRun,
+  ): Promise<ChatResult> {
+    this.setActiveMessages(messages);
+    try {
+      return await super._generate(messages, options, runManager);
+    } finally {
+      this.activeMessages = null;
+    }
+  }
+
+  override async *_streamResponseChunks(
+    messages: BaseMessage[],
+    options: this['ParsedCallOptions'],
+    runManager?: CallbackManagerForLLMRun,
+  ): AsyncGenerator<ChatGenerationChunk> {
+    this.setActiveMessages(messages);
+    try {
+      yield* super._streamResponseChunks(messages, options, runManager);
+    } finally {
+      this.activeMessages = null;
+    }
+  }
+
+  override async completionWithRetry(request: any, requestOptions?: any): Promise<any> {
+    const messages = this.activeMessages
+      ? buildDeepSeekRequestMessages(this.activeMessages)
+      : request.messages;
+    return super.completionWithRetry({ ...request, messages }, requestOptions);
+  }
+}
+
+/**
+ * OpenAI-compatible DeepSeek chat model with a DeepSeek-specific completions
+ * serializer. Keeping this as a subclass avoids provider checks in the shared
+ * agent streaming path and ensures LangChain `withConfig()` clones used by tool
+ * binding retain the same request serialization behavior.
+ */
+export class DeepSeekChatOpenAI<
+  CallOptions extends ChatOpenAICallOptions = ChatOpenAICallOptions,
+> extends ChatOpenAI<CallOptions> {
+  private readonly deepSeekFields: ChatOpenAIFields;
+
+  constructor(fields: ChatOpenAIFields) {
+    const deepSeekFields = {
+      ...fields,
+      completions: new DeepSeekChatOpenAICompletions(fields),
+    } as ChatOpenAIFields;
+    super(deepSeekFields);
+    this.deepSeekFields = deepSeekFields;
+  }
+
+  override withConfig(
+    config: Partial<CallOptions>,
+  ): Runnable<BaseLanguageModelInput, AIMessageChunk, CallOptions> {
+    // Mirror ChatOpenAI.withConfig() for this LangChain version, but keep the
+    // DeepSeek subclass. Calling super.withConfig() would drop our custom
+    // completions serializer by returning a plain ChatOpenAI instance.
+    const newModel = new DeepSeekChatOpenAI<CallOptions>(this.deepSeekFields);
+    newModel.defaultOptions = {
+      ...this.defaultOptions,
+      ...config,
+    } as typeof this.defaultOptions;
+    return newModel;
+  }
+}
+
+export const normalizeMessageContent = (content: unknown): string => {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    return content
+      .filter((block: any) => block?.type === 'text' || typeof block === 'string')
+      .map((block: any) => (typeof block === 'string' ? block : block.text || ''))
+      .join('');
+  }
+  if (content == null) return '';
+  return String(content);
+};
+
+const normalizeToolCallArgs = (toolCall: any): Record<string, unknown> => {
+  if (toolCall?.args && typeof toolCall.args === 'object') {
+    return toolCall.args as Record<string, unknown>;
+  }
+  try {
+    return toolCall?.function?.arguments ? JSON.parse(toolCall.function.arguments) : {};
+  } catch {
+    return {};
+  }
+};
+
+export const normalizeToolCalls = (toolCalls: unknown): AgentToolCall[] | undefined => {
+  if (!Array.isArray(toolCalls) || toolCalls.length === 0) return undefined;
+  return toolCalls.map((toolCall: any) => ({
+    id: typeof toolCall?.id === 'string' ? toolCall.id : undefined,
+    name: toolCall?.name || toolCall?.function?.name || 'unknown',
+    args: normalizeToolCallArgs(toolCall),
+    type: typeof toolCall?.type === 'string' ? toolCall.type : 'tool_call',
+  }));
+};
+
+const stringifyToolArguments = (args: unknown): string => {
+  if (typeof args === 'string') return args;
+  try {
+    return JSON.stringify(args ?? {});
+  } catch {
+    return '{}';
+  }
+};
+
+const normalizeOpenAIContent = (content: unknown): string | Array<Record<string, unknown>> => {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return normalizeMessageContent(content);
+
+  const blocks = content.flatMap((block: any) => {
+    if (typeof block === 'string') {
+      return [{ type: 'text', text: block }];
+    }
+    if (block?.type === 'text' && typeof block.text === 'string') {
+      return [{ type: 'text', text: block.text }];
+    }
+    return [];
+  });
+
+  if (blocks.length === 0) return '';
+  if (blocks.length === 1) return blocks[0].text as string;
+  return blocks;
+};
+
+const getOpenAIRole = (message: any): string => {
+  const messageType =
+    message?._getType?.() || message?.type || message?.constructor?.name || 'unknown';
+  if ((message.additional_kwargs || {}).__openai_role__ === 'developer') {
+    return 'developer';
+  }
+  switch (messageType) {
+    case 'human':
+    case 'HumanMessage':
+      return 'user';
+    case 'ai':
+    case 'AIMessage':
+      return 'assistant';
+    case 'system':
+    case 'SystemMessage':
+      return 'system';
+    case 'tool':
+    case 'ToolMessage':
+      return 'tool';
+    case 'function':
+    case 'FunctionMessage':
+      return 'function';
+    default:
+      return typeof message.role === 'string' ? message.role : 'user';
+  }
+};
+
+export const buildDeepSeekRequestMessages = (
+  messages: Array<BaseMessage | Record<string, unknown>>,
+): Array<Record<string, unknown>> =>
+  messages.map((message: any) => {
+    const role = getOpenAIRole(message);
+    const additionalKwargs =
+      message.additional_kwargs && typeof message.additional_kwargs === 'object'
+        ? message.additional_kwargs
+        : {};
+    const requestMessage: Record<string, unknown> = {
+      role,
+      content: normalizeOpenAIContent(message.content),
+    };
+
+    if (typeof message.name === 'string' && message.name.length > 0) {
+      requestMessage.name = message.name;
+    }
+    if (role === 'assistant') {
+      const toolCalls = Array.isArray(message.tool_calls)
+        ? message.tool_calls
+        : Array.isArray(additionalKwargs.tool_calls)
+          ? additionalKwargs.tool_calls
+          : undefined;
+      if (toolCalls?.length) {
+        requestMessage.tool_calls = toolCalls.map((toolCall: any) => {
+          if (toolCall?.function) {
+            return {
+              id: toolCall.id,
+              type: toolCall.type ?? 'function',
+              function: {
+                name: toolCall.function.name,
+                arguments: stringifyToolArguments(toolCall.function.arguments),
+              },
+            };
+          }
+          return {
+            id: toolCall?.id,
+            type: 'function',
+            function: {
+              name: toolCall?.name ?? 'unknown',
+              arguments: stringifyToolArguments(toolCall?.args),
+            },
+          };
+        });
+      }
+      if (additionalKwargs.function_call != null) {
+        requestMessage.function_call = additionalKwargs.function_call;
+      }
+      if (toolCalls?.length && typeof additionalKwargs.reasoning_content === 'string') {
+        requestMessage.reasoning_content = additionalKwargs.reasoning_content;
+      }
+      return requestMessage;
+    }
+
+    if (role === 'tool' && typeof message.tool_call_id === 'string') {
+      requestMessage.tool_call_id = message.tool_call_id;
+    }
+
+    if (role === 'function' && typeof message.name === 'string') {
+      requestMessage.name = message.name;
+    }
+
+    return requestMessage;
+  });

gitnexus-web/src/core/llm/settings-service.ts

@@ -17,6 +17,7 @@ import {
   OpenRouterConfig,
   MiniMaxConfig,
   GLMConfig,
+  DeepSeekConfig,
   ProviderConfig,
 } from './types';
 import { DEFAULT_OPENROUTER_BASE_URL, DEFAULT_OLLAMA_BASE_URL } from '../../config/ui-constants';
@@ -59,6 +60,10 @@ const mergeWithDefaults = (parsed?: Partial<LLMSettings> | null): LLMSettings =>
     ...DEFAULT_LLM_SETTINGS.glm,
     ...parsed?.glm,
   },
+  deepseek: {
+    ...DEFAULT_LLM_SETTINGS.deepseek,
+    ...parsed?.deepseek,
+  },
 });
 
 const readSettings = (storage: Storage): Partial<LLMSettings> | null => {
@@ -144,7 +149,9 @@ export const updateProviderSettings = <T extends LLMProvider>(
                   ? Partial<Omit<MiniMaxConfig, 'provider'>>
                   : T extends 'glm'
                     ? Partial<Omit<GLMConfig, 'provider'>>
-                    : never
+                    : T extends 'deepseek'
+                      ? Partial<Omit<DeepSeekConfig, 'provider'>>
+                      : never
   >,
 ): LLMSettings => {
   const current = loadSettings();
@@ -239,6 +246,17 @@ export const updateProviderSettings = <T extends LLMProvider>(
       saveSettings(updated);
       return updated;
     }
+    case 'deepseek': {
+      const updated: LLMSettings = {
+        ...current,
+        deepseek: {
+          ...(current.deepseek ?? {}),
+          ...(updates as Partial<Omit<DeepSeekConfig, 'provider'>>),
+        },
+      };
+      saveSettings(updated);
+      return updated;
+    }
     default: {
       // Should be unreachable due to T extends LLMProvider, but keep a safe fallback
       const updated: LLMSettings = { ...current };
@@ -316,6 +334,10 @@ const providerBuilders: Record<LLMProvider, ProviderBuilder> = {
       maxTokens: settings.glm.maxTokens,
     } as GLMConfig;
   },
+  deepseek: (settings) => {
+    if (!settings.deepseek?.apiKey) return null;
+    return { provider: 'deepseek', ...settings.deepseek } as DeepSeekConfig;
+  },
 };
 
 export const getActiveProviderConfig = (): ProviderConfig | null => {
@@ -347,6 +369,24 @@ export const clearSettings = (): void => {
   }
 };
 
+interface ProviderCapabilities {
+  /** Provider requires hidden assistant/tool transcript replay across turns. */
+  preserveAssistantTranscript: boolean;
+}
+
+const DEFAULT_PROVIDER_CAPABILITIES: ProviderCapabilities = {
+  preserveAssistantTranscript: false,
+};
+
+const PROVIDER_CAPABILITIES: Partial<Record<LLMProvider, ProviderCapabilities>> = {
+  deepseek: { preserveAssistantTranscript: true },
+};
+
+export const getProviderCapabilities = (provider: LLMProvider): ProviderCapabilities => ({
+  ...DEFAULT_PROVIDER_CAPABILITIES,
+  ...PROVIDER_CAPABILITIES[provider],
+});
+
 /**
  * Get display name for a provider
  */
@@ -368,6 +408,8 @@ export const getProviderDisplayName = (provider: LLMProvider): string => {
       return 'MiniMax';
     case 'glm':
       return 'GLM (Z.AI)';
+    case 'deepseek':
+      return 'DeepSeek';
     default:
       return provider;
   }
@@ -398,6 +440,8 @@ export const getAvailableModels = (provider: LLMProvider): string[] => {
       return ['MiniMax-M2.5', 'MiniMax-M2.5-highspeed'];
     case 'glm':
       return ['GLM-5', 'GLM-5-Turbo', 'GLM-4.7', 'GLM-4.5'];
+    case 'deepseek':
+      return ['deepseek-v4-flash', 'deepseek-v4-pro', 'deepseek-chat', 'deepseek-reasoner'];
     default:
       return [];
   }

gitnexus-web/src/core/llm/types.ts

@@ -2,7 +2,7 @@
  * LLM Provider Types
  *
  * Type definitions for multi-provider LLM support.
- * Supports OpenAI, Azure OpenAI, Gemini, Anthropic, Ollama, OpenRouter, MiniMax, and GLM5.
+ * Supports OpenAI, Azure OpenAI, Gemini, Anthropic, Ollama, OpenRouter, MiniMax, GLM, and DeepSeek.
  */
 
 /**
@@ -17,7 +17,8 @@ export type LLMProvider =
   | 'ollama'
   | 'openrouter'
   | 'minimax'
-  | 'glm';
+  | 'glm'
+  | 'deepseek';
 
 /**
  * Base configuration shared by all providers
@@ -106,6 +107,15 @@ export interface GLMConfig extends BaseProviderConfig {
   baseUrl?: string; // defaults to https://api.z.ai/api/coding/paas/v4
 }
 
+/**
+ * DeepSeek configuration — OpenAI-compatible API
+ */
+export interface DeepSeekConfig extends BaseProviderConfig {
+  provider: 'deepseek';
+  apiKey: string;
+  model: string; // e.g., 'deepseek-v4-flash', 'deepseek-v4-pro'
+}
+
 /**
  * Union type for all provider configurations
  */
@@ -117,7 +127,8 @@ export type ProviderConfig =
   | OllamaConfig
   | OpenRouterConfig
   | MiniMaxConfig
-  | GLMConfig;
+  | GLMConfig
+  | DeepSeekConfig;
 
 /**
  * Stored settings (what goes to localStorage)
@@ -136,6 +147,7 @@ export interface LLMSettings {
   openrouter?: Partial<Omit<OpenRouterConfig, 'provider'>>;
   minimax?: Partial<Omit<MiniMaxConfig, 'provider'>>;
   glm?: Partial<Omit<GLMConfig, 'provider'>>;
+  deepseek?: Partial<Omit<DeepSeekConfig, 'provider'>>;
 
   // Intelligent Clustering Settings
   intelligentClustering: boolean;
@@ -197,6 +209,11 @@ export const DEFAULT_LLM_SETTINGS: LLMSettings = {
     baseUrl: 'https://api.z.ai/api/coding/paas/v4',
     temperature: 0.1,
   },
+  deepseek: {
+    apiKey: '',
+    model: 'deepseek-v4-flash',
+    temperature: 0.1,
+  },
 };
 
 /**
@@ -219,6 +236,8 @@ export interface ChatMessage {
   id: string;
   role: 'user' | 'assistant' | 'tool';
   content: string;
+  /** Hidden raw transcript for reconstructing future agent turns */
+  historyMessages?: AgentHistoryMessage[];
   /** @deprecated Use steps instead for proper ordering */
   toolCalls?: ToolCallInfo[];
   /** Ordered steps: reasoning, tool calls, and final content interleaved */
@@ -238,6 +257,34 @@ export interface ToolCallInfo {
   status: 'pending' | 'running' | 'completed' | 'error';
 }
 
+/**
+ * Minimal tool-call payload needed to reconstruct prior assistant turns.
+ */
+export interface AgentToolCall {
+  id?: string;
+  name: string;
+  args: Record<string, unknown>;
+  type: 'tool_call';
+}
+
+/**
+ * Hidden per-turn transcript we keep so providers like DeepSeek can replay
+ * the original assistant/tool exchange on later user turns.
+ */
+export type AgentHistoryMessage =
+  | {
+      role: 'assistant';
+      content: string;
+      reasoningContent?: string;
+      toolCalls?: AgentToolCall[];
+    }
+  | {
+      role: 'tool';
+      content: string;
+      toolCallId: string;
+      name?: string;
+    };
+
 /**
  * Streaming chunk from agent
  * Now supports step-based streaming where each step is a distinct message
@@ -248,6 +295,8 @@ export interface AgentStreamChunk {
   reasoning?: string;
   /** Final answer content (streamed token by token) */
   content?: string;
+  /** Hidden raw transcript for reconstructing future agent turns */
+  historyMessages?: AgentHistoryMessage[];
   /** Tool call information */
   toolCall?: ToolCallInfo;
   /** Error message */

gitnexus-web/src/hooks/useAppState.tsx

@@ -18,7 +18,12 @@ import type {
   ToolCallInfo,
   MessageStep,
 } from '../core/llm/types';
-import { loadSettings, getActiveProviderConfig, saveSettings } from '../core/llm/settings-service';
+import {
+  loadSettings,
+  getActiveProviderConfig,
+  getProviderCapabilities,
+  saveSettings,
+} from '../core/llm/settings-service';
 import type { AgentMessage } from '../core/llm/agent';
 import { type EdgeType } from '../lib/constants';
 import {
@@ -35,10 +40,18 @@ import {
   type JobProgress,
 } from '../services/backend-client';
 import { ERROR_RESET_DELAY_MS } from '../config/ui-constants';
+import i18n from '../i18n';
 import { normalizePath } from '../lib/path-resolution';
 import { FILE_REF_REGEX, NODE_REF_REGEX } from '../lib/grounding-patterns';
 import { GraphStateProvider, useGraphState } from './app-state/graph';
 
+export const AUTO_START_EMBEDDINGS_STORAGE_KEY = 'gitnexus.autoStartEmbeddings';
+
+export const shouldAutoStartEmbeddings = (): boolean => {
+  if (typeof window === 'undefined' || !window.localStorage) return false;
+  return window.localStorage.getItem(AUTO_START_EMBEDDINGS_STORAGE_KEY) === 'true';
+};
+
 export type ViewMode = 'onboarding' | 'loading' | 'exploring';
 export type RightPanelTab = 'code' | 'chat';
 export type EmbeddingStatus = 'idle' | 'loading' | 'embedding' | 'indexing' | 'ready' | 'error';
@@ -529,6 +542,10 @@ const AppStateProviderInner = ({ children }: { children: ReactNode }) => {
       setEmbeddingStatus('idle');
       return;
     }
+    if (!shouldAutoStartEmbeddings()) {
+      setEmbeddingStatus('idle');
+      return;
+    }
     startEmbeddings().catch((err) => {
       console.warn('Embeddings auto-start failed:', err);
     });
@@ -623,6 +640,8 @@ const AppStateProviderInner = ({ children }: { children: ReactNode }) => {
 
   const sendChatMessage = useCallback(
     async (message: string): Promise<void> => {
+      if (isChatLoading) return;
+
       // Refresh Code panel for the new question: keep user-pinned refs, clear old AI citations
       clearAICodeReferences();
       // Also clear previous tool-driven AI highlights (highlight_in_graph)
@@ -649,7 +668,7 @@ const AppStateProviderInner = ({ children }: { children: ReactNode }) => {
         const assistantMessage: ChatMessage = {
           id: `assistant-${Date.now()}`,
           role: 'assistant',
-          content: 'Wait a moment, vector index is being created.',
+          content: i18n.t('common:chat.waitForVectorIndex'),
           timestamp: Date.now(),
         };
         setChatMessages((prev) => [...prev, assistantMessage]);
@@ -662,11 +681,23 @@ const AppStateProviderInner = ({ children }: { children: ReactNode }) => {
       setIsChatLoading(true);
       setCurrentToolCalls([]);
 
+      const providerCapabilities = getProviderCapabilities(llmSettings.activeProvider);
+
       // Prepare message history for agent (convert our format to AgentMessage format)
-      const history: AgentMessage[] = [...chatMessages, userMessage].map((m) => ({
-        role: m.role === 'tool' ? 'assistant' : m.role,
-        content: m.content,
-      }));
+      const history: AgentMessage[] = [...chatMessages, userMessage].flatMap<AgentMessage>((m) => {
+        if (m.role === 'user') {
+          return [{ role: 'user', content: m.content }];
+        }
+        if (m.role === 'tool') {
+          return m.toolCallId
+            ? [{ role: 'tool', content: m.content, toolCallId: m.toolCallId }]
+            : [];
+        }
+        if (providerCapabilities.preserveAssistantTranscript && m.historyMessages?.length) {
+          return m.historyMessages;
+        }
+        return [{ role: 'assistant', content: m.content }];
+      });
 
       // Create placeholder for assistant response
       const assistantMessageId = `assistant-${Date.now()}`;
@@ -675,6 +706,7 @@ const AppStateProviderInner = ({ children }: { children: ReactNode }) => {
       // Keep toolCalls for backwards compat and currentToolCalls state
       const toolCallsForMessage: ToolCallInfo[] = [];
       let stepCounter = 0;
+      let assistantHistoryMessages: ChatMessage['historyMessages'];
 
       // Helper to update the message with current steps
       const updateMessage = () => {
@@ -691,6 +723,7 @@ const AppStateProviderInner = ({ children }: { children: ReactNode }) => {
             id: assistantMessageId,
             role: 'assistant' as const,
             content,
+            historyMessages: assistantHistoryMessages,
             steps: [...stepsForMessage],
             toolCalls: [...toolCallsForMessage],
             timestamp: existing?.timestamp ?? Date.now(),
@@ -973,6 +1006,9 @@ const AppStateProviderInner = ({ children }: { children: ReactNode }) => {
               break;
 
             case 'done':
+              assistantHistoryMessages = providerCapabilities.preserveAssistantTranscript
+                ? chunk.historyMessages
+                : undefined;
               // Finalize the assistant message - just call updateMessage one more time
               scheduleMessageUpdate();
               break;
@@ -984,10 +1020,11 @@ const AppStateProviderInner = ({ children }: { children: ReactNode }) => {
         const agent = agentRef.current;
         if (!agent) throw new Error('Agent not initialized');
         const { streamAgentResponse } = await import('../core/llm/agent');
-        for await (const chunk of streamAgentResponse(agent, history)) {
+        for await (const chunk of streamAgentResponse(agent, history, {
+          captureHistory: providerCapabilities.preserveAssistantTranscript,
+        })) {
           onChunk(chunk);
         }
-        onChunk({ type: 'done' });
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         setAgentError(message);
@@ -1007,6 +1044,7 @@ const AppStateProviderInner = ({ children }: { children: ReactNode }) => {
       clearAIToolHighlights,
       graph,
       embeddingStatus,
+      isChatLoading,
     ],
   );
 
@@ -1032,8 +1070,8 @@ const AppStateProviderInner = ({ children }: { children: ReactNode }) => {
       setProgress({
         phase: 'extracting',
         percent: 0,
-        message: 'Switching repository...',
-        detail: `Loading ${repoName}`,
+        message: i18n.t('common:progress.switchingRepository'),
+        detail: i18n.t('common:progress.loadingRepository', { repo: repoName }),
       });
       setViewMode('loading');
       setIsAgentReady(false);
@@ -1061,8 +1099,8 @@ const AppStateProviderInner = ({ children }: { children: ReactNode }) => {
               setProgress({
                 phase: 'extracting',
                 percent: 5,
-                message: 'Switching repository...',
-                detail: 'Validating',
+                message: i18n.t('common:progress.switchingRepository'),
+                detail: i18n.t('common:progress.validating'),
               });
             } else if (phase === 'downloading') {
               const pct = total ? Math.round((downloaded / total) * 90) + 5 : 50;
@@ -1070,15 +1108,15 @@ const AppStateProviderInner = ({ children }: { children: ReactNode }) => {
               setProgress({
                 phase: 'extracting',
                 percent: pct,
-                message: 'Downloading graph...',
-                detail: `${mb} MB downloaded`,
+                message: i18n.t('common:progress.downloadingGraph'),
+                detail: i18n.t('common:progress.downloadedMb', { mb }),
               });
             } else if (phase === 'extracting') {
               setProgress({
                 phase: 'extracting',
                 percent: 97,
-                message: 'Processing...',
-                detail: 'Extracting file contents',
+                message: i18n.t('common:progress.processing'),
+                detail: i18n.t('common:progress.extractingFileContents'),
               });
             }
           },
@@ -1110,8 +1148,8 @@ const AppStateProviderInner = ({ children }: { children: ReactNode }) => {
         setProgress({
           phase: 'error',
           percent: 0,
-          message: 'Failed to switch repository',
-          detail: err instanceof Error ? err.message : 'Unknown error',
+          message: i18n.t('common:progress.failedSwitchRepository'),
+          detail: err instanceof Error ? err.message : i18n.t('common:progress.unknownError'),
         });
         setIsAgentReady(false);
         agentRef.current = null;

gitnexus-web/src/i18n/error-messages.ts

@@ -0,0 +1,27 @@
+import type { TFunction } from 'i18next';
+import { BackendError } from '../services/backend-client';
+
+export function formatBackendError(error: unknown, t: TFunction): string {
+  if (error instanceof BackendError) {
+    const seconds = error.retryAfterMs ? Math.ceil(error.retryAfterMs / 1000) : undefined;
+    const fallback = error.message || t('errors:unknown');
+    switch (error.code) {
+      case 'network':
+        return t('errors:backend.network', { defaultValue: fallback });
+      case 'timeout':
+        return t('errors:backend.timeout', { defaultValue: fallback });
+      case 'rate_limited':
+        return t('errors:backend.rateLimited', { seconds, defaultValue: fallback });
+      case 'not_found':
+        return t('errors:backend.notFound', { defaultValue: fallback });
+      case 'client':
+        return t('errors:backend.client', { message: error.message, defaultValue: fallback });
+      case 'server':
+        return t('errors:backend.server', { message: error.message, defaultValue: fallback });
+      default:
+        return fallback;
+    }
+  }
+
+  return error instanceof Error ? error.message : t('errors:unknown');
+}

gitnexus-web/src/i18n/index.ts

@@ -0,0 +1,70 @@
+import i18n from 'i18next';
+import LanguageDetector from 'i18next-browser-languagedetector';
+import { initReactI18next } from 'react-i18next';
+import {
+  DEFAULT_LANGUAGE,
+  SUPPORTED_LANGUAGE_CODES,
+  getLanguageMetadata,
+  normalizeSupportedLanguage,
+} from './languages';
+import { namespaceList, resources } from './resources';
+
+const DEFAULT_NAMESPACE = 'common';
+export const LANGUAGE_STORAGE_KEY = 'gitnexus.lng';
+
+function syncDocumentLanguage(language: string | undefined): void {
+  if (typeof document === 'undefined') return;
+  const metadata = getLanguageMetadata(language);
+  document.documentElement.lang = metadata.code;
+  document.documentElement.dir = metadata.dir;
+}
+
+function convertDetectedLanguage(language: string): string {
+  return normalizeSupportedLanguage(language) ?? DEFAULT_LANGUAGE;
+}
+
+function persistSupportedLanguage(language: string | undefined): void {
+  const normalized = normalizeSupportedLanguage(language);
+  if (!normalized || typeof window === 'undefined') return;
+  try {
+    window.localStorage.setItem(LANGUAGE_STORAGE_KEY, normalized);
+  } catch {
+    // localStorage may be unavailable in restricted browser contexts.
+  }
+}
+
+export const i18nReady = i18n
+  .use(LanguageDetector)
+  .use(initReactI18next)
+  .init({
+    resources,
+    fallbackLng: DEFAULT_LANGUAGE,
+    supportedLngs: SUPPORTED_LANGUAGE_CODES,
+    load: 'currentOnly',
+    ns: namespaceList,
+    defaultNS: DEFAULT_NAMESPACE,
+    fallbackNS: false,
+    returnEmptyString: false,
+    interpolation: { escapeValue: false },
+    react: { useSuspense: false },
+    detection: {
+      order: ['querystring', 'localStorage', 'navigator', 'htmlTag'],
+      lookupQuerystring: 'lng',
+      lookupLocalStorage: LANGUAGE_STORAGE_KEY,
+      caches: [],
+      convertDetectedLanguage,
+    },
+  })
+  .then(() => {
+    const language = i18n.resolvedLanguage || i18n.language;
+    syncDocumentLanguage(language);
+    persistSupportedLanguage(language);
+  });
+
+i18n.on('languageChanged', (language) => {
+  const resolvedLanguage = i18n.resolvedLanguage || language;
+  syncDocumentLanguage(resolvedLanguage);
+  persistSupportedLanguage(resolvedLanguage);
+});
+
+export default i18n;

gitnexus-web/src/i18n/languages.ts

@@ -0,0 +1,42 @@
+export type SupportedLanguage = 'en' | 'zh-CN';
+
+export interface LanguageMetadata {
+  code: SupportedLanguage;
+  nativeName: string;
+  englishName: string;
+  dir: 'ltr' | 'rtl';
+}
+
+export const DEFAULT_LANGUAGE: SupportedLanguage = 'en';
+
+export const SUPPORTED_LANGUAGES: LanguageMetadata[] = [
+  { code: 'en', nativeName: 'English', englishName: 'English', dir: 'ltr' },
+  { code: 'zh-CN', nativeName: '简体中文', englishName: 'Simplified Chinese', dir: 'ltr' },
+];
+
+export const SUPPORTED_LANGUAGE_CODES = SUPPORTED_LANGUAGES.map((language) => language.code);
+
+export function normalizeSupportedLanguage(
+  code: string | undefined | null,
+): SupportedLanguage | null {
+  const normalized = code?.trim().split('.')[0]?.replace(/_/g, '-').toLowerCase();
+  if (!normalized) return null;
+  if (normalized === 'en' || normalized.startsWith('en-')) return 'en';
+  if (
+    normalized === 'zh' ||
+    normalized === 'zh-cn' ||
+    normalized.startsWith('zh-cn-') ||
+    normalized === 'zh-hans' ||
+    normalized.startsWith('zh-hans-')
+  ) {
+    return 'zh-CN';
+  }
+  return null;
+}
+
+export function getLanguageMetadata(code: string | undefined): LanguageMetadata {
+  const normalized = normalizeSupportedLanguage(code);
+  return (
+    SUPPORTED_LANGUAGES.find((language) => language.code === normalized) ?? SUPPORTED_LANGUAGES[0]
+  );
+}

gitnexus-web/src/i18n/progress.ts

@@ -0,0 +1,31 @@
+import type { TFunction } from 'i18next';
+
+export function translateAnalyzePhase(
+  phase: string,
+  message: string | undefined,
+  t: TFunction,
+): string {
+  const key = `common:analyzePhases.${phase}`;
+  const translated = t(key, { defaultValue: '' });
+  return translated || message || phase;
+}
+
+export function translateProgressMessage(message: string | undefined, t: TFunction): string {
+  if (!message) return '';
+  const key = PROGRESS_MESSAGE_KEYS[message];
+  return key ? t(key) : message;
+}
+
+const PROGRESS_MESSAGE_KEYS: Record<string, string> = {
+  'Connecting...': 'common:progress.connectingShort',
+  'Connecting to server...': 'common:progress.connecting',
+  'Validating server': 'common:progress.validatingServer',
+  'Validating server...': 'common:progress.validatingServerEllipsis',
+  'Downloading graph...': 'common:progress.downloadingGraph',
+  'Extracting file contents': 'common:progress.extractingFileContents',
+  'Processing...': 'common:progress.processing',
+  'Processing graph...': 'common:progress.processingGraph',
+  'Loading graph...': 'common:progress.loadingGraph',
+  Queued: 'common:analyzePhases.queued',
+  'Starting...': 'common:progress.starting',
+};

gitnexus-web/src/i18n/resources.ts

@@ -0,0 +1,20 @@
+import type { Resource } from 'i18next';
+
+const localeModules = import.meta.glob('../locales/*/*.json', {
+  eager: true,
+  import: 'default',
+}) as Record<string, Record<string, unknown>>;
+
+export const resources: Resource = {};
+export const namespaces = new Set<string>();
+
+for (const [path, translations] of Object.entries(localeModules)) {
+  const match = path.match(/\.\.\/locales\/([^/]+)\/([^/.]+)\.json$/);
+  if (!match) continue;
+  const [, language, namespace] = match;
+  resources[language] ??= {};
+  resources[language][namespace] = translations;
+  namespaces.add(namespace);
+}
+
+export const namespaceList = Array.from(namespaces).sort();

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

@@ -123,6 +123,67 @@ export {
  * defaults to `currentColor`, so Tailwind `text-*` utilities work the same as
  * with any other icon in this module.
  */
+/**
+ * GitLab tanuki mark — SVG path data from simple-icons (CC0-1.0).
+ *
+ * GitLab's logo (the tanuki/fox-head) is a registered trademark of GitLab Inc.
+ * We use it here only to indicate GitLab source-repo integration.
+ *
+ * API-compatible with `lucide-react` icons (`LucideProps`).
+ */
+export const Gitlab = forwardRef<SVGSVGElement, LucideProps>(function Gitlab(
+  {
+    size = 24,
+    color = 'currentColor',
+    className,
+    strokeWidth: _strokeWidth,
+    absoluteStrokeWidth: _absoluteStrokeWidth,
+    ...rest
+  },
+  ref,
+) {
+  const numericSize = typeof size === 'string' ? Number.parseFloat(size) : size;
+  const useSmallVariant = Number.isFinite(numericSize) && (numericSize as number) <= 16;
+
+  if (useSmallVariant) {
+    return (
+      <svg
+        ref={ref}
+        xmlns="http://www.w3.org/2000/svg"
+        width={size}
+        height={size}
+        viewBox="0 0 16 16"
+        fill={color}
+        className={className}
+        {...rest}
+      >
+        <path d="M8 15.282l1.855-5.717H6.145L8 15.282z" />
+        <path d="M8 15.282L6.145 9.565H2.333L8 15.282z" />
+        <path d="M2.333 9.565l-.944-2.942c-.09-.267.067-.553.333-.553h3.153L2.333 9.565z" />
+        <path d="M4.875 6.07L6.145 9.565H2.333l2.542-3.495z" />
+        <path d="M13.667 9.565l.944-2.942c.09-.267-.067-.553-.333-.553h-3.153l2.542 3.495z" />
+        <path d="M11.125 6.07L9.855 9.565h3.812l-2.542-3.495z" />
+        <path d="M8 15.282l1.855-5.717H6.145L8 15.282z" />
+      </svg>
+    );
+  }
+
+  return (
+    <svg
+      ref={ref}
+      xmlns="http://www.w3.org/2000/svg"
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill={color}
+      className={className}
+      {...rest}
+    >
+      <path d="m23.6004 9.5927-.0337-.0862L20.3.9814a.851.851 0 0 0-.3362-.405.8748.8748 0 0 0-.9997.0539.8748.8748 0 0 0-.29.4399l-2.2055 6.748H7.5375l-2.2057-6.748a.8573.8573 0 0 0-.29-.4412.8748.8748 0 0 0-.9997-.0537.8585.8585 0 0 0-.3362.4049L.4332 9.5015l-.0325.0862a6.0657 6.0657 0 0 0 2.0119 7.0105l.0113.0087.03.0213 4.976 3.7264 2.462 1.8633 1.4995 1.1321a1.0085 1.0085 0 0 0 1.2197 0l1.4995-1.1321 2.4619-1.8633 5.006-3.7489.0125-.01a6.0682 6.0682 0 0 0 2.0094-7.003z" />
+    </svg>
+  );
+});
+
 export const Github = forwardRef<SVGSVGElement, LucideProps>(function Github(
   {
     size = 24,

gitnexus-web/src/locales/en/chat.json

@@ -0,0 +1,36 @@
+{
+  "tabs": {
+    "chat": "Nexus AI",
+    "processes": "Processes"
+  },
+  "suggestions": {
+    "architecture": "Explain the project architecture",
+    "whatDoes": "What does this project do?",
+    "importantFiles": "Show me the most important files",
+    "apiHandlers": "Find all API handlers"
+  },
+  "empty": {
+    "title": "Ask me anything",
+    "description": "I can help you understand the architecture, find functions, or explain connections."
+  },
+  "input": {
+    "placeholder": "Ask about the codebase...",
+    "initializing": "Initializing AI agent...",
+    "configureProvider": "Configure an LLM provider to enable chat."
+  },
+  "actions": {
+    "closePanel": "Close Panel",
+    "scrollBottom": "Scroll to bottom",
+    "clearChat": "Clear chat",
+    "stopResponse": "Stop response"
+  },
+  "badges": {
+    "configureAI": "Configure AI",
+    "connecting": "Connecting"
+  },
+  "roles": {
+    "you": "You",
+    "assistant": "Nexus AI"
+  },
+  "newBadge": "NEW"
+}

gitnexus-web/src/locales/en/common.json

@@ -0,0 +1,85 @@
+{
+  "app": {
+    "name": "GitNexus",
+    "nexusAI": "Nexus AI"
+  },
+  "actions": {
+    "cancel": "Cancel",
+    "dismiss": "Dismiss",
+    "tryAgain": "Try again",
+    "hide": "Hide",
+    "retry": "Retry",
+    "copy": "Copy",
+    "copied": "Copied",
+    "close": "Close",
+    "run": "Run",
+    "clear": "Clear",
+    "remove": "Remove",
+    "focusInGraph": "Focus in graph",
+    "expand": "Expand",
+    "collapse": "Collapse"
+  },
+  "chat": {
+    "viewNodeInCodePanel": "View {{inner}} in Code panel",
+    "openInCodePanel": "Open in Code panel • {{inner}}",
+    "waitForVectorIndex": "Wait a moment, vector index is being created."
+  },
+  "counts": {
+    "files_one": "{{count}} file",
+    "files_other": "{{count}} files",
+    "nodes_one": "{{count}} node",
+    "nodes_other": "{{count}} nodes",
+    "edges_one": "{{count}} edge",
+    "edges_other": "{{count}} edges",
+    "symbols_one": "{{count}} symbol",
+    "symbols_other": "{{count}} symbols",
+    "flows_one": "{{count}} flow",
+    "flows_other": "{{count}} flows"
+  },
+  "progress": {
+    "connecting": "Connecting to server...",
+    "connectingShort": "Connecting...",
+    "validatingServer": "Validating server",
+    "validatingServerEllipsis": "Validating server...",
+    "downloadingGraph": "Downloading graph...",
+    "downloadedMb": "{{mb}} MB downloaded",
+    "downloadingWithPercent": "Downloading graph... {{percent}}%",
+    "downloadingMb": "Downloading... {{mb}} MB",
+    "processing": "Processing...",
+    "processingGraph": "Processing graph...",
+    "extractingFileContents": "Extracting file contents",
+    "loadingGraph": "Loading graph...",
+    "starting": "Starting...",
+    "executing": "Executing...",
+    "truncated": "... (truncated)",
+    "ready": "Ready",
+    "switchingRepository": "Switching repository...",
+    "loadingRepository": "Loading {{repo}}",
+    "validating": "Validating",
+    "failedSwitchRepository": "Failed to switch repository",
+    "unknownError": "Unknown error"
+  },
+  "analyzePhases": {
+    "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"
+  },
+  "units": {
+    "elapsedSeconds": "{{seconds}}s",
+    "elapsedMinutesSeconds": "{{minutes}}m {{seconds}}s"
+  }
+}

gitnexus-web/src/locales/en/errors.json

@@ -0,0 +1,19 @@
+{
+  "unknown": "Unknown error",
+  "connectFailed": "Failed to connect to server",
+  "loadGraphFailed": "Failed to load graph",
+  "failedToConnect": "Failed to connect",
+  "analysisFailed": "Analysis failed. Check server logs.",
+  "startAnalysisFailed": "Failed to start analysis",
+  "invalidGithubUrl": "Please enter a valid GitHub repository URL.",
+  "missingFolderPath": "Please enter a folder path.",
+  "backend": {
+    "reconnecting": "Server connection lost. Reconnecting…",
+    "network": "Unable to reach the GitNexus server. Make sure `gitnexus serve` is running.",
+    "timeout": "The server took too long to respond. Try again in a moment.",
+    "rateLimited": "Too many requests. Try again in {{seconds}}s.",
+    "notFound": "The requested repository or resource was not found.",
+    "client": "Request failed: {{message}}",
+    "server": "Server error: {{message}}"
+  }
+}

gitnexus-web/src/locales/en/graph.json

@@ -0,0 +1,174 @@
+{
+  "statusBar": {
+    "sponsor": "Sponsor",
+    "sponsorHint": "need to buy some API credits to run SWE-bench 😅"
+  },
+  "loading": {
+    "filesProgress": "{{processed}} / {{total}} files"
+  },
+  "toolCall": {
+    "status": {
+      "running": "running",
+      "completed": "completed",
+      "error": "error"
+    },
+    "tools": {
+      "search": "🔍 Search Code",
+      "cypher": "🔗 Cypher Query",
+      "grep": "🔎 Pattern Search",
+      "read": "📄 Read File",
+      "overview": "🗺️ Codebase Overview",
+      "explore": "🔬 Deep Dive",
+      "impact": "💥 Impact Analysis"
+    },
+    "query": "Query",
+    "input": "Input",
+    "result": "Result",
+    "searchPrefix": "Search: \"{{query}}\""
+  },
+  "embedding": {
+    "generateTitle": "Generate embeddings for semantic search",
+    "enable": "Enable Semantic Search",
+    "loadingModel": "Loading AI model...",
+    "embeddingNodes": "Embedding {{processed}}/{{total}} nodes",
+    "creatingIndex": "Creating vector index...",
+    "readyTitle": "Semantic search is ready! Use natural language in the AI chat.",
+    "ready": "Semantic Ready",
+    "errorTitle": "Embedding failed. Click to retry.",
+    "failedRetry": "Failed - Retry",
+    "fallback": {
+      "title": "WebGPU said \"nope\"",
+      "subtitle": "Your browser doesn't support GPU acceleration",
+      "description": "Couldn't create embeddings with WebGPU, so semantic search (Graph RAG) won't be as smart. The graph still works fine though!",
+      "options": "Your options:",
+      "useCpu": "Use CPU",
+      "useCpuDescriptionSmall": "Works but a bit slower",
+      "useCpuDescriptionLarge": "Works but way slower",
+      "estimated": "(~{{minutes}} min for {{count}} nodes)",
+      "skipIt": "Skip it",
+      "skipDescription": "Graph works, just no AI semantic search",
+      "smallCodebase": "Small codebase detected! CPU should be fine.",
+      "tip": "💡 Tip: Try Chrome or Edge for WebGPU support",
+      "skipEmbeddings": "Skip Embeddings",
+      "useCpuRecommended": "Use CPU (Recommended)",
+      "useCpuSlow": "Use CPU (Slow)"
+    }
+  },
+  "queryFab": {
+    "query": "Query",
+    "cypherQuery": "Cypher Query",
+    "examples": "Examples",
+    "run": "Run",
+    "noProject": "No project loaded. Load a project first.",
+    "dbNotReady": "Database not ready. Please wait for loading to complete.",
+    "executionFailed": "Query execution failed",
+    "exampleLabels": {
+      "functions": "All Functions",
+      "classes": "All Classes",
+      "interfaces": "All Interfaces",
+      "calls": "Function Calls",
+      "imports": "Import Dependencies"
+    },
+    "clear": "Clear",
+    "rows": "rows",
+    "highlighted": "highlighted",
+    "showingRows": "Showing 50 of {{count}} rows"
+  },
+  "fileTree": {
+    "expandPanel": "Expand Panel",
+    "fileExplorer": "File Explorer",
+    "filters": "Filters",
+    "collapsePanel": "Collapse Panel",
+    "searchFiles": "Search files...",
+    "noFilesLoaded": "No files loaded",
+    "all": "All",
+    "selectNodeDepth": "Select a node to apply depth filter",
+    "explorer": "Explorer",
+    "nodeTypes": "Node Types",
+    "nodeTypesDesc": "Toggle visibility of node types in the graph",
+    "edgeTypes": "Edge Types",
+    "edgeTypesDesc": "Toggle visibility of relationship types",
+    "focusDepth": "Focus Depth",
+    "focusDepthDesc": "Show nodes within N hops of selection",
+    "hops_one": "{{count}} hop",
+    "hops_other": "{{count}} hops",
+    "colorLegend": "Color Legend"
+  },
+  "codePanel": {
+    "expand": "Expand Code Panel",
+    "dragResize": "Drag to resize",
+    "title": "Code Inspector",
+    "clearCitations": "Clear AI citations",
+    "clearSelection": "Clear selection",
+    "loadingSource": "Loading source...",
+    "selectFile": "Select a file node to preview its contents.",
+    "code": "Code",
+    "selected": "Selected",
+    "aiCitations": "AI Citations",
+    "references_one": "{{count}} reference",
+    "references_other": "{{count}} references",
+    "lines_one": "{{count}} line",
+    "lines_other": "{{count}} lines",
+    "codeNotAvailable": "Code not available in memory for {{path}}"
+  },
+  "canvas": {
+    "zoomIn": "Zoom In",
+    "zoomOut": "Zoom Out",
+    "fit": "Fit to Screen",
+    "focusSelected": "Focus on Selected Node",
+    "clearSelection": "Clear Selection",
+    "clear": "Clear",
+    "stopLayout": "Stop Layout",
+    "runLayout": "Run Layout Again",
+    "layoutOptimizing": "Layout optimizing...",
+    "turnOffHighlights": "Turn off all highlights",
+    "turnOnHighlights": "Turn on AI highlights"
+  },
+  "processes": {
+    "unknownStep": "Unknown",
+    "allProcessesLabel_one": "All Processes ({{count}} combined)",
+    "allProcessesLabel_other": "All Processes ({{count}} combined)",
+    "emptyTitle": "No Processes Detected",
+    "emptyDescription": "Processes are execution flows traced from entry points. Load a codebase to see detected processes.",
+    "filterPlaceholder": "Filter processes...",
+    "detected_one": "{{count}} process detected",
+    "detected_other": "{{count}} processes detected",
+    "fullMap": "Full Process Map",
+    "viewCombined_one": "View combined map of {{count}} process",
+    "viewCombined_other": "View combined map of {{count}} processes",
+    "crossCommunity": "Cross-Community",
+    "intraCommunity": "Intra-Community",
+    "steps_one": "{{count}} step",
+    "steps_other": "{{count}} steps",
+    "clusters_one": "{{count}} cluster",
+    "clusters_other": "{{count}} clusters",
+    "highlightTitle": "Click to highlight in graph",
+    "removeHighlightTitle": "Click to remove highlight from graph",
+    "loading": "Loading...",
+    "viewing": "Viewing",
+    "view": "View"
+  },
+  "processFlow": {
+    "title": "Process: {{label}}",
+    "diagramTooLarge": "📊 Diagram Too Large",
+    "renderError": "⚠️ Render Error",
+    "tooComplex_one": "This diagram has {{count}} step and is too complex to render. Try viewing individual processes instead of \"All Processes\".",
+    "tooComplex_other": "This diagram has {{count}} steps and is too complex to render. Try viewing individual processes instead of \"All Processes\".",
+    "unableToRender_one": "Unable to render diagram. Steps: {{count}}",
+    "unableToRender_other": "Unable to render diagram. Steps: {{count}}",
+    "zoomOutTitle": "Zoom out (-)",
+    "zoomInTitle": "Zoom in (+)",
+    "resetTitle": "Reset zoom and pan",
+    "resetView": "Reset View",
+    "toggleFocus": "Toggle Focus",
+    "copyMermaid": "Copy Mermaid"
+  },
+  "diagram": {
+    "aiGenerated": "AI Generated Diagram",
+    "error": "Diagram Error",
+    "showSource": "Show source",
+    "label": "Diagram",
+    "expandTitle": "Expand",
+    "loading": "Loading diagram…"
+  }
+}