gitnexus 1.6.9-rc.44 → 1.6.9-rc.46

package/README.md

@@ -40,14 +40,14 @@ To configure MCP for your editor, run `npx gitnexus setup` once — or set it up
 
 | Editor                   | MCP | Skills | Hooks (auto-augment)                                                                       | Support      |
 | ------------------------ | --- | ------ | ------------------------------------------------------------------------------------------ | ------------ |
-| **Claude Code**          | Yes | Yes    | Yes (PreToolUse)                                                                           | **Full**     |
+| **Claude Code**          | Yes | Yes    | Yes (PreToolUse + PostToolUse)                                                             | **Full**     |
 | **Cursor**               | Yes | Yes    | Yes (postToolUse, [manual install](../gitnexus-cursor-integration/README.md#hook-install)) | **Full**     |
 | **Antigravity** (Google) | Yes | Yes    | Yes (AfterTool, [Gemini CLI hooks schema](https://geminicli.com/docs/hooks/reference/))    | **Full**     |
 | **Codex**                | Yes | Yes    | —                                                                                          | MCP + Skills |
-| **Windsurf**             | Yes | —      | —                                                                                          | MCP          |
 | **OpenCode**             | Yes | Yes    | —                                                                                          | MCP + Skills |
+| **Windsurf**             | Yes | —      | —                                                                                          | MCP          |
 
-> **Claude Code** gets the deepest integration: MCP tools + agent skills + PreToolUse hooks that automatically enrich grep/glob/bash calls with knowledge graph context.
+> **Claude Code** gets the deepest integration: MCP tools + agent skills + PreToolUse hooks that automatically enrich grep/glob/bash calls with knowledge graph context + PostToolUse hooks that detect a stale index after commits and prompt the agent to reindex.
 
 ### Community Integrations
 
@@ -122,31 +122,44 @@ The result is a **LadybugDB graph database** stored locally in `.gitnexus/` with
 
 ## MCP Tools
 
-Your AI agent gets these tools automatically:
-
-| Tool             | What It Does                                                     | `repo` Param |
-| ---------------- | ---------------------------------------------------------------- | ------------ |
-| `list_repos`     | Discover all indexed repositories (paginated — `limit`/`offset`) | —            |
-| `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     |
-
-> With one indexed repo, the `repo` param is optional. With multiple, specify which: `query({search_query: "auth", repo: "my-app"})`.
+Your AI agent gets **17 tools** (15 per-repo + 2 group) automatically:
+
+| Tool             | What It Does                                                           |
+| ---------------- | ----------------------------------------------------------------------- |
+| `list_repos`     | Discover all indexed repositories (paginated — `limit`/`offset`)        |
+| `query`          | Process-grouped hybrid search (BM25 + semantic + RRF)                   |
+| `context`        | 360-degree symbol view — categorized refs, process participation        |
+| `impact`         | Blast radius analysis with depth grouping and confidence                |
+| `trace`          | Shortest directed path between two symbols (call + class-member edges)  |
+| `detect_changes` | Git-diff impact — maps changed lines to affected processes              |
+| `check`          | Read-only structural checks against the indexed graph                   |
+| `rename`         | Multi-file coordinated rename with graph + text search                  |
+| `cypher`         | Raw Cypher graph queries                                                |
+| `route_map`      | API route map — which components fetch which endpoints, and handlers    |
+| `tool_map`       | MCP/RPC tool definitions — where they're defined and handled            |
+| `shape_check`    | Validate API response shapes against consumers' property accesses       |
+| `api_impact`     | Pre-change impact report for an API route handler                       |
+| `explain`        | Explain persisted taint findings (source→sink flows, `--pdg` indexes)   |
+| `pdg_query`      | Query control/data dependence at statement level (`--pdg` indexes)      |
+| `group_list`     | List configured repository groups                                       |
+| `group_sync`     | Rebuild a group's Contract Registry and cross-repo links                |
+
+> With one indexed repo, the `repo` param is optional. With multiple, specify which: `query({search_query: "auth", repo: "my-app"})`. Per-repo tools also take an optional `branch` for indexes pinned with `gitnexus analyze --branch`; omitting it queries the workspace index, which follows your checked-out working tree. `explain` and `pdg_query` need an index built with `gitnexus analyze --pdg`.
 
 ## MCP Resources
 
 | Resource                                | Purpose                                              |
 | --------------------------------------- | ---------------------------------------------------- |
 | `gitnexus://repos`                      | List all indexed repositories (read first)           |
+| `gitnexus://setup`                      | Setup and usage guidance for agents                  |
 | `gitnexus://repo/{name}/context`        | Codebase stats, staleness check, and available tools |
 | `gitnexus://repo/{name}/clusters`       | All functional clusters with cohesion scores         |
 | `gitnexus://repo/{name}/cluster/{name}` | Cluster members and details                          |
 | `gitnexus://repo/{name}/processes`      | All execution flows                                  |
 | `gitnexus://repo/{name}/process/{name}` | Full process trace with steps                        |
 | `gitnexus://repo/{name}/schema`         | Graph schema for Cypher queries                      |
+| `gitnexus://group/{name}/contracts`     | A group's extracted contracts and cross-links        |
+| `gitnexus://group/{name}/status`        | Staleness of repos in a group                        |
 
 ## MCP Prompts
 
@@ -164,7 +177,11 @@ gitnexus analyze [path]          # Index a repository (or update stale index)
 gitnexus analyze --repair-fts    # Fast path: rebuild/verify only FTS indexes on existing index data
 gitnexus analyze --force         # Full rebuild: re-parse + graph rebuild + FTS rebuild
 gitnexus analyze --embeddings    # Enable embedding generation (slower, better search)
+gitnexus analyze --skills        # Generate repo-specific skill files from detected communities
 gitnexus analyze --skip-agents-md  # Preserve custom AGENTS.md/CLAUDE.md gitnexus section edits
+gitnexus analyze --skip-skills   # Skip installing .claude/skills/gitnexus/ skill files
+gitnexus analyze --skip-git      # Index folders that are not Git repositories
+gitnexus analyze --workers <n>   # Parse worker pool size (>=1; default: cores-1, capped at 16)
 gitnexus analyze --verbose       # Log skipped files when parsers are unavailable
 gitnexus analyze --max-file-size 1024  # Skip files larger than N KB (default: 512, cap: 32768)
 gitnexus analyze --worker-timeout 60  # Increase worker idle timeout for slow parses
@@ -177,13 +194,16 @@ gitnexus status                  # Show index status for current repo
 gitnexus clean                   # Delete index for current repo
 gitnexus clean --all --force     # Delete all indexes
 gitnexus wiki [path]             # Generate LLM-powered docs from knowledge graph
-gitnexus wiki --model <model>    # Wiki with custom LLM model (default: gpt-4o-mini)
+gitnexus wiki --model <model>    # Wiki with custom LLM model (default: minimax/minimax-m2.5)
+gitnexus doctor                  # Show runtime platform capabilities and embedding configuration
 
 # Direct graph queries — the same tools the MCP server exposes, no MCP daemon needed
 gitnexus query "<concept>"                                    # Process-grouped hybrid search
 gitnexus context <symbol> [--uid <uid> | --file <path>]       # 360° symbol view; flags disambiguate a shared name
 gitnexus impact <symbol> [--uid <uid> | --file <path> | --kind <kind>]  # Blast radius; flags disambiguate a shared name
+gitnexus trace <from> <to>       # Shortest directed path between two symbols
 gitnexus detect-changes          # Map the working-tree diff to affected symbols and execution flows
+gitnexus check                   # Read-only structural checks against the indexed graph
 gitnexus cypher "<query>"        # Run a raw Cypher query against the knowledge graph
 
 # Repository groups (multi-repo / monorepo service tracking)
@@ -195,6 +215,7 @@ gitnexus group sync <name>                                     # Extract contrac
 gitnexus group contracts <name>  # Inspect extracted contracts and cross-links
 gitnexus group query <name> <q>  # Search execution flows across all repos in a group
 gitnexus group status <name>     # Check staleness of repos in a group
+gitnexus group impact <name> --target <symbol> --repo <groupPath>  # Cross-repo blast radius
 ```
 
 > **`gitnexus uninstall`** reverses `gitnexus setup` — it removes the GitNexus MCP entries, hooks, and skill directories it added to each detected editor. Skill directories are identified **by bundled gitnexus skill name** (e.g. `gitnexus-cli/`), so if you customized files inside an installed skill directory, back them up first. It is a dry-run preview by default and prints the exact paths it would remove; pass `--force` to apply. Per-repo indexes (`gitnexus clean --all`) and the global npm package (`npm uninstall -g gitnexus`) are left for you to remove.
@@ -219,7 +240,7 @@ GitNexus supports indexing multiple repositories. Each `gitnexus analyze` regist
 
 ## Supported Languages
 
-TypeScript, JavaScript, Python, Java, C, C++, C#, Go, Rust, PHP, Kotlin, Swift, Ruby
+TypeScript, JavaScript, Python, Java, C, C++, C#, Go, Rust, PHP, Kotlin, Swift, Ruby, Dart
 
 ### Language Feature Matrix
 
@@ -238,6 +259,7 @@ TypeScript, JavaScript, Python, Java, C, C++, C#, Go, Rust, PHP, Kotlin, Swift,
 | 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
 
@@ -249,12 +271,14 @@ GitNexus ships with skill files that teach AI agents how to use the tools effect
 - **Debugging** — Trace bugs through call chains
 - **Impact Analysis** — Analyze blast radius before changes
 - **Refactoring** — Plan safe refactors using dependency mapping
+- **Guide** — GitNexus tool/resource/schema reference for the agent
+- **CLI** — Run analyze/status/clean/wiki commands on request
 
-Installed automatically by both `gitnexus analyze` (per-repo) and `gitnexus setup` (global).
+Installed automatically by both `gitnexus analyze` (per-repo) and `gitnexus setup` (global). Run `gitnexus analyze --skills` to additionally generate repo-specific skills for each detected functional area under `.claude/skills/generated/`.
 
 ## Requirements
 
-- Node.js >= 18
+- Node.js >= 22
 - Git repository (uses git for commit tracking)
 
 ## Release candidates
@@ -340,7 +364,7 @@ gitnexus serve
 
 ### Installation fails with native module errors
 
-Some optional language grammars (Dart, Kotlin, Swift) require native compilation. If they fail, GitNexus still works — those languages will be skipped.
+Some optional language grammars (Dart, Proto, Swift, Kotlin) require native compilation. If they fail, GitNexus still works — those languages will be skipped. To skip them intentionally (no C++ toolchain needed), set `GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1` before installing.
 
 If `npm install -g gitnexus` fails on native modules:
 

package/dist/cli/analyze.js

@@ -1005,10 +1005,11 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
             // preserving the rest of the block (incl. --skills community rows). No-op
             // when the value already matches, so a routine up-to-date run is silent
             // (#1996 tri-review P2).
-            // Only refresh the repo-root AGENTS.md/CLAUDE.md base_ref for the
-            // PRIMARY/flat index (#2106 R2). A non-primary branch's up-to-date
-            // analyze must not churn the committed AGENTS.md — this mirrors the
-            // in-pipeline `if (!placement.branch)` gate around generateAIContextFiles.
+            // Only refresh the repo-root AGENTS.md/CLAUDE.md base_ref for the flat
+            // WORKSPACE index (#2106 R2, #2354). A pinned --branch sub-index's
+            // up-to-date analyze must not churn the committed AGENTS.md — this
+            // mirrors the in-pipeline `if (!placement.branch)` gate around
+            // generateAIContextFiles.
             let baseRefRefreshed = [];
             if (result.isPrimaryBranch !== false) {
                 try {

package/dist/cli/i18n/en.d.ts

@@ -28,7 +28,7 @@ export declare const en: {
     readonly 'status.currentCommit': "Current commit";
     readonly 'status.branch': "Branch";
     readonly 'status.detached': "(detached HEAD)";
-    readonly 'status.branchNotIndexed': "⚠️ current branch not indexed (primary index is for '{{primary}}'; run gitnexus analyze)";
+    readonly 'status.workspaceIndexLabel': "Workspace index: last analyzed on '{{primary}}' (re-run gitnexus analyze to follow the current branch)";
     readonly 'status.status': "Status";
     readonly 'status.upToDate': "✅ up-to-date";
     readonly 'status.stale': "⚠️ stale (re-run gitnexus analyze)";
@@ -162,7 +162,7 @@ export declare const en: {
     readonly 'help.option.analyze.embeddingBatchSize': "Number of nodes per embedding batch";
     readonly 'help.option.analyze.embeddingSubBatchSize': "Number of chunks per embedding model call";
     readonly 'help.option.analyze.embeddingDevice': "Embedding device: auto, cpu, dml, cuda, or wasm";
-    readonly 'help.option.index.force': "Register even if meta.json is missing (stats will be empty)";
+    readonly 'help.option.index.force': "Register even if index metadata is missing (stats will be empty)";
     readonly 'help.option.index.allowNonGit': "Allow registering folders that are not Git repositories";
     readonly 'help.option.port': "Port number";
     readonly 'help.option.serve.host': "Bind address (default: 127.0.0.1, use 0.0.0.0 for remote access)";
@@ -172,7 +172,7 @@ export declare const en: {
     readonly 'help.option.force.confirmation': "Skip confirmation prompt";
     readonly 'help.option.uninstall.force': "Apply the changes (default is a dry-run preview)";
     readonly 'help.option.clean.all': "Clean all indexed repos";
-    readonly 'help.option.clean.branch': "Delete only the named branch index (not the primary)";
+    readonly 'help.option.clean.branch': "Delete only the named branch index (not the workspace index)";
     readonly 'help.option.clean.lbugSidecars': "Clean quarantined LadybugDB missing-shadow WAL sidecars";
     readonly 'help.option.wiki.force': "Force full regeneration even if up to date";
     readonly 'help.option.wiki.provider': "LLM provider: openai, openrouter, azure, custom, cursor, claude, codex, or opencode (default: openai)";

package/dist/cli/i18n/en.js

@@ -28,7 +28,7 @@ export const en = {
     'status.currentCommit': 'Current commit',
     'status.branch': 'Branch',
     'status.detached': '(detached HEAD)',
-    'status.branchNotIndexed': "⚠️ current branch not indexed (primary index is for '{{primary}}'; run gitnexus analyze)",
+    'status.workspaceIndexLabel': "Workspace index: last analyzed on '{{primary}}' (re-run gitnexus analyze to follow the current branch)",
     'status.status': 'Status',
     'status.upToDate': '✅ up-to-date',
     'status.stale': '⚠️ stale (re-run gitnexus analyze)',
@@ -162,7 +162,7 @@ export const en = {
     'help.option.analyze.embeddingBatchSize': 'Number of nodes per embedding batch',
     'help.option.analyze.embeddingSubBatchSize': 'Number of chunks per embedding model call',
     'help.option.analyze.embeddingDevice': 'Embedding device: auto, cpu, dml, cuda, or wasm',
-    'help.option.index.force': 'Register even if meta.json is missing (stats will be empty)',
+    'help.option.index.force': 'Register even if index metadata is missing (stats will be empty)',
     'help.option.index.allowNonGit': 'Allow registering folders that are not Git repositories',
     'help.option.port': 'Port number',
     'help.option.serve.host': 'Bind address (default: 127.0.0.1, use 0.0.0.0 for remote access)',
@@ -172,7 +172,7 @@ export const en = {
     'help.option.force.confirmation': 'Skip confirmation prompt',
     'help.option.uninstall.force': 'Apply the changes (default is a dry-run preview)',
     'help.option.clean.all': 'Clean all indexed repos',
-    'help.option.clean.branch': 'Delete only the named branch index (not the primary)',
+    'help.option.clean.branch': 'Delete only the named branch index (not the workspace index)',
     'help.option.clean.lbugSidecars': 'Clean quarantined LadybugDB missing-shadow WAL sidecars',
     'help.option.wiki.force': 'Force full regeneration even if up to date',
     'help.option.wiki.provider': 'LLM provider: openai, openrouter, azure, custom, cursor, claude, codex, or opencode (default: openai)',

package/dist/cli/i18n/resources.d.ts

@@ -29,7 +29,7 @@ export declare const cliResources: {
         readonly 'status.currentCommit': "Current commit";
         readonly 'status.branch': "Branch";
         readonly 'status.detached': "(detached HEAD)";
-        readonly 'status.branchNotIndexed': "⚠️ current branch not indexed (primary index is for '{{primary}}'; run gitnexus analyze)";
+        readonly 'status.workspaceIndexLabel': "Workspace index: last analyzed on '{{primary}}' (re-run gitnexus analyze to follow the current branch)";
         readonly 'status.status': "Status";
         readonly 'status.upToDate': "✅ up-to-date";
         readonly 'status.stale': "⚠️ stale (re-run gitnexus analyze)";
@@ -163,7 +163,7 @@ export declare const cliResources: {
         readonly 'help.option.analyze.embeddingBatchSize': "Number of nodes per embedding batch";
         readonly 'help.option.analyze.embeddingSubBatchSize': "Number of chunks per embedding model call";
         readonly 'help.option.analyze.embeddingDevice': "Embedding device: auto, cpu, dml, cuda, or wasm";
-        readonly 'help.option.index.force': "Register even if meta.json is missing (stats will be empty)";
+        readonly 'help.option.index.force': "Register even if index metadata is missing (stats will be empty)";
         readonly 'help.option.index.allowNonGit': "Allow registering folders that are not Git repositories";
         readonly 'help.option.port': "Port number";
         readonly 'help.option.serve.host': "Bind address (default: 127.0.0.1, use 0.0.0.0 for remote access)";
@@ -173,7 +173,7 @@ export declare const cliResources: {
         readonly 'help.option.force.confirmation': "Skip confirmation prompt";
         readonly 'help.option.uninstall.force': "Apply the changes (default is a dry-run preview)";
         readonly 'help.option.clean.all': "Clean all indexed repos";
-        readonly 'help.option.clean.branch': "Delete only the named branch index (not the primary)";
+        readonly 'help.option.clean.branch': "Delete only the named branch index (not the workspace index)";
         readonly 'help.option.clean.lbugSidecars': "Clean quarantined LadybugDB missing-shadow WAL sidecars";
         readonly 'help.option.wiki.force': "Force full regeneration even if up to date";
         readonly 'help.option.wiki.provider': "LLM provider: openai, openrouter, azure, custom, cursor, claude, codex, or opencode (default: openai)";
@@ -271,7 +271,7 @@ export declare const cliResources: {
         'status.currentCommit': string;
         'status.branch': string;
         'status.detached': string;
-        'status.branchNotIndexed': string;
+        'status.workspaceIndexLabel': string;
         'status.status': string;
         'status.upToDate': string;
         'status.stale': string;

package/dist/cli/i18n/zh-CN.d.ts

@@ -28,7 +28,7 @@ export declare const zhCN: {
     'status.currentCommit': string;
     'status.branch': string;
     'status.detached': string;
-    'status.branchNotIndexed': string;
+    'status.workspaceIndexLabel': string;
     'status.status': string;
     'status.upToDate': string;
     'status.stale': string;

package/dist/cli/i18n/zh-CN.js

@@ -28,7 +28,7 @@ export const zhCN = {
     'status.currentCommit': '当前提交',
     'status.branch': '分支',
     'status.detached': '（分离 HEAD）',
-    'status.branchNotIndexed': "⚠️ 当前分支未索引（主索引对应 '{{primary}}'；请运行 gitnexus analyze）",
+    'status.workspaceIndexLabel': "工作区索引：最近在 '{{primary}}' 分支上分析（重新运行 gitnexus analyze 以跟随当前分支）",
     'status.status': '状态',
     'status.upToDate': '✅ 已是最新',
     'status.stale': '⚠️ 已过期（重新运行 gitnexus analyze）',
@@ -162,7 +162,7 @@ export const zhCN = {
     'help.option.analyze.embeddingBatchSize': '每个嵌入批次的节点数',
     'help.option.analyze.embeddingSubBatchSize': '每次嵌入模型调用的分块数',
     'help.option.analyze.embeddingDevice': '嵌入设备：auto、cpu、dml、cuda 或 wasm',
-    'help.option.index.force': '即使缺少 meta.json 也注册（统计为空）',
+    'help.option.index.force': '即使缺少索引元数据也注册（统计为空）',
     'help.option.index.allowNonGit': '允许注册非 Git 仓库文件夹',
     'help.option.port': '端口号',
     'help.option.serve.host': '绑定地址（默认：127.0.0.1；远程访问可用 0.0.0.0）',
@@ -172,7 +172,7 @@ export const zhCN = {
     'help.option.force.confirmation': '跳过确认提示',
     'help.option.uninstall.force': '应用更改（默认仅为预演预览）',
     'help.option.clean.all': '清理所有已索引仓库',
-    'help.option.clean.branch': '仅删除指定分支的索引（不影响主索引）',
+    'help.option.clean.branch': '仅删除指定分支的索引（不影响工作区索引）',
     'help.option.clean.lbugSidecars': '清理已隔离的 LadybugDB missing-shadow WAL sidecar',
     'help.option.wiki.force': '即使已是最新也强制完整重新生成',
     'help.option.wiki.provider': 'LLM 提供商：openai、openrouter、azure、custom、cursor、claude、codex 或 opencode（默认：openai）',

package/dist/cli/index-repo.d.ts

@@ -1,10 +1,14 @@
 /**
  * Index Command
  *
- * Registers an existing .gitnexus/ folder into the global registry so the
+ * Registers an existing GitNexus index into the global registry so the
  * MCP server can discover the repo without running a full `gitnexus analyze`.
  *
- * Useful when a pre-built .gitnexus/ directory is already present (e.g. after
+ * The index can be either:
+ * - A per-worktree gitnexus.json file under .gitnexus/ (new format, worktree-compatible)
+ * - A legacy .gitnexus/meta.json file (auto-migrated on analyze)
+ *
+ * Useful when a pre-built index is already present (e.g. after
  * cloning a repo that ships its index, restoring from backup, or using a
  * shared team index).
  */

package/dist/cli/index-repo.js

@@ -1,16 +1,20 @@
 /**
  * Index Command
  *
- * Registers an existing .gitnexus/ folder into the global registry so the
+ * Registers an existing GitNexus index into the global registry so the
  * MCP server can discover the repo without running a full `gitnexus analyze`.
  *
- * Useful when a pre-built .gitnexus/ directory is already present (e.g. after
+ * The index can be either:
+ * - A per-worktree gitnexus.json file under .gitnexus/ (new format, worktree-compatible)
+ * - A legacy .gitnexus/meta.json file (auto-migrated on analyze)
+ *
+ * Useful when a pre-built index is already present (e.g. after
  * cloning a repo that ships its index, restoring from backup, or using a
  * shared team index).
  */
 import path from 'path';
 import fs from 'fs/promises';
-import { getStoragePaths, loadMeta, ensureGitNexusIgnored, registerRepo, } from '../storage/repo-manager.js';
+import { getStoragePaths, INDEX_METADATA_FILE, loadMeta, ensureGitNexusIgnored, registerRepo, } from '../storage/repo-manager.js';
 import { getGitRoot, getRemoteUrl, isGitRepo } from '../storage/git.js';
 export const indexCommand = async (inputPathParts, options) => {
     console.log('\n  GitNexus Index\n');
@@ -50,22 +54,35 @@ export const indexCommand = async (inputPathParts, options) => {
         return;
     }
     const { storagePath, lbugPath } = getStoragePaths(repoPath);
-    // ── Verify .gitnexus/ exists ──────────────────────────────────────
+    // ── Verify index exists (metadata file, legacy metadata, or restorable DB) ─
+    let hasMetadataIndex = false;
+    let hasLegacyIndex = false;
+    let hasLbugIndex = false;
+    try {
+        await fs.access(path.join(storagePath, INDEX_METADATA_FILE));
+        hasMetadataIndex = true;
+    }
+    catch { }
     try {
-        await fs.access(storagePath);
+        await fs.access(path.join(storagePath, 'meta.json'));
+        hasLegacyIndex = true;
     }
-    catch {
-        console.log(`  No .gitnexus/ folder found at: ${storagePath}`);
+    catch { }
+    try {
+        await fs.access(lbugPath);
+        hasLbugIndex = true;
+    }
+    catch { }
+    if (!hasMetadataIndex && !hasLegacyIndex && !hasLbugIndex) {
+        console.log(`  No GitNexus index found.`);
+        console.log(`  Expected gitnexus.json, .gitnexus/meta.json, or LadybugDB at: ${storagePath}`);
         console.log('  Run `gitnexus analyze` to build the index first.\n');
         process.exitCode = 1;
         return;
     }
     // ── Verify lbug database exists ───────────────────────────────────
-    try {
-        await fs.access(lbugPath);
-    }
-    catch {
-        console.log(`  .gitnexus/ folder exists but contains no LadybugDB index.`);
+    if (!hasLbugIndex) {
+        console.log(`  Index exists but contains no LadybugDB database.`);
         console.log('  Run `gitnexus analyze` to build the index.\n');
         process.exitCode = 1;
         return;
@@ -74,7 +91,7 @@ export const indexCommand = async (inputPathParts, options) => {
     let meta = await loadMeta(storagePath);
     if (!meta) {
         if (!options?.force) {
-            console.log(`  .gitnexus/ exists but meta.json is missing.`);
+            console.log(`  gitnexus.json or .gitnexus/meta.json is missing.`);
             console.log('  Use --force to register anyway (stats will be empty),');
             console.log('  or run `gitnexus analyze` to rebuild properly.\n');
             process.exitCode = 1;

package/dist/cli/index.js

@@ -49,9 +49,9 @@ program
     'for supported languages. Opt-in; off by default. (#2081 M1)')
     .option('--default-branch <branch>', 'Default branch used in the generated regression-compare example (base_ref). ' +
     'Falls back to .gitnexusrc, then auto-detected origin/HEAD, then "main".')
-    .option('--branch <name>', 'Index the working tree under a specific branch slot (multi-branch indexing). ' +
-    'Defaults to the checked-out branch; the primary/first-indexed branch keeps the ' +
-    'flat index and others get their own. Distinct from --default-branch (cosmetic base_ref).')
+    .option('--branch <name>', 'Pin the working tree into a dedicated per-branch index slot (multi-branch indexing). ' +
+    'Without this flag, analyze always updates the workspace index, which follows the ' +
+    'checked-out working tree. Distinct from --default-branch (cosmetic base_ref).')
     .option('--no-stats', 'Omit volatile file/symbol counts from AGENTS.md and CLAUDE.md')
     .option('--skip-skills', 'Skip installing standard GitNexus skill files under .claude/skills/gitnexus/. ' +
     'Does not suppress community skills from --skills (those use .claude/skills/generated/). ' +
@@ -123,7 +123,7 @@ program
 program
     .command('index [path...]')
     .description('Register an existing .gitnexus/ folder into the global registry (no re-analysis needed)')
-    .option('-f, --force', 'Register even if meta.json is missing (stats will be empty)')
+    .option('-f, --force', 'Register even if index metadata is missing (stats will be empty)')
     .option('--allow-non-git', 'Allow registering folders that are not Git repositories')
     .action(createLazyAction(() => import('./index-repo.js'), 'indexCommand'));
 program
@@ -158,7 +158,7 @@ program
     .description('Delete GitNexus index for current repo')
     .option('-f, --force', 'Skip confirmation prompt')
     .option('--all', 'Clean all indexed repos')
-    .option('--branch <name>', 'Delete only the named branch index (not the primary)')
+    .option('--branch <name>', 'Delete only the named branch index (not the workspace index)')
     .option('--lbug-sidecars', 'Clean quarantined LadybugDB missing-shadow WAL sidecars')
     .action(createLazyAction(() => import('./clean.js'), 'cleanCommand'));
 program

package/dist/cli/remove.d.ts

@@ -1,9 +1,12 @@
 /**
  * Remove Command (#664)
  *
- * Delete the `.gitnexus/` index for a registered repo and unregister it
- * from the global registry (~/.gitnexus/registry.json). The target is
- * identified by alias / basename-derived name / remote-inferred name /
+ * Delete the `.gitnexus/` index directory for a registered repo (including
+ * both metadata filenames — gitnexus.json and its legacy meta.json mirror —
+ * which live inside it) and unregister it from the global registry
+ * (~/.gitnexus/registry.json).
+ *
+ * The target is identified by alias / basename-derived name / remote-inferred name /
  * absolute path — no `--repo` flag, just a positional argument so the
  * destructive-command ergonomics match `clean` (which is also
  * destructive but scoped to `process.cwd()`).

package/dist/cli/remove.js

@@ -1,9 +1,12 @@
 /**
  * Remove Command (#664)
  *
- * Delete the `.gitnexus/` index for a registered repo and unregister it
- * from the global registry (~/.gitnexus/registry.json). The target is
- * identified by alias / basename-derived name / remote-inferred name /
+ * Delete the `.gitnexus/` index directory for a registered repo (including
+ * both metadata filenames — gitnexus.json and its legacy meta.json mirror —
+ * which live inside it) and unregister it from the global registry
+ * (~/.gitnexus/registry.json).
+ *
+ * The target is identified by alias / basename-derived name / remote-inferred name /
  * absolute path — no `--repo` flag, just a positional argument so the
  * destructive-command ergonomics match `clean` (which is also
  * destructive but scoped to `process.cwd()`).

package/dist/cli/status.js

@@ -30,25 +30,25 @@ export const statusCommand = async () => {
     }
     const currentCommit = getCurrentCommit(repo.repoPath);
     const currentBranch = getCurrentBranch(repo.repoPath);
-    // Pick the index matching the checked-out branch (#2106). The flat index
-    // belongs to the primary branch (repo.meta.branch); when the current branch
-    // differs and has its own index, report that one. Legacy/no-branch metas and
-    // detached HEAD fall through to the flat index (unchanged behavior).
+    // Pick the index matching the checked-out branch (#2106/#2354). A pinned
+    // `--branch` sub-index for the current branch wins; otherwise report the
+    // flat workspace index, which follows the checked-out working tree — the
+    // commit comparison below then says whether it needs a re-analyze. Legacy/
+    // no-branch metas and detached HEAD also fall through to the flat index.
     let activeMeta = repo.meta;
-    let currentBranchIndexed = true;
+    let workspaceLagsBranch = false;
     if (currentBranch && repo.meta.branch && currentBranch !== repo.meta.branch) {
         const { metaPath } = getStoragePaths(repo.repoPath, currentBranch);
         const branchMeta = await loadMeta(path.dirname(metaPath));
         if (branchMeta)
             activeMeta = branchMeta;
         else
-            currentBranchIndexed = false;
+            workspaceLagsBranch = true;
     }
     console.log(`${t('status.repository')}: ${repo.repoPath}`);
     console.log(`${t('status.branch')}: ${currentBranch ?? t('status.detached')}`);
-    if (!currentBranchIndexed) {
-        console.log(`${t('status.status')}: ${t('status.branchNotIndexed', { primary: repo.meta.branch ?? '' })}`);
-        return;
+    if (workspaceLagsBranch) {
+        console.log(t('status.workspaceIndexLabel', { primary: repo.meta.branch ?? '' }));
     }
     const isUpToDate = currentCommit === activeMeta.lastCommit;
     console.log(`${t('status.indexed')}: ${new Date(activeMeta.indexedAt).toLocaleString()}`);

package/dist/core/group/bridge-db.d.ts

@@ -110,7 +110,6 @@ export declare function queryBridge<T>(handle: BridgeHandle, cypher: string, par
  * is a lease release, so the file may stay open under other readers.
  */
 export declare function closeBridgeDb(handle: BridgeHandle): Promise<void>;
-export declare function retryRename(src: string, dst: string, attempts?: number): Promise<void>;
 export declare function writeBridgeMeta(groupDir: string, meta: BridgeMeta): Promise<void>;
 export declare function readBridgeMeta(groupDir: string): Promise<BridgeMeta>;
 export interface WriteBridgeInput {

package/dist/core/group/bridge-db.js

@@ -6,6 +6,7 @@ import { BRIDGE_SCHEMA_QUERIES, BRIDGE_SCHEMA_VERSION } from './bridge-schema.js
 import { closeLbugConnection, openLbugConnection, } from '../lbug/lbug-config.js';
 import { dedupeContracts, dedupeCrossLinks } from './normalization.js';
 import { createLogger } from '../logger.js';
+import { retryRename } from '../../storage/fs-atomic.js';
 const bridgeLogger = createLogger('bridge-db', {
     debugEnvVar: 'GITNEXUS_DEBUG_BRIDGE',
 });
@@ -512,24 +513,6 @@ export async function closeBridgeDb(handle) {
 // The read-only CHECKPOINT skip above remains the load-bearing fix on
 // Linux/macOS.
 /* ------------------------------------------------------------------ */
-/*  retryRename — handles transient EBUSY/EPERM/EACCES on Windows    */
-/* ------------------------------------------------------------------ */
-const RETRY_CODES = new Set(['EBUSY', 'EPERM', 'EACCES']);
-export async function retryRename(src, dst, attempts = 3) {
-    for (let i = 1; i <= attempts; i++) {
-        try {
-            await fsp.rename(src, dst);
-            return;
-        }
-        catch (err) {
-            const code = err.code;
-            if (!code || !RETRY_CODES.has(code) || i === attempts)
-                throw err;
-            await new Promise((r) => setTimeout(r, 100 * Math.pow(2, i - 1)));
-        }
-    }
-}
-/* ------------------------------------------------------------------ */
 /*  writeBridgeMeta / readBridgeMeta                                  */
 /* ------------------------------------------------------------------ */
 export async function writeBridgeMeta(groupDir, meta) {

package/dist/core/group/service.js

@@ -5,6 +5,7 @@
 import fsp from 'node:fs/promises';
 import path from 'node:path';
 import { checkStaleness } from '../git-staleness.js';
+import { loadMeta } from '../../storage/repo-manager.js';
 import { GroupNotFoundError, loadGroupConfig } from './config-parser.js';
 import { fileMatchesServicePrefix, normalizeServicePrefix, repoInSubgroup, } from './group-path-utils.js';
 import { getDefaultGitnexusDir, getGroupDir, listGroups, readContractRegistry } from './storage.js';
@@ -370,9 +371,7 @@ export class GroupService {
         for (const [repoPath, registryName] of Object.entries(config.repos)) {
             try {
                 const repoObj = await this.port.resolveRepo(registryName);
-                const metaPath = path.join(repoObj.storagePath, 'meta.json');
-                const metaRaw = await fsp.readFile(metaPath, 'utf-8').catch(() => '{}');
-                const meta = JSON.parse(metaRaw);
+                const meta = (await loadMeta(repoObj.storagePath)) ?? {};
                 const staleness = meta.lastCommit
                     ? checkStaleness(repoObj.repoPath, meta.lastCommit)
                     : { isStale: true, commitsBehind: -1 };

package/dist/core/group/storage.js

@@ -3,7 +3,7 @@ import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import { randomBytes } from 'node:crypto';
-import { retryRename } from './bridge-db.js';
+import { retryRename } from '../../storage/fs-atomic.js';
 /**
  * Build an unpredictable suffix for atomic-write tmp files. Replaces the
  * previous `Date.now()` pattern which CodeQL flagged as