chore: import upstream snapshot with attribution

site/src/content/docs/core-concepts/how-it-works.md

@@ -0,0 +1,32 @@
+---
+title: How It Works
+description: The extraction, storage, resolution, and auto-sync pipeline.
+---
+
+CodeGraph turns source code into a queryable graph in four stages.
+
+```
+files → Extraction (tree-sitter) → DB (nodes/edges/files)
+            ↓
+      Resolution (imports, name-matching, framework patterns)
+            ↓
+      Graph queries (callers, callees, impact)
+            ↓
+      Context building (markdown / JSON for AI consumption)
+```
+
+## 1. Extraction
+
+[tree-sitter](https://tree-sitter.github.io/) parses source into ASTs. Language-specific queries extract **nodes** (functions, classes, methods, types…) and **edges** (calls, imports, extends, implements). Heavy parsing runs off the main thread.
+
+## 2. Storage
+
+Everything goes into a local SQLite database (`.codegraph/codegraph.db`) with FTS5 full-text search, using Node's built-in `node:sqlite` in WAL mode from the bundled runtime.
+
+## 3. Resolution
+
+After extraction, references are resolved: function calls → definitions, imports → source files, class inheritance, and framework-specific patterns. Some dynamic-dispatch boundaries (callbacks, observers, React re-render, JSX children) are bridged by synthesizers so flows connect end-to-end. See [Resolution & Frameworks](/codegraph/core-concepts/resolution/).
+
+## 4. Auto-sync
+
+The MCP server watches your project using native OS file events (FSEvents / inotify / ReadDirectoryChangesW). Changes are debounced, filtered to source files, and incrementally synced — the graph stays fresh as you code, with no configuration.

site/src/content/docs/core-concepts/knowledge-graph.md

@@ -0,0 +1,27 @@
+---
+title: The Knowledge Graph
+description: The node and edge kinds the graph is built from.
+---
+
+CodeGraph stores three things: **nodes** (symbols and files), **edges** (relationships between them), and **files**. Every node and edge carries an exact `kind`, drawn from a fixed vocabulary so queries are consistent across languages.
+
+## Node kinds
+
+`file`, `module`, `class`, `struct`, `interface`, `trait`, `protocol`, `function`, `method`, `property`, `field`, `variable`, `constant`, `enum`, `enum_member`, `type_alias`, `namespace`, `parameter`, `import`, `export`, `route`, `component`.
+
+## Edge kinds
+
+`contains`, `calls`, `imports`, `exports`, `extends`, `implements`, `references`, `type_of`, `returns`, `instantiates`, `overrides`, `decorates`.
+
+## Provenance
+
+Most edges come straight from the AST. A few — at dynamic-dispatch boundaries that static parsing can't follow — are **synthesized** and marked with `provenance: 'heuristic'` plus the wiring site that created them. These are surfaced inline in `explore` and the `node` trail, so an agent can see exactly where a connection came from.
+
+## Querying it
+
+- **Search** symbols by name (FTS5).
+- **Callers / callees** walk the call graph one hop at a time.
+- **Impact** computes the transitive radius affected by a change.
+- **Explore** returns source for several related symbols grouped by file, plus the call path among them, in one call.
+
+See the [CLI](/codegraph/reference/cli/) and [MCP Server](/codegraph/reference/mcp-server/) references for how to run these.

site/src/content/docs/core-concepts/resolution.md

@@ -0,0 +1,30 @@
+---
+title: Resolution & Frameworks
+description: How CodeGraph connects references and links routes to handlers.
+---
+
+Extraction produces nodes and raw edges; **resolution** turns names into real connections.
+
+## Reference resolution
+
+After parsing, CodeGraph resolves:
+
+- **Imports** → the source files they point at (including tsconfig path aliases and cargo workspace members).
+- **Calls** → their definitions, by import resolution and name matching.
+- **Inheritance** → `extends` / `implements` between types.
+
+## Framework awareness
+
+CodeGraph recognizes web-framework routing files and emits `route` nodes linked by `references` edges to their handler classes or functions — so querying the callers of a view or controller surfaces the URL pattern that binds it. See [Framework Routes](/codegraph/guides/framework-routes/) for the full list of recognized frameworks.
+
+## Dynamic-dispatch coverage
+
+Static parsing misses computed and indirect calls, so flows can break at dynamic dispatch. CodeGraph bridges several of these boundaries with synthesizers so a flow connects end-to-end:
+
+- Callback / observer registration
+- `EventEmitter` channels
+- React re-render (`setState` → `render`)
+- JSX child (`render` → child component)
+- Interface → implementation dispatch
+
+Every synthesized edge is marked `provenance: 'heuristic'` with the site that wired it, and is shown inline wherever a path crosses it.

site/src/content/docs/getting-started/configuration.md

@@ -0,0 +1,97 @@
+---
+title: Configuration
+description: CodeGraph is zero-config by default, with one optional codegraph.json for custom extensions, excluding tracked directories, indexing gitignored source, and indexing nested git repositories.
+---
+
+Next to none — CodeGraph is **zero-config by default**, with nothing to write or keep in sync to get started. Language support is automatic from the file extension; there's nothing to wire up per language. The one optional file, `codegraph.json`, covers [custom file extensions](#custom-file-extensions), [excluding tracked directories](#excluding-a-tracked-directory), [indexing gitignored source](#indexing-gitignored-source-a-second-vcs), and [indexing nested git repositories](#indexing-nested-git-repositories).
+
+## What it skips out of the box
+
+- **Dependency, build, and cache directories** — `node_modules`, `vendor`, `dist`, `build`, `target`, `.venv`, `Pods`, `.next`, and the like across every [supported stack](/codegraph/reference/languages/) — so the graph is your code, not third-party noise. This holds even with no `.gitignore`.
+- **Anything in your `.gitignore`** — honored in git repos via git, and in non-git projects by reading `.gitignore` directly (root and nested).
+- **Files larger than 1 MB** — generated bundles, minified JS, vendored blobs.
+
+## Excluding or including more
+
+To keep something else out, add it to `.gitignore`. To pull a default-excluded directory back **in** (e.g. you really want a vendored dependency indexed), add a negation — `!vendor/`.
+
+The defaults apply uniformly, so committing a dependency or build directory doesn't force it into the graph — the `.gitignore` negation is the explicit opt-in.
+
+## Excluding a tracked directory
+
+`.gitignore` only affects files git **doesn't already track** — it can't drop a directory you've committed. So a vendored theme, SDK, or asset bundle that's checked into the repo (say a Metronic admin theme under `static/`, with hundreds of `.js` files) can't be excluded that way. For those, list them under `exclude` in `codegraph.json`:
+
+```json
+{
+  "exclude": ["static/", "**/vendor/**"]
+}
+```
+
+Each entry is a gitignore-style pattern, matched against project-root-relative paths, and honored everywhere CodeGraph looks at files — the full index, incremental `sync`, and file-watching. It applies even to tracked files (that's the whole point) and takes precedence over everything else, so it's the right tool for a large committed dependency that bloats the graph but isn't really your code. (This is the opposite of [`includeIgnored`](#indexing-nested-git-repositories), which pulls gitignored directories back *in*.)
+
+Re-index (`codegraph index`) after adding or changing `exclude`.
+
+## Indexing gitignored source (a second VCS)
+
+`.gitignore` keeps files out of the index — which is usually what you want, but not when the gitignored files are real first-party source. The case this exists for: a project tracked by **SVN, Perforce, or another VCS alongside Git**, where some source is committed to that VCS and deliberately listed in `.gitignore` so it never lands in Git. That source is still yours and you want it in the graph, but git never lists it, so CodeGraph never sees it. (`includeIgnored` doesn't help — it only revives *embedded git repositories* inside a gitignored directory, not plain source.)
+
+List those paths under `include` in `codegraph.json` to force them in:
+
+```json
+{
+  "include": ["Tools/", "Local/typescript/"]
+}
+```
+
+Each entry is a gitignore-style pattern, matched against project-root-relative paths (a directory like `"Tools/"`, a recursive `"Tools/**"` glob, or a single file all work). CodeGraph discovers the matching files directly off disk — overriding `.gitignore` — and indexes them everywhere it looks at files: the full index, incremental `sync`, and file-watching.
+
+A few things to know:
+
+- An explicit [`exclude`](#excluding-a-tracked-directory) still wins — listing the same path in both keeps it out.
+- Built-in skips like `node_modules`, `dist`, and `.git` are never re-included, even when an `include` pattern would match inside them.
+- This is the opposite of `exclude` (which keeps tracked files *out*); it's for source git itself never tracks.
+
+Re-index (`codegraph index`) after adding or changing `include`.
+
+## Custom file extensions
+
+If your project uses a non-standard extension for a [supported language](/codegraph/reference/languages/) — say `.dota_lua` for Lua, or `.tpl` for PHP — those files are skipped by default, because the extension isn't one CodeGraph recognizes. Map them with an optional `codegraph.json` at your project root:
+
+```json
+{
+  "extensions": {
+    ".dota_lua": "lua",
+    ".tpl": "php"
+  }
+}
+```
+
+Each value is a supported language id. The mappings merge on top of the built-in defaults and win on conflict, so you can also re-point a built-in (e.g. `".h": "cpp"`). Commit the file to share the mapping with your team.
+
+A typo'd language or a malformed file is warned about and skipped — it never breaks indexing — and a project with no `codegraph.json` behaves exactly as before. Re-index (`codegraph index`) after adding or changing mappings.
+
+## Indexing nested git repositories
+
+CodeGraph respects your `.gitignore`, so a directory you've gitignored stays out of the graph — **including any git repositories nested inside it.** If you keep cloned reference projects, vendored copies, or a folder of unrelated repos in a gitignored directory (a `resource/`, `.repos/`, or `examples/` dir), CodeGraph leaves it untouched: it won't walk in, discover the embedded repos, or index them.
+
+If instead you run a **"super-repo" of independent clones** — a workspace whose own `.gitignore` lists its child repos to keep `git status` quiet, where you genuinely want every child indexed into one graph — opt those directories back in with `includeIgnored`:
+
+```json
+{
+  "includeIgnored": ["packages/", "services/"]
+}
+```
+
+Each entry is a gitignore-style pattern naming a gitignored directory whose nested git repositories should be indexed anyway. CodeGraph descends into the directories you list and indexes each embedded repo by its own `git ls-files`, so every child repo's own `.gitignore` is still honored. Directories you don't list stay excluded.
+
+A few things to know:
+
+- **Untracked** nested repositories (ones you haven't gitignored) are indexed automatically — `includeIgnored` is only for the ones your `.gitignore` excludes.
+- Built-in skips like `node_modules` are never re-included, even inside an opted-in directory.
+- A project without this layout needs no `codegraph.json` at all.
+
+Re-index (`codegraph index`) after adding or changing `includeIgnored`.
+
+## Where data lives
+
+Per-project data lives in a `.codegraph/` directory at your project root, containing the SQLite database (`codegraph.db`). Nothing leaves your machine.

site/src/content/docs/getting-started/installation.md

@@ -0,0 +1,70 @@
+---
+title: Installation
+description: Install CodeGraph and configure your AI coding agents.
+---
+
+## 1. Run the installer
+
+```bash
+npx @colbymchenry/codegraph
+```
+
+The installer will:
+
+- Ask which agent(s) to configure — auto-detecting installed ones from **Claude Code**, **Cursor**, **Codex CLI**, **opencode**, **Hermes Agent**, **Gemini CLI**, **Antigravity IDE**, and **Kiro**.
+- Prompt to install `codegraph` on your `PATH` (so agents can launch the MCP server).
+- Ask whether configs apply to all your projects or just this one.
+- Write each chosen agent's MCP server config, plus a small marker-fenced CodeGraph section in the agent's instructions file (`CLAUDE.md` / `AGENTS.md` / `GEMINI.md`). Cursor and Kiro get the MCP config only. Removed cleanly by `codegraph uninstall`.
+- Set up auto-allow permissions when Claude Code is one of the targets.
+
+The installer **wires up your agents only — it does not index your code.** After it finishes, build each project's graph yourself with `codegraph init` (step 3 below).
+
+## Non-interactive (scripting / CI)
+
+```bash
+codegraph install --yes                              # auto-detect agents, install global
+codegraph install --target=cursor,claude --yes       # explicit target list
+codegraph install --target=auto --location=local     # detected agents, project-local
+codegraph install --print-config codex               # print snippet, no file writes
+```
+
+| Flag | Values | Default |
+|---|---|---|
+| `--target` | `auto`, `all`, `none`, or csv (`claude,cursor,…`) | prompt |
+| `--location` | `global`, `local` | prompt |
+| `--yes` | (boolean) | prompt every step |
+| `--no-permissions` | (boolean) skip Claude auto-allow list | permissions on |
+| `--print-config <id>` | dump snippet for one agent and exit | — |
+
+## 2. Restart your agent
+
+Restart your agent (Claude Code / Cursor / Codex CLI / opencode / Hermes Agent / Gemini CLI / Antigravity IDE / Kiro) for the MCP server to load.
+
+## 3. Initialize projects
+
+```bash
+cd your-project
+codegraph init
+```
+
+`codegraph init` creates the local `.codegraph/` directory and builds the full graph in the same step — one command. A single global `codegraph install` covers every project; you run `codegraph init` once per project.
+
+## Supported platforms
+
+Every release ships a self-contained build (bundled Node runtime — nothing to compile) for all three desktop OSes, on both x64 and arm64:
+
+| Platform | Architectures | Install |
+|---|---|---|
+| Windows | x64, arm64 | PowerShell installer or npm |
+| macOS | x64, arm64 | shell installer or npm |
+| Linux | x64, arm64 | shell installer or npm |
+
+## Uninstall
+
+Changed your mind? One command removes CodeGraph from every agent it configured:
+
+```bash
+codegraph uninstall
+```
+
+This reverses the installer — stripping CodeGraph's MCP server config, instructions, and permissions from each configured agent. Your project indexes (`.codegraph/`) are left untouched; remove those per-project with `codegraph uninit`. Use `--target` to remove from specific agents, or `--yes` to run non-interactively.

site/src/content/docs/getting-started/introduction.md

@@ -0,0 +1,34 @@
+---
+title: Introduction
+description: What CodeGraph is, and why it makes AI coding agents faster and more precise.
+---
+
+CodeGraph is a **local-first code-intelligence tool**. It parses your codebase with [tree-sitter](https://tree-sitter.github.io/), stores every symbol, edge, and file in a local SQLite database, and exposes the result as a queryable **knowledge graph** — over the [Model Context Protocol (MCP)](/codegraph/reference/mcp-server/), a CLI, and a TypeScript library.
+
+It exists to make AI coding agents — Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, and Kiro — **answer structural questions without scanning files**. Instead of fanning out across `grep`, `glob`, and `Read` to reconstruct how code fits together, an agent queries a pre-built index and gets the answer in a handful of calls.
+
+## Why it matters
+
+When an agent explores a codebase, it spends most of its budget on *discovery* — finding the right files before it can read them. CodeGraph removes that step: it hands the agent the exact code it needs in one call, so symbol relationships, call graphs, and structure don't have to be rebuilt file by file.
+
+The universal win is **surgical context and speed** — fewer tool calls, faster answers, on every codebase. Tested across 7 real-world open-source codebases (median of 4 runs per arm), giving an agent CodeGraph meant, regardless of repo size:
+
+- **58% fewer tool calls**
+- **22% faster**
+- **file reads cut to ~zero**
+
+Token and dollar savings are real too, but they're the **scale-dependent bonus** that shows up on large, tangled codebases run at volume — small and noisy on a modest repo, material only once the codebase (and the team) gets big.
+
+## What's in the graph
+
+- **Symbols** — functions, classes, methods, types, routes, components, and more.
+- **Edges** — calls, imports, inheritance, references, and framework-specific relationships.
+- **Files** — structure plus full-text search (FTS5).
+
+Extraction is **deterministic** — derived from the AST, never LLM-summarized.
+
+## 100% local
+
+No data leaves your machine. No API keys, no external services — just a SQLite database in `.codegraph/`.
+
+Ready to try it? Head to the [Quickstart](/codegraph/getting-started/quickstart/).

site/src/content/docs/getting-started/next-steps.md

@@ -0,0 +1,25 @@
+---
+title: Next Steps
+description: Where to go once CodeGraph is installed and indexing.
+---
+
+You've got CodeGraph installed and a graph built. Here's where to go next.
+
+## Understand the model
+
+- [How It Works](/codegraph/core-concepts/how-it-works/) — the extraction → storage → resolution → sync pipeline.
+- [The Knowledge Graph](/codegraph/core-concepts/knowledge-graph/) — the node and edge kinds the graph is built from.
+- [Resolution & Frameworks](/codegraph/core-concepts/resolution/) — how references and framework routes get connected.
+
+## Put it to work
+
+- [Indexing a Project](/codegraph/guides/indexing/) — full index, incremental sync, and the file watcher.
+- [Framework Routes](/codegraph/guides/framework-routes/) — link URL patterns to their handlers.
+- [Affected Tests in CI](/codegraph/guides/affected-tests/) — run only the tests a change touches.
+
+## Reference
+
+- [MCP Server](/codegraph/reference/mcp-server/) — the tools agents call.
+- [CLI](/codegraph/reference/cli/) — every command and flag.
+- [API](/codegraph/reference/api/) — use CodeGraph as a TypeScript library.
+- [Integrations](/codegraph/reference/integrations/) — supported agents and manual setup.

site/src/content/docs/getting-started/quickstart.md

@@ -0,0 +1,39 @@
+---
+title: Get Started
+description: Get up and running with CodeGraph in seconds.
+---
+
+Get up and running with CodeGraph in seconds.
+
+## 1. Install the CLI
+
+No Node.js required — one command grabs the right build for your OS:
+
+```bash
+# macOS / Linux
+curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
+
+# Windows (PowerShell)
+irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex
+```
+
+Already have Node? `npm i -g @colbymchenry/codegraph` works on any version. CodeGraph bundles its own runtime — nothing to compile, no native build, works the same everywhere. The installer puts `codegraph` on your `PATH` but doesn't change your current shell — open a new terminal before the next step.
+
+## 2. Wire up your agent(s)
+
+```bash
+codegraph install
+```
+
+Auto-detects and configures Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, and Kiro — wiring the CodeGraph MCP server into each. This step connects your agents only; it does **not** index any code. (Shortcut: `npx @colbymchenry/codegraph` downloads and runs the installer in one go.)
+
+## 3. Initialize each project
+
+```bash
+cd your-project
+codegraph init
+```
+
+`codegraph init` creates the local `.codegraph/` directory and builds the full graph in the same step — one command, done. Your agent will use CodeGraph tools automatically when a `.codegraph/` directory exists.
+
+Next: build [Your First Graph](/codegraph/getting-started/your-first-graph/), or see the full [Installation](/codegraph/getting-started/installation/) options.

site/src/content/docs/getting-started/your-first-graph.md

@@ -0,0 +1,51 @@
+---
+title: Your First Graph
+description: Build an index and run your first queries against it.
+---
+
+Once CodeGraph is installed, building and exploring a graph takes a few commands.
+
+## Index a project
+
+```bash
+cd your-project
+codegraph init
+```
+
+`codegraph init` creates the `.codegraph/` directory and builds the full graph in the same step — one command, done. From there a native file watcher keeps the index in sync on every change, so you rarely need to rebuild by hand. When you do want to:
+
+```bash
+codegraph index          # full re-index
+codegraph sync           # incremental update of changed files
+```
+
+## Check it worked
+
+```bash
+codegraph status
+```
+
+This reports the node/edge/file counts, the active SQLite backend, and the journal mode — a quick health check that the index is ready.
+
+## Run a query
+
+Reach for `codegraph explore` first — a natural-language question or a bag of symbol names returns the relevant source plus the call paths between those symbols in a single shot (the same output the `codegraph_explore` tool gives your agent):
+
+```bash
+codegraph explore "how does login work"
+```
+
+For narrower, scriptable lookups there are focused commands:
+
+```bash
+codegraph query UserService          # find symbols by name
+codegraph callers handleRequest      # what calls a function
+codegraph callees handleRequest      # what a function calls
+codegraph impact AuthMiddleware      # what a change would affect
+```
+
+These four each accept `--json` for machine-readable output. See the full [CLI reference](/codegraph/reference/cli/).
+
+## Hand it to your agent
+
+With a `.codegraph/` directory present and an agent configured (see [Installation](/codegraph/getting-started/installation/)), your agent uses the [MCP tools](/codegraph/reference/mcp-server/) automatically — no extra step.

site/src/content/docs/guides/affected-tests.md

@@ -0,0 +1,32 @@
+---
+title: Affected Tests in CI
+description: Run only the tests a change actually touches.
+---
+
+`codegraph affected` traces import dependencies transitively to find which test files are affected by a set of changed source files — so CI can run only the relevant tests.
+
+```bash
+codegraph affected src/utils.ts src/api.ts          # pass files as arguments
+git diff --name-only | codegraph affected --stdin    # pipe from git diff
+codegraph affected src/auth.ts --filter "e2e/*"      # custom test-file pattern
+```
+
+## Options
+
+| Option | Description | Default |
+|---|---|---|
+| `--stdin` | Read the file list from stdin | `false` |
+| `-d, --depth <n>` | Max dependency traversal depth | `5` |
+| `-f, --filter <glob>` | Custom glob to identify test files | auto-detect |
+| `-j, --json` | Output as JSON | `false` |
+| `-q, --quiet` | Output file paths only | `false` |
+
+## CI / hook example
+
+```bash
+#!/usr/bin/env bash
+AFFECTED=$(git diff --name-only HEAD | codegraph affected --stdin --quiet)
+if [ -n "$AFFECTED" ]; then
+  npx vitest run $AFFECTED
+fi
+```

site/src/content/docs/guides/framework-routes.md

@@ -0,0 +1,28 @@
+---
+title: Framework Routes
+description: CodeGraph links URL patterns to the handlers that serve them.
+---
+
+CodeGraph detects web-framework routing files and emits `route` nodes linked by `references` edges to their handler classes or functions. Querying the callers of a view or controller then surfaces the URL pattern that binds it.
+
+| Framework | Shapes recognized |
+|---|---|
+| **Django** | `path()`, `re_path()`, `url()`, `include()` in `urls.py` (CBV `.as_view()`, dotted paths) |
+| **Flask** | `@app.route('/path', methods=[...])`, blueprint routes |
+| **FastAPI** | `@app.get(...)`, `@router.post(...)`, all standard methods |
+| **Express** | `app.get(...)`, `router.post(...)` with middleware chains |
+| **NestJS** | `@Controller` + `@Get/@Post/...`, GraphQL `@Resolver` + `@Query/@Mutation`, `@MessagePattern`/`@EventPattern`, `@SubscribeMessage` |
+| **Laravel** | `Route::get()`, `Route::resource()`, `Controller@action`, tuple syntax |
+| **Drupal** | `*.routing.yml` routes (`_controller`, `_form`, entity handlers); `hook_*` implementations in `.module`/`.theme`/`.install`/`.inc` |
+| **Rails** | `get '/x', to: 'users#index'`, hash-rocket `=>` syntax |
+| **Spring** | `@GetMapping`, `@PostMapping`, `@RequestMapping` on methods |
+| **Play** | `GET`/`POST`/… verb routes in `conf/routes` → `Controller.method` actions (Scala + Java) |
+| **Gin / chi / gorilla / mux** | `r.GET(...)`, `router.HandleFunc(...)` |
+| **Axum / actix / Rocket** | `.route("/x", get(handler))` |
+| **ASP.NET** | `[HttpGet("/x")]` attributes on action methods |
+| **Vapor** | `app.get("x", use: handler)` |
+| **React Router** / **SvelteKit** | Route component nodes |
+| **Vue Router** / **Nuxt** | `pages/` file-based routes, `server/api/` endpoints, route middleware |
+| **Astro** | `src/pages/` file-based routes (`.astro` pages + `.ts` endpoints, `[param]`/`[...rest]` syntax) |
+
+Route resolution is automatic — there's nothing to configure. If a framework file is recognized, its routes appear in the graph after the next index or sync.

site/src/content/docs/guides/indexing.md

@@ -0,0 +1,101 @@
+---
+title: Indexing a Project
+description: Full index, incremental sync, and the file watcher.
+---
+
+## Initialize and index
+
+```bash
+cd your-project
+codegraph init      # creates .codegraph/ and builds the full graph — one step
+```
+
+`codegraph init` creates the local `.codegraph/` directory and builds the full graph in the same step — one command, done. There's no separate index step to run afterward, and from here the graph [stays fresh automatically](#stay-fresh-automatically).
+
+## Full vs. incremental
+
+```bash
+codegraph index           # full index of the whole project
+codegraph index --force   # re-index from scratch
+codegraph sync            # incremental — only changed files
+```
+
+`sync` is fast because it only reparses what changed — it's what the file watcher runs for you on every edit (see [Stay fresh automatically](#stay-fresh-automatically)). You rarely need to run it by hand.
+
+## Stay fresh automatically
+
+**You don't need to run `codegraph sync` by hand during an agent session.** When your agent (Claude Code, Cursor, Codex, opencode, Hermes, Gemini, Antigravity, Kiro) launches `codegraph serve --mcp`, three layers cooperate to keep the index in step with your code — and to never give the agent a quiet wrong answer in the small window between an edit and the next sync.
+
+### 1. File watcher with debounced auto-sync (always on)
+
+`serve --mcp` spins up a native file watcher (FSEvents on macOS, inotify on Linux, ReadDirectoryChangesW on Windows) over the project root. Every source-file create / modify / delete is captured. A debounce timer collapses bursts of edits into a single sync.
+
+```
+agent writes src/Widget.ts
+  → watcher fires (event delivery: typically <100ms)
+  → 2000ms debounce
+  → sync runs; Widget.ts's nodes + edges are in the index
+  → next agent query sees it
+```
+
+**Tunable**: `CODEGRAPH_WATCH_DEBOUNCE_MS` overrides the default 2000ms, clamped to `[100ms, 60s]`. Useful when a build step or formatter writes many files in a tight burst — bump it to `5000` or `10000` so the watcher coalesces them into one sync.
+
+### 2. Per-file staleness banner — covers the debounce window
+
+The watcher debounce introduces a small window (typically 2s) where a freshly-edited file is on disk but not yet in the index. CodeGraph closes that window with a per-file staleness banner: if any MCP tool response would reference a file that's currently pending re-index, the response prepends a `⚠️` banner naming the stale file:
+
+```
+⚠️ Some files referenced below were edited since the last index sync —
+their codegraph entries may be stale:
+  - src/Widget.ts (edited 800ms ago, pending sync)
+For accurate content of those specific files, Read them directly.
+The rest of this response is fresh.
+
+## Code Context
+…
+```
+
+Agents read this and follow up with a direct `Read` on the named file — validated end-to-end with Claude Code, where the agent literally says "Reading the file directly for the live content" before opening it. So even during the 2-second debounce window, the agent never gets a silent wrong answer.
+
+Pending files **not** referenced by the response surface as a small footer instead (`(Note: N file(s) elsewhere in this project are pending index sync but were not referenced above: …)`). Either way, the signal is explicit.
+
+### 3. Connect-time catch-up — covers gaps when the MCP server wasn't running
+
+When your editor / agent (re)connects to the MCP server, codegraph runs a fast filesystem-based reconciliation (a `(size, mtime)` stat pre-filter, then a content hash on the rest) before answering the first query. So files changed while no MCP server was running — a `git pull` from the terminal, an edit from another editor, an agent that finished and exited — are caught up automatically on the next session's first tool call.
+
+### Verify what the watcher sees
+
+`codegraph_status` exposes the pending set first-class — useful for an agent asking "is the index caught up?" in one call:
+
+```
+codegraph_status →
+  ## CodeGraph Status
+  …
+  ### Pending sync:
+  - src/Widget.ts (edited 1200ms ago)
+```
+
+If `### Pending sync:` isn't in the response, nothing is in flight.
+
+### When manual `codegraph sync` makes sense
+
+Almost never. The edge cases:
+
+- **The watcher is disabled.** Sandboxes that block local fs watchers, or you've set `CODEGRAPH_NO_DAEMON=1` to opt out of the shared daemon. In those cases `codegraph sync` is the manual fallback.
+- **Pre-flight before a CI run.** If you're scripting against the index outside an agent session, a single `codegraph sync` at the start of the script guarantees the index reflects the current working tree.
+
+Otherwise: just use it. The watcher + banner + connect-sync covers the AI-assisted workflow end-to-end. If you're seeing files genuinely missed after the debounce window has passed, that's a bug — please file an issue with a reproduction.
+
+> See the v0.9.5 release notes for the [staleness banner (#403)](https://github.com/colbymchenry/codegraph/releases/tag/v0.9.5) and the connect-time catch-up (#414); both shipped together.
+
+## Check status
+
+```bash
+codegraph status
+```
+
+Reports node/edge/file counts, the active SQLite backend, and the journal mode. In an agent session, the MCP-side `codegraph_status` additionally surfaces the `### Pending sync:` block described above.
+
+## What gets indexed
+
+Every file whose extension maps to a [supported language](/codegraph/reference/languages/), minus dependency/build directories excluded by default (`node_modules`, `vendor`, `dist`, …), anything your `.gitignore` excludes, and files over 1 MB. See [Configuration](/codegraph/getting-started/configuration/).

site/src/content/docs/reference/api.md

@@ -0,0 +1,69 @@
+---
+title: API
+description: Use CodeGraph as a TypeScript library.
+---
+
+CodeGraph ships a TypeScript API. The public surface is the `CodeGraph` class.
+
+```typescript
+import CodeGraph from '@colbymchenry/codegraph';
+
+const cg = await CodeGraph.init('/path/to/project');
+// Or open an existing index:
+// const cg = await CodeGraph.open('/path/to/project');
+
+await cg.indexAll({
+  onProgress: (p) => console.log(`${p.phase}: ${p.current}/${p.total}`),
+});
+
+const results = cg.searchNodes('UserService');
+const callers = cg.getCallers(results[0].node.id);
+const context = await cg.buildContext('fix login bug', {
+  maxNodes: 20,
+  includeCode: true,
+  format: 'markdown',
+});
+const impact = cg.getImpactRadius(results[0].node.id, 2);
+
+cg.watch();   // auto-sync on file changes
+cg.unwatch(); // stop watching
+cg.close();
+```
+
+## Key methods
+
+| Method | Purpose |
+|---|---|
+| `CodeGraph.init(path)` / `CodeGraph.open(path)` | Create or open a project index |
+| `indexAll(opts)` | Full index, with progress callback |
+| `sync()` | Incremental update |
+| `searchNodes(query)` | Full-text symbol search |
+| `getCallers(id)` / `getCallees(id)` | Walk the call graph |
+| `getImpactRadius(id, depth)` | Transitive impact of a change |
+| `buildContext(task, opts)` | Markdown / JSON context for AI |
+| `watch()` / `unwatch()` | Start / stop the file watcher |
+| `close()` | Close the database connection |
+
+CommonJS works too — `const { CodeGraph } = require('@colbymchenry/codegraph');`.
+
+## Lower-level building blocks
+
+The same entry point exports primitives for callers that drive the graph directly rather than through the `CodeGraph` facade: `DatabaseConnection`, `QueryBuilder`, `getDatabasePath`, `initGrammars` / `loadGrammarsForLanguages`, and `FileLock`.
+
+```typescript
+import {
+  CodeGraph,
+  DatabaseConnection,
+  QueryBuilder,
+  getDatabasePath,
+  initGrammars,
+  loadGrammarsForLanguages,
+  FileLock,
+} from '@colbymchenry/codegraph';
+```
+
+## Embedding requirements
+
+- **Install from npm** (`npm i @colbymchenry/codegraph`) so the matching per-platform package — which carries the compiled library — is fetched alongside the shim.
+- The API runs on **your** runtime, so it needs **Node 22.5+** for the built-in `node:sqlite` module (an Electron main process qualifies when its bundled Node is 22.5+). The CLI and MCP server are unaffected — they ship with a self-contained bundled runtime and need no Node at all.
+- TypeScript types ship with the package. Keep `@types/node` available and `skipLibCheck: true` (the common default).

site/src/content/docs/reference/cli.md

@@ -0,0 +1,51 @@
+---
+title: CLI
+description: Every CodeGraph command and the flags it accepts.
+---
+
+```bash
+codegraph                         # Run interactive installer
+codegraph install                 # Run installer (explicit)
+codegraph uninstall               # Remove CodeGraph from your agents (inverse of install)
+codegraph init [path]             # Initialize a project + build its graph (one step)
+codegraph uninit [path]           # Remove CodeGraph from a project (--force to skip prompt)
+codegraph index [path]            # Full re-index from scratch (--force, --quiet, --verbose)
+codegraph sync [path]             # Incremental update (--quiet)
+codegraph status [path]           # Show statistics (--json)
+codegraph unlock [path]           # Remove a stale lock file that's blocking indexing
+codegraph query <search>          # Search symbols (--kind, --limit, --json)
+codegraph explore <query>         # Relevant symbols' source + call paths in one shot (same output as the codegraph_explore MCP tool)
+codegraph node <symbol|file>      # One symbol's source + callers, or read a file with line numbers (same output as codegraph_node)
+codegraph files [path]            # Show file structure (--format, --filter, --pattern, --max-depth, --json)
+codegraph callers <symbol>        # Find what calls a function/method (--limit, --json)
+codegraph callees <symbol>        # Find what a function/method calls (--limit, --json)
+codegraph impact <symbol>         # Analyze what code is affected by changing a symbol (--depth, --json)
+codegraph affected [files...]     # Find test files affected by changes (see below)
+codegraph daemon                  # Manage background daemons — pick one to stop (alias: daemons)
+codegraph telemetry [on|off]      # Show or change anonymous usage telemetry
+codegraph upgrade [version]       # Update to the latest release (--check, --force)
+codegraph version                 # Print the installed version (also -v, --version)
+codegraph help [command]          # Show help, optionally for one command
+```
+
+The MCP server (`codegraph serve --mcp`) is launched automatically by your agent — you don't run it by hand. See [MCP Server](/codegraph/reference/mcp-server/).
+
+## init, index, and sync
+
+`codegraph init` creates the local `.codegraph/` directory **and** builds the full graph in one step. (The old `-i`/`--index` flag is now a no-op, accepted only so existing scripts don't break.) After that the file watcher keeps the graph current automatically — `index` (a full rebuild from scratch) and `sync` (an incremental update) are only needed when the watcher is disabled or you're scripting against the index outside an agent session.
+
+## Query commands
+
+`query`, `callers`, `callees`, and `impact` all accept `--json` for machine-readable output.
+
+```bash
+codegraph query UserService --kind class --limit 10
+codegraph callers handleRequest --json
+codegraph impact AuthMiddleware --depth 3
+```
+
+`explore` and `node` are the CLI faces of the `codegraph_explore` and `codegraph_node` MCP tools — same output — so subagents and non-MCP harnesses can reach the graph from a shell.
+
+## affected
+
+Traces import dependencies transitively to find which test files are affected by changed source files. See [Affected Tests in CI](/codegraph/guides/affected-tests/) for options and a CI example.

site/src/content/docs/reference/integrations.md

@@ -0,0 +1,59 @@
+---
+title: Integrations
+description: Supported agents, and manual MCP setup.
+---
+
+The interactive installer auto-detects and configures each supported agent — wiring the CodeGraph MCP server into each. For the agents that use an instructions file, it also writes a short marker-fenced CodeGraph section (`CLAUDE.md`, `AGENTS.md`, or `GEMINI.md`) so subagents and non-MCP harnesses learn the `codegraph explore` command; `codegraph uninstall` removes it.
+
+## Supported agents
+
+- **Claude Code**
+- **Cursor**
+- **Codex CLI**
+- **opencode**
+- **Hermes Agent**
+- **Gemini CLI**
+- **Antigravity IDE**
+- **Kiro**
+
+Run `npx @colbymchenry/codegraph` and pick your agent(s); see [Installation](/codegraph/getting-started/installation/) for the non-interactive flags.
+
+## Manual setup
+
+If you'd rather wire it up yourself, install globally:
+
+```bash
+npm install -g @colbymchenry/codegraph
+```
+
+Add the MCP server to `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "codegraph": {
+      "type": "stdio",
+      "command": "codegraph",
+      "args": ["serve", "--mcp"]
+    }
+  }
+}
+```
+
+Optionally auto-allow CodeGraph's tools in `~/.claude/settings.json`:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "mcp__codegraph__*"
+    ]
+  }
+}
+```
+
+One wildcard auto-approves every CodeGraph tool. The server lists a single tool by default — `codegraph_explore` — but if you re-enable others via the `CODEGRAPH_MCP_TOOLS` environment variable, they're already permitted with no prompt.
+
+:::tip
+Cursor launches MCP subprocesses with the wrong working directory. The installer handles this for you by injecting a `--path` argument; if you wire Cursor up by hand, pass the project path explicitly.
+:::

site/src/content/docs/reference/languages.md

@@ -0,0 +1,33 @@
+---
+title: Languages
+description: Every language CodeGraph parses, and the extensions it recognizes.
+---
+
+Language support is automatic from the file extension — there's nothing to configure.
+
+| Language | Extensions | Status |
+|---|---|---|
+| TypeScript | `.ts`, `.tsx` | Full support |
+| JavaScript | `.js`, `.jsx`, `.mjs` | Full support |
+| Python | `.py` | Full support |
+| Go | `.go` | Full support |
+| Rust | `.rs` | Full support |
+| Java | `.java` | Full support |
+| C# | `.cs` | Full support |
+| PHP | `.php` | Full support |
+| Ruby | `.rb` | Full support |
+| C | `.c`, `.h` | Full support |
+| C++ | `.cpp`, `.hpp`, `.cc` | Full support |
+| Objective-C | `.m`, `.mm`, `.h` | Partial support (classes, protocols, methods, `@property`, `#import`, message sends; `.mm` ObjC++ may parse incompletely) |
+| Swift | `.swift` | Full support |
+| Kotlin | `.kt`, `.kts` | Full support |
+| Scala | `.scala`, `.sc` | Full support (classes, traits, methods, type aliases, Scala 3 enums) |
+| Dart | `.dart` | Full support |
+| Svelte | `.svelte` | Full support (script extraction, Svelte 5 runes, SvelteKit routes) |
+| Vue | `.vue` | Full support (script + script-setup, Nuxt page/API/middleware routes) |
+| Astro | `.astro` | Full support (frontmatter + script extraction, template component/call references, `src/pages/` routes) |
+| Liquid | `.liquid` | Full support |
+| Pascal / Delphi | `.pas`, `.dpr`, `.dpk`, `.lpr` | Full support (classes, records, interfaces, enums, DFM/FMX forms) |
+| Lua | `.lua` | Full support (functions, methods, locals, `require` imports, call edges) |
+| R | `.R`, `.r` | Full support (functions, S4/R5/R6 classes with methods, `library`/`require` imports, `source()` file references, call edges) |
+| Luau | `.luau` | Full support (Lua, plus typed signatures, `type` aliases, Roblox `require`) |

site/src/content/docs/reference/mcp-server.md

@@ -0,0 +1,46 @@
+---
+title: MCP Server
+description: The tools CodeGraph exposes to AI agents over MCP.
+---
+
+CodeGraph runs as a [Model Context Protocol](https://modelcontextprotocol.io/) server. Agents configured by the installer launch it automatically — you don't start it by hand:
+
+```bash
+codegraph serve --mcp
+```
+
+When a `.codegraph/` index exists, the agent gets the tool below. In a workspace with **no** index, the server announces itself inactive and lists **no** tools — the agent works normally with its built-in tools, and indexing stays your decision.
+
+## One tool by default: `codegraph_explore`
+
+By default the server exposes a **single tool**, `codegraph_explore`. It's Read-equivalent: give it a natural-language question or a bag of symbol and file names, and it returns the **verbatim, line-numbered source** of the relevant symbols grouped by file — the same shape the `Read` tool gives you — plus the call paths between them (including dynamic-dispatch hops like callbacks, React re-render, and JSX children that grep can't follow) and a blast-radius summary of what depends on them. One call usually answers the whole question.
+
+Exposing a single strong tool is deliberate. Measured agent behavior showed that one well-aimed tool steers agents to a direct answer better than a menu of narrower ones — fewer mis-picks — and agents reach for it both when answering questions and while editing code.
+
+## The other tools
+
+Seven more tools exist and stay fully functional, but are **unlisted by default** — everything they return already arrives inline on a `codegraph_explore` response (its blast-radius section, the relationship map, a symbol's body and its callee list):
+
+| Tool | Purpose |
+|---|---|
+| `codegraph_node` | One symbol's source + caller/callee trail, or a whole file read with line numbers (Read-parity). Returns every overload's body for an ambiguous name. |
+| `codegraph_search` | Find symbols by name across the codebase (locations only) |
+| `codegraph_callers` | Find what calls a function |
+| `codegraph_callees` | Find what a function calls |
+| `codegraph_impact` | Analyze what code is affected by changing a symbol |
+| `codegraph_files` | Get the indexed file structure (faster than filesystem scanning) |
+| `codegraph_status` | Check index health and statistics |
+
+Re-enable any of them with the `CODEGRAPH_MCP_TOOLS` environment variable — a comma-separated allowlist of short names that replaces the default:
+
+```bash
+CODEGRAPH_MCP_TOOLS=explore,node,search,callers
+```
+
+Each also has a CLI equivalent (`codegraph node` / `query` / `callers` / `callees` / `impact` / `files` / `status`) for scripts and non-MCP harnesses.
+
+## How agents should use it
+
+CodeGraph *is* the pre-built search index. For "how does X work?", architecture, a flow ("how does X reach Y"), or where-is-X questions — and while editing code — an agent should answer with `codegraph_explore` and stop, typically with **zero file reads**, rather than re-deriving the answer with `grep` + `Read`. A direct CodeGraph answer is one to a few calls; a grep/read exploration is dozens.
+
+The MCP server delivers this guidance to the main agent automatically, in the MCP `initialize` response. Because subagents and non-MCP harnesses never see that response, the installer also writes a short marker-fenced section into each agent's instructions file pointing at the `codegraph explore` CLI equivalent.

site/src/content/docs/troubleshooting.md

@@ -0,0 +1,31 @@
+---
+title: Troubleshooting
+description: Fixes for the most common CodeGraph issues.
+---
+
+## "CodeGraph not initialized"
+
+Run `codegraph init` in your project directory first.
+
+## Indexing is slow
+
+Check that `node_modules` and other large directories are excluded (they are, if gitignored). Use `--quiet` to reduce output overhead.
+
+## MCP hits `database is locked`
+
+Current builds shouldn't: CodeGraph bundles its own Node runtime and uses Node's built-in `node:sqlite` in WAL mode, where concurrent reads never block on a writer. If you still see it:
+
+- **You're on an old (pre-0.9) install.** Reinstall to get the bundled runtime — `curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh` (macOS/Linux), `irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex` (Windows), or `npm i -g @colbymchenry/codegraph@latest`.
+- **`codegraph status` shows `Journal:` other than `wal`** — WAL couldn't be enabled on this filesystem (common on network shares and WSL2 `/mnt`), so reads can block on writes. Move the project (with its `.codegraph/` folder) onto a local disk.
+
+## MCP server not connecting
+
+Your agent starts the server itself, so you don't launch it by hand. Make sure the project is initialized and indexed (`codegraph status`) and that the path in your MCP config is correct. If it still won't connect, re-run `codegraph install` to rewrite the config.
+
+## Missing symbols
+
+The MCP server auto-syncs on save (wait a couple of seconds). Run `codegraph sync` manually if needed. Check that the file's language is [supported](/codegraph/reference/languages/) and isn't inside a `.gitignore`d or default-excluded directory (e.g. `node_modules`, `dist`).
+
+## Sharing one checkout between Windows and WSL
+
+Don't point both at the same `.codegraph/`: the background-server lock and the SQLite index are tied to the OS that wrote them, and SQLite locking across the WSL2/Windows filesystem boundary is unreliable. Give each side its own index in the same tree by setting `CODEGRAPH_DIR` to a distinct name on one of them — e.g. `CODEGRAPH_DIR=.codegraph-win` on Windows, leaving WSL on the default `.codegraph`. CodeGraph skips any sibling `.codegraph-*` directory when indexing and watching, so the two never trip over each other.