@duytransipher/gitnexus 1.4.6-sipher.0

package/LICENSE

@@ -0,0 +1,73 @@
+PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Abhigyan Patwari (https://github.com/abhigyanpatwari/GitNexus)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/README.md

@@ -0,0 +1,261 @@
+# GitNexus
+
+A Sipher-maintained npm distribution of GitNexus.
+
+**Graph-powered code intelligence for AI agents.** Index any codebase into a knowledge graph, then query it via MCP or CLI.
+
+Works with **Cursor**, **Claude Code**, **Windsurf**, **Cline**, **OpenCode**, and any MCP-compatible tool.
+
+[![npm version](https://img.shields.io/npm/v/%40duytransipher%2Fgitnexus.svg)](https://www.npmjs.com/package/@duytransipher/gitnexus)
+[![License: PolyForm Noncommercial](https://img.shields.io/badge/License-PolyForm%20Noncommercial-blue.svg)](https://polyformproject.org/licenses/noncommercial/1.0.0/)
+
+---
+
+## Why?
+
+AI coding tools don't understand your codebase structure. They edit a function without knowing 47 other functions depend on it. GitNexus fixes this by **precomputing every dependency, call chain, and relationship** into a queryable graph.
+
+**Three commands to give your AI agent full codebase awareness.**
+
+## Quick Start
+
+```bash
+# Run once without installing globally
+npx @duytransipher/gitnexus@latest analyze
+```
+
+That's it. This indexes the codebase, installs agent skills, registers Claude Code hooks, and creates `AGENTS.md` / `CLAUDE.md` context files — all in one command.
+
+Install globally if you want the persistent `gitnexus` CLI:
+
+```bash
+npm install -g @duytransipher/gitnexus
+```
+
+To configure MCP for your editor, run `npx @duytransipher/gitnexus@latest setup` once — or set it up manually below. After a global install, the executable name stays `gitnexus`.
+
+`gitnexus setup` auto-detects your editors and writes the correct global MCP config. You only need to run it once.
+
+### Editor Support
+
+| Editor | MCP | Skills | Hooks (auto-augment) | Support |
+|--------|-----|--------|---------------------|---------|
+| **Claude Code** | Yes | Yes | Yes (PreToolUse) | **Full** |
+| **Cursor** | 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 automatically enrich grep/glob/bash calls with knowledge graph context.
+
+### Community Integrations
+
+| Agent | Install | Source |
+|-------|---------|--------|
+| [pi](https://pi.dev) | `pi install npm:pi-gitnexus` | [pi-gitnexus](https://github.com/tintinweb/pi-gitnexus) |
+
+## MCP Setup (manual)
+
+If you prefer to configure manually instead of using `gitnexus setup`:
+
+### Claude Code (full support — MCP + skills + hooks)
+
+```bash
+claude mcp add gitnexus -- npx -y @duytransipher/gitnexus@latest mcp
+```
+
+### Cursor / Windsurf
+
+Add to `~/.cursor/mcp.json` (global — works for all projects):
+
+```json
+{
+  "mcpServers": {
+    "gitnexus": {
+      "command": "npx",
+      "args": ["-y", "@duytransipher/gitnexus@latest", "mcp"]
+    }
+  }
+}
+```
+
+### OpenCode
+
+Add to `~/.config/opencode/config.json`:
+
+```json
+{
+  "mcp": {
+    "gitnexus": {
+      "command": "npx",
+      "args": ["-y", "@duytransipher/gitnexus@latest", "mcp"]
+    }
+  }
+}
+```
+
+## How It Works
+
+GitNexus builds a complete knowledge graph of your codebase through a multi-phase indexing pipeline:
+
+1. **Structure** — Walks the file tree and maps folder/file relationships
+2. **Parsing** — Extracts functions, classes, methods, and interfaces using Tree-sitter ASTs
+3. **Resolution** — Resolves imports and function calls across files with language-aware logic
+4. **Clustering** — Groups related symbols into functional communities
+5. **Processes** — Traces execution flows from entry points through call chains
+6. **Search** — Builds hybrid search indexes for fast retrieval
+
+The result is a **LadybugDB graph database** stored locally in `.gitnexus/` with full-text search and semantic embeddings.
+
+## MCP Tools
+
+Your AI agent gets these tools automatically:
+
+| 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 |
+| `sync_unreal_asset_manifest` | Refresh Unreal Blueprint manifest via the configured Unreal commandlet | Optional |
+| `find_native_blueprint_references` | Confirm direct Blueprint references to a native C++ function | Optional |
+| `expand_blueprint_chain` | Expand upstream/downstream Blueprint graph flow from a confirmed anchor | Optional |
+| `find_blueprints_derived_from_native_class` | List Blueprint assets derived from a native class via the manifest | Optional |
+
+> With one indexed repo, the `repo` param is optional. With multiple, specify which: `query({query: "auth", repo: "my-app"})`.
+
+## MCP Resources
+
+| Resource | Purpose |
+|----------|---------|
+| `gitnexus://repos` | List all indexed repositories (read first) |
+| `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 |
+
+## MCP Prompts
+
+| 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 |
+
+## CLI Commands
+
+```bash
+gitnexus setup                    # Configure MCP for your editors (one-time)
+gitnexus analyze [path]           # Index a repository (or update stale index)
+gitnexus analyze --force          # Force full re-index
+gitnexus analyze --embeddings     # Enable embedding generation (slower, better search)
+gitnexus analyze --verbose        # Log skipped files when parsers are unavailable
+gitnexus mcp                     # Start MCP server (stdio) — serves all indexed repos
+gitnexus serve                   # Start local HTTP server (multi-repo) for web UI
+gitnexus list                    # List all indexed repositories
+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 sipher-patched [path]   # Validate S2 repo shape and Sipher gateway env
+gitnexus unreal-sync             # Refresh Unreal Blueprint asset manifest for the current indexed repo
+gitnexus unreal-find-refs <fn>   # Confirm Blueprint references to a native C++ function
+gitnexus unreal-expand-chain ... # Expand a Blueprint graph chain from a confirmed anchor
+gitnexus unreal-derived-blueprints <class> # List Blueprints derived from a native class
+```
+
+## Unreal Blueprint References
+
+GitNexus can bridge into an Unreal Editor commandlet to answer "which Blueprints call this native C++ function?" with graph-confirmed results.
+
+1. Install the plugin from `../gitnexus-unreal/` into your Unreal project's `Plugins/` folder.
+2. Create `.gitnexus/unreal/config.json` in the indexed repo:
+
+```json
+{
+  "editor_cmd": "C:/Program Files/Epic Games/UE_5.5/Engine/Binaries/Win64/UnrealEditor-Cmd.exe",
+  "project_path": "D:/Projects/sipher_test_project/sipher_test_project.uproject",
+  "commandlet": "GitNexusBlueprintAnalyzer",
+  "timeout_ms": 300000
+}
+```
+
+From this source repo, you can do both with:
+
+```powershell
+pwsh -File .\gitnexus\scripts\setup-unreal-gitnexus.ps1 -ProjectRoot D:\Projects\git_nexus_ue_lyra
+```
+
+The script fails if the plugin or config already exists unless you pass `-Force`.
+
+3. Refresh the manifest with `gitnexus unreal-sync`.
+4. Query references with `gitnexus unreal-find-refs "AMyActor::MyBlueprintCallableFunction"`.
+
+The manifest lives at `.gitnexus/unreal/asset-manifest.json`. GitNexus uses it only as a candidate shortlist; confirmed graph references still come from the Unreal commandlet.
+
+## Multi-Repo Support
+
+GitNexus supports indexing multiple repositories. Each `gitnexus analyze` registers the repo in a global registry (`~/.gitnexus/registry.json`). The MCP server serves all indexed repos automatically.
+
+## Supported Languages
+
+TypeScript, JavaScript, Python, Java, C, C++, C#, Go, Rust, PHP, Kotlin, Swift, Ruby
+
+### Language Feature Matrix
+
+| 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++ | — | — | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ |
+
+**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
+
+## Agent Skills
+
+GitNexus ships with skill files that teach AI agents how to use the tools effectively:
+
+- **Exploring** — Navigate unfamiliar code using the knowledge graph
+- **Debugging** — Trace bugs through call chains
+- **Impact Analysis** — Analyze blast radius before changes
+- **Refactoring** — Plan safe refactors using dependency mapping
+
+Installed automatically by both `gitnexus analyze` (per-repo) and `gitnexus setup` (global).
+
+## Requirements
+
+- Node.js >= 18
+- Git repository (uses git for commit tracking)
+
+## Privacy
+
+- All processing happens locally on your machine
+- No code is sent to any server
+- Index stored in `.gitnexus/` inside your repo (gitignored)
+- Global registry at `~/.gitnexus/` stores only paths and metadata
+
+## Web UI
+
+GitNexus also has a browser-based UI at [gitnexus.vercel.app](https://gitnexus.vercel.app) — 100% client-side, your code never leaves the browser.
+
+**Local Backend Mode:** Run `gitnexus serve` and open the web UI locally — it auto-detects the server and shows all your indexed repos, with full AI chat support. No need to re-upload or re-index. The agent's tools (Cypher queries, search, code navigation) route through the backend HTTP API automatically.
+
+## License
+
+[PolyForm Noncommercial 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0/)
+
+Free for non-commercial use. Contact for commercial licensing.

package/dist/cli/ai-context.d.ts

@@ -0,0 +1,23 @@
+/**
+ * AI Context Generator
+ *
+ * Creates AGENTS.md and CLAUDE.md with full inline GitNexus context.
+ * AGENTS.md is the standard read by Cursor, Windsurf, OpenCode, Cline, etc.
+ * CLAUDE.md is for Claude Code which only reads that file.
+ */
+import { type GeneratedSkillInfo } from './skill-gen.js';
+interface RepoStats {
+    files?: number;
+    nodes?: number;
+    edges?: number;
+    communities?: number;
+    clusters?: number;
+    processes?: number;
+}
+/**
+ * Generate AI context files after indexing
+ */
+export declare function generateAIContextFiles(repoPath: string, _storagePath: string, projectName: string, stats: RepoStats, generatedSkills?: GeneratedSkillInfo[]): Promise<{
+    files: string[];
+}>;
+export {};

package/dist/cli/ai-context.js

@@ -0,0 +1,265 @@
+/**
+ * AI Context Generator
+ *
+ * Creates AGENTS.md and CLAUDE.md with full inline GitNexus context.
+ * AGENTS.md is the standard read by Cursor, Windsurf, OpenCode, Cline, etc.
+ * CLAUDE.md is for Claude Code which only reads that file.
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+// ESM equivalent of __dirname
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const GITNEXUS_START_MARKER = '<!-- gitnexus:start -->';
+const GITNEXUS_END_MARKER = '<!-- gitnexus:end -->';
+/**
+ * Generate the full GitNexus context content.
+ *
+ * Design principles (learned from real agent behavior and industry research):
+ * - Inline critical workflows — skills are skipped 56% of the time (Vercel eval data)
+ * - Use RFC 2119 language (MUST, NEVER, ALWAYS) — models follow imperative rules
+ * - Three-tier boundaries (Always/When/Never) — proven to change model behavior
+ * - Keep under 120 lines — adherence degrades past 150 lines
+ * - Exact tool commands with parameters — vague directives get ignored
+ * - Self-review checklist — forces model to verify its own work
+ */
+function generateGitNexusContent(projectName, stats, generatedSkills) {
+    const generatedRows = (generatedSkills && generatedSkills.length > 0)
+        ? generatedSkills.map(s => `| Work in the ${s.label} area (${s.symbolCount} symbols) | \`.claude/skills/generated/${s.name}/SKILL.md\` |`).join('\n')
+        : '';
+    const skillsTable = `| 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\` |${generatedRows ? '\n' + generatedRows : ''}`;
+    return `${GITNEXUS_START_MARKER}
+# GitNexus — Code Intelligence
+
+This project is indexed by GitNexus as **${projectName}** (${stats.nodes || 0} symbols, ${stats.edges || 0} relationships, ${stats.processes || 0} 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"})\`.
+
+## When Debugging
+
+1. \`gitnexus_query({query: "<error or symptom>"})\` — find execution flows related to the issue
+2. \`gitnexus_context({name: "<suspect function>"})\` — see all callers, callees, and process participation
+3. \`READ gitnexus://repo/${projectName}/process/{processName}\` — trace the full execution flow step by step
+4. For regressions: \`gitnexus_detect_changes({scope: "compare", base_ref: "main"})\` — see what your branch changed
+
+## When Refactoring
+
+- **Renaming**: MUST use \`gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})\` first. Review the preview — graph edits are safe, text_search edits need manual review. Then run with \`dry_run: false\`.
+- **Extracting/Splitting**: MUST run \`gitnexus_context({name: "target"})\` to see all incoming/outgoing refs, then \`gitnexus_impact({target: "target", direction: "upstream"})\` to find all external callers before moving code.
+- After any refactor: run \`gitnexus_detect_changes({scope: "all"})\` to verify only expected files changed.
+
+## 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.
+
+## Tools Quick Reference
+
+| Tool | When to use | Command |
+|------|-------------|---------|
+| \`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 ..."})\` |
+
+## Impact Risk Levels
+
+| Depth | Meaning | Action |
+|-------|---------|--------|
+| d=1 | WILL BREAK — direct callers/importers | MUST update these |
+| d=2 | LIKELY AFFECTED — indirect deps | Should test |
+| d=3 | MAY NEED TESTING — transitive | Test if critical path |
+
+## Resources
+
+| Resource | Use for |
+|----------|---------|
+| \`gitnexus://repo/${projectName}/context\` | Codebase overview, check index freshness |
+| \`gitnexus://repo/${projectName}/clusters\` | All functional areas |
+| \`gitnexus://repo/${projectName}/processes\` | All execution flows |
+| \`gitnexus://repo/${projectName}/process/{name}\` | Step-by-step execution trace |
+
+## Self-Check Before Finishing
+
+Before completing any code modification task, verify:
+1. \`gitnexus_impact\` was run for all modified symbols
+2. No HIGH/CRITICAL risk warnings were ignored
+3. \`gitnexus_detect_changes()\` confirms changes match expected scope
+4. All d=1 (WILL BREAK) dependents were updated
+
+## Keeping the Index Fresh
+
+After committing code changes, the GitNexus index becomes stale. Re-run analyze to update it:
+
+\`\`\`bash
+npx gitnexus analyze
+\`\`\`
+
+If the index previously included embeddings, preserve them by adding \`--embeddings\`:
+
+\`\`\`bash
+npx gitnexus analyze --embeddings
+\`\`\`
+
+To check whether embeddings exist, inspect \`.gitnexus/meta.json\` — the \`stats.embeddings\` field shows the count (0 means no embeddings). **Running analyze without \`--embeddings\` will delete any previously generated embeddings.**
+
+> Claude Code users: A PostToolUse hook handles this automatically after \`git commit\` and \`git merge\`.
+
+## CLI
+
+${skillsTable}
+
+${GITNEXUS_END_MARKER}`;
+}
+/**
+ * Check if a file exists
+ */
+async function fileExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Create or update GitNexus section in a file
+ * - If file doesn't exist: create with GitNexus content
+ * - If file exists without GitNexus section: append
+ * - If file exists with GitNexus section: replace that section
+ */
+async function upsertGitNexusSection(filePath, content) {
+    const exists = await fileExists(filePath);
+    if (!exists) {
+        await fs.writeFile(filePath, content, 'utf-8');
+        return 'created';
+    }
+    const existingContent = await fs.readFile(filePath, 'utf-8');
+    // Check if GitNexus section already exists
+    const startIdx = existingContent.indexOf(GITNEXUS_START_MARKER);
+    const endIdx = existingContent.indexOf(GITNEXUS_END_MARKER);
+    if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+        // Replace existing section
+        const before = existingContent.substring(0, startIdx);
+        const after = existingContent.substring(endIdx + GITNEXUS_END_MARKER.length);
+        const newContent = before + content + after;
+        await fs.writeFile(filePath, newContent.trim() + '\n', 'utf-8');
+        return 'updated';
+    }
+    // Append new section
+    const newContent = existingContent.trim() + '\n\n' + content + '\n';
+    await fs.writeFile(filePath, newContent, 'utf-8');
+    return 'appended';
+}
+/**
+ * Install GitNexus skills to .claude/skills/gitnexus/
+ * Works natively with Claude Code, Cursor, and GitHub Copilot
+ */
+async function installSkills(repoPath) {
+    const skillsDir = path.join(repoPath, '.claude', 'skills', 'gitnexus');
+    const installedSkills = [];
+    // Skill definitions bundled with the package
+    const skills = [
+        {
+            name: 'gitnexus-exploring',
+            description: 'Use when the user asks how code works, wants to understand architecture, trace execution flows, or explore unfamiliar parts of the codebase. Examples: "How does X work?", "What calls this function?", "Show me the auth flow"',
+        },
+        {
+            name: 'gitnexus-debugging',
+            description: 'Use when the user is debugging a bug, tracing an error, or asking why something fails. Examples: "Why is X failing?", "Where does this error come from?", "Trace this bug"',
+        },
+        {
+            name: 'gitnexus-impact-analysis',
+            description: 'Use when the user wants to know what will break if they change something, or needs safety analysis before editing code. Examples: "Is it safe to change X?", "What depends on this?", "What will break?"',
+        },
+        {
+            name: 'gitnexus-refactoring',
+            description: 'Use when the user wants to rename, extract, split, move, or restructure code safely. Examples: "Rename this function", "Extract this into a module", "Refactor this class", "Move this to a separate file"',
+        },
+        {
+            name: 'gitnexus-guide',
+            description: 'Use when the user asks about GitNexus itself — available tools, how to query the knowledge graph, MCP resources, graph schema, or workflow reference. Examples: "What GitNexus tools are available?", "How do I use GitNexus?"',
+        },
+        {
+            name: 'gitnexus-cli',
+            description: 'Use when the user needs to run GitNexus CLI commands like analyze/index a repo, check status, clean the index, generate a wiki, or list indexed repos. Examples: "Index this repo", "Reanalyze the codebase", "Generate a wiki"',
+        },
+    ];
+    for (const skill of skills) {
+        const skillDir = path.join(skillsDir, skill.name);
+        const skillPath = path.join(skillDir, 'SKILL.md');
+        try {
+            // Create skill directory
+            await fs.mkdir(skillDir, { recursive: true });
+            // Try to read from package skills directory
+            const packageSkillPath = path.join(__dirname, '..', '..', 'skills', `${skill.name}.md`);
+            let skillContent;
+            try {
+                skillContent = await fs.readFile(packageSkillPath, 'utf-8');
+            }
+            catch {
+                // Fallback: generate minimal skill content
+                skillContent = `---
+name: ${skill.name}
+description: ${skill.description}
+---
+
+# ${skill.name.charAt(0).toUpperCase() + skill.name.slice(1)}
+
+${skill.description}
+
+Use GitNexus tools to accomplish this task.
+`;
+            }
+            await fs.writeFile(skillPath, skillContent, 'utf-8');
+            installedSkills.push(skill.name);
+        }
+        catch (err) {
+            // Skip on error, don't fail the whole process
+            console.warn(`Warning: Could not install skill ${skill.name}:`, err);
+        }
+    }
+    return installedSkills;
+}
+/**
+ * Generate AI context files after indexing
+ */
+export async function generateAIContextFiles(repoPath, _storagePath, projectName, stats, generatedSkills) {
+    const content = generateGitNexusContent(projectName, stats, generatedSkills);
+    const createdFiles = [];
+    // Create AGENTS.md (standard for Cursor, Windsurf, OpenCode, Cline, etc.)
+    const agentsPath = path.join(repoPath, 'AGENTS.md');
+    const agentsResult = await upsertGitNexusSection(agentsPath, content);
+    createdFiles.push(`AGENTS.md (${agentsResult})`);
+    // Create CLAUDE.md (for Claude Code)
+    const claudePath = path.join(repoPath, 'CLAUDE.md');
+    const claudeResult = await upsertGitNexusSection(claudePath, content);
+    createdFiles.push(`CLAUDE.md (${claudeResult})`);
+    // Install skills to .claude/skills/gitnexus/
+    const installedSkills = await installSkills(repoPath);
+    if (installedSkills.length > 0) {
+        createdFiles.push(`.claude/skills/gitnexus/ (${installedSkills.length} skills)`);
+    }
+    return { files: createdFiles };
+}

package/dist/cli/analyze.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Analyze Command
+ *
+ * Indexes a repository and stores the knowledge graph in .gitnexus/
+ */
+export interface AnalyzeOptions {
+    force?: boolean;
+    embeddings?: boolean;
+    skills?: boolean;
+    verbose?: boolean;
+}
+export declare const analyzeCommand: (inputPath?: string, options?: AnalyzeOptions) => Promise<void>;