@veewo/gitnexus 1.5.3 → 1.5.4

package/dist/cli/clean.d.ts

@@ -1,8 +1,9 @@
 /**
  * Clean Command
  *
- * Removes the .gitnexus index from the current repository.
- * Also unregisters it from the global registry.
+ * Removes the GitNexus index from the current repository while preserving
+ * configuration files (e.g. sync-manifest.txt). Also unregisters the repo
+ * from the global registry.
  */
 export declare const cleanCommand: (options?: {
     force?: boolean;

package/dist/cli/clean.js

@@ -1,11 +1,32 @@
 /**
  * Clean Command
  *
- * Removes the .gitnexus index from the current repository.
- * Also unregisters it from the global registry.
+ * Removes the GitNexus index from the current repository while preserving
+ * configuration files (e.g. sync-manifest.txt). Also unregisters the repo
+ * from the global registry.
  */
 import fs from 'fs/promises';
+import path from 'path';
 import { findRepo, unregisterRepo, listRegisteredRepos } from '../storage/repo-manager.js';
+/** Files under .gitnexus/ that are configuration, not index data. */
+const PRESERVE_FILES = new Set(['sync-manifest.txt']);
+async function cleanStoragePath(storagePath) {
+    let entries;
+    try {
+        entries = await fs.readdir(storagePath);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return;
+        throw err;
+    }
+    for (const entry of entries) {
+        if (PRESERVE_FILES.has(entry))
+            continue;
+        const fullPath = path.join(storagePath, entry);
+        await fs.rm(fullPath, { recursive: true, force: true });
+    }
+}
 export const cleanCommand = async (options) => {
     // --all flag: clean all indexed repos
     if (options?.all) {
@@ -15,22 +36,22 @@ export const cleanCommand = async (options) => {
                 console.log('No indexed repositories found.');
                 return;
             }
-            console.log(`This will delete GitNexus indexes for ${entries.length} repo(s):`);
+            console.log(`This will clean GitNexus indexes for ${entries.length} repo(s):`);
             for (const entry of entries) {
                 console.log(`  - ${entry.name} (${entry.path})`);
             }
-            console.log('\nRun with --force to confirm deletion.');
+            console.log('\nRun with --force to confirm.');
             return;
         }
         const entries = await listRegisteredRepos();
         for (const entry of entries) {
             try {
-                await fs.rm(entry.storagePath, { recursive: true, force: true });
+                await cleanStoragePath(entry.storagePath);
                 await unregisterRepo(entry.path);
-                console.log(`Deleted: ${entry.name} (${entry.storagePath})`);
+                console.log(`Cleaned: ${entry.name} (${entry.storagePath})`);
             }
             catch (err) {
-                console.error(`Failed to delete ${entry.name}:`, err);
+                console.error(`Failed to clean ${entry.name}:`, err);
             }
         }
         return;
@@ -44,17 +65,17 @@ export const cleanCommand = async (options) => {
     }
     const repoName = repo.repoPath.split(/[/\\]/).pop() || repo.repoPath;
     if (!options?.force) {
-        console.log(`This will delete the GitNexus index for: ${repoName}`);
+        console.log(`This will clean the GitNexus index for: ${repoName}`);
         console.log(`   Path: ${repo.storagePath}`);
-        console.log('\nRun with --force to confirm deletion.');
+        console.log('\nRun with --force to confirm.');
         return;
     }
     try {
-        await fs.rm(repo.storagePath, { recursive: true, force: true });
+        await cleanStoragePath(repo.storagePath);
         await unregisterRepo(repo.repoPath);
-        console.log(`Deleted: ${repo.storagePath}`);
+        console.log(`Cleaned: ${repo.storagePath}`);
     }
     catch (err) {
-        console.error('Failed to delete:', err);
+        console.error('Failed to clean:', err);
     }
 };

package/dist/core/ingestion/parsing-processor.js

@@ -104,8 +104,10 @@ const processParsingSequential = async (graph, files, symbolTable, astCache, onF
             skippedLanguages.set(language, (skippedLanguages.get(language) || 0) + 1);
             continue;
         }
-        // Skip files larger than the max tree-sitter buffer (32 MB)
-        if (file.content.length > TREE_SITTER_MAX_BUFFER)
+        // Skip files larger than the max tree-sitter buffer (32 MB).
+        // Use UTF-8 bytes, not JS string length, because tree-sitter buffer sizing
+        // is byte-oriented and multi-byte source can otherwise slip past the cap.
+        if (Buffer.byteLength(file.content, 'utf8') > TREE_SITTER_MAX_BUFFER)
             continue;
         try {
             await loadLanguage(language, file.path);

package/dist/core/ingestion/workers/parse-worker.js

@@ -14,26 +14,8 @@ import Ruby from 'tree-sitter-ruby';
 import { createRequire } from 'node:module';
 import { SupportedLanguages } from '../../../config/supported-languages.js';
 import { LANGUAGE_QUERIES } from '../tree-sitter-queries.js';
-import { TREE_SITTER_MAX_BUFFER } from '../constants.js';
+import { getTreeSitterBufferSize, TREE_SITTER_MAX_BUFFER } from '../constants.js';
 const _require = createRequire(import.meta.url);
-// tree-sitter-gdscript is an optionalDependency — may not be installed
-let GDScript = null;
-try {
-    GDScript = _require('tree-sitter-gdscript');
-}
-catch { }
-// tree-sitter-swift is an optionalDependency — may not be installed
-let Swift = null;
-try {
-    Swift = _require('tree-sitter-swift');
-}
-catch { }
-// tree-sitter-kotlin is an optionalDependency — may not be installed
-let Kotlin = null;
-try {
-    Kotlin = _require('tree-sitter-kotlin');
-}
-catch { }
 import { getLanguageFromFilename, FUNCTION_NODE_TYPES, extractFunctionName, isBuiltInOrNoise, getDefinitionNodeFromCaptures, findEnclosingClassId, extractMethodSignature, countCallArguments, inferCallForm, extractReceiverName, extractReceiverNode, CALL_EXPRESSION_TYPES, extractCallChain, } from '../utils.js';
 import { buildTypeEnv } from '../type-env.js';
 import { isNodeExported } from '../export-detection.js';
@@ -47,7 +29,7 @@ import { callRouters } from '../call-routing.js';
 // Worker-local parser + language map
 // ============================================================================
 const parser = new Parser();
-const languageMap = {
+const requiredLanguageMap = {
     [SupportedLanguages.JavaScript]: JavaScript,
     [SupportedLanguages.TypeScript]: TypeScript.typescript,
     [`${SupportedLanguages.TypeScript}:tsx`]: TypeScript.tsx,
@@ -58,11 +40,60 @@ const languageMap = {
     [SupportedLanguages.CSharp]: CSharp,
     [SupportedLanguages.Go]: Go,
     [SupportedLanguages.Rust]: Rust,
-    ...(Kotlin ? { [SupportedLanguages.Kotlin]: Kotlin } : {}),
     [SupportedLanguages.PHP]: PHP.php_only,
     [SupportedLanguages.Ruby]: Ruby,
-    ...(Swift ? { [SupportedLanguages.Swift]: Swift } : {}),
-    ...(GDScript ? { [SupportedLanguages.GDScript]: GDScript } : {}),
+};
+const optionalLanguagePackages = {
+    [SupportedLanguages.GDScript]: 'tree-sitter-gdscript',
+    [SupportedLanguages.Swift]: 'tree-sitter-swift',
+    [SupportedLanguages.Kotlin]: 'tree-sitter-kotlin',
+};
+const optionalLanguageCache = new Map();
+const optionalAvailabilityCache = new Map();
+const isOptionalLanguageInstalled = (language) => {
+    if (optionalAvailabilityCache.has(language)) {
+        return optionalAvailabilityCache.get(language);
+    }
+    const packageName = optionalLanguagePackages[language];
+    if (!packageName) {
+        optionalAvailabilityCache.set(language, false);
+        return false;
+    }
+    try {
+        _require.resolve(packageName);
+        optionalAvailabilityCache.set(language, true);
+        return true;
+    }
+    catch {
+        optionalAvailabilityCache.set(language, false);
+        return false;
+    }
+};
+const loadOptionalLanguage = (language) => {
+    if (optionalLanguageCache.has(language)) {
+        return optionalLanguageCache.get(language);
+    }
+    const packageName = optionalLanguagePackages[language];
+    if (!packageName) {
+        optionalLanguageCache.set(language, null);
+        return null;
+    }
+    try {
+        const grammar = _require(packageName);
+        optionalLanguageCache.set(language, grammar);
+        return grammar;
+    }
+    catch {
+        optionalLanguageCache.set(language, null);
+        optionalAvailabilityCache.set(language, false);
+        return null;
+    }
+};
+const resolveLanguage = (key, language) => {
+    if (key in requiredLanguageMap) {
+        return requiredLanguageMap[key];
+    }
+    return loadOptionalLanguage(language);
 };
 /**
  * Check if a language grammar is available in this worker.
@@ -74,13 +105,13 @@ const isLanguageAvailable = (language, filePath) => {
     const key = language === SupportedLanguages.TypeScript && filePath.endsWith('.tsx')
         ? `${language}:tsx`
         : language;
-    return key in languageMap && languageMap[key] != null;
+    return key in requiredLanguageMap || isOptionalLanguageInstalled(language);
 };
 const setLanguage = (language, filePath) => {
     const key = language === SupportedLanguages.TypeScript && filePath.endsWith('.tsx')
         ? `${language}:tsx`
         : language;
-    const lang = languageMap[key];
+    const lang = resolveLanguage(key, language);
     if (!lang)
         throw new Error(`Unsupported language: ${language}`);
     parser.setLanguage(lang);
@@ -720,27 +751,23 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
         return;
     }
     for (const file of files) {
-        // Skip files larger than the max tree-sitter buffer (32 MB)
-        if (file.content.length > TREE_SITTER_MAX_BUFFER)
+        // Skip files larger than the max tree-sitter buffer (32 MB).
+        // tree-sitter buffer sizing is byte-oriented; JS string length undercounts
+        // UTF-8 multi-byte source and can route oversized input into native code.
+        if (Buffer.byteLength(file.content, 'utf8') > TREE_SITTER_MAX_BUFFER)
             continue;
         let tree;
         let usedRawContentFallback = false;
         try {
-            const MAX_CHUNK = 4096;
-            tree = parser.parse((index) => {
-                if (index >= file.content.length)
-                    return null;
-                return file.content.slice(index, index + MAX_CHUNK);
+            tree = parser.parse(file.content, null, {
+                bufferSize: getTreeSitterBufferSize(Buffer.byteLength(file.content, 'utf8')),
             });
         }
         catch (err) {
             if (file.rawContent && file.rawContent !== file.content) {
                 try {
-                    const MAX_CHUNK = 4096;
-                    tree = parser.parse((index) => {
-                        if (index >= file.rawContent.length)
-                            return null;
-                        return file.rawContent.slice(index, index + MAX_CHUNK);
+                    tree = parser.parse(file.rawContent, null, {
+                        bufferSize: getTreeSitterBufferSize(Buffer.byteLength(file.rawContent, 'utf8')),
                     });
                     usedRawContentFallback = true;
                 }
@@ -756,11 +783,8 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
         }
         if (file.rawContent && file.rawContent !== file.content && tree.rootNode?.hasError) {
             try {
-                const MAX_CHUNK = 4096;
-                const rawTree = parser.parse((index) => {
-                    if (index >= file.rawContent.length)
-                        return null;
-                    return file.rawContent.slice(index, index + MAX_CHUNK);
+                const rawTree = parser.parse(file.rawContent, null, {
+                    bufferSize: getTreeSitterBufferSize(Buffer.byteLength(file.rawContent, 'utf8')),
                 });
                 if (!rawTree.rootNode?.hasError) {
                     tree = rawTree;

package/dist/core/tree-sitter/parser-loader.d.ts

@@ -4,9 +4,13 @@ export declare const isLanguageAvailable: (language: SupportedLanguages) => bool
 export declare const loadParser: () => Promise<Parser>;
 export declare const loadLanguage: (language: SupportedLanguages, filePath?: string) => Promise<void>;
 /**
- * Parse source code using tree-sitter's chunked callback API.
- * Avoids the native binding's single-buffer size limit (< 32768 bytes)
- * that causes "Invalid argument" errors on large files.
+ * Parse source code using tree-sitter's string input path with an adaptive
+ * native buffer size.
+ *
+ * The callback input API receives byte offsets. Returning JavaScript string
+ * slices from those byte offsets is unsafe for UTF-8/multi-byte content and has
+ * caused native tree-sitter crashes in large repositories. Use the stable string
+ * input path instead and raise tree-sitter's internal buffer for large files.
  *
  * @param content - Full source file content as UTF-8 string
  * @param oldTree - Optional previous tree for incremental parsing (must call tree.edit() first)

package/dist/core/tree-sitter/parser-loader.js

@@ -12,27 +12,10 @@ import PHP from 'tree-sitter-php';
 import Ruby from 'tree-sitter-ruby';
 import { createRequire } from 'node:module';
 import { SupportedLanguages } from '../../config/supported-languages.js';
+import { getTreeSitterBufferSize } from '../ingestion/constants.js';
 const _require = createRequire(import.meta.url);
-// tree-sitter-gdscript is an optionalDependency — may not be installed
-let GDScript = null;
-try {
-    GDScript = _require('tree-sitter-gdscript');
-}
-catch { }
-// tree-sitter-swift is an optionalDependency — may not be installed
-let Swift = null;
-try {
-    Swift = _require('tree-sitter-swift');
-}
-catch { }
-// tree-sitter-kotlin is an optionalDependency — may not be installed
-let Kotlin = null;
-try {
-    Kotlin = _require('tree-sitter-kotlin');
-}
-catch { }
 let parser = null;
-const languageMap = {
+const requiredLanguageMap = {
     [SupportedLanguages.JavaScript]: JavaScript,
     [SupportedLanguages.TypeScript]: TypeScript.typescript,
     [`${SupportedLanguages.TypeScript}:tsx`]: TypeScript.tsx,
@@ -43,13 +26,62 @@ const languageMap = {
     [SupportedLanguages.CSharp]: CSharp,
     [SupportedLanguages.Go]: Go,
     [SupportedLanguages.Rust]: Rust,
-    ...(Kotlin ? { [SupportedLanguages.Kotlin]: Kotlin } : {}),
     [SupportedLanguages.PHP]: PHP.php_only,
     [SupportedLanguages.Ruby]: Ruby,
-    ...(Swift ? { [SupportedLanguages.Swift]: Swift } : {}),
-    ...(GDScript ? { [SupportedLanguages.GDScript]: GDScript } : {}),
 };
-export const isLanguageAvailable = (language) => language in languageMap;
+const optionalLanguagePackages = {
+    [SupportedLanguages.GDScript]: 'tree-sitter-gdscript',
+    [SupportedLanguages.Swift]: 'tree-sitter-swift',
+    [SupportedLanguages.Kotlin]: 'tree-sitter-kotlin',
+};
+const optionalLanguageCache = new Map();
+const optionalAvailabilityCache = new Map();
+const isOptionalLanguageInstalled = (language) => {
+    if (optionalAvailabilityCache.has(language)) {
+        return optionalAvailabilityCache.get(language);
+    }
+    const packageName = optionalLanguagePackages[language];
+    if (!packageName) {
+        optionalAvailabilityCache.set(language, false);
+        return false;
+    }
+    try {
+        _require.resolve(packageName);
+        optionalAvailabilityCache.set(language, true);
+        return true;
+    }
+    catch {
+        optionalAvailabilityCache.set(language, false);
+        return false;
+    }
+};
+const loadOptionalLanguage = (language) => {
+    if (optionalLanguageCache.has(language)) {
+        return optionalLanguageCache.get(language);
+    }
+    const packageName = optionalLanguagePackages[language];
+    if (!packageName) {
+        optionalLanguageCache.set(language, null);
+        return null;
+    }
+    try {
+        const grammar = _require(packageName);
+        optionalLanguageCache.set(language, grammar);
+        return grammar;
+    }
+    catch {
+        optionalLanguageCache.set(language, null);
+        optionalAvailabilityCache.set(language, false);
+        return null;
+    }
+};
+const resolveLanguage = (key, language) => {
+    if (key in requiredLanguageMap) {
+        return requiredLanguageMap[key];
+    }
+    return loadOptionalLanguage(language);
+};
+export const isLanguageAvailable = (language) => language in requiredLanguageMap || isOptionalLanguageInstalled(language);
 export const loadParser = async () => {
     if (parser)
         return parser;
@@ -62,17 +94,20 @@ export const loadLanguage = async (language, filePath) => {
     const key = language === SupportedLanguages.TypeScript && filePath?.endsWith('.tsx')
         ? `${language}:tsx`
         : language;
-    const lang = languageMap[key];
+    const lang = resolveLanguage(key, language);
     if (!lang) {
         throw new Error(`Unsupported language: ${language}`);
     }
     parser.setLanguage(lang);
 };
-const MAX_CHUNK = 4096;
 /**
- * Parse source code using tree-sitter's chunked callback API.
- * Avoids the native binding's single-buffer size limit (< 32768 bytes)
- * that causes "Invalid argument" errors on large files.
+ * Parse source code using tree-sitter's string input path with an adaptive
+ * native buffer size.
+ *
+ * The callback input API receives byte offsets. Returning JavaScript string
+ * slices from those byte offsets is unsafe for UTF-8/multi-byte content and has
+ * caused native tree-sitter crashes in large repositories. Use the stable string
+ * input path instead and raise tree-sitter's internal buffer for large files.
  *
  * @param content - Full source file content as UTF-8 string
  * @param oldTree - Optional previous tree for incremental parsing (must call tree.edit() first)
@@ -81,9 +116,6 @@ const MAX_CHUNK = 4096;
 export const parseContent = (content, oldTree) => {
     if (!parser)
         throw new Error('Parser not initialized — call loadParser() first');
-    return parser.parse((index) => {
-        if (index >= content.length)
-            return null;
-        return content.slice(index, index + MAX_CHUNK);
-    }, oldTree);
+    const bufferSize = getTreeSitterBufferSize(Buffer.byteLength(content, 'utf8'));
+    return parser.parse(content, oldTree ?? null, { bufferSize });
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veewo/gitnexus",
-  "version": "1.5.3",
+  "version": "1.5.4",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",

package/skills/gitnexus-cli.md

@@ -60,35 +60,83 @@ $GN 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)                          |
-| `--extensions <ext>`       | Limit parsing to specific file types (comma-separated, e.g., `--extensions ".cs,.meta"`) |
-| `--csharp-define-csproj <path>` | Load C# `DefineConstants` from a `.csproj` and normalize `#if/#elif/#else/#endif` before parsing |
-| `--scope-prefix <prefix>`  | Limit analysis to a path prefix (e.g., `--scope-prefix Assets/` for Unity)               |
-| `--scope-manifest <file>`  | Read scope rules from a manifest file (e.g., `.gitnexus/sync-manifest.txt`)              |
-| `--sync-manifest-policy <policy>` | Drift policy when explicit CLI values differ from manifest directives: `ask|update|keep|error` |
-| `--skills`                 | Generate repo-specific skill files from detected code communities                         |
+| Flag | Effect |
+|------|--------|
+| `--force` | Force full re-index even if up to date |
+| `--embeddings` | Enable embedding generation (off by default) |
+| `--skills` | Generate repo-specific skill files from detected communities |
 
-**Scope manifest syntax:** Non-`@` lines are path-prefix scope rules (same semantics as before). `@key=value` directives set analyze options: `@extensions=<csv>`, `@repoAlias=<name>`, `@embeddings=<true|false>`. Unknown directives fail fast.
+**Two mutually exclusive paths. Choose one per rebuild.**
 
-**Defaulting + drift guard:** If `.gitnexus/sync-manifest.txt` exists and you do not pass `--scope-manifest`/`--scope-prefix`, analyze auto-uses that file. When explicit CLI values (`--extensions`, `--repo-alias`, `--embeddings`) differ from manifest directives, CLI follows `--sync-manifest-policy` (default `ask`; non-TTY requires explicit policy).
+#### Path A: sync-manifest managed (recommended for Unity / monorepo)
 
-**When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale. In Claude Code, a PostToolUse hook runs `analyze` automatically after `git commit` and `git merge`, preserving embeddings if previously generated.
+If `.gitnexus/sync-manifest.txt` exists, `analyze` **auto-uses** it when you do **not** pass `--scope-prefix` or `--scope-manifest`.
 
-**Unity projects:** Add `--extensions ".cs,.meta"` to ensure Unity asset edges (`UNITY_ASSET_GUID_REF`, `UNITY_COMPONENT_INSTANCE`) are parsed. Add `--scope-prefix Assets/` to limit scope if all code lives under `Assets/`.
+```bash
+# Unity project with an existing manifest — this is the normal rebuild command
+$GN analyze --force
+```
+
+The manifest controls scope rules, extensions, and repo alias. Example:
+
+```
+Assets/
+Packages/
+@extensions=.cs,.meta
+@repoAlias=neonspark-core
+```
+
+- Non-`@` lines = path-prefix scope rules
+- `@extensions=<csv>` = file extension filter
+- `@repoAlias=<name>` = stable repo alias
+- `@embeddings=<true|false>` = embedding toggle
+
+**Drift guard:** If you pass `--extensions` / `--repo-alias` / `--embeddings` while a manifest exists, CLI compares them. Use `--sync-manifest-policy` to control: `ask|update|keep|error` (default `ask`; non-TTY requires explicit policy).
+
+**Do not mix Path A and Path B.** Passing `--scope-prefix` or `--extensions` when a manifest exists triggers the drift guard and may error out in non-TTY environments.
+
+#### Path B: manual CLI flags (first-time or simple projects)
 
-**C# conditional-compilation projects (recommended):**
+Use when no sync-manifest exists:
 
-- Unity: pass `--csharp-define-csproj /path/to/Assembly-CSharp.csproj` (for neonspark, use `/Volumes/Shuttle/projects/neonspark/Assembly-CSharp.csproj`).
-- Non-Unity: discover candidate project files first, then pass the intended one explicitly:
+```bash
+# Unity project, first-time index
+$GN analyze --force --extensions ".cs,.meta" --scope-prefix Assets/ --repo-alias neonspark-core
+
+# Generic project
+$GN analyze --force --extensions ".ts,.tsx" --scope-prefix src/
+```
+
+| Manual flag | Effect |
+|-------------|--------|
+| `--extensions <ext>` | Comma-separated file extensions |
+| `--scope-prefix <prefix>` | Add a path prefix rule (repeatable) |
+| `--scope-manifest <file>` | Read scope rules from a manifest file |
+| `--repo-alias <name>` | Override indexed repository name |
+| `--csharp-define-csproj <path>` | Load C# `DefineConstants` from `.csproj` for `#if` normalization |
+
+**C# preprocessing (Unity):** For projects with heavy conditional compilation, add `--csharp-define-csproj /path/to/Assembly-CSharp.csproj` (neonspark: `/Volumes/Shuttle/projects/neonspark/Assembly-CSharp.csproj`). Without it, C# files are parsed raw and tree-sitter may mishandle `#if` branches.
+
+#### Rebuild recovery — when analyze hangs or crashes
+
+If `analyze --force` hangs (no progress after 5+ minutes) or crashes leaving a corrupted index:
 
 ```bash
-rg --files -g '*.csproj'
-$GN analyze --extensions ".cs" --csharp-define-csproj <picked-project>.csproj
+# 1. Clean the corrupted index (preserves sync-manifest.txt)
+$GN clean --force
+
+# 2. Rebuild
+$GN analyze --force
 ```
 
+**When to clean before rebuild:**
+- Previous run left `.gitnexus/csv/` with no `relations.csv` (crash mid-streaming)
+- `.gitnexus/lbug.wal` exists but `lbug` is tiny (LadybugDB in unrecovered state)
+- Any `analyze` run hangs indefinitely in the "Loading into LadybugDB..." phase
+- After `gitnexus clean`, always run `analyze --force` to rebuild
+
+**When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale.
+
 ### status — Check index freshness
 
 ```bash
@@ -97,13 +145,13 @@ $GN status
 
 Shows whether the current repo has a GitNexus index, when it was last updated, and symbol/relationship counts. Use this to check if re-indexing is needed.
 
-### clean — Delete the index
+### clean — Delete the index (preserves config)
 
 ```bash
-$GN clean
+$GN clean --force
 ```
 
-Deletes the `.gitnexus/` directory and unregisters the repo from the global registry. Use before re-indexing if the index is corrupt or after removing GitNexus from a project.
+Removes the GitNexus index (graph, CSVs, LadybugDB) from `.gitnexus/` while **preserving `sync-manifest.txt`** and other configuration files. Use this to recover from a corrupted index before re-indexing.
 
 | Flag      | Effect                                            |
 | --------- | ------------------------------------------------- |
@@ -189,6 +237,7 @@ $GN unity-ui-trace "Assets/NEON/VeewoUI/Uxml/BarScreen/Patch/PatchItemPreview.ux
 - **"Not inside a git repository"**: Run from a directory inside a git repo
 - **Index is stale after re-analyzing**: Restart Claude Code to reload the MCP server
 - **Embeddings slow**: Omit `--embeddings` (it's off by default) or set `OPENAI_API_KEY` for faster API-based embedding
+- **`analyze --force` hangs or crashes**: Run `$GN clean --force` to remove the corrupted index (sync-manifest is preserved), then `$GN analyze --force` to rebuild. Common corruption signatures: `.gitnexus/csv/` exists but `relations.csv` is missing; `.gitnexus/lbug.wal` exists while `lbug` is only a few KB.
 
 ## Runtime-Chain Closure Guard